About: Developing a sensor integration

Last modified: Tuesday February 28, 2023.

You can develop an integration for sensors from a number of different sensor manufacturers by using a generic integration. By integrating sensors with Alta Aware®, data from the sensors is available to all of the tools and features within Aware.

Exactly how each sensor integrates into Aware Cloud depends on the make and type of sensor, its capabilities, and the available API functions for the sensor. Find this information from the technical documentation provided by the sensor manufacturer.

Sensor integration using direct webhooks

If the sensors support the option to send webhooks in custom formats, configure the webhooks to meet the required Aware Cloud data format.

Sensor integration using an intermediate application

Create an application to sit between the sensors and Alta Aware Camera Proxy — the application sits between the sensor and Aware Cloud, and ensures the webhook sent to Aware Cloud are correctly formatted. The application receives messages from the sensor and converts them to the webhooks required by Aware.

Some sensors might require an application that uses the sensor API to poll for information that is then converted into the Aware Cloud webhooks.

Sources and channels

The Alta Aware generic sensor integration can be used for a wide range of scenarios. To achieve this, data is grouped in two ways within the system, and any integration should align with this.

Sensors can be used to take one or more measurements in one or more places. Overall a sensor can consist of one or more:

• Sources — physical locations where one or more measurements are taken. Sources can be linked to cameras, and placed onto maps in Map view.
• Channels — single measurements taken at a source. Each channel is associated with a source and provides a stream of data.

This means four different types of sensor can be added:

• Single source, single channel — a single measurement is made by the device.
• Single source, multiple channels — multiple measurements are made by a device in a single location. For example an air quality monitor could report multiple values.
• Multiple sources, single channel per source — the device reports a single piece of information from multiple physical locations. For example a sensor that measures the temperature in several distinct rooms. By doing this as multiple sources, each temperature measurement can be displayed in a separate location in Map view, and have different cameras associated with each source.
• Multiple sources, multiple channels per source — a combination of the above.

The decision on whether to use one device with multiple sources, or to appear as multiple devices each containing a single source depends on the following factors:

• The capabilities of the sensor. If the chosen sensor can send webhooks natively, but only to one address, then it will need to be treated as a single device with multiple sources.
• Heartbeats are per device, so if communicating that one source is offline is important, then consider separate devices per source.
• It the device has a fixed number of inputs, such as 8 sets of terminal blocks, then consider making these multiple sources within a single device.
• The ease of adding devices to Aware Cloud and configuring the sources depends on how many sources and channels are in each device. By having one source per device, more devices need to be added, but less configuration is required for each one.

Each channel within the sensor must be of a single type, but a sensor can include several channels, with a different type of data for each channels.

An application can interact with multiple sensors, and can then present these to Aware Cloud as either separate sensors with their own individual webhooks, or as a single, larger multi-source sensor with each channel uniquely identified.

Messaging

The sensor, or the application, sends updates to a webhook address on Aware Cloud using HTTP POST.

Aware Cloud needs to receive these updates at a suitable frequency that includes all changes of status or significant sensor value changes. The exact timing and the sizeof the sensor value changes depends on the types of sensor being used and the specific requirements for the integrations.

Multiple channels can be updated concurrently, but you do not need to update all channels in a single message.

Send the payload to Aware Cloud as an array of JSON objects in the format:

[{message1},{message2},{message3}]

[{message1}]

Each message must consist of the following fields:

• "channel_id" of type string - uniquely identifies the channel within the sensor. The matching value should be specified when configuring each of the channels when adding this sensor to Aware. It is up to the integration to determine how to uniquely identify the channels. These could be:
  • The channel number; “0”, “1”, etc.,
  • The measurement type, for example, “temperature”, “pressure”
  • Based on some hardware property of the sensor such as the MAC or serial number.
• "value" of type float - the value of the sensor reading, expressed as a float value. If the sensor is of a Boolean type, then send 0 or 1 in the value field.
• "timestamp" of type (unsigned) integer - the number of milliseconds since 01/01/1970 00:00:00 UTC. This is the UTC timestamp of the event based on the UNIX epoch. If using a Unix system, this is the regular UNIX timestamp multiplied by 1000.
• "status" of type string - indicates the sensor status and can take one of the following values:
• “normal” - used when the value is within expected values
• “warning” - used for minor issues
• “alarm” - used for more serious issues
This can be used if the current reading is above or below any thresholds on the sensor. A temperature sensor might have defined limits where a reading outside the limit should cause an alarm. Future releases of Aware Cloud will enable the status to be used as part of Aware Rules.

[{"channel_id": "1","value": -23, "timestamp": 1633711926000,"status": "normal"},
 {"channel_id": "7","value": -15, "timestamp": 1633711926000,"status": "alarm"}]

Heartbeat messages

Each sensor, or application, must send periodic messages. Aware Cloud uses the lack of messages to determine whether the sensor is offline, and so the frequency of messages should be known and used as part of the configuration of the sensor in Aware Cloud. Failure to send periodic messages will lead to the sensor appearing offline within Aware Cloud

In addition, sending of heartbeat messages allows Aware Cloud to learn the current state of the sensor after any restart of Aware deployment. After restarting, Aware Cloud will not display a value for a sensor until a message has been received for the channel. Therefore sending data for all channels in a heartbeat message allows Aware Cloud to learn the current values in a timely manner.

Documenting your integration

When you develop an integration with Aware Cloud, you should also document that integration. The documentation needs to include:

• How to get, install, and run any external application that is needed for the integration with Aware Cloud.
• The settings in the extension code that are needed. For example, the settings required to receive messages from the sensors.
• Any required sensor configuration. For example, to ensure the sensor sends messages to a specific place.
• Configuration of the Aware Cloud user interface. Document the data to be used, most critically around channel names to be entered, which should link back to anything already defined.
• How to get the webhook URL from Aware Cloud and where this information needs to be entered in the sensor integration.