DEV Community: Christopher McClellan

Debugging Rust Cortex-M with VS Code: Take 2

Christopher McClellan — Tue, 31 Dec 2019 15:23:14 +0000

Last time, I wrote about how to configure VS Code to debug Rust Cortex-M programs, but you know what's better than writing documentation for how to do a thing?

Automating it.

I'm very happy to announce my PR to add a basic debug configuration for VS Code has been merged into the cortex-m-quickstart template. VS Code is now supported out of the box when you cargo generate a new project. When I say "out of the box", I really mean "out of the box". I've also added a QEMU configuration, so you can go experiment with debugging embedded Rust with VS Code right now, without any additional hardware.

Setup

First, ensure you've installed Rust, the ARM Cortex-M toolchain, QEMU, and OpenOCD.

Then, ensure you've installed cargo generate.

$ cargo install cargo-generate

Lastly, install the necessary VS Code plugins.

$ code --install-extension rust-lang.rust
Installing extensions...
Installing extension 'rust-lang.rust' v0.7.0...
Extension 'rust-lang.rust' v0.7.0 was successfully installed.

$ code --install-extension marus25.cortex-debug
Installing extensions...
Installing extension 'marus25.cortex-debug' v0.3.4...
Extension 'marus25.cortex-debug' v0.3.4 was successfully installed.

Now we can generate a new project.

$ cargo generate --git https://github.com/rust-embedded/cortex-m-quickstart --name cortexm-app
🔧   Creating project called `cortexm-app`...
✨   Done! New project created /Users/rubberduck/src/cortexm-app

Let's go ahead and open it in Code.

$ code cortexm-app

Debugging with QEMU

It is recommended you complete the QEMU section of The Book before moving forward, although, it's probably not necessary.

Open src/main.rs and set a breakpoint.
Go to the debug screen and run the Debug (QEMU) configuration.

The project will automatically be built targeting the LM3S6965EVB MCU, the resulting executable used to start QEMU, and then break when execution hits the entry point. You can then step through the code as you will.

If you prefer not to break on main, set runToMain to false in the .vscode/launch.json file.

"runToMain": false,

That's pretty much it. I told you it worked out of the box. Feel free to play with the examples that come with the cortex-m-quickstart template. The easiest thing to do, at the moment, is to copy the code into src/main.rs and run the Debug (QEMU) task. This will ensure the code is built prior to starting the emulator. You could also build the executable from the command line and modify the launch.json file to point to the example, if you wish.

cargo build --example hello

{
    //...

    // "executable": "./target/thumbv7m-none-eabi/debug/testapp",
    /* Run `cargo build --example hello` and uncomment this line to run semi-hosting example */
    "executable": "./target/thumbv7m-none-eabi/debug/examples/hello",
},

Currently, the Rust Language Server extension doesn't directly support building an example, although we could create a new configuration and shell build task that executes the right cargo build command.
I consider this to be an area for improvement in the future but, honestly, it's a good exercise for the reader. These default configurations aren't meant to be the "end all, be all". They're meant to be a starting point for you to create debug configurations that meet your and your project's needs.

Debugging on Hardware

Like last time, we'll be using the STM32F3DISCOVERY board as our hardware.

Before you tackle this section, it is highly recommend you work through doing this from the command line to ensure you've installed the tools and properly setup your project. Unlike the QEMU section, debugging on hardware requires we modify a few files. I've included a brief summary below, but I really do encourage you to work through this chapter of The Embedded Rust Book first.

In .cargo/config, ensure you've set your build target to thumbv7em-none-eabihf.

[build]
target = "thumbv7em-none-eabihf" # Cortex-M4F and Cortex-M7F (with FPU)

Then ensure you have the correct memory layout in the memory.x linker script.

/* Linker script for the STM32F303VCT6 */
MEMORY
{
  /* NOTE 1 K = 1 KiBi = 1024 bytes */
  FLASH : ORIGIN = 0x08000000, LENGTH = 256K
  RAM : ORIGIN = 0x20000000, LENGTH = 40K
}

With that out of the way, we can connect our hardware via USB to the ST-Link port and launch a debug session. This time we'll use the Debug (OpenOCD) configuration.

You'll notice that "Cortex Peripherals" aren't loading. That's because, for licensing reasons, we couldn't include the *.svd file in the quickstart template. If you go to ST's website for the STM32F3 series, you can find and download the SVD pack (or just download the STM32F3 SVD pack from this link). Once you've unzipped the package, just copy the STM32F303.svd file into the .vscode/ directory and start a new debug session. The quickstart is configured to look here for the SVD, so you should now see all of the peripherals loaded into the editor.

