nerves

Craft and deploy bulletproof embedded software in Elixir

2,230

189

2,230

Quick Overview

Nerves is an open-source platform and set of tools for building and deploying embedded software for IoT devices using Elixir. It provides a complete framework for creating, managing, and updating firmware for various hardware platforms, focusing on reliability and ease of use for developers.

Pros

Streamlined development process for embedded systems using Elixir
Built-in support for OTA (Over-the-Air) updates
Extensive hardware support for various platforms (Raspberry Pi, BeagleBone, etc.)
Strong focus on security and reliability

Cons

Steep learning curve for developers new to Elixir or embedded systems
Limited community size compared to more mainstream embedded development platforms
Some hardware platforms may have limited support or documentation
Resource constraints on smaller devices may limit the use of certain Elixir features

Code Examples

Creating a new Nerves project:

mix nerves.new my_project
cd my_project
export MIX_TARGET=rpi3
mix deps.get
mix firmware

This code creates a new Nerves project, sets the target hardware to Raspberry Pi 3, fetches dependencies, and builds the firmware.

Configuring WiFi in a Nerves project:

config :nerves_network,
  regulatory_domain: "US"

config :nerves_network, :default,
  wlan0: [
    ssid: "your_wifi_name",
    psk: "your_wifi_password",
    key_mgmt: :"WPA-PSK"
  ]

This configuration sets up WiFi connectivity for a Nerves device.

Implementing a simple LED blink example:

defmodule MyProject.Blinker do
  use GenServer

  @led_pin 18

  def start_link(_) do
    GenServer.start_link(__MODULE__, [])
  end

  def init(_) do
    {:ok, gpio} = Circuits.GPIO.open(@led_pin, :output)
    :timer.send_interval(1000, :toggle)
    {:ok, gpio}
  end

  def handle_info(:toggle, gpio) do
    Circuits.GPIO.write(gpio, 1 - Circuits.GPIO.read(gpio))
    {:noreply, gpio}
  end
end

This code implements a simple LED blink example using the Circuits.GPIO library.

Getting Started

To get started with Nerves:

Install Elixir and Erlang
Install the Nerves bootstrap: mix archive.install hex nerves_bootstrap
Create a new project: mix nerves.new my_project
Set the target hardware: export MIX_TARGET=rpi3 (for Raspberry Pi 3)
Get dependencies: mix deps.get
Build firmware: mix firmware
Burn firmware to an SD card: mix firmware.burn

For more detailed instructions and advanced usage, refer to the official Nerves documentation.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Nerves

Craft and deploy bulletproof embedded software in Elixir

Nerves provides tooling and libraries for building small, self-contained software images using the rock-solid Erlang virtual machine hardware support of Linux, and happy development experience of Elixir for microprocessor-based embedded systems.

While the Nerves project provides base runtime libraries for hardware access and network configuration, nearly all of the Elixir ecosystem is available, including:

Phoenix and LiveView for interactive local web user interfaces
Elixir Nx for numerical computing and machine learning
Livebook for interactive code notebooks on your device
Scenic for local on-screen user interfaces

Or just keep it simple and use whatever libraries you need from the Hex package manager. Nerves only includes what you use so your embedded software can remain small.

Nerves uses the Linux kernel to support a large variety of hardware. It is not a Linux distribution, though, and contains little of what you would find on a typical embedded Linux system. Instead, it starts the Erlang runtime as one of the first OS processes and lets Erlang and Elixir take over from there. Not to fear, if you need something from Linux, Nerves provides a way to use most of the packages available through Buildroot.

Nerves Projects

Our project is spread over many repositories in order to focus on a limited scope per repository.

This repository (nerves-project/nerves) is an entrance to Nerves and provides the core tooling and documentation.

The Nerves core team maintains the projects in the nerves-project organization with the help of many in the Elixir community. Projects under other GitHub organizations are maintained by their respective organization, but listed here since they're so commonly used in conjunction with the core libraries and tools.

Framework / Core

Name	Description	Release
Erlinit	Replacement for /sbin/init that launches an Erlang/OTP Release
Nerves.Bootstrap	The Nerves new project generator and low level hooks into Mix
Nerves.Runtime	Small, general runtime utilities for Nerves devices
NervesPack	Initialization setup for Nerves devices
NervesSystemBR	Buildroot based build platform for Nerves Systems
RingLogger	A ring buffer backend for Elixir Logger with IO streaming

Example projects

Name	Description	Release
Circuits Quickstart	Try out Elixir Circuits with prebuilt Nerves firmware
NervesExamples	Small example programs using Nerves
Nerves Livebook	Develop on embedded devices with Livebook and Nerves

Hardware

These are the officially supported hardware ports. Many others exist in the community.

Name	Description	Release
NervesSystemBBB	Base Nerves system configuration for the BeagleBone-based boards
NervesSystemOSD32MP1	Base system for Octavo OSD32MP1
NervesSystemRPi	Base Nerves system configuration for the Raspberry Pi A+ and B+
NervesSystemRPi0	Base Nerves system configuration for the Raspberry Pi Zero and Zero W
NervesSystemRPi2	Base Nerves system configuration for the Raspberry Pi 2
NervesSystemRPi3	Base Nerves system configuration for the Raspberry Pi 3
NervesSystemRPi3A	Nerves system for the Raspberry Pi 3 Model A+ w/ gadget mode and Raspberry Pi Zero 2 W
NervesSystemRPi4	Base Nerves system configuration for the Raspberry Pi 4
NervesSystemRPi5	Base Nerves system configuration for the Raspberry Pi 5
NervesSystemVultr	Experimental configuration for a Vultr cloud server
NervesSystemX86_64	Generic Nerves system configuration x86_64 based hardware
NervesSystemGrisp2	Base Nerves system configuration for the GRiSP 2
NervesSystemMangoPiMQPro	Base Nerves system configuration for the MangoPi MQ-Pro

