As of December 2021, third-party use of the Local API is no longer supported. Please contact your MODE sales representative to discuss alternative ways to develop custom support for your sensors.

Introduction

MODE Sensor Gateway collects data from various types of sensors and sends the data to MODE Sensor Cloud for data visualization and monitoring.

Sensor Gateway collects real-world data with scalable features, such as remote sensor management, remote software firmware updates (OTA updates), and guaranteed delivery of data.

In some scenarios, you may need to collect data from unsupported sensors by MODE Sensor Gateway. MODE’s Local API allows data collection from unsupported sensors via a simple program using any programing language.

Local API is an HTTP API that operates on MODE Sensor Gateway. This API is very easy to use as it is accessible only from the gateway device.

To collect data from sensors, the following functionality need to be programmed:

In this section, you will learn how to develop a program that uses the CPU temperature of the MODE Sensor Gateway machine as sensor data and send data to the cloud every 5 seconds.

Log in to Sensor Gateway

Connect MODE Sensor Gateway to a keyboard and monitor to log into the Gateway console. You can connect to a monitor via HDMI and with a keyboard via USB. Your login ID and password provided by MODE in advance.

Set up and Sensor Declaration

Let’s write a simple Bash script. In this tutorial, code snippets are reflected in the script file. The complete code is listed at the end of this document.

ONE | Create a Shell Script File

First, create a file called cpu_temp.sh in your home directory and specify /bin/bash as the startup script.

#!/bin/bash

TWO | Declare your sensor module

First, we declare the sensor to the Local API. To make a declaration, we will use the announce endpoint to send the sensor ID and sensor data schema in a JSON format. In this tutorial, we send a POST request to announce endpoint with HTTP by using curl command.

Add the following to the previously created file cpu_temp.sh.

announce_json=$(cat <<JSON
{
  "model": "CUSTOM",
  "id": "MyNUC",
  "sensors": [
    "TEMPERATURE:0"
  ]
}
JSON
)

The model of the sensor MODE Sensor Gateway (Developer Edition) must be CUSTOM. id is the unique identifier of the sensor. Specify a unique id within MODE’s HomeID. If you are not familiar with MODE’s HomeID, you do not need to duplicate it in your sensor. The data to be collected is one temperature data, therefore define one schema with TEMPERATURE type. Send a HTTP POST request with the generated JSON using the cURL command.

curl -X POST -d "$announce_json" \
  --header "Content-Type: application/json" \
  http://localhost:55299/announce

Collect Data from sensors

In Linux on NUC5PYH, which is the hardware used for the MODE Sensor Gateway, the CPU temperature can be obtained from the following file.

/sys/devices/platform/coretemp.0/hwmon/hwmon1/temp2_input

When you open the file, you will see 44000. This indicates that the CPU temperature is 44.000℃. Add the following loop with sleep to store the CPU temperature in a variable every 5 seconds.

while true
do
  sleep 5

  temp=$(cat /sys/devices/platform/coretemp.0/hwmon/hwmon1/temp2_input)
done

Send Data to MODE Sensor Cloud

Now that we are collecting data, let’s send the collected CPU temperature data. Data is defined and sent in JSON format. Send the schema and sensor values in pairs. timestamp field is optional.

Let’s modify the previous loop as follows.

#!/bin/bash

announce_json=$(cat <<JSON
{
  "model": "CUSTOM",
  "id": "MyNUC",
  "sensors": [
    "TEMPERATURE:0"
  ]
}
JSON
)

curl -X POST -d "$announce_json" \
  --header "Content-Type: application/json" \
  http://localhost:55299/announce

while true
do
  sleep 5

  temp=$(cat /sys/devices/platform/coretemp.0/hwmon/hwmon1/temp2_input)
  value=$(echo $temp | awk '{print $1/1000}')

  data_json=$(cat <<JSON
    [
      {
        "sensor": "TEMPERATURE:0",
        "value": $value
      }
    ]
JSON
)

  curl -X POST -d "$data_json" \
    --header "Content-Type: application/json" \
    http://localhost:55299/sensorModules/CUSTOM:MyNUC/sensorData
done

Confirm successful data collection

If everything runs successfully, you should be able to check the data sent on MODE Sensor Cloud Evaluation (SC Eval). Save the shell script and give it execution permissions.

chmod +x cpu_temp.sh

Start executing the script.

./cpu_temp.sh

The /announce endpoint is called and data is sent every 5 seconds. This process allows MODE Sensor Cloud to recognize that a sensor is connected to MODE Sensor Gateway.

To confirm the program is running, on MODE Sensor Cloud Evaluation, scan the sensor module.

ONE | Click on the + Add Modules button on the upper right.

