View Source 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.
What features does Nerves support for my device?
Refer to the documentation of
nerves_system_<target>projects for their supported features. As an example, when your target is
rpi0, visit https://hexdocs.pm/nerves_system_rpi0.
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.
/dev/ttyAMA0 in the file system.
It is configured here
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
Enabling USB serial console
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|
Image credit: https://pinout.xyz
Most likely you don't need the power line since your purpose here is the serial data communication.
RX(receive) are relative terms. What is
TXfor one is
RXfor 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.
List TTY devices available
Start communication with the Raspberry Pi using
picocom -b 115200 /dev/ttyUSB0
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.
Linux USB gadget mode
Linux USB gadget mode also supplies a virtual serial connection for some Nerves targets.
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.
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
Unplug the USB connector and re-plug it.
On some Raspberry Pi family of targets such as
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:
- Look in the README of your target's system's documentation for a UART port name. For example,
- Locate your project's
erlinitconfiguration which is normally in your project's
- Add a
cttyoption 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
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
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:
To make a connection via the Linux USB gadget mode virtual Ethernet interface:
You should find yourself at the
To end your ssh connection type
exit, or you can use the
nerves.local is an mDNS address
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
picocom -b 115200 /dev/ttyUSB0
Windows Device Manager / Network adapters has no USB Ethernet/RNDIS Gadget device?
It might be caused by this, so install the optional
USB Ethernet/RNDIS Gadgetdriver to fix it.
config/config.exs generated in a new Nerves project will set up
connections for USB and Ethernet by default.
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
eth*interfaces, the device attempts to connect to the network with DHCP using
usb*interfaces, it uses
vintage_net_directto run a simple DHCP server on the device and assign the host an IP address over a USB cable.