guides/core/connecting-to-a-nerves-target.md
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.
What features does Nerves support for my device? {: .tip}
Refer to the documentation of
nerves_system_<target>projects for their supported features. As an example, when your target isrpi0_2, visit https://hexdocs.pm/nerves_system_rpi0_2.
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.
Enabling USB serial console {: .info}
Depending on your target's default settings, you may need to modify your Nerves configuration as described in the Using a USB Serial Console FAQ topic.
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.
| Raspberry Pi | USB-to-TTL Serial Cable |
|---|---|
TX0 (pin 8 / GPIO 14) | RX |
RX0 (pin 10 / GPIO 15) | TX |
GND | GND |
Image credit: https://pinout.xyz
Tips {: .tip}
Most likely you don't need the power line since your purpose here is the serial data communication.
TX(transmit) andRX(receive) are relative terms. What isTXfor one isRXfor the other.
For visual learners, Adafruit's Raspberry Pi Lesson has some helpful images.
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.
As an example, on a macOS host machine, you can open a terminal and try these commands.
ls /dev/tty*
picocompicocom -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.
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.
exit not working in the serial consoleIt works, but Erlang doesn't automatically restart the shell. You should be able to type CTRL-G to get the Erlang job menu.
screen commandUnplug the USB connector and re-plug it.
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:
nerves_system_rpi3erlinit configuration which is normally in your project's config/target.exs filectty option with the UART port name as a value config :nerves,
erlinit: [
+ ctty: "ttyAMA0",
hostname_pattern: "nerves-%s"
]
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.
Use correct USB port {: .warning}
Make sure to plug the USB cable into the USB OTG port. For example, the Raspberry Pi Zero has two USB ports. The OTG one is the "middle" one. The other one is power-only.
Use correct USB cable {: .warning}
Make sure your USB cable supports data transfer. Generally there are two types of USB cables:
- charging only
- charging and data transfer
Once the target is powered up, test the connection from your host:
ping nerves.local
To make a connection via the Linux USB gadget mode virtual Ethernet interface:
ssh nerves.local
You should find yourself at the iex([email protected])1> prompt.
To end your ssh connection type exit, or you can use the ssh command
<enter>~.
nerves.local is an mDNS address {: .info}
Most examples in this page are done with a macOS host, which has mDNS enabled by default. Linux and Windows hosts may have to enable mDNS networking.
USB gadget mode also supplies a virtual serial connection. Use it with any
terminal emulator like screen or picocom:
picocom -b 115200 /dev/ttyUSB0
Windows Device Manager / Network adapters has no USB Ethernet/RNDIS Gadget device? {: .info}
It might be caused by this, so install the optional
USB Ethernet/RNDIS Gadgetdriver to fix it.
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.
eth* interfaces, the device attempts to connect to the network
with DHCP using ipv4 addressing.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.
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.
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
For Linux users {: .tip}
Linux users should install
avahi-utilsfor better discovery results.bash# On Ubuntu/Debian sudo apt-get install avahi-utils # On Fedora/RHEL sudo dnf install avahi-tools
The mix nerves.discover supports the following option:
--timeout - Timeout in milliseconds to wait for device replies. Default is 5000ms (5 seconds).Wait longer for devices to respond (useful on slower networks):
mix nerves.discover --timeout 10000
Quick scan with default timeout:
mix nerves.discover
The mix nerves.discover output displays the following information when available:
| Column | Description |
|---|---|
| NAME | The hostname of the device |
| IP | The IP address of the device on the local network |
| SERIAL | The device serial number (if available) |
| VERSION | The firmware version running on the device (if available) |
| PRODUCT | The product name configured in the firmware (if available) |
| PLATFORM | The target platform (e.g., rpi5, rpi0) (if available) |
| UUID | The unique identifier for the device (if available) |
Limited information? {: .info}
If a device only shows NAME and IP, it means the device isn't advertising firmware attributes. You can still connect to it, but detailed information is not available through this task.
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
If mix nerves.discover reports "No devices found", try the following:
Verify network connectivity - Ensure your host and your Nerves devices are on the same local network. mDNS typically doesn't work across network subnets.
Check device status - Confirm your Nerves devices are powered on and fully booted.
Increase timeout - Some networks may require a longer discovery period:
mix nerves.discover --timeout 15000
Check mDNS service - On Linux, ensure the Avahi daemon is running:
systemctl status avahi-daemon
Firewall settings - Ensure your firewall isn't blocking mDNS traffic (UDP port 5353).
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.