Lab 2: Using the Afero Profile Editor

This lab will demonstrate:

  • How to create a simple profile for a Modulo development board.
  • How to configure specific behaviors from the available GPIO pins.
  • How to create and modify UI elements that present the device in the Afero mobile app.

This lab should take about an hour to complete, depending on how much experimentation you want to do.

Prerequisites

Before you begin this lab, you should have completed Lab 1: Afero Onboarding, so you have:

  • An account on the Afero Cloud.
  • A Modulo development board added to your account, connected and online.

Tools/Materials

For this lab, you will need:

  • Windows or Macintosh computer
  • iOS or Android mobile phone, running:
    • Android KitKat 4.4 (API Level 19), or
    • iOS release 9.3
  • Afero Modulo development board
  • Micro-USB cable to power the Modulo
  • USB power source (free USB port on a computer, AC wall adapter, or portable charger)

Setup

  1. Download the Afero Profile Editor application to your computer. You can download the Profile Editor installer from the following locations:
  2. Double-click the installer to run it. Installation is automatic and won’t require anything from you other than granting permission for the installer to run.

Steps

  1. Launch the Afero Profile Editor on your computer from the Start menu in Windows or from the Applications folder in macOS.
  2. On the sign-in window, sign in to the Afero Cloud with the same credentials you used in the Afero mobile app. This will allow you to send profiles from the Profile Editor to the devices connected to your Afero account.
  3. Click the + icon to create a new profile: Profile Editor Main Menu

    You will need to provide:

    • The type of Modulo board for which you’re creating a profile. Select Modulo-1 or Modulo-2, based on the board you have. (Hint: Modulo-1 boards have a square silver chip on the board with an Afero logo with the letters “af”. Modulo-2 boards will not have this silver Modulo-2 but will have “Modulo2” printed on the board.)
    • The name of the profile (this will also be called the “device type” since we’re defining what the device is going to be: toaster, mousetrap, etc.). Use any name you like, or something descriptive like AferoLab2.
    • The location of the folder where you want to save the profile (by default this should be in your Documents folder, or you can click Select to put the profile in a folder of your choosing.) By default, the Profile Editor will create a folder using the Profile Name to store the files created.
    • Click Create to create your new profile and start customizing it.New Profile
  4. A navigation bar, containing a list of options, runs vertically along the left side of the window. We’ll run through all of these items to produce a profile:
    • Device Type
    • Attributes
    • UI Controls
    • UI Control Groups
    • Publish
  5. Device Type Window
    1. In the nav bar at the left, Device Type will be selected by default. On this window much of the information will be populated from the New Profile dialog you just completed.
      Device Type Window
    2. Click the Select button to the right of Device Icon. The icon you select will be the icon displayed for your device on the Afero mobile app. Select an icon from the provided list.
      Device Type Done
    3. To save your settings and advance, click Save in the upper-right corner of the Profile Editor window.
  6. Attributes Window

    In the nav bar at the left, click Attributes. The Attributes window is where we define the pieces of data that are synced between the device, the Afero Cloud, and the Afero mobile app.

    We’ll use the term “attribute” a lot from here on. The easiest way to think about an attribute is that it’s the smallest useful piece of data that can be communicated between the device and the cloud.

    Good attribute examples: Current Temperature, Target Temperature, Switch State, Altitude, Direction, Sensor Value, Light Level, Error Code, etc.

    Attributes should not be constantly-changing variables, since there is overhead in sending that data to the Afero Cloud. Avoid “live” updates, such as: GPS Position, Accelerometer, Velocity, RPM. Instead send point-in-time snapshots of such data.


    1. At the top of the Attributes window you can select an MCU protocol; we support MCU attachment via SPI or UART, which we’ll get to in a later lab. For now, leave that as No MCU and we’ll configure a couple of GPIO pins to tinker with.
    2. Turn on the switch for Unnamed Attribute I/O 0. GPIO 0 on the Modulo board is connected to the on-board LED, so let’s define this GPIO as an output:
      • Attribute Name: LED
      • Default Logic Level: 0
      • Operation Mode: Output (leave all the Options unchecked for now)
      • Active: Low (1=Low)
      LED I/0 0
    3. Turn on the switch for Unnamed Attribute I/O 3. GPIO 3 on the Modulo board is connected to the on-board button, so let’s define this GPIO as an input:
      • Attribute Name: Button
      • Operation Mode: Input
      • Options: Pull Up and Is Toggle
      • Debounce Time: 0
      • Active: Low (1=LOW)

      Setting the button as Is Toggle will let us turn that GPIO on and off with each button press. Otherwise, the button would only register as “on” when the button was pressed and held.Attribute 3

    4. Click Save in the upper-right corner of the window.
  7. UI Controls Window

    Now that we’ve defined the attributes in our profile, we can create UI controls that will display the state of those attributes in the mobile app.

    1. In the nav bar at the left, click UI Controls, then click + New Control at the top of the window.
    2. We provide a toolbox of simple UI elements you can use to display attributes in the mobile app. For the LED, select Switch, then click Add.UI Controls
      • Select LED under the Attribute drop-down.
      • The Default Label is a text description that is shown above the UI Control in the app to describe what the control does. Call this one My LED or whatever you like, so you can identify where it shows up in the mobile app.
      • Select the Primary Operation checkbox. This checkbox is used in the mobile UI to indicate that the device is performing its defined task. When the profile’s “primary operation” is running, the device’s icon will turn orange so you can easily tell the device is doing something.
      • The Value Options section allows you to map attribute values to meaningful descriptions of the values. For example, the GPIO pin attached to our LED only has two states: 1 (on) and 0 (off). In general, If we don’t put anything in the Value Options for a control, the “raw” attribute value will be displayed, which may not be intuitive to the mobile user. to define the states of the switch.

        For our Switch UI element, however, we must provide two Value Options with human-readable labels describing each state:

        Value Label Running State
        0 Off Unchecked
        1 On Checked

        Running State is used with Primary Operation to indicate when the device is actively performing its main task.


    3. Click + New Control to create a new UI control for the button: UI Controls
      • Select Value as the UI element type, which is a simple text box we can use to display the button state.
      • Define this UI Control as follows:
        • Attribute: Button
        • Default Label: Button State
        • Value Options, define two: 0 = toggled off; 1 = toggled on
    4. Click Save in the upper-right corner.
  8. UI Control Groups Window

    Groups allow us to organize UI elements into logical groups in separate menu items. When you interacted with the Modulo earlier, there was a menu for LED that contained the LED control buttons, and another menu for Button that displayed the button state. Those menus are defined here in UI Control Groups.

    1. In the nav bar, click UI Control Groups. A mockup of the Afero mobile app is displayed.
    2. Click an empty circle, then click the small icon next to the group name and give your group a name and icon.
    3. From here, you can drag and drop any UI Controls from the right side of the window into the area under the menu. Drag both the LED switch and the button text box into the area under the menu. UI Control Groups
    4. Click Save in the upper-right of the window.
  9. Publish Window

    The Publish window is where you can deliver this profile over-the-air to any of the devices connected to your account.

    1. In the nav bar, click Publish. Your Modulo will appear in the device list after a brief pause:
      Publish Window
    2. Ensure the device is connected to power and online. The device Status will be orange with a signal strength measurement if the device is online, as shown in the example; or will report “Offline” if the device is not online.
    3. Select the checkbox to the left of the Modulo you want to publish this profile to.
    4. Click Publish!

    If you’re watching the mobile app when this happens, you’ll see the device get a short over-the-air software update and then reboot. When the device reboots, the icon and menus will change to the icons, labels, and UI elements you put in your profile. Verify that the LED switch works properly and that the text box for the button changes when you press the button on the Modulo.

Experiment

Now that you have a basic working profile, if there is remaining time in the lab session, go back and modify your profile in the ways shown below. Publish your profile after each change and observe the difference in the mobile UI and the behavior of the Modulo board:

  1. Control LED Blinking
    1. Edit the Attribute for GPIO 0 and set the Pulse option.
    2. Use 500ms active/500ms inactive.
    3. Edit the UI Control for the LED and change it from Switch to Slider.
    4. Set the slider range from 0-10 step 1.
    5. Publish your profile.

    Instead of turning the LED on and off, now the Modulo will blink the LED (500ms on, 500ms off) as many times as you set the attribute value to. While the LED is blinking, you can change the slider value to 0 and the Modulo will stop blinking.

  2. Adjust PWM Cycle
    1. Edit the Attribute for GPIO 0 and set the PWM option.
    2. Leave the PWM Frequency at its default.
    3. Edit the UI Control for the LED and change the Slider range to 0-100 step 10.
    4. Publish your profile.

    The attribute value (set by the slider) now sets the PWM duty cycle from 0-100%. Adjusting this PWM cycle will alter the brightness of the LED from off (0%) to full on (100%).

  3. Use a Menu to Limit Setting Options
    1. Edit the UI Control for the LED and change it from Slider to Menu.
    2. Check the Primary Operation checkbox.
    3. Add the following Value Options to the UI Control (using the + Value Option button to add more entries):
      Value Label Running State
      0 Off Unchecked
      25 Low Checked
      50 Medium Checked
      75 High Checked
      100 Full Checked
    4. Publish your profile.

    Notice that you can use multiple Menu options to set specific values for the attribute that you control instead of letting the user set an arbitrary value with the slider.

