Merge pull request #15 from ngrok/joelhans/persistent-oled

Show hostname, MAC, and IPs on the OLED from boot

Author: joelhans

image/README.md

@@ -91,6 +91,12 @@ file in place so you can fix it and reboot.
   with no prompt.
 - Confirm the networking tools are present: `which tcpdump tshark arping`.
 - Check the I2C bus (for the OLED): `i2cdetect -y 1`.
+- If an OLED is wired up, it shows the node's identity from boot — hostname in
+  the yellow strip, eth0's MAC and each interface's IPv4 in the blue area — so
+  a rack of identical Pis is tellable-apart at a glance (see
+  [`tools/status-oled`](../tools/status-oled/README.md)). The on-demand OLED
+  scripts (`~/oled-test`, `~/arp-oled`) borrow the panel while they run and the
+  status display resumes when they exit.
 - Wi-Fi is management-only by design: you can SSH in and the node reaches the
   internet, but two nodes **can't reach each other over Wi-Fi**. The lessons run
   on a wired link instead. So if a second node seems unreachable _from the first
@@ -132,7 +138,9 @@ image/
     │   ├── 03-run.sh             Lets the user run tshark unprivileged, pre-creates ~/cap, and sets COLORTERM for colored output over SSH.
     │   ├── 04-run.sh             Builds /opt/little-internet/venv with luma.oled to drive the OLED displays.
     │   ├── 05-run.sh             Installs the OLED test scripts into ~/oled-test (staged from tools/oled-test by build.sh).
-    │   └── files/                eth-dhcp.nmconnection — the eth0 DHCP baseline keyfile (build.sh also stages oled-test/ here).
+    │   ├── 06-run.sh             Installs the on-demand ARP-state OLED viewer into ~/arp-oled (staged from tools/arp-oled by build.sh).
+    │   ├── 07-run.sh             Installs + enables the boot-time OLED status display, little-internet-oled.service (staged from tools/status-oled by build.sh).
+    │   └── files/                eth-dhcp.nmconnection + little-internet-oled.service (build.sh also stages oled-test/, arp-oled/, and status-oled/ here).
     ├── 01-firstboot-config/      First-boot hostname + Wi-Fi provisioner for flashed (released) images.
     │   ├── 00-run.sh             Installs the provisioner script, service, and boot-partition template.
     │   └── files/                The script, systemd unit, and little-internet.txt.example.

image/build.sh

@@ -154,6 +154,13 @@ arp_files="${PIGEN_DIR}/${STAGE_NAME}/00-net-tools/files/arp-oled"
 mkdir -p "${arp_files}"
 cp "${HERE}/../tools/arp-oled/arp_oled.py" "${arp_files}/"
 
+# 3e. Stage the boot-time OLED status display (tools/status-oled is its source
+#     of truth); 00-net-tools/07-run.sh installs it under /opt/little-internet
+#     and enables it as a systemd service.
+status_files="${PIGEN_DIR}/${STAGE_NAME}/00-net-tools/files/status-oled"
+mkdir -p "${status_files}"
+cp "${HERE}/../tools/status-oled/status_oled.py" "${status_files}/"
+
 # 4. Only export our final image, not the intermediate Lite image.
 touch "${PIGEN_DIR}/stage2/SKIP_IMAGES"
 

image/stage-little-internet/00-net-tools/06-run.sh

@@ -8,8 +8,10 @@
 #
 # Run it by hand against the venv built in 04-run.sh (no sudo: reading the
 # neighbour cache is unprivileged and the first user is already in the i2c
-# group). It deliberately is NOT a boot service — that would permanently claim
-# the OLED and fight the oled-test smoke scripts over the one I2C panel:
+# group). It deliberately is NOT a boot service — the panel's boot-time
+# resident is the status display (07-run.sh). While this script runs it pauses
+# that display via the claim file described in little-internet-oled.service,
+# and hands the panel back on exit:
 #   /opt/little-internet/venv/bin/python3 ~/arp-oled/arp_oled.py
 #
 # Staged into files/arp-oled by build.sh from tools/arp-oled (source of truth);

