XY Sense

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 virtual devices mapped to each 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.

Field	Required	Description
Api Key Name	Yes	The name of the API key issued by XY Sense. Found in the XY Sense admin portal under API key management.
Api Secret	Yes	The 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.

Field	Required	Unique	Description
building.name	Yes	—	Name of the building (auto-populated from XY Sense location name)
building.address	Yes	—	Address of the building (auto-populated from XY Sense location address)
floor.name	Yes	—	Name of the floor (auto-populated from XY Sense floor name)
floor.level	Yes	—	Numeric floor level (auto-derived from floor name, e.g. "Level 3" → level 2, zero-indexed)
space.name	Yes	—	Name of the space (auto-populated from XY Sense floor space name)
space.code	No	—	Optional space code identifier
space.refId	Yes	Yes	Unique XY Sense floor space ID used to link webhook events to mapped spaces

Mapped Concepts

API to Mapped Entities

Occupancy Entities

XY Sense Concept	Mapped Entity Type	exactType	Description
Location (Building)	Building	—	Created by place mapping; the building containing the floor spaces
Floor	Floor	—	Created by place mapping; the floor within the building
Floor Space	Space	—	Created by place mapping; the physical space being monitored. Carries maxOccupancy from the XY Sense capacity value.
— (virtual)	Zone	OCCUPANCY_ZONE	An occupancy zone created as a child of the Space (hasPart). Groups the occupancy sensing device and its points.
— (virtual)	Thing	OCCUPANCY_SENSING_DEVICE	A virtual occupancy sensing device that serves the zone and is located in the space.
Occupancy Status	Point	OCCUPANCY_SENSOR	Binary occupancy status point — 0 = CurrentlyOccupied, 1 = NotOccupied
Headcount	Point	OCCUPANCY_COUNT_SENSOR	Numeric headcount point — current number of occupants in the space

IAQ (Air Quality) Entities

XY Sense Concept	Mapped Entity Type	exactType	Description
Floor Space with sensors	Thing	AIR_QUALITY_SENSING_DEVICE	A virtual air quality sensing device for each mapped space that has sensor installations. Located in and serves the Space. Holds one point per environmental capability its sensors support.
Space Sensor	Thing	AIR_QUALITY_SENSING_DEVICE, OCCUPANCY_SENSING_DEVICE or DEVICE	One device per physical sensor serving a mapped space, typed by its hardware (air quality monitor, presence sensor, or other). Named after the sensor model, with the sensor's hardware id as serialNumber. Located in each Space it serves. Holds the sensor's battery and signal points.
Temperature	Point	TEMPERATURE_SENSOR	Ambient temperature reading
Humidity	Point	HUMIDITY_SENSOR	Relative humidity reading
Ambient Light	Point	ILLUMINANCE_SENSOR	Ambient light level in lux
Relative Light	Point	ILLUMINANCE_SENSOR	Relative light level as percentage
Ambient Noise	Point	SOUND_PRESSURE_LEVEL_SENSOR	Ambient noise level in decibels
Sound Pressure	Point	SOUND_PRESSURE_LEVEL_SENSOR	Sound pressure in pascals
Barometric Pressure	Point	ABSOLUTE_BAROMETRIC_PRESSURE_SENSOR	Barometric pressure reading
Carbon Dioxide	Point	CO2_LEVEL_SENSOR	CO₂ concentration in parts per million
Volatile Organic Compounds	Point	TVOC_LEVEL_SENSOR	Total volatile organic compound concentration
Particulate Matter 1	Point	PM_1_LEVEL_SENSOR	PM1 particulate matter concentration
Particulate Matter 2.5	Point	PM_2_5_LEVEL_SENSOR	PM2.5 particulate matter concentration
Particulate Matter 10	Point	PM_10_LEVEL_SENSOR	PM10 particulate matter concentration
Battery Percentage	Point	BATTERY_LEVEL_SENSOR	Remaining battery of one physical sensor
Signal Strength	Point	COMMUNICATION_SIGNAL_STRENGTH_SENSOR	Radio signal strength of one physical sensor

Note: IAQ points are discovered at provision time. A space only gets points for capabilities its installed sensor models can measure, as listed by XY Sense for each sensor model. For example, a space with only 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 installation's points, and at floor-space level they apply to that space's points. If a space's sensors support no environmental capability, its air quality device has no points. Points that are no longer provisioned are detached from their device on the next sync.

Relationship summary:

• The Space is part of the Floor/Building place hierarchy (managed by place mappings).
• The OccupancyZone is a part of the Space (hasPart).
• 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).
• The AirQualitySensingDevice serves and is located in the Space (serves, hasLocation).
• IAQ Points are attached to the AirQualitySensingDevice (hasPoint).
• Each physical sensor's device is located in every Space the sensor serves (hasLocation), and its Battery Level Sensor and Signal Strength Sensor points are attached to it (hasPoint).

Time Series Points

Occupancy Points

XY Sense Event Field	Mapped Point exactType	Datatype	Unit	Description
OccupancyStatus	OCCUPANCY_SENSOR	DOUBLE	NUM	Binary occupancy indicator. 0 = CurrentlyOccupied, 1 = NotOccupied. The valueMap field provides human-readable labels. stateTexts: ["CurrentlyOccupied", "NotOccupied"].
Headcount	OCCUPANCY_COUNT_SENSOR	DOUBLE	NUM	Current 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

XY Sense Capability	Mapped Point exactType	Datatype	Unit	Description
Temperature	TEMPERATURE_SENSOR	DOUBLE	DEG_C	Ambient temperature in degrees Celsius
Humidity	HUMIDITY_SENSOR	DOUBLE	PERCENT	Relative humidity percentage
Ambient Light	ILLUMINANCE_SENSOR	DOUBLE	LUX	Ambient illuminance in lux
Relative Light	ILLUMINANCE_SENSOR	DOUBLE	PERCENT	Relative light level as a percentage
Ambient Noise	SOUND_PRESSURE_LEVEL_SENSOR	DOUBLE	DeciB	Sound pressure level in decibels
Sound Pressure	SOUND_PRESSURE_LEVEL_SENSOR	DOUBLE	PA	Sound pressure in pascals, for sensor models that report it in pascals rather than decibels
Barometric Pressure	ABSOLUTE_BAROMETRIC_PRESSURE_SENSOR	DOUBLE	HectoPA	Absolute barometric pressure measured at the sensor, in hectopascals
Carbon Dioxide	CO2_LEVEL_SENSOR	DOUBLE	PPM	CO₂ concentration in parts per million
Volatile Organic Compounds	TVOC_LEVEL_SENSOR	DOUBLE	PPB	Total volatile organic compound concentration in parts per billion
Particulate Matter 1	PM_1_LEVEL_SENSOR	DOUBLE	MicroGM-PER-M3	PM1 particulate matter in µg/m³
Particulate Matter 2.5	PM_2_5_LEVEL_SENSOR	DOUBLE	MicroGM-PER-M3	PM2.5 particulate matter in µg/m³
Particulate Matter 10	PM_10_LEVEL_SENSOR	DOUBLE	MicroGM-PER-M3	PM10 particulate matter in µg/m³

Sensor Health Points

These points belong to the device of one physical sensor, so readings from different sensors serving the same space are never combined.

XY Sense Capability	Mapped Point exactType	Datatype	Unit	Description
Battery Percentage	BATTERY_LEVEL_SENSOR	DOUBLE	PERCENT	Remaining battery of the sensor
Signal Strength	COMMUNICATION_SIGNAL_STRENGTH_SENSOR	DOUBLE	DeciB_M	Radio signal strength received from the sensor, in dBm

IAQ and sensor health events are sourced from XY Sense SpaceSensorReadings webhooks. Each reading carries a CollectedAt timestamp indicating when the measurement was taken by the sensor. Occupancy readings are covered by the occupancy points above.

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 IAQ devices with their sensor 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

Sensor Health

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-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: Each physical sensor appears as its own device with Battery Level and Signal Strength points.
• 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.