Once you’ve created the Attribute definition, you’re ready to design how the end-user views and controls your device from the Afero mobile app. There are three parts to this task:
Define the UI Control Groups - For usability, you will organize your UI controls into one or more control groups. The name of each group is displayed in a “ribbon” above the group’s controls in the mobile app UI. Control groups are organizational constructs and provide no additional functionality to the enclosed controls.
After you’ve defined the mobile app UI but before you move on to publishing your Profile, check out your UI using a virtual “preview” device in the Afero mobile app. Read more about this feature in Preview the Mobile App UI.
For each of your attributes, you will define “attribute options”, which specify how a control will display the attribute’s values. Follow the instructions below:
Click UI Controls in the left-hand Navigation pane to open the UI Controls definition window.
Field |
Description | Relevant UI Control(s) |
---|---|---|
Attribute | Click the Attribute drop-down menu and select your first attribute. You will repeat for each of your attributes, but if you know for a fact that you won’t be displaying an attribute value in the mobile app UI, then you can skip that attribute. | All Controls |
Default Label | This is the label that will be displayed in the mobile app UI; it is what the end-user will see. Type a label that clearly identifies the device characteristic that is being displayed or controlled. | All Controls |
Primary Operation |
On/Off checkbox, only available for write attributes that toggle between two values, and for controls that support writing to an attribute. Only one of your UI controls can be set as Primary Operation within a given device Profile. With this option selected, you’ll be able to control the attribute from the mobile app Home screen by double-tapping the device icon. Double-tapping will toggle between the attribute values. |
|
If you're defining both Value and Range Options (below) for the same attribute option, make the number of value options equal to the number of range steps. For example, if your Range is 0-50, with step size 10, make sure you have 6 Value Options defined. |
||
Value Options |
Select the Value Options checkbox before entering values. Note that Switch controls require that you select this checkbox and define two value options. To define the options, type the set of attribute values along with their corresponding labels in the table. In the mobile app, value options are often rendered as a menu of buttons, only one of which can be selected at any one time. Using the menu example, after the end-user taps any of the buttons, the associated attribute would be set to the corresponding value. If you select the Running State box for a given value option, when the associated attribute has the selected value, your device will be marked as “Running” in the mobile app UI — this means the Home screen device icon will be colored orange. Note that the value options you define will appear in the UI in the order listed in the table. They won't automatically reorder in the UI on the basis of value or label. This gives you complete control over presentation, regardless of underlying implementation. To reorder a defined value option, move your cursor to the left of the option to reveal the hand cursor and a textured handle. Click and hold the handle; without letting go, reposition the option, then let go to drop it into place. |
|
Range Options | Select the Range Options checkbox before entering values. Min, Max - All values must be numbers (can use decimals with Q15_16 data type). Min must be less than Max. The Min value is both the minimum limit of the slider range and the numeric label shown on the left. Max value is the maximum of the range, on the right. Number or Size of Steps - You must define the set points (steps) you want the control to use between Min and Max values. The way you do this depends on the underlying data type of the attribute:
Unit Label - This label describes the units that the control is displaying and is limited to eight characters. The label is drawn above the control adjacent to the current value of the slider. As a Slider example, if you define the label as “Lumens”, as you drag the slider, it changes from “25 Lumens” to “40 Lumens”, and so on. |
|
Now that you’ve defined all your attribute options, you can move on to assigning controls for your attributes.
Use this window to define which attribute option(s) will be displayed using which UI controls(s).
You can assign a single attribute option to multiple UI controls. Each control assigned will use the attribute option details that are relevant to that control.
If you haven’t defined any controls for your device yet, or to create a new one, click + Control to open the Select Control Type window. You’ll be able to select from the following controls (read below, step 2, for details).
Use the following guidelines when selecting and defining a control. Note that if you have not defined attribute options for a given attribute, that attribute won’t be available in the Attribute Option drop-down menu. You must do that by selecting the +Attribute Option button in the right-hand pane. Instructions for completing those fields are described above in Define the Attribute Options.
Menu - Use when the function has a small number of discrete value states and when each value state is short (can only be one line of text). When you select this control you must define the fields described below:
Field | Description |
---|---|
Attribute Option | Select the attribute option you want to associate with this Menu control. If it doesn’t appear in the drop-down menu, create a new one by selecting the +Attribute Option button in the right-hand pane. |
Control Type | Should be predefined with Menu control. |
View Style | Select Inline or Popup. Inline style exposes each menu item as a selectable button. Popup style shows the current value in a selectable circle, which expands to the full menu on tap. Select View Style Preview to see what that control will look like in the mobile app. |
Slider - Use when the attribute supports a range of values. The attribute associated with a Slider must have a data type with sufficient range to support the full range of values and will need to be defined as Output (GPIO) or Writeable (MCU).
When you select this control you must define the fields described below:
Field | Description |
---|---|
Attribute Option | Select the attribute option you want to associate with this Slider control. If it doesn’t appear in the drop-down menu, create a new one by selecting the +Attribute Option button in the right-hand pane. |
Control Type | Should be predefined with Slider control. |
View Style | Select Inline or Popup. Inline style displays the full slider. Popup style shows the current value in a selectable circle, which expands to a full vertically-oriented slider on tap. Select View Style Preview to see what that control will look like in the mobile app. |
Value - Use when you need to display status, as text. You will probably associate a Value control with an MCU attribute that has a data type of UTF8, which would allow your MCU to set the Value control display dynamically. If the attribute is read/write, the user will be able to change the value on tap.
When you select this control you must define the fields described below:
Field | Description |
---|---|
Attribute Option | Select the attribute option you want to associate with this Value control. If it doesn’t appear in the drop-down menu, create a new one by selecting the +Attribute Option button in the right-hand pane. |
Control Type | Should be predefined with Value control. |
View Style | Select Inline or Popup. Inline style displays the current value in a rectangle. Popup style shows the current value in a selectable circle. When tapped, both view styles can allow a selection by the end-user. Select View Style Preview to see what that control will look like in the mobile app. |
Temperature - Use when the function specifically requires the user set a temperature level. This control uses up to three attributes:
When you select this control you must define the fields described below:
Field | Description |
---|---|
Attribute Option | Select the attribute option you want to associate with this Temperature control. If it doesn’t appear in the drop-down menu, create a new one by selecting the +Attribute Option button in the right-hand pane. |
Control Type | Should be predefined with Temperature control. |
View Style | Select Inline or Popup. Inline style displays the full slider. Popup style shows the current value in a selectable circle, which expands to a full vertically-oriented slider on tap. Select View Style Preview to see what that control will look like in the mobile app. |
Additional Attributes | You can optionally set two more attributes if you want to show the end-user the current temperature and a heating “status” (as a number or a string):
|
Battery Level - Use when you need to display battery level to the end-user. This control is like the Slider but gets information from two attributes:
When you select this control you must define the fields described below:
Field | Description |
---|---|
Attribute Option | Select the attribute option you want to associate with this Battery Level control. If it doesn’t appear in the drop-down menu, create a new one by selecting the +Attribute Option button in the right-hand pane. |
Control Type | Should be predefined with Battery Level control. | View Style | Select Inline or Popup. Inline style displays the battery charge in a rectangular horizontal display. Popup style shows the current value in a selectable circle, which expands to a rectangular vertical display on tap. Select View Style Preview to see what that control will look like in the mobile app. |
Additional Attributes | You have the option to select an attribute (Boolean data type) that will indicate whether the device Is Charging. If set to “true”, a charging indicator will appear in the UI below the charge value. If set to “false”, no indicator will display in the UI. |
Switch - Use when you want to give the user two mutually-exclusive choices. When you select this control you must define the fields described below:
Field | Description |
---|---|
Attribute Option | Select the attribute option you want to associate with this Switch control. If it doesn’t appear in the drop-down menu, create a new one by selecting the +Attribute Option button in the right-hand pane. |
Control Type | Should be predefined with Switch control. |
View Style | Select Inline or Popup. Inline style displays the full switch; popup style shows the current value in a selectable circle that toggles the value on tap. Select View Style Preview to see what that control will look like in the mobile app. |
Text Box - Use the Text Box control for any of the following cases:
Field | Description |
---|---|
Attribute Option | Select the attribute option you want to associate with this Text Box control. If it doesn’t appear in the drop-down menu, create a new one by selecting the +Attribute Option button in the right-hand pane. |
Control Type | Should be predefined with Text Box control. |
View Style | Inline is the only View Style option for the Text Box control. Select View Style Preview to see what that control will look like in the mobile app. |
You are now ready to take your UI controls and decide how you want to present them to the end-user in the mobile app. You’ll do that in the UI Control Groups window; it simulates what the end-user will see in the mobile app, and provides some editing tools for you to use.
UI control “groups” are simply organizational devices, like folders, for logically grouping and presenting your controls to the end-user. If your device were a humidifier, you could group Temp and Humidity controls in a Climate group. The end-user could then easily find all their climate controls in a single group, improving ease-of use.
Every UI control must belong to at least one UI control group; orphan controls are not displayed in the mobile app UI. This means that even if you’re planning to use a single UI control, you must create a group and place your loner in it.
Read through and follow the steps below:
Click UI Control Groups in the left-hand Navigation pane to open the UI Control Groups definition window. We’ll look the example below before starting.
The left-hand pane, Define the UI Control Groups, displays a representation of the device mobile app UI (both shown below). At the top of both the mobile app and the Profile Editor is the “groups ribbon”; below are the controls for the selected group. Note that device Settings and Automation are selections only shown in the mobile app groups ribbon, not in the Profile Editor.
You’ll see two groups have been defined: LED and Button. These are shown at the top in the “groups ribbon”. The LED group is centered and highlighted, which means it’s “active” and ready for editing. Below the groups ribbon you’ll see that the LED control has been added to the LED group. In the right-hand pane, Available UI Controls, the Button control is shown as still “available” to the LED group.
You’ll define your groups in the groups ribbon:
It’s possible to preview the UI as you’re creating it, right in the Afero mobile app on your own device. To do this:
The Preview Device is a virtual device. Changing controls in the Preview UI will not affect the state of any actual device.
You can also exercise your attributes using the Attribute Tester, which opens after you click Preview UI.
To use the Attribute Tester, click any group icon to reveal the associated Attribute(s), type a desired value, and click Update. Changes will be visible in the mobile app UI.