Aqara Cube T1 Pro: Home Assistant Automations via Zigbee2MQTT
The Aqara Cube T1 Pro is one of the most action-dense physical controllers you can put on a coffee table. One device, one hand, and you get 58+ distinct gestures — shake, flip, rotate, tap, hold — each mappable to a different Home Assistant action. That’s a lot of leverage from a device the size of a golf ball.
The catch: out of the box, ZHA gives you an inconsistent experience. Some actions drop, some never register. Zigbee2MQTT (Z2M) solves this — it exposes the full action set reliably, and the device page documents every action by name so your YAML targets are explicit.
This guide covers everything after you buy the cube: pairing it to Z2M, choosing Action Mode vs Scene Mode, wiring up practical automations with working YAML, and a blueprint shortcut if you want pre-built triggers. There’s also a troubleshooting section for the two most common failure modes (lag and events not reaching HA).
What You Need
- Home Assistant — any recent release with the MQTT integration configured
- Zigbee2MQTT — running as an HA add-on or standalone; MQTT discovery enabled (
homeassistant: truein Z2M config) - Aqara Cube T1 Pro — sold as model CTP-R01 (international) or MFCZQ12LM (Chinese market). Same hardware, two SKU names.
- CR2450 battery — ships installed; check charge before pairing
- Optional: an HA Blueprint for cube actions (covered in the blueprint section below)
If you haven’t set up Zigbee2MQTT yet, get that running first.
Pairing the Cube T1 Pro to Zigbee2MQTT
Pairing is standard Zigbee — the only trick is finding the pairing button.
1. Enable Permit Join in Z2M.
In your Z2M dashboard, click the permit join toggle (the zigzag network icon) or enable it for a specific coordinator. Leave it open during pairing.
2. Find the LINK button.
Twist off the cube’s backplate (it unscrews from the bottom). The LINK button is on the internal PCB — small button near the battery slot.
3. Trigger pairing mode.
Hold the LINK button for 5 seconds until the LED blinks blue. Release. The cube is now advertising.
4. Watch Z2M for the interview.
Within 30–60 seconds, the device should appear in your Z2M dashboard. The model field should populate as CTP-R01. If it shows as unknown, let the interview complete (it runs several rounds) before concluding there’s a problem.
5. Rename the device.
In Z2M, rename it something memorable — cube_living_room, for example. This becomes part of the MQTT topic (zigbee2mqtt/cube_living_room) and HA entity names.
That’s all for pairing. The cube starts in Action Mode by default on most firmware versions.
Action Mode vs Scene Mode — Choose One First
Before writing any automations, you need to decide which mode you’re running. The two modes expose completely different behavior, and your automation YAML structure differs accordingly.
Action Mode (Recommended for HA Power Users)
In Action Mode, every gesture the cube detects fires a named action event. You get the full library:
shakehold_shaketap_twiceflip_to_side(with face number)flip_90/flip_180rotate_left/rotate_right(with degrees)1_min_inactivity- And more — the full list is on the Z2M device page for CTP-R01
Each action fires as a discrete event on the MQTT topic, which HA picks up via the action entity. You can trigger a different HA automation for each action — up to 58+ independent triggers from one device.
Best for: complex setups where you want many different gestures doing many different things. The learning curve is slightly higher (you need to know which action string matches which gesture), but it’s the most capable mode.
Scene Mode (Simpler, Six Actions)
In Scene Mode, the cube forgets gestures. Instead, it tracks which face is currently down. Flip the cube to a new face → fire the trigger for that face. Six faces = six distinct scenes/actions, maximum.
Scene Mode is dead-simple for a specific use case: mapping each side of the cube to a different HA scene or light preset. It’s less capable than Action Mode but takes five minutes to set up.
Best for: non-technical household members who just want “flip to this face = activate this scene.”
How to Switch Modes
Press the LINK button 5 times consecutively. The cube toggles between modes. Alternatively, switch via the Aqara Home app under Device Settings → More Settings → Mode Switching.
You can confirm which mode you’re in by triggering an action and watching what appears in Z2M’s “Exposes” tab — Scene Mode shows scene_number, Action Mode shows action.
Receiving Cube Actions in Home Assistant
Zigbee2MQTT exposes the cube’s action entity to HA automatically via MQTT discovery. You don’t need to write MQTT listeners manually.
In HA, navigate to Settings → Devices & Services → MQTT and find your cube device. You’ll see an entity named something like sensor.cube_living_room_action. This sensor’s state updates to the action string whenever a gesture fires, then resets to empty.
For automations, you have two paths:
Path 1: Device Triggers in the UI
Open Settings → Automations → Create Automation. Under “Trigger,” pick “Device.” Select your cube. You’ll see a list of device triggers — Z2M populates these from the action set. Pick an action (e.g., “shake”) and build from there. No YAML required for basic flows.
Path 2: YAML Automation (more control)
Use a state trigger on the action entity. This gives you full template access, conditional logic, and is easier to copy/paste across automations. Examples follow below.
Practical Automation Patterns
These are working YAML patterns. Replace cube_living_room with your device name, and replace entity IDs with your actual entities.
Shake → Toggle Living Room Lights
alias: "Cube: Shake → Toggle Living Room"
trigger:
- platform: state
entity_id: sensor.cube_living_room_action
to: "shake"
action:
- service: light.toggle
target:
entity_id: light.living_room_ceiling
mode: single
Rotate Left/Right → Dim or Brighten Lights
The rotate action reports degrees turned. Use a template to map rotation to a brightness step.
alias: "Cube: Rotate → Adjust Brightness"
trigger:
- platform: state
entity_id: sensor.cube_living_room_action
to:
- "rotate_left"
- "rotate_right"
action:
- choose:
- conditions:
- condition: state
entity_id: sensor.cube_living_room_action
state: "rotate_right"
sequence:
- service: light.turn_on
target:
entity_id: light.living_room_ceiling
data:
brightness_step_pct: 15
- conditions:
- condition: state
entity_id: sensor.cube_living_room_action
state: "rotate_left"
sequence:
- service: light.turn_on
target:
entity_id: light.living_room_ceiling
data:
brightness_step_pct: -15
mode: restart
Flip 90° → Skip to Next Track
alias: "Cube: Flip 90 → Next Track"
trigger:
- platform: state
entity_id: sensor.cube_living_room_action
to: "flip_to_side"
condition:
- condition: state
entity_id: media_player.living_room_speaker
state: "playing"
action:
- service: media_player.media_next_track
target:
entity_id: media_player.living_room_speaker
mode: single
Hold + Shake → Goodnight Scene
alias: "Cube: Hold Shake → Goodnight"
trigger:
- platform: state
entity_id: sensor.cube_living_room_action
to: "hold_shake"
action:
- service: scene.turn_on
target:
entity_id: scene.goodnight
mode: single
The hold_shake gesture requires holding the cube steady for ~1 second before shaking — it’s harder to trigger accidentally, which makes it good for decisive “end of night” commands.
Six-Face Scene Selector (Scene Mode)
If you’ve switched to Scene Mode, the cube reports scene_N (where N is 1–6) rather than gesture names. Map each face to a HA scene:
alias: "Cube: Scene Mode → Select Scene"
trigger:
- platform: state
entity_id: sensor.cube_living_room_action
action:
- choose:
- conditions:
- condition: state
entity_id: sensor.cube_living_room_action
state: "scene_1"
sequence:
- service: scene.turn_on
target:
entity_id: scene.bright_work
- conditions:
- condition: state
entity_id: sensor.cube_living_room_action
state: "scene_2"
sequence:
- service: scene.turn_on
target:
entity_id: scene.movie_mode
- conditions:
- condition: state
entity_id: sensor.cube_living_room_action
state: "scene_3"
sequence:
- service: scene.turn_on
target:
entity_id: scene.relax_evening
- conditions:
- condition: state
entity_id: sensor.cube_living_room_action
state: "scene_4"
sequence:
- service: scene.turn_on
target:
entity_id: scene.morning_routine
- conditions:
- condition: state
entity_id: sensor.cube_living_room_action
state: "scene_5"
sequence:
- service: scene.turn_on
target:
entity_id: scene.party_mode
- conditions:
- condition: state
entity_id: sensor.cube_living_room_action
state: "scene_6"
sequence:
- service: scene.turn_on
target:
entity_id: scene.goodnight
mode: single
Using a Blueprint (Faster Setup)
If writing individual automations for each gesture sounds tedious, the HA Blueprint Exchange has community blueprints for the Cube T1 Pro with Z2M. A good blueprint pre-wires all the action triggers; you just assign what each gesture does.
To import a blueprint:
- Go to Settings → Automations & Scenes → Blueprints
- Click Import Blueprint
- Paste the blueprint URL from the HA community forums (search “Aqara Cube T1 Pro zigbee2mqtt blueprint” on community.home-assistant.io)
- Click Preview, then Import
- Create an automation from the blueprint and assign your services/scenes to each gesture slot
The blueprint approach is worth it if you want all 10+ common gestures wired up quickly. For one or two gestures, writing the YAML directly (as above) is faster.
Troubleshooting
Cube Actions Lag or Drop
This is the most common complaint. The Cube T1 Pro is battery-powered and aggressively sleeps to conserve battery. If you set the cube down for a few minutes and then immediately try to shake it, the action may not register because the radio hasn’t woken up yet.
What’s actually happening: the cube’s Zigbee radio goes into a low-power sleep state. Your first gesture wakes it, but the wake-up takes long enough that the gesture itself gets dropped. The second gesture usually fires correctly.
Mitigation:
– Give the cube a light tap before performing your intended gesture — this wakes it first.
– Check linkquality in Z2M for the cube. Battery-powered devices can’t act as routers, so if your coordinator is far away, signal drop compounds the sleep issue. Place a mains-powered Zigbee device (like a smart plug) between the cube’s location and your coordinator to act as a router.
– There’s no configuration to disable sleep — it’s firmware-level behavior to preserve battery.
Actions Fire in Z2M But Not Reaching HA
If you can see the action appearing in Z2M’s dashboard but HA automations aren’t triggering:
- Check MQTT discovery is enabled. In your Z2M
configuration.yaml, confirmhomeassistant: trueis set. Restart Z2M after changing this. - Check the MQTT integration in HA. Go to Settings → Devices & Services → MQTT. If the cube isn’t listed as a device there, discovery isn’t working. Use the MQTT integration’s “Listen to a topic” tool — subscribe to
zigbee2mqtt/cube_living_roomand perform a gesture. If you see the payload arrive but HA entities don’t update, the entity may have the wrong name in your automation. - Check the entity name. After renaming the device in Z2M, the HA entity ID may not update automatically. Check Settings → Entities and search for your cube — confirm the entity ID matches what’s in your automation trigger.
ZHA vs Zigbee2MQTT — Why Switch
If you’re coming from ZHA and the cube seemed unreliable, this is the reason. ZHA’s CTP-R01 implementation has incomplete action support — several gesture types don’t fire reliably or at all. Z2M’s implementation is more complete: all 58+ actions are documented on the Z2M device page for CTP-R01, and you can verify which actions your firmware version supports before writing automations.
If you want to stay on ZHA for other devices but use Z2M for the cube, that’s possible — run both integrations simultaneously with the cube on Z2M. It adds coordinator complexity but is a valid setup.
Battery and Long-Term Use
The CR2450 battery should last roughly 1–2 years under typical use (several triggers per day). Z2M reports the battery percentage as a sensor entity — set up an automation to alert you when it drops below 20%.
alias: "Cube: Low Battery Alert"
trigger:
- platform: numeric_state
entity_id: sensor.cube_living_room_battery
below: 20
action:
- service: notify.mobile_app_your_phone
data:
message: "Cube T1 Pro battery below 20%. Replace CR2450."
mode: single
<!– VERIFY: confirm battery entity is named sensor._battery in Z2M MQTT discovery –>
OTA Firmware Updates
Aqara releases firmware updates for the CTP-R01, and Z2M can install them over-the-air without removing the device from your network.
To check and apply updates:
1. Open Z2M dashboard
2. Navigate to your cube device
3. Click the OTA tab
4. Click Check for update — Z2M will query the OTA server
5. If an update is available, click Update
The update process takes a few minutes. The cube’s LED will blink during flashing. Don’t remove the battery during this process.
Keep firmware current — updates sometimes fix action reliability issues and add new gesture support.
Setup Summary
The Aqara Cube T1 Pro is the highest-leverage physical controller you can add to a local Home Assistant setup. No other single device gives you this many distinct inputs from one hand gesture vocabulary — and with Z2M, every action fires reliably with a documented event name.
The setup path: pair via Z2M → choose Action Mode or Scene Mode → wire up automations from the YAML patterns above (or import a blueprint) → configure a battery alert and check OTA. That’s the full lifecycle.
For occupancy-aware automations — where the cube’s action depends on whether the room is occupied — pair it with a motion sensor. For the full Z2M setup walkthrough if you haven’t done it yet, start here.
If you’re evaluating the hub-based alternative — using Aqara’s own hub instead of Z2M — note that hub-based setups limit the available action set. Z2M is the right path if you want all 58+ actions local and under your control.