Build a gateway package
A gateway support package brings another company’s gateway onto the Pulzr platform: its owner adopts it like any gateway, its devices’ readings arrive like any device’s, and the console manages it through the capabilities the package declares. The package is a repository you own; the platform installs a release of it into an organization, and runs its adapter, a WebAssembly module, in its sandbox. Adding a gateway type needs no platform release.
The worked example is examples/beacon-gateway,
a made-up beacon gateway that speaks JSON over MQTT.
pipx install pulzr-pkgrustup target add wasm32-unknown-unknownpulzr-pkg new gateway acme-gatewaycd acme-gatewaypulzr-pkg build && pulzr-pkg test| File | |
|---|---|
gateway.json |
the manifest: the gateway, how it is adopted, its broker topics, its management capabilities, and the adapter module |
commands.json |
the intents the adapter answers |
settings.schema.json, state.schema.json |
the gateway’s settings and facts, as JSON Schema, when it declares those capabilities |
src/lib.rs |
the adapter |
tests/*.jsonl |
events and the answers they must get, run by pulzr-pkg test |
.github/workflows/release.yml |
builds, checks and tests every push; releases a tag |
The manifest
Section titled “The manifest”What each key means is the platform’s gateway package specification; the ones you set first:
broker.gateway: the topics the gateway’s own login may publish and subscribe to, each naming the gateway ({mac},{eui}or{identity}), so one gateway is never granted another’s.broker.adapter: what the adapter hears (subscribe) and may send (publish). These are the vendor messages your module gets and gives.adapter.prefix: the name the adapter speaks as,<prefix>-<gateway EUI>, unique across packages.adapter.limits: fuel and memory per call (abi.md).adapter.imports:log,now,state; neverhttp(a gateway’s traffic is answered in line with every other gateway’s).
Events and answers
Section titled “Events and answers”Your module gets one event per call (Event):
message: a vendor message on one ofbroker.adapter’s subscriptions, with its topic, payload and the time it was received.intent: a protocol v1 intent for one of your gateways or a device behind one, with itsid,nameandparams(secret params opened for this call), itsexpiresand the time now.tick: about every ten seconds.
and answers with (Answer):
protocol: protocol v1 messages:upfor a device’s reading or frame,stateandsettingsfor the gateway itself (gw:<EUI>),event, andcmd/resfor each intent:sentwhen it went to the gateway, thendelivered,ok,refusedorfailedas the gateway answers.publish: vendor messages, on topicsbroker.adapterlets you publish on.log: lines for the platform’s log.
Matching without memory. Carry the intent’s id through the vendor’s
correlation field (correlation::seq_for_id for an integer one), and read it
back from the vendor’s answer (correlation::id_for_seq): your module then
keeps nothing about what is in flight, and losing its instance loses nothing.
What the platform enforces, whatever the module says: a vendor message
goes only to the instance of the organization whose gateway its topic names;
protocol messages are taken only for that organization’s gateways, checked
against the protocol’s schema; publish messages go only to those gateways’
own topics. pulzr-pkg test checks the same, so what passes there passes in
the platform.
Each line of a tests/*.jsonl file is one call:
{"name": "a reboot is sent with the id as its seq", "event": {"event": "intent", "adapter": "exbg-aabbccfffeddeeff", "key": "gw:aabbccfffeddeeff", "id": "10000042", "name": "reboot", "params": {}, "expires": null, "now": 1795000000.0}, "expect": {"publish": [{"topic": "example/down/AABBCCDDEEFF", "payload": "eyJjbWQiOiJyZWJvb3QiLCJzZXEiOjEwMDAwMDQyfQ=="}], "protocol": [{"adapter": "exbg-aabbccfffeddeeff", "key": "gw:aabbccfffeddeeff", "kind": "cmd/res", "body": {"v": 1, "id": "10000042", "status": "sent"}}]}}expect is the whole answer; expect_contains only what it must include.
install names the instance (a new name is a fresh one, as after a restart).
Every answer is also checked as the platform would check it.
Release
Section titled “Release”Tag the manifest’s version (v1.0.0) and push: the workflow builds the module,
writes its sha256 into the manifest, checks and tests it, and releases the
manifest, commands.json, the schemas and the module. Pulzar staff add the
release to the platform’s catalog by its tag, through the Pulzar GitHub App
installed on your repository (it reads releases, nothing else); an
organization’s admin then installs it.