Networking

Name	Description	Release
VintageNet	Network configuration and management for Nerves
VintageNetWiFi	WiFi networking for VintageNet
VintageNetDirect	Direct network connection support for VintageNet
VintageNetEthernet	Ethernet support for VintageNet
VintageNetMobile	Mobile connection support for VintageNet
VintageNetQMI	VintageNet technology support for QMI mobile connections
VintageNetWireGuard	Wireguard VPN support

Hardware access

Name	Description	Release
Circuits.GPIO	Use GPIOs in Elixir
Circuits.I2C	Use I2C in Elixir
Circuits.SPI	Communicate over SPI from Elixir
Circuits.UART	Discover and use UARTs and serial ports in Elixir

SSH and Shell

Name	Description	Release
NervesMOTD	Message of the day for Nerves devices
NervesSSH	Manage an SSH daemon and subsystems on Nerves devices
SSHSubsystemFwup	Erlang SSH Subsystem for Nerves firmware updates
Toolshed	A toolshed of shell-like IEx helpers

Toolchain

Nerves provides a C/C++ cross-toolchain to ensure consistency builds on all supported host platforms. These are built using crosstool-ng and are similar to other GCC toolchains.

Name	Description	Release
nerves_toolchain_ctng	Crosstool-NG integration for building Nerves toolchains
nerves_toolchain_aarch64_nerves_linux_gnu	64-bit ARM toolchain
nerves_toolchain_armv5_nerves_linux_musleabi	32-bit ARM toolchain for older ARM processors
nerves_toolchain_armv6_nerves_linux_gnueabihf	32-bit ARM toolchain for Raspberry Pi A, B, and Zero
nerves_toolchain_armv7_nerves_linux_gnueabihf	32-bit ARM toolchain for most 32-bit ARMs
nerves_toolchain_i586_nerves_linux_gnu	32-bit Intel x86 toolchain
nerves_toolchain_mipsel_nerves_linux_musl	32-bit MIPS toolchain
nerves_toolchain_riscv64_nerves_linux_gnu	64-bit RISC-V toolchain
nerves_toolchain_x86_64_nerves_linux_musl	64-bit x86 toolchain using the musl libc
nerves_toolchain_x86_64_nerves_linux_gnu	64-bit x86 toolchain using GNU libc

Miscellaneous

Name	Description	Release
boardid	Print out a platform-specific board serial number
NervesFWLoaders	A collection of firmware loaders for boards with internal storage
NervesHeart	Erlang heartbeat support for Nerves
Shoehorn	Help handle OTP application failures and start order
UBootEnv	Read and write to U-Boot environment blocks

Upcoming

These projects are new or experimental and are in various stages of being ready to promote to the above categories.

Name	Description	Release
NervesLogging	Route system log messages through the Elixir logger
NervesUEvent	Simple UEvent monitor for detecting hardware and automatically loading drivers
PropertyTable	In-memory key-value store with subscriptions
nerves_initramfs	An initramfs for early boot handling of Nerves devices
nerves_system_linter	Mix task to check Nerves system configuration files
nerves_systems	Build scripts for maintaining multiple repositories	unreleased

See outdated/inactive projects...

Name	Description	Release
nerves_leds	Functions to drive LEDs on embedded systems
system_registry	Serial nested term storage and dispatch registry
system_registry_term_storage	Simple term storage for SystemRegistry
nerves_system_test
nerves_test_server

There is also a gravesite for old Nerves libraries at https://github.com/nerves-project-attic.

Host Requirements

Mac OS 10.13+ (High Sierra and later)
64-bit Linux (tested on Debian / Ubuntu / Redhat / CentOS / Arch)
Windows 10 with Windows Subsystem for Linux 2
Elixir ~> 1.11

See Installation Docs for software dependencies.

Quick-Reference

Generating a New Nerves Application

mix nerves.new my_app

Building Firmware

export MIX_TARGET=rpi3
mix deps.get      # Fetch the dependencies
mix firmware      # Cross-compile dependencies and create a .fw file
mix firmware.burn # Burn firmware to an inserted SD card

Note: The mix firmware.burn target relies on the presence of ssh-askpass. Some users may need to export the SUDO_ASKPASS environment variable to point to their askpass binary. On Arch Linux systems, this is in /usr/lib/ssh/ssh-askpass

Docs

Installation Docs

Getting Started

Frequently-Asked Questions

Systems

Targets

User Interfaces

Advanced Configuration

Compiling non-BEAM code

Customizing Systems

Contributors

This project exists thanks to all the people who contribute.

Please see our Contributing Guide for details on how you can contribute in various ways.

Metal Level Sponsors

Metal level sponsors are companies that allow core team members to maintain and extend Nerves for a portion of each work week. Nerves is not a product of any one company. We also have a soft spot for supporting makers and hobbyists using the BEAM, and it would be difficult to do this without them.

[Become a metal level sponsor]

OpenCollective Backers

Thank you to all our monetary backers! Hardware costs money and without support, we wouldn't be able to support nearly as many devices. ð [Become a backer]

OpenCollective Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot