Monday, February 12, 2018

TI Motor Drive Bundle (LAUNCHXL-F28027, BOOSTXL-DRV8301) & MotorWare - How Easy is it to Get Your Motor Spinning


I would like to thank Element14 and Texas Instruments for selecting me for this roadtest. I applied to review the TI Motor Drive Bundle because of a previous experience with the BOOSTXL-DRV8301 boosterpack and a not so compatible launchpad. I have previously reviewed this boosterpack with less than favourable results. I was therefore hoping that after 3 years of availability, the documentation and support would have improved.

Unboxing & First impressions

Element14 has worked with TI to deliver these boards as complete evaluation kit. The packaging has therefore been altered to reflect this. The three components, each individually packaged, come shipped in a single kit box. The launchpad is packaged in the standard TI box. The DRV8301 on the other hand is shipped in what has been labeled a new product box. If this was a new product, as it may have been during my initial review, this would be acceptable. Its now substanily later in the products life and this generic, oversized box reflects an apathy or disinterest towards this product. The provided motor (DN4240S24-026-TI) is shipped wrapped in bubble wrap. As a perk, a pen with a screwdriver in the back and a level and ruler on the side has been included.
Kit contents as assembled by TI in partnership with Furnell/Newark

The getting started guide for the LAUNCHXL-F28027 has a simple demo to let you know the board is working. The demo interestingly contains two parts. The first demo is done with no PC connected. Once powered up a reference temperature is take. If the temperature changes, the change is reflected on the LEDs to indicate the difference. A new reference value can be set by pressing the S3 switch.
Demo: LEDs displaying change in temperature from initial setpoint

An extension of the first demo is accessed by connecting the LAUNCHXL-F28027 to a PC. After connecting the board, configuring the terminal (115200, 8, No parity, 1 stop) and pressing reset, the board display a text version of the TI symbol.
Terminal after resetting the F28027F

The display prompts you to press the S3 button. This again begins the temperature demo. Instead of only having the LEDs to inform you of the change, the measured value is updated at the bottom of the display.

The DRV8301 doesn't have a quickstart program to run even though there is a quick start guide. Any demo software for this boosterpack is found in the motorware software package and will be look at later in the review.

Getting Started

The various getting started guides all demonstrate how to configure the onboard switches and jumpers before starting. Once these are set there is little help to get you any further.
Proceeding to look through Motorware which had previously installed didn’t help. Knowing that this is an InstaSPIN-FOC board I looked under this section first. Unfortunately there are only projects listed there with no documentation. Attempting to use the Universal GUI to get started revealed the documentation for this software was lacking.

MotorWare labs available for the 8301 Rev B,, notice no documentation listed

Fortunately I was directed by a fellow member of Element14 (najath) to look in the Motorware software for further information. More specifically najath specified to look under the resources section (Resources > Launchpads > F28027F Launchpad). The “Kit Readme First” provides some information but nothing that has not already been provided from the various other getting started guides. The “GUI Quick Start Guide” is also the same as listed under InstaSPIN-FOC. Thankfully najath provided some further instructions. Under “Training:User’s Guides, Labs, Tutorials” is a PDF called “InstaSPIN Projects and Labs User's Guide”. This guide finally gets a user moving forward with this kit.

The resources section has a bit more information but, nothing particularly useful under the F28027F section

After spending a considerable amount of time to get to the kit working it became abundantly clear that TI had not made much, if any progress with this kit since my last review. The main difference between the current and previous review is the help provided from the Element14 community, something I don’t believe I got from TI’s e2e forum on previous attempts.


The documentation for this kit has already been mentioned in passing. There is however a decent amount more to be said about this. The quick start guides, of which there seem to be an abundance, don’t point a user in any meaningful direction. The getting started guide for the launchpad shows the user how to configure the board and run the preprogrammed demos. It then points a user to CCS or ControlSUITE for anything further the user may want to do. This may be pretty standard for a getting started guide but, in this case the instructions don't lead to anything concrete to help a user move forward.

Sadly the getting started guide for the DRV8301 is worse then this. After explaining how to setup the hardware, and not really explaining how to connect the motor we arrive at step VI. If anything has been intuitive or well explained until now TI has made sure to rectify that. This last step simply states “Enable your control algorithm and spin that motor”. If this is unclear then TI suggest using MotorWare to get started.

Step 4 listed in the 8301 getting started guide, “Enable your control algorithm and spin that motor”

As has already been outline in the getting started section, this is more complicated than it would appear. There is no clear starting point once MotorWare is opened up. It should be mentioned at the END of the instructions for each project in MotorWare there is one line “Follow the InstaSPIN Projects and User’s Guide to Get Started”.

Atr the END of each project TI lists where to find more information about getting the lab working

This concept of doing things out of order and in a non intuitive manor seems to be common with this kit. The Quick Start Guide for the Universal GUI also lists all the steps needed to run the software including clicking on run. Only after completing the lab, TI explains how to setup the hardware that the software runs on. Just before setting up the hardware but, after the completion of the lab, is the explanation of the GUI’s interface.

Other issues include incorrect referencing/labeling of tables in the lab guide. Steps that are not relevant to some launchpads, including the one included with this kit, are not commented as such. Missing steps, such as those needed to get the Universal GUI working. The steps for the GUI were eventually stumbled upon by reading the readme file in the InstaSPIN_F2802xFUNIVERSAL folder. The GUI has also been changed since the guide for it was last updated in 2015. There have been some components added and others removed. This leaves a user unclear what the functionality of these components are.

Overall TI has really dropped the ball with regards to its documentation for this product. The time between this product first being introduced and now has not been used to streamline the process to get a new user from demo to product. Nore has it been used to increase ease of use. I would be beneficial for TI and it’s customers if these documents where revamped. It would also be helpful if there was one getting started guide with a logical progression to get this kit running with minimum hiccups along the way.


Once the documentation has been worked out and, the single useful starting point found, there is a lot of software to work through. Because of the complexities of the Piccolo along with the those of controlling a motor TI has provided a HAL layer. This allows a user to focus on getting the system working as needed and not worry about setting up registers. Another reason not made clear at first, is the need to hide the code running in the FOC. As this is proprietary and TI not wanting it shared, this HAL also provides access without giving away anything. In order to help the user understand each of the functions are 20+ labs each with multiple parts. While some of these labs are not relevant to the LAUNCHXL-F28027 there are still a large number of demos helping someone working with this kit to understand how to get their project working.

Each lab is provided with complete code that compiles out of the box. Sadly not all the code is well explained and there is a decent amount of following functions to get to the root of their intent. This added effort adds time and complexity to getting through each lab. Along with a unclear explanation of the software in each lab is an equally brief explanation in the lab manual. It is definitely possible to work out the ambiguities but this again adds time. One major issue in this regard is the lack of mentioning when a specific part of the software is not relevant to a microcontroller. Some of the labs require code changes to be made in order to get a better understanding of what the software is doing. The sections in the lab manual are not labeled as not being relevant to different controllers. The only way to infer this is by looking at the #ifdef statements at the top of each section of code.

Another issue with the software and its associated documentation is the assumption of specific knowledge. There are terms and abbreviations used that are not explained or done so very briefly. This would be acceptable if there was some reference information provided to help a new user to learn more, but there are no footnotes or references.

Regarding this specific kit, each project uses a header file to pull in parameters that the user can set for their motor. TI has kindly provided parameters for 16 different motors. This allows for a user to easily switch over to a different motor without needing to figure out the parameters of that motor. TI however forgot or decided to not include the parameters for the motor (DN4240S24-026-TI) that is shipped with this kit. Adding to this issue is the lack of availability of any documentation for this motor. Only after contacting the manufacturer of the motor was I able to get the documentation for it. This one page document still did not provide all the needed information. There is however a page, that was pointed out by another element14 member (MARK2011), that doesn't seem to be anyway linked to the kit or the product identifier that does have the full specs.

DN4240S24-026-TI datasheet as received from the manufacturer


The hardware provided in this kit has a few interesting factors. The first and most obvious is the ill fitting nature between the LAUNCHXL-F28027F and the BOOSTXL-DRV8301. The switch S4’s form factor prevents the boosterpack from seating properly on the launchpad.

The S3 switch on the F28027 launchpad can interfere with the DRV8301s ability to be correctly seated

