Aqara Cube T1 Pro (CTP-R01): Full Setup in Home Assistant via Zigbee2MQTT
The Cube T1 Pro is Aqara’s most unusual device: a physical cube that maps gestures to Home Assistant automations. Rotating it dims your lights, flipping it 90 degrees switches a scene, tossing it triggers an action. It’s useful as a bedside controller or a desk shortcut pad, and it runs entirely over Zigbee, which means once it’s paired to Zigbee2MQTT, there’s no Aqara cloud involved at all.
What trips people up is the mode system. The Cube T1 Pro has two distinct operation modes (scene mode and action mode), each with a different gesture set, and switching between them isn’t instant. Get that wrong and half your automations simply won’t fire.
This guide covers hub-free pairing via Zigbee2MQTT, the mode distinction in practical terms, what entities Z2M exposes, and how to build automations in Home Assistant that actually work. It also explains why ZHA users see only a subset of gestures and what to do about it.
What the Aqara Cube T1 Pro is (and isn’t)
The model number you want is CTP-R01. If you’re looking at older forum posts or Zigbee2MQTT discussions and something doesn’t match, check the model — Aqara also makes a first-generation cube with model number MFKZQ01LM. These are different devices with separate Z2M device pages and different supported action sets. Everything in this guide applies to the CTP-R01 only.
Hardware specifics: the Cube T1 Pro uses Zigbee 3.0, runs on a single CR2450 coin cell (user-replaceable), and is a 45mm cube with six faces. Inside the box you get the cube, a back plate removal tool (looks like a small plastic pry), and a CR2450 battery already installed.
The device ships in scene mode by default. That matters because the two modes detect different gestures, and choosing the wrong one for your use case is the most common source of “missing actions” complaints.
Do you need an Aqara hub?
No. The Cube T1 Pro is a standard Zigbee 3.0 device. It pairs directly to any compatible Zigbee coordinator (CC2652P, Sonoff Zigbee 3.0 USB Dongle Plus, or similar) running Zigbee2MQTT.
The Aqara Hub M2 is the vendor’s intended path and routes events through Aqara’s cloud. Skip it. When the cube is paired directly to Z2M, all communication stays on your local Zigbee network. The device has no IP address, no Wi-Fi radio, and makes no outbound connections. From a network perspective, it doesn’t exist beyond the Zigbee RF layer.
The Aqara Home app is irrelevant once you’re on this path — you won’t need it to configure or control the cube.
What you’ll need
- A Zigbee coordinator supported by Zigbee2MQTT (CC2652P, Sonoff Dongle-E, or equivalent)
- Zigbee2MQTT running and accessible — ideally as a Home Assistant add-on, though standalone works too
- The Aqara Cube T1 Pro (CTP-R01) with battery installed
- The plastic back plate removal tool (included in box)
- Home Assistant with the Zigbee2MQTT integration configured
If you’re setting up a Zigbee coordinator for the first time, the pairing steps here assume Z2M is already running and you can access its dashboard.
Pairing the Cube T1 Pro to Zigbee2MQTT
1. Enable permit join in Zigbee2MQTT
In the Z2M dashboard, click Permit join, either globally or on the specific coordinator. You have 255 seconds by default.
2. Open the cube’s back plate
Use the included plastic pry tool to lift the back plate off. The slot is along one edge; lever gently. You’ll see the CR2450 battery and the LINK button.
3. Trigger pairing mode
Press and hold the LINK button for approximately 5 seconds. The LED will blink blue three times. That’s the signal that pairing mode is active.
4. Keep the device awake during the interview
This is where most pairing failures happen. The cube is a battery-powered device that sleeps aggressively. While Z2M is interviewing it (querying endpoints, clusters, device descriptor), you need to periodically press the LINK button to wake it. Press it every few seconds until Z2M reports the interview complete.
What success looks like: in the Z2M dashboard, the device appears with the name “Aqara Cube T1 Pro” and model CTP-R01. You’ll see a cluster of entities populate — battery percentage, operation mode, action, and others.
Note: Battery percentage may show as unavailable or 0% for up to 24 hours after first pairing. This is normal — the device sends its first battery report on its own schedule, not during the initial interview.
5. Confirm the entities
Once paired, go to Home Assistant → Devices → search for your cube. You should see these entities (among others):
- Battery — percentage; slow to update, check back after 24 hours
- Operation mode — scene_mode or action_mode
- Cube side — which of the six numbered faces is currently up
- Action — the string describing the last detected gesture
- Rotation angle — degrees rotated (for rotation gestures)
- Action from side / Action to side — which face triggered and which it transitioned to
- Power outage count — diagnostic; useful for spotting battery drops
Scene mode vs. action mode: which should you use?
This is the most important configuration decision for the Cube T1 Pro, and it’s easy to get wrong.
Scene mode (the default)
Scene mode detects: side placement (placing a specific face down), rotation, shake, throw, hold, and one-minute inactivity.
If you want a 6-scene controller (face 1 means “movie mode,” face 2 means “reading mode,” face 3 means “off,” and so on) scene mode is the right choice. The face-down detection is reliable and the gesture set is simple to reason about.
Action mode
Action mode detects: rotation, shake, throw, slide, tap, 90-degree flip, 180-degree flip, and one-minute inactivity.
If you want more granular triggers (rotate right to raise brightness, tap to toggle, flip 90 to switch scenes) action mode gives you a richer set of distinct gestures. You lose the face-placement detection but gain the flip and tap actions.
Neither mode is strictly better. Scene mode suits “which state am I in?” use cases; action mode suits “what action did I just do?” use cases.
Switching operation modes
You change the mode by publishing an MQTT message to the device’s Z2M set topic:
Topic: zigbee2mqtt/<device_friendly_name>/set
Payload: {"operation_mode": "action_mode"}
Or to revert:
Topic: zigbee2mqtt/<device_friendly_name>/set
Payload: {"operation_mode": "scene_mode"}
Replace <device_friendly_name> with whatever you named the device in Z2M — typically aqara_cube_t1_pro or similar.
The one-hour response window. The cube doesn’t accept mode change commands immediately at all times. It only acts on them during a one-hour window that opens when the device wakes up and refreshes its configuration. Outside that window, the command sits there and does nothing.
Two ways to force the device into the window immediately:
- Throw gesture. Give the cube a forceful forward push without a backward flick. Z2M calls this
throw. This wakes the device and opens the configuration window. Publish the mode change command within the next few minutes. - LINK button × 5. Press the LINK button five times in quick succession. This toggles the mode via a hardware path directly, bypassing the MQTT window entirely.
If you publish the mode command and nothing happens, try option 2. The LINK × 5 method is more reliable when you want an immediate mode switch without waiting for the window to open naturally.
Building automations in Home Assistant
The cube’s action entity is a state entity that changes value each time a gesture fires. Automations trigger on state changes to this entity.
Trigger on a specific action
In the Home Assistant automation editor, use a State trigger:
- Entity: your cube’s
actionsensor - From: (leave blank — any previous state)
- To: the specific action string you want (e.g.,
rotate_right,shake,flip_to_side_5)
The full list of action strings depends on which mode the device is in. The Zigbee2MQTT device page for the CTP-R01 lists all valid action values for both modes.
Example: rotation controlling brightness
automation:
- alias: "Cube rotate right - raise brightness"
trigger:
- platform: state
entity_id: sensor.aqara_cube_t1_pro_action
to: "rotate_right"
action:
- service: light.turn_on
target:
area_id: living_room
data:
brightness_step_pct: 10
For finer control, the rotation_angle entity gives you the actual degrees rotated — useful for mapping rotation magnitude to brightness delta rather than a fixed step.
The SirGoodenough blueprint
If you’d rather not build individual automations from scratch, the SirGoodenough community blueprint is a commonly referenced starting point. It handles all action strings for both modes via a single automation, uses MQTT directly so it works regardless of whether you have Z2M legacy triggers enabled, and is actively maintained — the version published on the HA Blueprint Hub is dated 2025-04-19. It’s a YAML import, not an official integration, so treat the YAML as a reference pattern and review it before importing.
ZHA vs. Zigbee2MQTT: which bridge handles the T1 Pro better?
If you’re already running ZHA and wondering whether to switch: yes, for this specific device, it matters.
ZHA pairs the Cube T1 Pro and it appears in Home Assistant, but the event coverage is limited. ZHA’s device handler for the CTP-R01 only reliably fires events for rotate left, rotate right, and shake. The flip, tap, slide, and throw actions don’t generate events. This was filed against Home Assistant core as issue #84301 back in December 2022 and was eventually closed as “not planned” — the gap is a quirk of how the CTP-R01 reports its action cluster to ZHA, and as of 2025 it remains the practical state of things.
Zigbee2MQTT exposes the full action set. If you’re using the Cube T1 Pro as a multi-gesture controller and want more than three reliable trigger types, Z2M is the practical choice.
If you’re committed to ZHA for other reasons, the device still works for shake-and-rotate use cases. Just don’t plan automations around flip or tap — they won’t fire.
This pattern (Z2M providing materially better event coverage than ZHA for certain Aqara sensors) shows up on a few other devices too, so it’s worth weighing across your whole device list before picking a bridge.
Troubleshooting
Only getting shake and rotate events, nothing else
Two likely causes: the device is in scene mode when you expected action mode, or you’re on ZHA rather than Z2M.
Check the operation_mode entity in Home Assistant — it will read scene_mode or action_mode. If you’re on Z2M and the mode is correct but actions still don’t fire, try the LINK × 5 hardware toggle to confirm the mode actually changed.
If you’re on ZHA, see the section above — that’s expected behavior, not a configuration problem.
Mode switch command not taking effect
You published the MQTT command but the operation_mode entity didn’t change. The device is not in its one-hour response window. Throw the cube (forceful forward push) or press LINK five times. Then republish the mode command.
Device not pairing
The interview is timing out because the cube went to sleep between presses. Restart the pairing attempt and press the LINK button every 2-3 seconds throughout the interview — more frequently than feels necessary. The interview typically takes 20-40 seconds.
If pairing still fails after several attempts, move the cube closer to the coordinator or a router device.
Battery shows 0% or unavailable
Normal after first pairing. The device sends battery reports on its own reporting interval, not during the initial interview. Check back after 24 hours.
Actions fire twice
This typically indicates duplicate automations: the same action entity is triggering two overlapping automation rules. Check your automation list for duplicates with similar triggers. It can also happen if you have both a state trigger and an event trigger targeting the same action string.
Frequently asked questions
Does the Aqara Cube T1 Pro work without an Aqara hub?
Yes. It’s a standard Zigbee 3.0 device that pairs directly to any compatible Zigbee coordinator. No Aqara hub, no Aqara account, and no cloud connection is needed when using it with Zigbee2MQTT.
What is the difference between scene mode and action mode on the Aqara Cube T1 Pro?
Scene mode detects face placement, rotation, shake, throw, and hold — suited for 6-scene setups where you’re placing the cube a certain way to select a state. Action mode detects rotation, shake, throw, slide, tap, and flip (90 and 180 degrees) — suited for action-triggered automations with more distinct gesture types.
Why is my Aqara Cube T1 Pro only firing shake and rotate events?
Two possible causes. First, you may be using ZHA, which has a device handler limitation that only exposes three event types for the CTP-R01. Switch to Zigbee2MQTT for full event coverage. Second, you may be in scene mode but expecting action mode gesture types — check your operation_mode entity.
How do I change the operation mode on the Aqara Cube T1 Pro in Zigbee2MQTT?
Publish {"operation_mode": "action_mode"} or {"operation_mode": "scene_mode"} to zigbee2mqtt/<device_name>/set. The device must be in its one-hour response window to accept the command — trigger this with a throw gesture or five rapid LINK button presses.
Does the Aqara Cube T1 Pro send data to the cloud when used with Zigbee2MQTT?
No. The device communicates exclusively over Zigbee RF. When paired to Zigbee2MQTT without an Aqara hub, it has no network presence — no IP address, no Wi-Fi, no outbound connections. Cloud traffic only becomes relevant when using an Aqara hub as the bridge, which this setup intentionally avoids.
Once paired and set to the right mode, the Cube T1 Pro is one of the more reliable physical controllers you can add to a Home Assistant setup. The gesture recognition is consistent, the battery life is long on a single CR2450, and the full action set available via Z2M gives you enough distinct inputs to replace a lot of voice-command or app-tap workflows with something tactile. The mode quirk and the one-hour window are the only real friction points, and now you know how both work.
