Sensibo (Sky / Air / Pure / Elements)

Cloud REST integration for Sensibo pods — universal Wi-Fi retrofit controllers for IR-only air conditioners (ductless mini-splits, window units, PTACs, portables). One Sensibo account becomes one GEM device row; each commissioned pod becomes a zone, addressed by its 8-character Sensibo pod id.

What this integration covers

• Power on / off for every IR-equipped Sensibo pod (Sky, Air, Air Pro).
• Setpoint in °C or °F per zone — integer values only (Sensibo does not accept fractional setpoints).
• Operation mode — cool / heat / fan / dry / auto. Per-unit support varies; check pod.remoteCapabilities.modes via get_status.
• Fan speed — auto, quiet, low, medium_low, medium, medium_high, high, strong. Universal subset is auto / low / medium / high.
• Swing — stopped, rangeFull, rangeTop, rangeMiddle, rangeBottom, fixedTop, fixedMiddleTop, fixedMiddle, fixedMiddleBottom, fixedBottom. Most ACs collapse to stopped vs rangeFull.
• Room temperature + humidity from the pod's onboard sensors, polled on a configurable cadence (default 60 s).

What this integration does NOT cover (yet)

• Sensibo Pure (air-quality pod) and Sensibo Elements (standalone air-quality sensor) — these have no IR transmitter. They appear in get_devices but the driver returns {error: "pod is read-only"} for any write. Air-quality measurement polling is not yet wired.
• Climate React smart-trigger schedules — managed in the Sensibo app, not from GEM.
• Geofencing. Done in the Sensibo app.
• Multi-account aggregation in one device row. Each Sensibo account is one GEM device.

Prerequisites

• A Sensibo account at https://home.sensibo.com (free) with at least one pod commissioned via the Sensibo mobile app.
• An API key minted under Account → API in the Sensibo web dashboard. The Sensibo mobile app does NOT generate API keys — it is web-only.
• Outbound HTTPS reachability from the GEM controller to home.sensibo.com.

Setup steps

1. Commission each Sensibo pod via the Sensibo mobile app — this driver does not handle Wi-Fi onboarding.
2. Sign in at https://home.sensibo.com → Account → API → Create API key. Copy the key; the dashboard only shows it once.
3. In GEM admin → Devices → New Device, pick Sensibo (Sky / Air / Pure / Elements) as the driver.
4. Paste the API key into the api_key attribute (stored encrypted at rest).
5. Save. After ~5 seconds the device should show as connected.
6. Run the get_devices command — each entry shows the 8-character pod id and the room name configured in the Sensibo app.
7. For each AC you want to control, create a zone in the climate subsystem with address = "<podId>" (e.g. AbCdEfGh).
8. (Optional) Set zone.temperature_unit to C or F to match what the Sensibo app shows for that pod. Defaults to the pod's app-side unit.

Attribute reference

Device attributes

Name	Type	Required	Description
api_key	string	yes	Generated at https://home.sensibo.com → Account → API. Stored encrypted.
api_base	string	no	Override the Sensibo API root. Leave empty unless directed by support.
status_interval	int	no	Poll cadence in ms (default 60000, minimum 15000).
request_timeout	int	no	Per-request timeout (default 15000 ms).

Zone attributes

Name	Type	Description
address	string	Sensibo pod id (required). 8 alphanumeric characters.
temperature_unit	string	C or F. Optional override of the app-configured unit.
state	string	Maintained by the driver: on / off.
system_mode	string	cool / heat / fan / dry / auto.
setpoint	number	acState.targetTemperature from the cloud.
temperature	number	Pod's onboard ambient sensor (measurements.temperature).
humidity	number	Pod's onboard humidity sensor (measurements.humidity).
fan_mode	string	Last commanded fan level.

Zone address format

A single 8-character alphanumeric pod id — e.g. AbCdEfGh. Run get_devices after the first connect to enumerate every pod on the account.

Commands

Command	Args	Notes
on / off	address	Power.
set_temperature	address, value	Integer setpoint in the unit set on the zone.
set_mode	address, mode	cool / heat / fan / dry / auto.
set_fan_mode	address, value	auto / quiet / low / medium_low / medium / medium_high / high / strong.
set_swing	address, value	stopped / rangeFull / rangeTop / rangeMiddle / rangeBottom / fixedTop / fixedMiddleTop / fixedMiddle / fixedMiddleBottom / fixedBottom.
get_devices	—	Enumerate every pod on the account.
get_status	optional address	Read live acState + measurements for one zone, or all zones if omitted.

Known limitations

• One-way IR. The pod transmits but cannot read the AC's display, so the state surfaced to GEM is what the pod last commanded — not what the unit is physically doing. A tap on the AC's own remote desyncs until the next Sensibo app refresh.
• Sensor placement. Room temperature comes from the pod itself, which is in the supply-air path under the indoor unit. Expect a ~5°F bias colder than room ambient while the AC is actively cooling.
• Rate limits. Sensibo allows roughly 600 requests/hour per API key. With more than 10 pods on a 15-second poll you will hit the limit; the driver back-pressures with a 150 ms per-zone delay, but tune status_interval upward if HTTP 429s appear in the logs.
• Integer setpoints only. Sensibo's cloud rejects fractional targetTemperature values; the driver rounds before sending.

Troubleshooting

• auth rejected (HTTP 401) — wrong or revoked API key. Re-mint at https://home.sensibo.com → Account → API and update the api_key attribute.
• auth rejected (HTTP 403) — the API key is valid but lacks access to this account. Make sure the key is from the account that owns the pods.
• rate-limited (HTTP 429) — too many requests. Raise status_interval (try 120000 = 2 min) or reduce pod count on one key.
• Zone never updates — make sure zone.address is the 8-character pod id from get_devices, not the room name.
• pod is read-only on every write — the pod is a Sensibo Pure or Elements, which has no IR transmitter. Use a Sky / Air pod for AC control.
• Setpoint snaps back to the previous value — the AC unit rejected the IR command. Some splits silently ignore setpoints outside their range; check the AC's own minimum / maximum.