Device Control¶

ExoSense supports making control requests down to devices. This is accomplished using a dedicated interface resource (data_out) for devices to subscribe or poll from over the Device API.

Application use cases include such as turning on/off a valve and setting set points or modes of operation. A control channel works and uses the same schema / format as regular device channels. Data types, units, and other properties are all used exactly the same.

Device Configuration¶

Devices that support control channels must specify this in the configuration in the config_io Device API resource. The channel properties such as type, report rate, etc are exactly the same, the only different is that a control channel has the 'control' property set to true (default is false).

For example, a temperature set point control channel would use data type of TEMPERATURE with proper units set.

The full specification for the device interface and schema includes more details for developers.

Accepted Control Values¶

The configuration has added a new property called control_properties that allows a device through the configuration to specify acceptable values for the channel. If not provided, the ExoSense UI will allow any value that matches the primitive type (STRING, NUMERIC, BOOLEAN, JSON) for the specified channel data_type. There are two types of control properties.

range

Used for NUMERIC channels to specify the min and max of a range of acceptable values.

enum

Allows specifying a specific set of acceptable values. Applicable for NUMERIC, STRING, and JSON

Boolean channel types always and only have two options - True and False.

Example Channel Configurations¶

This example shows a channel type of Boolean which will only allow for true/false (1 / 0 ) values.

"004": {
  "display_name": "Valve Control",
  "description": "On / Off control",
  "properties": {
    "data_type": "BOOLEAN",
    "control": true
  },
  "protocol_config": {
    "report_rate": 60000,
    "timeout": 360000
  }
}

This example shows a channel of type TEMPERATURE with units of Celsius. In this case, it specifies a range of 20 to 40. The ExoSense UI will only allow for specifying a value inside of this range.

Temperature Set-point Control Channel Config Example

"005": {
      "display_name": "Set Temperature",
      "description": "Set point for Temperature",
      "properties": {
        "data_type": "TEMPERATURE",
        "data_unit": "DEG_CELSIUS",
        "control": true
      },
      "protocol_config": {
        "report_rate": 60000,
        "timeout": 360000
      },
      "control_properties": {
        "range": {
          "min": 20,
          "max": 40
        }
      }
    }

This example shows a channel of type STRING to be used to set a mode. In this case, it specifies a set number of values it will accept as an 'enum'. The ExoSense UI will only allow for specifying a one of these values. If this control_properties was not set, the UI would allow any string.

String type Control Channel Config Example

"006": {
      "display_name": "HVAC Mode",
      "description": "HVAC system mode",
      "properties": {
        "data_type": "STRING",
        "control": true
      },
      "protocol_config": {
        "report_rate": 60000,
        "timeout": 360000
      },
      "control_properties": {
        "enum": [
          "heat",
          "cool",
          "auto",
          "fan",
          "off"
        ]
      }
    }

Control Flow¶

ExoSense will set the data_out resource with the new control requests payload in the same format as devices write channel data to data_in. Devices may subscribe to (MQTT) or use long-poll (HTTP) or a read (HTTP) for the data_out resource.

The next steps slightly different depending on whether devices are required for your application to acknowledge the control request. There are two slight variations on the flow depending on whether the devices in the IoT Connector are required to acknowledge a control message.

Use Device Acknowledgement¶

Sync value with the device Enabled

At the IoT Connector, if the data_out resource is set to Sync value with the device, the device must acknowledge it received the new value by writing it back to the data_out resource. The control panels will show an 'error' message in a giving timeout if this does not happen as it can not be verified that the device received the request.

When receiving a new channel control value through data_out, a device should then:

1. Acknowledge by writing the full data_out value back to that resource. While waiting for this feedback, the UI elements typically will not allow users to make another control request. The UI elements will give up and tell the user the device did not respond given the channel's report rate property.
2. Take action (example turn on a valve, set a set point, etc)
3. (Optional but recommended) Write the new value for the channel back to data_in.

No Device Acknowledgement¶

Sync value with the device Disabled

At the IoT Connector, if the data_out resource is not set to Sync value with the device, the device doesn't need to acknowledge a control message.

When receiving a new channel control value through data_out, a device must:

1. Take action (example turn on a valve, set a set point, etc)
2. (Optional / Recommended) write the new value for the channel to data_in.