Skip to content

V3 usage interactions inline & more structure - #30

Merged
addshore merged 24 commits into
mainfrom
refine-v3-yaml-authoring
Nov 12, 2026
Merged

addshore merged 24 commits into
mainfrom
refine-v3-yaml-authoring

Conversation

@addshore

@addshore addshore commented Oct 28, 2026 •

Copy link
Copy Markdown
Member

The intention here is to allow us to have more structure, rather than needing to just use descriptions etc to explain things, and also then feed into better auto generated documentation.
We are starting wtih this format in the docs repo, this is the 2nd iteration, and now we need to sync it back out into other places.

@github-actions

github-actions Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Documentation preview

Open preview

Last published commit: dbe5b15

Publish workflow

This URL updates after each successful publication. A newer commit may still be building or awaiting approval. The preview is removed when this PR closes.

Comment thread public/files/protocol-v3.yaml Outdated
"5":
1: {}
5:
presence: required

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks like a missed edit?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I left required in for now

Comment thread public/files/protocol-v3.yaml Outdated
presence: optional
description: Include a nonzero Message ID to correlate the reply.
"5":
1: {}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what is the purpose of having the empty {}? what will it hold?

I had said I thought it should be headers: [1] (implied required) , optionalHeaders:[]

@addshore addshore Oct 29, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[1,2,3] doesnt work as we want more fields

  "22":
                  presence: required
                  value: 2

Comment thread public/files/protocol-v3.yaml Outdated
"6": {presence: optional}
"7": {presence: optional}
"10": {presence: optional}
1: {}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why?

Comment thread public/files/protocol-v3.yaml Outdated
request:
title: SET request
description: Use writable control fields, not the read-only GPS status field.
description: >-

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i'm really confused why this is better than the per field descriptions we had beore

@chris-lightbug

Copy link
Copy Markdown
Contributor

@addshore I'm stopping reviewing because it seems theres loads of unintentional changes? or I'm missing the point.. 100% this is worse that what we currently have IMO with no clear benefit? or maybe you're looking at something in particular?

Comment thread public/files/protocol-v3.yaml Outdated
"22":
22:
presence: required
maxBytes: 1

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maxBytes: 1 shouldnt be here

@chris-lightbug

Copy link
Copy Markdown
Contributor

As discussed: I'm awaiting a "reason for doing all this" - specifically why these changes are necessary and why this particular design has been chosen.

In my view, we should be handling this with easier to read & maintain yaml, that matches how the code is written, rather than trying to cover every possibility.

Personally I would see this as a combination of conventions and additional fields.

Like we could have

methods:

  • GET.1:
    headersRequired: [1,2,3]
    fieldsRequired: [2,129]
    descriptionOverrides:
    2: With GET v1, field 2 doens't mean X, but Y.
    example: ...

I'm not advocating for this format as is: just providing an example for what would make a lot more sense to me: IMO we need to collect the requirements to make a more informed / better planned decision

@addshore addshore changed the title Refine structured v3 YAML authoring and hex examples Add versioned interactions without reshaping V3 messages Nov 4, 2026
@addshore addshore changed the title Add versioned interactions without reshaping V3 messages Define V3 usage interactions inline with each message Nov 4, 2026
@addshore
addshore marked this pull request as ready for review November 11, 2026 10:27
@addshore
addshore force-pushed the refine-v3-yaml-authoring branch from 970927a to 5745361 Compare November 11, 2026 10:40
@addshore addshore changed the title Define V3 usage interactions inline with each message V3 usage interactions inline & more structure Nov 12, 2026
Comment thread public/files/protocol-v3.yaml Resolved
1:
presence: required
2:
presence: omitted

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

now I understand presence.. still wondering what "optional" means

Comment thread public/files/protocol-v3.yaml Resolved
Comment thread public/files/protocol-v3.yaml Resolved
@chris-lightbug

Copy link
Copy Markdown
Contributor

@addshore added a few comments, wouldn't mind understanding a bit more of the design decisions

@addshore
addshore merged commit 9a047d9 into main Nov 12, 2026
6 checks passed
@addshore
addshore deleted the refine-v3-yaml-authoring branch November 12, 2026 10:35
Comment thread public/files/protocol-v3.yaml Outdated
id: gsmControl
description: >-
GET returns GSM state directly. Successful SET operations return an ACK only when the request
includes a nonzero Message ID.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

only when the request
      includes a nonzero Message ID.

This is part of https://docs-next.lightbug.io/devices/api/protocol/responses not something that should be documented or written about in here

Comment thread public/files/protocol-v3.yaml Outdated
name: GSM Control
id: gsmControl
description: >-
GET returns GSM state directly. Successful SET operations return an ACK only when the request

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"GET returns GSM state directly. Successful SET operations"
This should be in the usage pattern descriptions if it even makes sense.
The description at this level should be about what GSM control means and does at a high level.

@@ -1257,6 +1260,73 @@ messages:
methods:

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the future, i expect we can deduce all possible methods based on the interactions that are defined.
Or maybe now

Comment thread public/files/protocol-v3.yaml Outdated
3: {presence: ignored}
4: {presence: ignored}
5: {presence: omitted}
response: &gsmControlAck

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I apprecaite this reuse

Comment thread public/files/protocol-v3.yaml Outdated
method: GET
title: Read GSM state
versions:
1:

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have to specify version 1,
When there is only 1 version?

Comment thread public/files/protocol-v3.yaml Outdated
"0": Version 1 (also the omitted/malformed-width fallback)
"1": Version 1
'0': Version 1 (also the omitted/malformed-width fallback)
'1': Version 1

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why '1': Version 1
Why not 1: Version 1

Comment thread public/files/protocol-v3.yaml Outdated
description: >-
A successful GET returns this MT58 payload. An unsuccessful request returns
MT5 (ACK) with Status instead.
description: A successful GET returns this MT58 payload. An unsuccessful request returns MT5 (ACK)

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if in the docs actually view, we could auto turn things like MT58 literal in text into a clickable component thing

Comment thread public/files/protocol-v3.yaml Resolved
Comment thread public/files/protocol-v3.yaml Resolved
Comment thread public/files/protocol-v3.yaml Resolved
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants