Device Groups

Overview

A device group is a virtual device that aggregates multiple physical sensors into one logical unit. It represents a space — a room, a floor, a building — where you want unified measurements instead of separate readings from each individual sensor.

Device groups behave like physical devices across the platform:

• They have their own UUID
• They appear in the same GraphQL, MQTT, and Parquet APIs
• They store measurements in the same tables
• They can be installed to a space in the hierarchy

The key difference is that device groups have no hardware — their measurements are computed by the Occupancy Data Engine from the raw data of their member sensors.

Why Use Device Groups

When a space has multiple sensors, each device reports its own measurements independently. A meeting room with two doors has two Entryway sensors, each counting entries and exits at their door — but neither knows the total number of people in the room.

A device group solves this by combining those sensors into a single virtual device. The Occupancy Data Engine processes all member sensor data and produces one unified occupancy state for the entire space.

Single device — One sensor covers the entire space. No device group needed.

Device group — Multiple sensors cover one space, or you need aggregated occupancy logic (count + presence combined). Create a device group.

How Device Groups Work

Creating a Device Group

Device groups can be created through Haltian IoT applications or directly via the Service API (GraphQL). A device group needs a name and at least one member device.

Via Applications

Create and manage device groups using the application that fits your workflow:

• Haltian Field — Create, edit, and delete device groups. Add devices by scanning QR codes or searching by name.
• IoT Studio Web — Browse existing device groups and view members.

Via Service API (GraphQL)

Use the createDeviceGroup mutation to create a device group programmatically:

mutation CreateDeviceGroup {
  createDeviceGroup(
    name: "Meeting Room Taika",
    devices: ["device-uuid-1", "device-uuid-2"],
    keywords: ["meeting-room", "3rd-floor"]
  )
}

The response includes the device group’s UUID, which you use to query its measurements — exactly like a physical device:

{
  "data": {
    "deviceGroup": {
      "id": "731fda0a-7843-468d-94b3-e377a873deeb",
      "name": "Meeting Room Taika",
      "deviceType": {
        "productName": "Device Group",
        "model": "com.haltian.device-group",
        "make": "Haltian Oy"
      }
    }
  }
}

Member Devices

Any device type can be added to a device group. The Occupancy Data Engine processes measurements from supported sensor types (Entryway and Presence sensors) and ignores measurements from unsupported types.

This means you can group all devices in a room together — even if some don’t contribute to occupancy calculations — to keep them organized as a logical unit.

Query the member devices of a group:

query DeviceGroupDevices($deviceGroupId: uuid) {
  deviceGroupDevices(where: { deviceGroupId: { _eq: $deviceGroupId } }) {
    deviceGroupId
    deviceId
    memberDevice {
      id
      name
      identifiers { tuid }
      deviceType { make, model, productName }
    }
  }
}

Access Control

When you install a device group to a space in the hierarchy, it follows the same role-based access control as physical devices. Users can only see device groups installed in spaces they have access to.

Inactivity Reset Period

Each device group has a configurable inactivity period (in hours) that controls when the Occupancy Data Engine automatically resets the occupancy count to zero. When all sensors in the group have been inactive for this duration, the engine assumes the space is empty and corrects any accumulated count drift.

Choose the period based on the type of space — a meeting room might use 2–4 hours, while a floor or building entrance needs a longer period to avoid false resets during quiet hours. See Reset Logic for detailed behavior and guidance on choosing values.

Enriching Device Group Metadata

After creating a device group, you can add metadata to make it easier for your team and integrations to identify and work with. Metadata is managed through Haltian IoT applications or the Service API.

Keywords

Assign keyword tags to categorize and filter device groups. Keywords can be set during creation or added later.

mutation CreateDeviceGroup {
  createDeviceGroup(
    name: "Meeting Room Taika",
    devices: ["device-uuid-1", "device-uuid-2"],
    keywords: ["meeting-room", "3rd-floor", "capacity:10"]
  )
}

Common keyword patterns for device groups:

Keywords are searchable in applications and exported in the devicekeywords Parquet table.

Notes

Attach freeform text notes to a device group for installation details, configuration records, or maintenance logs. Each note is timestamped and records the author.

Use notes for information that changes over time or doesn’t fit a keyword, for example:

• “Entryway sensor at door 2 installed 15 cm above standard height due to door frame”
• “Room capacity reduced from 10 to 6 during renovation — update keyword after completion”
• “Presence sensor Zone B covers the alcove area near the window”

Notes are exported via the deviceNotes Parquet table.

Images

Upload a photo to visually identify the space or the sensor installation. Supported formats: JPEG, PNG, WebP.

Useful image examples:

• Room photo showing sensor placement
• Floor plan detail highlighting the device group’s coverage area
• Installation reference for maintenance teams

External ID

Map the device group to an identifier in an external system using the externalId field. This is useful when integrating with systems that have their own resource identifiers:

• Microsoft Places room resource ID
• Building management system zone ID
• Calendar system room identifier

mutation CreateDeviceGroup {
  createDeviceGroup(
    name: "Meeting Room Taika",
    devices: ["device-uuid-1", "device-uuid-2"],
    externalId: "room-resource@company.onmicrosoft.com"
  )
}

API Access

Device groups use the same UUID structure and API patterns as physical devices. No special handling is needed.

Device group structure is also exported via Parquet files in the devicegroups and devicegroupdevices tables, allowing you to reconstruct group membership in your data warehouse.

Next Steps

• Sensor Composition — Which sensor combinations work and how each behaves
• Occupancy Data Engine — How the engine processes device group data into occupancy measurements
• IoT Studio Web — Device Groups — Browse and manage device groups in the web application