MangOH Red Launch and Legato Framework

Sierra Wireless has just launched their newest offering in the IoT space. The MangOH Red is a smaller and more compact board than it's older brother the MangOH Green. Aimed at a being used in an end product rather than the development, the board resembles the footprint of the Raspberry Pi. With onboard Bluetooth and WiFi, the MangOH Red is ready to be used in any IoT application. Still standard are the CF3 modules with their on chip cellular connectivity and GLONASS and GPS positioning capabilities. The CF3 module cellular options include 3G, 4G LTE and LTE-m1/NB-IoT modules.

MangOH Hardware

The MangOH Red has a notably different hardware setup from the MangOH Green. Being more compact, the MangOH Red has one CF3 slot and one IoT expansion card slot. Because the MangOH Red has onboard bluetooth and WiFi there is an onboard antenna as well as  u.fl connector to allow for an external antenna to be attached for these services. The other previously supported antenna connections (cellular, Glonass and diversity) are all still provided. No longer provided onboard is ethernet, RS323 and the arduino shield connector. For the users who may miss these, they are still available via the IoT expansion cards. The debugging interface has been made simple with a micro USB connector.

New to the MangOH Red are pressure, light and temperature sensors. These new sensors along with the IMU gives the board spacial awareness right out of the box. Also new the the MangOH Red is a Raspberry Pi Hat connector. This allows for the more complex and capable boards designed for use with the Raspberry Pi to be used with the MangOH Red.  Built in battery charging and monitoring circuitry allow for a rechargeable battery to be added. With this setup Sierra Wireless has made a product that a true IoT board that is ready to be deployed anywhere monitoring is needed.

Unboxing and Setup

The MangOH Red comes in a neatly packed box with everything you need to get started. One big improvement from the MangOH Green is the inclusion of a universally compatible sim card. With 100MB of data this is enough to get anyone started with the demos and basic applications. Setting up the MangOH Red is quick and easy The WP module is slipped into the module holder and the cover snapped closed. After connecting the cellular antenna all that is left to do is connect the USB cables. These are used to provide power and access to the console. While it is possible to provide power from either USB cable, access to both the console and CF3 module via SSH is useful.

The documentation for the MangOH Red has been revised and updated from the MangOH Green. This new revision has produced a clearer and more concise set of documents. The initial setup time, from out of the box to getting the demos running has been reduced with the aid of better step by step instructions. The “MangOH Red Setup Guide” is especially helpful in getting the system setup and performing its first set of data logging to the cloud.

After everything has been connected the hardware is ready to be used. Upon powering up the system, you will need to work through the getting started guide. This will setup your environment on your PC as well as install the latest applications on the MangOH Red. The only issue encountered was a change in RSA key which the command line explained how to resolve.

Once done, completing the installation is easy and smooth. The rest of the getting started guide follows the same well explained step by step paradigm. As the rest of the setup and getting started is self explanatory we’ll move to the software structure of Legato used by the MangOH

MangOH Software - Basic Structure

The MangOH boards use the Legato framework as the basis for their software. The Legato framework provides a lot of APIs take care of the simple as well as to simplify the more complex tasks that can be performed with the MangOH boards. The framework, while well thought out and logically ordered, can take some time to get used to for those just starting out. The basic file structure as well as the chain between variables and peripherals will be explained below.

Basic organization of the Legato file structure

The first folder (application folder) acts as a container for the application and is often named with the name of the application. This folder contains the application definition file as well as the component folders. The application definition file (adef) allows the compiler to know what components are used in the application as well as what peripherals are required. The adef also binds external hardware or devices to internally used variables.

Application Definition File (ADEF)

