Skip to content

CLI for SidePulse

Python

Add firmware version and upgrade commands with 1.1.0 packages

Peter Kuhar0454ef58fda5
diff --git a/README.md b/README.md
index af0ab99..9eacebb 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,9 @@ The device mounts as a disk drive. You can control the LEDs by writing to `LEDS.
The LED control DSL is described in [`LEDS_FORMAT.md`](LEDS_FORMAT.md).
+Firmware downloads and release notes are available in
+[`firmware/README.md`](firmware/README.md).
+
## Installation
Choose the level that fits how you want to use SidePulse.
@@ -64,6 +67,44 @@ python3 -m pip install -e .
sidepulse setup
```
+### Firmware
+
+Show the firmware version of connected SidePulse devices:
+
+```sh
+sidepulse firmware version
+```
+
+Upgrade a connected device to the latest published firmware for its model:
+
+```sh
+sidepulse firmware upgrade
+sidepulse firmware upgrade --dry-run
+```
+
+The CLI downloads firmware from this repository on GitHub and verifies the ZIP
+and its contents before writing to the device. `--dry-run` downloads and checks
+the package without writing it. With multiple devices connected, select one
+using `--device /Volumes/SidePulse` or `--device /Volumes/PulseDot` (use the actual
+mount path on your computer).
+
+Choose a specific version or install a downloaded ZIP:
+
+```sh
+sidepulse firmware upgrade --version 1.1.0
+sidepulse firmware upgrade --file firmware/v1.1.0/sidepulse-pro-1.1.0-ota.zip
+```
+
+Use the ZIP for your model from the [firmware downloads](firmware/README.md).
+Local ZIPs work offline. The CLI rejects packages for the wrong model and older
+versions, and skips a version that is already installed. Copy-based upgrades
+require a writable device drive.
+
+After the transfer, leave the device connected for at least 10 seconds, then
+reconnect it and run `sidepulse firmware version` to confirm the installed
+version. Reconnecting avoids a cached status file. Use `sidepulse firmware
+version --json` for machine-readable output.
+
### Updating
```sh
diff --git a/firmware/README.md b/firmware/README.md
new file mode 100644
index 0000000..b6fd08d
--- /dev/null
+++ b/firmware/README.md
@@ -0,0 +1,47 @@
+# Firmware release notes
+
+Firmware ZIP files are organized by version. Download the ZIP for your SidePulse
+model; firmware is specific to each model.
+
+## v1.1.0
+
+First firmware release distributed in this repository.
+
+| Model | Download |
+| --- | --- |
+| SidePulse Dot | [sidepulse-dot-1.1.0-ota.zip](v1.1.0/sidepulse-dot-1.1.0-ota.zip) |
+| SidePulse Pro | [sidepulse-pro-1.1.0-ota.zip](v1.1.0/sidepulse-pro-1.1.0-ota.zip) |
+
+[SHA-256 checksums](v1.1.0/SHA256SUMS.txt) are included for both ZIP files.
+
+### SidePulse Dot
+
+- Add animation updates on devices with read-only storage, where permitted by
+ device management policies.
+- Support animation programs up to 512 bytes.
+- Reduce power use when the LEDs are off.
+
+### SidePulse Pro
+
+- Improve white balance and dynamic range.
+- Add animation, startup settings, and firmware updates on devices with read-only
+ storage, where permitted by device management policies.
+- Improve update reliability and file preservation across restarts.
+- Improve SD-reader compatibility and recovery from interrupted reads.
+
+## Installation
+
+1. Extract the ZIP for your model on your computer.
+2. Connect your device and open its drive: `PulseDot` for SidePulse Dot or
+ `SidePulse` for SidePulse Pro.
+3. Copy only `FIRMWARE.BIN` to the top level of the drive. Choose Replace if the
+ file already exists.
+4. After copying finishes, leave the device connected and untouched for at least
+ 10 seconds while it applies the update and restarts.
+5. Reconnect the device, then open `STATUS.TXT` and check that `app_version`
+ (Dot) or `release_version` (Pro) matches the version you downloaded, such as
+ `1.1.0`. Reconnecting avoids a cached copy of `STATUS.TXT` on your computer.
+
+Do not rename `FIRMWARE.BIN` or copy the ZIP itself onto the drive. The other files
+in each ZIP are for reference. Normal copy/paste updates require a writable drive;
+read-only storage policies may prevent this installation method.
diff --git a/firmware/v1.1.0/SHA256SUMS.txt b/firmware/v1.1.0/SHA256SUMS.txt
new file mode 100644
index 0000000..8ba3ed5
--- /dev/null
+++ b/firmware/v1.1.0/SHA256SUMS.txt
@@ -0,0 +1,2 @@
+0e7325cacfa08a30cced5d0250ab3032e4c4b2b615dc3a09acb99f6021627761 sidepulse-dot-1.1.0-ota.zip
+1efc35498f837932938aaf1b3e4f2889549d09cfbf974ae1132cafb7768b6fac sidepulse-pro-1.1.0-ota.zip
diff --git a/firmware/v1.1.0/sidepulse-dot-1.1.0-ota.zip b/firmware/v1.1.0/sidepulse-dot-1.1.0-ota.zip
new file mode 100644
index 0000000..df8ce62
Binary files /dev/null and b/firmware/v1.1.0/sidepulse-dot-1.1.0-ota.zip differ
diff --git a/firmware/v1.1.0/sidepulse-pro-1.1.0-ota.zip b/firmware/v1.1.0/sidepulse-pro-1.1.0-ota.zip
new file mode 100644
index 0000000..89b4f09
Binary files /dev/null and b/firmware/v1.1.0/sidepulse-pro-1.1.0-ota.zip differ
diff --git a/src/sidepulse/cli.py b/src/sidepulse/cli.py
index f53fe0c..4daefeb 100644
--- a/src/sidepulse/cli.py
+++ b/src/sidepulse/cli.py
@@ -137,6 +137,9 @@ def build_sidepulse_parser() -> argparse.ArgumentParser:
help="Show the setup command without downloading or changing anything.",
)
update.set_defaults(func=cmd_sidepulse_update)
+ from .firmware import add_firmware_parser
+
+ add_firmware_parser(subparsers)
subparsers.add_parser(
"agent-monitor",
help="Install hooks and show live AI agent statuses.",
diff --git a/src/sidepulse/firmware.py b/src/sidepulse/firmware.py
new file mode 100644
index 0000000..149d928
--- /dev/null
+++ b/src/sidepulse/firmware.py
@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+import argparse
+import hashlib
+import http.client
+import io
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+import zipfile
+import zlib
+from dataclasses import dataclass
+from pathlib import Path
+
+from .device_writer import discover_devices, sync_directory
+
+
+RELEASES_URL = "https://api.github.com/repos/inteliwear/sidepulse/contents/firmware?ref=main"
+DOWNLOAD_ROOT = "https://raw.githubusercontent.com/inteliwear/sidepulse/main/firmware"
+MAX_PACKAGE_BYTES = 4 * 1024 * 1024
+PRODUCT_NAMES = {"dot": "SidePulse Dot", "pro": "SidePulse Pro"}
+PACKAGE_FILES = {"FIRMWARE.BIN", "README.txt", "RELEASE_NOTES.txt", "SHA256SUMS.txt"}
+
+
+class FirmwareError(RuntimeError):
+ pass
+
+
+@dataclass(frozen=True)
+class FirmwareDevice:
+ root: Path
+ product: str
+ version: str
+ serial: str
+
+ @property
+ def name(self) -> str:
+ return PRODUCT_NAMES[self.product]
+
+
+@dataclass(frozen=True)
+class FirmwarePackage:
+ product: str
+ version: str
+ payload: bytes
+
+
+def normalize_version(value: str) -> str:
+ match = re.fullmatch(r"v?(\d+)\.(\d+)(?:\.(\d+))?", value)
+ if not match:
+ raise FirmwareError(f"Invalid firmware version: {value!r}. Use a version such as 1.1.0.")
+ return ".".join(str(int(part or 0)) for part in match.groups())
+
+
+def version_key(value: str) -> tuple[int, ...]:
+ return tuple(int(part) for part in normalize_version(value).split("."))
+
+
+def read_device(root: Path) -> FirmwareDevice:
+ root = root.expanduser().resolve()
+ try:
+ with (root / "STATUS.TXT").open("rb") as stream:
+ text = stream.read(65536).decode("utf-8", errors="replace")
+ except OSError as exc:
+ raise FirmwareError(f"Cannot read {root / 'STATUS.TXT'}: {exc}") from exc
+ fields = {}
+ for line in text.replace("\x00", "").splitlines():
+ parts = line.strip().split(None, 1)
+ if len(parts) == 2:
+ fields[parts[0]] = parts[1]
+ dot = "app_version" in fields or ("app_build" in fields and "fw_state" in fields)
+ pro = "release_version" in fields or ("firmware_version" in fields and "firmware_slot" in fields)
+ if dot == pro:
+ raise FirmwareError(f"Cannot identify a SidePulse Dot or Pro from {root / 'STATUS.TXT'}.")
+ product = "dot" if dot else "pro"
+ version = fields.get("app_version" if dot else "release_version", "unknown")
+ return FirmwareDevice(root, product, version, fields.get("serial", "unassigned"))
+
+
+def find_devices(device_path: Path | None) -> list[FirmwareDevice]:
+ if device_path is not None:
+ return [read_device(device_path)]
+ devices = []
+ for candidate in discover_devices(file_name="STATUS.TXT"):
+ try:
+ devices.append(read_device(candidate.root))
+ except FirmwareError:
+ continue
+ if not devices:
+ raise FirmwareError("No mounted SidePulse device found. Connect it or pass --device /path/to/drive.")
+ return devices
+
+
+def download(url: str, *, limit: int = MAX_PACKAGE_BYTES) -> bytes:
+ request = urllib.request.Request(url, headers={"User-Agent": "sidepulse-cli", "Cache-Control": "no-cache"})
+ try:
+ with urllib.request.urlopen(request, timeout=30) as response:
+ data = response.read(limit + 1)
+ except (OSError, urllib.error.URLError, http.client.HTTPException) as exc:
+ raise FirmwareError(f"Could not download firmware release data: {exc}. You can use --file with a local OTA ZIP.") from exc
+ if len(data) > limit:
+ raise FirmwareError("Firmware download exceeds the size limit.")
+ return data
+
+
+def published_versions() -> list[str]:
+ try:
+ entries = json.loads(download(RELEASES_URL, limit=1024 * 1024))
+ except (ValueError, UnicodeError) as exc:
+ raise FirmwareError("The firmware release listing is invalid.") from exc
+ if not isinstance(entries, list):
+ raise FirmwareError("The firmware release listing is invalid.")
+ versions = [
+ entry["name"][1:]
+ for entry in entries
+ if isinstance(entry, dict) and entry.get("type") == "dir"
+ and re.fullmatch(r"v\d+\.\d+\.\d+", str(entry.get("name", "")))
+ ]
+ if not versions:
+ raise FirmwareError("No published firmware releases found.")
+ return sorted(set(versions), key=version_key, reverse=True)
+
+
+def parse_checksums(data: bytes) -> dict[str, str]:
+ try:
+ lines = data.decode("utf-8").splitlines()
+ except UnicodeError as exc:
+ raise FirmwareError("Invalid firmware checksums.") from exc
+ result = {}
+ for line in lines:
+ if not line.strip():
+ continue
+ match = re.fullmatch(r"([0-9a-fA-F]{64}) ([A-Za-z0-9_.-]+)", line)
+ if not match or match[2] in result:
+ raise FirmwareError("Invalid firmware checksums.")
+ result[match[2]] = match[1].lower()
+ return result
+
+
+def verify_checksum(data: bytes, expected: str | None, name: str) -> None:
+ if expected is None or hashlib.sha256(data).hexdigest() != expected:
+ raise FirmwareError(f"Firmware checksum mismatch: {name}.")
+
+
+def read_package(data: bytes, filename: str) -> FirmwarePackage:
+ match = re.fullmatch(r"sidepulse-(dot|pro)-(\d+\.\d+\.\d+)-ota\.zip", filename)
+ if not match:
+ raise FirmwareError("Use a customer OTA ZIP named sidepulse-dot-VERSION-ota.zip or sidepulse-pro-VERSION-ota.zip.")
+ product, version = match.groups()
+ if len(data) > MAX_PACKAGE_BYTES:
+ raise FirmwareError("Firmware package exceeds the size limit.")
+ try:
+ with zipfile.ZipFile(io.BytesIO(data)) as archive:
+ names = archive.namelist()
+ prefix = "" if set(names) == PACKAGE_FILES else filename[:-4] + "/"
+ if len(names) != 4 or set(names) != {prefix + name for name in PACKAGE_FILES}:
+ raise FirmwareError("Unexpected files in firmware package.")
+ if sum(info.file_size for info in archive.infolist()) > MAX_PACKAGE_BYTES:
+ raise FirmwareError("Expanded firmware package exceeds the size limit.")
+ contents = {name: archive.read(prefix + name) for name in PACKAGE_FILES}
+ except (zipfile.BadZipFile, RuntimeError, NotImplementedError, OSError, zlib.error) as exc:
+ raise FirmwareError(f"Invalid firmware ZIP: {exc}") from exc
+ checksums = parse_checksums(contents["SHA256SUMS.txt"])
+ if set(checksums) != PACKAGE_FILES - {"SHA256SUMS.txt"}:
+ raise FirmwareError("Firmware package checksums are incomplete.")
+ for name, digest in checksums.items():
+ verify_checksum(contents[name], digest, name)
+ title = f"{PRODUCT_NAMES[product]} firmware update - version {version}"
+ if contents["README.txt"].splitlines()[:1] != [title.encode()]:
+ raise FirmwareError("Firmware package model or version does not match its filename.")
+ if not contents["FIRMWARE.BIN"]:
+ raise FirmwareError("Firmware image is empty.")
+ return FirmwarePackage(product, version, contents["FIRMWARE.BIN"])
+
+
+def load_package(product: str, version: str | None, path: Path | None) -> FirmwarePackage:
+ if path is not None:
+ path = path.expanduser()
+ with path.open("rb") as stream:
+ return read_package(stream.read(MAX_PACKAGE_BYTES + 1), path.name)
+ releases = [normalize_version(version)] if version else published_versions()
+ for release in releases:
+ name = f"sidepulse-{product}-{release}-ota.zip"
+ base = f"{DOWNLOAD_ROOT}/v{release}"
+ checksums = parse_checksums(download(f"{base}/SHA256SUMS.txt", limit=65536))
+ if name not in checksums:
+ continue
+ data = download(f"{base}/{name}")
+ verify_checksum(data, checksums[name], name)
+ return read_package(data, name)
+ requested = f" for {normalize_version(version)}" if version else ""
+ raise FirmwareError(f"No published {PRODUCT_NAMES[product]} firmware package found{requested}.")
+
+
+def write_firmware(device: FirmwareDevice, package: FirmwarePackage) -> None:
+ # Recheck identity after downloading, before opening the update file.
+ if read_device(device.root) != device:
+ raise FirmwareError("The connected device changed. Run the upgrade again.")
+ target = device.root / "FIRMWARE.BIN"
+ if target.is_symlink():
+ raise FirmwareError("The firmware target must not be a symbolic link.")
+ try:
+ with target.open("wb") as stream:
+ stream.write(package.payload)
+ stream.flush()
+ os.fsync(stream.fileno())
+ sync_directory(device.root)
+ except OSError as exc:
+ raise FirmwareError(
+ f"Firmware transfer did not finish: {exc}. Keep the device connected for at least "
+ "10 seconds, then reconnect and check its version before retrying. "
+ "Copy-based upgrades require a writable drive."
+ ) from exc
+
+
+def cmd_firmware_version(args: argparse.Namespace) -> int:
+ try:
+ devices = find_devices(args.device)
+ except (FirmwareError, OSError) as exc:
+ print(f"SidePulse firmware: {exc}", file=sys.stderr)
+ return 1
+ if args.json:
+ print(json.dumps([
+ {"model": device.name, "version": device.version, "serial": device.serial, "device": str(device.root)}
+ for device in devices
+ ]))
+ else:
+ for device in devices:
+ print(f"{device.name}: {device.version} ({device.root}, serial {device.serial})")
+ return 0
+
+
+def cmd_firmware_upgrade(args: argparse.Namespace) -> int:
+ try:
+ devices = find_devices(args.device)
+ if len(devices) != 1:
+ paths = "\n".join(f" {device.root}" for device in devices)
+ raise FirmwareError("Multiple SidePulse devices found. Select one with --device:\n" + paths)
+ device = devices[0]
+ print(f"{device.name}: firmware {device.version} ({device.root})", flush=True)
+ package = load_package(device.product, args.release_version, args.file)
+ if package.product != device.product:
+ raise FirmwareError(f"This ZIP is for {PRODUCT_NAMES[package.product]}, but the device is {device.name}.")
+ try:
+ current = version_key(device.version)
+ except FirmwareError:
+ current = None
+ target = version_key(package.version)
+ if current == target:
+ print(f"{device.name} is already on firmware {package.version}.")
+ return 0
+ if current is not None and current > target:
+ raise FirmwareError(f"Firmware {package.version} is older than installed version {device.version}; downgrade refused.")
+ if args.dry_run:
+ print(f"Would upgrade {device.name} from {device.version} to {package.version}. Package verified; no files written.")
+ return 0
+ print(f"Sending firmware {package.version}. Keep the device connected.", flush=True)
+ write_firmware(device, package)
+ print(
+ f"Firmware {package.version} transferred. Leave the device connected for at least 10 seconds "
+ "while it applies the update, then reconnect and run `sidepulse firmware version` "
+ "to confirm installation."
+ )
+ return 0
+ except (FirmwareError, OSError) as exc:
+ print(f"SidePulse firmware upgrade failed: {exc}", file=sys.stderr)
+ return 1
+
+
+def add_firmware_parser(subparsers: argparse._SubParsersAction) -> None:
+ firmware = subparsers.add_parser("firmware", help="Show or upgrade device firmware.")
+ commands = firmware.add_subparsers(dest="firmware_command", required=True)
+ version = commands.add_parser("version", help="Show firmware versions of connected devices.")
+ version.add_argument("--device", type=Path, help="Mounted SidePulse drive. Default: all detected devices.")
+ version.add_argument("--json", action="store_true", help="Print device versions as JSON.")
+ version.set_defaults(func=cmd_firmware_version)
+ upgrade = commands.add_parser("upgrade", help="Install the latest published firmware for a connected device.")
+ upgrade.add_argument("--device", type=Path, help="Mounted SidePulse drive. Required when multiple devices are connected.")
+ source = upgrade.add_mutually_exclusive_group()
+ source.add_argument("--version", dest="release_version", help="Install a specific release, such as 1.1.0.")
+ source.add_argument("--file", type=Path, help="Install a local customer OTA ZIP.")
+ upgrade.add_argument("--dry-run", action="store_true", help="Download and verify the package without writing to the device.")
+ upgrade.set_defaults(func=cmd_firmware_upgrade)
diff --git a/tests/test_firmware.py b/tests/test_firmware.py
new file mode 100644
index 0000000..b091175
--- /dev/null
+++ b/tests/test_firmware.py
@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import tempfile
+import unittest
+import zipfile
+from pathlib import Path
+from unittest.mock import patch
+
+from sidepulse.cli import sidepulse_main
+from sidepulse import firmware
+
+
+def package_bytes(product='pro', version='1.1.0', *, nested=True, tamper=False):
+ title = firmware.PRODUCT_NAMES[product]
+ files = {
+ 'FIRMWARE.BIN': b'encrypted firmware payload',
+ 'README.txt': f'{title} firmware update - version {version}\n'.encode(),
+ 'RELEASE_NOTES.txt': f'# {title} {version}\n'.encode(),
+ }
+ files['SHA256SUMS.txt'] = ''.join(
+ f'{hashlib.sha256(data).hexdigest()} {name}\n' for name, data in files.items()
+ ).encode()
+ if tamper:
+ files['FIRMWARE.BIN'] = b'corrupt firmware'
+ output = io.BytesIO()
+ prefix = f'sidepulse-{product}-{version}-ota/' if nested else ''
+ with zipfile.ZipFile(output, 'w', zipfile.ZIP_DEFLATED) as archive:
+ for name, data in files.items():
+ archive.writestr(prefix + name, data)
+ return output.getvalue()
+
+
+class FirmwareTests(unittest.TestCase):
+ def setUp(self):
+ self.temp = tempfile.TemporaryDirectory()
+ self.addCleanup(self.temp.cleanup)
+ self.root = Path(self.temp.name)
+ self.device = self.make_device('pro')
+ self.stdout = io.StringIO()
+ self.stderr = io.StringIO()
+ self.addCleanup(patch.stopall)
+ patch('sys.stdout', self.stdout).start()
+ patch('sys.stderr', self.stderr).start()
+
+ def make_device(self, product, version='1.0.5'):
+ device = self.root / product
+ device.mkdir(exist_ok=True)
+ field = 'app_version' if product == 'dot' else 'release_version'
+ (device / 'STATUS.TXT').write_bytes(f'{field} {version}\nserial SP-123\n'.encode() + b'\0' * 100)
+ return device
+
+ def make_package(self, product='pro', version='1.1.0', **kwargs):
+ path = self.root / f'sidepulse-{product}-{version}-ota.zip'
+ path.write_bytes(package_bytes(product, version, **kwargs))
+ return path
+
+ def upgrade(self, package, *args):
+ return sidepulse_main(['firmware', 'upgrade', '--device', str(self.device), '--file', str(package), *args])
+
+ def test_version_reports_both_models_and_json(self):
+ self.make_device('dot', '1.1.0')
+ with patch.dict('os.environ', {'SIDEPULSE_MOUNT_ROOTS': str(self.root)}):
+ self.assertEqual(sidepulse_main(['firmware', 'version', '--json']), 0)
+ output = json.loads(self.stdout.getvalue())
+ self.assertEqual([(d['model'], d['version']) for d in output], [('SidePulse Dot', '1.1.0'), ('SidePulse Pro', '1.0.5')])
+ self.assertEqual(output[0]['serial'], 'SP-123')
+
+ def test_explicit_renamed_drive_uses_status_not_volume_name(self):
+ self.assertEqual(sidepulse_main(['firmware', 'version', '--device', str(self.device)]), 0)
+ self.assertIn('SidePulse Pro: 1.0.5', self.stdout.getvalue())
+
+ def test_missing_device_fails_without_download(self):
+ with patch.dict('os.environ', {'SIDEPULSE_MOUNT_ROOTS': str(self.root / 'missing')}), patch.object(firmware, 'download') as download:
+ self.assertEqual(sidepulse_main(['firmware', 'upgrade']), 1)
+ download.assert_not_called()
+ self.assertIn('No mounted SidePulse', self.stderr.getvalue())
+
+ def test_multiple_devices_require_selection_before_download(self):
+ self.make_device('dot')
+ with patch.dict('os.environ', {'SIDEPULSE_MOUNT_ROOTS': str(self.root)}), patch.object(firmware, 'download') as download:
+ self.assertEqual(sidepulse_main(['firmware', 'upgrade']), 1)
+ download.assert_not_called()
+ self.assertIn('--device', self.stderr.getvalue())
+
+ def test_invalid_or_ambiguous_status_is_rejected(self):
+ for status in ('hello\n', 'release_version 1.0.5\napp_version 1.0.5\n'):
+ (self.device / 'STATUS.TXT').write_text(status)
+ with self.assertRaises(firmware.FirmwareError):
+ firmware.read_device(self.device)
+
+ def test_older_pro_status_shows_unknown_release(self):
+ (self.device / 'STATUS.TXT').write_text('firmware_version 12345\nfirmware_slot A\n')
+ self.assertEqual(firmware.read_device(self.device).version, 'unknown')
+
+ def test_copy_preserves_payload_and_existing_programs(self):
+ for name in ('LEDS.LED', 'INIT.LED'):
+ (self.device / name).write_text('existing program')
+ (self.device / 'FIRMWARE.BIN').write_bytes(b'old firmware with a longer payload' * 100)
+ with patch.object(firmware.os, 'fsync', wraps=firmware.os.fsync) as sync:
+ self.assertEqual(self.upgrade(self.make_package()), 0)
+ self.assertGreaterEqual(sync.call_count, 1)
+ self.assertEqual((self.device / 'FIRMWARE.BIN').read_bytes(), b'encrypted firmware payload')
+ for name in ('LEDS.LED', 'INIT.LED'):
+ self.assertEqual((self.device / name).read_text(), 'existing program')
+ self.assertIn('transferred', self.stdout.getvalue())
+ self.assertIn('confirm installation', self.stdout.getvalue())
+
+ def test_dry_run_verifies_without_writing(self):
+ self.assertEqual(self.upgrade(self.make_package(), '--dry-run'), 0)
+ self.assertFalse((self.device / 'FIRMWARE.BIN').exists())
+ self.assertIn('Would upgrade', self.stdout.getvalue())
+
+ def test_wrong_product_or_corrupt_package_never_writes(self):
+ for package in (self.make_package('dot'), self.make_package(tamper=True)):
+ self.assertEqual(self.upgrade(package), 1)
+ self.assertFalse((self.device / 'FIRMWARE.BIN').exists())
+
+ def test_same_version_is_noop_and_downgrade_is_rejected(self):
+ self.assertEqual(self.upgrade(self.make_package(version='1.0.5')), 0)
+ self.assertEqual(self.upgrade(self.make_package(version='1.0.4')), 1)
+ self.assertFalse((self.device / 'FIRMWARE.BIN').exists())
+
+ def test_status_identity_is_rechecked_after_download(self):
+ package = firmware.FirmwarePackage('pro', '1.1.0', b'payload')
+ def load(*args):
+ (self.device / 'STATUS.TXT').write_text('release_version 1.0.5\nserial DIFFERENT\n')
+ return package
+ with patch.object(firmware, 'load_package', side_effect=load):
+ self.assertEqual(self.upgrade(self.make_package()), 1)
+ self.assertFalse((self.device / 'FIRMWARE.BIN').exists())
+
+ def test_failed_flush_is_not_reported_as_success(self):
+ with patch.object(firmware.os, 'fsync', side_effect=OSError('write failed')):
+ self.assertEqual(self.upgrade(self.make_package()), 1)
+ self.assertNotIn('transferred', self.stdout.getvalue())
+ self.assertIn('did not finish', self.stderr.getvalue())
+
+ def test_symlink_target_is_rejected(self):
+ outside = self.root / 'unrelated'
+ outside.write_bytes(b'keep me')
+ (self.device / 'FIRMWARE.BIN').symlink_to(outside)
+ self.assertEqual(self.upgrade(self.make_package()), 1)
+ self.assertEqual(outside.read_bytes(), b'keep me')
+
+ def test_flat_and_nested_packages_are_supported(self):
+ for nested in (True, False):
+ parsed = firmware.read_package(package_bytes(nested=nested), 'sidepulse-pro-1.1.0-ota.zip')
+ self.assertEqual(parsed.version, '1.1.0')
+ self.assertEqual(parsed.payload, b'encrypted firmware payload')
+
+ def test_extra_and_traversal_entries_are_rejected(self):
+ for extra in ('../outside', 'sidepulse-pro-1.1.0-ota/extra.txt'):
+ data = io.BytesIO(package_bytes())
+ with zipfile.ZipFile(data, 'a') as archive:
+ archive.writestr(extra, 'unwanted')
+ with self.assertRaises(firmware.FirmwareError):
+ firmware.read_package(data.getvalue(), 'sidepulse-pro-1.1.0-ota.zip')
+
+ def test_renamed_model_and_version_are_rejected(self):
+ for filename in ('sidepulse-dot-1.1.0-ota.zip', 'sidepulse-pro-2.0.0-ota.zip'):
+ with self.assertRaises(firmware.FirmwareError):
+ firmware.read_package(package_bytes(nested=False), filename)
+
+ def test_latest_release_is_selected_numerically(self):
+ entries = [{'name': name, 'type': 'dir'} for name in ('v1.9.0', 'v1.10.0', 'v2.0.0-beta')]
+ with patch.object(firmware, 'download', return_value=json.dumps(entries).encode()):
+ self.assertEqual(firmware.published_versions(), ['1.10.0', '1.9.0'])
+
+ def test_latest_release_is_selected_for_the_connected_model(self):
+ data = package_bytes('dot')
+ sums = f'{hashlib.sha256(data).hexdigest()} sidepulse-dot-1.1.0-ota.zip\n'.encode()
+ pro_only = f'{"0" * 64} sidepulse-pro-1.2.0-ota.zip\n'.encode()
+ with patch.object(firmware, 'published_versions', return_value=['1.2.0', '1.1.0']), patch.object(firmware, 'download', side_effect=[pro_only, sums, data]):
+ self.assertEqual(firmware.load_package('dot', None, None).version, '1.1.0')
+
+ def test_requested_version_never_falls_back_to_another_release(self):
+ with patch.object(firmware, 'download', return_value=b'') as download:
+ with self.assertRaises(firmware.FirmwareError):
+ firmware.load_package('dot', '1.2.0', None)
+ self.assertEqual(download.call_count, 1)
+
+ def test_remote_package_is_verified_against_outer_checksum(self):
+ data = package_bytes()
+ sums = f'{hashlib.sha256(data).hexdigest()} sidepulse-pro-1.1.0-ota.zip\n'.encode()
+ with patch.object(firmware, 'download', side_effect=[sums, data]) as download:
+ package = firmware.load_package('pro', '1.1', None)
+ self.assertEqual(package.version, '1.1.0')
+ self.assertIn('/v1.1.0/SHA256SUMS.txt', download.call_args_list[0].args[0])
+ with patch.object(firmware, 'download', side_effect=[sums, data + b'corruption']):
+ with self.assertRaises(firmware.FirmwareError):
+ firmware.load_package('pro', '1.1.0', None)
+
+ def test_network_failure_and_invalid_zip_have_friendly_errors(self):
+ with patch.object(firmware.urllib.request, 'urlopen', side_effect=OSError('offline')):
+ self.assertEqual(sidepulse_main(['firmware', 'upgrade', '--device', str(self.device)]), 1)
+ self.assertIn('--file', self.stderr.getvalue())
+ with self.assertRaises(firmware.FirmwareError):
+ firmware.read_package(b'not a zip', 'sidepulse-pro-1.1.0-ota.zip')
+
+ def test_download_size_is_bounded(self):
+ with patch.object(firmware.urllib.request, 'urlopen', return_value=io.BytesIO(b'0123456789')):
+ with self.assertRaises(firmware.FirmwareError):
+ firmware.download('https://example.com', limit=3)
+
+ def test_invalid_version_does_not_download(self):
+ with patch.object(firmware, 'download') as download:
+ with self.assertRaises(firmware.FirmwareError):
+ firmware.load_package('pro', '../other', None)
+ download.assert_not_called()