iotsa - Internet of Things server architecture

Build Status:

See More projects using iotsa section, below, for more build status indicators.

This library contains a framework to easily create esp8266-based or esp32-based web servers that can interface to all sorts of sensors and actuators. The servers can be REST-compatible, and COAP-compatible, including seamless integration with the Igor home automation server.

Home page is https://github.com/cwi-dis/iotsa. This software is licensed under the MIT license by the CWI DIS group, http://www.dis.cwi.nl.

Note that the build badges above are for the develop branch, for the iotsa library itself and the examples. Build status for iotsa applications against the develop branch can be found below.

Installation and use for developers

Iotsa can be used with both the Arduino IDE and with the PlatformIO build system (which can be used from within Atom or VSCode or from the command line). The Arduino IDE is easiest to get started with, but PlatformIO is more powerful if you want to target multiple device types, use Git integration, etc.

Arduino IDE

Download the zipfile (via https://github.com/cwi-dis/iotsa) and install into Arduino IDE with Sketch -> Include Library -> Add .ZIP Library... . (If you downloaded the zipfile through github you may have to rename the directory because it may be called something like iotsa___master).

Build the Hello example (File -> Examples -> iotsa -> Hello) and flash it onto an ESP-12 or similar board.

Note: the structure of the iotsa examples may be slightly different than what you are used to for Arduino examples: the Hello.ino file is basically empty, and the code is contained in the mainHello.cpp file, which is in a separate tab in the Arduino IDE.

PlatformIO

The iotsa library is known to the PlatformIO library manager, so simply adding it to your platformio.ini file should do the trick for adding the iotsa framework to your project..

To build an example you can open the iotsa source directory in VSCode or Atom and look at the [env:nodemcuv2-example-skeleton] section. Replace the references to skeleton with the name of the example you want to build.

But: each example in the examples folder also has its own platform.ini file to build it. So you can also open iotsa/examples/Hello in VSCode or Atom and build it, or use the command line:

$ cd iotsa/examples/Hello
$ platformio run --target build
$ platformio run --target upload

Both Arduino IDE and PlatformIO

On reboot, the board will first initialize the SPIFFS flash filesystem (if needed) and then create a WiFi network with a name similar to config-iotsa1234. Connect a device to that network and visit http://192.168.4.1. Configure your device name (at http://192.168.4.1/config) and WiFi name and password (at http://192.168.4.1/wificonfig), and after reboot the iotsa board should connect to your network and be visible as http://yourdevicename.local.

When the device is running normally you can visit http://yourdevicename.local/config and request the device to go into configuration mode, or to do a factory reset. After requesting this you have 5 minutes to power cycle the device to make it go into configuration mode again (see previous paragraph) or do a complete factory reset. When in configuration mode you have five minutes to change the configuration (device name, WiFi name, password, maybe other parameters) before the device reverts to normal operation. The idea behind this sequence (request configuration mode, then power cycle, then change parameters) is that you need both network acccess and physical access before you can do a disruptive operation on the device.

Build time options

A number of features of the iotsa framework can be enabled and disabled selectively at build time. These features are encoded in iotsaBuildOptions.h.

The general naming convention is that a feature WIFI will be triggered by a define IOTSA_WITH_WIFI. If the WIFI feature is enabled by default (which happens to be the case for WIFI, obviously) that can be overridden by defining IOTSA_WITHOUT_WIFI at compile time of the iotsa library.

When using the Arduino IDE you can edit this file to change the options, by commenting out the defines for features you do not need.

When using Platformio you can also use the build_flags in platformio.ini. For example, to enable COAP and disable REST:

	build_flags = -DIOTSA_WITHOUT_REST -DIOTSA_WITH_COAP

The following features are defined:

• DEBUG Enables logging and debugging messages to the serial line. Default on.
• WIFI Enables the WiFi network interface. Default on.
• HTTP Enables the web server infrastructure. Default on.
• HTTPS Enables the secure web server infrastructure. Default off. Exclusive with HTTP.
• WEB Enables the user-oriented web interfaces. Default on. Requires HTTP or HTTPS.
• API Enables the application-oriented interfaces. Default on. Requires REST or COAP.
• REST Enables the http(s) based REST application interfaces. Default on. Requires HTTP or HTTPS.
• COAP Enables the udp-based COAP application interfaces. Default off.
• BLE Enables Bluetooth LE application interface (esp32 only). Default off.

There are a few more that are not very important, please inspect iotsaBuildOptions.h.

HTTPS support

If a iotsa application is built with IOTSA_WITH_HTTPS if will initially use a builtin key and certificate. This is NOT secure, because the key and certificate are contained in the github source repository, and therefore known to the world.

After building and flashing your software for the first time you should create a new, unique, key and certificate. There are three ways to do this, using scripts in the extras directory:

• extras/name-self-signed-cert.sh creates a self-signed certificate. This can be copied into your source code (before building and flashing).
• extras/make-csr-step{1,2,3}.sh these create a key and self-signed or CA-signed certificate that can be uploaded to the iotsa device using iotsaControl.
• extras/make-igor-signed-cert.sh creates a key and certificate signed by your Igor CA and uploads it to your device.

Note that HTTPS support here refers to iotsa as a server only, HTTPS client support (for the iotsaButton and iotsaRequest modules) is completely independent.

Controlling iotsa devices

Command line tool

There is a command line helper program iotsa. It will be documented here at some point. For now, install iotsa with the following commands:

cd extras/python
pip3 install .

Alternatively, for development, do

python3 -m venv .venv
. .venv/bin/activate
cd extras/python
pip install -e .

Then you can get a list of the available commands with iotsa help and a list of the available options with iotsa --help.

OTA programming

If you have enabled over-the-air programming http://yourdevicename.local/config will also allow you to request the device to go into programmable mode. Again, you have 5 minutes to power cycle and then 5 minutes to reprogram:

• For Arduino IDE:

  • In Tools -> Port -> Network Port select your device.

    • Sometimes ota-programmable devices are slow to appear because of mDNS issues. On a Mac, run the following command in a Terminal window to speed up discovery:

      dns-sd -B _services._dns-sd._udp.
      

      or, on Linux,

      avahi-browse _services._dns-sd._udp
      

      or, on either, use the convenience script

      [...]/iotsa/extras/refreshOTA.sh
      

  • Use the normal Upload command to flash your new program.

• For PlatformIO:

  • Visit http://yourdevicename.local and note the IP address.
  • Edit platform.ini and add the upload_port setting with the correct host name or IP address,
  • or upload with the following command line:

  platformio run -t upload --upload-port yourdevicename.local
  

• For PlatformIO, using iotsaControl:

  • Build using platformio run or the plaformio IDE integration commands.
  • iotsaControl --target yourdevicename.local otaWait ota ./.pioenvs/nodemcuv2/firmware.bin
  • Power cycle the device when iotsaControl asks you to do so.

General design philosophy

Unlike most Arduino libraries and frameworks Iotsa does expose some of its C++ interfaces, but for simple applications you do not have to worry about this.

Iotsa has two main types of objects:

• IotsaApplication, of which there is only one, which is the web server and the container for the plugin modules.

• IotsaMod which is a plugin module and of which there can be many. Each plugin module provides a web interface (usually with a HTML form to allow control over it) plus some functionality. The IotsaMod class is subclassed to provide specific functionality.

  One subclass that is always used is the IotsaWifiMod, which provides the functionality to connect to a specific Wifi network (after the user has provided the name and password).

  One that is often used is IotsaSimpleMod which allows you to write two functions to implement your own functionality (your reason for actually using Iotsa).

Do-nothing application

You create a global variable application of type IotsaApplication to hold the b