otto

README

OttO the Sensor Station

Sensor Station gathers data via MQTT from any number of publishers, which are typically battery powered, wireless sensors spread around a certain location. It also managers control inputs and actuators that allow things like buttons and switches to be used to control attached devices.

Overview

MQTT is the key

MQTT Broker

• Run MQTT broker, e.g. mosquitto

• Base topic "ss//data/"

Example: ss/00:95:fb:3f:34:95/data/tempc 25.00

Web Sockets

We sockets or HTTP/2 will be used to send data to and from the IOTe device (otto) in our case.

Subscribe to Topics

• announce/station - announces stations that control or collect

• announce/hub - announces hubs, typ

• data/tempc/ - data can have option /index at the end

• data/humidity

• control/relay/idx - control can have option /index at the end

REST API

• GET /api/config

• PUT /api/config data => { config: id, ... }

• GET /api/data

• GET /api/stations

Station Manager

• Collection of stations
• Stations can age out

Stations

• ID (name, IP and mac address)
• Capabilities
  • sensors
  • relay

Data

Data can be optimized and we expect we will want to optimize different data for all kinds of reasons and we won't preclude that from happening, we'll give applications the flexibility to handle data elements as they see fit (can optimize).

We will take an memory expensive approach, every data point can be handled on it's own. The data structure will be:

struct Data
    Source ID
    Type
    Timestamp
    Value

User Interface

Build

1. Install Go
2. go get ./...
3. cd ss; go build

That should leave the execuable 'sensors' in the 'sensors' directory as so:

./station/sensors/sensors

Deploy

1. Install and run an MQTT broker on the sensors host (e.g. mosquitto).

2. Start the sensors program ensuring the sensor station has connected to a wifi network.

3. Put batteries in sensors and let the network build itself.

Testing

Fake Websocket Data

% ./ss -fake-ws

% ./ss -help

This will open the following URL for the fake websocket data:

http://localhost:8011/ws

Replace localhost with a hostname or IP if needed. Have the websocket connect to the URL and start spitting out fake data formatted like this:

{"year":2020,"month":12,"day":10,"hour":20,"minute":48,"second":8,"action":"setTime"}
{"K":"tempf","V":88}
{"K":"soil","V":0.49}
{"K":"light","V":0.62}
{"K":"humid","V":0.12}

Adding Automated Builds

Automated builds will be using Github events.

Documentation

Overview

The iote package was designed to help build IoT edge software for on premise edge devices managing a large number of IoT Stations.

The package provides

- MQTT messaging amoung IoT stations and control software - HTTP REST Server for data gathering and configuration - Websockets for realtime bidirectional communication with UI - Web server for mondern web based User Interface - Station manager to track a variety of IoT stations

Messaging Based

The primary communication model for IoTe is a messaging system based on MQTT. These messages can be broke into the following categories

- Meta Data that help describe the "network" infrastructure - Sensor Data that produces data gathered by sensors - Control Data that represents actions to be performed by stations

The topic format used by MQTT is flexible but generally follows the following formats:

## ss/m/<source>/<type> -> { station-informaiton }

Where ss/m == sensor station, <source> is the station Id or source of the message and type represents the specific type of information.

### Meta Data (Station Information)

For example when a station comes alive it can provide some information about itself using the topic:

```ss/m/be:ef:ca:fe:02/station```

The station will announce itself along with some meta information and it's capabilities. The body of the message might look something like this:

```json

{
	"id": "be:ef:ca:fe:02",
	"ip": "10.11.24.24",
    "sensors": [
		"tempc",
		"humidity",
		"light"
	],
	"relays": [
		"heater",
		"light"
	],
}

```

### Sensor Data

Sensor data takes on the form:

```ss/d/<source>/<sensor>/<index>```

Where the source is the Station ID publishing the respective data. The sensor is the type of data being produced (temp, humidity, lidar, GPS).

The index is optional in situations where they may be more than one similar device or sensor, for example a couple of rotation counters on wheels.

The value published by the sensors is typically going to be floating point, however these values may also be integer or string values, including nema-0183.

### Control Data

```ss/c/<source>/<device>/<index>```

This is essentially the same as the sensor except that control commands are used to have a particular device change, for example turning a relay on or off.

Index

• Variables
• func Cleanup()
• func OttO()
• type Configuration
  • func GetConfig() *Configuration
  • func (c *Configuration) ReadFile(fname string) error
  • func (c *Configuration) SaveFile(fname string) error
  • func (c Configuration) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Rando
  • func NewRando() (r *Rando)
  • func (p Rando) Float64() float64
  • func (p Rando) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (p Rando) String() interface{}
• type Stats
  • func GetStats() *Stats

Variables

var (
	Done        chan bool
	StationName string
	Version     string
)

global variables and structures

Functions

func Cleanup

func Cleanup()

func OttO

func OttO()

OttO is a convinience function starting the MQTT and HTTP servers, the station manager and other stuff.

Types

type Configuration

type Configuration struct {
	Addr   string
	Broker string
	Appdir string

	Debug       bool
	DebugMQTT   bool
	FakeWS      bool
	Filename    string
	Interactive bool
	Mock        bool
	MaxData     int // maximum data values to save
	Plugin      string

	GPIO    bool
	Verbose bool
}

Configuration holds all variables that can be changed to alter the way the program works.

func GetConfig

func GetConfig() *Configuration

func (*Configuration) ReadFile

func (c *Configuration) ReadFile(fname string) error

Load the file from the file corresponding to the fname parameter

func (*Configuration) SaveFile

func (c *Configuration) SaveFile(fname string) error

Save write the configuration to a file in JSON format

func (Configuration) ServeHTTP

func (c Configuration) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP provides a REST interface to the config structure

type Rando

type Rando struct {
	F float64
}

PeriodicRandomData will collected a new random piece of data every period and transmit it to the given mqtt channel

func NewRando

func NewRando() (r *Rando)

func (Rando) Float64

func (p Rando) Float64() float64

func (Rando) ServeHTTP

func (p Rando) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (Rando) String

func (p Rando) String() interface{}

type Stats

type Stats struct {
	Goroutines int
	CPUs       int
	runtime.MemStats
	GoVersion string
}

func GetStats

func GetStats() *Stats