Expand

When OKE has a WiFi network interface, either directly integrated into the equipment or via a WiFi CWM, it will interface with the OKC as a secure HTTP client using the RESTful API documented in this section.

OKC Server Name

The DNS name of the OKC is TBD.

Security

OKE will use TLS 1.2 or later to secure the HTTP connection between the OKE and OKC.

Timeouts

When making HTTP requests OKE will wait at least 20 seconds for an HTTP response before timing out.

Connection Persistence

OKE will maintain its TCP/TLS session with the OKC between RESTful requests.

Reconnection Back-off

CWM will implement a back-off algorithm for reconnecting to the server when a connection fails. The back-off timeout will increase exponentially for each consecutive connection failure up to 2 minutes in duration.

Server Error Back-off

Like the reconnection back-off, OKE will follow the same back-off algorithm when the server indicates it is busy, or when an unexpected error has occurred.

/pull

When the OKE ISFQ is not full and the OKC has indicated to make a request to the /pull URI then the CWM will make a GET request for that resource.

The CWM will URL encode GET argument values.

Example:

/pull?sha256hmac=XX…XX&req={"devid":"00000102030405060708","ts":"2020-09-16T12:13:47","lokm":true}

HTTP Status 200

Code Block

language	json

{"okm":{"_dst": ["00006hgCB20O8Az|8PL|8Rz|"],"_cmd": "rd","_id": 4,"_ts": "2020-09-21T17:20:58Z","_crc": "79F1","_pld": {"_ping": true}},"pull":false}

/pull Request

The CWM will include a sha256hmac argument on the URL which is a hexadecimal string used to authenticate the message and verify its integrity.

The CWM will include a sha256hmac argument on the URL which is a hexadecimal string used to authenticate the message and verify its integrity. In order to authenticate the CWM the OKC must compute the SHA256 HMAC of the req argument's URL decoded value using the Provisioning Key associated with the CWM's device ID.

If the computed value exactly matches the hexadecimal string encoded value of the sha256hmac argument, then the OKC may process the req field. Otherwise the OKC must not process the req argument and may log an authentication error. Regardless, the OKC should not process any other arguments passed in the URL as these are not authenticated by the Provisioning Key.

The CWM will include a req argument on the URL which is a JSON string containing three fields.

The first field is named devid and its value is the Device ID of the CWM. The OKC can use this field to determine which OKM should be sent in response to the /pull request.

The second field is ts, which is an ISO 8601 string indicating when the /pull request was generated by the CWM.

The third field is lokm with a value of either true or false. When true the last OKM sent in response to the last /pull request was successfully queued by the CWM and the OKC can advance to the next OKM for delivery. When false or not present the OKC should send the same OKM as the previous /pull response.

/pull Response

If the server responds with a status code of 200 the CWM will expect a JSON string in the response data. The JSON string will contain two fields: okm and pull.

The okm field value is a JSON object that is the OKM to be queued by the CWM. This OKM should be addressed to either the CWM or the connected OKE.

The pull field is either true or false. When true the CWM will schedule another /pull request once it has successfully queued the OKM, or the queuing fails. When false the CWL will not invoke /pull again until the pull field is set to true in a /push response.

MiWi Protocol Interface

When an OKE system has a MiWi CWM it will interface with the OKC via the MiWi network. The head of the MiWi network is the PowerHouse IoT Gateway that has a network connection (WiFi and/or Ethernet) to the OKC. The IoT Gateway will use the same RESTful interface that an OKE with a WiFi interface uses to interact with the OKC.

The IoT gateway will pass an argument named lcwack on the config_* URL. If the value is 1 then the last config write request of an OKM was successfully delivered to the CWM via the MiWi network. However, it does not mean that the OKE has successfully received the OKM. When the value is 1 the OKC may advance to the next OKM that should be sent to the CWM. When the value is 0 the OKC should resend the last OKM it sent to the IoT gateway previously since the OKM was not confirmed as delivered to the CWM over the MiWi network.

When responding to a config_* request the OKC may include pc field in the JSON response with the value of 1. This causes the IoT gateway to keep polling the config_* interface until the OKC doesn’t have any more OKMs to send to the CWM or OKE.

CWM Messages

Expand

This section describes application layer messages that are generated and recognized by the CWM.

CWM Heartbeat Messages

The CWM generates its own application layer heartbeat message primarily to aid remote troubleshooting of OKE installations.

If supported the ti field reports the internal temperature of the CWM in whole degrees C.

The diag field is an array of 32-bit unsigned integers. The counters are reset to 0 on a reset and could overflow to 0. The first array value is total number of OKM queue read requests. The second value is total number of queue reads without a _crc field. The third value is the total number of queue reads with an invalid _crc field. The forth field is the total number of queue reads that were invalid JSON.

If supported the cfgpend field is a Boolean that indicates if the CWM needs to reboot to apply a configuration.

The scan field is a Boolean that indicates if the CWM is scanning its ports for an OKE.

The baud field is an unsigned 32-bit integer indicating the current baud rate the CWM is operating at.

The sidx field is an unsigned 16-bit integer indicating the port index being scanned.

The smax field is an unsigned 16-bit integer indicating the total number of port indexes to scan.

The txp field is a Boolean indicating if there is a transmit request pending on the OKE port.

The msp field is an array of 16-bit integers that indicate the maximum number of OKMs that the Telemetry, Priority, and Inbound queues can store respectively.

The rcon field is a hexadecimal string field representing the 16-bit register value of the PIC24's RCON register on boot.

The 5v and 12v fields respectively report the voltages of the power rails in mV.

The port field is an enumerated string indicating which port the CWM is currently using to communicate to the OKE.

OKE Port Configuration

The OKC may manually configure the CWM's OKE communication port and settings using this message within the _pld field of a standard OKM.

oke

The oke field encapsulates the port configuration that the CWM should use for communicating to an attached OKE. The value of the field is an object containing both the port and baud fields.

The port field value is an enumerated string with a value of "usb", "ttl", "232", or "485". The SPOD CWM implementation only supports "232" and "485".

The baud field value is an unsigned 32-bit integer, any value >= 9600 and <= 230400 is valid. The most common setting is 115200.

Example _pld object: