Content Comparison

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.

/push

The OKC /push interface allows the CWM to push OKMs to the OKC and confirm their delivery. It also provides a mechanism for the OKC to have the CWM invoke the OKC /pull interface to fetch OKMs going downstream to the CWM or connected OKE.

The CWM will URL encode GET argument values.

Example:

/push?sha256hmac=XX..XX&req={"okm":{…},"ts":"2020-09-16T12:13:47"}

HTTP Status 200

{"push":true,"pull":true}

/push request

When the CWM has a message in either its PSFQ or TSFQ and the $._dst is OKC or not present, then the CWM will POST to the /push URI of the OKC server.

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 two fields. The first field is named okm and its value is the OKM being pushed to the OKC. The OKC can determine the source of the OKM from the _src field. The second field is ts, which is an ISO 8601 string indicating when the /push request was generated by the CWM.

/push response

If the server responds with HTTP status code 200 then the CWM will process the response data as a JSON string. This JSON string should contain the following fields: push and pull.

The push value is either true or false. When true the OKM pushed by the CWM to the OKC was successfully received and the CWM will free the OKM from its queue. When false or the push field is not present the CWM will not free the OKM from the queue and will attempt to resubmit the OKM again.

The pull value is either true or false. When true the OKC is requesting that the CWM invoke the /pull interface. When false or the pull field is not present the CWM will not invoke the /pull interface.

The CWM can simultaneously invoke both the /push and /pull interfaces on separate connections with the OKC. However, the CWM will never invoke more than one /push or /pull request simultaneously.

/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

{"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 (Deprecated)

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.