/nerves

Craft and deploy bulletproof embedded software in Elixir

Primary LanguageElixirApache License 2.0Apache-2.0

Nerves

Backers on Open Collective Sponsors on Open Collective CircleCI Hex version

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 GitHub release (latest SemVer)
Nerves.Bootstrap The Nerves new project generator and low level hooks into Mix Hex.pm
Nerves.Runtime Small, general runtime utilities for Nerves devices Hex.pm
NervesPack Initialization setup for Nerves devices Hex.pm
NervesSystemBR Buildroot based build platform for Nerves Systems Hex.pm
RingLogger A ring buffer backend for Elixir Logger with IO streaming Hex.pm

Example projects

Name Description Release
Circuits Quickstart Try out Elixir Circuits with prebuilt Nerves firmware GitHub release (latest SemVer)
NervesExamples Small example programs using Nerves
Nerves Livebook Develop on embedded devices with Livebook and Nerves GitHub release (latest SemVer)

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 Hex.pm
NervesSystemOSD32MP1 Base system for Octavo OSD32MP1 Hex.pm
NervesSystemRPi Base Nerves system configuration for the Raspberry Pi A+ and B+ Hex.pm
NervesSystemRPi0 Base Nerves system configuration for the Raspberry Pi Zero and Zero W Hex.pm
NervesSystemRPi2 Base Nerves system configuration for the Raspberry Pi 2 Hex.pm
NervesSystemRPi3 Base Nerves system configuration for the Raspberry Pi 3 Hex.pm
NervesSystemRPi3A Nerves system for the Raspberry Pi 3 Model A+ w/ gadget mode and Raspberry Pi Zero 2 W Hex.pm
NervesSystemRPi4 Base Nerves system configuration for the Raspberry Pi 4 Hex.pm
NervesSystemVultr Experimental configuration for a Vultr cloud server Hex.pm
NervesSystemX86_64 Generic Nerves system configuration x86_64 based hardware Hex.pm
NervesSystemGrisp2 Base Nerves system configuration for the GRiSP 2 Hex.pm

Networking

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

Hardware access

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

SSH and Shell

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

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 Hex.pm
nerves_toolchain_aarch64_nerves_linux_gnu 64-bit ARM toolchain Hex.pm
nerves_toolchain_armv5_nerves_linux_musleabi 32-bit ARM toolchain for older ARM processors Hex.pm
nerves_toolchain_armv6_nerves_linux_gnueabihf 32-bit ARM toolchain for Raspberry Pi A, B, and Zero Hex.pm
nerves_toolchain_armv7_nerves_linux_gnueabihf 32-bit ARM toolchain for most 32-bit ARMs Hex.pm
nerves_toolchain_i586_nerves_linux_gnu 32-bit Intel x86 toolchain Hex.pm
nerves_toolchain_mipsel_nerves_linux_musl 32-bit MIPS toolchain Hex.pm
nerves_toolchain_riscv64_nerves_linux_gnu 64-bit RISC-V toolchain Hex.pm
nerves_toolchain_x86_64_nerves_linux_musl 64-bit x86 toolchain using the musl libc Hex.pm
nerves_toolchain_x86_64_nerves_linux_gnu 64-bit x86 toolchain using GNU libc Hex.pm

Miscellaneous

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

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 Hex.pm
NervesUEvent Simple UEvent monitor for detecting hardware and automatically loading drivers Hex.pm
PropertyTable In-memory key-value store with subscriptions Hex.pm
nerves_initramfs An initramfs for early boot handling of Nerves devices GitHub release (latest SemVer)
nerves_system_linter Mix task to check Nerves system configuration files Hex.pm
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 Hex.pm
system_registry Serial nested term storage and dispatch registry Hex.pm
system_registry_term_storage Simple term storage for SystemRegistry Hex.pm
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]

Copyright (C) 2015-2021 by the Nerves Project developers nerves@nerves-project.org