Skip to content

SMARTTHINGS.md

Latest commit

 

History

History
206 lines (123 loc) · 8.84 KB

SMARTTHINGS.md

File metadata and controls

206 lines (123 loc) · 8.84 KB
Raw

Connecting AirCube to SmartThings (Samsung hub)

This guide walks you through pairing AirCube to a SmartThings-compatible Zigbee hub and installing the community AirCube Zigbee Edge driver so you get temperature, humidity, eCO2, eTVOC, and VOC Level in the SmartThings app.

Default behavior: Without this driver, SmartThings often joins AirCube as a generic humidity / temperature device. You only get temp and humidity. The Edge driver adds the air quality sensors over Zigbee cluster 0xFC01 (same idea as the ZHA quirk and Zigbee2MQTT converter).

You will need

  • AirCube powered over USB-C
  • A SmartThings Edge–capable hub (e.g. SmartThings v3, Aeotec Smart Home Hub, SmartThings Station) on your Samsung account
  • A Mac, Windows, or Linux PC for the SmartThings CLI (one-time driver install)
  • A Samsung account used with SmartThings

The first time the CLI needs your SmartThings account, it starts a browser sign-in automatically (you may not see a separate login subcommand in smartthings --help). You do not need to create a Personal Access Token in the developer portal for normal interactive use. For automation / CI, you can use a PAT with channel scopes — see driver channels.

Step 1 — Put AirCube in pairing mode

  1. Plug in AirCube (or, if already powered, use the next step).
  2. Hold the button for about 3 seconds until the LEDs flash blue (Zigbee pairing mode).

See the README LED / button table if you need a refresher.

Step 2 — Add AirCube in the SmartThings mobile app

  1. Open the SmartThings app → Add device (or +).
  2. Choose Scan nearby / Zigbee / Generic Zigbee device per your app version, and enable pairing on the hub when prompted.
  3. Wait until AirCube appears and finish naming / room assignment.

Check: Open the new device — you should see temperature and humidity.
eCO2, TVOC, and VOC Level will not appear yet until the AirCube Zigbee driver is installed and selected (next steps).

Step 3 — Install the SmartThings CLI (sign-in is automatic)

  1. Install the CLI using the official instructions for your OS (Homebrew on Mac: brew install smartthings).
  2. Run smartthings --version and confirm the command works.

Authentication: Many recent builds do not list a smartthings login command. The first command that calls the SmartThings API (for example smartthings edge:drivers:package . in Step 5) will open a browser so you can sign in with your Samsung account. Complete that flow once; later CLI commands reuse the session.

  • To sign out on this machine: smartthings logout (then the next API command will prompt for login again).
  • Optional: Headless or automation-only setups can use a Personal Access Token instead; see CLI authentication.

Step 4 — Get the Edge driver source

From your clone of this repository (folder name may differ):

cd smartthings/aircube-zigbee

If you have not cloned yet:

git clone https://github.com/StuckAtPrototype/AirCube.git
cd AirCube/smartthings/aircube-zigbee

That directory contains config.yml, fingerprints.yml, profiles/, and src/init.lua.

Step 5 — Package the driver (build + upload)

From smartthings/aircube-zigbee:

smartthings edge:drivers:package .

The first time you run this (or any API command), the CLI may open the browser for Samsung sign-in — complete it, then re-run package if needed.

The CLI prints a Driver Id and Version (timestamp string). Save both — you need them to assign the driver to a channel.

Optional: also write a local zip:

smartthings edge:drivers:package . -b ./aircube-zigbee.zip

Recent CLI versions upload the driver when you package; there is no separate publish command.

Step 6 — Create a driver channel (first time only)

You need a driver channel to install your own driver on the hub.

This repo ships smartthings/driver-channel.json for edge:channels:create. It points termsOfServiceUrl at the StuckAtPrototype Terms of Service. Edit name / description in that file if you want different labels on your channel.

From the repository root (the folder that contains smartthings/):

smartthings edge:channels:create -i smartthings/driver-channel.json

List channels and copy your channel id (UUID):

smartthings edge:channels

Step 7 — Assign the packaged driver to your channel

smartthings edge:channels:assign <DRIVER_ID> "<VERSION>" --channel <CHANNEL_ID>

Use the Driver Id and Version from Step 5. You can omit arguments and use interactive prompts instead.

Step 8 — Enroll your hub, then install the driver

Order matters: enroll the hub on the channel before install.

smartthings edge:channels:enroll --channel <CHANNEL_ID>

Pick your hub when prompted (or pass flags if your CLI supports them).

Then install the driver onto that hub from the same channel:

smartthings edge:drivers:install --channel <CHANNEL_ID> --hub <HUB_DEVICE_UUID>

Hub id must be a UUID

<HUB_DEVICE_UUID> looks like xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. It is not the sticker MAC, Zigbee EUI, or networkId string.

Where to find it

  • SmartThings Advanced Web App → open your hub as a device → copy Device id, or
  • Open any Zigbee child device (e.g. AirCube) → Parent device / hub → copy that hub’s id.

If you omit --hub, the CLI usually offers a list — picking from the list avoids typos.

If install returns HTTP 400, see Troubleshooting below.

Step 9 — Use the AirCube Zigbee driver for your device

The hub must run AirCube Zigbee instead of the generic Zigbee Humidity Sensor driver.

Option A — Switch driver (keep device / room)

smartthings edge:drivers:switch <DEVICE_ID>

Use the AirCube device id from the Advanced Web App (not the hub id). Follow prompts to select AirCube Zigbee.

Option B — Remove and re-pair

Remove AirCube from SmartThings, then add it again (Step 2) after the driver is installed on the hub. With a matching fingerprint, SmartThings should pick AirCube Zigbee automatically.

Step 10 — Confirm in the Advanced Web App

  1. Open SmartThings Advanced Web App.
  2. Select AirCube.
  3. Check Driver (or device summary): it should show AirCube Zigbee (or your packaged driver name), not only “Zigbee Humidity Sensor”.
  4. Under capabilities / state, you should eventually see carbon dioxide, TVOC, and air quality style attributes after reports arrive (allow a few minutes for sensor warm-up).

Step 11 — Confirm in the mobile app

Open the device card: you should see temperature, humidity, CO₂, TVOC, and air quality (labels may vary slightly by app version).

Gas sensors may read 0 for the first few minutes after power-on — that is normal while the ENS16x warms up (same as Home Assistant).

Troubleshooting

Problem What to try
Only temp / humidity Driver not applied — repeat Step 9.
drivers:install 400 Bad Request Use hub UUID, not sticker id. Run channels:enroll for the same channel first.
eCO2 / TVOC / VOC Level stuck at 0 Wait 3–5+ minutes after power-on. Ensure driver is AirCube Zigbee and hub is online.
CLI / channel errors Run smartthings logout then repeat the command that triggered login (browser). If you use a PAT instead, confirm it includes channel read/write. See driver channels.

Technical reference

Zigbee layout (endpoint 10): standard temp/humidity clusters; custom air quality cluster 0xFC01; LED brightness uses Analog Output 0x000D (not exposed in this driver v1). Details match CONTRIBUTING.md → Zigbee Integration.

Contributors

If you improve the Edge driver or this guide, open a pull request on the AirCube repository so all users get the update.