Using a very simple example we will look at the heartbeatRed application. In this application which uses very few resources and has only one component the  the adef looks as shown below. Starting from the top, the executables defines what code should be run in this application. In this snippet the heartbeatComponent is what we would like the application to run. Since a component can be run with multiple instances each instance is given a unique name. In the code below there is only one instance named heartbeat. Now that the instance has been named, we let the system know under processes that we would like this instance to be run. To do this we place the instance name heartbeat in the subsection run. This will start the application when the system loads (provided we have put on line 3 “start: auto” and not “start: manual”). If it is set to manual, you will need to do: app start heartbeatRed. Lastly there is the bindings section. This links the external devices (ports, files, etc.) to variables the software can use. In the code below we would like to be able to control pin 34, this is the onboard LED. To accomplish this the variable mangoh_led which is found in the heartbeatComponent and is part of the heartbeat executable is connected to the  gpioService. This service through the Legato GPIO service  then connects the variable to the specified pin.

sandboxed: true version: 1.0.0 start: auto executables: {    heartbeat = ( heartbeatComponent ) } processes: {    envVars:    {        LE_LOG_LEVEL = INFO    }    run:    {        ( heartbeat )    }    faultAction: restart } bindings: {    heartbeat.heartbeatComponent.mangoh_button -> gpioExpanderServiceRed.mangoh_gpioExpPin14    heartbeat.heartbeatComponent.mangoh_led -> gpioService.le_gpioPin34 }

heartbeatRed adef file as found in the heartbeatRed application folder

Component Definition File (CDEF)

Now that we have shown the compiler what components are to be included as well as what devices are needed and provided a handle for components to access them, let's look at the file that explains how the component is put together. The component definition file (cdef) explains how the various files are integrated as well as what source files the component needs to be correctly compiled.

As mentioned in the adef, we would like to have access to peripherals and as such we have linked a variable to them in the adef. In the cdef we now connect them to an API to allow us to manipulate and interact with these hardware or service components. This is done in the requires section by listing the variable in the api subsection and linking it to the required API. In this code snippet we need access to the gpio API, the mangoh_led variable is therefore linked to the le_gpio.api. The other section in this code snippet lists all the source files needed by the component to function correctly.

requires: {    api:    {        mangoh_button = ${LEGATO_ROOT}/interfaces/le_gpio.api        mangoh_led = ${LEGATO_ROOT}/interfaces/le_gpio.api    } } sources: {    heartbeat.c }

Component.cdef file as found in the heartbeatComponent folder

Source Code

Let's now have a quick look at the source file that makes up this component and controls how the LED behaves. Below is the full source code for this component it is the code listed in the cdef and used to turn on and off the onboard LED. The first thing to note is the inclusion of both legato.h and interfaces.h. The first allows us to use any of the legato header files used by the component, all legato programs will use some legato header. The second file include.h links in the auto generated header file from the cdef.

Moving further down the code we see in the function LedTimer a variable called mangoh_led_Deactivate, this variable is created through the binding section in the .adef file. In essence this is using the variable mangoh_led, created in the cdef and linked to hardware in the adef, with the api. We are therefore saying the variable mangoh_led should be used with the function call Deactivate to turn off the specified pin. This same principle applies to the other variables in the code that use the legato APIs. The next function, ConfigureGpios sets the pin with the LED attached as an output. If this fails the legato API is then used to send a message to the system log using LE_FATAL_IF. This ability set in the cdef under envVars and allows the system to log messages at the info level and lower.

The last and most important part of the C source file is the COMPONENT_INIT. This is similar to main() in C programs but, because there is no main() in legato applications, we need a different entry point. The COMPONENT_INIT is this entry point. It is important to note though, that unlike main functions this function must return. If COMPONENT_INIT does not return then the rest of the application will not run. In this specific COMPONENT_INIT function a timer instance is created to control the intervals between turning on and off the LED. After an instance is created various parameters for the timer (period, whether to repeat or not as well as its handle) are set.  Lastly the gpios are configured using the previously created function and the timer is then started. After all this is done the COMPONENT_INIT is exited and control is handed back to the legato framework.      

