ironflock

About

With this library you can publish data from your apps on your IoT edge hardware to the fleet data storage of the IronFlock devops platform. When this library is used on a certain device the library automatically uses the private messaging realm (Unified Name Space) of the device's fleet and the data is collected in the respective fleet database.

So if you use the library in your app, the data collection will always be private to the app user's fleet.

For more information on the IronFlock IoT Devops Platform for engineers and developers visit our IronFlock home page.

Requirements

• Node.js: 18 or higher
• Browser: Any modern browser with WebSocket support (Chrome, Firefox, Safari, Edge)

Installation

npm install ironflock

Usage

import { IronFlock } from "ironflock";

// Create an IronFlock instance to connect to the IronFlock platform data infrastructure.
// The IronFlock instance handles authentication when run on a device registered in IronFlock.
const ironflock = new IronFlock();

// Start the connection to the platform
await ironflock.start();

// Publish an event
await ironflock.publish("test.publish.example", [{ temperature: 20 }]);

// Stop the connection when done
await ironflock.stop();

Options

The IronFlock constructor accepts an options object. In Node.js, values fall back to environment variables. In the browser, all config must be passed explicitly.

{
  serialNumber?: string;  // Device serial number (env: DEVICE_SERIAL_NUMBER)
  deviceName?: string;    // Device display name (env: DEVICE_NAME)
  deviceKey?: string;     // Device key for auth (env: DEVICE_KEY)
  appName?: string;       // Application name (env: APP_NAME)
  swarmKey?: number;      // Fleet/swarm key (env: SWARM_KEY)
  appKey?: number;        // Application key (env: APP_KEY)
  env?: string;           // Environment: "DEV" or "PROD" (env: ENV)
  reswarmUrl?: string;    // Studio URL to resolve WebSocket URI (env: RESWARM_URL)
  cburl?: string;         // Direct WebSocket URI override
}

All fields are optional in the type, but serialNumber is required at runtime (either via the option or the DEVICE_SERIAL_NUMBER environment variable).

Browser Usage

The library works in modern browsers. Since browsers don't have environment variables, pass all config via the constructor:

import { IronFlock } from "ironflock";

const ironflock = new IronFlock({
  serialNumber: "device-serial-from-server",
  deviceKey: "my-device-key",
  appName: "MyWebApp",
  swarmKey: 10,
  appKey: 20,
  env: "PROD",
});

await ironflock.start();
await ironflock.publish("sensor.readings", [{ temperature: 22 }]);

Loading config from a server

Use IronFlock.fromServer() to fetch configuration from your backend:

import { IronFlock } from "ironflock";

// Your backend endpoint returns a JSON object matching IronFlockOptions
const ironflock = await IronFlock.fromServer("/api/ironflock-config");
await ironflock.start();

Your backend endpoint should return JSON like:

{
  "serialNumber": "device-serial-123",
  "deviceKey": "dev-key-1",
  "appName": "MyApp",
  "swarmKey": 10,
  "appKey": 20,
  "env": "PROD"
}

Normally the server should extracts these values from the environment variables of the server process, since they depend on the execution environment. i.e. the edge device the server is running on.

Security note: The endpoint providing device credentials should be protected by authentication. This is normally already provided by the IronFlock remote access proxy when executed in an IronFlock project.

API Reference

publish(topic, args?, kwargs?)

Publishes an event to a topic on the IronFlock message router.

const publication = await ironflock.publish("com.myapp.mytopic", [{ temperature: 20 }]);

| Parameter | Type | Description | |-----------|------|-------------| | topic | string | The URI of the topic to publish to | | args | unknown[], optional | Payload arguments | | kwargs | Record<string, unknown>, optional | Payload keyword arguments |

Returns: Promise<unknown> — The publication object (an acknowledged publish receipt).

publishToTable(tablename, args?, kwargs?)

Convenience function to publish data to a fleet table in the IronFlock platform. Automatically constructs the correct topic using the SWARM_KEY and APP_KEY environment variables.

await ironflock.publishToTable("sensordata", [{ temperature: 22.5, humidity: 60 }]);

| Parameter | Type | Description | |-----------|------|-------------| | tablename | string | The name of the table, e.g. "sensordata" | | args | unknown[], optional | Row data to publish | | kwargs | Record<string, unknown>, optional | Row data as keyword arguments |

Returns: Promise<unknown> — The publication object (an acknowledged publish receipt).

appendToTable(tablename, args?, kwargs?)

Appends data to a fleet table by calling the registered append procedure at append.<SWARM_KEY>.<APP_KEY>.<tablename>. Unlike publishToTable, this uses a remote procedure call rather than a pub/sub event.

await ironflock.appendToTable("sensordata", [{ temperature: 22.5, humidity: 60 }]);

| Parameter | Type | Description | |-----------|------|-------------| | tablename | string | The name of the table, e.g. "sensordata" | | args | unknown[], optional | Row data to append | | kwargs | Record<string, unknown>, optional | Row data as keyword arguments |

Returns: Promise<unknown> — The result of the remote procedure call.

subscribe(topic, handler)

Subscribes to a topic on the IronFlock message router.

function onMessage(...args: any[]) {
  console.log("Received:", args);
}

const subscription = await ironflock.subscribe("com.myapp.mytopic", onMessage);

| Parameter | Type | Description | |-----------|------|-------------| | topic | string | The URI of the topic to subscribe to | | handler | (...args: any[]) => void | Function called when a message is received |

Returns: Promise<Subscription | undefined> — The subscription object.

subscribeToTable(tablename, handler)

