Tutorial 2: Creating a Device Profile

Before you start, we assume that you’ve already run through Tutorial 1: Linking Modulo. If not, please start there.

  1. If you haven’t already, download the Afero Profile Editor, for Windows or macOS. Open and sign in to the Profile Editor. The Startup window appears:

    Startup Window
  2. For the purposes of this tutorial, we’re going to save you some typing by providing a pre-configured Modulo project.
    1. Download the appropriate Sample Project from the Tools > Sample Projects system menu. Select “Modulo-1” or “Modulo-2”. (Both Modulo projects, and more, are available from http://github.com/aferodeveloper/APE-Project-Profiles.)
    2. Double-click the downloaded .zip file to uncompress it to your computer.
    3. In the Afero Profile Editor Startup window, select the Open button, navigate to the directory where you unzipped the project, and select the directory to open the project.
  3. Once the project is open, click Device Type in the Navigation pane in the left of the window, to be sure we’re all starting in the same view. Your window should look something like this: Device Type Pane

    Notice the Module Type of the Profile is specified right at the top of the pane (in the example, we’re working with a Modulo-2.) This module type was specified in the pre-built Profile you downloaded; when creating a Profile from scratch, you must specify the module type right from the beginning. Doing so is the first step in the New Profile window. It’s critical that the module type in the Profile match the hardware you’re using in your project!

    In the Device Type view, you can set the device name, type a detailed device description, and set the device icon. Of these items, only the icon will be visible to the end-user. Notice the Preview panel on the right of the view – it shows the selected device icon as it will appear in the mobile app.

    Since we’re working with a pre-configured Profile, you don’t need to make any changes, but if you like, feel free to do so. When you’re finished, click Save to save any changes you might have made.

  4. Click Attributes in the left-hand Navigation pane. You’ll see that the four Modulo GPIO pins are listed. Only two GPIO pins are needed for this project, pins 0 and 3. Click the On/Off switch to ON for these two pins; you’ll see them highlighted in the right-hand Preview pane:

    Preview Pane
  5. For this project, we’ve defined two attributes: one for GPIO 0, which is connected to the LED on the Modulo; and one for GPIO 3, which is tied to the pushbutton. We’ll take a detailed look at the attributes now. Note that selected values are shown in white letters on an orange background.
    1. Click LED Attribute, the attribute name for GPIO 0, to open its detailed view:

      Attribute Definitions
      • Attribute Name is a required field for all attributes. We’ve named this one LED Attribute but you can change it in this field.
      • To control the LED from the mobile app, Operation Mode must be Output. This is because Outputs are Read/Write, and sending a command from the mobile app requires writing to an attribute.
      • GPIO 0 is given a Default Logic Level of 0, which sets the default state of the LED to OFF.
      • Leave both Options, PWM (pulse-width modulation) and Pulse, deselected.
      • Change the Active selector set to Low. Because the cathode of the LED is connected to GPIO 0, the LED turns on when the pin goes Low.
      • Don’t select any of the Bind to Attributes buttons.
    2. Click Button Attribute, the attribute name for GPIO 3, to open its detailed view:

      Attribute Definitions
      • Attribute Name is a required field for all attributes. We’ve named this one Button Attribute but you can change it here.
      • Leave GPIO3 Operation Mode set to Input. This will display the state of the button when pressed in the mobile app.
      • Change the Active setting to Low. When pressed, the button connects GPIO 3 to ground so the pin is considered active when it goes Low.
      • The Pull Up setting is required for to keep the GPIO pin inactive when the button is not pressed.
      • With Is Toggle set, the status displayed by the mobile app will switch with every momentary button push. If Is Toggle is not set, the state displayed will always reflect the current button state.
      • Leave the Debounce Time set to 0, the Active selector set to High, and don’t select any of the Bind to Attributes buttons.
    3. Click Save when you are finished defining project attributes.
  6. To move on to defining the mobile app UI for this project, click UI Controls in the left-hand Navigation pane.

    You will probably not be surprised to find that two UI controls have been defined, since our project uses two attributes. It’s common (though not a rule) to have one UI control for every attribute.

    There are several types of UI Controls available, but in this project we will use the Menu control for both.

    Menu Controls
    1. Click the first attribute, LED Attribute (I/O 0): Menu, to open it for editing.

      LED Control
      • The LED control is selected as Primary Operation, which means you can control the LED from the Home screen of the mobile app by double-tapping the device icon.
      • For View Style, we have selected INLINE, which means all menu options will be shown. (Popup View Style means the end-user must tap the control to reveal all menu options.) You can see an example in the pane on the right (shown in the screenshot above).
      • Note that two Value Options have been defined. These present the two different states the on-board LED can have: 1 is On, 0 is Off. You can edit the labels if you want, but keep the values as defined.
      • Check the Running State box next to the On state for the LED. This will change the color of the device in the mobile app when the LED is on.
    2. Click Button Attribute (I/O 3): Menu to open it.

      This control happens to have the same value options as the LED control, but is not set as the Primary Operation.

      Button Attribute

      Notice that we've selected the POPUP View Style.

    3. Click Save when you are finished defining UI controls.
  7. Click UI Control Groups in the left-hand Navigation pane to group your controls.

    The left-hand pane, Define the UI Control Groups, displays a representation of the device mobile app UI. 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 is a selection only shown in the mobile app groups ribbon, not in the Profile Editor.

    1. We’ve already set up two groups, shown in the groups ribbon and labeled LED and Button. (We’ve already created groups for this project, but if we hadn’t, you would clickto create a new group.)

    2. On the right, you’ll see all the controls you defined on the UI Controls window, identified by their Default Label. These are the controls available for grouping.
    3. Click the group labeled LED to make it active and ready for editing. The group will be highlighted in orange:

      UI Control Group

      Below the selected group, you’ll see the LED menu control. We’ve already moved the LED menu into the LED group, but if we hadn’t, you would add a control by dragging it from the Available UI Controls pane on the right into the controls display on the left, below the groups ribbon.

    4. To remove a control from a group, simply drag it back to the Available UI Controls pane.

      A control can appear in multiple groups, but must appear in at least one group or it won’t appear at all in the mobile app UI. That means that even if you have just one UI control, you’ll need to create a UI control group to contain it.

    5. Click Save when you are finished defining UI control groups.
  8. Now that your device Profile is complete, click Publish in the left-hand Navigation pane to install it on your Modulo.

    If you intend to perform the next steps yourself (and you should!), you’ll need to set up some hardware:

    • You should have your Modulo connected to USB (for power only at this time).
    • You should have the Afero app running and open on your smartphone.

    Before we get started, take a look at the Publish window:

    • This window shows you all the developer devices on your account. For each available device, the Status displays the Bluetooth signal strength, e.g. -40dBm, in an orange badge.
    • The Device Activity log will show all attribute-related communication between device and service in real-time. It is initially populated by the latest cached values from the Cloud.

    OK, time to Publish:

    1. Select the device(s) you want to update by selecting the corresponding orange checkbox(es).
    2. Click Publish.
    3. The update can take up to one minute. You’ll see an update message in the Device Activity and the SW Version will change once the update has completed.
  9. Try out the new mobile app UI for your device! Notice that the LED is on, which is indicated on the Home screen. Because it’s the Primary Operation defined with a Boolean attribute, tapping the large device icon on the Home screen will toggle the LED on and off.

    Mobile App

    You should now be able to control the Modulo LED using the LED buttons on your smartphone, and the pushbutton on the Modulo board should toggle the On/Off Button control in the mobile app UI.