FiWorks Multi-Agent

6 Agents, 1 Library, 6 × Node.js

Today, FIWARE has 6 active IoT Agents, each a separate Node.js application, each consuming ~80–150 MB of RAM, each running its own Express HTTP server. They all depend on a shared base library (iotagent-node-lib) that handles 80% of the work: device provisioning, NGSI broker communication, configuration, and the northbound API.

A typical FIWARE IoT deployment with 3 protocols needs 3 separate Node.js processes (~300–450 MB RAM) plus the shared library duplicated in each process. They don't share device registries, don't share broker connections, and can't be managed as a single unit.

The iotagent-node-lib Architecture

The purple boxes are protocol-specific. Everything else is shared. In practice, the protocol plugin is 5–15% of the code; the library is 85–95%.

One Binary, Pluggable Protocols

Instead of 6 separate Node.js applications, the FiWorks Multi-Agent is a single C binary with protocol support via shared libraries (.so plugins) or compile-time flags:

# Run as JSON agent (MQTT + HTTP)
fiworks-agent --protocol json --mqtt localhost:1883 --broker localhost:1026

# Run as Ultralight agent
fiworks-agent --protocol ul --mqtt localhost:1883 --broker localhost:1026

# Run as OPC UA agent
fiworks-agent --protocol opcua --opcua-server opc.tcp://plc:4840 --broker localhost:1026

# Run as LoRaWAN agent (HTTP callback receiver)
fiworks-agent --protocol lorawan --port 4061 --broker localhost:1026

# Run as LWM2M agent (CoAP server)
fiworks-agent --protocol lwm2m --coap-port 5683 --broker localhost:1026

# Run as multi-protocol agent (why not?)
fiworks-agent --protocol json,ul,lorawan --mqtt localhost:1883 --broker localhost:1026

Architecture

// FiWorks Multi-Agent core (the new "iotagent-node-lib")

typedef struct FwProtocol {
    const char*     name;           // "json", "ul", "opcua", "lorawan", "lwm2m"
    KhStatus       (*init)(FwAgent* agent, FwConfig* config);
    KhStatus       (*decode)(FwAgent* agent, char* payload, int len, FtNode** measures);
    KhStatus       (*encode)(FwAgent* agent, FtNode* command, char** payload, int* len);
    void            (*shutdown)(FwAgent* agent);
} FwProtocol;

// The core handles everything else:
// - fwHttp: northbound API (device provisioning, config, health)
// - fwHttp client: NGSI-LD broker communication
// - fwHash: device registry (device ID -> entity mapping)
// - fwHash: device group management
// - fwJson: NGSI-LD entity building from decoded measures
// - fwAlloc: per-message bump allocation
// - fwTrace: structured logging
// - fwProm: Prometheus metrics

fw-libs Coverage: iotagent-node-lib → FiWorks Multi-Agent Core

The core library functionality is ~80% covered by existing fw-libs. The remaining 20% is transport-specific clients (MQTT, CoAP, OPC UA) which can use mature C libraries.

Protocol Plugins

Node.js vs C — The IoT Agent Hot Path

The IoT Agent hot path is: receive device message → decode → map to NGSI entity → POST/PATCH to broker. For a sensor sending a temperature reading every 10 seconds, this happens millions of times per day across a fleet.

Per-Message Processing

System-Level Comparison

The Multi-Protocol Advantage

The unified design isn't just about performance — it's about operational simplicity:

Why One Binary for All Protocols?

The current FIWARE IoT Agent architecture already proves the concept of a shared core with thin protocol layers. The iotagent-node-lib base library provides 85–95% of the functionality — device provisioning, northbound API, broker communication, attribute mapping, command handling — while each protocol agent contributes only 5–15% of protocol-specific code. Running 6 separate Node.js processes that each bundle that same 85–95% is pure waste.

What the Single Binary Gives You

• Shared device registry — one fwHash instance, one provisioning API. If a device switches protocol (or you realize it should be Ultralight instead of JSON), no re-provisioning is needed. The device is already known.
• Single broker connection pool — instead of 3 processes each maintaining their own HTTP connections to the broker, one pool is shared across all protocols. Fewer sockets, less broker load, better connection reuse.
• Operational simplicity — one process to monitor, one health endpoint, one log stream, one config file, one Prometheus metrics endpoint. For edge deployments (Raspberry Pi, industrial gateways) this matters enormously — every extra process is memory and complexity you can't afford.
• The protocol plugins are tiny — JSON is ~100 lines of C, Ultralight is ~50 lines. They share nothing with each other, so there is no coupling risk between protocols. Each plugin is just a decode function and an encode function behind a common interface.
• Sub-50ms startup — the entire multi-protocol agent starts in under 50ms, compared to 2–5s per Node.js agent. Crash recovery is near-instant.

Fault Isolation

The natural question: if one protocol plugin crashes, does it take down the others? The answer depends on the protocol:

For the simple text-based protocols (JSON, UL, LoRaWAN, Sigfox), there is no practical fault isolation concern — they are pure parsing code running in the process space with no external library dependencies that could cause unexpected crashes.

For the complex protocols (OPC-UA, LWM2M) that wrap external C libraries, a segfault in the library would take down the entire process. However, with restart: always and <50ms startup time, recovery is near-instant — all protocols come back online in the blink of an eye.

# Instance 1: simple protocols (shared)
fiworks-agent --protocol json,ul,lorawan --mqtt localhost:1883 --broker localhost:1026

# Instance 2: OPC-UA isolated
fiworks-agent --protocol opcua --opcua-server opc.tcp://plc:4840 --broker localhost:1026

Effort Estimate with Claude Max

Phase 1: Core + JSON + Ultralight (the quick wins)

Phase 2: LoRaWAN + Sigfox (HTTP callback protocols)

Phase 3: OPC UA + LWM2M (complex protocols)