Of course, you could keep this file anywhere you like and just modify this line of the .vscode/launch.json file.

"svdFile": "${workspaceRoot}/.vscode/STM32F303.svd",

Personally, I like keeping them in my home directory so I don't have to keep multiple copies of the SVD on disk.

"svdFile": "${env:HOME}/.svd/en.stm32f3_svd/STM32F3_svd_V1.2/STM32F303.svd",

If you're working on a shared project though, you may want to use the default location and check the file in. That way, everyone who clones your project has a working configuration as soon as they've cloned it.
Which brings us to...

Git

By default, all files in the .vscode/ directory are ignored by Git. There are a number of files that can end up in the .vscode/ directory that shouldn't be committed, so ignoring the files in this directory as a default is a good idea, but the task.json and launch.json files define build & run configurations that can (in my opinion, should) be shared with anyone cloning the project. They're not user specific files, so they're safe to add to your repository and will be tracked by default.

Logging with ITM

Nothing really changes here since last time, so see the logging section of the original post.

Using other hardware

This is where we need to take an actual hard look at the launch.json configuration and you'll also need a pretty good understanding of the hardware you wish to use, so if you're happily debugging your STM32F3DISCOVERY, feel free to stop here. However, if you're looking to setup VS Code for some other board, continue on and I'll do my best to explain what the different parts of the Debug (OpenOCD) config do. For full documentation, see the Cortex-Debug project site and repository.

For reference, here is the OpenOCD config for the STM32F303.

{
    /* Configuration for the STM32F303 Discovery board */
    "type": "cortex-debug",
    "request": "launch",
    "name": "Debug (OpenOCD)",
    "servertype": "openocd",
    "cwd": "${workspaceRoot}",
    "preLaunchTask": "build",
    "runToMain": true,
    "executable": "./target/thumbv7em-none-eabihf/debug/cortexm-app",
    "device": "STM32F303VCT6",
    "configFiles": [
        "interface/stlink-v2-1.cfg",
        "target/stm32f3x.cfg"
    ],
    "svdFile": "${workspaceRoot}/.vscode/STM32F303.svd",
    "swoConfig": {
        "enabled": true,
        "cpuFrequency": 8000000,
        "swoFrequency": 2000000,
        "source": "probe",
        "decoders": [
            { "type": "console", "label": "ITM", "port": 0 }
        ]
    }
}

Server Type

The Cortex-Debug extension supports a number of different GDB servers. Here, we're specifying that we're using OpenOCD.

"servertype": "openocd",

If you're using a different GDB server, you'll obviously need to reference the documentation to configure your server and most of the information below will be of questionable value to you.

Device

"device": "STM32F303VCT6",

The device field is used to specify which MCU you're targeting and is used in conjunction with one of the several Cortex-Debug Device Support Packs. If you've installed the right pack and specified a device, the Cortex-Debug extension will use this field to look up the right SVD file for you and you can then omit the svdFile field.
So, technically, in the current configuration, this does nothing but document which microcontroller this config is meant for.

SVD File

"svdFile": "${workspaceRoot}/.vscode/STM32F303.svd",

Specifies where the System View Description for your device is located. As we've covered, this allows the Cortex-Debug plugin to load peripherals for your device into the editor. This can be omitted if using a Device Support Pack and device field.

Config Files

"configFiles": [
    "interface/stlink-v2-1.cfg",
    "target/stm32f3x.cfg"
],

This is an array of config files passed to openocd and equivalent to using the -f flag.

openocd \
  -f interface/stlink-v2-1.cfg \
  -f target/stm32f3x.cfg

If you find your openocd installation directory, you will find many common configurations and targets under the share/openocd/scripts/ directory. Specify the correct files for your device here.

SWO Config

"swoConfig": {
    "enabled": true,
    "cpuFrequency": 8000000,
    "swoFrequency": 2000000,
    "source": "probe",
    "decoders": [
        { "type": "console", "label": "ITM", "port": 0 }
    ]
}

This configures the ITM output for the device. The fields you'll likely need to update here are the cpuFrequency, swoFrequency, and the ITM port. Get any of these wrong and you'll not see any output in the SWO output of the editor.

