simpleiot

README

Simple IoT is collection of building blocks to help you build custom IoT systems quickly, but yet provide full flexibility to customize the system. Many features such as device communication, device update, rules, user/group management, user portal, etc. are needed for every IoT system. This project provides a solid foundation of common features so that you can focus on the specific problem you are solving.

Guiding principles

1. Simple concepts are flexible and scale well.
2. There are more problems to solve than people to solve them, thus it makes sense to collaborate on the common technology pieces.
3. There are a lot of IoT applications that are not Google scale (10-1000 device range).
4. There is significant opportunity in the long tail of IoT, which is our focus. This is not an "enterprise" platform.
5. There is value in custom solutions (programming vs drag-n-drop).
6. There is value in running/owning our own platform.
7. A single engineer should be able to build and deploy a custom IoT system.
8. We don't need to spend gobs of time on operations. For smaller deployments, we deploy one binary to a cloud server and we are done with operations. We don't need 20 microservices when one monolith will work just fine.
9. For many applications, a couple hours of down time is not the end of the world. Thus a single server that can be quickly rebuilt as needed is adequate.

Core features/requirements:

1. Runs in cloud and edge instances.
2. Configuration changes can be made at either cloud, UI, or edge and are synchronized efficiently in any direction.
3. Efficient use of network bandwidth for edge systems as most are connected via low cost cellular plans.
4. Rules can run in cloud or edge devices depending on action required (sending notifications or controlling outputs).
5. System supports user authentication and grouping users and devices at multiple levels.
6. User interface updates to changes in real time.

IoT Systems are inherently distributed, so even though we prefer a monolith for a cloud service, we can't get around the fact that we also need to synchronize data with edge devices and user interfaces.

Simple IoT is built on simple data structures arranged in a graph that allows for very flexible configurations.

Because the core of Simple IoT is designed with flexible data structures, adding functionality and supporting new devices is usually as simple as creating your custom edge device code and modifying the UI to display and configure your device features.

Though we are focusing on smaller deployments initially, there is no reason Simple IoT can't scale to large systems by swapping out the internal database for MongoDB/Dgraph/InfluxDB/etc.

See vision and architecture for addition discussion on these points.

This project was developed while building real-world applications and has primarily been driven by these project requirements. This project provides

• a portal application (typically deployed in the cloud)
• packages for implementing an edge application to run on embedded Linux systems.

The Simple IoT project also includes open source gateway firmware and hardware designs.

Detailed documentation

Example 1 (build from source)

This example (only tested on Linux and MacOS) shows how to run the server and send data to it:

• install Go v1.14 (newer versions will likely work) and node/npm (tested with v12 and v14)
• git clone https://github.com/simpleiot/simpleiot.git
• cd simpleiot
• . envsetup.sh (note space is required between . and envsetup.sh. Another way to type this is source envsetup.sh. This command populates your terminal session with all the functions defined in envsetup.sh.)
• siot_setup
• siot_build
• in one terminal, start server: ./siot
• open http://localhost:8080
  • login with user admin@admin.com and password admin
• in another terminal, send some data
  • using HTTP: ./siot -sendPoint "1823:t1:23.5:temp"
  • using NATS: ./siot -sendPointNats "1234:v2:12.5:volt"
  • (the format of the -sendPoint argument is: devId:sensId:value:type)
• in a few seconds, devices should be populated in the web application

SIOT web interface screenshot

Below is a screenshot of the siot web interface. The greyed out device is one that is longer communicating and is considered "offline".

Example 2 (send commands/files to device)

• ./siot
• in another terminal, start edge device example: go run cmd/edge/main.go
• in a 3rd terminal:
  • send command to device: ./siot -sendCmd=setTank:150
  • send file to device: ./siot -sendFile=https://raw.githubusercontent.com/simpleiot/simpleiot/master/README.md

Example 3 (send data with acknowledgments from server)

• ./siot -sendPointNats "1234:v2:12.5:volt" -natsAck

Example 4 (send version information to server)

Hardware version information is a Point that encodes the version information in the Text field of a Point.

• `./siot -sendPointText "1234::1:hwVersion"
• `./siot -sendPointText "1234::2:osVersion"
• `./siot -sendPointText "1234::3:appVersion"

User/Group management

Users can be added to the system. If a user and device are in the same group, then the user can see the device.

User page screenshot

Group page screenshot

In the below example, Joe and Cliff will both have access to the "1234" device because they are all in the "Building A" group.

Configuration

Simple IoT can be configured to connect with a number of external programs/services such as Particle.io, Twilio, and Influxdb.

Additionally, command line option help can be viewed by running siot --help.

Dashboard and Graphing

Although Simple IoT provides a rudimentary dashboard and device listing, it does not provide graphs yet. If you need graphs, using InfluxDb + Grafana may be a good interim solution. Contact us if you need help setting this up -- it is relatively simple.

Features

Note, Simple IoT is under heavy development right now and APIs may change. If you can't find something, it likely got moved to a different package, or renamed -- feel free to ask if you run into problems.

• edit/save device config
• device management
• dashboard showing each device and collected parameters
• REST api for devices
• particle.io support
• boltdb support
• influxdb 1.x support
• user authentication
• user accounts
• group support (assign users and devices to a group so users can only see devices they own).
• Modbus RTU pkg (both client and server)
• Command line Modbus utlity
• rules engine (conditions/consequences)
• sms notifications
• modem/network management
• NATS.io integration (WIP)
• file transfer over NATs (used for sw updates)
• efficient protocols for cellular data connections (NATs/protobuf)
• email notifications
• COAP API for devices
• influxdb 2.x support
• store timeseries data in bolthold
• esp32 client example
• graph timeseries data
• WiFi management
• Graphs

Support, Contributing, etc.

Pull requests are welcome -- see development for more thoughts on architecture, tooling, etc. Issues are labelled with "help wanted" and "good first issue" if you would like to contribute to this project.

For support or to discuss this project, use one of the following options:

• Simple IoT community forum
• #simpleiot Slack channel is available on gophers.slack.com
• open a github issue

License

Apache Version 2.0

Documentation

Overview

Package simpleiot is a collection of Go code that is useful for implementing cloud and edge applications.

See http://simpleiot.org/ for more information.