JackFrostbyte/rgb-aura
1
2
Fork 0
Code Issues 24 Pull requests Projects Releases 2 Packages Wiki Activity Actions

Define minimal portable device profile schema (v1.1.0 unblocker) #66

New issue
Closed
opened 2026-05-18 10:28:22 -04:00 by McJuniorstein · 1 comment
McJuniorstein commented 2026-05-18 10:28:22 -04:00
Collaborator
Copy link

First concrete v1.1.0 issue, per §10.4 of issue #62 comment #273 and Jack's acceptance in comment #289.

Goal

Land a portable, minimal device_profile.json schema and a working example derived from Jack's existing config/device_map.json. This is the foundation the rest of v1.1.0 (aura profile, animation pack, prompt generator) builds on.

Scope (minimal — additions wait for the milestone that needs them)

Initial schema fields, per §10.4 of #273:

  • schema_version (string, semver) — explicit version tag so future schema evolutions can be detected and migrated.
  • machine_name (string) — human-readable identifier for the machine.
  • openrgb (object): host (string), port (integer).
  • devices (array of objects), each containing:
    • id (string, stable identifier)
    • openrgb_name (string, name as OpenRGB reports it)
    • type (enum: at minimum fan, motherboard, gpu, unknown)
    • zones (array of objects):
      • zone_index (integer, OpenRGB's index)
      • led_count (integer, total LEDs in the zone)
      • usable_leds (integer, LEDs RGB Aura should actually drive)

Acceptance criteria

  1. JSON Schema document checked in (path TBD in PR — likely schemas/device_profile.schema.json or similar).
  2. Working example device_profile.json for Jack's machine, derived from the current config/device_map.json. Roundtrip-equivalent — the runtime should be able to produce the same hardware behavior from either.
  3. The schema rejects malformed inputs with errors that follow the paste-back-friendly diagnostic shape from §4.2 of #273 (field path, expected, got, how to fix, example). The diagnose CLI itself is a separate issue — this one only requires that the validation errors carry the information needed to produce that output.
  4. Tests cover at least: valid example accepted, missing required field rejected, wrong-type field rejected, out-of-range LED count rejected.

Out of scope (deferred per #62 §8 cut list)

  • Setup wizard (rgb-aura setup) — v1.1.X or v1.2.0.
  • LED-by-LED mapping — v1.2.0.
  • Layout types beyond linear / unknown — v1.2.0.
  • LED groups — v1.2.0.
  • aura_profile.json and animation pack schemas — their own issues.
  • The rgb-aura migrate-profile CLI — its own issue (likely opened immediately after this one lands, since it's the path that turns device_map.json into the v1.1.X reality).
  • The rgb-aura pack diagnose CLI itself — its own issue.

Branch and PR plan

  • Branch from develop as feature/issue-<this-issue-number>-device-profile-schema.
  • McJuniorstein opens the PR; Jack reviews and merges per AGENTS.md §4.
  • No hardware-touching changes in this PR — it's pure schema + example + validation tests. Jack's review can be done without running on his rig.

Notes

  • Field naming and exact JSON Schema shape are up for discussion in the PR. This issue locks the scope; the PR locks the form.
  • The schema_version field starts at "1.0.0". Rationale: SemVer reserves 0.x.y for experimental APIs where anything can break; calling this schema experimental contradicts the "schema is the contract" framing from §4.1 of #273. Starting at 1.0.0 lets v1.1.X additions bump minor (additive, backward-compatible) and any breaking changes bump major — a distinction LLMs and validators can act on. Open to a different versioning scheme (e.g., integer-only) if you want to push back on this — say so before the PR opens.
First concrete v1.1.0 issue, per §10.4 of issue #62 comment #273 and Jack's acceptance in comment #289. ## Goal Land a portable, minimal `device_profile.json` schema and a working example derived from Jack's existing `config/device_map.json`. This is the foundation the rest of v1.1.0 (aura profile, animation pack, prompt generator) builds on. ## Scope (minimal — additions wait for the milestone that needs them) Initial schema fields, per §10.4 of #273: - `schema_version` (string, semver) — explicit version tag so future schema evolutions can be detected and migrated. - `machine_name` (string) — human-readable identifier for the machine. - `openrgb` (object): `host` (string), `port` (integer). - `devices` (array of objects), each containing: - `id` (string, stable identifier) - `openrgb_name` (string, name as OpenRGB reports it) - `type` (enum: at minimum `fan`, `motherboard`, `gpu`, `unknown`) - `zones` (array of objects): - `zone_index` (integer, OpenRGB's index) - `led_count` (integer, total LEDs in the zone) - `usable_leds` (integer, LEDs RGB Aura should actually drive) ## Acceptance criteria 1. JSON Schema document checked in (path TBD in PR — likely `schemas/device_profile.schema.json` or similar). 2. Working example `device_profile.json` for Jack's machine, derived from the current `config/device_map.json`. Roundtrip-equivalent — the runtime should be able to produce the same hardware behavior from either. 3. The schema rejects malformed inputs with errors that follow the paste-back-friendly diagnostic shape from §4.2 of #273 (field path, expected, got, how to fix, example). The diagnose CLI itself is a separate issue — this one only requires that the validation errors carry the information needed to produce that output. 4. Tests cover at least: valid example accepted, missing required field rejected, wrong-type field rejected, out-of-range LED count rejected. ## Out of scope (deferred per #62 §8 cut list) - Setup wizard (`rgb-aura setup`) — v1.1.X or v1.2.0. - LED-by-LED mapping — v1.2.0. - Layout types beyond `linear` / `unknown` — v1.2.0. - LED groups — v1.2.0. - `aura_profile.json` and animation pack schemas — their own issues. - The `rgb-aura migrate-profile` CLI — its own issue (likely opened immediately after this one lands, since it's the path that turns `device_map.json` into the v1.1.X reality). - The `rgb-aura pack diagnose` CLI itself — its own issue. ## Branch and PR plan - Branch from `develop` as `feature/issue-<this-issue-number>-device-profile-schema`. - McJuniorstein opens the PR; Jack reviews and merges per AGENTS.md §4. - No hardware-touching changes in this PR — it's pure schema + example + validation tests. Jack's review can be done without running on his rig. ## Notes - Field naming and exact JSON Schema shape are up for discussion in the PR. This issue locks the *scope*; the PR locks the *form*. - The `schema_version` field starts at `"1.0.0"`. Rationale: SemVer reserves `0.x.y` for experimental APIs where anything can break; calling this schema experimental contradicts the "schema is the contract" framing from §4.1 of #273. Starting at `1.0.0` lets v1.1.X additions bump minor (additive, backward-compatible) and any breaking changes bump major — a distinction LLMs and validators can act on. Open to a different versioning scheme (e.g., integer-only) if you want to push back on this — say so before the PR opens.
JackFrostbyte commented 2026-05-23 01:58:59 -04:00
Owner
Copy link

Implemented by PR #96.

Issue #66 is complete.

The PR targeted develop and stayed within the schema/profile validation scope for v1.1.0.

What was added:

  • schemas/device_profile.schema.json
  • config/device_profile.example.json
  • src/rgb_aura/device_profile.py
  • tests/test_device_profile.py

The new device profile foundation supports:

  • controlled devices/zones
  • ambient devices/zones
  • ignored discovered-but-not-driven devices/zones
  • reserved devices/zones
  • unknown devices/zones
  • minimal linear / unknown zone layout classification
  • structured validation diagnostics suitable for later diagnose/paste-back workflows

Jack’s example profile preserves the current runtime behavior conceptually:

  • GPU remains controlled.
  • Motherboard main zone remains controlled.
  • Top Fractal fans remain controlled.
  • Thermaltake/front fans remain controlled.
  • Reserved ARGB zone is represented as reserved and disabled.
  • Corsair K70 RGB PRO keyboard is represented as ignored and disabled.
  • Logitech G502 Hero mouse is represented as ignored and disabled.
  • Memory/static RAM lighting is represented as ignored and disabled.

No runtime hardware behavior was changed. config/device_map.json remains the active runtime mapping until a future migration/runtime issue explicitly changes that.

Hardware verification was not required for this issue because the completed work does not change OpenRGB connection logic, RGB write paths, animation frame builders, runtime startup behavior, shutdown restore behavior, systemd ordering, or active device mapping behavior.

Verification performed:

python -m pytest
108 passed, 11 skipped

python -m ruff format --check src tests scripts
36 files already formatted

python -m ruff check src tests scripts
All checks passed!
Implemented by PR #96. Issue #66 is complete. The PR targeted `develop` and stayed within the schema/profile validation scope for v1.1.0. What was added: - `schemas/device_profile.schema.json` - `config/device_profile.example.json` - `src/rgb_aura/device_profile.py` - `tests/test_device_profile.py` The new device profile foundation supports: - controlled devices/zones - ambient devices/zones - ignored discovered-but-not-driven devices/zones - reserved devices/zones - unknown devices/zones - minimal `linear` / `unknown` zone layout classification - structured validation diagnostics suitable for later diagnose/paste-back workflows Jack’s example profile preserves the current runtime behavior conceptually: - GPU remains controlled. - Motherboard main zone remains controlled. - Top Fractal fans remain controlled. - Thermaltake/front fans remain controlled. - Reserved ARGB zone is represented as reserved and disabled. - Corsair K70 RGB PRO keyboard is represented as ignored and disabled. - Logitech G502 Hero mouse is represented as ignored and disabled. - Memory/static RAM lighting is represented as ignored and disabled. No runtime hardware behavior was changed. `config/device_map.json` remains the active runtime mapping until a future migration/runtime issue explicitly changes that. Hardware verification was not required for this issue because the completed work does not change OpenRGB connection logic, RGB write paths, animation frame builders, runtime startup behavior, shutdown restore behavior, systemd ordering, or active device mapping behavior. Verification performed: ```text python -m pytest 108 passed, 11 skipped python -m ruff format --check src tests scripts 36 files already formatted python -m ruff check src tests scripts All checks passed! ```
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
docs/issue-72-animation-pack-architecture
develop
v1.0.1
v1.0
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
JackFrostbyte/rgb-aura#66
No description provided.