Skip to content

Align config schema between firmware and host provisioning example #11

Description

@TalkingJupiter

Context

The firmware config parser (parseRuntimeConfigJson in ESP32-Firmware/src/RuntimeConfig.cpp) and the host provisioning example (host/example.md) disagree on the config schema. Running the example service against the real firmware would get every config rejected — three separate fields fail validation independently.

Field Host example sends Firmware expects Result
enabled not sent at all required true by isValid() rejected
unit_id "unit01" rack_id empty rack ID → rejected
role "controllerA" / "controllerB" "Primary" / "Standby" Unknown role → rejected
MAC format AA-BB-CC-DD-EE-FF (dashes) A1B2C3D4E5F6 (compact) in topics/payload registry lookup misses → unknown_mac path

The example also sends config_version and timing{} which the firmware currently ignores.

Scope

Pick one canonical config schema and make both sides match it. The firmware side works today, so the smaller change is probably updating the host example — but the naming decisions (rack_id vs unit_id, role names, MAC format) should be made deliberately since they end up in the database schema too (device_map.mac, rack_id).

Implementation notes

  • Decide MAC format once: compact (A1B2C3D4E5F6) is what the firmware embeds in topics and hello payloads today.
  • Decide role vocabulary: firmware parseRole() accepts Primary/Standby.
  • Decide whether enabled is required in every config or defaults to true when omitted (relates to Fix RuntimeConfig validation for required topics #6).
  • Decide whether config_version and timing{} are part of v1 or dropped from the example.
  • Update host/example.md (note: currently untracked — root .gitignore line 7 ignores example.md, likely by accident).

Acceptance criteria

  • A config produced by the provisioning example is accepted by the firmware parser unchanged.
  • The schema is documented in one place both sides reference.
  • MAC format is consistent across hello payload, topics, and the host registry keys.

Relates to #6 and #7.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions