Skip to main content

XY Sense

XYSense

The XY Sense connector integrates with the XY Sense occupancy and indoor air quality (IAQ) sensing platform. It listens for real-time updates as occupancy changes or new sensor readings come in from the sensors installed in each mapped floor space. Using webhooks, it streams live occupancy status, headcount data, and environmental metrics directly into the Mapped graph.

Use Cases​

  • Real-time occupancy monitoring: Track which spaces are currently occupied and their headcount to drive workplace analytics dashboards.
  • Indoor air quality visibility: Monitor temperature, humidity, CO₂, TVOC, particulate matter, noise, light, and barometric pressure to ensure healthy and comfortable environments.
  • Space utilization analysis: Aggregate historical occupancy and environmental data to identify underused or overcrowded spaces and inform space planning decisions.
  • Occupancy & IAQ-driven automation: Use live occupancy and air quality signals as triggers for downstream building systems such as HVAC, ventilation, lighting, or cleaning schedules.

Configuration​

Auth Requirements​

The connector authenticates with the XY Sense Core API using an API key name and secret. The API key must have WriteExternalApi permissions enabled so the connector can register and manage webhooks.

FieldRequiredDescription
Api Key NameYesThe name of the API key issued by XY Sense. Found in the XY Sense admin portal under API key management.
Api SecretYesThe secret associated with the API key. Provided when the API key is created in the XY Sense portal.

During configuration, the connector validates the credentials by minting a bearer token and confirming write permissions by creating and immediately deleting a test webhook.

Place Mappings​

The connector fetches all available floor spaces from XY Sense and presents them for mapping to the Mapped graph hierarchy. Each row maps an XY Sense floor space to a Building → Floor → Space hierarchy.

FieldRequiredUniqueDescription
building.nameYes—Name of the building (auto-populated from XY Sense location name)
building.addressYes—Address of the building (auto-populated from XY Sense location address)
floor.nameYes—Name of the floor (auto-populated from XY Sense floor name)
floor.levelYes—Numeric floor level (auto-derived from floor name, e.g. "Level 3" → level 2, zero-indexed)
space.nameYes—Name of the space (auto-populated from XY Sense floor space name)
space.codeNo—Optional space code identifier
space.refIdYesYesUnique XY Sense floor space ID used to link webhook events to mapped spaces

Advanced Options​

OptionTypeDefaultDescription
Materialize Sensor HealthBooleanOffAdds Battery Level and Signal Strength points to each physical XY Sense sensor's device. Sensors report these every 5 to 15 minutes, so turning this on adds a large volume of readings. Takes effect when the connector restarts after saving. Turning it off again stops new readings, but devices already created stay in the graph.
Materialize Sensor OccupancyBooleanOffGives each presence sensor (such as the Milesight NE203) its own Occupancy Sensor point, on that sensor's device. Each space already has an occupancy point that combines all of its sensors, so most sites do not need this. While it is on, XY Sense also sends the sensors' battery and signal readings; the connector discards them unless Materialize Sensor Health is on too. Takes effect when the connector restarts after saving.
Materialize Area And Entry SensorsBooleanOffAdds a device for each XY Sense area sensor and entry sensor on the mapped floors, with a Heartbeat that shows whether XY Sense sees the sensor online, checked every hour. Takes effect when the connector restarts after saving.

Reports and Cleanup​

The Reports section of the connector has two reports, each with an export to CSV. Both are worked out when you open them, from XY Sense and the Mapped graph.

ReportShows
Device Point MappingEach air quality point that earlier versions put on a space's XY Sense IAQ Sensor device, and the point on the physical sensor that replaces it, with the Mapped IDs and mapping keys of both. A space point measured by one sensor moves to that sensor and keeps its ID; a second sensor in the same space gets a new point.
Cleanup PreviewEach entity the Clean Up Unused Entities job deletes: the space XY Sense IAQ Sensor devices and the space points that did not move to a sensor.

Clean Up Unused Entities is a job under Jobs. It runs as a dry run unless you turn Dry Run off. Deleting is permanent, so check the Cleanup Preview report first. The job only runs once a sync has moved the points to their sensors; before that it stops without deleting anything. This job is temporary and will be removed once it has run on every connector.

Mapped Concepts​

API to Mapped Entities​

Occupancy Entities

XY Sense ConceptMapped Entity TypeexactTypeDescription
Location (Building)Building—Created by place mapping; the building containing the floor spaces
FloorFloor—Created by place mapping; the floor within the building
Floor SpaceSpace—Created by place mapping; the physical space being monitored. Carries maxOccupancy from the XY Sense capacity value.
— (virtual)ZoneOCCUPANCY_ZONEAn occupancy zone that is part of the Space (isPartOf). Groups the occupancy sensing device and its points.
— (virtual)ThingOCCUPANCY_SENSING_DEVICEA virtual occupancy sensing device that serves the zone and is located in the space.
Occupancy StatusPointOCCUPANCY_SENSORBinary occupancy status point — 0 = CurrentlyOccupied, 1 = NotOccupied
HeadcountPointOCCUPANCY_COUNT_SENSORNumeric headcount point — current number of occupants in the space

IAQ (Air Quality) Entities

XY Sense ConceptMapped Entity TypeexactTypeDescription
Space SensorThingAIR_QUALITY_SENSING_DEVICE, OCCUPANCY_SENSING_DEVICE or DEVICEOne device per physical sensor serving a mapped space, typed by its hardware (air quality monitor, presence sensor, or other). Named after the sensor model and its installation name, with the sensor's hardware id as serialNumber. Located in each Space it serves. Holds a point for each environmental capability it measures, plus its battery and signal points and its own occupancy point when those options are on.
TemperaturePointTEMPERATURE_SENSORAmbient temperature reading
HumidityPointHUMIDITY_SENSORRelative humidity reading
Ambient LightPointILLUMINANCE_SENSORAmbient light level in lux
Relative LightPointILLUMINANCE_SENSORRelative light level as percentage
Ambient NoisePointSOUND_PRESSURE_LEVEL_SENSORAmbient noise level in decibels
Sound PressurePointSOUND_PRESSURE_LEVEL_SENSORSound pressure in pascals
Barometric PressurePointABSOLUTE_BAROMETRIC_PRESSURE_SENSORBarometric pressure reading
Carbon DioxidePointCO2_LEVEL_SENSORCO₂ concentration in parts per million
Volatile Organic CompoundsPointTVOC_LEVEL_SENSORTotal volatile organic compound concentration
Particulate Matter 1PointPM_1_LEVEL_SENSORPM1 particulate matter concentration
Particulate Matter 2.5PointPM_2_5_LEVEL_SENSORPM2.5 particulate matter concentration
Particulate Matter 10PointPM_10_LEVEL_SENSORPM10 particulate matter concentration
Battery PercentagePointBATTERY_LEVEL_SENSORRemaining battery of one physical sensor
Signal StrengthPointCOMMUNICATION_SIGNAL_STRENGTH_SENSORRadio signal strength of one physical sensor
Occupancy (presence sensor)PointOCCUPANCY_SENSORWhether one presence sensor currently detects someone

Area and Entry Sensor Entities

Created only when Materialize Area And Entry Sensors is on. XY Sense uses these sensors to work out each space's occupancy and headcount, which already reach the space's occupancy points. The devices let you see and track the sensors themselves.

XY Sense ConceptMapped Entity TypeexactTypeDescription
Area SensorThingOCCUPANCY_SENSING_DEVICEAn overhead sensor that watches part of the floor plan rather than one space. One device per active area sensor on a mapped floor, named XY Sense Area Sensor followed by its installation name or serial number. Its MAC address is the serialNumber. Located on the Floor.
Entry SensorThingPEOPLE_COUNT_SENSOR_EQUIPMENTA doorway sensor that counts people going in and out of one or more spaces. One device per active entry sensor on a mapped floor, named XY Sense Entry Sensor followed by its installation name or the names of its entries. Its MAC address is the serialNumber, and isVirtual is set for XY Sense virtual entry sensors. Located in each mapped space its entries lead into, or on the Floor when none of them is mapped.
Sensor connectionHeartbeat—Whether XY Sense sees the area or entry sensor online (see Heartbeats). Virtual entry sensors have none.

Note: IAQ points are discovered at provision time. A sensor only gets points for capabilities its model can measure, as listed by XY Sense for each sensor model. For example, a Milesight NE203 presence sensor gets Temperature and Humidity, not CO₂ or particulate matter. Capabilities marked as "ignored" in the XY Sense configuration are also excluded: at installation level they apply to all of the sensor's points, and at floor-space level they apply to what the sensor measures for that space. Points that are no longer provisioned are detached from their device on the next sync.

Note: Earlier versions put the air quality points on one virtual XY Sense IAQ Sensor device per space. The first sync on this version moves each of those points to a sensor in the space that measures it; the point keeps its Mapped ID and its history. Other sensors in the same space get new points. The space devices are left with no points, and the Clean Up Unused Entities job deletes them (see Reports and Cleanup).