Convenience function to subscribe to a fleet table. Automatically constructs the correct topic using the SWARM_KEY and APP_KEY environment variables.

function onTableData(...args: any[]) {
  console.log("New row:", args);
}

await ironflock.subscribeToTable("sensordata", onTableData);

| Parameter | Type | Description | |-----------|------|-------------| | tablename | string | The name of the table to subscribe to | | handler | (...args: any[]) => void | Function called when new data arrives |

Returns: Promise<Subscription | undefined> — The subscription object.

getHistory(tablename, queryParams?)

Retrieves historical data from a fleet table.

// Simple query with limit
const data = await ironflock.getHistory("sensordata", { limit: 100 });

// Query with time range and filters
const data = await ironflock.getHistory("sensordata", {
  limit: 500,
  offset: 0,
  timeRange: {
    start: "2026-01-01T00:00:00Z",
    end: "2026-03-01T00:00:00Z",
  },
  filterAnd: [
    { column: "temperature", operator: ">", value: 20 },
    { column: "humidity", operator: "<=", value: 80 },
  ],
});

| Parameter | Type | Description | |-----------|------|-------------| | tablename | string | The name of the table to query | | queryParams | TableQueryParams | Query parameters (see below) |

queryParams fields:

| Field | Type | Description | |-------|------|-------------| | limit | number | Maximum number of rows to return (1–10000, required) | | offset | number, optional | Offset for pagination | | timeRange | ISOTimeRange, optional | { start: "<ISO datetime>", end: "<ISO datetime>" } | | filterAnd | SQLFilterAnd[], optional | List of AND filter conditions: { column: string, operator: string, value: ... } |

Supported filter operators: =, !=, >, <, >=, <=, LIKE, ILIKE, IN, NOT IN, IS, IS NOT.

Returns: Promise<unknown | null> — The query result data (typically an array of row objects), or null if the call failed.

call(topic, args?, kwargs?)

Calls a remote procedure on the IronFlock message router using a full WAMP topic URI.

const result = await ironflock.call("some.full.wamp.topic", [42]);

| Parameter | Type | Description | |-----------|------|-------------| | topic | string | The full WAMP URI of the procedure to call | | args | unknown[], optional | Positional arguments | | kwargs | Record<string, unknown>, optional | Keyword arguments |

Returns: Promise<unknown> — The result of the remote procedure call.

callDeviceFunction(deviceKey, topic, args?, kwargs?)

Calls a remote procedure registered by another IronFlock device. Automatically assembles the full WAMP topic as {swarmKey}.{deviceKey}.{appKey}.{env}.{topic}.

const result = await ironflock.callDeviceFunction(42, "com.myapp.myprocedure", [42]);

| Parameter | Type | Description | |-----------|------|-------------| | deviceKey | number | The device key of the target device | | topic | string | The URI of the procedure to call | | args | unknown[], optional | Positional arguments | | kwargs | Record<string, unknown>, optional | Keyword arguments |

Returns: Promise<unknown> — The result of the remote procedure call.

callFunction() is a deprecated alias for callDeviceFunction().

IronFlock.fromServer(url) (static)

Fetches configuration from a server endpoint and creates an IronFlock instance. Useful in browser environments where the backend provides device credentials.

const ironflock = await IronFlock.fromServer("/api/ironflock-config");
await ironflock.start();

| Parameter | Type | Description | |-----------|------|-------------| | url | string | URL of the endpoint returning IronFlockOptions JSON |

Returns: Promise<IronFlock> — A configured IronFlock instance.

registerDeviceFunction(topic, endpoint)

Registers a procedure that can be called by other devices in the fleet. Automatically constructs the full WAMP topic as {swarmKey}.{deviceKey}.{appKey}.{env}.{topic}.

function add(args: any[]) {
  return args[0] + args[1];
}

await ironflock.registerDeviceFunction("com.myapp.add", add);

| Parameter | Type | Description | |-----------|------|-------------| | topic | string | The URI of the procedure to register | | endpoint | (...args: any[]) => any | The function to register |

Returns: Promise<Registration | undefined> — The registration object.

register() is an alias for registerDeviceFunction(). registerFunction() is a deprecated alias.

setDeviceLocation(long, lat)

Updates the device's location in the platform master data. The maps in device or group overviews will reflect the new location in realtime.

await ironflock.setDeviceLocation(8.6821, 50.1109);

| Parameter | Type | Description | |-----------|------|-------------| | long | number | Longitude (-180 to 180) | | lat | number | Latitude (-90 to 90) |

Returns: Promise<unknown | null> — The result of the location update call, or null if the call failed.

Note: Location history is not stored. If you need location history, create a dedicated table and use publishToTable.

getRemoteAccessUrlForPort(port)

Returns the remote access URL for a given port on the device.

const url = ironflock.getRemoteAccessUrlForPort(8080);
// e.g. "https://<device_key>-<app_name>-8080.app.ironflock.com"

| Parameter | Type | Description | |-----------|------|-------------| | port | number | The port number |

Returns: string | null — The remote access URL string, or null if the device key or app name is not available.

Properties

| Property | Type | Description | |----------|------|-------------| | isConnected | boolean | true if the connection to the platform is established | | connection | CrossbarConnection | The underlying connection instance (for advanced use) |

Lifecycle Methods

| Method | Description | |--------|-------------| | await start(cburl?) | Configures and starts the connection to the platform | | await stop() | Stops the connection |

Development

Install dependencies:

npm install

Run tests:

npm test              # Node.js tests
npm run test:browser  # Browser environment tests
npm run test:all      # Both

Type check:

npm run typecheck

Build:

npm run build

Publish a new release:

npm run release