docs: make the driver page a host reference, not a second authoring guide - #727
docs: make the driver page a host reference, not a second authoring guide#727frahlg wants to merge 1 commit into
Conversation
…uide FTW and srcfl/device-drivers both carried a "how to write a driver" guide, 220 and 268 lines. They overlap on the entry points, the DRIVER block, the sign convention and the build-and-test loop, and there is no mechanism that keeps them agreeing. The upstream copy is built around blueprint/BLUEPRINT.lua and is the one a driver author reaches for, so the FTW copy is the one that quietly goes stale — and #720 is currently moving the website's "Write a driver" link upstream, which makes that worse. Split by what each repository actually owns. Authoring moves upstream, and this page keeps what only FTW can answer: what its host registers, how a capability is granted, when the host calls driver_default_mode, where FTW resolves a driver file from, and how to test one against a running instance. The host API is now a table generated from what lua.go registers, including http_patch and its allow_write gate from #716. Every name in it was checked against host.RawSetString in lua.go; the two Blixt L1 aliases stay in the prose below the table rather than the table itself. Removed content is covered elsewhere: entry points, sign convention, manifest and make targets upstream, and the drivers-beta promotion paragraph was already a duplicate of device-repository.md, which this page links to. README is untouched — #720 is editing the same section and has right of way. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4e3d4a5f93
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| A YAML driver entry grants only what the file needs. The keys are `modbus`, | ||
| `mqtt`, `serial`, `http`, `websocket` and `tcp`: |
There was a problem hiding this comment.
For a driver that intentionally needs no external I/O capability, this exhaustive list hides the valid capabilities.standalone key. config.Config.Validate accepts that boolean specifically as the alternative to MQTT, Modbus, serial, HTTP, WebSocket, or TCP and otherwise rejects the driver, so an operator relying on this host reference cannot construct a valid standalone configuration. Include standalone and clarify that it is a boolean rather than a resource block.
Useful? React with 👍 / 👎.
| Some calls answer to two names. `srcfl/device-drivers` treats the Blixt L1 host | ||
| API as its naming reference and is converting its catalog to it, so `write`, | ||
| `write_registers` and `now_ms` resolve to `modbus_write`, `modbus_write_multi` | ||
| and `millis`. `host.emit` likewise reads `W` and `SoC_nom_fract` when `w` and | ||
| `soc` are absent; when both are present the lowercase key wins. Prefer the | ||
| canonical spelling in a new driver. The older names stay until the catalog has | ||
| finished moving. | ||
| API as its naming reference, so `write`, `write_registers` and `now_ms` resolve | ||
| to `modbus_write`, `modbus_write_multi` and `millis`. `host.emit` likewise | ||
| reads `W` and `SoC_nom_fract` when `w` and `soc` are absent; when both are | ||
| present the lowercase key wins. Both spellings are correct — prefer the | ||
| canonical one in a new driver. |
There was a problem hiding this comment.
When authors follow the Blixt naming reference, write and write_registers are the canonical names, while modbus_write and modbus_write_multi are the older FTW spellings retained for compatibility; TestCanonicalHostFunctionAliasesExist and the registration comments explicitly document that direction. The new table omits the canonical write names, and this prose says to prefer the canonical spelling without identifying which side of the mapping that is, encouraging new drivers to use names intended for eventual retirement. List the Blixt names in the table or explicitly label them as canonical.
AGENTS.md reference: AGENTS.md:L41-L44
Useful? React with 👍 / 👎.
1 participant
FTW and
srcfl/device-driversboth carry a "how to write a driver" guide — 220 lines here, 268 upstream. They overlap on the entry points, theDRIVERblock, the sign convention and the build-and-test loop, and nothing keeps them agreeing.The upstream copy is built around
blueprint/BLUEPRINT.luaand says outright that the blueprint is the specification, so it is the one a driver author reaches for. That makes the FTW copy the one that quietly goes stale — and #720 is moving the website's "Write a driver" link upstream right now, which removes the last reason anyone would open this one first.The split
Divide by what each repository can actually answer.
Upstream owns authoring, and this page now links there in its first section: entry points, sign convention, what never to fabricate, the manifest/
DRIVERversion agreement,make test-driver,make check.This page keeps what only FTW knows:
driver_default_mode— stale telemetry, reloads, removal, shutdown — which is a safety invariant of core, not a driver-authoring detail;set_make/set_snmatter (durable state is keyed by hardware identity, not the YAML name);220 → 159 lines.
Verification
host.RawSetStringingo/internal/drivers/lua.go: 45 documented, 0 that do not exist. The only registered names not in the table arewriteandwrite_registers, the Blixt L1 aliases, which are covered in the prose below it rather than listed as canonical.http_patchand itscapabilities.http.allow_writegate are included, from feat(drivers): host.http_patch write verb for device REST writes (#537) #716 earlier today.drivers-betapromotion paragraph was already a duplicate ofdocs/device-repository.md, which this page links to.Scope
README.mdis deliberately untouched. #720 is editing the same Drivers section and has right of way; its "Start with docs/writing-a-driver.md" sentence still reads correctly, since this remains the right first page for the host side. Any README rewording belongs in a follow-up after #720 lands.Documentation only, so the changeset gate exempts it.