Build device plugins without importing the gateway
Offline authoring and conformance tools for OTDP device plugins. Scaffold an independent project, hand your AI the generated guide and 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 with test dependencies, run
pytest, thenbenchweave-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
uv build, prepare registry metadata and reviewed evidence, then approve the release before publication or hardware qualification.benchweave-sdk inventorygenerates hashes, not a complete registry manifest.
Public surfaces
Six modules. No SDK superclass is required — the interfaces are structural.
interfaces
asyncStructural Adapter, HostServices, OperationContext and optional CaptureServices 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 S01/S02/S04 checks. 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, using the same validator bytes as the gateway.
packaging
integrityInventory and integrity checks for a prepared bundle, including duplicate, path and symlink rejection. No installation, signing or publication.
Compatibility and limits
The gateway bridge implements identify, scalar read and scalar write; profile actions, capture and streaming are not implemented by that bridge. The SDK supplies no live install endpoint, physical backend, container device permissions or hardware qualification. SDK and gateway versions are independently named — each release records the exact pair tested.
Questions and discussion
Stuck on a descriptor, or want to show what you are building? 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, check, check-ui, check-preset, preview-ui, inventory, sync-standards — 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; none of them 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 → |
check | Run offline descriptor schema and basic semantic checks. | ref → |
check-ui | Validate a presentation candidate offline. | ref → |
check-preset | Validate complete settings offline. | ref → |
preview-ui | Preview simulated presentation states on a local renderer. Loopback only unless --allow-network; every preview is labelled simulated. | ref → |
inventory | Print hashes for a prepared bundle; 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; this package is mounted there at packages/sdk as a git submodule with its own CI and release cycle.
Vendored contract sets
The sdist 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.1.0 against main project >=0.1.0.