control [ezeio documentation]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
==== control ====

Set a field value or output status

=== Description ===

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

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''
<code>https://api.eze.io/v1/control/XYZ987/field[12]=4711</code>

To set the state of a register: ''register[DEVICENO,REGISTERNO]=value''
<code>https://api.eze.io/v1/control/XYZ987/register[2,34]=56</code>

To set the state of an output, bypassing logic: ''output[OUTPUTNO]=value''
<code>https://api.eze.io/v1/control/XYZ987/output[2]=100</code>

Multiple commands can be used in the same call.

=== Example usage ===

Set the value of two fields:
<code>https://api.eze.io/v1/control/XYZ987/field[12]=888/field[5]=999</code>

== 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):
<code javascript>
{
  "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
}
</code>

The callback message from the controller, acknowledging processing of the command:
<code javascript>
{
  "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
    }
  }
}
</code>