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.

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
Status Codes

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

http

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

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