Sourceful Device Drivers
This public repository is FTW's driver repository: the source of truth for its
device driver code, catalog metadata and tests. FTW installs signed,
content-addressed release assets from this repository. It never runs raw code
from main.
Browse the catalog
Every driver, and what stands behind it →
The catalog page is generated from this repository and republished on every push
to main, so it cannot fall behind the source. The manifests supply versions,
tiers, protocols and tested models; each Lua source supplies its own description
and verification record. Search by manufacturer or model number, filter by device
type or protocol, or take the whole catalog as
drivers.json.
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.
Report a need or adapt a driver
Sourceful maintains the drivers and releases. External PRs are welcome,
preferably based on issues
with hardware needs, bugs and test evidence. Share a short Markdown proposal
or a focused fix; hardware claims need hardware results.
FTW's product vision
sets the FTW goals. The existing license still permits local adaptation.
The instructions below serve contributions and local adaptation.
Start from blueprint/BLUEPRINT.lua. It is a
complete, working driver for an imaginary inverter, written so that every rule
this repository enforces appears beside the code that follows it. It is
verified like a shipped driver: it compiles, passes the sandbox, and is run
against the harness by tests/test_blueprint.py.
cp blueprint/BLUEPRINT.lua drivers/lua/example.lua
make test-driver ID=example
make check
docs/WRITING-A-DRIVER.md explains the reasoning
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.
For an issue, include the device model, protocol source and any observations
you can safely share. Implementation PRs use the template and include
sign checks and test evidence without credentials or private site data.
A driver that can command its device ships with control on, marked
experimental until an owner reports it working on real hardware. Control needs
a safe default mode, bounded writes and structured results. A driver that
cannot command its device says so, and why, in its description.
Read CONTRIBUTING.md before opening a pull request.
Scope
The drivers here target linux-edge hosts: FTW (gopher-lua) and Blixt L1
(luajit). Both run on Linux-class hardware, so a driver is not written to a
memory budget.
37 of them came from FTW, where they have run on customer sites for months.
They were promoted byte-identical to baselines/ftw/drivers/ so their
provenance stays checkable, and FTW continues to test them in Go. A driver
that has since been fixed here no longer matches its baseline, which is the
point — the baseline is a record of what was imported, not a mirror of what
ships. make ftw-baseline-report lists the current state.
One driver per device, not one dialect per repository. FTW and Blixt spell
some host functions differently, and both spellings are correct — each is the
real API of a shipping host, and a host that wants the other's drivers adds
aliases in a few lines. What matters is that a driver never calls a name no
host provides, which tools/host_api_check.py enforces. Converting drivers to
a single spelling was tried and abandoned: it changed 196 lines across 36
field-proven drivers without changing what any of them does.
What a driver may call is defined in spec/host-api-profile.json
and enforced by make check. A function outside the profile is not available,
whichever host it was tested against.
Drivers here are community-supported. The tier in each manifest states the test
and support evidence behind that driver; a channel signature proves artifact
integrity, never hardware coverage.
Repository boundary
This repository contains only public source and validation code:
drivers/lua — Lua driver source;
manifests — public catalog metadata and tested models;
spec — driver, host API, manifest and signing contracts;
drivers/tests and tests — driver and tooling tests;
ftw-channel.json — the rules for FTW's signed, read-only channel;
tools — local validation and FTW release builds.
Private keys, credentials, cloud roles and service code stay outside this
repository. A pull request can produce unsigned test output only. GitHub
Actions signs the FTW channel after review and merge. The signature proves the
source commit and artifact bytes; it does not claim hardware test coverage.
Release flow
public PR -> public CI -> reviewed commit on main -> signed drivers-beta
-> FTW pins the commit and ships it in an FTW beta
-> FTW stable -> drivers-stable promoted
Drivers reach FTW users with the FTW release: FTW bundles the commit pinned in
its drivers/BUNDLED_SOURCE.json, and ftw update and ftw rollback move
those drivers with FTW. Every commit on main is published to the signed
drivers-beta channel, where an owner can pick one driver's newer version
from FTW's Versions list. After a stable FTW release, drivers-stable is
promoted with gh workflow run ftw-drivers-release.yml --ref main -f channel=stable; it accepts only the exact commit drivers-beta carries, and
serves installs that read the stable channel.
The channel contains every catalog driver as its own signed Lua asset. A
driver that can command its device ships with control: its driver_command
writes to the device. A driver that cannot declares read_only = true in its
DRIVER table and says why in its description, and ships read-only. A
driver_command that only logs and refuses does not count as control. The
manifest's control: field states the same, and make check fails when it
disagrees with the code or when a stub ships as control. The catalog page
shows each driver's answer. Refreshing the signed catalog never installs or
activates code. FTW keeps its own safety, activation, rollback and bundled
copies.
Each asset name contains the driver ID, semantic version and source hash. FTW
downloads only the selected driver. The release workflow never replaces a
content-addressed driver asset, so GitHub keeps its download count across later
manifest updates. To view counts by driver, version and channel, run:
uv run python tools/ftw_download_stats.py
GitHub counts asset downloads, not unique users or active installs.
The catalog is not an install claim. See SUPPORT_STATUS.md
for target conformance, signed beta, HIL and legacy parity per driver and
target.
License
This version uses AGPL-3.0-only with the Energyplan combination permission
in LICENSE. See LICENSING.md and NOTICE. Vendored Lua 5.5 source
keeps its own MIT notice; see THIRD_PARTY_NOTICES.md.