Unfortunately, I can't help you much here. You'll need to reference your datasheet and schematic for the CPU frequency, as well as know what SWO frequency and port the software is using.

Conclusion

I couldn't be happier that these configurations were added to the quickstart template. Hopefully, this lowers the barrier just that much more for folks looking to get into embedded Rust. I have high hopes for Rust as an embedded development language over the next decade. I figure the lower the bar to entry is, the more people we can get involved, the more likely it will be that we can develop the ecosystem into something that makes Rust a default choice for systems programming. I know it won't happen over night, and the languages currently in use aren't ever going away, but I'm happy to contribute one small piece in the puzzle to a better future for embedded software.

Until next time,
Semper Cogitet

Debugging Rust ARM CortexM Programs with Visual Studio Code

Christopher McClellan — Fri, 29 Nov 2019 19:10:30 +0000

Debugging Rust ARM CortexM Programs with Visual Studio Code

I've been toying with embedded Rust off and on for some time now.
I picked up one of the STM Discovery boards and it's been an interesting novelty for me to be able to remotely debug code running on the microcontroller. I've never been willing to spring for the external hardware debugger required to do so, but the Discovery has a STLink built into the board. The Rust Embedded and Discovery books have great instructions for remote debugging Rust programs, but rely soley on command line tools for doing so. I like the terminal as much as, if not more, than the next person, but it's also really nice to be able to set breakpoints and step through code right inside of the editor.

I tend to use VS Code as my main editor these days, so that's what we'll set up today. We'll take a look at the hardware and setting up the toolchain first, before moving on to setting up our editor. The prior is essentially a condensed version of the information in the Discovery book, so if you've already worked your way through that, feel free to skip to setting up VS Code.

The Hardware

This is the STM32F3DISCOVERY board by ST.

It has a 32 bit ARM CortexM4 processor and, as I mentioned earlier, a super convenient built in debugger. It's a really nice little board. The mcu itself has 256kb flash memory and 48kb RAM while the eval board also has an accelerometer, magnetometer, gryroscope, and lots of built in leds, IO, and peripherals to play with. To top it all off, its $16 price point brings it in as less expensive than the official Arduino Uno with its 32kb flash memory, 2kb RAM, and lack of any additional trinkets. To be fair the STM32F303VCT6 microcontroller costs 3 times the Uno's ATMega328p and is quite a bit more complex, but I really like this board.

Installing the toolchain

Below is a summary of the instructions in the Discovery book for setting up your environment for ARM development.

First, install the necessary build targets and extra cargo tools.

# itmdump
cargo install itm

# bin-utils
rustup component add llvm-tools-preview
rustup target add thumbv7em-none-eabihf
cargo install cargo-binutils

Then install the actual ARM toolchain itself.

If you're using Mac, be sure to use the instructions from the Rust Embedded Book. There have been multiple pull requests open to fix this in the Discovery book for a little while now.

brew tap ArmMbed/homebrew-formulae
brew install arm-none-eabi-gcc

Install openocd, we'll be using it to flash and debug our Discovery board.

brew install openocd

Connect the board to your laptop via the STLink USB port and verify you can connect via openocd.

$ openocd -f interface/stlink-v2-1.cfg -f target/stm32f3x.cfg
Open On-Chip Debugger 0.10.0
Licensed under GNU GPL v2
For bug reports, read
    http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "hla_swd". To override use 'transport select <transport>'.
adapter speed: 1000 kHz
adapter_nsrst_delay: 100
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
none separate
Info : Unable to match requested speed 1000 kHz, using 950 kHz
Info : Unable to match requested speed 1000 kHz, using 950 kHz
Info : clock speed 950 kHz
Info : STLINK v2 JTAG v27 API v2 SWIM v15 VID 0x0483 PID 0x374B
Info : using stlink api v2
Info : Target voltage: 2.900414
Info : stm32f3x.cpu: hardware has 6 breakpoints, 4 watchpoints

Clone the Discovery repository and build the led-roulette example (it's not actually a led-roulette at this point, but it's a good example for using the gdb debugger).

git clone https://github.com/rust-embedded/discovery.git
cd discovery/src/05-led-roulette/
cargo build --target thumbv7em-none-eabihf

Making sure openocd is still running in another terminal, connect to the device with gdb.

Note: If you're running Linux or Windows, or installed the ARM toolchain without homebrew, the gdb command may be slightly different. See the "Flash It" section of the Discovery book.

