Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions .github/ISSUE_TEMPLATE/driver_request.yml
Original file line number Diff line number Diff line change
@@ -1,8 +1,13 @@
name: Driver request
description: Request support for a device or propose a driver contribution
description: Request device support or share hardware evidence
title: "[driver] "
labels: ["driver"]
body:
- type: markdown
attributes:
value: |
Sourceful develops the drivers. External users submit issues with needs
and evidence; we do not accept external pull requests, including docs.
- type: input
id: device
attributes:
Expand Down Expand Up @@ -30,4 +35,4 @@ body:
attributes:
label: Contribution
options:
- label: I can help write or test this driver.
- label: I can provide device documentation or help test on hardware.
3 changes: 3 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
<!-- Sourceful maintains implementation PRs. External users submit issues,
including driver and documentation requests; see CONTRIBUTING.md. -->
Comment on lines +1 to +2

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Add an issue path for documentation requests

When an external user follows this instruction for a documentation correction, GitHub offers no appropriate submission path: .github/ISSUE_TEMPLATE/config.yml disables blank issues, while the only available forms are driver requests and driver bugs requiring device/protocol or reproduction details. The new policy therefore rejects documentation PRs while preventing the requested issue-based alternative; add a documentation/general issue form or enable blank issues.

AGENTS.md reference: AGENTS.md:L10-L14

Useful? React with 👍 / 👎.


## Summary

<!-- State what hardware support or contract changes. -->
Expand Down
16 changes: 16 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,22 @@ drivers and the main driver source for FTW. It publishes FTW's signed driver
channel from reviewed commits. Device Support may later consume a locked commit
for other products or support levels, but it does not own a second source tree.

## FTW product direction

Read [FTW's vision](https://github.com/srcfl/ftw/blob/master/VISION.md) for the household
experience these drivers support. Sourceful maintains this shared repository.
External users submit issues with needs and evidence, not implementation PRs.
See [CONTRIBUTING.md](CONTRIBUTING.md). Local Lua customization remains useful
and does not grant signed-channel activation or release rights.

Support mixed makes and generations with explicit model/firmware evidence.
Report identity, reliable measurements, known limits and structured command
results so Core can distinguish read support from control support. A catalog
entry or a simulated response does not establish working physical control.
Heat telemetry helps planning first; active tank or hot-water control requires
its separate safety and hardware evidence. Keep the existing host contracts
and control acceptance gates below.

## Boundaries

- Keep API, admin, database and deployment code out of this repo.
Expand Down
15 changes: 12 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,16 @@
# Contributing device drivers

Thank you for helping add hardware support. Keep each pull request focused on
one driver or one contract change.
Sourceful maintains this repository. External users contribute through
[issues](https://github.com/srcfl/device-drivers/issues): device needs, bugs,
protocol sources and hardware evidence. We do not accept external pull
requests, including documentation. Acceptance of an issue does not invite an
external implementation PR.
Comment on lines +3 to +7

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Remove the remaining instruction to open community PRs

drivers/INTEGRATION_OVERVIEW.md still tells readers in its “Adding a New Device” flow to open a PR (lines 198–204) and advertises community contributions as “PR a .lua file” (line 218). That directly contradicts this newly introduced external-issue-only policy and sends contributors toward submissions maintainers say they will reject; update that guide as part of the policy migration.

AGENTS.md reference: AGENTS.md:L10-L14

Useful? React with 👍 / 👎.


Users may adapt Lua drivers locally under the existing license. Local changes
do not grant release, signing or activation authority. The development steps
below apply to Sourceful-maintained PRs and local adaptation. Keep Sourceful
PRs focused on one driver or one contract change. FTW direction lives in
[the shared vision](https://github.com/srcfl/ftw/blob/master/VISION.md).

## Legal sign-off

Expand Down Expand Up @@ -146,7 +155,7 @@ State:
Do not post credentials, full configuration, serial numbers, private addresses
or energy history from a real site.

New contributions use the `community` tier. That tier states the current test
New drivers use the `community` evidence tier. That tier states the current test
and support evidence; it does not mean the public repo is unofficial or
unmaintained. A maintainer may promote a driver only after the stated review
and hardware checks. Control support always uses a separate change and cannot
Expand Down
17 changes: 12 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,14 @@ Being listed is not an install claim. The page states the same evidence the
repository does, including how few drivers have been confirmed against physical
hardware.

## Contribute a driver
## Report a need or adapt a driver

Sourceful maintains implementation and release PRs. External users submit
[issues](https://github.com/srcfl/device-drivers/issues) with hardware needs,
bugs and test evidence; we do not accept external PRs, including docs.
[FTW's product vision](https://github.com/srcfl/ftw/blob/master/VISION.md)
sets the FTW goals. The existing license still permits local adaptation.
The instructions below serve local work and Sourceful development.

Start from **[`blueprint/BLUEPRINT.lua`](blueprint/BLUEPRINT.lua)**. It is a
complete, working driver for an imaginary inverter, written so that every rule
Expand All @@ -43,11 +50,11 @@ behind each rule — why a failed read can take a whole site offline, why a
fabricated zero is worse than a missing field, and why arithmetic never belongs
in the host API.

Then open a pull request using the template. Include the tested device models,
the protocol source, sign checks against vendor data and a test fixture when
one can be shared without credentials or site data.
For an issue, include the device model, protocol source and any observations
you can safely share. Sourceful implementation PRs use the template and include
sign checks and test evidence without credentials or private site data.

New community drivers start with telemetry only. Control support needs a later,
New drivers start with telemetry only. Control support needs a later,
separate review with a safe default mode, a bounded command lease, structured
results and supervised hardware-in-the-loop evidence.

Expand Down
7 changes: 6 additions & 1 deletion docs/WRITING-A-DRIVER.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# Writing a driver

This guide serves local Lua adaptation and Sourceful development. External
users submit [issues](https://github.com/srcfl/device-drivers/issues) with
needs and evidence; the project does not accept external pull requests.
See [CONTRIBUTING.md](../CONTRIBUTING.md).

Start here: **[`blueprint/BLUEPRINT.lua`](../blueprint/BLUEPRINT.lua)**.

It is a complete, working driver for an imaginary inverter. Every rule in this
Expand Down Expand Up @@ -95,7 +100,7 @@ Wrap the driver's own typed helpers — `read_i16`, `read_u32_be` and the like
around `probe_read` rather than giving each its own `pcall`. That fixes every
call site at once and leaves one place to reason about.

### Check your driver before you open the pull request
### Check local changes and Sourceful pull requests

```bash
make absent-register-report ID=example
Expand Down