When defining attributes in a Profile for Afero devices, it’s important to model the data in a way that supports easy client design and implementation, as well as good reporting. This page will lay out some best practices and an example to help you define a comprehensive and efficient attribute set for your device.
Below are four guidelines to help you take maximum advantage of the Afero attribute model.
The best way to implement an efficient data model is to start with the client application team. Build the list of things they want to represent in the user interface and work backwards to determine the attributes required to support those features.
For most applications, you can simply take the interesting local variables you have in your firmware and make them Afero attributes; such as a Boolean that holds whether the device is powered on or off.
In general, it’s a good idea to store only one value per attribute. This makes for a cleaner history and reporting data, as well as making things better for the client applications. The one time you may want to consider storing multiple values in an attribute is when they are all part of a single transaction. For example, a command attribute that takes a command type followed by command parameters is better sent as one attribute so that all the data can be parsed at the same time.
Storing things like comma-separated strings or json objects as attribute values will definitely limit what can be done when reporting on those values. It will also increase the size of the attribute value and reduce response time.
Whenever possible, express data in the smallest form possible. Usually this just means using the correct data type for the actual value. Expressing data types like numbers is not only inefficient from a size point of view, it complicates comparisons when doing reporting over a large data set.
For frequency, no more than one write/update per second is preferable. Much slower than that, if possible, is recommended. Remember, a high update rate can affect your overall solution cost. If a device reports attribute values rapidly during operation even if those values haven’t changed, those updates will cause excessive traffic between the MCU and ASR. Also, there’s no need to write a group of related attributes if only one has changed. Only send updates that are meaningful to you.
Writing to ASR does not mean the attribute has been synchronized with the Cloud; synchronization may take some time depending on the radio network or connectivity in general. So if you overwrite an attribute before it’s synchronized, the Cloud will not know about it (with an exception for attributes defined as latch). Read more about allowing adequate attribute write timing in Don’t Forget to Call af_lib_loop().
The MCU can sample as often as desired; there’s no limit on attribute reads since they come directly from ASR with no Cloud overhead. But again, only push useful data.
One way to build a attribute model for your device is to organize all the attribute information in a table, one attribute per row. Assign each attribute a number using column 1. MCU attributes can be numbered 1-1023.
1 No. |
2 Feature |
3 Description |
4 States |
5 Data Type |
6 Writability |
7 Default Value |
8 UI Control |
9 Send Frequency |
10 Dependencies |
---|---|---|---|---|---|---|---|---|---|
1 | |||||||||
2 | |||||||||
⋮ | |||||||||
1023 |
The information entered in the table will answer these questions:
In this example we’ll define the attributes for a smart midline toaster oven. We’ll step through the toaster oven features (a.k.a. attributes), numbering and naming them so we can use that information when defining these attributes in the Afero Profile Editor. The full table is shown at the end of the example in The Toaster Oven Data Model.
First, let’s ask, “What controls does the toaster oven provide?” The Start Button is pretty obvious, let’s begin with that.
Let’s use the table to define the Start button characteristics. We’ll later use this information when defining the attribute in the Profile Editor.
No. | Feature | Description | States | Data Type | Writability | Default Value | UI Control | Send Frequency | Dependencies |
---|---|---|---|---|---|---|---|---|---|
1 | Start Button | Button that starts/stops the currently-set action. |
|
Boolean | Read/Write | Stop | Menu | On Change | Any Cooking Mode is selected. |
The next feature we’ll look at is the cooking mode. On the physical oven unit, the end-user selects a cooking mode using a dial.
No. | Feature | Description | States | Data Type | Writability | Default Value | UI Control | Send Frequency | Dependencies |
---|---|---|---|---|---|---|---|---|---|
2 | Cooking Mode Dial | Selector for setting cooking mode. | 1 = Bake 2 = Convection 3 = Broil 4 = Toast 5 = Warm 6 =Reheat |
SINT8 | Read/Write | Menu | On Change | Feature is available when unit is not cooking. |
This toaster oven requires you set how many slices you want to toast in the oven at once. The toaster can hold up to six slices, but the MCU code accommodates two options.
No. | Feature | Description | States | Data Type | Writability | Default Value | UI Control | Send Frequency | Dependencies |
---|---|---|---|---|---|---|---|---|---|
3 | Number of Toast Slices | Toggle to set number of slices you plan to toast. | 1–3 4–6 |
Boolean | Read/Write | 1–3 | Menu | On Change | Cooking Mode Toast is selected. |
No. | Feature | Description | States | Data Type | Writability | Default Value | UI Control | Send Frequency | Dependencies |
---|---|---|---|---|---|---|---|---|---|
4 | Toast Shade | Selector for setting toast “doneness”. | Range from 1-10, increments of 1, where labels show: 1 = Defrost 3 = Light 5 = Medium 7 = Dark 10 = Very Dark |
SINT8 | Read/Write | Medium (5) | Slider | On Change | Cooking Mode Toast is selected. |
The density of a bagel vs. toast means toasting a bagel to a given doneness takes longer. This toaster oven allows the end-user to specify a bread vs. bagel option via a button.
No. | Feature | Description | States | Data Type | Writability | Default Value | UI Control | Send Frequency | Dependencies |
---|---|---|---|---|---|---|---|---|---|
5 | Bagel | Toggle to set bagel function (adds time to toast cycle). |
|
Boolean | Read/Write | Off | Switch | On Change | Cooking Mode Toast is selected. |
This oven accommodates the entry and reporting of both Celsius and Fahrenheit temperature scales. Using the physical oven controls, the end-user sets their preference using a toggle switch.
No. | Feature | Description | States | Data Type | Writability | Default Value | UI Control | Send Frequency | Dependencies |
---|---|---|---|---|---|---|---|---|---|
6 | Degree Units | Toggle between °C and °F. | °C °F |
Boolean | Read/Write | °F | Menu | On Change | Feature is always available. |
The oven’s current temperature should always be available to the end-user once a Cooking Mode selection is made for either Bake, Convection, or Broil.
No. | Feature | Description | States | Data Type | Writability | Default Value | UI Control | Send Frequency | Dependencies |
---|---|---|---|---|---|---|---|---|---|
7 | Current Temp | Display of current oven temperature. | 130–500 °F (54-250 °C) | SINT8 | Read-Only | Value | On Change | Cooking Mode Bake, Convection, or Broil is selected. |
For Cooking Modes Bake and Convection, the end-user must select a baking temperature. For these modes, the oven is preset to 150 °F or 65 °C. The end-user can adjust the target temperature up to 500 °F or 250 °C. Once the target temperature is reached, a bell rings once. (If the user selects Broil cooking mode, the target temperature is not adjustable, but is set to 500 °F or 250 °C., automatically.)
No. | Feature | Description | States | Data Type | Writability | Default Value | UI Control | Send Frequency | Dependencies |
---|---|---|---|---|---|---|---|---|---|
8 | Set Temp | Selector to set target oven temperature. | 100–500 °F | SINT8 | Read/Write | 150 °F or 65 °C | Slider | On Start | Cooking Mode Bake or Convection. |
The user will be able to set a timer while using Cooking Modes Bake, Convection, or Broil. The timer can be set for up to four hours, in minute/hour increments.
No. | Feature | Description | States | Data Type | Writability | Default Value | UI Control | Send Frequency | Dependencies |
---|---|---|---|---|---|---|---|---|---|
9 | Timer | Selector to set count-down timer. | 0–60 mins | SINT8 | Read/Write | Slider | On Change | Cooking Mode Bake, Convection, or Broil is selected. |
Once a set timer has run down, it will ring until the end-user shuts it off.
No. | Feature | Description | States | Data Type | Writability | Default Value | UI Control | Send Frequency | Dependencies |
---|---|---|---|---|---|---|---|---|---|
10 | Timer Ring | Ringer that goes off when timer reaches zero. Rings until shut off. |
|
Boolean | Read/Write | Silent | Menu | On Change | Timer must have run down to zero to ring. |
The table below lays out the data model. You can even use the No. and Feature column contents to number and name your attributes as you enter them in the Profile Editor.
No. | Feature | Description | States | Data Type | Writability | Default Value | UI Control | Send Frequency | Dependencies |
---|---|---|---|---|---|---|---|---|---|
1 | Start Button | Button that starts/stops the currently-set action. |
|
Boolean | Read/Write | Stop | Menu | On Change | Any Cooking Mode is selected. |
2 | Cooking Mode | Selector for setting cooking mode. | 1 = Bake 2 = Convection 3 = Broil 4 = Toast 5 = Warm 6 = Reheat |
SINT8 | Read/Write | Bake | Menu | On Change | Feature is available when unit is not cooking. |
3 | Number of Toast Slices | Toggle to set number of slices you plan to toast. | 1–3 4–6 |
Boolean | Read/Write | 1–3 | Menu | On Change | Cooking Mode Toast is selected. |
4 | Toast Shade | Selector for setting toast “doneness”. | Range from 1–10, increments of 1, where labels reflect:
1 = Defrost 3 = Light 5 = Medium 7 = Dark 10 = Very Dark |
SINT8 | Read/Write | Medium (5) | Slider | On Change | Cooking Mode Toast is selected. |
5 | Bagel | Toggle to set bagel function (adds time to toast cycle). |
|
Boolean | Read/Write | Off | Switch | On Change | Cooking Mode Toast is selected. |
6 | Degree Units | Toggle between °C and °F. | °C °F |
Boolean | Read/Write | °F | Menu | On Change | Feature is always available. |
7 | Current Temp | Display of current oven temperature. | 100–500 °F | SINT8 | Read-Only | None | Value | On Change | Cooking Mode Bake, Convection, or Broil is selected. |
8 | Set Temp | Selector to set target oven temperature. | 100–500 °F | SINT8 | Read/Write | 150 °F or 65 °C | Slider | On Start | Cooking Mode Bake or Convection is selected. |
9 | Timer | Selector to set count-down timer. | 0–60 mins | SINT8 | Read/Write | None | Slider | On Change | Cooking Mode Bake, Convection, or Broil is selected. |
10 | Timer Ring | Ringer that goes off when timer reaches zero. Rings until shut off. |
|
Boolean | Read/Write | Silent | Switch | On Change | Timer must have run down to zero to ring. |
Note that in addition to the information gathered above, before you can complete your device’s Profile and UI presentation using the Afero Profile Editor, you will need to specify a few more details, such as attribute value max size, temperature setting increments, and so on, depending on how your MCU code functions.