image/stage-little-internet/00-net-tools/07-run.sh

@@ -0,0 +1,24 @@
+#!/bin/bash -e
+
+# Install the boot-time OLED status display: hostname in the yellow strip,
+# eth0's MAC and each interface's IPv4 in the blue body, painted from boot so
+# a rack of identical Pis is tellable-apart at a glance. Runs as a systemd
+# service (little-internet-oled.service) against the venv built in 04-run.sh.
+#
+# The script lives in /opt/little-internet (not the user's home) because a
+# root service shouldn't execute user-editable files. The on-demand scripts
+# installed by 05-/06-run.sh share the panel with it through the claim file
+# described in the service unit.
+#
+# Staged into files/status-oled by build.sh from tools/status-oled (source of
+# truth).
+install -d -m 755 "${ROOTFS_DIR}/opt/little-internet/status-oled"
+install -m 755 files/status-oled/status_oled.py \
+	"${ROOTFS_DIR}/opt/little-internet/status-oled/"
+
+install -m 644 files/little-internet-oled.service \
+	"${ROOTFS_DIR}/etc/systemd/system/little-internet-oled.service"
+
+on_chroot << 'EOF'
+systemctl enable little-internet-oled.service
+EOF

image/stage-little-internet/00-net-tools/files/little-internet-oled.service

@@ -0,0 +1,27 @@
+[Unit]
+Description=Show hostname, MAC, and IPv4 on the OLED (little-internet)
+# The boot-time resident of the panel: with a rack of identical Pis, the OLED
+# is what tells you which node is which. Ordered after the first-boot
+# provisioner so a hostname from little-internet.txt is already set when the
+# first frame paints. No network dependency — the script polls, so addresses
+# appear as DHCP hands them out.
+After=local-fs.target little-internet.service
+
+[Service]
+Type=simple
+# Unbuffered stdout so the script's log lines reach the journal as they
+# happen, not when the buffer fills.
+Environment=PYTHONUNBUFFERED=1
+ExecStart=/opt/little-internet/venv/bin/python3 /opt/little-internet/status-oled/status_oled.py
+Restart=on-failure
+RestartSec=5
+# /run/little-internet is the handoff point for the one panel: on-demand OLED
+# scripts (~/arp-oled, ~/oled-test) create oled.claim there to pause this
+# display and remove it to resume. Group i2c + 0775 lets the unprivileged lab
+# user (already in i2c for the bus itself) create and remove that file.
+Group=i2c
+RuntimeDirectory=little-internet
+RuntimeDirectoryMode=0775
+
+[Install]
+WantedBy=multi-user.target

tools/arp-oled/README.md

@@ -15,8 +15,10 @@ the cache is unprivileged, and the `pi` user is already in the `i2c` group):
 
 By default it watches the other half of the `10.10.0.x` pair (on `.1` it watches
 `.2`, and vice versa); override with `--peer`. Ctrl-C clears the panel and exits.
-It's a script, not a service, so it won't fight the `oled-test` scripts for the
-display.
+On the image the panel normally shows the boot-time
+[status display](../status-oled/README.md) (hostname/MAC/IP); this script pauses
+it while it runs — via `/run/little-internet/oled.claim`, no sudo needed — and
+the status display repaints when this exits.
 
 ## Drive the state machine
 

tools/arp-oled/arp_oled.py

