Expand description
Write a Pulzr extension module in Rust.
An extension module is code a third party adds to the Pulzr platform, run
in the platform’s WebAssembly sandbox: a gateway support package’s adapter
(another vendor’s gateway, translated into protocol v1) or a carrier driver.
This crate hides the ABI (abi, docs/src/content/docs/abi.md): implement Package,
name your type in export!, and build for wasm32-unknown-unknown.
use pulzr_package::{export, Answer, Event, Package};
#[derive(Default)]
struct Hello;
impl Package for Hello {
fn handle(&mut self, event: Event) -> Answer {
let mut answer = Answer::default();
if let Event::Tick { .. } = event {
answer.log_info("still here");
}
answer
}
}
export!(Hello);The host functions (host) are imported only when called, and each must
be declared in the manifest’s imports; ids, hexs, correlation
and settings are the helpers gateway translators keep needing.
Re-exports§
pub use serde_json;
Modules§
- abi
- The ABI’s plumbing (docs/src/content/docs/abi.md), which
crate::export!wires up: the host writes an event into roompz_allocmade,pz_handlereads it, frees it, and returns the answer’s place in memory, kept until the next call. Other languages implement the same three exports. - correlation
- Matching an answer to its command without remembering anything.
- hexs
- Hex and base64.
- host
- The host functions (docs/src/content/docs/abi.md, module
pz). Each is imported only when called, and must be declared in the manifest’simports(log,now,state,http), or the platform refuses the module at install. Off wasm32 (in a crate’s own tests) they do nothing useful: test translation logic with plain functions, and the module withpulzr-pkg test. - ids
- MAC-48 and EUI-64. The platform names every device by EUI-64 and carries a
MAC inside one the way IEEE maps it,
FFFEbetween the OUI and the rest:BC5729049964isbc5729fffe049964. - settings
- Settings in a vendor’s own vocabulary: sections of values, as most
gateways group them. The platform computes nothing about a vendor’s
settings; a package’s
settings.setdoes, with these. - v1
- Protocol v1 messages a gateway package sends most, typed. Anything else
(and any member these leave out) goes as a
serde_json::Valuebody throughcrate::Answer::protocol; the platform checks every message against the protocol’s schema either way.
Macros§
- export
- Exports the ABI for a
Packagetype:pz_abi,pz_alloc,pz_handle. - json
- Construct a
serde_json::Valuefrom a JSON literal.
Structs§
- Answer
- The answer to one event. Every part is optional;
extracarries a kind’s own members (a carrier driver’s). - LogLine
- A line for the platform’s log.
- Map
- Represents a JSON key/value type.
- Protocol
- A protocol v1 message, as an adapter would publish it on
pulzr/a/<adapter>/d/<key>/<kind>. - Publish
- A vendor message to publish.
Enums§
- Event
- One event from the host. Gateway packages receive the first three; a kind
with other events (a carrier driver’s) reads them from
Event::Other. - Value
- Represents any valid JSON value.
Constants§
- ABI_
VERSION - The ABI version this crate’s exports implement.
Traits§
- Package
- An extension module. One value lives for as long as its instance does:
what it keeps may be lost at any time (a trap, an upgrade, a restart), so
keep in it only what costs nothing to lose, and the rest in
host::state_set.