$ arm-none-eabi-gdb -q target/thumbv7em-none-eabihf/debug/led-roulette
Reading symbols from target/thumbv7em-none-eabihf/debug/led-roulette

This will drop you into a gdb shell where you can execute the following commands to connect to the target, load the executable, set a breakpoint, and generally debug the code, with gdb commands like next and step.

(gdb) target remote :3333
Remote debugging using :3333
0x00000000 in ?? ()
(gdb) load
Loading section .vector_table, size 0x188 lma 0x8000000
Loading section .text, size 0x4102 lma 0x8000188
Loading section .rodata, size 0xf20 lma 0x8004290
Start address 0x8003df0, load size 20906
Transfer rate: 19 KB/sec, 5226 bytes/write.
(gdb) break main
Breakpoint 1 at 0x800018c: file src/05-led-roulette/src/main.rs, line 9.
(gdb) continue
(gdb) layout src

Improving the Terminal Experience

Eventually we'll want to use the built in debugging capabilities of VS Code, but first let's make a few adjustments to our cargo configuration to make our lives a bit easier.

First, we'll script our gdb session to automatically load the latest code and advance us to main instead of pre-init.

openocd.gdb

target remote :3333
load
break main
continue

Then, we can update our .cargo\config to use this script as part of the runner, as well as set the default build target.

[target.thumbv7em-none-eabihf]
runner = "arm-none-eabi-gdb -q -x openocd.gdb"
rustflags = [
  "-C", "link-arg=-Tlink.x",
]

[build]
target = "thumbv7em-none-eabihf"

Now, if we run cargo run, we'll automatically build for the correct target and run our gdb script.

$ cargo run
   Compiling led-roulette v0.1.0 (/Users/rubberduck/src/discovery/src/05-led-roulette)
    Finished dev [unoptimized + debuginfo] target(s) in 0.18s
     Running `arm-none-eabi-gdb -q -x openocd.gdb /Users/rubberduck/src/discovery/target/thumbv7em-none-eabihf/debug/led-roulette`
Reading symbols from /Users/rubberduck/src/discovery/target/thumbv7em-none-eabihf/debug/led-roulette...
main () at src/05-led-roulette/src/main.rs:10
10          let x = 42;
Loading section .vector_table, size 0x188 lma 0x8000000
Loading section .text, size 0x66a lma 0x8000188
Loading section .rodata, size 0x2c4 lma 0x8000800
Start address 0x8000196, load size 2742
Transfer rate: 8 KB/sec, 914 bytes/write.
Breakpoint 1 at 0x800018c: file src/05-led-roulette/src/main.rs, line 10.
Note: automatically using hardware breakpoints for read-only addresses.

Breakpoint 1, main () at src/05-led-roulette/src/main.rs:10
10          let x = 42;
(gdb)

Setting up Visual Studio Code

We'll need a couple of extensions from the marketplace.
Go ahead and install the Rust Language Server and Cortex-Debug extensions from the marketplace.

Next, we'll add a new launch configuration.

.vscode/launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "cortex-debug",
            "request": "launch",
            "servertype": "openocd",
            "cwd": "${workspaceRoot}",
            "executable": "./target/thumbv7em-none-eabihf/debug/led-roulette",
            "name": "Debug (OpenOCD)",
            "device": "STM32F303VCT6",
            "configFiles": [
                "interface/stlink-v2-1.cfg",
                "target/stm32f3x.cfg"
            ],
            "runToMain": true
        }
    ]
}

Notice that the configFiles property contains the same list of files that we passed to openocd earlier. Ensure you've stopped openocd in the other terminal, run the default build task (CMD + Shift + B), and then start the debug session. The code will break just inside of the main method. You're currently debugging the code running on the Discovery board from VS Code! You can step over and into the code, as well as see the current values of the individual registers under "CORTEX REGISTERS".

You may notice that there is also a "CORTEX PERIPHERALS" section in the debug sidebar, but it says "No SVD File Loaded: undefined". Let's fix that now. Download the SVD files and extract them. Copy STM32F303.svd into the src/05-led-roulette directory and add the following line to the launch.json file.

{
    "type": "cortex-debug",
    "request": "launch",
    "servertype": "openocd",
    //...
    "svdFile": "${workspaceRoot}/STM32F303.svd"
}

The next time you start the debugger, you'll now see all of the STM32F303's peripherals loaded. You can even directly write hex values to them!

