Water Sensors using MySensors Framework with oneM2M Platform

Overview

The aim of this project is to demonstrate the usage of the oneM2M IOT platform reference implementation in conjunction with the MySensors radio network meshing framework.

There are 4 separate components for this project.

• An Arduino Uno edge node device

• An ESP8266 Node MCU gateway device

• A reference implementation of the oneM2M specification (CSE)

• A monitor application which allows us to interrogate CSE data

The project will not attempt to describe the inner workings of either the oneM2M reference implementation nor the MySensors framework, rather we will detail how the two can be used to upload sensor data as managed by the MySensors mesh network into the oneM2M IOT platform. This project will not include extracting data back out of the oneM2M platform for visualization at this time. We may update the project in the future to add that functionality,

NOTE: This project is written from the Linux point of view. Please make adjustments as necessary if you are running on Windows or Mac.

MySensors Introduction

To quote the opening introduction on the MySensors home page at https://www.mysensors.org/ "MySensors is an open source hardware and software community focusing on do-it-yourself home automation and Internet of Things."

The idea behind MySensors is that one can implement multiple IOT edge nodes which in turn communicate via one of several low power radio technologies with a local central gateway implementation. That gateway implementation then will funnel the edge node supplied data on to a cloud IOT or home automation platform. The cloud platform can also send commands/data back down to the individual edge nodes via the gateway implementation.

The following image depicts the edge node sensors the the "S", the gateway with the "GW" and also intermediate repeater nodes withe the "R".

This project will demonstrate use of a single edge node (S) implemented with an Arduino Uno as well as a gateway (GW) implemented with an ESP8266 Node MCU. The gateway will transmit the edge node data on to the oneM2M platform via it's HTTP restful API.

At present this is a one way communication, edge node to gateway to cloud. The project can be easily expanded to accommodate return data/command transmission from the oneM2M cloud server back to the edge nodes.

For more details about the MySensors network checkout the documentation at https://www.mysensors.org/about/network .

oneM2M Introduction

oneM2M is a proposed standard IOT communications protocol that is intended to help bridge together the many different sensor protocols that are emerging. This project will not get into the details of oneM2M but we will leverage off of a reference implementation described in a n existing Hackster.io project titled "oneM2M Demo. The project can be found at https://www.hackster.io/onem2m/onem2m-demo-57022e . The demo details the steps required to install and execute a set of three applications. The first is the oneM2M platform server, the CSE, the second is the oneM2M data visualization application implemented via onem2m-monitor.js and the third is a sample edge node application running on an Arduino like Node MCU development board.

This project will utilize the first two applications, the oneM2M platform and the oneM2M-monitor as they are found in the oneM2M Demo project without any changes. The edge node application will however be entirely different. It will be replaced by two Arduino style boards both running the MySensors framework. The first being the edge node itself, which is an Arduino Uno, the second being an ESP8266 NODE MCU board which is the local gateway that also acts as the communications bridge between the edge node and the oneM2M cloud platform.

oneM2M platform setup

For details about setting up the oneM2M reference platform as well as the oneM2M-monitor please refer to the Hackster project titled "oneM2M Demo" at https://www.hackster.io/onem2m/onem2m-demo-57022e .

Refer to sections 1-4 of that document for the getting starting and setup/running details for the CSE platform. Section 5 dealing with the Arduino edge node application can be ignored as we will replace that with steps below. Continue with section 6 to start up the oneM2M monitor application.

Below you will find a sample of debug output to the console for a successful "CSE platform" startup.

Below you will find a sample of debug output to the console for a successful startup of the "monitor" application.

Once these two oneM2M pieces of this puzzle have been installed/started proceed with the setup of this projects IOT edge and gateway nodes.

Edge Node and Gateway Requirements

As mentioned earlier the edge portion of this project is implemented using two Arduino type development boards, and Arduino Uno will be the sensor edge node (S) and an ESP8266 Node MCU will be the gateway node(GW). These two devices will communicate using the MySensors.org radio framework and will use the RF24L01 Nordic low power 2.4Ghz radios. Circuit connection diagrams are included in the sections below.