/** * @file * * Blinks the user controlled LED at 1Hz. If the push-button is pressed, the LED * will remain on until the push-button is released. * * <HR> * * Copyright (C) Sierra Wireless, Inc. Use of this work is subject to license. */ #include "legato.h" #include "interfaces.h" #define LED_TIMER_IN_MS (1000) static bool LedOn; static le_timer_Ref_t LedTimerRef; /*------------------------------------------------------------------------------------------ * Toggle the LED when the timer expires */------------------------------------------------------------------------------------------ static void LedTimer(le_timer_Ref_t ledTimerRef) {    if (LedOn)    {        mangoh_led_Deactivate();        LedOn = false;    }    else    {        mangoh_led_Activate();        LedOn = true;    } } /*------------------------------------------------------------------------------------------ * Turn the LED on and disable the timer while the button is pressed. When the  button is * released, turn off the LED and start the timer. */------------------------------------------------------------------------------------------ static void PushButtonHandler(bool state, void *ctx) // {    if (state)    {        LE_DEBUG("turn on LED due to push button");        le_timer_Stop(LedTimerRef);        mangoh_led_Activate();    }    else    {        LE_DEBUG("turn off LED due to push button");        mangoh_led_Deactivate();        LedOn = false;        le_timer_Start(LedTimerRef);    } } /*-------------------------------------------------------------------------------------------------- * Sets default configuration LED D750 as on */-------------------------------------------------------------------------------------------------- static void ConfigureGpios(void) {    // Set LED GPIO to output and initially turn the LED ON    LE_FATAL_IF(mangoh_led_SetPushPullOutput(MANGOH_LED_ACTIVE_HIGH, true) != LE_OK, "Couldn't configure LED GPIO as a push pull output");    LedOn = true;    // Set the push-button GPIO as input    LE_FATAL_IF(mangoh_button_SetInput(MANGOH_BUTTON_ACTIVE_LOW) != LE_OK, "Couldn't configure push button as input");    mangoh_button_AddChangeEventHandler(MANGOH_BUTTON_EDGE_BOTH, PushButtonHandler, NULL, 0); } COMPONENT_INIT {    LedTimerRef = le_timer_Create("LED Timer");    le_timer_SetMsInterval(LedTimerRef, LED_TIMER_IN_MS);    le_timer_SetRepeat(LedTimerRef, 0);    le_timer_SetHandler(LedTimerRef, LedTimer);    ConfigureGpios();    le_timer_Start(LedTimerRef); }

heartbeat.c source file as found in the heartbeatComponent folder

While this was a rather simple and easy to follow demonstration it outlines the most important parts of setting up a legato application. The most complex and important part of this example is how variables are linked to the device or hardware they wish to control. The adef links the device to a variable name. The cdef then links this to an API which the source code can then use to interact with and manipulate the device.

I am planning on releasing another blog post shortly that will explain the more complex redSensorToCloud application. This application has multiple components and uses linux drivers for some of the peripherals.

MSP430F5529 Power Logger with AT&T M2X

In the previous blog the issue of having too many options when choosing an IoT solution was introduced. As a way to judge how easy it it is to select a solution, a project was proposed that could be implemented using different hardware and software. Once these projects are implemented on these platforms a comparison will be done to determine, from a prototyping perspective, what is an easy platform to use.

Usage Case

Power consumption at home and in the office is becoming a more conscious issue. The concept of leaving appliances to use whatever power they need at all hours of the day and night is no longer socially acceptable. Unfortunately most people do not know what power they are consuming or when they consume it. For these reasons this project aims to monitor power consumption of a device in either a residential or commercial setting.

Hardware & Setup

The hardware used to prototype this project consists of three components. The code that controls the various components is run on the MSP430F5529. The power consumption data is acquired using a MCP39F511 power monitoring IC from Microchip. Lastly the data is uploaded to the cloud via a CC3100 SimpleLink WiFi boosterpack that provides WiFi connectivity.

This initial implementation of the project was decided to be implemented on an MSP430 launchpad and programmed using Energia. The simplicity of both the hardware and software was also a factor in this selection. Another factor was the ability to easily move the prototype to a production model. The MSP430FR5969 was initially selected for this project because of the desire for a platform with a minimal number prebuilt examples. Unfortunately due to connectivity issues that were not immediately resolved the MSP40F5529 was selected. Subsequently it has been observed that it may be the first CC3100 used that has an issue and not the MSP430FR5969. The second choice of the MSP430F5529 was based on the availability of all 40 header pins in the boosterpack standard as well as previous experience with this board.

