Groups

Organize devices into groups for batch operations and aggregated telemetry streaming. RelayX supports two grouping models.

Group Types

Type	Access	Description
Logical groups	app.logicalGroup	Tag-based grouping — a device can belong to multiple groups
Hierarchy groups	app.heirarchyGroup	Path-based grouping — organize devices in a tree structure (e.g., zone-1.building-a.floor-1)

Logical Groups

Tag-based groups where devices are organized by labels. A device can belong to multiple logical groups.

create()

Create a new logical group with tags and devices. The returned object includes stream() and off() methods for immediate telemetry streaming.

JavaScript

const group = await app.logicalGroup.create({
  name: "floor_1_sensors",
  tags: ["floor_1", "temperature"],
  device_idents: ["sensor_01", "sensor_02"],
});

// you can start streaming right away
group.stream({
  callback: (data) => console.log(data),
});

Python

group = await app.logical_group.create({
    "name": "floor_1_sensors",
    "tags": ["floor_1", "temperature"],
    "device_idents": ["sensor_01", "sensor_02"],
})

# you can start streaming right away
await group.stream({
    "callback": lambda data: print(data),
})

Example response:

{
  "id": "69cb12a4ed4d9fe786145c01",
  "name": "floor_1_sensors",
  "tags": ["floor_1", "temperature"],
  "device_ids": ["69ca39e4ed4d9fe786145b48", "69ca3a12ed4d9fe786145b49"]
}

update()

Add or remove tags and devices from an existing logical group. The returned object includes stream() and off() methods.

JavaScript

await app.logicalGroup.update({
  id: groupId,
  tags: { add: ["humidity"], remove: ["floor_1"] },
  devices: { add: ["sensor_03"], remove: ["sensor_01"] },
});

Python

await app.logical_group.update({
    "id": group_id,
    "tags": {"add": ["humidity"], "remove": ["floor_1"]},
    "devices": {"add": ["sensor_03"], "remove": ["sensor_01"]},
})

list()

Retrieve all logical groups. Each group object includes stream() and off() methods.

JavaScript

const groups = await app.logicalGroup.list();

Python

groups = await app.logical_group.list()

Example response:

[
  {
    "id": "69cb12a4ed4d9fe786145c01",
    "name": "floor_1_sensors",
    "tags": ["floor_1", "temperature"],
    "device_ids": ["69ca39e4ed4d9fe786145b48", "69ca3a12ed4d9fe786145b49"]
  },
  {
    "id": "69cb12b8ed4d9fe786145c02",
    "name": "outdoor_sensors",
    "tags": ["outdoor", "weather"],
    "device_ids": ["69ca3a12ed4d9fe786145b49"]
  }
]

get()

Retrieve a single logical group by ID. The returned object includes stream() and off() methods.

JavaScript

const group = await app.logicalGroup.get(groupId);

Python

group = await app.logical_group.get(group_id)

listDevices()

Retrieve all devices in a logical group.

JavaScript

const devices = await app.logicalGroup.listDevices(groupId);

Python

devices = await app.logical_group.list_devices(group_id)

Example response:

[
  {
    "id": "69ca39e4ed4d9fe786145b48",
    "ident": "sensor_01",
    "schema": {
      "temperature": { "type": "number", "unit": "Celsius", "unit_symbol": "°C" },
      "humidity": { "type": "number", "unit": "Percent", "unit_symbol": "%" }
    },
    "config": { "reportInterval": 5000 }
  },
  {
    "id": "69ca3a12ed4d9fe786145b49",
    "ident": "sensor_02",
    "schema": {
      "pressure": { "type": "number", "unit": "Pascal", "unit_symbol": "Pa" }
    },
    "config": {}
  }
]

delete()

Permanently remove a logical group.

JavaScript

await app.logicalGroup.delete(groupId);

Python

await app.logical_group.delete(group_id)

stream() / off()

Stream telemetry from all devices in a group, or stop streaming.

JavaScript

const group = await app.logicalGroup.get(groupId);

group.stream({
  callback: (data) => {
    console.log(`Device ${data.ident}:`, data.data);
  },
});

// stop streaming
group.off();

Python

group = await app.logical_group.get(group_id)

await group.stream({
    "callback": lambda data: print(f"Device {data['ident']}: {data['data']}"),
})

