HowTo (Mac) - Upload

Note: This page discusses ways (both current and prospective) of uploading Nerves system images to target machines. It assumes that you have successfully completed the [Install]] and [Build]] steps.


Depending on the available hardware on the target machine, it may be possible to upload images in any of several ways. Writing an SD card is the simplest approach, but it requires quite a bit of fine physical manipulation. Wired or wireless networking, which require more setup, may actually be much more convenient over time.

In order to run a Nerves app on (say) a Raspberry Pi, the Pi's Micro SD Card must be formatted and loaded with the app's system image. Once this has been accomplished, however, it should be possible to update system images by means of wired or wireless data communication.

Micro SD Card

In this approach, we remove the SD card from the target, update it on the build machine (aka "host"), and then move it back to the target. Adaptors are readily (and economically) available, if need be, for full-size SD and USB sockets.

SD cards transfers data at 6-30 MB/s, depending on the Speed Class, so a 30 MB system image could take one to five seconds to upload. In addition, there is the time involved in manipulating the card.


In theory, here's the way to create the SD card on a Mac host:

  • Remove the SD card from the target computer, if need be.
  • Plug the card (via any needed adaptor) into the Mac.
  • Burn the firmware image and eject the SD card.


After putting the card into a full-size SD adaptor and plugging it into my MacBook Air, I entered:

$ mix firmware.burn
** (Mix) Could not auto detect your SD card

Disk Utility couldn't detect the card either, so (on a guess) I tried unplugging and replugging the adaptor. Yep; it hadn't been seated all the way! After reseating the card, I tried again:

$ mix firmware.burn
Use 29.29 GiB memory card found at /dev/rdisk2? [Yn] 
fwup: eject failed: 0xc010 (49168) (null))

For unknown reasons, fwup consistently failed to eject the SD Card. However, the workaround is easy: eject the APPDATA drive using the Finder, choosing the "Eject All" button.


The Raspberry Pi 3B hardware supports both Ethernet (10/100Base-T) and Wi-Fi (2.4GHz 802.11n wireless). Assuming that the target's running image is set up to support one of these (per the Network HowTo), it should be possible to update the other image using Nerves.Firmware.HTTP.


100Base-T (Ethernet) transfers data at 100 Mb/s (~12 MB/s), so a 30 MB system image should take about three seconds to upload. 802.11n (Wi-Fi) transfers data at 50-600 Mb/s (~6-100 MB/s), so an image could take one to five seconds to upload.


Nerves.Firmware is an Elixir API for upgrading and managing firmware on a Nerves device. It leans heavily on Frank Hunleth's excellent fwup (firmware update) utility, which is included of the standard Nerves configurations.

Nerves.Firmware.HTTP is an HTTP / REST micro service providing over-the-network firmware management. It starts a small Cowboy instance that returns status about the current firmware and accepts updates to the firmware via a REST-style interface.

To be continued...

Client / Server

It should also be possible to update an system image using some form of client / server communication (e.g., Bluetooth, USB). However, I don't know of any work in this area at the moment.


The Raspberry Pi 3B has built-in Bluetooth (Bluetooth 4.1 Classic, Bluetooth Low Energy). Bluetooth 4.0 transfers data at 250 Mb/s (~40 MB/s), so a 30 MB system image should take about a second to upload.

The current systems do not have Bluetooth drivers included, so that's not an out of the box option.

-- @tattdcodemonkey, on the Nerves Slack channel


Some Raspberry Pi models (including the 2B and 3B) have multiple (e.g., 4) USB sockets. USB 2 transfers data at 480 Mb/s (~60 MB/s), so a 30 MB system image should take about a half a second to upload.

This wiki page is maintained by Rich Morin, an independent consultant specializing in software design, development, and documentation. Please feel free to email comments, inquiries, suggestions, etc!

Topic revision: r15 - 19 Jul 2016, RichMorin
This site is powered by Foswiki Copyright © by the contributing authors. All material on this wiki is the property of the contributing authors.
Foswiki version v2.1.6, Release Foswiki-2.1.6, Plugin API version 2.4
Ideas, requests, problems regarding CFCL Wiki? Send us email