blocksd 0.2.0__tar.gz

blocksd-0.2.0/.github/FUNDING.yml

@@ -0,0 +1,4 @@
+# These are supported funding model platforms
+
+github: hyperb1iss
+ko_fi: hyperb1iss

blocksd-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    uses: hyperb1iss/shared-workflows/.github/workflows/python-ci.yml@v1
+    with:
+      python-version: "3.13"
+      system-deps: libasound2-dev
+
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - run: sudo apt-get update && sudo apt-get install -y libasound2-dev
+      - uses: astral-sh/setup-uv@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: uv sync
+      - run: uv run ty check src

blocksd-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,63 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+  actions: read
+
+jobs:
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/blocksd
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.ref }}
+
+      - uses: astral-sh/setup-uv@v7
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    uses: hyperb1iss/shared-workflows/.github/workflows/github-release.yml@v1
+    needs: [pypi]
+    permissions:
+      contents: write
+      actions: read
+    secrets: inherit
+
+  aur:
+    name: Update AUR
+    runs-on: ubuntu-latest
+    needs: [pypi]
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Generate .SRCINFO and publish to AUR
+        uses: KSXGitHub/github-actions-deploy-aur@v3.0.1
+        with:
+          pkgname: blocksd
+          pkgbuild: packaging/aur/blocksd/PKGBUILD
+          updpkgsums: true
+          commit_message: "Update to ${{ steps.version.outputs.version }}"
+          ssh_private_key: ${{ secrets.AUR_SSH_KEY }}