# stop streaming
await group.off()

Example callback data:

{
  "ident": "sensor_01",
  "data": {
    "metric": "temperature",
    "value": 22.5,
    "timestamp": 1774690200000
  }
}

Hierarchy Groups

Path-based groups that organize devices in a tree structure using dot-separated paths. Useful for physical layouts like buildings, floors, and rooms.

create()

Create a new hierarchy group with a dot-separated path and devices. The returned object includes stream() and off() methods.

JavaScript

const group = await app.heirarchyGroup.create({
  name: "building_a_floor_1",
  heirarchy: "zone-1.building-a.floor-1",
  device_idents: ["sensor_01", "sensor_02"],
});

Python

group = await app.heirarchy_group.create({
    "name": "building_a_floor_1",
    "heirarchy": "zone-1.building-a.floor-1",
    "device_idents": ["sensor_01", "sensor_02"],
})

Example response:

{
  "id": "69cb14c2ed4d9fe786145c05",
  "name": "building_a_floor_1",
  "heirarchy": "zone-1.building-a.floor-1",
  "device_ids": ["69ca39e4ed4d9fe786145b48", "69ca3a12ed4d9fe786145b49"]
}

update()

Modify a hierarchy group's path or devices. The returned object includes stream() and off() methods.

JavaScript

await app.heirarchyGroup.update({
  id: groupId,
  heirarchy: "zone-1.building-a.floor-2",
  devices: { add: ["sensor_05"], remove: ["sensor_01"] },
});

Python

await app.heirarchy_group.update({
    "id": group_id,
    "heirarchy": "zone-1.building-a.floor-2",
    "devices": {"add": ["sensor_05"], "remove": ["sensor_01"]},
})

list()

Retrieve all hierarchy groups. Each group object includes stream() and off() methods.

JavaScript

const groups = await app.heirarchyGroup.list();

Python

groups = await app.heirarchy_group.list()

Example response:

[
  {
    "id": "69cb14c2ed4d9fe786145c05",
    "name": "building_a_floor_1",
    "heirarchy": "zone-1.building-a.floor-1",
    "device_ids": ["69ca39e4ed4d9fe786145b48", "69ca3a12ed4d9fe786145b49"]
  },
  {
    "id": "69cb14d6ed4d9fe786145c06",
    "name": "building_a_floor_2",
    "heirarchy": "zone-1.building-a.floor-2",
    "device_ids": ["69ca3b22ed4d9fe786145b50"]
  }
]

get()

Retrieve a single hierarchy group by ID. The returned object includes stream() and off() methods.

JavaScript

const group = await app.heirarchyGroup.get(groupId);

Python

group = await app.heirarchy_group.get(group_id)

listDevices()

Retrieve all devices in a hierarchy group.

JavaScript

const devices = await app.heirarchyGroup.listDevices(groupId);

Python

devices = await app.heirarchy_group.list_devices(group_id)

Example response:

[
  {
    "id": "69ca39e4ed4d9fe786145b48",
    "ident": "sensor_01",
    "schema": {
      "temperature": { "type": "number", "unit": "Celsius", "unit_symbol": "°C" }
    },
    "config": { "reportInterval": 5000 }
  }
]

delete()

Permanently remove a hierarchy group.

JavaScript

await app.heirarchyGroup.delete(groupId);

Python

await app.heirarchy_group.delete(group_id)

stream() / off()

Stream telemetry from devices in a hierarchy group with wildcard support.

JavaScript

const group = await app.heirarchyGroup.get(groupId);

group.stream({
  heirarchy: "zone-1.building-a.*",  // all floors in building A
  metrics: ["temperature"],
  callback: (data) => {
    console.log(`${data.ident} — ${data.metric}: ${data.value}`);
  },
});

group.off();

Python

group = await app.heirarchy_group.get(group_id)

await group.stream({
    "heirarchy": "zone-1.building-a.*",
    "metrics": ["temperature"],
    "callback": lambda data: print(f"{data['ident']} — {data['metric']}: {data['value']}"),
})

await group.off()

Example callback data:

{
  "ident": "sensor_01",
  "data": {
    "metric": "temperature",
    "value": 22.5,
    "timestamp": 1774690200000
  }
}