Definition

A template is a group of properties and attributes (e.g. temperature, module name, OEM ID, ON, OFF, Ayla registration type, etc.) that define the parameters, behaviors, and functionality of a device that connects to the Ayla Platform.

Product development begins by defining a device. To define a device, use an existing template or create a new one to enter the device properties and attributes. A physical device is represented on the Ayla Cloud Platform via a “digital twin” comprised of properties and key-value pairs. Essentially, a template is an abstraction of a device in the Ayla Cloud Platform. It determines how the users and applications interact with the connected device.

Please contact Ayla Support if you need more help with Templates or have any additional questions on the Ayla IoT Platform.

Importance of templates

• Predefined templates reduce the time and effort required in creating a product. When a template is assigned to a device, common settings are applied, which saves the time required for manual configuration.
• Templates provide a common interface between device, cloud, and application on which properties are available for the device.
• A template is required to define the device services which are accessible and controlled through the cloud. It helps to represent a device used by web and mobile applications. Example: For a light bulb device, services can be anything that can be controlled, like ON / OFF, color, and brightness.
• A template is used to configure useful settings for a device. For example: who can set a property, which property types are supported.
• Templates are used to configure other settings like schedules and LAN mode.

Template diagram

Topics related to templates

Properties

Properties define the functionality and behavioral attributes of a device. A property can be “from device” or “to device”. This is shown as direction "output" (from device) or "input" (to device). This indicates whether the datapoints always come from the device to the cloud (from device) or from the cloud or application to the device (to device).

Developers have the ability to add, edit, or remove properties from templates whenever it is needed (but not while the template is associated with a device). Example property names are: Temperature, set_temp, module_name, power, etc.

Property names can have maximum of 27 characters, must start with an alphabetical character, and must contain only letters, numbers, and underscores (_).

LAN mode

Template indicates whether LAN support is enabled for devices using the template. LAN Support provides local communications between applications and devices when both are on the same LAN network. Enabling LAN support, applications provide the following advantages:

• Allows mobile apps to automatically use Wi-Fi and communicate with the device locally, which works even when the internet is down.
• Possibility to reduced latency for all LAN Mode Enabled (LME) APIs.
• Direct property/connection status updates from the device; polling for device properties is not required.
• Secure communications between applications and modules.
• Session management for applications.

Schedule

Template indicates which schedules a device will have. Schedules are used to automatically trigger property updates and other events on the Ayla 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 universal time (UTC) and for many other parameters, such as months and days of the year, start and end times of the day, intervals, durations, etc.

Ayla schedules are used to schedule an action to execute in the device at any given point of time. All device schedules are pre-created for every customer devices with the help of Schedule Templates. Schedules can support one or more Schedule actions.

Example: With scheduling, developers can configure a water sprinkler to turn ON for some time any time of the day like clockwork. Adding to that, the user can even create a sequence set for days and months of the year.

Role

Developers can grant or deny read/write permissions to specific users (i.e. end-user, dealer, developer, etc.) so that they can create, modify, or view device properties. This means now a user can share access to his light bulb with his family, so that they can turn it ON and OFF.

Template visibility

Template visibility is based on combination of scope defined for a template and the user role.
Templates have the following scope:

• Public - available to all users.
• OEM - can only be viewed by users with an OEM assigned role.
• Private - can only be viewed by the user who created the template.

Template life cycle

1. Product Designers create a document describing what properties should a device have and how they are used. Once you have the properties determined, create a new template in “Private” visibility mode and add properties in Ayla Developer Portal. Alternatively, you can clone from an existing (OEM or Private visibility) template to a new (Private visibility) template and then edit/add parameters to it.
2. When the template is ready for development, associate your development device(s) with the Private template. Template association is the process of applying all of the settings in the template to the Ayla device. The Ayla Device Service chooses the template for association in the following order:
   a. By oem, oem_model, and template version matching exactly with the property oem_host_version.
   b. By using oem, oem_model, and default version "*".
   As template and devices are associated in the Ayla Cloud, Ayla Services are informed of the properties available for the device. Once associated, any changes to the Private template will reflect automatically on the device(s) that are linked to that template.
3. Once the development is stable and you are satisfied with the latest copy of the Private template, clone the template and change visibility to “OEM”. As best practice, ensure that the new OEM template has a unique “oem_host_version” before committing.
4. The final template version of the product should be deployed to Field Service from the OEM Dashboard. Ayla recommends you keep a separate template on the Ayla Developer Service, for testing and modification post production. OEM templates are not allowed to be modified directly.

For any required updates to the “OEM” template, repeat steps 1 to 4.

Use cases

Let us take an example of the dimmer switch product. Dimmer switches are needed for adjusting brightness to have efficient smart home or office lighting requirements. A product developer wants to create a template, set its visibility to “public,” and add properties such as “Current”, “Level”, “Power”, and “Version.”

Start with designing the dimmer switch by creating a device template for it. For more information about template creation, click here. By creating a template and adding required properties and attributes, a digital twin is created for the dimmer switch.

As the developer wants the template to be “public,” the visibility field is set accordingly in the Ayla Developer Portal.

NOTE: Typically a template will have "private" visibility at first, then it is cloned to an "oem" visible template.

All the required properties are added along with their data type, direction, and scope. When the template is ready, it is associated with the device(s). The following screenshot is an example of a template within the Ayla Developer Portal:

Best practices to create and maintain templates

• Each host firmware version will have a template version (“oem_host_version” property). Change the host firmware version when the template needs to be changed,
• When you need to change the host firmware to add a property or change the template in an incompatible way, create new template with a new template version, and then update the firmware to match the new version.
• Secure your device templates by periodic inspection on user roles.
• We recommend not to use Wild card notation (*) in the version field.

Tasks related to templates

• Cloning templates
• Adding templates
• Migrating templates from Development to Field
• Associating/disassociating templates (criteria)
• Editing templates
• Deleting templates

Please refer to Ayla Developer Portal User Guide, to learn more about managing templates.