A workaround for this is to provide an extra set of headers to increase the clearance between the bottom of the boosterpack and the switch. The placement of this switch as well as S1 means that any change to these switches requires that the boosterpacks be removed. This again is solved by adding the extension

Headers added to the F28027 launchpad allow the DRV8301 to clear the S3 switch

Another interesting issue noticed is the seemingly incompatibility between the F28027F and the F28027. The previous review I did was supposed to contain an F28027F but instead I received a F28027. Since TI specifies these are pin compatible and the schematics for the LAUNCHXL-F28027/F don’t mention any alterations depending on the provided chips the F28027 was swapped for a F28027F. Unfortunately this did not resolve any issues and the board does not perform like one containing a F28027F.

On the positive side, TI has positioned the BOOSTXL-DRV8301 on top of the LAUNCHXL-F28027F in such a way as to keep S2 and S3 (the two user push buttons) accessible during operation. This allows for those buttons be incorporated into a design without concern for accessibility.

The two user switches have been well placed allowing them to be accessed even when a boosterpack is mounted


TI included with this kit 6 hours of free online help with your own “personal trainer”. This is probably the one thing TI has done well to move this product forward. The kit includes a card with a TI employees name and email address. Contacting the employee reveals he is someone well acquainted with the software for this kit. I was also informed that should more than the advertised 6 hours be needed that would not be an issue. The help includes anything from just answering a few short questions to getting a walk through on the software. The idea is that after the personal help you should be well on your way with your project. In the few interactions I had through this service I found the employee to be both helpful and courteous.

TI’s e2e forum is still available for this product so if immediate help is needed (the personal trainer is located in Germany) you can try find answers there. The one big difference between the personal trainer and e2e is accountability. By directing your question to one person instead of to a broad forum is there is one person responsible. This leads to both better and more timely responses.

Moving forward

Having spent a decent amount of time getting to know this kit I am looking forward to using it further both as a learning tool as well as in future projects. Something that I have found this kit to be useful for other than motor control is it sability to teach control theory. Because there are so many variables in controlling a motor and both the LAUNCHXL-F28027F and the BOOSTXL-DRV8301 allow for these variables to be controlled this is a great platform for learning applying these control strategies.

I would also like to complete all the labs associated with this kit. As previously mentioned working through each lab and following each function call down to its base call to get a better understanding takes time. I have therefore been unable to complete all 19 labs for the BOOSTXL-DRV8301. Once this has been completed I would like to try implement this kit in a boat project I have been looking at. This would be used control the propulsion propeller allowing for such things as cavitation mitigation to be implemented


Overall this is a quilty kit provided from TI in partnership with Element14. The software and HAL layers are well implemented. There are sufficient demonstrations to allow a user to learn how to use the kit for any application they may have in mind.

Sadly these great qualities are overshadowed by the badly written getting started guide and the abundance of them. Had TI selected to have one getting started guide for the BOOSTXL-DRV8301 that clearly outlined the steps to get the kit working with the demo software this kit would be a lot more useful. Along with this had TI put more effort into the lab manual to explain what the various functions are doing as well as what functions work with what kit that would have helped as well.

I am therefore looking forward to working more with this kit to learn about motor control as well as control theory in general. I am also hoping to implement more motors into my projects now that I have become acquainted with this product and its use cases. For others wanting to learn about motor control and have the time and energy to go through the many pages of documentation and lengthy lines of code, this kit is definitely useful and has a lot to offer.

Original post on Element14 can be found here

Monday, February 5, 2018

MangOH Red and the Legato Framework with Multiple Components

In a previous blog post we took a brief look at the MangOH Red and what makes this new board standout. We then started to explore the Legato framework that runs on the Magoh boards (and the Raspberry Pi, instructions here).

We started off looking at a very simple application, heartbeatRed, one that has only one component, includes one source file and uses one API, to interface with two GPIOs (a button and a LED). In this blog we will move further to an application that has multiple components and various APIs. Since in the “Getting Started Guide” an app called redSensorToCloud is used to capture sensor data and post it to AirVantage, we will look at that app.

System Definition File (SDEF)

