Define the Mobile App UI

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 two parts to this task:

  • Define the UI Controls - Each UI control corresponds to a specific attribute, except for Battery Level and Temperature. Battery Level and Temperature are unique in that they combine information from more than one attribute. The UI control may provide only a graphic representation of the attribute state (for a Read-Only attribute), or may additionally act as an active control to allow the end-user to set the value of an attribute.
  • Define the UI Control Groups - You can organize one or more UI controls into groups. Groups have a name and are displayed in a “groups 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.

    Every UI control must belong to at least one group; unenclosed controls will not be displayed in the mobile app UI.


After you’ve defined the mobile app UI but before you move on to publishing your profile, check out your UI using a virtual device in the Afero mobile app. Read more about this feature in Preview the Mobile App UI.

Define the UI Controls

Use this window to map each of your device’s attributes to a control displayed to the end-user.

  1. Click UI Controls in the left-hand Navigation pane to open the UI Controls definition window. 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):

  2. Use the following guidelines when selecting and defining a control:

    Field Description
    Attribute Select the attribute you want to associate with this Menu control.
    Control Type

    Should be predefined with Menu control.

    Default Label

    This is the label that will be displayed in the mobile app UI and what the end-user will see. It should clearly identify the device characteristic that is being displayed or controlled.

    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.

    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 the attribute value.

    Value Options

    In the mobile app, Value Options for a Menu control will be rendered as a set of buttons, only one of which can be selected at any one time. Provide the set of desired attribute values, along with corresponding button labels. When the end-user taps any of the buttons, the associated attribute is 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.

    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.Moving Value Options

     

    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 also define:

    Field Description
    Default Label This is the label that will be displayed in the mobile app UI and what the end-user will see. It should clearly identify the device characteristic that is being displayed or controlled.
    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.
    Unit Label This label describes the units that the slider is changing and is limited to eight characters. The label is drawn above the control adjacent to the current value of the slider. For example, if you define the label as "Lumens", as you drag the slider, it changes from "25 Lumens" to "40 Lumens", and so on.
    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 slider to use between Min and Max values. The way you do this depends on the underlying data type of the attribute:
    • If your attribute is a fixed-point integer, you will set the number of steps. The size of each step will be calculated for you.
    • For all other data types, you must type the minimum granularity of the slider. For example, if you define Min as 0, Max as 1000, and Step as 2, there are 500 valid positions on the slider.
    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 the attribute value.

     

    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 also define:

    Field Description
    Default Label This is the label that will be displayed in the mobile app UI and what the end-user will see. It should clearly identify the device characteristic that is being displayed or controlled.
    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.

    Value Options

    In the mobile app, Value Options for a Value control will be rendered in a rectangle that pops open on tap to reveal the options, only one of which can be selected at any one time. Provide the set of desired attribute values, along with corresponding labels. When the end-user taps any of the labels, the associated attribute is set to the corresponding value and the popup collapses.

    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 icon for the device will be colored orange and “ON” will display on the mobile app Home screen.

    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.Moving Value Options

     

    Temperature - Use when the function specifically requires the user set a temperature level. This control uses up to three attributes:

    • (Required) The first attribute is read/write. It represents the value of a thermostat set point, or Target Temperature, which the user will set using the specialized slider.
    • (Optional) The second represents the Current Temperature, so is a read-only value displayed on a scale, which you define in Celsius degrees.
    • (Optional) The last attribute represents the Current Status; it is read-only and can be used to display the status of a heating/cooling device, such information as “Heating” or “Cooling”. Current status can also display a numeric value.

    When you select this control you must also define:

    Field Description
    Default Label This is the label that will be displayed in the mobile app UI and what the end-user will see. It should clearly identify the device characteristic that is being displayed or controlled.
    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.
    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 the attribute value.

    Target Temp Range: Min, Max, Size of Steps All values must be in °C and integers; 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. Step is the minimum granularity of the slider. For example, if you define Min as 5°C, Max as 35°C, and Step as 1, there will be 31 valid positions on the slider.
    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):
    • Current Temperature - Select a defined attribute that will report the current temperature, then define the Current Temp Range: Min, Max, and Size of Steps.
    • Current Status - Select a defined attribute that will report the thermostat “status”, which will appear next to the slider (below for Inline; on the left for Popup).

     

    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:

    • One attribute is a range attribute, intended to display the battery charge level as a percentage.
    • The second attribute is a Boolean attribute, used as the Is Charging indicator. A value of “true” is used to indicate active charging. This is a Read-Only control type.

    When you select this control you must also define the following:

    Field Description
    Default Label This is the label that will be displayed in the mobile app UI and what the end-user will see. It should clearly identify the device characteristic that is being displayed or controlled.
    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.
    Unit Label This label describes the units that the slider is changing. The label is drawn over the control with the current value of the slider. For example, if you define the label as “Charge”, as you drag the slider, it changes from, say, “25% Charge” to “40% Charge”, and so on. The % sign appears by default. Limited to eight characters.
    Min, Max, Size of Steps 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. Size of steps is the minimum granularity of the slider.
    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 also define the following values:

    Field Description
    Default Label This is the label that will be displayed in the mobile app UI and what the end-user will see. It should clearly identify the device characteristic that is being displayed or controlled.
    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.

    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 the attribute value.

    Value Options

    In the mobile app, Value Options for a Switch control will be rendered as a toggle switch between two values, of which only one can be selected at any given time. You must provide the two desired attribute values, along with corresponding labels. The first entry is used to define the value and label for the ON state; the second entry is used to define the value and label for the OFF state.

    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.

    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.Moving Value Options

     

    Text Box - Use the Text Box control for any of the following cases:

    • To present menu options that have labels running more than one line. (Menu control options must fit on one line.) The attribute must be Read/Write.
    • To hold a multi-line block of static text. Attribute should be Read-Only. This is useful for product or feature descriptions.
    • To hold a multi-line block of text that the end-user can edit. This is useful when, for example, you have a sign with a display message that changes. You can use the mobile app to update this message text.

    When you select this control you must also define the following:

    Field Description
    Default Label This is the label that will be displayed in the mobile app UI and what the end-user will see. It should clearly identify the device characteristic that is being displayed or controlled.
    View Style Inline is the only View Style option for the Text Box control.
    Value Options

    In the mobile app, the label(s) you define for a Text Box control will be rendered in a rectangle. If the attribute is Read-Write, the end-user will be able to edit the text.

    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.

    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.Moving Value Options

  3. When you are finished defining the UI controls, click Save in the upper-right corner of the window.

