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¶

Devices must subscribe to (MQTT) or poll from (HTTP) the data_out resource. ExoSense will send new control requests to this resource in the same format as devices write to data_in.

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

1. Acknowledge by writing the full data_out value back to that resource.
2. Take action (example turn on a valve, set a setpoint, etc) and write the new value for the channel to data_in.

UI elements in ExoSense use the data_in value for a channel to close the feedback loop that the device actually took action on the control request.

A few notes:

• 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.