Skip to content

CLI for SidePulse

Python

Add size-limited raw FAT12 LED writer for macOS

Peter Kuhar74aa7c41464e
diff --git a/README.md b/README.md
index ebdefa5..d4b2391 100644
--- a/README.md
+++ b/README.md
@@ -143,6 +143,23 @@ sidepulse write "off" --device /media/$USER/SidePulseDot
The writer decodes simple escapes such as `\n`, then enforces the controller's
512-byte and 20-line limits before writing the LED control file.
+For an **unmounted macOS device**, the standalone standard-library utility can
+write the existing `LEDS.LED` directly through `/dev/diskN` or `/dev/rdiskN`:
+
+```sh
+# Replace disk4 with the SidePulse device. Unmount first if already mounted.
+diskutil unmountDisk /dev/disk4
+sudo python3 scripts/write_led_raw.py /dev/rdisk4 'off\n#ff00ff 1s pulse\nrepeat'
+sudo python3 scripts/write_led_raw.py /dev/disk4 - < animation.LED
+```
+
+It requires a whole drive of **at most 300,000 bytes**, verified using device
+capacity queries on the open disk before writing. Partitions, unknown capacity,
+mounted volumes, and larger drives are rejected, with no override. The filesystem
+must be FAT12 starting at sector zero, with one FAT and 512-byte sectors. Programs
+are limited to 512 bytes and 20 lines. It writes the existing file's first data
+sector and updates its directory size, preserving its FAT allocation.
+
### Link an iPhone
Run one command and either scan the terminal QR code with the SidePulse iOS app
diff --git a/scripts/write_led_raw.py b/scripts/write_led_raw.py
new file mode 100644
index 0000000..8e4bb37
--- /dev/null
+++ b/scripts/write_led_raw.py
@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""macOS: write an existing LEDS.LED on an unmounted, single-FAT FAT12 disk.
+
+ sudo python3 scripts/write_led_raw.py /dev/rdisk4 '#ff00ff'
+ sudo python3 scripts/write_led_raw.py /dev/disk4 - < animation.LED
+
+Only whole devices <= 300,000 bytes are accepted. No mounting or allocation.
+"""
+
+import argparse
+import fcntl
+import os
+import plistlib
+import re
+import stat
+import struct
+import subprocess
+import sys
+
+MAX_DISK_BYTES = 300_000 # Decimal KB; deliberately stricter than 300 KiB.
+SECTOR = 512
+# macOS <sys/disk.h>: _IOR('d', 24, uint32_t), _IOR('d', 25, uint64_t).
+DKIOCGETBLOCKSIZE = 0x40046418
+DKIOCGETBLOCKCOUNT = 0x40086419
+
+
+def require(condition, message):
+ if not condition:
+ raise ValueError(message)
+
+
+def device_size(fd):
+ """Query actual media capacity, never the size claimed by its FAT boot sector."""
+ require(sys.platform == "darwin", "This utility requires macOS.")
+ mode = os.fstat(fd).st_mode
+ require(stat.S_ISBLK(mode) or stat.S_ISCHR(mode), "Not a disk device.")
+ block = struct.unpack("=I", fcntl.ioctl(fd, DKIOCGETBLOCKSIZE, bytes(4)))[0]
+ count = struct.unpack("=Q", fcntl.ioctl(fd, DKIOCGETBLOCKCOUNT, bytes(8)))[0]
+ size = block * count
+ require(0 < size <= MAX_DISK_BYTES,
+ f"Refusing drive size {size:,} bytes; limit is {MAX_DISK_BYTES:,}.")
+ require(block == SECTOR, "Only 512-byte device blocks are supported.")
+ return size
+
+
+def check_unmounted(device):
+ result = subprocess.run(
+ ["/usr/sbin/diskutil", "info", "-plist", device],
+ check=True, capture_output=True,
+ )
+ info = plistlib.loads(result.stdout)
+ require(info.get("DeviceIdentifier") == device.removeprefix("/dev/"),
+ "Cannot verify device identity.")
+ require(info.get("WholeDisk") is True, "Only whole disks are accepted.")
+ # diskutil omits MountPoint for unmounted media; there is no Mounted key.
+ require(info.get("MountPoint", "") == "",
+ f"Drive must be unmounted first: diskutil unmountDisk {device}")
+
+
+def read_sector(fd, offset):
+ data = os.pread(fd, SECTOR, offset)
+ require(len(data) == SECTOR, "Short disk read; refusing to write.")
+ return data
+
+
+def locate_led(fd, size):
+ """Return data offset, directory-sector offset, and entry offset within it."""
+ boot = read_sector(fd, 0)
+ bps, spc, reserved, fats, entries, total = struct.unpack_from("<HBHBHH", boot, 11)
+ fat_sectors = struct.unpack_from("<H", boot, 22)[0]
+ hidden, total32 = struct.unpack_from("<II", boot, 28)
+ total = total or total32
+ require(boot[510:512] == b"\x55\xaa" and bps == SECTOR and fats == 1,
+ "Expected FAT12 with 512-byte sectors and exactly one FAT.")
+ require(hidden == 0 and reserved > 0 and entries > 0 and fat_sectors > 0,
+ "Expected a FAT12 volume starting at sector zero.")
+ require(spc in (1, 2, 4, 8, 16, 32, 64, 128), "Invalid cluster size.")
+ root = reserved + fat_sectors
+ data = root + (entries * 32 + SECTOR - 1) // SECTOR
+ clusters = (total - data) // spc
+ require(0 < total * SECTOR <= size and 0 < clusters < 4085,
+ "Invalid FAT12 geometry or filesystem exceeds device size.")
+ require(((clusters + 2) * 3 + 1) // 2 <= fat_sectors * SECTOR,
+ "FAT is too small for this volume.")
+ fat = os.pread(fd, fat_sectors * SECTOR, reserved * SECTOR)
+ require(len(fat) == fat_sectors * SECTOR, "Short FAT read.")
+ for index in range(entries):
+ if index % 16 == 0:
+ directory = read_sector(fd, root * SECTOR + index * 32)
+ offset = (index % 16) * 32
+ entry = directory[offset:offset + 32]
+ if entry[0] == 0:
+ break
+ if entry[:11] != b"LEDS LED" or entry[11] & 0x18:
+ continue
+ require(not entry[11] & 1, "LEDS.LED is read-only.")
+ cluster = struct.unpack_from("<H", entry, 26)[0]
+ require(2 <= cluster < clusters + 2, "Invalid LEDS.LED cluster.")
+ packed = struct.unpack_from("<H", fat, cluster + cluster // 2)[0]
+ next_cluster = (packed >> (4 if cluster & 1 else 0)) & 0xFFF
+ require(next_cluster >= 0xFF8 or
+ (2 <= next_cluster < clusters + 2 and next_cluster != cluster),
+ "LEDS.LED cluster is unallocated or invalid.")
+ return ((data + (cluster - 2) * spc) * SECTOR,
+ (root + index // 16) * SECTOR, offset)
+ raise ValueError("Existing LEDS.LED not found in the root directory.")
+
+
+def write_led(device, text):
+ require(sys.platform == "darwin", "This utility requires macOS.")
+ match = re.fullmatch(r"/dev/r?(disk[0-9]+)", device)
+ require(match is not None, "Use a whole /dev/diskN or /dev/rdiskN; no partitions.")
+ payload = text.encode("utf-8")
+ require(0 < len(payload) <= SECTOR and len(text.splitlines()) <= 20,
+ "LED program must contain 1–512 bytes and at most 20 lines.")
+ require("\0" not in text, "LED program must not contain NUL bytes.")
+ buffered = "/dev/" + match.group(1)
+ check_unmounted(buffered)
+ # No symlinks, creation or truncation. Retain this descriptor for all I/O.
+ fd = os.open(device, os.O_RDWR | os.O_NOFOLLOW)
+ try:
+ size = device_size(fd)
+ data_offset, root_offset, entry_offset = locate_led(fd, size)
+ directory = bytearray(read_sector(fd, root_offset))
+ struct.pack_into("<I", directory, entry_offset + 28, len(payload))
+ # Data first, file size last. Preserve the existing allocation and all
+ # other directory entries. Raw devices require whole-sector writes.
+ for offset, sector in ((data_offset, payload.ljust(SECTOR, b"\0")),
+ (root_offset, directory)):
+ check_unmounted(buffered)
+ require(device_size(fd) == size, "Device capacity changed; refusing write.")
+ require(0 <= offset <= size - SECTOR and offset % SECTOR == 0,
+ "Write would be outside the device or unaligned.")
+ require(os.pwrite(fd, sector, offset) == SECTOR, "Short disk write.")
+ os.fsync(fd)
+ finally:
+ os.close(fd)
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("device", help="whole /dev/diskN or /dev/rdiskN")
+ parser.add_argument("program", help="LED text (supports \\n), or - to read stdin")
+ args = parser.parse_args()
+ try:
+ text = (sys.stdin.read(513) if args.program == "-"
+ else args.program.replace("\\n", "\n"))
+ write_led(args.device, text)
+ except (OSError, ValueError, subprocess.SubprocessError) as exc:
+ parser.exit(1, f"error: {exc}\n")
+ print(f"Wrote LEDS.LED to {args.device}")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tests/test_write_led_raw.py b/tests/test_write_led_raw.py
new file mode 100644
index 0000000..be5af46
--- /dev/null
+++ b/tests/test_write_led_raw.py
@@ -0,0 +1,180 @@
+"""Exercise raw-disk safety entirely in memory; never open a real device."""
+
+import contextlib
+import plistlib
+import stat
+import struct
+import unittest
+from types import SimpleNamespace
+from unittest.mock import patch
+
+from scripts import write_led_raw as raw
+
+
+def fat12_image(cluster=2, entry_index=0, spc=1):
+ image = bytearray(340 * 512)
+ struct.pack_into("<HBHBHH", image, 11, 512, spc, 1, 1, 32, 340)
+ struct.pack_into("<H", image, 22, 1)
+ image[510:512] = b"\x55\xaa"
+ image[512:515] = b"\xf8\xff\xff"
+ struct.pack_into("<H", image, 512 + cluster + cluster // 2,
+ 0xFFF << (4 if cluster & 1 else 0))
+ for i in range(entry_index):
+ image[1024 + i * 32] = 0xE5
+ entry = 1024 + entry_index * 32
+ image[entry:entry + 11] = b"LEDS LED"
+ image[entry + 11] = 0x20
+ struct.pack_into("<H", image, entry + 26, cluster)
+ struct.pack_into("<I", image, entry + 28, 4)
+ start = (4 + (cluster - 2) * spc) * 512
+ image[start:start + 512] = b"x" * 512
+ return image, start, entry
+
+
+class RawWriteTests(unittest.TestCase):
+ def setUp(self):
+ self.image, self.data_offset, self.entry = fat12_image()
+ self.capacity = len(self.image)
+ self.info = {"DeviceIdentifier": "disk4", "WholeDisk": True}
+ self.stack = contextlib.ExitStack()
+ self.addCleanup(self.stack.close)
+ self.mock("sys.platform", "darwin")
+ self.open = self.mock("os.open", return_value=43)
+ self.close = self.mock("os.close")
+ self.mock("os.fstat", return_value=SimpleNamespace(st_mode=stat.S_IFCHR))
+ self.ioctl = self.mock("fcntl.ioctl", side_effect=self.ioctl_result)
+ self.mock("subprocess.run", side_effect=lambda *a, **k: SimpleNamespace(
+ stdout=plistlib.dumps(self.info)))
+ self.mock("os.pread", side_effect=lambda fd, count, offset:
+ bytes(self.image[offset:offset + count]))
+ self.pwrite = self.mock("os.pwrite", side_effect=self.write)
+ self.mock("os.fsync")
+
+ def mock(self, name, *args, **kwargs):
+ return self.stack.enter_context(patch("scripts.write_led_raw." + name,
+ *args, **kwargs))
+
+ def ioctl_result(self, fd, request, buffer):
+ self.assertEqual(fd, 43)
+ if request == raw.DKIOCGETBLOCKSIZE:
+ return struct.pack("=I", 512)
+ self.assertEqual(request, raw.DKIOCGETBLOCKCOUNT)
+ return struct.pack("=Q", self.capacity // 512)
+
+ def write(self, fd, data, offset):
+ self.assertEqual(fd, 43)
+ self.image[offset:offset + len(data)] = data
+ return len(data)
+
+ def refused(self, device="/dev/rdisk4", text="off"):
+ with self.assertRaises((ValueError, OSError)):
+ raw.write_led(device, text)
+ self.pwrite.assert_not_called()
+
+ def test_writes_only_data_and_file_size_for_both_paths(self):
+ for device in ("/dev/disk4", "/dev/rdisk4"):
+ with self.subTest(device=device):
+ self.image, start, entry = fat12_image()
+ expected = bytearray(self.image)
+ payload = b"#ff00ff\n"
+ expected[start:start + 512] = payload.ljust(512, b"\0")
+ struct.pack_into("<I", expected, entry + 28, len(payload))
+ raw.write_led(device, payload.decode())
+ self.assertEqual(self.image, expected)
+ self.close.assert_called_with(43)
+
+ def test_nondefault_cluster_and_second_root_sector(self):
+ self.image, start, entry = fat12_image(cluster=7, entry_index=18, spc=2)
+ raw.write_led("/dev/rdisk4", "off")
+ self.assertEqual(self.image[start:start + 512], b"off".ljust(512, b"\0"))
+ self.assertEqual(struct.unpack_from("<I", self.image, entry + 28)[0], 3)
+ self.assertEqual([c.args[2] for c in self.pwrite.call_args_list], [start, 1536])
+
+ def test_large_device_cannot_hide_behind_small_fat_volume(self):
+ for size in (300032, 300 * 1024, 1024**4):
+ with self.subTest(size=size):
+ self.capacity = size
+ self.refused()
+
+ def test_largest_allowed_512_byte_device(self):
+ self.capacity = 299520
+ raw.write_led("/dev/rdisk4", "off")
+ self.assertEqual(self.pwrite.call_count, 2)
+
+ def test_unknown_or_zero_capacity(self):
+ self.capacity = 0
+ self.refused()
+ self.ioctl.side_effect = OSError("capacity unavailable")
+ self.refused()
+
+ def test_capacity_rechecked_before_write(self):
+ with patch.object(raw, "device_size", side_effect=[174080, 300032]):
+ self.refused()
+
+ def test_partition_and_nondevice_paths_rejected_before_open(self):
+ for path in ("/dev/disk4s1", "/dev/rdisk4s1", "disk4", "/tmp/disk4", "/dev/disk"):
+ self.refused(device=path)
+ self.open.assert_not_called()
+
+ def test_mounted_invalid_mount_or_nonwhole_device(self):
+ for change in ({"MountPoint": "/Volumes/SidePulse"}, {"MountPoint": False},
+ {"WholeDisk": False},
+ {"DeviceIdentifier": "disk5"}):
+ with self.subTest(change=change), patch.dict(self.info, change):
+ self.refused()
+ self.open.assert_not_called()
+
+ def test_explicit_empty_mountpoint_is_unmounted(self):
+ self.info["MountPoint"] = ""
+ raw.write_led("/dev/rdisk4", "off")
+ self.assertEqual(self.pwrite.call_count, 2)
+
+ def test_missing_whole_disk_status_is_rejected(self):
+ del self.info["WholeDisk"]
+ self.refused()
+ self.open.assert_not_called()
+
+ def test_regular_file_rejected(self):
+ self.mock("os.fstat", return_value=SimpleNamespace(st_mode=stat.S_IFREG))
+ self.refused()
+
+ def test_bad_programs_rejected_before_open(self):
+ for text in ("", "x" * 513, "é" * 257, "off\n" * 21, "off\0"):
+ self.refused(text=text)
+ self.open.assert_not_called()
+
+ def test_full_sector_program(self):
+ raw.write_led("/dev/rdisk4", ";" + "x" * 511)
+ self.assertEqual(self.image[self.data_offset:self.data_offset + 512],
+ b";" + b"x" * 511)
+
+ def test_malformed_fat_and_missing_file_never_write(self):
+ for offset, data in ((510, b"\0\0"), (16, b"\x02"), (13, b"\0"),
+ (19, b"\xff\xff"), (22, b"\0\0"), (28, b"\x01"),
+ (1024, b"\0"), (1050, b"\xff\xff"),
+ (515, b"\0\0"), (1035, b"\x21")):
+ with self.subTest(offset=offset):
+ self.image, _, _ = fat12_image()
+ self.image[offset:offset + len(data)] = data
+ self.refused()
+
+ def test_short_read_never_writes(self):
+ self.mock("os.pread", return_value=b"")
+ self.refused()
+
+ def test_short_data_write_stops_before_directory(self):
+ self.pwrite.side_effect = None
+ self.pwrite.return_value = 12
+ with self.assertRaisesRegex(ValueError, "Short disk write"):
+ raw.write_led("/dev/rdisk4", "off")
+ self.assertEqual(self.pwrite.call_count, 1)
+ self.close.assert_called_once_with(43)
+
+ def test_symlinks_are_not_followed(self):
+ self.open.side_effect = OSError("symlink")
+ self.refused()
+ self.assertTrue(self.open.call_args.args[1] & raw.os.O_NOFOLLOW)
+
+
+if __name__ == "__main__":
+ unittest.main()