Relationship summary:

  • The Space is part of the Floor/Building place hierarchy (managed by place mappings).
  • The OccupancyZone is a part of the Space (isPartOf).
  • The OccupancySensingDevice serves the OccupancyZone (serves) and is located in the Space (hasLocation).
  • Both occupancy Points are attached to the OccupancySensingDevice (hasPoint) and the OccupancyZone (hasPoint).
  • Each physical sensor's device is located in every Space the sensor serves (hasLocation).
  • IAQ Points are attached to the device of the sensor that measures them (hasPoint).
  • When Materialize Sensor Health is on, the sensor's Battery Level Sensor and Signal Strength Sensor points are attached to its device too (hasPoint).
  • When Materialize Sensor Occupancy is on, each presence sensor's device also has its own Occupancy Sensor point (hasPoint).
  • When Materialize Area And Entry Sensors is on, each area sensor's device is located on its Floor (hasLocation). Each entry sensor's device is located in the mapped Spaces its entries lead into, or on its Floor (hasLocation). Both have a Heartbeat (hasHeartbeat).

Time Series Points​

Occupancy Points

XY Sense Event FieldMapped Point exactTypeDatatypeUnitDescription
OccupancyStatusOCCUPANCY_SENSORDOUBLENUMBinary occupancy indicator. 0 = CurrentlyOccupied, 1 = NotOccupied. The valueMap field provides human-readable labels. stateTexts: ["CurrentlyOccupied", "NotOccupied"].
HeadcountOCCUPANCY_COUNT_SENSORDOUBLENUMCurrent number of occupants detected in the space.

Occupancy events are sourced from XY Sense OccupancyChanges webhooks. The timestamp for the occupancy status point comes from OccupancyStatusChangeDate, and the headcount point timestamp comes from CollectedDate.

IAQ Points

Each point belongs to the device of one physical sensor, so readings from different sensors serving the same space are never combined.

XY Sense CapabilityMapped Point exactTypeDatatypeUnitDescription
TemperatureTEMPERATURE_SENSORDOUBLEDEG_CAmbient temperature in degrees Celsius
HumidityHUMIDITY_SENSORDOUBLEPERCENTRelative humidity percentage
Ambient LightILLUMINANCE_SENSORDOUBLELUXAmbient illuminance in lux
Relative LightILLUMINANCE_SENSORDOUBLEPERCENTRelative light level as a percentage
Ambient NoiseSOUND_PRESSURE_LEVEL_SENSORDOUBLEDeciBSound pressure level in decibels
Sound PressureSOUND_PRESSURE_LEVEL_SENSORDOUBLEPASound pressure in pascals, for sensor models that report it in pascals rather than decibels
Barometric PressureABSOLUTE_BAROMETRIC_PRESSURE_SENSORDOUBLEHectoPAAbsolute barometric pressure measured at the sensor, in hectopascals
Carbon DioxideCO2_LEVEL_SENSORDOUBLEPPMCO₂ concentration in parts per million
Volatile Organic CompoundsTVOC_LEVEL_SENSORDOUBLEPPBTotal volatile organic compound concentration in parts per billion
Particulate Matter 1PM_1_LEVEL_SENSORDOUBLEMicroGM-PER-M3PM1 particulate matter in µg/m³
Particulate Matter 2.5PM_2_5_LEVEL_SENSORDOUBLEMicroGM-PER-M3PM2.5 particulate matter in µg/m³
Particulate Matter 10PM_10_LEVEL_SENSORDOUBLEMicroGM-PER-M3PM10 particulate matter in µg/m³

Sensor Health Points

Created only when Materialize Sensor Health is on (see Advanced Options). Like the IAQ points, they belong to the device of one physical sensor.

XY Sense CapabilityMapped Point exactTypeDatatypeUnitDescription
Battery PercentageBATTERY_LEVEL_SENSORDOUBLEPERCENTRemaining battery of the sensor
Signal StrengthCOMMUNICATION_SIGNAL_STRENGTH_SENSORDOUBLEDeciB_MRadio signal strength received from the sensor, in dBm

Presence Sensor Points

Created only when Materialize Sensor Occupancy is on, for sensor models that XY Sense lists as able to detect occupancy. Like the IAQ points, each belongs to the device of one physical sensor.

XY Sense CapabilityMapped Point exactTypeDatatypeUnitDescription
OccupancyOCCUPANCY_SENSORENUMNUMWhat one presence sensor detects. 0 = CurrentlyOccupied, 1 = NotOccupied, the same values as the space's own occupancy point. Presence sensors report about every 10 minutes and again whenever their state changes.

IAQ, sensor health and presence sensor readings are sourced from XY Sense SpaceSensorReadings webhooks. Each reading carries a CollectedAt timestamp indicating when the measurement was taken by the sensor.

Heartbeats​