In the previous blog we started with the ADEF and explained what that is used for in the overall file system, there is however a file above the ADEF. The SDEF (system definition file) lets the overall Legato framework know what is need when the system is compiled. At this point it should be mentioned, Legato allows you to compile the full framework or compile an individual application to be loaded to the target. The SDEF is always needed to compile the framework. An SDEF can not easily be compared to any one part of a C program. The first section #include makes the file look like a regular C file but, in this case the include links in another SDEF, one used for the WiFi modules.

After the include comes the apps section. This is where the a list of all applications to be included in the compilation of the framework are listed. In the SDEF below there are 7 applications listed to be included in the build. Looking through this section we can see the application we are currently looking at, redSensorToCloud, as well as the heartbeatRed application which we explained in the previous blog post.

If any command line tools are needed when logged in as a root-user through a remote shell we need to make them accessible. In order to do so list them under commands. This works in a command name and command extension pair. The portion on the left hand side of the assignment statement is the name used to call the function from the command line. The portion on the right hand side is the location of the command we would like to make accessible. Once this has been loaded on the MangOH these commands would be accessible when logged in over SSH or through the terminal. It is possible to make an application, local to the MangOH board, executable from the command line in a similar way. The only difference is on the right hand side of the assignment, instead of the commands name (drTool or socialService in the file below) you would list the name of the application to be used.

The interfaceSearch section acts, in away, like a linker file in C. This section shows the compiler where any mksys or other files (.api, .h, etc) files are that may be needed to build the components for the framework. This allows for comments to be truly separated from their interfaces. By allowing interfaces to be stored in one location (not within or part of the component) the same file can be used for multiple components and any upgrades or fixes made would be applied to all components using the relevant interface.

The last section in the SDEF below is that for kernalModules. This shows the compiler where to find prebuilt kernel modules that may be needed or used by some of the components. Each entry in this list points to an MDEF file. The MDEF lists the files used in to build the module as well as passes any other information to the compiler that may be needed to complete these drivers for the target board. Noticeably listed are modules for the sensors on the MangOH Red board, these include the BMI160 and the BMP280.

// mangOH Red system definition that extends the wifi sdef from Legato.
// Copyright (C) Sierra Wireless Inc.  Use of this work is subject to license.

#include "$LEGATO_ROOT/modules/WiFi/wifi.sdef"




   // The heartbeat app is disabled on mangOH Red because the logging messages
   // from the low power microcontroller make it very difficult to use the console port.
   // $MANGOH_ROOT/apps/Heartbeat/heartbeatRed


   dr = drTool:/bin/dr
   twitter = socialService:/bin/twitter



   // Required for bmp280 & bmi160

   // Required for bmi160


   // Used on mangOH Red DV3 and later

   // spisvc creates a spidev device which will appear as /dev/spidev0.0 once the spidev module is
   // loaded.

While the SDEF may not be something you interact with very often it is still an important file to understand. Drivers may need to be added or altered and you may want to run applications that are not standard or remove some that are.

Application Definition File (ADEF)

The next file that is used in the compilation of a system/application is the ADEF, this is the first file that is always needed. The ADEF lists the executables to be run within this application and what components are needed for that executable. Any resources that are specified in the ADEF are also given a handle by which they can be referenced

While all ADEFs have the same basic blocks and we have previously looked at the ADEF, what's in them can differ and appear complicated. The ADEF below starts off the same as in the previous blog post with sandboxed, start and version all set the same. The first and most noticeable difference comes under executables. In this section, instead of a one to one mapping, the executable redSensorToCloud is mapped to two components. In the ADEF below the executable redSensorToCloud is mapped to two components. This means that when redSensorToCloud is executable both components (avPublisherComponent and sensorsComponent) are run and both of their COMPONENT_INIT functions are run at startup.

The next block, processes, has previously been looked at. Subsections run and envVars tell the application which executables to run as well as what environment variables are accessible from within the application. The last section bindings in this ADEF are slightly different than those previously encountered. While the section provides the same functionality, the API in this file behaves slightly differently than those found in the previous application. The previous API provided a handle to directly manipulate the internal interface. This application’s API does not provide such functionality. The first API, le_adc, connects directly to the interface, by specifying the ADC channel in the function calls the API knows what channel to read from (the exact code can be seen here and here). The second API avdata is used to send/receive data between the MangOH board and the AirVantage server. This API requires that a record object be created. Data is inserted into the record, the record is then pushed to the server. Therefore because these two APIs use objects, there is no variable name to be used in the CDEF or source files.

