Skip to content

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.

Important Disclaimer

Device control from a remote server application requires common sense and risk analysis to decide if a machine should actually be remotely controlled. To use this functionality, device developers and system integrators that are creating full solution support for remote control are required to provide local override capabilities and safety measures. For example, if a device allows remote control of a garage door that there are physical sensors to sense and not allow a door to close if someone is in the way and ways to override the closing of the door at the physical location.

Enabled Device Control

The Control functionality in ExoSense must be enabled by an administrator before it can be used.

Feature Control Information

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.

ExoSense Panel Support for Device Control

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.

Does the device need to send a value back to data_in?

For a user's experience, UI elements in ExoSense such as dashboard panels that show the control signal will use the data_in value. If you want this to match what the device last did and/or current state, the device should write the value back to data_in for that channel/signal. This ensures the user has the feedback loop that the device took the action (not just acknowledged the request).

It may not be used in 'send and forget' use cases in which the signal value is never shown in the UI.