Module-Update - Support for Mozilla's Things Gateway and ThingURL-Adapter

The most recent update to the first two THGN:STRUCTION modules gave additional options regarding the WebOfThings/Things API output structures, and they're implemented in version 0.4 of the ESP8266 module and version 0.6 of the generic Arduino/WiFi module. These options are turned on by default and will make them compatible with Thing-URL-Adapter of the Mozilla Thing Gateway. This short post will show how to set up a dimmable, colored light using a Wemos D1 Mini and its LED Shield.

dimmable led Dimmable Color LED in action

Prerequisites

For this example, i have used

  • a Wemos D1 Mini (ESP8266-based development board),
  • Wemos WS2812B RGB Shield,
  • the Arduino IDE to compile and flash the code and
  • Adafruit's Neopixel library to control the LED.

However it should compile/run with any ESP8266-board that is able to run the ESP8266 Arduino Framework (e.g. a NodeMCUv2) and the Adafruit Neopixel library with a Neopixel module.

Create HTTP+JSON skeleton code

To create the skeleton code for handling HTTP/JSON requests, open a new tab and head to the THNG:STRUCTION application, or hit "Get started" from the main page.

Start from a pre-defined template, selecting "Dimmable, colored LED light ..." and hit "Create From ..." to use this template.

Create from template

As generator, select the "Arduino/ESP8266-compatible JSON/REST-API, for use with ESP8266WiFi/WebServer".

It automatically creates three properties that are relevant to a dimmable, colored light:

  • color is a string specifying RGB in hexadecimal form, preceeded by a #, e.g. #ff0000 as red, similar to CSS colors.
  • level is the light intensity in percent, where 0 means off and 100 means fully on
  • on is a boolean trigger to turn the light off or on.

Additionally, two actions are created which tell the device to set the LED in "breathing" mode, where it continuously fades out and in.

Click through actions, events, over to the generate tab, generate code and you'll find yourself on the download code once skeleton code has been generated:

download sketch

Compile sketch

Open the Arduino IDE or your favorite editor/embedded development environment. PlatformIO is a great choice, too! Download sketch.ino from the download page, or click on the eye icon to view it in a browser window and copy/paste the code to a fresh editor.

This code is ready to run, and it will offer a REST-API with HTTP+JSON to set and get all device properties. To get an impression of how to test this API you might want to take a look at Testing a WoT REST Device API with Postman.

Ok, next up: Add some application logic. The skeleton contains application-level callback methods for all entrypoints such as getting or setting a property, but they're empty. To fill in the application magic, insert code from this gist at the right positions.

In your editor, mark from the beginning of:

// ------------------------------------------------------------------------------------------------------------------
// Application Handlers
// TODO: Implement application functionality here
// ------------------------------------------------------------------------------------------------------------------

to the end of

// ------------------------------------------------------------------------------------------------------------------
// END Application Handlers
// ------------------------------------------------------------------------------------------------------------------

and replace it with the contents of the gist from above (Find the raw version here which is best for copy+paste).

One more thing to modify are the WiFi credentials at the top of the sketch, around lines 24-25:

/* TODO: place your WiFi credentials here */
const char* WIFI_SSID =         "YOURSSID";
const char* WIFI_PASSWORD =     "YOURPASSWORD";

Compile and upload the sketch to your board, open a serial monitor. It should connect to the WiFi using the credentials you specified, printing out the IP address.

Some sample actions that can be triggered from command line of using Postman are:

  • GET to URI /wot returns the Things API Descriptions
  • PUT to /wot/properties/on with body of { "on": true } turns on the LED
  • PUT to /wot/properties/color with body of { "color": "#ff0000" } changes the color, e.g. to red.
  • POST to /wot/actions with body of { "name": "start_breathing" } makes the LED start to breathe.

Mozilla Things Gateway

Release 0.4 of Mozilla's Things Gateway introduced thing-url-adapter as a preinstalled adapter, which makes it possible to add devices that are capable of speaking the Things API via an URL. One of the next blog posts will demonstrate how to set this up and connect the Dimmable LED to it!