Build device plugins. Do not import the gateway.
Offline tools to author OTDP device plugins and to check their conformance. Scaffold an independent project. Hand your AI the generated guide and the evidence files. Then check descriptors, presentation resources and presets against the same contract bytes the gateway uses.
Install
Stable releases are on PyPI. The generated plugin runtime has no dependency on the SDK. Only its test extra pins the SDK version.
benchweave-sdk new plugins/acme/model100 --package benchweave_acme_model100
Five steps
Generate, implement, test, review, then prepare a release. The SDK covers the offline parts. Hardware qualification and publication approval stay with you.
- 1Install the SDK
From PyPI, as an isolated CLI tool, or from Homebrew.
- 2Scaffold the project
benchweave-sdk new plugins/<manufacturer>/<device> --package <import_name>. The project containssrc/,tests/and a generatedAI-GUIDE.mdthat describes the design, build, test, review and release steps. - 3Replace the synthetic protocol
Swap the explicitly synthetic
protocol.mdandvectors.jsonfor verified device behaviour. Then update the descriptor. - 4Run the checks
Install the plugin with its test dependencies. Run
pytest. Then runbenchweave-sdk checkagainst the descriptor. Record the applicable S01–S18, C01–C12 and M01–M14 obligations and evidence. The basic checks do not cover all of them. - 5Build and prepare the release
Run
uv build. Prepare the registry metadata and the reviewed evidence. Then approve the release before publication or hardware qualification.benchweave-sdk inventorygenerates hashes, not a complete registry manifest.
Public surfaces
Six modules. You do not need an SDK superclass. The interfaces are structural.
interfaces
asyncStructural Adapter, HostServices, OperationContext and optional CaptureServices and DatasetServices capability definitions.
testing
doublesDeterministic MockContext and MockHost: scripted transfers, dispatch markers, cancellation and a manually advanced clock. Not qualified host services.
validation
offlinePinned local schemas, strict finite JSON, format validation, runtime correlation and basic descriptor checks for S01, S02 and S04. Unresolved references fail without network retrieval.
conformance
reusableOperation and quiet-lifecycle checks with configurable wall-clock timeouts. Authors add device-specific failure, profile and measurement tests.
presentation
same bytesBounded offline validation of presentation resources and complete configuration presets, with the same validator bytes as the gateway.
packaging
integrityInventory and integrity checks for a prepared bundle, including duplicate, path and symlink rejection. It does not install, sign or publish anything.
Compatibility and limits
The gateway bridge implements identify, scalar read, scalar write, single-channel capture, streaming subscriptions and pinned-contract invoke. It does not implement the self_test, get_errors and reset verbs, or profile scheduling. The SDK supplies no live install endpoint, physical backend, container device permissions or hardware qualification. SDK and gateway versions have independent names. Each release records the exact tested pair.
Questions and discussion
Are you stuck on a descriptor? Do you want to show your work? The BenchWeave Discord is open, and the invite is permanent.
Documentation
Versioned docs built with Great Docs. The root tracks the latest release. Every page carries a version selector that switches between released versions and the current main build.
Plugin SDK guide
Install, generate, give the AI the facts and prompts, run the checks, review compatibility, prepare the release.
Docs home
Package overview and the full navigation tree.
CLI reference
new, doctor, check, check-ui, check-preset, preview-ui, inventory, sync-standards, and the registry family. The family has eight management commands: queue, status, publish-status, yank, advise, unlist, withdraw, transfer. The reference is generated from --help.
API reference
The Adapter, HostServices and OperationContext protocols, plus the testing doubles, conformance checks, validation, presentation and packaging helpers.
CLI
One console script, benchweave-sdk, built on Click with Rich output. Every command works offline. No command admits a plugin, approves settings or qualifies hardware.
| Command | What it does | |
|---|---|---|
new | Create a synthetic external plugin project. Add --with-ui for a presentation envelope, binding catalogue and readings page. | ref → |
doctor | Report the project's pinned SDK version against the installed one, offline. A mismatch is a report, not an error. | ref → |
check | Run offline descriptor schema and basic semantic checks. | ref → |
check-ui | Validate a presentation candidate offline. | ref → |
check-preset | Validate complete configuration presets offline. | ref → |
preview-ui | Preview the plugin project on the standalone host, mock transport only. Needs the [server] extra. Loopback only unless you pass --allow-network. Every preview carries a simulated label. | ref → |
inventory | Print hashes for a prepared bundle. This is not a release manifest. | ref → |
sync-standards | Import a standards bundle into the SDK's vendored tree and lock. --check verifies the committed lock alone. | ref → |
Validate from the plugin project root
benchweave-sdk check src/benchweave_acme_model100/descriptor.json
benchweave-sdk check-ui src/benchweave_acme_model100/presentation.json \
--descriptor src/benchweave_acme_model100/descriptor.json \
--resources src/benchweave_acme_model100 \
--catalogue src/benchweave_acme_model100/binding-catalogue.json \
--firmware 1.0.0
pytest
uv build
--resources points at the package root. The envelope's resource_root: "ui" selects its ui/ subdirectory. Resource paths must stay inside the root and cannot traverse symlinks.
Gateway
This is the SDK. The BenchWeave gateway, the canonical architecture and the contract standards live in the main repository. The main repository mounts this package at packages/sdk as a git submodule. The package has its own CI and release cycle.
Vendored contract sets
The source distribution and wheel carry these standards so validation runs without the gateway checkout. standards-lock.json pins every file by hash. The release smoke compares installed bytes with the canonical copies.
Compatibility: SDK 0.15.0 against the main repository >=0.1.0.