sandboxed: true
start: manual
version: 0.1

   redSensorToCloud = ( avPublisherComponent sensorsComponent)

       ( redSensorToCloud )


   redSensorToCloud.sensorsComponent.le_adc -> modemService.le_adc
   redSensorToCloud.avPublisherComponent.le_avdata -> avcService.le_avdata

Component Definition File (CDEF)

In order to increase reusability, this application has been written using two CDEFs. This allows for the various components to be used in multiple applications without needing to rewrite code.

Individually the CDEFs are not complex and are even similar to those previously discussed. There are however, some noticeable differences. In the avPublisherComponent, there is a previously unseen subsection. The component subsection informs the compiler there is some functionality in the sensorsComponent needed by the current component. This other component is therefore required by the current component, similarly this included component or any subsequent components have required components those too will be imported. This also implies codependence is not allowed, if this does occur the application will not compile. When done correctly, the dependant components COMPONENT_INIT will be run after the non-dependant component’s has run. Other than the component section there is the previously seen api section which lets the component have access to the avdata_le API. There is also the sources section which list the C sources file needed to build this component.





Other than the longer list of source files listed in the sensorsComponet CDEF the noticeable difference here is the file subsection. This section allows us to provide files (as defined by linux) to the application that are not part of but, are needed by the application. It also tells the application where to find the specified file within the application sandbox. These files need to be accessible at run time and not build time as that is when the application will look for them.



       /sys/devices/i2c-0/0-0068/iio:deice0/in_accel_x_raw    /sys/devices/i2c-0/0-0068/iio:device0/
       /sys/devices/i2c-0/0-0068/iio:deice0/in_accel_y_raw    /sys/devices/i2c-0/0-0068/iio:device0/
       /sys/devices/i2c-0/0-0068/iio:deice0/in_accel_z_raw    /sys/devices/i2c-0/0-0068/iio:device0/
       /sys/devices/i2c-0/0-0068/iio:device0/in_accel_scale    /sys/devices/i2c-0/0-0068/iio:device0/
       /sys/devices/i2c-0/0-0068/iio:deice0/in_anglvel_x_raw  /sys/devices/i2c-0/0-0068/iio:device0/
       /sys/devices/i2c-0/0-0068/iio:deice0/in_anglvel_y_raw  /sys/devices/i2c-0/0-0068/iio:device0/
       /sys/devices/i2c-0/0-0068/iio:deice0/in_anglvel_z_raw  /sys/devices/i2c-0/0-0068/iio:device0/
       /sys/devices/i2c-0/0-0068/iio:device0/in_anglvel_scale  /sys/devices/i2c-0/0-0068/iio:device0/
       /sys/devices/i2c-0/0-0076/iio:device1/in_temp_input     /sys/devices/i2c-0/0-0076/iio:device1/
       /sys/devices/i2c-0/0-0076/iio:deice1/in_pressure_input /sys/devices/i2c-0/0-0076/iio:device1/


Over all the file system started with the SDEF at the very top and is followed by the ADEF and CDEF respectively below it. Each CDEF will list the source files as well as any other system requirements it needs to build the component. Below and in away to the side of the SDEF is also the MDEF, these list/build the modules needed by the kernel. In this application MDEFs for the various onboard sensors are included and can be thought of as drivers. A full outline of this application (without the MDEFs is provided in the image below).

2017-10-18 10_01_25-MangOH File Structure using Legato - Multiple Components.pdf.png

The next step is to build our own application, this will be looked at in future blogs. The first project will be to attempt to use a Raspberry Pi shield to measure temperature, humidity and air pressure. Once this has been accomplished a future project will look to incorporate sensor readings along with GPS data. This project's goal will be to attempt to use the MangOH Red as a standalone Weather Balloon board, with the cellular modem providing communications and the on chip GPS providing location. Sensor data will be collected via external sensors but will be relayed in semi realtime back to AirVantage via cellular networks.