JsonServer

This application was added in REL-1.1.1.0.

Introduction

JsonServer is a command-line (non graphical) tool that turns the SmartMesh IP Manager serial API into an JSON-based HTTP API.

It connects to one or more embedded SmartMesh IP Managers.

Description

The JsonServer application runs on the computer connected to your SmartMesh IP Manager. It offers an HTTP interface using JSON serialization to the Manager API and has special functions for interacting with the built-in sensors on motes in the network using OAP.

Setup

We assume the following setup:

  • The manager runs the default SmartMesh IP manager firmware, and is switched on.
  • The motes run the default SmartMesh IP mote firmware, in master mode, and have joined the network of the manager.
  • The manager is connected to the server computer. This computer will run the JsonServer application.
  • The client is a remote computer which wants to interact with the SmartMesh IP network

server and client computers are logical roles. During this tutorial, both will run on the same computer.

Start the JSON Server

On the server, start the JsonServer application:

  • by double-clicking on the Windows executable at /win/JsonServer.exe
  • by double-clicking on its source files at /src/app/JsonServer/JsonServer.py (may require additional steps on non-windows OSes)

The JsonServer application starts:

JsonServer - SmartMesh SDK 1.1.0.2 - (c) Dust Networks

The JsonServer application listens on TCP port 8080 for HTTP commands. The client needs to issue commands using a JSON format over HTTP to the server. For simple status queries, using a browser to make HTTP requests is sufficient. To issue commands containing data, an HTTP client or browser extension must be used. 

Postman

Throughout the tutorial presented on this page, you will use Postman - an HTTP API client that runs on Windows, macOS, and Linux - to issue JSON requests to the JsonServer.

We assume you are reasonably familiar with Postman.

In the source code, we provide:

  • postman_collection.json: a Postman collection with example calls for the complete API
  • postman_environment.json: a Postman environment which defines the following variables

    variabledescriptionexample
    hosthostname or IP address of the server running the JsonServer app127.0.0.1
    portTCP port that the JsonServer app is listening on, defaults to 80808080
    serialportserial port the SmartMesh IP manager is connected to on the serverCOM27
    moteMAC address of a SmartMesh IP mote running the default firmware in master mode00-17-1d-00-00-38-06-45

Make sure you upload both the collection and environment files in Postman, and change the environment variables to match your setup.

Retrieve the state of the JsonServer

Issue the "02 stats/GET status" request to retrieve the current status of the JsonServer. The response contains:

{
  "managers": {},
  "current time": "11/09/2016 14:46:39",
  "JsonServer version": "0.0.0.1",
  "running since": "11/09/2016 13:49:22 (0:57:16.480000 ago)",
  "threads running": [
    "MainThread",
    "Thread-1"
  ],
  "SmartMesh SDK version": "1.1.0.2"
}

In particular, the response indicates that the JsonServer is not connected to any SmartMesh IP manager:

"managers": {},

List the active serial ports

Issue the "05 helpers/GET helpers serialports" request. The response contains:

{
  "serialports": [
    "COM28",
    "COM29",
    "COM30",
    "COM31"
  ]
}

The response indicates that there are 4 serial ports active on the server. In this example, the serial API of my SmartMesh IP Manager is the fourth entry, "COM31".

Connect the JsonServer to your Manager

Issue a "06 config/PUT config managers put" request with the following body:

{
    "managers": ["COM31"]
}

The JsonServer responds with a "200 OK" status indicating the manager was added.

You can issue a new "02 stats/GET status" request to verify the manager has been added and the JsonServer established a connection:

{
  "managers": {
    "COM31": "connected"
  },
  "current time": "11/10/2016 07:14:34",
  "JsonServer version": "0.0.0.1",
  "running since": "11/09/2016 13:49:22 (17:25:11.519000 ago)",
  "threads running": [
    "IpMgrSubscribe",
    "Thread-1004",
    "MainThread",
    "Thread-1",
    "ManagerHandler@COM31",
    "COM31_HDLC"
  ],
  "SmartMesh SDK version": "1.1.0.2"
}

List the motes in the network

The JsonServer can connect to one or more managers. It automatically discovers which motes are in each of the networks. You can issue a "05 helpers/GET helpers motes" request to retrieve the list:

{
  "COM31": [
    "00-17-0d-00-00-38-07-18",
    "00-17-0d-00-00-38-06-d5",
    "00-17-0d-00-00-38-06-ad",
    "00-17-0d-00-00-38-06-45"
  ]
}

Here, the JsonServer tells me there are 5 motes connected to the manager at COM31.

Issue the getNetworkConfig Serial API commands

Through the JsonServer, you can issue any raw serial API command through the /api/v1/raw resource. That is, to issue getNetworkConfig serial API request on the manager connected to COM31, send an HTTP post with the body:

{
    "manager": "COM31",
    "command": "getNetworkConfig"
}

The body of the response contains the serial API response of the manager:

{
  "networkId": 425,
  "apTxPower": 8,
  "ccaMode": 0,
  "locMode": 0,
  "numParents": 2,
  "channelList": 32767,
  "baseBandwidth": 9000,
  "maxMotes": 33,
  "bbSize": 2,
  "bbMode": 2,
  "oneChannel": 255,
  "isRadioTest": 0,
  "downFrameMultVal": 1,
  "RC": 0,
  "bwMult": 300,
  "frameProfile": 1,
  "autoStartNetwork": true
}

Issue the getMoteConfig Serial API commands

For serial API requests requiring additional fields, just specify them in the "fields" JSON element. For example:

{
    "manager": "COM31",
    "command": "getMoteConfig",
    "fields": {
    	"macAddress": [0,0,0,0,0,0,0,0],
    	"next": true
    }
}

Which returns:

{
  "macAddress": [
    0,
    23,
    13,
    0,
    0,
    56,
    6,
    103
  ],
  "reserved": 1,
  "state": 4,
  "isRouting": true,
  "RC": 0,
  "moteId": 1,
  "isAP": true
}

Switch mote's LED on/off over OAP

The JsonServer understands the OAP protocol natively.

The "On-chip Application Protocol" (OAP) is documented in the SmartMesh IP Tools Guide. We assume you are familiar with it.


To set the INDICATOR_0 LED of mote 00-17-0d-00-00-38-07-18, issue an HTTP PUT to URI /api/v1/oap/00-17-0d-00-00-38-07-18/digital_out/INDICATOR_0 with body:

{
    "value": 1
}

which returns:

{
  "status": "OK",
  "fields": {},
  "resource": "digital_out/INDICATOR_0",
  "method": "PUT"
}

Verify that the blue LED on your DC9003 board is on. If the LED does not turn on, check that the LED_EN jumper is closed.

Issue the same request with the following body to switch off the LED:

{
    "value": 0
}

Issue an OAP echo request

OAP includes an "echo" resource which returns an incrementing counter. You can interact with it by issuing an HTTP GET request to URI  /api/v1/oap/00-17-0d-00-00-38-07-18/pkgen/echo with an empty body.

Issue it multiple times to see the counter (the "echo" field) increment:

{
  "status": "OK",
  "fields": {
    "echo": 3
  },
  "resource": "pkgen/echo",
  "method": "GET"
}
{
  "status": "OK",
  "fields": {
    "echo": 4
  },
  "resource": "pkgen/echo",
  "method": "GET"
}
{
  "status": "OK",
  "fields": {
    "echo": 5
  },
  "resource": "pkgen/echo",
  "method": "GET"
}

in addition to what we have seen here, the OAP protocol allows you to:

  • see the version of the application running on the mote
  • specify the IPv6 address notifications should be sent to
  • get/set the state of GPIO pins and enable automatic notifications on change
  • read the value of the ADC pins, and enable periodic notifications
  • read the temperature, and enable periodic notifications
  • trigger the generation of a number of (dummy) notifications to generate arbitrary data in the network for testing purposes

All of these can be done though the JsonServer application and are present in the Postman collection.


Receive Notifications

The SmartMesh IP manager generates notifications on its serial port (data received from motes, networking events, etc). The JsonServer application translates each notification into a JSON string and performs an HTTP POST with the JSON body to a configured URL. The URL to which each notification is sent is configured by the user for each type of notification. By default, it is http://127.0.0.1:1880, the default URL of a Node-RED instance running on the same computer as the JsonServer

Notification typeDefault URLDescription
event
http://127.0.0.1:1880/event
Event notification
hr
http://127.0.0.1:1880/hr
Parsed health report notification
oap
http://127.0.0.1:1880/oap
OAP notification from a mote

notifData

http://127.0.0.1:1880/notifData
Data notification from a mote
notifIpData
http://127.0.0.1:1880/notifIpData
IP Data notification from a mote
notifHealthReport
http://127.0.0.1:1880/notifHealthReport
Health report notification
notifLog
http://127.0.0.1:1880/notifLog
Log notification

The URL that each of the notifications are sent to is part of the configuration of the JsonServer. You can get/set it through the /api/v1/config resource.


The NotifReceiver.py script shows the notifications sent by the JsonServer. 

The NotifReceiver.py script listens for notifications on the same default port as the Node-RED server. Only one of these applications can be listening for notifications at a time.


Run NotifReceiver.py and observe the notifications that it prints out. Motes with the default firmware should generate OAP temperature notifications every 30 seconds. For each temperature notification, two notifications, /oap and /notifData will appear in the NotifReceiver output. 

Bottle v0.12.10 server starting up (using WSGIRefServer())...
Listening on http://localhost:1880/
Hit Ctrl-C to quit.


================================================================================
method: POST
path:   /oap
body:   {   u'fields': {   u'channel': [5],
                   u'channel_str': u'temperature',
                   u'num_samples': 1,
                   u'packet_timestamp': [262572119296, 95553792],
                   u'rate': 30000,
                   u'received_timestamp': u'2016-11-14 17:37:42.916559',
                   u'sample_size': 16,
                   u'samples': [2764]},
    u'mac': u'00-17-0d-00-00-38-10-e0',
    u'name': u'oap'}

127.0.0.1 - - [14/Nov/2016 17:37:42] "POST /oap HTTP/1.1" 200 0
================================================================================
method: POST
path:   /notifData
body:   {   u'fields': {   u'data': [   0,
                                2,
                                5,
                                0,
                                255,
                                1,
                                5,
                                0,
                                0,
                                0,
                                0,
                                61,
                                34,
                                132,
                                149,
                                0,
                                5,
                                178,
                                9,
                                0,
                                0,
                                117,
                                48,
                                1,
                                16,
                                10,
                                204],
                   u'dstPort': 61625,
                   u'macAddress': u'00-17-0d-00-00-38-10-e0',
                   u'srcPort': 61625,
                   u'utcSecs': 1025672341,
                   u'utcUsecs': 373250},
    u'manager': u'COM27',
    u'name': u'notifData'}



Stop the JsonServer application

To close the JsonServer application, simply close the command prompt window.

The application saves its configuration in the JsonServer.config file, so the next time you start it, it resumes with the same configuration.