TWO | Click on the Start Scanning button to scan the sensor.

THREE | The sensors available displays. Look for the sensor with the correct id. For our example, the MyNUC sensor declared in Announce API is displayed.

FOUR | Select MyNUC and click on the Add Sensor Modules button.

The sensor 0001:MyNUC displays under the Sensor Gateway and sensor data collection has started.

FIVE | Select the sensor to view the data collected.

If there is no change in the CPU temperature, run the following shell scripts in the background to load the CPU and increase the temperature. Remember to stop the process after the test.

#!/bin/bash
while true
do
  date +%s | sha256sum > /dev/null
done

Changing status based on commands

Let’s set up Sensor Gateway to receive commands from MODE Cloud. In this section, you learn how to stop and restart data transmission based on commands.

Add a command acquisition API that can receive commands in the data collection loop. Add the following bolded text to the loop of the code we have so far.

while true
do
  sleep 5

  curl -s -X GET \
    http://localhost:55299/sensorModules/CUSTOM:MyNUC/command

  temp=$(cat /sys/devices/platform/coretemp.0/hwmon/hwmon1/temp2_input)
  value=$(echo $temp | awk '{print $1/1000}')

  data_json=$(cat <<JSON
    [
      {
        "sensor": "TEMPERATURE:0",
        "value": $value
      }
    ]
JSON
)

  curl -X POST -d "$data_json" \
    --header "Content-Type: application/json" \
    http://localhost:55299/sensorModules/CUSTOM:MyNUC/sensorData
done

When executed, the following JSON outputs several times. This is a command to start the sensor to automatically send data at the time of announcement or connection.

{"action":"startSensors","interval":30,"sensors":["TEMPERATURE:0"]}

Let’s modify the loop so sensor data is not sent when a sensor stop command is received from MODE sensor cloud, and send data when a start command is issued. The parts to be modified are in bolded text below.

sensing=true
while true
do
  sleep 5

  cmd=$(curl -s -X GET -w '%{http_code}' \
    http://localhost:55299/sensorModules/CUSTOM:MyNUC/command |\
  grep 200)

  echo $cmd | grep startSensor && sensing=true
  echo $cmd | grep stopSensor && sensing=false

  ! $sensing && continue

  temp=$(cat /sys/devices/platform/coretemp.0/hwmon/hwmon1/temp2_input)
  value=$(echo $temp | awk '{print $1/1000}')

  data_json=$(cat <<JSON
    [
      {
        "sensor": "TEMPERATURE:0",
        "value": $value
      }
    ]
JSON
)

  curl -X POST -d "$data_json" \
    --header "Content-Type: application/json" \
    http://localhost:55299/sensorModules/CUSTOM:MyNUC/sensorData
done

Data collection configuration settings

Let’s explore some configuration settings. Here, we configure the sensor setting so data collection automatically starts when MODE Sensor Gateway is turned off and restarted.

Add an execution command to start the script written previously by cron. Start the editor using the crontab command and open the configuration file.

crontab -e

Add the following to the bottom line and save:

@reboot nohup /home/ubuntu/cpu_temp.sh > /dev/null &

To confirm this is successful, we want to see data in MODE Sensor Cloud Evaluation after restarting. To restart, press the power button on MODE Sensor Gateway to turn off the power (the blue LED on the power button will go off) and press it again to turn it on. Alternatively, the Gateway can be restarted with the following command.

sudo shutdown -r now

Reference: Code Tutorial Snippet

This following is the complete code snippet from the guide above for your convenience.

#!/bin/bash

announce_json=$(cat <<JSON
{
  "model": "CUSTOM",
  "id": "MyNUC",
  "sensors": [
    "TEMPERATURE:0"
  ]
}
JSON
)

curl -X POST -d "$announce_json" \
  --header "Content-Type: application/json" \
  http://localhost:55299/announce

sensing=true
while true
do
  sleep 5

  cmd=$(curl -s -X GET -w '%{http_code}' \
    http://localhost:55299/sensorModules/CUSTOM:MyNUC/command |\
  grep 200)

  echo $cmd | grep startSensor && sensing=true
  echo $cmd | grep stopSensor && sensing=false

  ! $sensing && continue

  temp=$(cat /sys/devices/platform/coretemp.0/hwmon/hwmon1/temp2_input)
  value=$(echo $temp | awk '{print $1/1000}')

  data_json=$(cat <<JSON
    [
      {
        "sensor": "TEMPERATURE:0",
        "value": $value
      }
    ]
JSON
)

  curl -X POST -d "$data_json" \
    --header "Content-Type: application/json" \
    http://localhost:55299/sensorModules/CUSTOM:MyNUC/sensorData
done