The Arduino Uno implementation of the edge node is developed using the Arduino IDE, we used version 1.8.1. The ESP8266 Node MCU implementation of the gateway uses the Eclipse IDE with the Arduino CDT plugin. Both implementations will share a similar MySensors library code base. The Arduino sketch can use the unaltered MySensors V 2.2.0 library, while the ESP8266 Node MCU project's version of the MySensors library must have changes applied to the stock version extracted from GIT hub. Refer to the "MySensors Code Changes" section above for details.

Download the sample code

The sample code used in this project can be downloaded from github at https://github.com/leroyle/oneM2MWaterSensor . For simplicity we will use separate copies of the downloaded MySensors library for each of the implementations.

The github sample contains a directory structure intended to keep both applications within the same top level directory.

• oneM2MWaterSensor/Arduino_sketch intended to contain the edge node code and libraries

• oneM2MWaterSensor/Eclipse intended to contain the gateway Eclipse gateway project code

• oneM2MWaterSensor/MySensors contains only the update files for the MySensors V2.2.0 framework.

Each sub-directory has a README file that contains important steps that must be performed for this project to work properly. The sections below will refer to those README's when appropriate.

Download the MySensors Framework

This project utilizes version 2.2.0 of the MySensors framework. The framework document ion is extensive and can be found at https://www.mysensors.org . The downloadable code for the framework is available via github at https://github.com/mysensors/MySensors/tree/master . Download the code into this projects code base within the oneM2mWaterSensor/Arduino_sketch/libraries subdirectory. When complete you should now have a MySensors sub-directory under the Arduino_sketch/libraries directory.

MySensors library Code Changes

The MySensors framework does not currently include any support for HTTP restful type interfacing. However, this can be added fairly simply if we require that the user written application within the gateway implementation handle the nitty gritty details of the HTTP protocol. To that end we have slightly modified the stock MySensors code base as follows.

• Implement a new transport level interface file ./core/MyGatewayTransportHTTPClient.cpp. This file implements the few basic communications API as required by the MySensors framework. These API's are depending on the user written application to provide user callbacks that implement the required functionality. These callbacks have been implemented within the sample gateway application code that we will describe shortly.

• Declare the five new HTTP interfaces within MyCoreSensors.h

• Modify the libraries top level include file MySensors.h in order to declare the new HTTPClient user callback functions.

• The new HTTP code is enabled if the user application specifies "#define MY_GATEWAY_ESP8266_HTTP_CLIENT" prior to including the top level MySensors.h include file. This can be seen in the gateway user application.

To pull all of this together,

• download the MySensors V2.2.0 code,

• copy this projects supplied MySensors.h file over the top of the libraries existing file in the top level directory,

• copy this projects supplied MyGatewayTransportHTTPClient.cpp and MyCodeSensors.h files into the libraries core/ sub-directory.

Please ensure the downloaded MySensors code versions is 2.2.0. If it is a later version the changes are minor so you should not have much trouble merging the changes into a later code base. The changes are delineated by a #define of "MY_GATEWAY_ESP8266_HTTP_CLIENT".

At this time take a look at the README file that can be found in this projects downloaded code base within the oneM2mWaterSensor/MySensors_Changes sub-directory/ The README details the steps to down load the library as well as make the necessary code changes to allow HTTP support.

Arduino Uno Node Setup

The edge node implementation is the beginnings of a water sensor monitor node. It is currently being designed to accommodate 2 water presence sensors. This code is implemented via the standard version 1.8.1 Arduino IDE. Earlier versions should work as well.

The only requirement for this implementation is that the MySensors framework library as well as any dependencies must be downloaded. Again the MySensors framework must be at version 2.2.0. It can, but is not required to contain the above mentioned HTTP support code changes.

As mentioned in the MySensors section above be sure to visit the README file in this projects source directory at .oneM2MWaterSensor/MySensors_Changes/README. The document details how to download and modify the MySensors library for our purposes. When that is completed, follow the Arduino related document at .oneM2MWaterSenro/Arduino_sketch/README

Implementing the Edge Node Application

The source sketch for the edge node application can be found in this projects github downloaded code in the oneM2MWaterSensor/Arduino_sketch sub-directory.

