All guides

How-to guides · 8 min

A WebAssembly telemetry normalisation module

A telemetry transform module is a small WebAssembly program that takes a vendor's raw fields and returns candidate Wesfin canonical fields. The Lab runs it in isolation with hard limits, checks every result itself and records input and output hashes.

Why a module if there is a profile

A declarative profile is enough when a field only needs renaming and scaling. But some devices report scaled integers, separate charge and discharge registers or an inverted sign. A module expresses that conversion in code, and the module version and its SHA-256 make the result reproducible.

The contract: one function

A module is a WebAssembly component with exactly one export, transform, and no imports. Input and output are UTF-8 JSON. The wesfin:lab-telemetry@1.0.0 contract is versioned separately from the engine.

WIT
world telemetry-transform {
  export transform: func(input: list<u8>) -> result<list<u8>, string>;
}
spec example
// payload (vendor-shaped sample)
{ "battery_soc": 735, "power_w": -4200 }

// transform-output-1
{ "sample_id": "<echo>",
  "candidate_fields": { "soc_pct": 73.5, "asset_active_power_kw": -4.2 },
  "diagnostics": [] }

Signs follow the Wesfin canonical convention: asset_active_power_kw plus is discharge, minus is charge. Converting the vendor's convention is the module's job; the host checks the result.

What a module cannot do

A module has no imports, so it has no files, network, environment variables, secrets, clock, randomness, database, MQTT or device interfaces (Modbus, CAN). A module that imports anything, including a normal wasm32-wasip2 build, is rejected before it runs with FORBIDDEN_IMPORT.

LimitValue and failure code
Module size2 MiB · MODULE_TOO_LARGE
Module hashmust match the SHA-256 · MODULE_HASH_MISMATCH
Input and output64 KiB each · INPUT_TOO_LARGE, OUTPUT_TOO_LARGE
Memory32 MiB · MEMORY_LIMIT
Compute10 M Wasmtime fuel · FUEL_EXHAUSTED
Time250 ms · TIMEOUT

Every run is a fresh instance in its own process, so a module cannot keep state between runs.

How to read the result

Result layerWhat it checks
executionThe module ran and returned within the limits.
schemaThe response envelope and its link to the sample (sample_id).
semanticOnly known canonical measurement fields with allowed values.
fixture_matchA match with the fixture's expected values, when it has them.

The result always carries environment LAB and production_eligible false. Candidate fields are published nowhere: not to the digital twin, not to MQTT.

Try it

  1. In the Lab

    Open a workspace, then Modules. Pick the reference module and a fixture and press Run. The runs table shows the state, error code, fuel, time and report hash.

  2. Locally

    Build the runtime and the reference module from the repository (Rust and Wasmtime), then run the spec example. Exit code 0 is PASSED, 1 FAILED, 2 ERROR.

    shell
    wesfin-lab-runtime run \
      --module telemetry-normalizer.wasm \
      --sha256 "$(cut -d' ' -f1 MODULE.sha256)" \
      --fixture contracts/lab-wasm/fixtures/spec-example.json --workspace-id ws-local
  3. Your own module

    Start from the reference module, build for wasm32-unknown-unknown and turn it into a component. Divide scaled integers (735 / 10.0) rather than multiplying by 0.1.

Right now the Lab runs only Wesfin reference modules pinned in the repository. Your own modules run locally; uploading arbitrary modules to the Lab needs a separate isolated runtime and is not open yet.