################### 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. .. http:post:: /sendCommand :query string key: The Push3 gateway key. This can optionally be specified in the POST body json. :reqjson string command: the name of the command (ie "SetRelay") :reqjson string target: the target device type (ie "meter") :reqjson string target_id: the target id (ie a meter address) :reqjson string client: optional API client name. This should be relatively unique. :reqjson string response_channel_id: optional response channel id :reqjson jsonobj params: the command parameters as a JSON object :resjson string msg_id: the message id used to identify the response message :resjson string response_channel_id: websocket/stream channel id for response message :resjson string response_channel_host: host of websocket/stream :reqheader Content-Type: application/json :statuscode 200: request succeeded :statuscode 400: 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: .. code:: bash https://(response_channel_host)/sub/(response_channel_id) The websocket address: .. code:: bash wss://(response_channel_host)/ws/(response_channel_id) HTTP stream endpoint and response JSON: .. http:get:: /sub/(response_channel_id) :query string response_channel_id: the channel id returned by the *sendCommand* API. :resjson string msg_id: the message id used to identify the response message :resjson float timestamp: epoch timestamp of when the gateway received the command :resjson boolean success: *true* if the command succeeded, otherwise *false* :resjson string error: an error message if the command failed, otherwise *null* :resjson jsonobj data: a json object if the command has a return value, otherwise *null* Example ======= Close Relay 1 for one second on meter 000300004127 .. http:example:: curl 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" } } 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:example:: GET /sub/response_NjUyNTQwNzI6dUU5N2F3MEFOMmxSdlVadTM0 HTTP/1.1 Host: psrv1.ekmmetering.com Accept: application/json HTTP/1.1 200 OK Content-Type: application/json { "msg_id": "8fce23ce5d0b11ebb86e4c1d96d9f4c7", "timestamp": 1611374002.628128, "success": true, "error": null, "data": null } Using curl: .. code:: bash curl --no-buffer -s -v "https://psrv1.ekmmetering.com/sub/response_NjUyNTQwNzI6dUU5N2F3MEFOMmxSdlVadTM0.b20" Meter Commands ============== :target: "meter" .. topic:: 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 -------------