NervesDiscovery

Discover Nerves devices on your local network using mDNS service discovery

This library provides a simple way to find Nerves devices on your network without needing to know their IP addresses. It finds Nerves devices in two ways:

1. Devices that advertise SSH and have hostnames that start with "nerves-"
2. Devices that advertise the _nerves-device._tcp mDNS service

The second mechanism also supports advertising other attributes like serial numbers and firmware versions.

Nerves Tip {: .tip}

If you already have a Nerves project using :nerves v1.13.0+, run mix nerves.discover on the command line to find devices. See below for advertising serial numbers and firmware information.

OS-specific installation

This library uses native mDNS programs when available and backs off to a generic pure-Elixir implementation. The pure-Elixir method is slower.

MacOS and Windows users don't need to do anything. Desktop Linux users should install the Avahi tools:

# Debian/Ubuntu
sudo apt-get install avahi-utils

# Fedora/RHEL
sudo dnf install avahi-tools

Usage

Calling NervesDiscovery.discover/1 with no options should result in a good list of what's available. See the options to change the wait time.

iex> NervesDiscovery.discover()
[
  %{
    name: "nerves-8465",
    serial: "55e77bfdd5030316",
    version: "0.2.1",
    addresses: [{192, 168, 7, 48}],
    description: "",
    author: "The Nerves Team",
    product: "kiosk_demo",
    hostname: "nerves-8465.local",
    platform: "rpi4",
    architecture: "arm",
    uuid: "28a2e0e8-2166-5ff2-f24e-a42564cf9bc4"
  },
  %{
    name: "nerves-0316",
    addresses: [{192, 168, 7, 128}],
    hostname: "nerves-0316.local",
  }
]

If you want the serial number and firmware information from your Nerves device, it should advertise the _nerves-device._tcp mDNS service. Include this code snippet in your firmware (or pasted it on the Nerves device's IEx prompt to test):

MdnsLite.add_mdns_service(%{
    id: :nerves_device,
    protocol: "nerves-device",
    transport: "tcp",
    port: 0,
    txt_payload: [
      "serial=#{Nerves.Runtime.serial_number()}",
      "product=#{Nerves.Runtime.KV.get_active("nerves_fw_product")}",
      "description=#{Nerves.Runtime.KV.get_active("nerves_fw_description")}",
      "version=#{Nerves.Runtime.KV.get_active("nerves_fw_version")}",
      "platform=#{Nerves.Runtime.KV.get_active("nerves_fw_platform")}",
      "architecture=#{Nerves.Runtime.KV.get_active("nerves_fw_architecture")}",
      "author=#{Nerves.Runtime.KV.get_active("nerves_fw_author")}",
      "uuid=#{Nerves.Runtime.KV.get_active("nerves_fw_uuid")}"
    ]
  })

mDNS Service specification

This section formally specifies the _nerves-device._tcp mDNS service for enabling automatic discovery of devices and information about them.

Service Name

_nerves-device._tcp.local

Port Number

The port number MUST be 0.

TXT Records

Devices advertising this service SHOULD include the following TXT records:

Required Fields

• serial: Device serial number or unique identifier
• version: The application or firmware version string

Optional Fields

Additional TXT records MAY be included as needed by specific applications:

• architecture: The CPU architecture (e.g., aarch64, riscv, x86_64) - author: Author field in the firmware metadata
• description: Human-readable device description
• platform: The hardware model or platform identifier (e.g., rpi4, bbb, imx6ull)
• product: The application or product name running on the device
• uuid: Firmware UUID

Example

Service Name: my-thermostat._nerves-device._tcp.local
Port: 0
TXT Records:
  serial=ABC123456
  version=1.2.3
  product=smart_thermostat