MSP430F5529 Launchpad with CC3100 Boosterpack Mounted Underneath and UART Connections Wired to the Top Headers

The MCP39F511 was selected as an easy to use power monitoring solution. The MCP39F511 records 16 different values relevant to power consumption. These values include the usual voltage, current, active reactive and apparent power. In addition to these there is also power factor and imported and exported power counters allowing for both power consumed and generated to be accounted for. The MCP39F511 communicates via UART and allows for most of its functionality to be customized to fit your specific application. With a configurable power range as well as minimum accumulated power consumption, this solution is capable of covering a large range of applications. In this project the MCP39F511 is contained in the ADM00667 evaluation kit. The ADM00667 provides isolation between the high and low sides ensuring any control electronics do not get damaged. There are also headers for easy connection to an external UART device to simplify communications with an external controller.

MCP39F511 in the ADM00667 Evaluation Lit

In order to upload the data to the selected cloud platform a CC3100 boosterpack is mounted on the MSP430. The CC3100 is WiFi certified and contains a TCP/IP stack as well as various other protocols. This makes the CC3100 a simple solution for connecting to the internet and uploading data to any desired cloud platform. Texas Instruments provides an API for communicating with the CC3100 in C allowing for easy progression to a large scale manufacturable device.

CC3100 Simplelink WiFi BoosterPack

Since the CC3100 is a boosterpack that mounts directly on the MSP430F5529 the only wired connections that need to be made are to the MCP39F511. The UART connections provided through the 40-pin headers are used for this purpose. Also because the ADM00667 provides isolation between the high and the low voltage sides 5V needs to be provided to the low side to power the optocouplers. For this an additional connection could be made from the MSP430F529 as long as the CC3100 is mounted under the MSP430F5529. Once these connections are made the hardware is setup and ready to be used.

SOFTWARE

The software for this project was written using C/C++ in the Energia IDE. The simplicity as well as abundance of libraries allowed for a prototype to be up and running in a very short period of time. The code has two main parts, the initialization code found in the setup function and a 6 state, state machine in the loop function. The initialization code sets up a WiFi object, sets the UART baud rate to 115200 bps and initializes two outputs for indicator LEDs. The WiFi connection is used to communicate to the M2X cloud platform. The MSP430 communicates to both the MCP39F511 and the connected PC via UART. This is used for both retrieving data from the MCP39F511 as well as debugging software and communication issues via the PC connection.

Communicating with the MCP39F511

The communication protocol for the MCP39F511 device is based on the Simple Sensor Interface (SSI) protocol. This protocol is used for point-to-point communication from a single-host MCU to a single-slave MCP39F511. It is important to note that the maximum number of bytes in either a receive or transmit frame is 35.

The SSI protocol requires that each message start with a header (0xA5), the number of bytes in the frame, a command byte and a valid checksum.

MCP39F511 Packet Format

Every frame that is sent starts with the same header or start byte, 0xA5. The number of bytes in the frame includes the payload as well as the header and checksum bytes. The checksum is generated by adding all bytes in the frame and taking to modulo of 256. There are 10 commands that can be sent to the MCP39F511 that allow for reading and writing to registers, setting and clearing the EEPROM as well as calibrating various functions in the MCP39F511. An issue to be aware of with the MCP39F511 is that although the default baud rate is 115200 bps, the MCP39F511 needs a few microseconds (~300) between every grouping of two bytes.

The MCP39F511 has three device responses. The first is an ACK, this signifies that the frame was received correctly and the commands were executed correctly. The second response is a NAK, this is used to let the host controller know that the frame was received but was either not understood or could not be executed. Lastly there is a CSFAIL response that lets the host know the frame may be correct but the checksum is not and the frame needs to be resent.

Code Generation

The code for this project was started from two other base projects and then rehashed to provide the functionality needed for this project.

The first code base used was the MultiSerial.ino example from Energia. This allowed for basic communication between two different serial devices. In this case the MSP430F5520 would request data from the MCP39F511 via UART and then pass it to a host PC via the UART backchannel. The second code base used was the LaunchPasWiFiPost.ino example from M2X bundled with Energia. This postes a value to the M2X cloud based on the value read from the onboard buttons.

The two projects were then merged once they were determined to be working satisfactory. That is that the MCP39F511 could reliably be polled for data and the data correctly outputted to the PC. Since the data is received LSB first, the bytes first need to swapped to correctly interpret the data. Also the MCP39F511 data sheet does not clearly explain the conversion factors between the measured data and the received data. In order to achieve the correct results trial and error along with the provided “Power Monitoring Utility” were used.

For the M2X demo, the major issue was trying to get multiple data points uploaded simultaneously without having a real time clock. While there apparently is a function to retrieve the server time from the M2X server, Energia had issues finding the correct data types in the M2X library. There is also mention of a single value upload for multiple data streams but again the functionality could not be found in the Energia library. Eventually multiple single value uploads were used decreasing the reliable polling rate for the MCP39F511.

State machine

The system uses a 6 state, state machine of which the last state is a fail case should the WiFi/internet connection be dropped. This case was added after experiencing the issue with the damaged CC3100 in the hope that resetting the connection would resolve the issue. Ultimately this did not resolve the issue with this particular boosterpack but was left in as a preventative measure for other fully functional CC3100 boosterpacks.

The first state is the only state where data is requested from the MCP39F511. In this state the MSP430 sets the address pointer for the MCP39F511 to 0x00 and then requests the next 28 bytes of data. This allows the system to retrieve the values for voltage RMS, line frequency, power factor, current RMS as well as active, reactive and apparent power. Since this request is repeated every 10 seconds an array is used to store this command sequence. This state also sets the green LED high for the duration of requesting data from the MCP39F511 as a visual indicator that the system is working.

The second state looks for an ACK from the MCP39F511. If an ACK is received the state is incremented and the state machine can progress to receiving the number of bytes in the current frame. If there is an issue the MCP39F511 sends back other device responses to indicate the possible issues. The first device response is a NAK, this indicates that the frame was received but the command could not be executed or could not be understood. It is also possible that there was an issue in the command byte. The second possible device response is CSFAIL. In this case the frame again was received but the checksum was incorrect. If either a NAK or CSFAIL are received the state is decremented so that the command can be resent.

The next state (3rd) receives the number of bytes in the frame. This is used in the next state to know how many more bytes need to be received.

The 4th state receives the remaining bytes in the frame. At every iteration through this state the number of bytes received is compared to the number of bytes to be received. Once these numbers are equal the state is incremented. In the current implementation of the software there is no time out or other check to ensure an issue between the MSP430 and the MCP39F511 does not cause the system to hang. There is however a precaution in place to be sure any unread data does not cause ongoing issues by including a Serial.flush at the start of the first state.

The last continually used state is the 5th state which process and sends the retrieved data to the M2X cloud platform. In order to send the data correctly to the cloud the data first needs to be organized correctly. The MCP9F511 returns all data LSB first, therefore the order of the returned bytes needs to be swapped. Before the data can be processed the validity of the received data needs to be checked. To accomplish this the checksum is first calculated and checked. If the received checksum and the locally calculated checksum match then the data is processed. If the checksums do not match, the data is discarded and a new request is issued.

System State Machine with Six States

The code and discoveries in this project were done in a way that hopefully they could easily be reproduced. To better aid in this the full code revision has been uploaded to github. The Git repository for this project can be found here and can be cloned by anyone wanting to add, change or use the code for their own purposes. It should be noted there is a need to add your own WiFi and M2X credentials in the associated WiFi_Credentials.h file.

Moving Forward

The next steps for this project would be to improve the timing resolution. This would need either the addition of a RTC or a connection to a time server. The next major step is to see how this compares to the MangOH Green board to get a better sense of of the comparable capabilities and prototyping time frames.

Real Time Power Consumption in Watts

Original post on Element14 can be found here