Device Settings API

This API is used to send commands and settings to devices connected to a Push3 gateway as well as the gateway device itself.

Settings API requests require an API bearer token to prove that the client is authorized to make the request.

If the token has OWNER permissions then commands can only be sent to devices that the client owns.

If the token has GROUP or ADMIN privilege then the client can send commands to devices owned by any account provided that a valid key is provided that is associated with the requested object. This would normally be an account key or a gateway key for which the device is assigned to.

POST /sendCommand

Query Parameters:

• key (string) – The Push3 gateway key. This can optionally be specified in the POST body json.

Request JSON Object:

• command (string) – the name of the command (ie “SetRelay”)

• target (string) – the target device type (ie “meter”)

• target_id (string) – the target id (ie a meter address)

• client (string) – optional API client name. This should be relatively unique.

• response_channel_id (string) – optional response channel id

• params (jsonobj) – the command parameters as a JSON object

Response JSON Object:

• msg_id (string) – the message id used to identify the response message

• response_channel_id (string) – websocket/stream channel id for response message

• response_channel_host (string) – host of websocket/stream

Request Headers:

• Authorization – Bearer <api-token>

• Content-Type – application/json

Status Codes:

• 200 OK – request succeeded

• 400 Bad Request – when parameters are invalid

In case of an error (response code 400) the response JSON will contain an error attribute with a string value describing the error.

The response from this endpoint does not tell you if the command was received by the gateway device or if it was successfully executed, only that the command was sent to the gateway device.

The command message is sent to the gateway device via an HTTP push stream that the gateway polls for incoming commands. The gateway then responds by sending a JSON message via a separate response push stream.

The response from the sendCommand endpoint gives enough information to poll the push stream for a response message from the Push3 gateway device handling the command. The stream is accessible using a websocket or an HTTP stream connection.

Retrieving the Command Response

Since commands can be sent to the same Push3 gateway device by more than one client asynchronously the order of response messages (or the time it takes to respond) is not guaranteed. It is necessary to poll an HTTP stream or websocket for messages and wait for the message that matches the message id returned by the sendCommand API.

Either an HTTP stream connection or a websocket can be used.

The response message stream URL is constructed as follows:

https://(response_channel_host)/sub/(response_channel_id)

The websocket address:

wss://(response_channel_host)/ws/(response_channel_id)

HTTP stream endpoint and response JSON:

GET /sub/(response_channel_id)

Query Parameters:

• response_channel_id (string) – the channel id returned by the sendCommand API.

Response JSON Object:

• msg_id (string) – the message id used to identify the response message

• timestamp (float) – epoch timestamp of when the gateway received the command

• success (boolean) – true if the command succeeded, otherwise false

• error (string) – an error message if the command failed, otherwise null

• data (jsonobj) – a json object if the command has a return value, otherwise null

Example

Close Relay 1 for one second on meter 000300004127

Note: The example API token is non-functional so this request will fail. You will need to request an API token and use your own account keys.

http

POST /sendCommand?key=MTAxMDoyMDIw HTTP/1.1
Host: api.ekmpush.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer XZTdu8_5iw62WQuDg4OHIMhG7mcEqJu8VrzHSywCkPk

{
    "command": "SetRelay",
    "target": "meter",
    "target_id": "000350000900",
    "params": {
        "relay": "Relay_1",
        "status": "close",
        "duration": 1,
        "meter_password": "00000000"
    }
}

curl

curl -i -X POST 'https://api.ekmpush.com/sendCommand?key=MTAxMDoyMDIw' -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer XZTdu8_5iw62WQuDg4OHIMhG7mcEqJu8VrzHSywCkPk" --data-raw '{"command": "SetRelay", "params": {"duration": 1, "meter_password": "00000000", "relay": "Relay_1", "status": "close"}, "target": "meter", "target_id": "000350000900"}'

response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "msg_id": "8fce23ce5d0b11ebb86e4c1d96d9f4c7",
    "response_channel_id": "response_NjUyNTQwNzI6dUU5N2F3MEFOMmxSdlVadTM0",
    "response_channel_host": "psrv1.ekmmetering.com"
}

To then get the command response from the message push stream

http

GET /sub/response_NjUyNTQwNzI6dUU5N2F3MEFOMmxSdlVadTM0 HTTP/1.1
Host: psrv1.ekmmetering.com
Accept: application/json

response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "msg_id": "8fce23ce5d0b11ebb86e4c1d96d9f4c7",
    "timestamp": 1611374002.628128,
    "success": true,
    "error": null,
    "data": null
}

Using curl:

curl --no-buffer -s -v "https://psrv1.ekmmetering.com/sub/response_NjUyNTQwNzI6dUU5N2F3MEFOMmxSdlVadTM0.b20"

Meter Commands

target:

“meter”

Note

For more details on parameter values see settings constants

SetMeterPassword

new_password:

(string) - the new meter password

SetCTRatio

ct_ratio:

(string) - the new CT ratio value

SetTime

year:

(string) - “YYYY”

month:

(string) - “MM”

day:

(string) - “DD”

hour:

(string) - “HH”

minutes:

(string) - “mm”

seconds:

(string) - “ss”

SetMaxDemandResetInterval

interval:

(int) - the new interval

SetMaxDemandResetNow

(no parameters)

SetMaxDemandPeriod

max_demand_period:

(int) - the new period

SetLCD

display_fields:

(list) - list of display fields

SetPulseInputRatio

pulse_line:

(int) - the pulse input line number

pulse_input_ratio:

(int) - the new input ratio

SetPulseOutputRatio

pulse_line:

(int) - the pulse input line number

pulse_output_ratio:

(int) - the new output ratio

SetZeroResettableKWH

(no parameters)

SetRelay

relay:

(string) - the relay name (ie. “Relay_1”)

status:

(string) - relay state (“open” or “close”)

duration:

(int) - state duration in seconds. A value of 0 (zero) means hold indefinitely.

meter_password:

(string) - the meter password. Defaults to “00000000” if not present.

SetHolidayDates

SetSchedule

SetWeekendHolidaySchedules

weekend_schedule:

(int) - the weekend schedule number

holiday_schedule:

(int) - the holiday schedule number

GetSchedules

GetTariffData

IOStack Commands

target:

“iostack”

SetPassword

new_password:

(string) - the new meter password

password:

(string) - the current password

ScanOneWire

Scan 1-wire bus for devices.

GetStatus

SetDateTime

ResetDICount

Reset DI pulse count.

pin:

(int) - the Digital input pin number

SetDOLevel

pin:

(int) - the Digital output pin number

level:

(int) - the pin level (0 or 1)

clear_watch:

(bool) - optional

password:

(string) - optional