blocksd-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,128 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (leave empty for auto-bump)"
+        required: false
+        default: ""
+      bump:
+        description: "Version bump type (if version not specified)"
+        required: false
+        type: choice
+        default: "patch"
+        options:
+          - patch
+          - minor
+          - major
+      dry_run:
+        description: "Dry run (skip tag, publish, and release)"
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  actions: write
+  contents: write
+  id-token: write
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Determine version
+        id: version
+        run: |
+          CURRENT=$(grep '^version' pyproject.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
+          echo "Current version: $CURRENT"
+
+          if [[ -n "${{ inputs.version }}" ]]; then
+            VERSION="${{ inputs.version }}"
+          else
+            IFS='.' read -r MAJOR MINOR PATCH <<< "${CURRENT%%-*}"
+            case "${{ inputs.bump }}" in
+              major) VERSION="$((MAJOR + 1)).0.0" ;;
+              minor) VERSION="${MAJOR}.$((MINOR + 1)).0" ;;
+              patch) VERSION="${MAJOR}.${MINOR}.$((PATCH + 1))" ;;
+            esac
+          fi
+
+          if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
+            echo "::error::Invalid version format: $VERSION"
+            exit 1
+          fi
+
+          if git tag -l "v$VERSION" | grep -q "v$VERSION"; then
+            echo "::error::Tag v$VERSION already exists"
+            exit 1
+          fi
+
+          echo "current=$CURRENT" >> $GITHUB_OUTPUT
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Releasing: $CURRENT → $VERSION"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Update version in pyproject.toml
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          sed -i "s/^version = .*/version = \"$VERSION\"/" pyproject.toml
+          echo "Updated pyproject.toml to $VERSION"
+
+      - name: Build package
+        run: uv build
+
+      - name: Commit version bump
+        if: ${{ !inputs.dry_run }}
+        run: |
+          git add pyproject.toml
+          git commit -m "release: v${{ steps.version.outputs.version }}"
+
+      - name: Create and push tag
+        if: ${{ !inputs.dry_run }}
+        run: |
+          git tag -a "v${{ steps.version.outputs.version }}" -m "Release v${{ steps.version.outputs.version }}"
+          git push origin HEAD:${{ github.ref_name }}
+          git push origin "v${{ steps.version.outputs.version }}"
+
+      - name: Trigger publish workflow
+        if: ${{ !inputs.dry_run }}
+        run: |
+          gh workflow run publish.yml --ref "v${{ steps.version.outputs.version }}"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Summary
+        run: |
+          echo "## Release ${{ inputs.dry_run && '[DRY RUN] ' || '' }}v${{ steps.version.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          if [[ "${{ inputs.dry_run }}" == "true" ]]; then
+            echo "Build passed. Ready to release." >> $GITHUB_STEP_SUMMARY
+          else
+            echo "Released: ${{ steps.version.outputs.current }} → ${{ steps.version.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "[blocksd on PyPI](https://pypi.org/project/blocksd/${{ steps.version.outputs.version }}/)" >> $GITHUB_STEP_SUMMARY
+          fi

blocksd-0.2.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+.env
+.pytest_cache/
+.ruff_cache/
+.ty/
+*.so
+.coverage
+htmlcov/
+.hypothesis/
+
+# Web UI
+web/node_modules/
+src/blocksd/web/static/

blocksd-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ["--maxkb=1000"]
+      - id: check-merge-conflict
+      - id: detect-private-key
+      - id: mixed-line-ending
+        args: ["--fix=lf"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.0
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format

blocksd-0.2.0/.python-version

@@ -0,0 +1 @@
+3.13

blocksd-0.2.0/CLAUDE.md

@@ -0,0 +1,305 @@
+# blocksd — ROLI Blocks Linux Daemon
+
+## Project Overview
+
+Linux daemon that implements the ROLI Blocks protocol to keep devices alive, control LEDs, and manage topology. ROLI devices require an active host-side handshake over MIDI SysEx to enter "API mode" — without it, they show a "searching" animation and eventually power off.
+
+**Stack:** Python 3.13, asyncio, python-rtmidi, Typer, Rich, Pydantic
+**Package Manager:** uv
+**Linter:** ruff
+**Type Checker:** ty
+
+## Architecture
+
+```
+daemon.py                 asyncio main loop, signal handling
+  └─ TopologyManager      polls MIDI ports every 1.5s
+       └─ DeviceGroup     per-USB lifecycle (serial → topology → API mode → ping)
+            └─ MidiConnection   python-rtmidi wrapper (send/receive SysEx)
+                 └─ protocol/*   pure protocol logic (packing, builder, decoder)
+```
+
+## ROLI Blocks Protocol Reference
+
+### SysEx Framing
+
+All BLOCKS protocol messages are MIDI SysEx:
+
+```
+F0 00 21 10 77 [deviceIndex] [7-bit packed payload] [checksum] F7
+│  │           │  │                                  │
+│  │           │  └ lower 6 bits = topology index    └ payload checksum & 0x7F
+│  │           │    bit 6: 0=host→device, 1=device→host
+│  │           └ BLOCKS product byte
+│  └ ROLI manufacturer ID
+└ SysEx start
+```
+
+### Checksum Calculation
+
+```python
+def calculate_checksum(data: bytes) -> int:
+    checksum = len(data) & 0xFF
+    for byte in data:
+        checksum = (checksum + (checksum * 2 + byte)) & 0xFF
+    return checksum & 0x7F
+```
+
+### 7-Bit Packing
+
+Payload bits are packed LSB-first across 7-bit bytes (bit 7 always 0 for MIDI safety). When a value spans byte boundaries, low bits fill the current byte remainder, high bits continue in the next byte's low bits.
+
+### Serial Number Request (separate SysEx format)
+
+- **Request:** `F0 00 21 10 78 3F F7`
+- **Response header:** `F0 00 21 10 78`
+- Response contains MAC prefix `48:B6:20:` followed by 16-char serial
+- Serial prefixes identify device type:
+  - `LPB`/`LPM` = Lightpad Block
+  - `SBB` = Seaboard Block
+  - `LKB` = LUMI Keys Block
+  - `LIC` = Live Block
+  - `LOC` = Loop Block
+  - `DCB` = Developer Control Block
+  - `TCB` = Touch Block
+
+### USB Device IDs (Vendor `0x2AF4`)
+
+| PID      | Device              |
+| -------- | ------------------- |
+| `0x0100` | Seaboard (original) |
+| `0x0200` | Seaboard RISE 25    |
+| `0x0210` | Seaboard RISE 49    |
+| `0x0700` | Seaboard Block      |
+| `0x0900` | Lightpad Block      |
+| `0x0E00` | LUMI Keys / Piano M |
+| `0x0F00` | ROLI Piano (49-key) |
+| `0x1000` | ROLI Airwave Pedal  |
+
+### Protocol Constants
+
+```
+ROLI_SYSEX_HEADER     = F0 00 21 10 77
+SERIAL_DUMP_REQUEST   = F0 00 21 10 78 3F F7
+SERIAL_RESPONSE_HDR   = F0 00 21 10 78
+RESET_MASTER          = F0 00 21 10 49 F7
+PROTOCOL_VERSION      = 1
+TOPOLOGY_INDEX_BROADCAST = 63
+API_MODE_PING_TIMEOUT_MS = 5000
+```
+
+### Message Types — Device → Host
+
+| ID     | Name                   | Payload                                         |
+| ------ | ---------------------- | ----------------------------------------------- |
+| `0x01` | deviceTopology         | 7b deviceCount, 8b connectionCount, then blocks |
+| `0x02` | packetACK              | 10b packetCounter                               |
+| `0x03` | firmwareUpdateACK      | 7b code, 32b detail                             |
+| `0x04` | deviceTopologyExtend   | continuation of topology                        |
+| `0x05` | deviceTopologyEnd      | signals end of multi-packet topology            |
+| `0x06` | deviceVersion          | index + version string                          |
+| `0x07` | deviceName             | index + name string                             |
+| `0x10` | touchStart             | 7b devIdx, 5b touchIdx, 12b x, 12b y, 8b z      |
+| `0x11` | touchMove              | same as touchStart                              |
+| `0x12` | touchEnd               | same as touchStart                              |
+| `0x13` | touchStartWithVelocity | + 8b vx, 8b vy, 8b vz                           |
+| `0x14` | touchMoveWithVelocity  | + velocity                                      |
+| `0x15` | touchEndWithVelocity   | + velocity                                      |
+| `0x18` | configMessage          | config command + data                           |
+| `0x20` | controlButtonDown      | 7b devIdx, 12b buttonID                         |
+| `0x21` | controlButtonUp        | 7b devIdx, 12b buttonID                         |
+| `0x28` | programEventMessage    | 3 × 32b integers                                |
+| `0x30` | logMessage             | string data                                     |
+
+### Message Types — Host → Device
+
+| ID     | Name                 | Payload                            |
+| ------ | -------------------- | ---------------------------------- |
+| `0x01` | deviceCommandMessage | 9b command (see Device Commands)   |
+| `0x02` | sharedDataChange     | 16b packetIndex + data change cmds |
+| `0x03` | programEventMessage  | 3 × 32b integers                   |
+| `0x04` | firmwareUpdatePacket | 7b size + 7-bit encoded data       |
+| `0x10` | configMessage        | 4b configCmd + item + value        |
+| `0x11` | factoryReset         | (no payload)                       |
+| `0x12` | blockReset           | (no payload)                       |
+| `0x20` | setName              | 7b length + 7-bit chars            |
+
+### Device Commands (inside deviceCommandMessage)
+
+| ID     | Name                   |
+| ------ | ---------------------- |
+| `0x00` | beginAPIMode           |
+| `0x01` | requestTopologyMessage |
+| `0x02` | endAPIMode             |
+| `0x03` | ping                   |
+| `0x04` | debugMode              |
+| `0x05` | saveProgramAsDefault   |
+
+### Config Commands
+
+| ID     | Name               |
+| ------ | ------------------ |
+| `0x00` | setConfig          |
+| `0x01` | requestConfig      |
+| `0x02` | requestFactorySync |
+| `0x03` | requestUserSync    |
+| `0x04` | updateConfig       |
+| `0x05` | updateUserConfig   |
+| `0x06` | setConfigState     |
+| `0x07` | factorySyncEnd     |
+| `0x08` | clusterConfigSync  |
+| `0x09` | factorySyncReset   |
+
+### Data Change Commands (for sharedDataChange / program upload)
+
+| ID  | Name                     | Extra bits                  |
+| --- | ------------------------ | --------------------------- |
+| `0` | endOfPacket              | —                           |
+| `1` | endOfChanges             | —                           |
+| `2` | skipBytesFew             | 4b count                    |
+| `3` | skipBytesMany            | 8b count                    |
+| `4` | setSequenceOfBytes       | (8b value + 1b continues)×N |
+| `5` | setFewBytesWithValue     | 4b count + 8b value         |
+| `6` | setFewBytesWithLastValue | 4b count                    |
+| `7` | setManyBytesWithValue    | 8b count + 8b value         |
+
+### Topology Packet Format
+
+Device info block (per device in topology):
+
+- 16 × 7-bit chars: serial number
+- 5 bits: battery level
+- 1 bit: battery charging
+
+Connection info block:
+
+- 7 bits: device1 topology index
+- 5 bits: device1 port (clockwise from top-left)
+- 7 bits: device2 topology index
+- 5 bits: device2 port
+
+Max 6 devices and 24 connections per topology packet. Use extend/end for larger topologies.
+
+### Connection Lifecycle (from roli_ConnectedDeviceGroup.cpp)
+
+```
+1. Scan MIDI ports for names containing "BLOCK" or "Block"
+2. Open matched in/out pair
+3. Send serial dump: F0 00 21 10 78 3F F7 (retry every 300ms)
+4. Parse serial from response (find "48:B6:20:", skip MAC, read 16 chars)
+5. Send requestTopologyMessage (cmd 0x01) to device index 0
+6. Parse topology response → build device list
+7. For each device not yet in API mode:
+   a. Send endAPIMode (cmd 0x02) — reset stale state
+   b. Send beginAPIMode (cmd 0x00) — enter rich protocol
+8. Ping loop:
+   - Master block: ping every ~400ms
+   - DNA-connected blocks: ping every ~1666ms
+   - Device timeout: 5000ms without ping → falls back to MPE mode
+9. On ACK received: update ping timer for that device
+10. On topology change: re-request topology
+11. On disconnect: destroy group, emit device-removed
+```
+
+### Bit Sizes Reference
+
+| Field              | Bits |
+| ------------------ | ---- |
+| MessageType        | 7    |
+| ProtocolVersion    | 8    |
+| PacketTimestamp    | 32   |
+| TimestampOffset    | 5    |
+| TopologyIndex      | 7    |
+| DeviceCount        | 7    |
+| ConnectionCount    | 8    |
+| BatteryLevel       | 5    |
+| BatteryCharging    | 1    |
+| ConnectorPort      | 5    |
+| TouchIndex         | 5    |
+| TouchPosition.x    | 12   |
+| TouchPosition.y    | 12   |
+| TouchPosition.z    | 8    |
+| TouchVelocity.v\*  | 8    |
+| DeviceCommand      | 9    |
+| ConfigCommand      | 4    |
+| ConfigItemIndex    | 8    |
+| ConfigItemValue    | 32   |
+| ControlButtonID    | 12   |
+| PacketCounter      | 10   |
+| PacketIndex        | 16   |
+| DataChangeCommand  | 3    |
+| ByteCountFew       | 4    |
+| ByteCountMany      | 8    |
+| ByteValue          | 8    |
+| ByteSequenceCont   | 1    |
+| FirmwareUpdateACK  | 7    |
+| FirmwareUpdateDtl  | 32   |
+| FirmwareUpdateSize | 7    |
+
+### Device Memory Sizes
+
+| Device Type   | Program + Heap | Stack |
+| ------------- | -------------- | ----- |
+| Pad Block     | 7200 bytes     | 800   |
+| Control Block | 3000 bytes     | 800   |
+
+## Key Reference Files
+
+Protocol source (cloned to `~/Downloads/roli-extracted/roli_blocks_basics/`):
+
+- `protocol/roli_BitPackingUtilities.h` — 7-bit packing algorithm (CRITICAL to port correctly)
+- `protocol/roli_BlocksProtocolDefinitions.h` — all enums, constants, bit sizes
+- `protocol/roli_HostPacketBuilder.h` — host→device packet construction
+- `protocol/roli_HostPacketDecoder.h` — device→host packet parsing
+- `protocol/roli_BlockModels.h` — device type definitions and capabilities
+- `topology/internal/roli_ConnectedDeviceGroup.cpp` — full device lifecycle state machine
+- `topology/internal/roli_BlockSerialReader.cpp` — serial number request/parse
+- `topology/internal/roli_MIDIDeviceDetector.cpp` — MIDI port scanning/matching
+- `topology/internal/roli_Detector.cpp` — top-level detection loop
+- `topology/internal/roli_MidiDeviceConnection.cpp` — MIDI I/O wrapper
+
+Extracted ROLI Connect installer (`~/Downloads/roli-extracted/`):
+
+- `rpkg-driver/` — Windows driver package (reference only)
+- `midi-driver/DriverINF` — USB VID/PID mapping
+- `app-asar-unpacked/` — Electron app source (minified JS)
+- `app/resources/app/resources/extra/firmware/default/*.littlefoot` — device firmware
+
+## Implementation Phases
+
+### Phase 1: Protocol Core (no hardware needed)
+
+`protocol/constants.py` → `protocol/checksum.py` → `protocol/packing.py` → `protocol/builder.py` → `protocol/decoder.py` → `protocol/serial.py` + full test suite
+
+### Phase 2: Device Models
+
+`device/models.py` → `device/registry.py` → `device/config_ids.py`
+
+### Phase 3: Connection Layer
+
+`device/connection.py` → `topology/detector.py` → `topology/device_group.py` → `topology/manager.py`
+
+### Phase 4: Daemon + Config
+
+`daemon.py` → `config/schema.py` + `config/loader.py` → `logging.py`
+
+### Phase 5: CLI
+
+`cli/app.py` → `cli/status.py` → `cli/config_cmd.py` → `cli/led_cmd.py`
+
+### Phase 6: LED Control + Program Upload
+
+`led/bitmap.py` → `led/patterns.py` → `protocol/data_change.py`
+
+### Phase 7: Polish
+
+systemd service → udev rules → `cli/service.py` → sd_notify integration
+
+## Critical Implementation Notes
+
+- **7-bit packing is the #1 risk** — must be tested exhaustively with round-trips and golden vectors from the C++ implementation
+- **Ping timing is critical** — 5000ms timeout means we need reliable <400ms ping intervals. Use dedicated asyncio tasks, not shared timers
+- **rtmidi callbacks arrive on a separate thread** — marshal to asyncio via `loop.call_soon_threadsafe()` or `asyncio.Queue`
+- **ALSA handles multi-client MIDI natively** — we don't block DAW access
+- **Device detection**: match MIDI port names containing "BLOCK" or "Block", validate with USB VID `0x2AF4` via sysfs as fallback
+- **Incoming packet processing**: strip SysEx header (5 bytes), first byte after header is device index, remaining bytes are payload + checksum (last byte). Validate checksum on payload bytes, then create `Packed7BitReader` from payload (excluding checksum)

blocksd-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing to blocksd
+
+Contributions welcome! Bug fixes, device support, new features, we'd love your help.
+
+## Setup
+
+```bash
+git clone https://github.com/hyperb1iss/blocksd.git
+cd blocksd
+uv sync          # installs all dependencies including dev tools
+```
+
+## Development Workflow
+
+The project includes a [justfile](https://just.systems/) for common tasks:
+
+```bash
+just check          # lint + format check + typecheck + tests (the full gate)
+just test           # run all tests
+just test-v         # verbose test output
+just test-mod protocol  # tests for a specific module
+just lint           # ruff lint
+just fmt            # auto-format
+just typecheck      # ty check
+just fix            # auto-fix lint + format
+```
+
+Or run tools directly:
+
+```bash
+uv run pytest                  # all tests
+uv run pytest -v               # verbose
+uv run pytest tests/protocol/  # specific module
+uv run ruff check .            # lint
+uv run ruff format .           # auto-format
+uv run ty check                # type check
+uv run blocksd run -v          # run the daemon (requires hardware)
+```
+
+## Project Structure
+
+- **`src/blocksd/protocol/`**: pure protocol logic (packing, builder, decoder), no I/O, fully testable
+- **`src/blocksd/device/`**: device models, config IDs, connection layer
+- **`src/blocksd/topology/`**: device discovery, lifecycle management, topology tracking
+- **`src/blocksd/led/`**: LED bitmap grid and pattern generators
+- **`src/blocksd/littlefoot/`**: LittleFoot VM opcodes, assembler, programs
+- **`src/blocksd/api/`**: Unix socket + WebSocket server, event broadcasting
+- **`src/blocksd/web/`**: web dashboard assets
+- **`src/blocksd/config/`**: daemon configuration (Pydantic schema, TOML loader)
+- **`src/blocksd/cli/`**: Typer CLI commands
+- **`tests/`**: mirrors source structure
+
+## Best Areas to Contribute
+
+- **LED patterns**: new visual patterns for Lightpad blocks
+- **Touch event handling**: higher-level gestures, MIDI mapping
+- **Web dashboard**: enhance the `blocksd ui` real-time interface
+- **D-Bus interface**: IPC for desktop integration
+- **Device support**: testing with Seaboard, Live, Loop, or Developer blocks
+- **Documentation**: usage guides, API examples (see `docs/` for protocol reference)
+
+## Guidelines
+
+- All code must pass `ruff check`, `ruff format --check`, and `ty check`
+- Add tests for new functionality, the protocol layer especially should have exhaustive coverage
+- Keep commits focused and descriptive
+- The protocol layer is pure functions with no I/O, keep it that way
+
+## Testing Without Hardware
+
+Most of the codebase is testable without a physical ROLI device. The protocol layer, LED bitmap logic, and LittleFoot assembler are all pure computation. Only the topology/connection layer requires hardware.
+
+```bash
+# Run just the hardware-free tests
+uv run pytest tests/protocol/ tests/led/ tests/littlefoot/ tests/device/
+```

blocksd-0.2.0/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025-2026 hyperb1iss (Stefanie Jane)
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.