IoT

Marvell AWS IoT Starter Kit

This is a great platform for learning more about the IoT ecosystem and building connected devices.

Marvell's MW300 SoC is similar to the nRF5x line and is aimed at the IoT crowd. The MW300 uses a Cortex-M4F core (same as nRF52) with an integrated 802.11 b/g/n wifi module. Marvell's SDK utilizes Amazon's AWS IoT framework for handling communications up to the AWS cloud services. The AWS IoT framework is a bit more involved than the Particle framework mentioned above, but it also provides more flexibility and extensibility. Marvell sells an AWS IoT starter kit that you can use for prototyping and for playing around with the AWS IoT service.

Marvell provides a limited SDK for free on Github. Some of the lower-layer code (such as the USB stack) is available only in library form. There is a full SDK, but you must request access from Marvell.

More on the MW300 and AWS IoT Starter Kit:

You can purchase the starter kit on Amazon

Serial Debugging On the Particle Electron

As I started writing code for the Particle Electron, it wasn't long until I was fed up with my debugging setup. After a little bit of digging, I found out that it's quite simple to get USB or serial printing to work.

The Particle Electron has two USB channels and four USART channels that we can use for our debug output. These channels can be accessed using the various Serial classes provided by Particle.

A quick note: I am writing this guide for quick processing by experienced firmware hackers. If you are unfamiliar with communicating to hardware devices over a Serial port, I recommend trying the USB approach or checking this detailed tutorial for more information Particle USB/Serial debugging setup.

Serial

Particle Electron supports four serial ports:

  • Serial1
  • Serial2
  • Serial4
  • Serial5

Serial1 is the most convenient port to access, as it is wired out the the Electron's TX and RX pins.

Note that if you intend to use the USART port(s) to communicate with your host machine, you will need a USB-to-serial adapter (such as an FTDI device or their many clones). The TX and RX pin definitions will be flipped when connecting two devices: TX lines connect to RX lines on the other end, and vice-versa. Don't forget to connect the ground pin!

To configure the TX/RX pins to act as a serial port, you need to configure the Serial1 interface. Pulling an example from the Particle documentation:

Serial1.begin(speed);         // via TX/RX pins
Serial1.begin(speed, config); //  "

Serial1.begin(9600, SERIAL_9N1); // via TX/RX pins, 9600 9N1 mode
Serial1.begin(9600, SERIAL_DATA_BITS_8 | SERIAL_STOP_BITS_1_5 | SERIAL_PARITY_EVEN); // via TX/RX pins, 9600 8E1.5

For further serial port information, I recommend reading this Particle community tutorial.

USB

USB is certainly more convenient to use for our debugging purposes, as we don't need to bother with any adapters.

Particle provides two interfaces for USB serial comms:

  • Serial (no number!)
  • USBSerial1 (added as of system firmware v0.6.0)

These interfaces communicate through the USB port. When connected to a computer, each will show up on the host as a separate connected port. The USBSerial1 port is disabled by default.

Enabling and using the Serial interface is quite simple:

// EXAMPLE USAGE
void setup()
{
  Serial.begin(); //or USBSerial1.begin();
  Serial.println("Hello World!");
}

Now we are ready to rock and roll with our serial debugging

particle monitor

While you can use your favorite serial application (e.g. picocom, miniterm, screen), it's worth noting that the Particle CLI provides serial monitor functionality. The CLI only supports reading from the device, which is certainly good enough for debugging purposes.

Simply run:

$ particle serial monitor
Opening serial monitor for com port: "/dev/cu.usbmodem"
Hello world!

Further Reading

Getting up and running with serial debugging is a common task for experienced embeddded developers, so I have left out many details here. If you need more in-depth instructions, please see the links below.

Getting Started: Developing for Particle Electron on Your Host

One of my clients uses the Particle Electron in their product. Particle is an IoT platform provider, and Electron is a development platform that connects to the Particle cloud using a 2G/3G cellular connection.

Particle provides a web IDE for developers, but I decided to get myself setup to compile Particle firmware on the host machine. This guide will walk you through the setup of a host-based Particle development environment.

Cheat Sheet

Particle's documentation is thorough, but I found myself keeping a set of notes to work with their systems and figured it was worth sharing.

  • Make sure to compile in main/ - most of the particle instructions
  • make clean to clean projects
  • make all PLATFORM=electron to build
  • make program-dfu PLATFORM=electron to flash your recent build (in DFU mode)
  • particle flash --usb <binary.bin> to flash a specific build (in DFU mode)
  • particle update to update your device's system firmware (in DFU mode)
  • npm update -g particle-cli to upgrade particle-cli
  • DFU mode entry:
    1. Hold down BOTH buttons (RESET + MODE)
    2. Release only the RESET button (continue to hold MODE)
    3. Wait for the LED to start flashing yellow (it will flash magenta first, which indicates safe mode)
    4. Release the MODE button
  • Safe mode entry:
    1. Hold down BOTH buttons (RESET + MODE)
    2. Release only the RESET button (continue to hold MODE)
    3. Wait for the LED to start flashing magenta
    4. Release the MODE button (before it flashes yellow!)

Setup

The Particle Electron Getting Started Guide is a very thorough resource for getting up to speed. I have simplified their notes into a few useful steps.

If you need more information or run into problems, please refer to the Getting Started Guide for help.

Particle CLI

For full CLI installation steps please refer to Particle's console guide. I'm providing a quick summary here for more advanced users.

These are the dependencies:

  • npm (to install particle-cli)
  • dfu-util (to flash Particle boards)
  • particle-cli (to perform various Particle activities)

I installed npm and dfu-util through homebrew. Once npm is installed, you can run the following commands to set up particle-cli:

