Add serial_number and provisioning information

README.md

@@ -76,6 +76,46 @@ The base image includes drivers for the onboard Raspberry Pi Zero W wifi module
 (`brcmfmac` driver). Due to the USB port being placed in gadget mode, this
 system does not support USB WiFi adapters.
 
+## Provisioning devices
+
+This system supports storing provisioning information in a small key-value store
+outside of any filesystem. Provisioning is an optional step and reasonable
+defaults are provided if this is missing.
+
+Provisioning information can be queried using the Nerves.Runtime KV store's
+[`Nerves.Runtime.KV.get/1`](https://hexdocs.pm/nerves_runtime/Nerves.Runtime.KV.html#get/1)
+function.
+
+Keys used by this system are:
+
+Key             | Example Value     | Description
+:-------------- | :---------------- | :----------
+`serial_number` | "1234578"`        | By default, this string is used to create unique hostnames and Erlang node names. If unset, it defaults to part of the Raspberry Pi's device ID.
+
+The normal procedure would be to set these keys once in manufacturing or before
+deployment and then leave them alone.
+
+For example, to provision a serial number on a running device, run the following
+and reboot:
+
+```elixir
+iex> cmd("fw_setenv serial_number 1234")
+```
+
+This system supports setting the serial number offline. To do this, set the
+`SERIAL_NUMBER` environment variable when burning the firmware. If you're
+programming MicroSD cards using `fwup`, the commandline is:
+
+```sh
+sudo SERIAL_NUMBER=1234 fwup path_to_firmware.fw
+```
+
+Serial numbers are stored on the MicroSD card so if the MicroSD card is
+replaced, the serial number will need to be reprogrammed. The numbers are stored
+in a U-boot environment block. This is a special region that is separate from
+the application partition so reformatting the application partition will not
+lose the serial number or any other data stored in this block.
+
 ## Linux kernel and RPi firmware/userland
 
 There's a subtle coupling between the `nerves_system_br` version and the Linux

fwup.conf

@@ -204,6 +204,13 @@ task complete {
         uboot_setenv(uboot-env, "a.nerves_fw_vcs_identifier", ${NERVES_FW_VCS_IDENTIFIER})
         uboot_setenv(uboot-env, "a.nerves_fw_misc", ${NERVES_FW_MISC})
 
+        # Support setting device serial numbers when creating MicroSD cards.
+        # Note that the '$' is escaped so that environment variable replacement
+        # happens at "burn" time rather than at firmware creation time. No
+        # serial numbers are stored in the .fw file. If left blank, the device
+        # will default to a built-in ID.
+        uboot_setenv(uboot-env, "serial_number", "\${SERIAL_NUMBER}")
+
         fat_mkfs(${BOOT_A_PART_OFFSET}, ${BOOT_A_PART_COUNT})
         fat_setlabel(${BOOT_A_PART_OFFSET}, "BOOT-A")
         fat_mkdir(${BOOT_A_PART_OFFSET}, "overlays")

rootfs_overlay/etc/erlinit.config

@@ -54,9 +54,11 @@
 # Erlang release search path
 -r /srv/erlang
 
-# Assign a unique hostname based on the board id
--d "/usr/bin/boardid -b rpi -n 4"
--n nerves-%.4s
+# Assign a hostname of the form "nerves-<serial_number>". The serial number is either
+# read from the U-boot environment block that contains provisioning information from
+# manufactoring or it uses 4 digits of the Raspberry Pi's device ID
+-d "/usr/bin/boardid -b uboot_env -u serial_number -b rpi -n 4"
+-n nerves-%s
 
 # If using shoehorn (https://github.com/nerves-project/shoehorn), start the
 # shoehorn OTP release up first. If shoehorn isn't around, erlinit fails back