CLI for SidePulse
Python
Add size-limited raw FAT12 LED writer for macOS
Peter Kuhar74aa7c41464e
diff --git a/README.md b/README.mdindex ebdefa5..d4b2391 100644--- a/README.md+++ b/README.md@@ -143,6 +143,23 @@ sidepulse write "off" --device /media/$USER/SidePulseDotThe writer decodes simple escapes such as `\n`, then enforces the controller's512-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 iPhoneRun one command and either scan the terminal QR code with the SidePulse iOS appdiff --git a/scripts/write_led_raw.py b/scripts/write_led_raw.pynew file mode 100644index 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.pynew file mode 100644index 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()