Define the UI Control Groups

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:

  1. 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.Define the UI Control Groups

  2. You’ll define your groups in the groups ribbon:

    1. To add a group, click.
    2. To edit a group name, click the name to make the group active and editable, then make your text edits.
    3. To reposition a group in the ribbon, click the group to make it active, then hover your cursor to the left of the group name (outlined in orange) to reveal the textured move handlethen drag & drop the group – left or right – to the new position.
    4. To delete a group, click the group to make it active, then hover your cursor to the right of the group name to reveal the trash iconthen click the trash.
  3. Now that you’ve defined your control groups, you can organize them as you’d like them to appear to the end-user on the mobile app screen. Remember you can include a given UI control in multiple groups.

    1. In the groups ribbon, click the group you want to work on. If you need to scroll the groups ribbon, hover your cursor over the line separating the groups ribbon from controls display and drag the horizontal scroll bar that appears under your cursor. The group you select will center and be outlined in orange. The group is active and ready to receive controls.
    2. The controls you defined in the UI Controls window appear in the right-hand column of the window, under the heading Available UI Controls. To add a control to the active group, simply drag it from the column of available controls to the controls display below the groups ribbon. Repeat for all the controls you want to add to the active group.
    3. To reposition a control within the group, simply drag & drop it.
    4. To remove a control from a group, drag it back to the Available UI Controls pane.
  4. To quickly switch a control’s View Style or remove it from the group, hover your cursor to the right of a control that’s been added to a group, then click the pencil icon that appears. Editing tools open:
  5. When you’re finished defining your groups, click Save.

Preview the Mobile App UI

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:

  1. Click the Preview UI button in the upper-left of the window.
  2. Check the mobile app UI. You will see that a new device icon has been added to your devices: this is the Preview Device.
  3. The Preview Device is a virtual device. Changing controls in the Preview UI will not affect the state of any actual device.


  4. In the mobile app, tap the Preview Device to open it and see the UI that you defined. You can test the controls, see changes to the Primary Operation, Running State, and so on.
  5. If you make changes in the Profile Editor, click the Preview UI button again to update the mobile app UI; you don’t need to Save to see changes.
  6. You can also exercise your attributes using the Attribute Tester, which opens after you click Preview UI.

    Using the Attribute Tester

    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.

  7. When you’re done testing your UI, remove the Preview Device by doing this: In the mobile app, go to the Preview Device > Settings screen, then tap the Remove Device button.