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. Battery Level is unique in that it combines information from two attributes. 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 an icon and label, and are drawn in a ring surrounding the main device icon in the 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 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 on 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 bar 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 New Control at the top of the window to open the Select Control Type window:

    UI Controls Definition Window

  2. Click each control type to see it in better detail. Use the following guidelines when selecting and defining a control:

    Menu - Use when the function has a small number of discrete value states. When you select this control you must also define:

    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 App UI and what the end-user will see. It should clearly identify the device characteristic that is being displayed or controlled.

    Primary Operation On/Off, only available for controls that support writing to an attribute. Turn this option On if you want this function to be in the central position in the control group’s hex. Only one of your UI controls can be set as Primary Operation within a given control group.
    Value Options

    In the mobile app, Value Options for a Menu control will be rendered as a set of buttons, of which only one 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 check the Running State box for a given Value Option, when the associated attribute has the checked value, your device will be marked as “Running” in the mobile App UI — this means the main hex for the device 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

    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 you associate a Value control with a GPIO attribute, the attribute’s Default Value will display, but there won’t be any way to change that. This is a Read-Only control type.

    When you select this control you must also define:

    Field Description
    Default Label This is the label that will be displayed in the App UI and what the end-user will see. It should clearly identify the device characteristic that is being displayed or controlled.

    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 App UI and what the end-user will see. It should clearly identify the device characteristic that is being displayed or controlled.
    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 Lumens, as you drag the slider, it changes from 25 Lumens to 40 Lumens, and so on.
    Min, Max All values must be integers and 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 to appear on the slider 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. Turn this option On if you want this function to be in the central position in the control group’s hex. Only one of your UI controls can be set as Primary Operation within a given control group.

    Temperature - Use when the function specifically requires the user set a temperature level. The Temperature control is a specialized Slider, with the value displayed in Celsius degrees.

    When you select this control you must also define:

    Field Description
    Default Label This is the label that will be displayed in the App UI and what the end-user will see. It should clearly identify the device characteristic that is being displayed or controlled.
    Unit Label This label describes the units that the slider is changing. The label is drawn over the control along with the current value of the slider.
    Min, Max, Step All values must be integers and 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 40°, Max as 100°, and Step as 5, there are 13 valid positions on the slider.
    Primary Operation On/Off. Turn this option On if you want this function to be in the central position in the control group’s hex. Only one of your UI controls can be set as Primary Operation within a given control group.

    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 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 values, which are displayed as percentages:

    Field Description
    Default Label This is the label that will be displayed in the App UI and what the end-user will see. It should clearly identify the device characteristic that is being displayed or controlled.
    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 25% Charge to 40% Charge, and so on. The % sign appears by default.
    Min, Max, Step 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.
    Primary Operation On/Off. Turn this option On if you want this function to be in the central position in the control group’s hex. Only one of your UI controls can be set as Primary Operation within a given control group.

    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 App UI and what the end-user will see. It should clearly identify the device characteristic that is being displayed or controlled.
    Primary Operation On/Off, only available for controls that support writing to an attribute. Turn this option On if you want this function to be in the central position in the control group’s hex. Only one of your UI controls can be set as Primary Operation within a given control group.
    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 check the Running State box for a given Value Option, when the associated attribute has the checked value, your device will be marked as “Running” in the mobile App UI — this means the main hex for the device 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 selecting control types, click the Save button in the upper-right corner of the window.

Define the UI Control Groups

UI Control Groups are solely organizational devices to group your controls in the UI in a way that increases usability. For example, if your device is a humidifier, you might want sliders that let the end-user set the temp and humidity in the same control group. The end-user could easily find all the relevant controls under a single group icon, improving ease-of use.

Remember! Every UI control must belong to at least one UI Control Group for the control to be displayed in the App UI. This means that even if you’re creating a single UI control, you must create a Control Group to contain it.

  1. Click UI Control Groups in the left-hand navigation bar to open the UI Control Groups definition window:

    Define the UI Control Groups

    In the center of the window, you’ll see a representation of the UI that will be created for your device in the mobile app. There is a central large hex surrounded by a ring of smaller circles. Two of those circles are gray: these are pre-built groups that provide access to Settings and Schedules for your device. The other circles – those with dotted outlines – represent groups you can add.

  2. Click any of the dotted circles in the icon ring to open the Group Labeling editor. It doesn’t matter which dotted circle you select; they’re equivalent, and in the actual App UI, the Control Group circles change positions.
  3. In the Group Labeling editor, type a string label for your group. This label should be brief and descriptive; it will be visible to the end-user. Next, click the Group Labeling Editor icon, and select an appropriate group icon from the panel that opens. Once you’ve made your edits, click anywhere to close the small Labeling editor window.
  4. Now that you’ve labeled your new group, you need to add the control(s). If the group you want to work on is not selected, click it once to select it – it will turn orange. Notice that a dashed-outline box appears below the icon ring. This box contains the text “Drop your controls here.” Notice also that the control(s) you defined earlier appear in the right-hand column of the window, under the label Available UI Controls. To add a control, simply drag from the column of available controls to the dotted box. Repeat for all the controls you want to add to the group.
  5. When you’re finished defining your groups, click Save.

Tips when creating control groups:

  • You are currently limited to a maximum of six UI Control Groups per device.
  • A given UI control can be included in multiple groups.
  • To remove a control from a group, drag it back to the Available Controls list.
  • To delete a group altogether, double-click it to open the Group Labeling editor window, then click the trash can icon in the upper-right.

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 Modulo.


  4. On 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: In the mobile app, go to the Preview Device > Settings screen, then tap the Remove Device button.