Skip to main content

Crate pulzr_package

Crate pulzr_package 

Source
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 room pz_alloc made, pz_handle reads 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’s imports (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 with pulzr-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, FFFE between the OUI and the rest: BC5729049964 is bc5729fffe049964.
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.set does, 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::Value body through crate::Answer::protocol; the platform checks every message against the protocol’s schema either way.

Macros§

export
Exports the ABI for a Package type: pz_abi, pz_alloc, pz_handle.
json
Construct a serde_json::Value from a JSON literal.

Structs§

Answer
The answer to one event. Every part is optional; extra carries 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.