Humly Integration

Forward Haltian IoT sensor measurements to the Humly Control Panel API for room and desk sensor display

Status

The Humly Connector is under active development.

Overview

Humly is a third-party workplace and room-booking management platform with its own Control Panel REST API. The Humly Connector (also referred to as the Humly Integrator) is a Go service, owned by Haltian, whose job is to forward Haltian IoT sensor measurements to the Humly Control Panel API so that Humly can display sensor state temperature, occupancy, and related readings against its own rooms and desks.

The integration is one-directional: the connector reads sensor measurements from Haltian IoT and pushes them into Humly. Humly does not call back into Haltian IoT, and there is no reverse or pull direction. The connector is multi-tenant, one integration configuration per Haltian organization.

Architecture

The connector sits between Haltian’s sensor data pipeline and the Humly Control Panel API. It consumes sensor measurements, maps each measurement type to the corresponding Humly sensor type, and pushes the mapped readings to Humly via REST calls.

Components

Component	Role
Haltian sensor devices	Detect temperature, humidity, pressure, CO2, occupancy, and presence
Haltian IoT measurement pipeline	Publishes sensor measurements for downstream consumers
Humly Connector - Message Workers	Consume measurement events and hand them to the sensor registry
Humly Connector - Sensor Registry	Discovers and validates sensors as measurements arrive
Humly Connector - Batch Handler	Batches mapped readings before submission to Humly
Humly Connector - Humly Client	Authenticates with Humly and submits sensor readings, with circuit breaker and retry logic
Humly Connector - Integration Manager	Manages per-tenant configuration and lifecycle (pending, active, paused, error, disabled)
Humly Control Panel API	Receives sensor registrations and readings via REST
Humly platform	Surfaces sensor readings against rooms and desks in the Humly product

Sensors are auto-created in Humly the first time a measurement for that device and measurement type arrives (identified by device ID and measurement type). A newly created sensor appears unassigned in Humly until it is manually mapped to a room inside Humly’s own UI - the connector does not perform or configure this mapping.

Data Flow

Measurement Lifecycle

Measurement - A Haltian sensor device reports a measurement (temperature, humidity, pressure, CO2, occupancy, or presence).
Consumption - The Humly Connector’s message workers pick up the measurement event.
Mapping - The connector maps the Haltian measurement type to the corresponding Humly sensor type (see table below). Measurement types with no mapping are skipped.
Registration - If the sensor has not been seen before, the connector registers it with Humly via the Control Panel API.
Submission - The connector submits the mapped reading to the Humly Control Panel API, batching and rate-limiting as needed.
Presentation - The reading appears against the corresponding sensor in Humly. A person then manually assigns that sensor to a room or desk inside Humly’s own UI.

Measurement Type Mapping

Haltian measurement type	Humly sensor type	Unit
`ambient_temperature`, `system_temperature`	`temperature`	°C
`humidity`	`relativeHumidity`	%
`barometric_pressure`	`pressure`	-
`co2`	`co2`	ppm
`occupancy_status`, `movement_detections`, `directional_movement`	`motion`	-
`presence`	`presence`	-

Any measurement type not listed above is skipped and not forwarded to Humly.

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#F6FAFA', 'primaryTextColor': '#143633', 'primaryBorderColor': '#143633', 'lineColor': '#143633', 'secondaryColor': '#C7FDE6', 'tertiaryColor': '#73F9C1', 'clusterBkg': '#ffffff', 'clusterBorder': '#143633', 'edgeLabelBackground': '#ffffff'}}}%%
flowchart TB
    subgraph North["Humly Platform (North)"]
        HumlyUI[Humly Rooms / Desks UI]
        HumlyAPI[Humly Control Panel API]
    end

    subgraph Middle["Haltian IoT (Middle)"]
        Pipeline[Haltian IoT Measurement Pipeline]
        Connector[Humly Connector]
    end

    subgraph South["Sensor Devices (South)"]
        Temp[fa:fa-thermometer-half Temperature / Humidity / CO2 Sensor]
        Occ[fa:fa-walking Occupancy / Presence Sensor]
    end

    Temp --> Pipeline
    Occ --> Pipeline
    Pipeline --> Connector
    Connector --> HumlyAPI
    HumlyAPI --> HumlyUI

Next Steps

Integration Guide - Setup and configuration for the Humly Connector
Supported Sensors - Which Haltian sensors feed data into Humly and what they report
FAQ - Common questions about scope, mapping, and current limitations