Esrom geocache

A Nerves-based geocache running on a Raspberry Pi 2. The device blinks a morse-code message through a GPIO-connected relay/lamp, driven from a Phoenix LiveView web interface that visitors open in their browser.

The repo is two Elixir apps:

• esrom_ui — the Phoenix LiveView app (the web UI + morse logic). Runs on your laptop for development, and is embedded into the firmware for the device.
• esrom_firmware — the Nerves project that bundles esrom_ui into a bootable Raspberry Pi image.

Prerequisites

• Nix with flakes enabled. You do not need Elixir, Erlang, or the Nerves toolchain installed globally — the dev shells provide everything, pinned to the versions this project needs.
• For flashing: an SD card and a card reader.

The two dev shells

Command	What you get	Use it for
nix develop	Elixir + esbuild + inotify-tools	Working on the esrom_ui web app
nix develop .#firmware	An FHS sandbox with Elixir and the Nerves cross-compile toolchain	Building the Raspberry Pi firmware

Both shells pin Erlang/OTP 28, which is the version the Nerves system (nerves_system_rpi2) expects. If the host and target OTP majors don't match, mix firmware refuses to build — so always build from nix develop .#firmware, not your own global Elixir.

Development (the web UI)

nix develop
cd esrom_ui
mix deps.get
mix phx.server

Open http://localhost:4000/seinlamp for the morse page (the bare / returns 204; see esrom_ui/lib/esrom_ui_web/router.ex for all routes).

Building the firmware

Enter the firmware shell. It drops you into an FHS bash sandbox — that layout is required because Nerves downloads pre-compiled toolchain binaries that expect a standard Linux filesystem (/lib/ld-linux.so, etc.), which NixOS doesn't have.

nix develop .#firmware

First time only, install the Nerves bootstrap Mix archive (into ~/.mix):

mix archive.install hex nerves_bootstrap

Then build:

cd esrom_firmware
mix deps.get
mix firmware

The default target is rpi2. On success you get:

esrom_firmware/_build/rpi2_dev/nerves/images/esrom_firmware.fw

To build for another board, set MIX_TARGET before entering the shell (and add the matching nerves_system_* dep in esrom_firmware/mix.exs):

MIX_TARGET=rpi3 nix develop .#firmware

Flashing an SD card

Do this from a normal terminal, not from inside nix develop .#firmware. That firmware shell is a bubblewrap sandbox with the kernel no_new_privs flag set, which blocks sudo — so mix burn / fwup fail there with sudo: The "no new privileges" flag is set. Build in the firmware shell, then flash from a regular shell.

1. Insert the card and find its device node (e.g. /dev/mmcblk0 or /dev/sdX):

   lsblk
   

2. Unmount any partitions your desktop auto-mounted (otherwise fwup errors with Error calling umount). No sudo needed — udisksctl uses polkit:

   for p in /dev/mmcblk0p*; do udisksctl unmount -b "$p" 2>/dev/null; done
   

3. Flash. fwup comes from Nix; we resolve its full path so sudo (which resets PATH) can find it:

   FWUP=$(nix build --no-link --print-out-paths nixpkgs#fwup)/bin/fwup
   sudo "$FWUP" -a -t complete \
     -d /dev/mmcblk0 \
     -i esrom_firmware/_build/rpi2_dev/nerves/images/esrom_firmware.fw
   

   ⚠️ Double-check the -d device — this overwrites the whole disk.

Put the card in the Pi and power on. After boot, the web UI is served on port 80 (e.g. http://<device-ip>/seinlamp).

Updating a running device over the network

Once a device is on the network you can push new firmware over SSH — no need to pull the SD card. From nix develop .#firmware, after mix firmware:

cd esrom_firmware
mix upload <device-ip-or-hostname>

(Or generate a standalone script once with mix firmware.gen.script and run ./upload.sh <device>.) The device applies the update to its inactive A/B partition and reboots, so a bad image rolls back automatically.

SSH into the device

The firmware runs an SSH server (via nerves_pack) that gives you an IEx prompt using the keys in esrom_firmware/config/authorized_keys:

ssh <device-ip-or-hostname>

Useful once connected: VintageNet.info() to inspect network state.

Troubleshooting

• Major version mismatch between host and target Erlang/OTP — you're building with the wrong Erlang. Build from nix develop .#firmware (pinned to OTP 28), not a globally installed Elixir.
• sudo: The "no new privileges" flag is set — you ran mix burn/fwup inside the firmware FHS shell. Flash from a normal terminal instead (see above).
• fwup: Error calling umount — a partition on the card is still mounted. Run the udisksctl unmount loop above, then re-flash.
• Device pings but shows no web page — the endpoint only listens when built for a target (it binds 0.0.0.0:80 with server: true via the non-host branch of esrom_ui/config/dev.exs). Rebuild and reflash.