Logging

The ARM Cortex M3 series has an Instrumentation Trace Macrocell (ITM) for sending log statements via the debugger. The Rust itm and panic-itm crates use this to send println and panic messages back to your development machine. Doing this from the terminal is described in Chapter 6: Hello World of the Discovery book. It's worth while running through that excercise before the next section. Note that you either need to jump pins SWO and PB3 or close solder bridge SB10 on the underside of the board. I opted for the latter as it's a pretty simple job to solder the bridge closed. If you're uncomfortable with, or don't have a solder iron, don't worry, the jumper wire works just fine too.

You're back? Awesome! Let's integrate itm into our editor too!

Copy .vscode/launch.json and .cargo/config from the 05-led-roulette directory into the 06-hello-world directory. Then modify the executable path and add the following swoConfig to your launch.json file.

launch.json

"executable": "./target/thumbv7em-none-eabihf/debug/hello-world",
//...
"swoConfig": {
    "enabled": true,
    "cpuFrequency": 8000000,
    "swoFrequency": 2000000,
    "source": "probe",
    "decoders": [
        { "type": "console", "label": "ITM", "port": 0 }
    ]
},

This is essentially equivalent to the gdb commands we ran from the Discovery book.

(gdb) # globally enable the ITM and redirect all output to itm.txt
(gdb) monitor tpiu config internal itm.txt uart off 8000000

(gdb) # enable the ITM port 0
(gdb) monitor itm port 0 on

We enable the monitor, tell the debugger that the CPU is running at 8MHz (the default clock speed for the STM32F303x controllers) and connect to ITM port 0 at 2MHz. Instead of writing the output to a specific file, the Cortex-Debug extension will create a new temporary file for us.

Build the program and begin debugging.
Navigate to the OUTPUT and select the SWO: ITM[port:0, type: console] output.
Step over the iprintln and you'll see the message written to the log.

If you run the panic example, you'll see the panic message printed to the log.

[2019-11-29T18:04:58.320Z]   panicked at 'Hello, world!', src/06-hello-world/src/main.rs:19:5

Automatically Build Before Uploading/Debugging

Up until this point, we've had to manually run cargo build prior to debugging any time we've changed the code. I've frustrated myself more than once by forgetting to do this, so I added a preLaunchTask to automatically build before upload. The build task is just the default cargo build task, but we need to add a label to it to be able to reference it from launch.json.

.vscode/tasks.json

{
    "label": "build",
    "type": "cargo",
    "subcommand": "build",
    "problemMatcher": [
        "$rustc"
    ],
    "group": {
        "kind": "build",
        "isDefault": true
    }
},

.vscode/launch.json

"preLaunchTask": "build",

Now when we press the "play" button to debug, we ensure we've compiled the latest version of our code first.

Full Config Files

That's about it. We have a fully functioning development environment in VS Code. Complete config files are below. Enjoy!

.vscode/tasks.json

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "type": "cargo",
            "subcommand": "build",
            "problemMatcher": [
                "$rustc"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        }
    ]
}

.vscode/launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "cortex-debug",
            "request": "launch",
            "name": "Debug (OpenOCD)",
            "servertype": "openocd",
            "cwd": "${workspaceRoot}",
            "executable": "./target/thumbv7em-none-eabihf/debug/compass",
            "preLaunchTask": "build",
            "device": "STM32F303VCT6",
            "configFiles": [
                "interface/stlink-v2-1.cfg",
                "target/stm32f3x.cfg"
            ],
            "svdFile": "${workspaceRoot}/STM32F303.svd",
            "runToMain": true,
            "swoConfig": {
                "enabled": true,
                "cpuFrequency": 8000000,
                "swoFrequency": 2000000,
                "source": "probe",
                "decoders": [
                    { "type": "console", "label": "ITM", "port": 0 }
                ]
            }
        }
    ]
}

.cargo/config

[target.thumbv7em-none-eabihf]
# Not used by the VS Code Debugger, only `cargo run`
runner = "arm-none-eabi-gdb -q -x openocd.gdb"
rustflags = [
  "-C", "link-arg=-Tlink.x",
]

[build]
target = "thumbv7em-none-eabihf"

openocd.gdb

# Not used by the VS Code Debugger, only `cargo run`
target remote :3333
set print asm-demangle on
set print pretty on
load
monitor tpiu config internal itm.txt uart off 8000000
monitor itm port 0 on
break main
continue