The sketch is designed to send updates to the gateway if the sensor status changes. The gateway then automatically forwards those on to the oneM2M cloud server. Once the sensor signals a water alarm the edge node will continue to transmit alarm status until water is no longer sensed. It is up to the cloud application to not forward extra, multiple alarm messages on to the end user.

If the water sensor is attached, the edge node will transmit 4 different status codes to the gateway. The codes are defined by the alarmStatus_t enum within WaterSensor.h

• 0: FirstStart, used to inform the gateway this sensor is just coming online

• 1: NoChange, used internally to signify the sensor has not changed status from the last time (except for SetAlarm status). If the alarm in the the clear state, no water sensed, there is no need to keep transmitting that status to the gateway

• 2: ClearAlarm, used to indicate we had an alarm but the water is no longer detected.

• 3: SetAlarm, water has been detected. It was a design choice to send this alarm message each time the sensors are interrogated and leave it up to the user application to decide how often the end user should be notified.

If the sensor is left disconnected an alarm is assumed, thus alarm messages are continuously sent to the gateway. This is an acceptable condition for our exercise. Thus you do not "need" to actually attach a water sensor in order to follow the oneM2M platform update.

The sketch is called "WaterSensor". Load the sketch into the Arduino IDE and verify it will compile correctly.

Connecting the Radio to the Arduino Uno

Below is the connection diagram used during the construction of this project.

Refer to the following link for details on connecting the NRF24L01 radio to the Arduino board. Note the different connection points depending on your board type.

NOTE: The NRF24l01 radio is a 3.3 volt device. Connecting VCC to +5 volts will damage the radio.

Next we see a close up view of the NRF24L01 radio.

More connection details. For Arduino Uno, use the pin numbers listed under the Pro Mini/Nano column.

https://www.mysensors.org/build/connect_radio#nrf24l01+-&-arduino

Upload the Edge Node Application

Now that the current project has been built and the radio has been connected, plug in the Arduino and upload the edge node implementation. When the upload completes the application should restart automatically, if not press the reset button on the board. Below is an example output of a successful startup when the debug #define is enabled within the sample application.

The items of interest are:

• TMS:INIT:TSP OK

• TSF:SID:OK, ID=200

• TSF:MSG:SEND

• TSM:FPAR OK

• TSM:ID:OK

• TSM:UPL:OK

ESP8266 Node MCU Setup

The gateway implementation uses an ESP8266 Node MCU demonstration board.

The code for the project is implemented using the Neon version of the Eclipse IDE along with the Arduino CDT add on. There is another Hackster.io project that goes into great detail about how to implement Arduino code on the Node MCU using the Eclipse IDE.

Please visit project "Using Eclipse Arduino plug-in with ESP8266 NodeMCU board" found at https://www.hackster.io/dallas-onem2m/using-eclipse-arduino-plug-in-with-esp8266-nodemcu-board-cb77ef for the full details.

It would be best to work through that entire document, including the creating/installing the sample project before continuing here as that will ensure the environment is setup correctly before adding more complexity into the mix.

You will be revisiting the "Using Eclipse Arduino...." project again when setting up the Eclipse environment below.

Implementing the Gateway Application

We will continue from here on the assumption you have run through the above "Using Eclipse Arduino...." project and that you have successfully created and executed a sample application, that the ESP8266 Node MCU is attached to your development computer and that you have successfully viewed the console debug output.

Prior to continuing we need to make the MySensors library and its dependencies available to the Eclipse IDE environment. There is a README document in this projects code's oneM2MWaterSensor/Eclipse sub-directory. That README details how to setup/copy the MySensors library for Eclipse use. Complete the README's instructions before continuing.

Once the README steps are completed and Eclipse has been restarted perform the following to verify the proper MySensors library is found,

• Within Eclipse select "Help->Arduino Downloads Manager". Within the downloads dialog, select the Libraries tab. Verify the MySensors library version 2.2.0 is displayed in the list of installed libraries. If not then revisit the REAME content. Click the Done button to dismiss the dialog

The GitHub code for "this" project contains the gateway project code that can be imported into Eclipse.

• Within Eclipse, select File->Import, then "Existing Projects into Workspace" then click "Next".

