Keragi Docs

Development and device integration

Keragi is not limited to the bundled clients: the server can load custom WASM resources, and devices can join the messaging system through a gateway or as a client participant. This page covers the interface model, a simple example and device integration patterns.

1. Two extension paths

2. Custom WASM resources

2.1 Runtime model

2.2 Simple example: hello + echo

The minimal resource below exposes GET /demo/hello and POST /demo/echo.

Cargo.toml:

[package]
name = "hello-resource"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[features]
default = ["wasm"]
wasm = ["wasm-core/wasm"]

[dependencies]
wasm-core = { version = "0.1", default-features = false }
serde = { version = "1", features = ["derive"] }
serde_json = "1"

src/lib.rs:

use serde::{Deserialize, Serialize};
use wasm_core::{get, post, wasm_handler, wasm_main, Json, Router};

#[wasm_main]
fn router() -> Router {
    Router::new()
        .route("/hello", get(hello))
        .route("/echo", post(echo))
}

#[wasm_handler]
async fn hello() -> String {
    "hello from hello-resource".to_string()
}

#[derive(Deserialize)]
struct EchoRequest {
    message: String,
}

#[derive(Serialize)]
struct EchoResponse {
    message: String,
}

#[wasm_handler]
async fn echo(Json(req): Json<EchoRequest>) -> EchoResponse {
    EchoResponse { message: req.message }
}

Build:

cargo build --release --target wasm32-unknown-unknown \
  --no-default-features --features wasm

The output is target/wasm32-unknown-unknown/release/hello_resource.wasm.

2.3 Packaging and installation

Resource directory:

hello-resource/
├── package.json
├── wasmx.resource.json
└── wasm/hello.wasm

package.json:

{
  "name": "@example/hello-resource",
  "version": "0.1.0",
  "files": ["wasm", "wasmx.resource.json"]
}

wasmx.resource.json:

{
  "resources": [
    {
      "name": "hello",
      "file": "hello.wasm",
      "config": { "prefix": "/demo", "allow_http": true }
    }
  ]
}

Install and start:

cp target/wasm32-unknown-unknown/release/hello_resource.wasm \
  hello-resource/wasm/hello.wasm

wasmx add ./hello-resource
wasmx stop
wasmx start

curl http://127.0.0.1:3001/demo/hello
curl -X POST http://127.0.0.1:3001/demo/echo \
  -H 'content-type: application/json' \
  -d '{"message":"hi"}'

The example uses the current Rust SDK interface. How the official SDK, macros, templates and examples will be distributed will be announced with the developer edition; if the interface changes, the SDK documentation for that version governs.

2.4 Data and authentication

3. Device integration

3.1 Three integration modes

ModeData pathCan it read end-to-end encrypted messages?Typical use
Device as a client participantDevice holds its own identity and keys and joins specific conversations/channelsYes, but only conversations it is a member ofDevices with secure storage and enough compute
WASM gateway resourceDevice ↔ gateway resource ↔ messaging systemNo for end-to-end encrypted messages; only plaintext/bot channels or client-side bridgingSensors, actuators, HTTP/MQTT devices
Local edge bridgeDevice ↔ local bridge (client) ↔ conversationsYes; the bridge machine becomes a trusted endpointHome, industrial, serial/GPIO devices

Encryption boundary: the server only holds ciphertext, so a server-side WASM gateway cannot decrypt end-to-end encrypted messages. Devices that need to read encrypted messages must join as client participants, or be controlled by a local bridge that decrypts on the client side.

3.2 Typical data flows

3.3 Example endpoints

These are endpoints a gateway resource can implement; the device-side protocol is up to you:

MethodPathPurpose
POST/device/{id}/telemetryReport sensor data, e.g. {"temperature":23.5,"ts":...}
GET/device/{id}/commandsSSE/WebSocket long connection for commands
POST/device/{id}/ackAcknowledge command execution
POST/device/{id}/relayControl a relay/actuator, e.g. {"channel":1,"on":true}
GET/device/{id}/stateQuery device state

3.4 Authentication and security

3.5 Actuators and physical safety

Important: Relays, motors, valves and other actuators involve personal and property safety. Design fail-safe behavior, emergency stop, timeout reset, authorization and manual override, and test before connecting real loads. The examples here describe software integration only and are not an industrial safety certification or guarantee.

3.6 ESP32 and similar devices