Add device interface specification by bruno-f-cruz · Pull Request #215 · harp-tech/protocol

bruno-f-cruz · 2026-04-25T18:05:07Z

This is a first stab at describing the device interface, device.yml specification.
It provides a high-level description on how the document is organized, validated and used by downstream tooling. I also provides a few examples.

I think we could add more detail in the following points:

converter
~~interfaceType~~
~~The way that @glopesdev ended up resolving the heterogeneous registers Heterogenous register types in yaml schema #40~~

bruno-f-cruz · 2026-04-26T17:18:44Z

We should also address #214
One idea is that scalar registers should NEVER specify length. If length is specied (even if 0) the register interface must always return a array type

Documention on heterogenous registers here(harp-tech/generators#87)

banchan86

Looks pretty good to me! I thought it was well written and clear with the accompanying examples. Just minor suggestions for clarity and one stumbling block regarding the bitmasks.

banchan86 · 2026-06-28T08:09:11Z

+
+## Document Structure Overview
+
+A device interface file is a YAML document whose schema is defined by `./schema/device.json`. The root level of the document contains metadata fields describing the device and a `registers` map that declares all application registers. Optional `bitMasks` and `groupMasks` sections define named masks that can be referenced by registers.


So the first line duplicates/contradicts the "Schema Reference" at the end of the file, which states that it's defined by a set of 3 files (device.json, core.json, registers.json). I think it might help to bring the "Schema Reference" section with the table up here and delete this line, as I also find that section is a little out of place at the end of the article.

I also realize the term device.yml is never used anywhere, while core.yml is mentioned. I feel like it can be brought in here.

Suggested change

A device interface file is a YAML document whose schema is defined by `./schema/device.json`. The root level of the document contains metadata fields describing the device and a `registers` map that declares all application registers. Optional `bitMasks` and `groupMasks` sections define named masks that can be referenced by registers.

The root level of the device interface file (`device.yml`) contains metadata fields describing the device and a `registers` map that declares all application registers. Optional `bitMasks` and `groupMasks` sections define named masks that can be referenced by registers.

banchan86 · 2026-06-28T08:29:20Z

+A YAML language-server schema directive SHOULD be placed at the top of the file to enable editor validation and autocompletion:
+
+```yaml
+# yaml-language-server: $schema=https://harp-tech.org/draft-02/schema/device.json


Suggested change

# yaml-language-server: $schema=https://harp-tech.org/draft-02/schema/device.json

%YAML 1.1

---

# yaml-language-server: $schema=https://harp-tech.org/draft-03/schema/device.json

Add yaml version directive and update the schema directive link which is now on draft-03

banchan86 · 2026-06-28T08:30:48Z

+
+The file MUST declare all four metadata fields (`device`, `whoAmI`, `firmwareVersion`, `hardwareTargets`) and the `registers` map. The `bitMasks` and `groupMasks` sections are OPTIONAL and SHOULD be included when registers reference named masks.
+
+A YAML language-server schema directive SHOULD be placed at the top of the file to enable editor validation and autocompletion:


Suggested change

A YAML language-server schema directive SHOULD be placed at the top of the file to enable editor validation and autocompletion:

A YAML version and language-server schema directive SHOULD be placed at the top of the file to enable editor validation and autocompletion:

Include the YAML version directive here?

banchan86 · 2026-06-28T10:15:12Z

+
+## Core Registers
+
+Every Harp device also exposes a set of core registers (addresses 0–31) that are common to all devices. These registers are defined in a separate file (`core.yml`) and follow the same YAML schema described in this document. Core registers handle device identification, timestamping, operation mode control, and other shared functionality. See [Device Registers and Operation](Device.md#core-registers) for the full specification of core register behavior.


Suggested change

Every Harp device also exposes a set of core registers (addresses 0–31) that are common to all devices. These registers are defined in a separate file (`core.yml`) and follow the same YAML schema described in this document. Core registers handle device identification, timestamping, operation mode control, and other shared functionality. See [Device Registers and Operation](Device.md#core-registers) for the full specification of core register behavior.

Every Harp device also exposes a set of core registers (addresses 0–31) defined in a separate [`core.yml`](./schema/core.yml) file that follows the same YAML schema described in this document. Core registers handle device identification, timestamping, operation mode control, and other shared functionality. As these registers are common to all devices, `core.yml` does not need to be included alongside `device.yml`. See [Device Registers and Operation](Device.md#core-registers) for the full specification of core register behavior.

I feel like one thing that is not obvious to people is whether or not they should include core.yml in the device repository, so I suggested edits here, and added link to schema/core.yml.

banchan86 · 2026-06-28T10:18:08Z

+
+A register that specifies only `Event` as its access mode is implicitly read-only from the Controller's perspective — the Controller cannot write to it, and the device pushes data when events occur.
+
+When multiple access modes are needed, they SHOULD be expressed as a YAML sequence (1–3 unique values):


Suggested change

When multiple access modes are needed, they SHOULD be expressed as a YAML sequence (1–3 unique values):

When multiple access modes are needed, they MUST be expressed as a YAML sequence (1–3 unique values):

Is there another way of expressing multiple access modes? If not, should it be a MUST?

banchan86 · 2026-06-28T11:01:42Z

+| `ushort`       | 16-bit unsigned integer.                           |
+| `float`        | Floating-point value.                              |
+| `string`       | Text, typically over a span of byte elements. When using interfaceType, the `length` parameter MUST be defined     |
+| `HarpVersion`  | Custom type composed from multiple elements that describes a SemVer-like version. When using this `interfaceType`, the `length` MUST be equal to 3       |


Suggested change

| `HarpVersion` | Custom type composed from multiple elements that describes a SemVer-like version. When using this `interfaceType`, the `length` MUST be equal to 3 |

| `HarpVersion` | Custom type composed from multiple elements that describes a [semantic version](https://semver.org/). When using this `interfaceType`, the `length` MUST be equal to 3 |

Changed text and added link, similar to what was done in Device.MD

banchan86 · 2026-06-28T11:33:11Z

+A member is located within the payload using two **independent** coordinates, either or both of which MAY be present:
+
+- `offset` (with optional `length`) selects *which element(s)* of the payload array the member occupies.
+- `mask` selects *which bits* within a payload word the member occupies.


So one thing that really tripped me up is I am not sure when one should define the bitmask in the payloadSpec and when one should define it in the "bitMask" section of the device.yml. Are these reasons correct?

Define bitmask in payloadSpec:

When combining offset and bitmask to locate a member?

When separating heterogenous type members with different-sized bitfields?

Define bitmask in bitMasks section:

When defining the same type members, with equal-size bitfields?

I also think I may have the wrong mental model and might be completely off about the distinction between the two 😆 A note about the differences between the two might help other confused readers like me.

banchan86 · 2026-06-28T11:38:29Z

+| `int`          | Signed integer.                                    |
+| `uint`         | Unsigned integer.                                  |


banchan86 · 2026-06-28T11:46:13Z

+### Private registers
+
+Registers that are not meant to be exposed in high-level interfaces (e.g. code-generated classes) can be marked with `visibility: private`. This is commonly used for reserved registers that fill gaps in the address space to maintain contiguity.
+
+```yaml
+Reserved0: &reserved
+  address: 33
+  type: U8
+  access: Read
+  description: Reserved for future use
+  visibility: private
+Reserved1:
+  <<: *reserved
+  address: 84
+```


Hmm, I feel like this section might be better placed in the walkthrough of the properties in the "Registers" section. The example will have to be changed to get rid of the yaml anchors and aliases.

banchan86 · 2026-06-28T11:54:12Z

+## Schema Reference
+
+The device interface YAML format is formally defined by a set of JSON Schema files:
+
+| Schema           | Description                                                                                                 |
+| :--------------- | :---------------------------------------------------------------------------------------------------------- |
+| `device.json`    | Top-level schema for device interface files. Requires device metadata and references `core.json`.           |
+| `core.json`      | Schema for core device properties. Requires `protocolVersion` and references `registers.json`.              |
+| `registers.json` | Defines the structure of registers, bit masks, group masks, payload members, and all associated properties. |
+
+Editors supporting the [YAML Language Server](https://github.com/redhat-developer/yaml-language-server) can validate device interface files by adding the schema directive shown in the [Document Structure Overview](#document-structure-overview).


As mentioned there is some overlap with this and the document overview section so might be better to move this up there.

bruno-f-cruz requested review from a team, banchan86 and glopesdev April 25, 2026 18:05

bruno-f-cruz added 4 commits June 21, 2026 05:11

Add draft for device interface

b971227

Fix note syntax

3144da2

Add additional edge cases from generators package

2b9d265

Minor clarification of interfaceType and formatting.

ce8a1f6

bruno-f-cruz force-pushed the feat-add-device-interface-spec branch from 3e6f4a9 to ce8a1f6 Compare June 21, 2026 12:12

banchan86 reviewed Jun 28, 2026

View reviewed changes

MicBoucinha mentioned this pull request Jul 1, 2026

Refactor package for unified data and device API harp-tech/pyharp#5

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add device interface specification#215

Add device interface specification#215
bruno-f-cruz wants to merge 4 commits into
mainfrom
feat-add-device-interface-spec

bruno-f-cruz commented Apr 25, 2026 •

edited

Loading

Uh oh!

bruno-f-cruz commented Apr 26, 2026 •

edited

Loading

Uh oh!

banchan86 left a comment

Uh oh!

banchan86 Jun 28, 2026

Uh oh!

banchan86 Jun 28, 2026

Uh oh!

banchan86 Jun 28, 2026

Uh oh!

banchan86 Jun 28, 2026

Uh oh!

banchan86 Jun 28, 2026

Uh oh!

banchan86 Jun 28, 2026

Uh oh!

banchan86 Jun 28, 2026

Uh oh!

banchan86 Jun 28, 2026

Uh oh!

banchan86 Jun 28, 2026

Uh oh!

banchan86 Jun 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		## Document Structure Overview

		A device interface file is a YAML document whose schema is defined by `./schema/device.json`. The root level of the document contains metadata fields describing the device and a `registers` map that declares all application registers. Optional `bitMasks` and `groupMasks` sections define named masks that can be referenced by registers.

	A device interface file is a YAML document whose schema is defined by `./schema/device.json`. The root level of the document contains metadata fields describing the device and a `registers` map that declares all application registers. Optional `bitMasks` and `groupMasks` sections define named masks that can be referenced by registers.
	The root level of the device interface file (`device.yml`) contains metadata fields describing the device and a `registers` map that declares all application registers. Optional `bitMasks` and `groupMasks` sections define named masks that can be referenced by registers.

-# yaml-language-server: $schema=https://harp-tech.org/draft-02/schema/device.json
+%YAML 1.1
+---
+# yaml-language-server: $schema=https://harp-tech.org/draft-03/schema/device.json


		The file MUST declare all four metadata fields (`device`, `whoAmI`, `firmwareVersion`, `hardwareTargets`) and the `registers` map. The `bitMasks` and `groupMasks` sections are OPTIONAL and SHOULD be included when registers reference named masks.

		A YAML language-server schema directive SHOULD be placed at the top of the file to enable editor validation and autocompletion:

	A YAML language-server schema directive SHOULD be placed at the top of the file to enable editor validation and autocompletion:
	A YAML version and language-server schema directive SHOULD be placed at the top of the file to enable editor validation and autocompletion:


		## Core Registers

		Every Harp device also exposes a set of core registers (addresses 0–31) that are common to all devices. These registers are defined in a separate file (`core.yml`) and follow the same YAML schema described in this document. Core registers handle device identification, timestamping, operation mode control, and other shared functionality. See [Device Registers and Operation](Device.md#core-registers) for the full specification of core register behavior.


		A register that specifies only `Event` as its access mode is implicitly read-only from the Controller's perspective — the Controller cannot write to it, and the device pushes data when events occur.

		When multiple access modes are needed, they SHOULD be expressed as a YAML sequence (1–3 unique values):

	\| `HarpVersion` \| Custom type composed from multiple elements that describes a SemVer-like version. When using this `interfaceType`, the `length` MUST be equal to 3 \|
	\| `HarpVersion` \| Custom type composed from multiple elements that describes a [semantic version](https://semver.org/). When using this `interfaceType`, the `length` MUST be equal to 3 \|

Uh oh!

Conversation

bruno-f-cruz commented Apr 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bruno-f-cruz commented Apr 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

banchan86 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bruno-f-cruz commented Apr 25, 2026 •

edited

Loading

bruno-f-cruz commented Apr 26, 2026 •

edited

Loading