control

Set a field value or output status

Description

https://api.eze.io/v1/control/{serial}/{command}/[additional commands]

Directly control a field value or output status of a controller. Note that this command will generate traffic to the controller, and is therefore rate limited to avoid excessive traffic. The field has to be set as “Writable”.

The immediate return data is a confirmation from the servers that the command was accepted. It is not an acknowledgement that the command(s) were actually received or executed on the controller.

If the API key is set up with a callback URI, a separate message will be sent to this URI when the command has been confirmed by the controller. See below for the format of the return messages.

Parameters

serial ezeio serial number (XYZ123)
command Command. See below

Possible commands:

To set the value of a field: field[FIELDNO]=value

https://api.eze.io/v1/control/XYZ987/field[12]=4711

To set the state of a register: register[DEVICENO,REGISTERNO]=value

https://api.eze.io/v1/control/XYZ987/register[2,34]=56

To set the state of an output, bypassing logic: output[OUTPUTNO]=value

https://api.eze.io/v1/control/XYZ987/output[2]=100

Multiple commands can be used in the same call.

Example usage

Set the value of two fields:

https://api.eze.io/v1/control/XYZ987/field[12]=888/field[5]=999
Log flush

Setting the value of a field will also cause any pending buffered log samples to be sent to the servers. This only applies to the control field command. Setting register or output value does not cause a log flush.

Tip: To force a log flush without making any changes to field values, write value 0 to field[0]. This has no effect on any valid field, but will still cause a log flush.

Return value

JSON formatted data

(below examples have whitespaces added for readability)

The immediate server reply (acknowledging receipt of the command on the servers):

{
  "reqtime":"2019-06-16T19:50:18Z",
  "actions":[
    "Set field 12 to 888",
    "Set field 5 to 999",
    "Callback URI: https://mydomain.com/mycallbackscript.php"
  ],
  "status":"OK",
  "exec_time":0.011375188827514648
}

The callback message from the controller, acknowledging processing of the command:

{
  "apikeyid":10009,
  "subject":"CONTROL_ACK",
  "time":"2019-06-16T19:45:52Z",
  "meta":{
    "serial":"XYS-987",
    "group":2,
    "accountgroupid":0,
    "name":"Test controller in lab",
    "note":"Here is a note",
    "tzofs":"0"
  },
  "adc":{
    "1":2,
    "2":2,
    "3":7,
    "4":2,
    "5":2,
    "6":2,
    "7":2,
    "8":29977,
    "Vin":12213,
    "Vbat":12090,
    "V5":5106
  },
  "out":{
    "1":0,
    "2":0,
    "3":0,
    "4":0
  },
  "pos":{
    "x":38677889,
    "y":-121174896,
    "z":0,
    "signal":-1
  },
  "fields":{
    "1":{
      "name":"Uptime",
      "unit":"s",
      "assettag":"uptime",
      "value":1102790
    },
    "2":{
      "name":"Temp (C)",
      "unit":"°C",
      "assettag":"temp",
      "value":26.6
    },
    "3":{
      "name":"Temp (F)",
      "unit":"°F",
      "assettag":"",
      "value":79.879997
    }
  }
}