• Navigate to the root directory where the github code for "this" project (oneM2MWaterSensor) was downloaded, then into the Eclipse sub-directory and click "OK". When you are returned back to the Import dialog, check the "Copy projects into workspace" option, then click "Finish".

• You should see the project WSGateway imported into your workspace.

• Back at the Project Explorer view, right click on the imported project, then select "Properties". At the Properties view, select "Libraries".

• Within the "Libraries" view, click on the "Communications" arrow.

• This should expand the item and show the libraries available for use, check the "MySensors" check box.

• Expand the "Platforms Libraries" and then the "esp8266" item

• scroll down and select each of the "EEPROM", "ESP8266WiFi", "SPI" libraries.

• Click "OK"

• You should now be able to build the project by clicking on the "Hammer" button.

• Verify the project builds OK before continuing.

Connecting the Radio to the ESP8266 Node MCU

Below is the connection diagram used during the construction of this project.

Close up view of the NRF24L01 radio

Refer to the following link for details on connecting the NRF24L01 radio to the ESP8266 Node MCU board.

Note: The NRF24l01 radio is a 3.3 volt device. Connecting VCC to +5 volts will damage the radio.

https://www.mysensors.org/build/connect_radio#nrf24l01+-&-esp8266

Upload the gateway application

Now that the gateway Eclipse project has been built and the radio has been connected it can be uploaded to the ESP8266 Node MCU board.

Refer to again to the "Using Eclipse Arduino plug-in with ESP8266 NodeMCU board" found at https://www.hackster.io/dallas-onem2m/using-eclipse-arduino-plug-in-with-esp8266-nodemcu-board-cb77ef .

Go to the section labeled "Upload the oneM2M project code to NodeMCU board."

When the upload completes the application should restart automatically, if not press the reset button on the board.

Gateway Application Execution on the NodeMCU board

When the upload completes the gateway will automatically start to execute the application. To view the debug statement output messages, within the “Console” view click on the drop down arrow just to the right of the “Display Selected Console” button, select the item labeled “ESP8266 Connection” (assuming that is what you called the connection when you created it above).

The debug messages dumped to the console should be much like we see below if the MySensors framework is successfully initialized.

The items of interest are:

• TSM:INIT:TSP:OK

• TSM:READY:ID=0,PAR=0,DIS=0

• MCO:REG:NOT NEEDED

• HTTP_userTransportinit(): connect to wifi

• TransportInit: success

• GWT:HTTP:TPC:CONNECTING

• RegisterOneM2M(): status of http server: 1

• SendOneM2M() Http response: HTTP/1.1 201 Created

oneM2M reference platform startup/restart implications

With the current oneM2M platform implementation, the sensor data store within the platform is re-initialized when the platform is started. There is no data persistence between server restarts by default. Thus when the CSE platform is restarted all previous sensor container and data are lost.

With this sample implementation it is the gateway node's responsibility to create the oneM2M containers via HTTP calls once and only once during the time the gateway is running through the MySensor framework initialization.

Thus if the oneM2M platform implementation is started up "after" the gateway has initialized the MySensors framework, or if oneM2M is restarted when the gateway is already running you will get "resource not found" Http response codes returned from oneM2M. The data store has been re-initialized, the containers no longer exist.

If this occurs merely restarting the ESP8266 Node MCU gateway by pressing its reset button should then allow the containers to be created and subsequent data pushes to the oneM2M server should succeed.

Summary

During this rather involved project we have shown via secondary projects how to:

• Implement a simple sample IOT edge node to oneM2M IOT platform system

• We have then introduced the MySensors radio mesh framework using the Nordic 2.4GHz radios

• Added HTTP support to the MySensors library

• Implemented a new sample 2 node MySensors network consisting of an Arduino Uno edge node communicating via 2.4Ghz to its gateway implemented on an ESP8266 Node MCU.

• Pushed the MySensors data up to the oneM2M IOT platform server via the newly implemented HTTP support.

Hopefully the reader has gained some insight into how this all fits together. There is still much to be done with this project to make it more robust but it is a good start. We hope you enjoy...

Code repository: https://github.com/leroyle/oneM2MWaterSensor

Circuit pictures repository: https://github.com/leroyle/oneM2MWaterSensor/tree/master/Circuits