Using USB with Docker for Mac

Christopher McClellan — Sun, 21 Apr 2019 13:37:50 +0000

If you've been struggling with this issue and just want an answer, skip to the bottom for the TL;DR. I won't fault you for it.

Docker is a great tool for deploying web services, but one of my favorite uses for it is standardizing toolchains. Instead of everyone on the team needing to setup their development environments identically, and then keep them in sync, you define the build tools in a single place, a docker image. Then everyone, including your build server, uses that single pre-packaged image.

Not only is this great for teams, but it's also fantastic when you have side projects that you only periodically revisit. Without fail, when I come back to some old project, I've since updated my tools for something newer, and I can't build that old project without either upgrading the project or degrading my tools. Leaving a build tools image behind means I can just pick it up and work on it without spending a day getting back up and running.

It's not all sunshine and roses though. I went on quite an adventure today. Last year I put on a TDD for Arduino workshop. I had started to create a Docker image for AVR development, but ran into problems when it came time to flash the program to the board. Exposing a USB port to a docker container on Mac isn't exactly a trivial task (until you know how at least!). For that session we mobbed, so I only had to setup one machine. I just stopped fighting with it and went with a regular install of the tools on my machine.

Recently though, I've taken a renewed interest in getting this to work properly. First, I've been playing with ARM development, but there's a bug in AVR and ARM's compiler packaging that means you can't have both toolchains installed at the same time. Having these toolchains containerized means I can easily keep both readily available. Secondly, I'm now beginning to build on that workshop to turn it into an "Intro to Bare Metal Programming" course. For that, I really need to be able to hand folks an environment I know works, so we're not spending more time working kinks out of dev setups than learning. Also, in order to standardize embedded toolchains for a team or client at work, I really need to know how to get USB working on Mac.

If you're running Linux, this is as simple as adding --device /dev/ttyUSBx to the docker run command. Needless to say, it's not that simple on OSX or Windows. That's because the docker daemon only runs natively on Linux. For other operating systems it's run in a hypervisor or virtual machine. In order to expose the port to the container, you first have to expose it to the virtual machine where Docker is running. Unfortunately, hyperkit, the hypervisor that Docker-For-Mac uses doesn't support USB forwarding.

Since we can't expose a USB port to the native Mac Docker hypervisor, we have to fallback onto docker-machine, which uses a Virtualbox VM to host the dockerd daemon. There are great instructions for setting up docker-machine with a USB filter, but I was getting a lot of mysterious segfaults from docker-machine that would leave my VM running, but also unable to recover a connection to it through docker-machine. It turns out that several versions of VirtualBox had a bug causing the segfaults. Upgrading to v6.06 solved that problem, but I still couldn't see the device. It took me too long to remember that I had the same trouble with USB 3.0 a few months ago with a Windows guest OS. Dropping down to USB 2.0 fixed that issue.

Okay, let's get down to business and get a fully containerized embedded toolchain running on Mac.

First, download and install VirtualBox version 6.06 or greater. Again, this must be version 6.06 or greater or you'll see segfaults when trying to create a USB filter later. You can optionally install the VirtualBox extension pack. I recommend it though, because it enables USB 2.0, which results in faster programming times.

Next, we can create and setup our docker-machine (virtual machine).

#! /bin/bash
#create and start the machine
docker-machine create -d virtualbox default

#We must stop the machine in order to modify some settings
docker-machine stop

#Enable USB
vboxmanage modifyvm default --usb on

# OR, if you installed the extension pack, use USB 2.0
vboxmanage modifyvm default --usbehci on

# Go ahead and start the VM back up
docker-machine start

# Official Arduinos and many clones use an FTDI chip.
# If you're using a clone that doesn't, 
# or are setting this up for some other purpose
# run this to find the vendor &amp;amp;amp;amp;amp;amp;amp;amp; product id for your device.
# vboxmanage list usbhost

# Setup a usb filter so your device automatically gets connected to the Virtualbox VM.
vboxmanage usbfilter add 0 --target default --name ftdi --vendorid 0x0403 --productid 0x6015

#setup your terminal to use your new docker-machine
#(you must do this every time you want to use this docker-machine or add it to your bash profile)
eval $(docker-machine env default)

Now go ahead and plug in your device and run this command to verify that containers can see it.

docker run --rm -it --device /dev/ttyUSB0 ubuntu:18.04 bash -c "ls /dev/ttyUSB0"

If the command fails, make sure your device is plugged in and visible to the VM. You may have mistyped the vendor and product ids, or the tty may be attached under a different number.

docker-machine ssh default "ls /dev/tty*"

That's it. Like I said, it's really easy once you know how. Unfortunately, there's not official documentation and, considering that both docker-machine and boot2docker are in maintenance mode, I'm hoping we get official support for USB on hyperkit in the future. Containerizing build tools is a great way for teams to take advantage of the technology even if you're not using them to deploy services. Now, if you'll excuse me, I need to go update my AVR toochain image with a script to do this and add in avrdude for uploading programs.

Until next time,
Semper Cogitet

Test Driving Arduino

Christopher McClellan — Fri, 16 Feb 2018 03:36:33 +0000

Originally posted on christopherjmcclellan.wordpress.com.

I gave a workshop for the Columbus Arduino and Raspberry Pi Enthusiasts (CARPE) Tuesday night. We had a great time and I thought it would be a good idea to share the experience and my motivation creating the workshop here.

The Arduino IDE isn't what I'd call good. It's great for someone new to programming or microcontrollers. It gets you from zero to blinking a light in seconds, but lacks a lot of features that seasoned programmers rely on. It has a myriad of problems.

No file browser.
No terminal.
No code navigation (like "Go to declaration").
Code is hidden away where it's hard find and get into source control.
No way to create automated unit tests.
Arduino libs aren't always well behaved (SoftwareSerial and OneWire are notorious for globally disabling interrupts).

A few months ago I set out to see if I could some of these problems. My main goal was to be able to TDD microcontroller code. The secondary goal was to be able to use whichever editor I liked. I figured I would probably need to use a different editor anyway.

Before I got started, I picked up a copy of "Test Driven Development For Embedded C" by James Grenning. I wanted to know if what I wanted to do was even possible before I got started. It turns out that it's largely very testable, even if not many people out there are doing TDD for embedded systems. There are some things that are legitimately hard to test, but I'll get to that later.

James gives an example of doing TDD for a LED Driver in the book. That inspired me to create the LED Driver Kata. The premise is pretty simple. You need to create a LED driver to light up some LEDs memory mapped to an 8 bit register. The problem is, the hardware isn't ready yet. How do we write and, perhaps more importantly, test code for hardware that doesn't exist yet? James gives examples in his book, but the most important for me was the idea of faking the register out by passing a reference to an unsigned integer to the driver. This allows us not only to observe the results of the code, but also means the driver code isn't dependent on the hardware. It looks something like this.

TEST(LedDriverTests, TurnAllLedsOn)
{
volatile uint8_t leds = 0xFF;
LedsOn(&leds);
BYTES_EQUAL(0x00, leds);
}

The other core concept is cross-compiling your code. The code under test gets compiled along with your tests for the host machine. Your tests run on your development machine. Once the tests pass, then you compile for the target device's architecture.

Now that I knew it was indeed feasible to test drive embedded code, I set out to implement the kata.

The secret here is that Arduino is built on top of the pre-existing AVR toolchain. Arduino uses the avr-gcc compiler and AVRDude under the hood to compile and upload to the board. You can see this yourself by going to File -> Preferences and selecting the "Show Verbose Output" options.

Arduino installs the toolchain inside it's application directory, but I found it convenient to just install the tools separately. If you're running Windows, the toolchain is available via WinAVR. If you're running a *nix system, just go check out the AVR docker image I created. It lists out the different apt packages you'll need, including the CppUTest testing framework.

I started out compiling by hand, but it didn't take me long to start fumbling my way through creating a Makefile. In fact, the first time I did the kata, I spent far more time working on crafting a Makefile than I did working on the code. The LED Driver kata turned out to be 2 katas in one. Thankfully, I only needed to work that out once. I turned that Makefile into a reusable template for all my AVR projects. Just clone the project add some code. I've actually been using this setup for the digital thermometer I'm building too. It works really well.

I can use any text editor and terminal.
I've TDD'ed most of the implementation.
No worries about Arduino libs misbehaving, because I'm not using them.

There are a few downsides to this approach though.

No Arduino libs + no Arduino IDE means no serial monitor. To be honest though, I've rarely missed it because I have a test suite.
Not everything is unit testable.

For example, consider some external device that requires a very quick pin pulse.

void ShiftRegister::pulse(uint8_t bitmask)
{
    // pull the pin high to clock the data,
    // then back to low so we choose when to send it.
    port.DataOut |= bitmask;
    port.DataOut &= ~bitmask;
}

There's no way to observe the side effect from the test. By time the test has finished executing, the register is back in its original state. I suppose this could be solved with a layer of indirection and some mocking, but the code is obviously correct by sight. I'm okay with leaving this as it is.

Anyway, that's a fairly long winded way of providing some context for what we did at the workshop the other night. I cloned a fresh copy of the template and introduced the group to the kata. Next I gave them the rules of the game. We'd be Mob Programming the kata together. The person at the keyboard would type what the group told them to type. That person isn't allowed to think. If they have an idea, they must give the keyboard to someone else and instruct that person on what to type next. When we were done, we'd upload it to an Arduino hooked up to a bank of 8 LEDs.

I got the group started by writing the first test. Things were a bit bumpy out of the gate. I was live coding in front of an audience after a full day's work and couldn't get the test to pass. After a few minutes someone pointed out that I was setting the value to the exact opposite of the expected value. I thanked him, laughed, and passed off the keyboard. People were very hesitant at first, but pretty soon the group had found their rhythm. One by one tests would go red then green. Once in a while I'd interject with some insight or a refactor to try.

Eventually I wasn't paying much attention to the code at all. I started wandering around talking to the folks who were a bit too reserved to actively participate. I found there was an interesting mix of questions. Some people were asking me about TDD, some about microcontrollers and embedded programming. There were very few people in the room who had done both and, as far as I could tell, none who had done TDD with embedded C++.

Suddenly I heard "Hey Chris! We're done! How do we upload this thing to the board?" They took me by surprise. Before we started, I was worried that we wouldn't have time to finish the kata. I ran back to the keyboard and wrote a quick loop in the main to flash the lights in sequence, then burned the program. It worked. It. Just. Worked. We all kind of marveled at the power of the mob and TDD for a moment as our device driver worked the very first time we flashed it to the board.

Well... it almost worked. There was one light that wasn't lighting up. I instantly suspected the loop I wrote without any tests, but then someone piped up, "The code works. The tests pass and we all saw you write that loop. The code is right. It's a hardware bug." By golly they were right too. We fiddled with the breadboard for just a moment before that stubborn little light lit up.

This was precisely the point of the whole exercise. We knew the code worked because every single line of code was tested and reviewed by an entire room full of programmers. This narrowed the search space for the bug down to the only place it could have been. It was fixed within moments.

I really couldn't be happier with how things went. Even though I screwed up by live coding instead of preparing the first test before hand, the power of collective problem solving and test driven development really shined through. Most importantly though, we proved that not only can embedded code be tested, but that people with little experience can do it if given the right tools and support.

How to See Memory and CPU Usage for All Your Docker Containers (on CentOS 6)

Christopher McClellan — Sat, 22 Jul 2017 19:43:50 +0000

Originally posted on my blog.

I run a bunch of Docker containers on a single CentOS 6 server with a limited amount of memory. (I only recently bumped it from 0.5 to 1 whole whopping gig!) Before I bring another container online, I like to check to see how much room I've got. Being the newest versions of Docker aren't available for CentOS 6, I'm running an ancient version, 1.7 or so. On the new versions of Docker, running docker stats will return statistics about all of your running container, but on old versions, you must pass docker stats a container id. Here's a quick one-liner that displays stats for all of your running containers for old versions.

$ docker ps -q | xargs  docker stats --no-stream
CONTAINER           CPU %               MEM USAGE/LIMIT     MEM %               NET I/O
31636c70b372        0.07%               130.8 MB/1.041 GB   12.57%              269.7 kB/262.8 kB
8d184dfbeeaf        0.00%               112.8 MB/1.041 GB   10.84%              45.24 MB/32.66 MB
a63b24fe6099        0.45%               50.09 MB/1.041 GB   4.81%               1.279 GB/1.947 GB
fd1339522e04        0.01%               108.2 MB/1.041 GB   10.40%              8.262 MB/23.36 MB

docker ps -q returns the list of running container ids, which we then pipe through xargs and into docker stats. Adding --no-stream gives us just the first result instead of continually updating the stats, but this works just fine without it.

It’s a neat little trick. If anyone knows how to make this return container names instead of ids, please comment below.

Again, this is unnecessary for the newest versions. Just run docker stats and you'll get nearly identical output.

~Semper Cogitet