Properties

Properties and Datapoints

Properties define the functionality and behavioral attributes of a device. The Ayla agent sends and receives name/value pairs between the device and the Ayla cloud service. The Ayla cloud uses properties to deliver control and status information between any device and the web or a mobile application.

A property and its datapoints represent features, states, and status of device in the cloud and is defined by the device OEM. Each device can have a number of properties (Number of properties is limited by host application's memory. There is no limitation from the device and cloud services). A property may represent the ON or OFF state of a light or switch, a temperature sensor reading, the desired thermostat temperature, a schedule for a sprinkler system, an input to a calculation, or just about anything.

Property names are ASCII strings and can contain up to 27 characters. The name must adhere to the following conventions:

Property name can contain:
- Upper and lower-case letters
- Numbers
- Hyphens (-)
- Underscores (_)
First character must be alphabetic.
Spaces or special characters are not allowed.

The following are some attributes that provide the basic details about properties in the Ayla platform:

Template Name - the name of the template for the selected property
Name - name of the property
ID - the Ayla-assigned property ID
Base type - the data type (integer, string, boolean, decimal, file, message)
Direction - the direction of the property (input, output)
Scope – who can use the property (the user, oem, etc.)

For complete list of attributes, please refer to Ayla Developer Portal Guide

Property Base Type

Attribute “base_type” is used to define the data type of a property. The Ayla Module supports the following property base types:

Base Type	Description
Boolean	It has only two possible values: 1 (true) or 0 (false). Use this data type when you want to track true/false conditions. Example: When the red LED button is pressed or released, the property “Red_button” is sent to the ADS with a boolean value of 1 (when pressed) and 0 (when released).
Integer	Integer data type may be of different sizes. It can be either signed or unsigned. Example: A template can be identified by its unique ID number. This ID number is an integer (“template_id”=3827).
String	An array of characters (up to 1024 bytes long, after JSON encoding). Example: “product_name” = “Ayla EVB”.
Decimal	It provides an exact numeric with fixed scale and precision. Example: "property_value": 1008.1008
File	This data type is used for large size properties (size >1 KB). File can be of any type, for example, .png or .txt Only datapoint will be stored in Ayla Cloud, actual file will reside in AWS S3/Azure location. Retention follows the property datapoint rules (30 -90 days based on device template configuration). When all the datapoints cross the configured retention period, the last datapoint will be fetched. File once fetched will no longer be available for later retrieval. File datapoints can only be retrieved in ‘first in first out’ order. If you want to view the latest datapoint, use the History API to fetch all the file datapoints and then check for the latest timestamp. For more information on file properties, please refer File Properties Tech Note
Message	This data type is used to send large strings, JSON files or binary data. Messages can be 0 to 512 MB in size. Mime types supported are: application/json, application/octet-stream, and text/plain.

Batch Datapoint

Batch datapoints are the way to combine property updates over a period and send at once to Ayla cloud. Batch datapoints effectively reduce transaction counts. These are supported on all the agent types. To use this, developers must update the Ayla agent with batch property compatibility.

NOTE: Batch datapoints are not supported on Integrated Agents.

Adding and Editing Properties

A group of properties are added into a device template and then the template is added in Ayla Developer Portal.
“OEM Admin” and “OEM Developer” roles have the ability to add, edit, or remove properties from templates. All property changes must be done at the Template level.
Using the “Denied Roles” feature, OEM Admin can grant or deny read/write permissions for specific users (i.e. end-user, dealer, developer, etc.) to create, modify, or view device properties.

Please refer to Ayla Developer Portal Guide to learn how to add/edit properties.
Please refer to Templates Feature Guide to learn about the device templates.

Metadata

Datapoint metadata is sets of key-value pairs. Metadata can be used to provide more granular details about the device (such as key=Color, value=blue; key=MfgLoc, value=NY; key=Language, value=English; key=MfgDt, value=1706; etc.).

Metadata (create, update, delete) is managed using APIs and/or the Developer Portal with device property datapoints.

Schedules

Once the properties are defined, developers can create schedules for those properties, which can trigger actions in the schedule. Schedules are used to automatically trigger property updates and other events on the device. For example, a schedule can prompt the water sprinkler to turn on at a certain time every morning. You can configure schedules for local time or UTC, and for many other parameters, such as months and days of the year, durations, etc.

The schedule actions specify the update that should occur in the Ayla property when the schedule executes. Every schedule can contain one or more schedules actions.

For more information on schedules, please refer to Ayla Developer Portal Guide.
For schedule related APIs, please refer to Ayla API Reference.