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.
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 excessive amounts 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 and in many cases more reliable than complex systems with many moving parts.

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.
7. Easy to add custom logic/algorithms by adding processes written in any language that connect to Simple IoT via NATS.

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

• an stand-alone application that can be deployed at the edge or 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

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

Build Simple Iot or download the latest release:

• 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

Now, run the example:

• 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 with the above data.

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

Flexible node view

Information is arranged in a flexible node/tree which allows for easy grouping of users, devices, and device attributes.

Each nodes can be expanded to edit/view attributes

Extensive support for modbus devices

Simple IoT can function as either a Modbus TCP/RTU master or client.

Upstream support

Simple IoT is designed such that one instance can be run at the edge and connect to another instance in the cloud. The tree in the edge instance is simply mirrored in the upstream tree. Changes at either place are synchronized in real-time. If one device is offline, the changes are synchronized the next time they are connected. See the below video for a demo of this.

Rules and Notifications

Simple IoT rules can be used to set node values and to trigger notifications.

Configuration

Simple IoT can be configured for basic options such as port numbers, etc.

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 and database format 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
• 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)
• Modbus RTU support in SIOT
• Modbus TCP support in SIOT
• Twilio SMS notifications
• influxdb 2.x support
• synchronization with upstream instances
• email notifications
• COAP API for devices
• store timeseries data in bolt
• esp32 client example
• graph timeseries data
• WiFi management
• Graphs

Support, Community, 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

Other resources:

• Simple IoT YouTube channel

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.

Index

• type Options
• type Siot
  • func NewSiot(o Options) *Siot
  • func (s *Siot) Close() error
  • func (s *Siot) Start() (*natsgo.Conn, error)

Types

type Options

type Options struct {
	StoreType         store.Type
	DataDir           string
	HTTPPort          string
	DebugHTTP         bool
	DisableAuth       bool
	NatsServer        string
	NatsDisableServer bool
	NatsPort          int
	NatsHTTPPort      int
	NatsTLSCert       string
	NatsTLSKey        string
	NatsTLSTimeout    float64
	AuthToken         string
	ParticleAPIKey    string
}

Options used for starting Simple IoT

type Siot

type Siot struct {
	// contains filtered or unexported fields
}

Siot is used to manage the Siot server

func NewSiot

func NewSiot(o Options) *Siot

NewSiot create new siot instance

func (*Siot) Close

func (s *Siot) Close() error

Close the siot server

func (*Siot) Start

func (s *Siot) Start() (*natsgo.Conn, error)

Start Simple IoT data store. The nats connection returned can be used with helper functions in the simpleiot nats package. Note, this function cannot be used directly because we don't checkin the frontend assets for the SIOT web ui. See this example for how you can embed SIOT in your project by adding it as a submodule: https://github.com/simpleiot/custom-application-examples/tree/main/example-1