Overview

Every claimed Device lives in a single Space within an End Customer's Space tree. Spaces carry their own configuration (location, timezone, maintenance state, etc.), and Devices can read this configuration to deliver a richer End Customer experience.

Space information

Use the Get Space Info API to fetch the Space's configuration. The set of fields is growing over time; the values shown below are returned when the End Customer has configured them on the Space (or inherited them from a parent Space):

{
    "location": {
        "coordinates": {
            "lat": 51.165691,
            "lng": 10.451526
        },
        "utc_offset": 60,
        "name": "Germany"
    },
    "temperature_units": "celsius",
    "maintenance": false,
    "name": "Interactive Class",
    "local_time": "2024-03-17T10:55:28+01:00"
}

The Space configuration currently exposes:

1. Geographical location.
2. Timezone and current local time.
3. Preferred temperature unit.
4. Maintenance state.
5. Space name.

Detecting space changes

Spaces and Device-to-Space assignments change over time. Xyte signals these changes through the space_data_version counter on the Send Telemetry API response.

The server increments space_data_version whenever the Space the Device belongs to is modified, or when the Device is moved to a different Space. The Device persists the last-seen value and compares it to the value in each Telemetry response. When the server's value is higher, call Get Space Info API to refresh.

Daylight saving time

location.utc_offset follows daylight saving time: it is the offset in effect at the moment the Space is read, not the zone's standard-time offset, so it changes at each DST transition. Xyte bumps space_data_version shortly after a transition (and MQTT Devices receive a fresh space_info event), but only on a best-effort basis — typically within about 30 minutes, and not guaranteed for every Space.

Do not cache utc_offset (or anything derived from it) until the next version bump. Re-read the Space when space_data_version changes and periodically, at least daily. An MQTT Device refreshes by publishing to v1/device/DEVICE_ID/get, which republishes the latest space_info.

A space_data_version of 0 means the Device has not been claimed by any End Customer yet. See Claiming Overview.