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

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.

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

  variable	description	example
  host	hostname or IP address of the server running the JsonServer app	127.0.0.1
  port	TCP port that the JsonServer app is listening on, defaults to 8080	8080
  serialport	serial port the SmartMesh IP manager is connected to on the server	COM27
  mote	MAC address of a SmartMesh IP mote running the default firmware in master mode	00-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.

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"
}

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"
}

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. 

http://127.0.0.1:1880/event

http://127.0.0.1:1880/hr

http://127.0.0.1:1880/oap

http://127.0.0.1:1880/notifData

http://127.0.0.1:1880/notifIpData

http://127.0.0.1:1880/notifHealthReport

http://127.0.0.1:1880/notifLog

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

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.