@@ -17,6 +17,10 @@
 The peer defaults to the other half of the 10.10.0.1 <-> 10.10.0.2 lab pair
 (auto-picked from this node's own address), or pass --peer.
 
+On the little-internet image the panel normally shows the boot-time status
+display (hostname/MAC/IP); this script pauses it via a claim file while it
+runs and the status display resumes when this exits.
+
     /opt/little-internet/venv/bin/python3 arp_oled.py
     arp_oled.py --peer 10.10.0.2 --interval 0.5
     arp_oled.py --address 0x3d --controller sh1106
@@ -25,6 +29,7 @@
 import argparse
 import json
 import os
+import signal
 import subprocess
 import sys
 import time
@@ -39,6 +44,33 @@
 PAIR = {"10.10.0.1": "10.10.0.2", "10.10.0.2": "10.10.0.1"}
 DEFAULT_PEER = "10.10.0.2"
 
+# The boot-time status display (little-internet-oled.service on the image)
+# owns the panel; it pauses while this claim file exists and resumes when it's
+# removed. The claim directory is that service's RuntimeDirectory (root:i2c,
+# 0775), so no sudo is needed. On systems without the service, claiming just
+# fails quietly — there's nothing to pause.
+CLAIM_FILE = "/run/little-internet/oled.claim"
+
+
+def claim_panel():
+    """Pause the boot status display; True if the claim file was written."""
+    try:
+        with open(CLAIM_FILE, "w") as fh:
+            fh.write(f"{os.getpid()}\n")
+    except OSError:
+        return False
+    # Let an in-flight status frame land before we paint over it.
+    time.sleep(0.5)
+    return True
+
+
+def release_panel(claimed):
+    if claimed:
+        try:
+            os.remove(CLAIM_FILE)
+        except OSError:
+            pass
+
 # NUD states worth a one-glance read. Anything else is shown verbatim.
 KNOWN_STATES = {
     "REACHABLE", "STALE", "DELAY", "PROBE",
@@ -228,6 +260,10 @@ def main():
         print("Requested font unavailable; using the built-in bitmap font.")
 
     print(f"Watching ARP state for {peer} (poll {args.interval}s). Ctrl-C to stop.")
+    # Python dies on SIGTERM without running `finally`, which would strand the
+    # claim file and leave the status display paused; exit cleanly instead.
+    signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
+    claimed = claim_panel()
     beat = False
     try:
         while True:
@@ -238,6 +274,9 @@ def main():
     except KeyboardInterrupt:
         device.clear()
         print("\nDone.")
+    finally:
+        # Hand the panel back: the status display repaints within a second.
+        release_panel(claimed)
 
 
 if __name__ == "__main__":

tools/oled-test/README.md

@@ -27,6 +27,11 @@ Quick smoke tests for the **SSD1306 128×64** OLEDs over **I2C** (4-pin modules)
 > /opt/little-internet/venv/bin/python3 ~/oled-test/oled_shrimp.py
 > ```
 >
+> On the image the panel is normally driven by the boot-time
+> [status display](../status-oled/README.md) (hostname/MAC/IP). These scripts
+> pause it while they run and it repaints when they exit, so a working panel
+> already showing status is itself a passing smoke test.
+>
 > The steps below are for a stock Raspberry Pi OS where you set this up yourself.
 
 ```sh

tools/oled-test/oled_shrimp.py

@@ -11,6 +11,8 @@
 """
 import argparse
 import base64
+import os
+import signal
 import sys
 import time
 
@@ -19,6 +21,33 @@
 from luma.core.interface.serial import i2c
 from luma.oled.device import sh1106, ssd1306
 
+# The boot-time status display (little-internet-oled.service on the image)
+# owns the panel; it pauses while this claim file exists and resumes when it's
+# removed. The claim directory is that service's RuntimeDirectory (root:i2c,
+# 0775), so no sudo is needed. On systems without the service, claiming just
+# fails quietly — there's nothing to pause.
+CLAIM_FILE = "/run/little-internet/oled.claim"
+
+
+def claim_panel():
+    """Pause the boot status display; True if the claim file was written."""
+    try:
+        with open(CLAIM_FILE, "w") as fh:
+            fh.write(f"{os.getpid()}\n")
+    except OSError:
+        return False
+    # Let an in-flight status frame land before we paint over it.
+    time.sleep(0.5)
+    return True
+
+
+def release_panel(claimed):
+    if claimed:
+        try:
+            os.remove(CLAIM_FILE)
+        except OSError:
+            pass
+
 # 64x64, 1-bit, MSB-first packed (PIL mode "1"). Phosphor "shrimp" (regular).
 SHRIMP_64_B64 = (
     "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAYAAAAAAAAADwAAAAAAAAAPA"
@@ -66,10 +95,17 @@ def main():
     x = (device.width - icon.width) // 2
     y = (device.height - icon.height) // 2
     frame.paste(icon, (x, y))
-    device.display(frame)
-    print(f"Shrimp on I2C {args.port} @ {hex(args.address)}. "
-          f"Holding {args.hold}s... 🦐")
-    time.sleep(args.hold)
+    # Python dies on SIGTERM without running `finally`, which would strand the
+    # claim file and leave the status display paused; exit cleanly instead.
+    signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
+    claimed = claim_panel()
+    try:
+        device.display(frame)
+        print(f"Shrimp on I2C {args.port} @ {hex(args.address)}. "
+              f"Holding {args.hold}s... 🦐")
+        time.sleep(args.hold)
+    finally:
+        release_panel(claimed)
     print("Done.")
 
 

tools/oled-test/oled_test.py

@@ -8,13 +8,42 @@
     python3 oled_test.py --address 0x3d --hold 8
 """
 import argparse
+import os
+import signal
 import sys
 import time
 
 from luma.core.interface.serial import i2c
 from luma.core.render import canvas
 from luma.oled.device import sh1106, ssd1306
 
+# The boot-time status display (little-internet-oled.service on the image)
+# owns the panel; it pauses while this claim file exists and resumes when it's
+# removed. The claim directory is that service's RuntimeDirectory (root:i2c,
+# 0775), so no sudo is needed. On systems without the service, claiming just
+# fails quietly — there's nothing to pause.
+CLAIM_FILE = "/run/little-internet/oled.claim"
+
+
+def claim_panel():
+    """Pause the boot status display; True if the claim file was written."""
+    try:
+        with open(CLAIM_FILE, "w") as fh:
+            fh.write(f"{os.getpid()}\n")
+    except OSError:
+        return False
+    # Let an in-flight status frame land before we paint over it.
+    time.sleep(0.5)
+    return True
+
+
+def release_panel(claimed):
+    if claimed:
+        try:
+            os.remove(CLAIM_FILE)
+        except OSError:
+            pass
+
 
 def main():
     p = argparse.ArgumentParser(description="Smoke test an I2C SSD1306 OLED.")
@@ -38,14 +67,21 @@ def main():
               "and that I2C is enabled.")
         sys.exit(1)
 
-    with canvas(device) as draw:
-        draw.rectangle(device.bounding_box, outline="white")
-        draw.text((6, 8), "OLED OK", fill="white")
-        draw.text((6, 26), f"I2C {args.port} @ {hex(args.address)}", fill="white")
-        draw.text((6, 44), f"{device.width}x{device.height}", fill="white")
-    print(f"Drew test pattern on I2C {args.port} @ {hex(args.address)}. "
-          f"Holding {args.hold}s...")
-    time.sleep(args.hold)
+    # Python dies on SIGTERM without running `finally`, which would strand the
+    # claim file and leave the status display paused; exit cleanly instead.
+    signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
+    claimed = claim_panel()
+    try:
+        with canvas(device) as draw:
+            draw.rectangle(device.bounding_box, outline="white")
+            draw.text((6, 8), "OLED OK", fill="white")
+            draw.text((6, 26), f"I2C {args.port} @ {hex(args.address)}", fill="white")
+            draw.text((6, 44), f"{device.width}x{device.height}", fill="white")
+        print(f"Drew test pattern on I2C {args.port} @ {hex(args.address)}. "
+              f"Holding {args.hold}s...")
+        time.sleep(args.hold)
+    finally:
+        release_panel(claimed)
     print("Done.")