Area and entry sensor devices have a Thing-level Heartbeat when Materialize Area And Entry Sensors is on. Every hour the connector asks XY Sense whether each sensor is online and records the answer:

ValueMeaningContext
0 (OK)XY Sense sees the sensor online—
1 (NOT_OK)XY Sense reports the sensor offline{ "connection": "OFFLINE", "offlineSince": "<when XY Sense saw it go offline>" }

Area and entry sensors installed after the connector last started get their device and heartbeat when it next restarts. Virtual entry sensors have no hardware and no heartbeat. Space sensors (air quality and presence) do not have heartbeats; their readings show when they last reported.

Sample Code​

Query all spaces with their occupancy and IAQ devices

{
spaces(filter:{connectedDataSourceId:{eq:"your-connector-Id"}}) {
id
name
exactType
id
name
maxOccupancy
exactType
isLocationOf {
... on Thing {
id
name
exactType
isVirtual
serves {
... on Zone {
id
name
exactType
}
}
hasPoint {
id
name
exactType
datatype
unit {
id
}
}
}
}
}
}

Query occupancy zones with their points and latest time series

{
zones(filter: { connectedDataSourceId: { eq: "your-connector-Id" } }) {
id
name
exactType
isServedBy {
id
name
exactType
isVirtual
}
hasPoint {
id
name
exactType
datatype
unit {
id
}
series(latest:true) {
value {
int64Value
}
timestamp
ingestionTime
}
}
}
}

Query air quality sensors with their points and latest time series

{
things(filter: { connectedDataSourceId: { eq: "CONY6QnVTHmicqhVKtwcVrpWe" },
and: { exactType: {eq: "Air_Quality_Sensing_Device"}} }) {
id
name
exactType
isVirtual
hasLocation {
... on Space {
id
name
}
}
hasPoint {
id
name
exactType
datatype
unit {
id
}
series(latest:true) {
value {
float64Value
}
timestamp
ingestionTime
}
}
}
}

Graph Diagrams​

Occupancy​

IAQ​

One device per physical sensor; the diagram shows an air quality monitor with some of its points. Battery_Level_Sensor and Communication_Signal_Strength_Sensor are only there when Materialize Sensor Health is on.

A physical sensor's device is an Air_Quality_Sensing_Device for air quality monitors, an Occupancy_Sensing_Device for presence sensors, and a Device otherwise.

Changelog​

2026-11-06​

  • Changed: Air quality points (temperature, humidity, CO₂ and the rest) now belong to the device of the physical XY Sense sensor that measures them, instead of one virtual XY Sense IAQ Sensor device per space. Every sensor serving a mapped space gets a device. On the first sync, each existing space point moves to a sensor that measures it and keeps its Mapped ID and history; other sensors in the same space get new points.
  • Added: A Reports section with Device Point Mapping, listing each space point and the sensor point that replaces it, and Cleanup Preview, listing what the Clean Up Unused Entities job deletes. Both export to CSV.
  • Changed: Clean Up Unused Entities now also deletes the space XY Sense IAQ Sensor devices, and the space points that did not move to a sensor.

2026-11-05​

  • Added: Optional devices for XY Sense area sensors (located on their Floor) and entry sensors (located in the spaces they count for), with an hourly Heartbeat showing whether each sensor is online. Off by default; turn on Materialize Area And Entry Sensors under Advanced Config.
  • Added: Optional Occupancy Sensor point for each presence sensor, such as the Milesight NE203, on a device for that sensor. Off by default; turn on Materialize Sensor Occupancy under Advanced Config.
  • Fixed: Spaces whose sensors measure no air quality (for example presence-only sensors) no longer get an empty Air Quality Sensing Device.
  • Fixed: Large sites no longer get stuck re-trying the sync before any devices or points are updated.
  • Added: Optional Battery Level and Signal Strength points, on a device for each physical sensor. Off by default; turn on Materialize Sensor Health under Advanced Config.
  • Fixed: Each Occupancy Zone is now part of its Space (isPartOf), instead of the Space being recorded as part of the zone. The old relationship is removed on the next sync.

2026-11-04​

  • Fixed: Spaces only get air quality points their installed XY Sense sensors can measure. Presence sensors such as the Milesight NE203 no longer show CO₂, TVOC, particulate matter, light, noise and pressure points that never receive data, and those points are detached from existing devices on the next sync.
  • Added: Spaces with sensors that report Sound Pressure (in pascals) get a Sound Pressure Sensor point.
  • Fixed: TVOC points now report in ppb, matching XY Sense, instead of µg/m³.
  • Fixed: Barometric Pressure points are now typed as absolute barometric pressure in hPa instead of sea-level pressure in mbar.