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.
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.
For this lab, you will need:
- Windows or Macintosh computer
- iOS or Android smartphone, 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)
- Download the Afero Profile Editor application to your computer. You can download the Profile Editor installer from the following locations:
- 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.
- Launch the Afero Profile Editor on your computer from the Start menu in Windows or from the Applications folder in macOS.
- 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.
- Click Newto create a new Profile:
On the dialog box that opens, 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.
- A Navigation pane, 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
- UI Controls
- UI Control Groups
Device Type Window
- In the Navigation pane 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.
- 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. In the lab examples, we’ve selected a mousetrap.
- To save your settings, click Save in the upper-right corner of the Profile Editor window.
In the Navigation pane 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.
- Turn on the Unnamed Attribute I/O 0 switch (on the right). 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
- Operation Mode: Output
- Default Logic Level: 0
- Operation Mode: Output (leave all the Options deselected for now)
- Active: Low (1=Low)
- 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.
- Click Save in the upper-right corner of the window.
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.
- In the Navigation pane at the left, click UI Controls, then click + Control at the top of the window.
- 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.
- 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.
- For View Style, select Inline. 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. Popup is good if you have a lot of controls because it’s more compact.
- 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.
Running State is used with Primary Operation to indicate when the device is actively performing its main task.
For our Switch UI element we must provide two Value Options with human-readable labels describing each state, defined as follows:
- 0 = off
- 1 = on, with Running State selected
- Click + Control to create a new UI control for the button:
- 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
- View Style: Inline
- Value Options, define two: 0 = toggled off; 1 = toggled on
- Click Save in the upper-right corner.
UI Control Groups Window
Groups allow us to organize UI controls into logical groups. When you interacted with the Modulo earlier, there was a control for LED that contained the LED control buttons (menu), and another control for Button that displayed the button state. The layout – groupings – for those controls are defined here in UI Control Groups.
- In the Navigation pane, click UI Control Groups. A mockup of the Afero mobile app is displayed. Along the top there is the “groups ribbon”. It’s empty to start so we’ll clickto create the first group. Click the “New Group” name and type “LED”. This will be the group that holds the LED control.
- From the right, under Available UI Controls, drag & drop the LED switch to the area under the groups ribbon. Create another group named “Button” and drag the Button State control into the area under the groups ribbon.
- Click the Preview UI button to see how the UI looks on your smartphone. Select the Preview Device from the mobile app Swipe left in the groups ribbon to switch from Settings, LED, and Button controls:
- Back in the Profile Editor’s UI Controls Group window, click Save in the upper-right of the window.
The Publish window is where you can deliver this Profile over-the-air to any of the devices connected to your account.
- In the Navigation pane, click Publish. Your Modulo will appear in the device list after a brief pause:
- 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.
- Select the checkbox to the left of the Modulo you want to publish this Profile to.
- 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.
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:
- Control LED Blinking
- Edit the Attribute for GPIO 0 and set the Pulse option.
- Use 500ms active/500ms inactive.
- Edit the UI Control for the LED and change it from Switch to Slider.
- Set the slider range from 0-10 step 1.
- 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.
- Adjust PWM Cycle
- Edit the Attribute for GPIO 0 and set the PWM option.
- Leave the PWM Frequency at its default.
- Edit the UI Control for the LED and change the Slider range to 0-100 step 10.
- 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%).
- Use a Menu to Limit Setting Options
- Edit the UI Control for the LED and change it from Slider to Menu.
- Select the Primary Operation checkbox.
- Add the following Value Options to the UI Control (using the + Value Option button to add more entries):
- 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.
- Menu vs. Slider
- Change the GPIO 0 attribute back to Pulse.
- 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.
- Edit the attribute for GPIO 3 and change it from Is Toggle to Count.
- Then edit the UI Control for the Button and remove the two Value Options from the control.
- 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.
- Map Value Options to Labels
- 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:
||Button Not Pressed
- 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.
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 phone 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.