$ npm install -g particle-cli
$ particle login
$ particle setup

You can also setup your device using the online Device Setup tool rather than using particle setup.

Interacting with the Particle Electron

Before we dive into building the Particle firmware, I want to share a few brief notes about interacting with the Electron.

Particle Console

The Particle Console is a very useful resource for developing and testing devices. When devices come online, go offline, or publish messages, you will see them listed in the Particle console log. If your device provides functions, you can also call those from the Particle console.

You can find the Particle Console at console.particle.io.

DFU Mode

In order to flash your firmware from your host, you will need to put your device in DFU mode. Getting the device into this mode is simple:

  1. Hold down BOTH buttons (RESET + MODE)
  2. Release only the RESET button (continue to hold MODE)
  3. Wait for the LED to start flashing yellow (it will flash magenta first, which indicates safe mode)
  4. Release the MODE button, and now you're in DFU

Updating System Firmware

In order to upgrade the system firmware on your device, perform the following:

  • Put the device into DFU mode
  • Run particle update

The system firmware is contained in the particle-cli release, so if a new system firmware is released you will need to update your CLI.

Flashing Firmware Images

To flash a firmware image, you can use the following methods:

  • particle flash --usb <binary.bin> to flash a specific build (in DFU mode)
    • Will take any .bin file and flash it
  • make program-dfu PLATFORM=electron to flash your recent build (in DFU mode)
    • Will take the locally built user-part.bin file and flash it to the device
    • This is the workflow we will use in our host development process

Safe mode

I just want to mention Safe Mode, as I ran into some issues on this front. If you see that your device's LED is in a magenta state, it is in safe mode. You can also see it checkin on the Particle Console as a device in /spark/safe-mode. This usually indicates that your app did not run, likely due to a firmware version mismatch or data corruption.

If your device is in safe mode, the first thing to check that the SDK firmware version you are compiling with matches the system firmware on your device.

Safe mode is a useful recovery mechanism in the field. If your device becomes corrupted or hangs, you can manually put it into safe mode. Once in safe mode, it can register to the Particle cloud and receive an OTA update.

Manually entering safe mode is similar to entering DFU mode:

  1. Hold down BOTH buttons (RESET + MODE)
  2. Release only the RESET button (continue to hold MODE)
  3. Wait for the LED to start flashing magenta
  4. Release the MODE button (before it flashes yellow!)

Building Particle Firmware on Your Host

I really hate web development environments. The tools and workflows I like are unavailable, and I am not able to put my code under source control.

Luckily Particle provides their firmware in a Github repository that we can use for host development.

Toolchain

You will need the gcc ARM cross-compiler (gnu-arm-none-eabi) to compile for the Electron.

At the time of this publication, the latest GNU tooltain (6-2017-q1-update) fails to compile. I have decided to use the 4.9-2015-q3 toolchain, which works well. There's likely a version in between 4.9 and 6 that will work, but I did not have the patience to search.

Once you have downloaded the ARM toolchain, unpack it and add the toolchain's bin/ folder to your PATH. For example, this is in my .bashrc file:

export PATH="$PATH:$HOME/toolchain/gcc-arm-none-eabi-4.9/bin/"

Getting Firmware Source

You can find the Particle firmware in a Github repository. Checkout or fork the firmare repository. If you don't want to fork the repository, you will also need a second Github repo which you will use for tracking your firmware.

Once you have checked out the repo, you will be on the development branch. It is very important to check out a stable branch which matches the system firmware you want to use for your devices. If your system firmware does not match the SDK version you are compiling for, your device will end up in safe mode rather than running your user code.

I recommend updating your particle-cli installation to make sure you have the latest version. Using particle update, you can upgrade your device to the latest system firmware.

Not sure what system firmware is on your device? You can check build.particle.io and go to the "devices" tab on the left hand side. If you select the device you're interested in, you can see note detailing the current firmware version.

Once you know the version you need, checkout the corresponding tag in the firmware repository (0.6.2 at the time of this writing). This will be the baseline for our firmware setup. If you update the system firmware, you will need to pull in the corresponding firmware tag from the Particle firmware repository.

Setting Up Your Project

Once you have selected the proper firmware version we are ready to setup our repository.

If you did not fork the repository, you will need to copy the Particle repository contents to your project repo.

Your project code should go itno the user/ directory. The main source files are stored in user/src. Inside this folder you should find an application.cpp file which matches the "Tinker" demo application. This is the starting point for creating your own Particle project.

Your project needs a setup() and loop() function, but the remaining functions can be stripped out.

When you add source files to the user/src folder they will be automatically picked up - no need to much around with any Makefiles!

Building Firmware

Building firmware is pretty simple. You just need to run:

make all PLATFORM=electron

This command will work from either the root directory or the main/ folder. However, all of the Particle instructions assume that you are compiling inside main/, so I recommend this workflow. You will also find that useful things like make program-dfu fail unless you are compiling from main/.

The build results are output in build/target/user-port/<platform>/. The user-part.bin file is the firmware image that you will want to flash to your device.

Flashing Firmware

Once you've successfully compiled your project, you can issue this command to flash your build to a device in DFU mode:

# Assumes you are inside main/
$ make program-dfu PLATFORM=electron

Otherwise you can run:

$ particle flash --usb /path/to/user-part.bin

After flashing is complete, your device will reboot and run your new firmware! If there was a problem, you will see the LED turn magenta to indicate it booted into safe mode.

That's all there is to it! You are now able to start working on your project from the comfort of your host OS. Happy hacking!

Further Reading

Particle has excellent documentation, I recommend diving in and familiarizing yourself: