Device Types Guide

The Arrayent Cloud enables you to create data models for your connected devices. Arrayent calls these device data models Device Types.

The Arrayent Cloud provides the authoritative state of your connected devices.

  • When a state change occurs in a device (e.g. a user pushes a button), the device updates its data model in the Arrayent Cloud.
  • When a web or smartphone application wishes to change the state of a device, it updates the device’s data model in the Arrayent Cloud. The Arrayent Cloud pushes the state change to the device.
  • When a web application wishes to retrieve the state of a device, it uses the Arrayent web service API to read the device data model from the Arrayent Cloud.

Because many connected devices operate in constrained environments (e.g. poor wireless connection, power outages) it is possible for the Arrayent Cloud’s representation of a device to be different from the actual state of the device. For this reason you can think of the Arrayent Cloud’s data model of your device as the intended state of the device.

Each Device Type consists of a set of one or more Device Attributes. The Device Attributes are key-value pairs which describe the state of the device.

For example, if you wanted to be able to monitor or control the state of a light on your device, you could create a Device Attribute called LightState in your Device Type. To view the state of the light from a mobile application, your mobile application would use the Arrayent web service API to retrieve the current value of LightState. Conversely, if you wanted to remotely turn the light on or off using your mobile application, the mobile application would update the value of LightState. The Arrayent Cloud will automatically send the state update to the device. Last, when a user turns on the light locally, your device would transmit this event to the cloud by updating the value of LightState.

Device Attributes

You define Device Types and Device Attributes using the Configurator. See the Configurator Reference for step-by-step instructions on creating Device Types and Device Attributes. When you create a Device Attribute you are provided with the option to configure numerous fields, such as Time Series, Hardware Attribute, Data Type, and more (see image below). The rest of this section describes the purpose of each of these fields.

../_images/create-device-attribute-form.png

Name

The Name is the official identifier for the attribute. This is the “key” that we refer to when we say “key-value” pair. The name must be alphanumeric.

Display Name

The Display Name is simply a description of the attribute. You can use this to store internal information about the intended purpose of and expected values for the attribute. Or you can use this to store a user-friendly description of the attribute. A web or mobile application could then retrieve this information by calling the web service operation getDeviceAttributesWithValues and then displaying it to the end-user.

Time Series

When the Time Series field is enabled the Arrayent Cloud stores a timestamped history of every update to this Device Attribute, whether that update was submitted by a web / mobile application or a device. When Time Series is disabled, the Arrayent Cloud only stores the current value of the attribute. A web or smartphone application can retrieve the timestamped history of an attribute using the web service operation getDeviceTS2.

Hardware Attribute

If you want the Arrayent Cloud to automatically push a Device Attribute update down to a device when a web application updates the value of the Device Attribute, then enable the Hardware Attribute field. For example, assume that a Device Attribute named Nickname has been defined with the Hardware Attribute field enabled and then look at the diagram below. ../_images/hardware-attribute.pngThe web application updates the value of Nickname to Fred. The Arrayent Cloud sends the update to the device. The device acknowledges the update. The cloud then updates value of Nickname in its data model for the device. The cloud finally sends an acknowledgment back to the web application indicating that the update successfully reached the device. Now assume that the Nickname attribute has been defined with the Hardware Attribute field disabled and look at the diagram below. ../_images/non-hardware-attribute.pngWhen the web application updates the value of Nickname to Fred the Arrayent Cloud simply updates its data model for the device and then returns an acknowledgment. In general, disabling the Hardware Attribute is useful if you have some device data that you can retrieve from the user and store in the Arrayent Cloud, but do not need to actually send down to the physical device.

Hardware IO Type

The Hardware IO Type field specifies the typical direction of the Device Attribute. By “direction” we mean whether updates to the attribute usually come from the web / mobile application, or from the device. FromDevice means that the attribute is usually updated by the device. ToDevice means that the attribute is usually updated by the web / mobile application. This field is only provided for the convenience of web and mobile applications. For example, the Arrayent Utility web application reads the Hardware IO Type field in order to determine how it should display an attribute in its user interface (e.g. a FromDevice attribute is displayed as read-only, a ToDevice attribute is displayed as editable). The Arrayent Cloud does not enforce directionality. For example, just because a Device Attribute is defined as FromDevice does not mean that the Arrayent Cloud will reject any updates the attribute that originate from web / mobile applications. All Device Attributes can be updated from either a device or a web / mobile application.

Stored by Server

This is an old feature that is no longer supported in any Arrayent Cloud environments. For historical purposes, an explanation of the feature is provided below. When Stored by Server is enabled, the Arrayent Cloud writes the current value of an attribute to its database whenever an update is received (from either the device or a web / mobile application). Each update overwrites the previous value that was stored in the database. When Stored by Server is disabled, the current value of the attribute is only stored in nonvolatile memory. In theory, if the Arrayent Cloud were to go down, the current value of the attribute would be lost.

Attribute Data Type

Attribute Data Type specifies the type of input that is valid for the attribute, as well as the range of valid values for the input. Setting Device Attributes to values that do not match their defined data types can result in errors from the Arrayent Cloud or undefined behavior. For example, if you define an attribute as an integer and then set the value of the attribute to a string, the Arrayent Cloud will reject the update. See Data Types Reference for a list of supported data types.

Global and Global Attribute Value

When the Global field is enabled, the value of the attribute will be the same for all devices of this Device Type. You specify the value of the attribute in the Global Attribute Value field when defining the attribute. The Arrayent Cloud does not send Global Attributes to devices. If you want to retrieve a global attribute value and then send this value to a device, call getDeviceAttributesWithvalues from your web / mobile application and then send the value to a device via some other Device Attribute. You cannot modify the value of a Global Attribute via the Arrayent web service API. The only way to modify its value is to log in to the Configurator and edit the Device Attribute definition. Global attributes are often used for displaying information which is global across all devices of this type and which does not need to be sent to a device. For example, suppose that you manufacture refrigerators and you want to display the model number of your connected refrigerator somewhere in your web application. You could define a ModelNumber attribute and set it as a global. Your web application could then call getDeviceAttributesWithValues to retrieve the value of ModelNumber and display this to the user.

Enumerated Alias

The Enumerated Alias is a numerical alias for the Name of the Device Attribute. Your Enumerated Aliases can be any value between 1and 99. Values 100 and beyond are reserved by Arrayent. When updating a device via the web service operation setMultiAttributesBy you can refer to each Device Attribute by its Enumerated Alias (rather than its Name) by setting the by argument to ENUM. In order to use the Arrayent Connect Agent’s multi-attribute message functions ArrayentSetMultiAttribute or ArrayentRecvMultiAttribute you must define an Enumerated Alias for each attribute that you plan on sending or receiving via these functions.