Connecting to a Nerves Target

There are multiple ways to connect to your Nerves target device and different target may support different connection methods.

The default features are different depending on Nerves targets. For example, some Nerves targets support a UART serial console by default; others, HDMI and USB keyboard instead.

USB to TTL serial cable (UART)

A target device can be accessed via a serial connection with a USB to TTL serial cable, which is connected between the host USB port and a couple of header pins on the target.

This connection method allows you to interact with the console of the target device using a terminal emulator program on your development host. It is useful for debugging networking or the boot process and for advanced development workflows.

First of all, locate the documentation of the Nerve system that corresponds to your target device, and find out how your Nerves system supports the IEx terminal feature.

As an example, as of this writing, the documentation of nerves_system_rpi0 (a Nerves system for Raspberry Pi Zero) says the system supports one UART port named ttyAMA0 available for IEx terminal. It is /dev/ttyAMA0 in the file system.

It is configured here in the nerves_system_rpi0 source code.

On the Raspberry Pi Zero, the UART that is known as UART0 in the hardware descriptions is routed to pins 8 and 10.

On Linux on the Raspberry Pi Zero, UART0 is exposed as the device file /dev/ttyAMA0.

Get a USB-to-TTL serial cable

We've had good luck with this cable if you haven't already found one.

You may need to install to your host machine the driver software for the cable. If you use the above-mentioned cable, Adafruits provides this guide.

Connect the leads

Image credit: https://pinout.xyz

For visual learners, Adafruit's Raspberry Pi Lesson has some helpful images.

Run a terminal emulation program

The USB-to-TTL serial cable converts the text into a standard serial USB port. There are multiple open source terminal emulator programs out there that support the serial console.

• picocom
• bootterm
• screen
• tio

As an example, on a macOS host machine, you can open a terminal and try these commands.

List TTY devices available

ls /dev/tty*

Start communication with the Raspberry Pi using picocom

picocom -b 115200 /dev/ttyUSB0

Replace ttyUSB0 with the TTY device that has the USB-to-TTL serial cable. They usually have the letters "USB" somewhere in the name.

You should be at an iex(1)> prompt. If not, try pressing Enter a few times.

Troubleshooting

First boot shows error messages

First boot shows error messages due to the file system not being formatted. Seems like something is wrong even though it isn't. This is visible if you attach to the UART and watch the messages the very first time that you boot off a MicroSD card.

Toolshed's exit not working in the serial console

It works, but Erlang doesn't automatically restart the shell. You should be able to type CTRL-G to get the Erlang job menu.

"could not find a PTY" Error when running screen command

Unplug the USB connector and re-plug it.

HDMI cable

On some Raspberry Pi family of targets such as rpi3 and rpi4, the IEx console is displayed on the screen attached to the HDMI port by default. You can simply connect your target device to a monitor or TV.

For troubleshooting start-up issues and for more advanced development workflows, it's desirable to connect from your development host to the target using a UART serial cable.

Here is how to override the default, for rpi3 as an example:

1. Look in the README of your target's system's documentation for a UART port name. For example, nerves_system_rpi3
2. Locate your project's erlinit configuration which is normally in your project's config/target.exs file
3. Add a ctty option with the UART port name as a value

 config :nerves,
   erlinit: [
+    ctty: "ttyAMA0",
     hostname_pattern: "nerves-%s"
   ]

USB data cable

Some Nerves targets can operate in Linux USB gadget mode, which means a network connection can be made with a USB cable between your host and target. The USB cable provides both power and network connectivity. This can be a convenient way to work with your target device.

Test the connection

Once the target is powered up, test the connection from your host:

ping nerves.local

Make the network connection

To make a connection via the Linux USB gadget mode virtual Ethernet interface:

ssh nerves.local

You should find yourself at the iex(hello_nerves@nerves.local)1> prompt.

To end your ssh connection type exit, or you can use the ssh command <enter>~.

Gadget-mode virtual serial connection

USB gadget mode also supplies a virtual serial connection. Use it with any terminal emulator like screen or picocom:

picocom -b 115200 /dev/ttyUSB0

Wireless and wired Ethernet connections

The config/config.exs generated in a new Nerves project will set up connections for USB and Ethernet by default.

The nerves_pack dependency simplifies the network setup and configuration process. At runtime, nerves_pack will detect all available interfaces that have not been configured and apply defaults for usb* and eth* interfaces.

• For eth* interfaces, the device attempts to connect to the network with DHCP using ipv4 addressing.
• For usb* interfaces, it uses vintage_net_direct to run a simple DHCP server on the device and assign the host an IP address over a USB cable.

If you want to use some other network configuration, such as wired or wireless Ethernet, refer to the nerves_pack documentation and the underlying vintage_net documentation as needed.

Discovering Nerves Devices on your network

Nerves provides a mix task that you can use to find devices running on your network, it allows you to connect to them later on without needing to keep track of their IP addresses or hostnames. The mix nerves.discover task uses mDNS (multicast DNS) to help you find any Nerves device on your network.

Using mix nerves.discover

The discovery task scans your local network for Nerves devices and displays their information in a convenient table format:

$ mix nerves.discover
Discovering Nerves devices (waiting up to 5000ms)...

NAME         ADDRESSES      SERIAL            PRODUCT     VERSION  PLATFORM  UUID
nerves-0316  192.168.7.128  55e77bfdd5030316  kiosk_demo  0.2.1    rpi5      salute-valley (cbf8c271-2673-51f7-ab08-3de09af404eb)
nerves-8465  192.168.7.48

# On Ubuntu/Debian
sudo apt-get install avahi-utils
# On Fedora/RHEL
sudo dnf install avahi-tools

Command options

The mix nerves.discover supports the following option:

• --timeout - Timeout in milliseconds to wait for device replies. Default is 5000ms (5 seconds).

Examples

Wait longer for devices to respond (useful on slower networks):

mix nerves.discover --timeout 10000

Quick scan with default timeout:

mix nerves.discover

Understanding the output

The mix nerves.discover output displays the following information when available:

Connecting to discovered devices

Once you've discovered devices on your network, you can connect to them using their IP address or their hostname. For SSH access:

ssh nerves-0316.local

Or using the IP address directly:

ssh 192.168.7.128

Troubleshooting

No devices found

If mix nerves.discover reports "No devices found", try the following:

1. Verify network connectivity - Ensure your host and your Nerves devices are on the same local network. mDNS typically doesn't work across network subnets.

2. Check device status - Confirm your Nerves devices are powered on and fully booted.

3. Increase timeout - Some networks may require a longer discovery period:

   mix nerves.discover --timeout 15000
   

4. Check mDNS service - On Linux, ensure the Avahi daemon is running:

   systemctl status avahi-daemon
   

5. Firewall settings - Ensure your firewall isn't blocking mDNS traffic (UDP port 5353).

Using the nerves_discovery library

The discovery functionality is provided by the nerves_discovery library, which can be used directly in your Elixir programs for programmatic device discovery. This is useful for building custom tooling or integrating discovery into your applications.

See the nerves_discovery documentation for more information on using the library in your own code.