Nerves basics

Print Cheatsheet Copy Markdown View Source

Terminology

TermDefinition
hostThe computer on which you are editing source code, compiling, and assembling firmware
targetThe platform for which your firmware is built (for example, Raspberry Pi Zero W, Raspberry Pi 4, or Beaglebone Black)
toolchainThe tools required to build code for the target, such as compilers, linkers, binutils, and C runtime
systemA lean Buildroot-based Linux distribution that has been customized and cross-compiled for a particular target
firmware bundleA single file with the extension .fw that contains your compiled application and everything else needed to run on your target
firmware imageBuilt from a firmware bundle. It's a raw representation of what's on the MicroSD card. These aren't used in normal development and firmware updates.

Nerves systems

Nerves systemMIX_TARGETHardware
nerves_system_rpirpiRaspberry Pi A+, B, B+
nerves_system_rpi0rpi0Raspberry Pi Zero and Zero W
nerves_system_rpi2rpi2Raspberry Pi 2
nerves_system_rpi3rpi3Raspberry Pi 3 B, B+
nerves_system_rpi3arpi3aRaspberry Pi 3A and Zero 2 W (32-bit)
nerves_system_rpi0_2rpi0_2Raspberry Pi Zero 2 W and 3A (64-bit)
nerves_system_rpi4rpi4Raspberry Pi 4
nerves_system_rpi5rpi5Raspberry Pi 5
nerves_system_bbbbbbBeagleBone Black, Green, Green Wireless, and PocketBeagle
nerves_system_osd32mp1osd32mp1OSD32MP1
nerves_system_x86_64x86_64Generic x86_64
nerves_system_grisp2grisp2GRiSP 2
nerves_system_mangopi_mq_promangopi_mq_proMangoPi MQ Pro

While the Nerves core team only officially supports the above hardware, the community has added support for other boards. See Nerves Systems on hex.pm.

Useful shell commands

Making a new firmware from scratch

Creating a Nerves application

$ mix nerves.new hello_nerves
$ cd hello_nerves

Specifying Nerves target

$ export MIX_TARGET=<target>

Installing dependencies

$ mix deps.get

Building firmware

$ mix firmware

Creating a bootable MicroSD card

$ mix burn

The mix burn command discovers any MicroSD cards on your computer. It will confirm before writing the card.

Uploading firmware to a Nerves device over SSH

$ export MIX_TARGET=<target>
$ mix upload nerves.local

Substitute nerves.local with nerves-abcd.local when you have multiple Nerves devices.

Connecting to the target over SSH

Testing the network connection

$ ping nerves.local

Making the network connection

$ ssh nerves.local

Connecting to the target with a serial cable

Serial ports

On boards with USB gadget support (e.g., rpi0, rpi0_2, bbb), the IEx prompt is available over a virtual serial port on the USB cable. Other boards (e.g., rpi5) require a separate USB-to-serial adapter. Serial devices show up as /dev/tty.usbmodem* or /dev/ttyUSB0.

Using screen

$ screen /dev/tty<device> 115200

Exit screen with CTRL+A, CTRL+\

Using picocom

$ picocom -b 115200 /dev/tty<device>

Exit picocom with CTRL+A, CTRL+X

Misc

Printing Nerves information

$ mix nerves.info

Discovering Nerves devices on the local network

$ mix nerves.discover

Listing Nerves artifacts cached locally

$ ls ~/.nerves/artifacts

Listing Nerves downloads cached locally

$ ls ~/.nerves/dl

If $XDG_DATA_HOME is set, Nerves stores data under $XDG_DATA_HOME/nerves/ instead of ~/.nerves.

Useful IEx commands

Firmware

iex> uname
iex> reboot
iex> Nerves.Runtime.revert
iex> Nerves.Runtime.KV.get_all
iex> NervesMOTD.print

Logging

iex> log_attach
iex> log_detach
iex> RingLogger.viewer

Linux commands

iex> cmd "ps"
<CTRL+R>text to find

Misc

iex> h Toolshed
iex> hostname
iex> top
iex> weather
iex> cat "/proc/cpuinfo"
iex> hex 255