Extra Credit

  1. Menu vs. Slider
    1. Change the GPIO 0 attribute back to Pulse.
    2. Instead of a slider for the UI Control, use a Menu with several Value Options to allow the user to request 0, 5, 10, 15, or 20 pulses.
  2. Count
    1. Edit the attribute for GPIO 3 and change it from Is Toggle to Count.
    2. Then edit the UI Control for the Button and remove the two Value Options from the control.
    3. Publish your profile.

    Press the button on the Modulo repeatedly and note that the button state keeps a running count of how many times you’ve pressed the button.

  3. Map Value Options to Labels
    1. Edit the UI Control for the Button and add a few Value Option entries for the control. Use the examples below, or something similar of your own choosing, to see how attribute values map to human-readable labels:
      Value Label
      0 Button Not Pressed
      6 Half Dozen
      12 Dozen
      13 Baker's Dozen
    2. Publish your profile.

    Press the button every second or so for at least 13 times. Note that as you press the button, the raw value of the attribute is displayed in the UI unless there’s a specific Value Option entry for that value. This way you can map specific values to more meaningful terms if you need to.

Practical Uses

You can see that for simple control or sensing tasks, the Modulo can be used on its own. without an attached MCU. Using just GPIO attributes and various hardware options you can create simple sensors or controllers:

  • Use a magnet and a Hall effect sensor and a Count attribute to count the number of times a door has been opened or closed.
  • Use two GPIOs with Pulse attributes connected to a motor controller to turn a simple motor or servo in either direction.
  • Use an output attribute with Toggle connected to a relay to control a larger electric device such as a lamp or fan.
  • Use an output attribute with PWM connected to a small vibration motor (like a pager or cellphone vibration motor) to “buzz” the device at different pitches for different haptic notifications.
  • Use an input GPIO with Toggle connected to a piece of copper tape, and another piece of copper tape connected to the Ground pin of the Modulo, and use the two pieces of tape as a water sensor under a sink or water tank.

For more complex tasks, the Modulo can be connected to an MCU and then it can be used to communicate arbitrary data between the MCU and the Afero Cloud. The next lab will expand your new knowledge of the Afero Profile Editor as we connect a microcontroller to the Afero Cloud.