Tutorial

Run the gateway
and accept an event.

Run a self-contained MQTT demo, then initialize your own gateway. Rust MSRV 1.88.0; device protocol v1.

You will

Run a local MQTT demo
Initialize and validate a gateway configuration
Connect devices and a confirmed business sink

1. Run the demo

From a source checkout, run this command. It authenticates a real MQTT device, publishes a heartbeat, waits for the business sink ACK, then drains and exits. Omit --once for an interactive demo. Demo credentials are for local development only.

cargo run --locked -p netbaiot-cli -- demo --once

From an extracted release archive, run:

./netbaiot demo --once

2. Initialize your gateway

From an extracted release archive, initialize a directory, validate the configuration, and start the gateway. The CLI reads netbaiot.json in the current directory by default.

./netbaiot init my-gateway
cd my-gateway
../netbaiot config check --config netbaiot.json
../netbaiot serve

3. Connect a business sink

Configure a confirmed HTTP webhook or Business RPC V4 sink. Business RPC V5 event windows are opt-in. ACK only after application processing and make processing idempotent by event_id. The example below reads management and event credentials from environment variables.

use futures_util::StreamExt;
use netbaiot_client::NetbaIoTClient;
use netbaiot_protocol::EventFilter;

#[netbaiot_driver::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = NetbaIoTClient::builder()
        .endpoint(std::env::var("NETBAIOT_ENDPOINT")?)
        .token(std::env::var("NETBAIOT_TOKEN")?)
        .event_token(std::env::var("NETBAIOT_EVENT_TOKEN")?)
        .event_address(std::env::var("NETBAIOT_EVENT_ADDRESS")?.parse()?)
        .connect().await?;
    let mut events = client.events().subscribe(EventFilter::default()).await?;
    while let Some(delivery) = events.next().await {
        let delivery = delivery?;
        println!("event {}", delivery.event_id());
        // Process the event durably and idempotently before ACK.
        delivery.ack().await?;
    }
    Ok(())
}

The example uses futures-util, netbaiot-client, netbaiot-protocol and netbaiot-driver. The event address and token must match the Business RPC listener and authentication configuration. Production applications should complete durable processing before ACK.

4. Connect devices

Use standard MQTT 3.1.1 or the supported MQTT 5.0 profile, framed TCP, or authenticated UDP. Public device TCP requires TLS; UDP authentication does not encrypt payloads.

5. Production setup

Use netbaiot init --production to generate a configuration and independent device and management TLS material. Review the production PKI documentation and configure the business sink before deployment.

netbaiot init --production --domain example.com

The command creates netbaiot.json, a private CA hierarchy and independent device and management TLS keys in the current directory. Device ingress defaults to 0.0.0.0:8443; UDP uses the same port. Non-loopback management requires its own management_tls. Business RPC uses business_rpc.listen and an independent TLS profile.

Initialization displays the new offline CA password once. Store it securely, keep it out of logs, and do not supply it to the running gateway. Distribute only root-ca.pem as the appropriate client trust anchor; certificate hostname validation still applies. Certificates cover the base domain and its one-level wildcard; configure additional domains or IPs explicitly.

The generated authentication and business receiver addresses are local defaults. Start those services or change the configuration before deployment. Use netbaiot cert reload to update certificates on a running gateway; existing connections retain their old configuration and new handshakes use the new one.

Operating constraints

The gateway keeps runtime state in bounded memory and starts empty after restart.
EventAccepted is not business persistence; consumers must be idempotent on event_id.
Commands are not stored for offline devices.
Planned shutdown waits for required ACKs; a forced exit loses pending events.
The gateway is single-node; MQTT over WebSocket and shared subscriptions are not supported.

License

Current NetbaIoT versions use the NetbaIoT Commercial Software License. It permits 30 days of internal non-production evaluation. Production, hosting and redistribution require the applicable written commercial grant. Historical AGPL rights remain in effect for their respective copies.

Run the gatewayand accept an event.