Tuya Air Purifier Local: A SmartThings Edge Driver for Tuya / Smart Life Air Purifiers
I have been using this air purifier for about two years now. As an air purifier, it has been working great: it reacts quickly to bad air, the PM2.5 sensor is useful, the automatic mode does what it should, and the device itself has proven to be reliable in daily use.
But one thing has always bothered me: it was still a Tuya / Smart Life Wi‑Fi device that was not locally integrated into SmartThings.
Yes, the purifier could be controlled through the Smart Life app. Yes, cloud integrations can sometimes bridge devices into other platforms. But for a device that sits in my home, measures my air quality, reacts automatically and is part of daily routines, I really wanted something better:
Local SmartThings control through the SmartThings Hub.
That is what this driver is about.
The project started with my own KLAMER 500i air purifier. During development, however, it became clear that this is not really a unique KLAMER device. Internally, it is a Tuya / Smart Life white-label device, and very similar air purifiers are sold under several different brand names. Some may look almost identical, some may only look vaguely similar, and some may have different branding or slightly different outer shells — but internally they may still expose the same Tuya data points.
Why this driver exists
Many Tuya / Smart Life air purifiers work well in their original app, but SmartThings support is often limited, cloud-based, incomplete or completely missing.
The official Tuya / Smart Life cloud integration can be useful, but it still depends on a cloud-to-cloud path. That means:
- commands may be slower,
- automations depend on external cloud services,
- local fallback is limited,
- device-specific features may not appear in SmartThings,
- and the SmartThings Hub is not really talking directly to the device.
This driver takes a different approach.
It talks directly to the purifier over the local network using the Tuya local protocol. After setup, normal control happens locally through the SmartThings Hub.
The device family: Tuya white-label air purifiers
The confirmed test device is sold as the KLAMER 500i, but the device itself appears to be part of a broader Tuya white-label air-purifier family.
These devices are often sold under different names. The brand on the front, the product page and the housing are not always enough to know whether the driver will work. What really matters is the internal Tuya DPS map.
The tested device exposes this Tuya DPS structure:
| DPS | Function |
|---|---|
| 1 | Power |
| 2 | PM2.5 / fine dust |
| 3 | Fan mode |
| 5 | Filter life remaining |
| 6 | Ionizer |
| 9 | UV |
| 11 | Filter reset |
| 18 | Timer mode |
| 19 | Timer remaining |
| 21 | Air-quality state |
| 22 | Fault state |
| 101 | Display light mode |
This is a typical Tuya air-purifier feature set. Tuya’s own air-purifier documentation describes functions such as mode, fan speed, anion / ionizer, lighting, UV sterilization, timer and filter reset as common air-purifier functions.
That is why this driver may be useful beyond the exact device I started with.
Compatible and likely compatible devices
The driver is confirmed with my KLAMER-branded device.
However, similar Tuya / Smart Life air purifiers appear under other names. Devices that look identical or even only vaguely similar from the outside are worth checking, because this is a white-label market and the same internal platform may be reused across different brands.
Examples of devices or device families that are worth checking include:
| Compatibility status | Device / family | Notes |
|---|---|---|
| Confirmed | KLAMER 500i / KLAMER-branded tested device | Fully tested during development |
| Very likely same family | Tubble Air Purifier Max | A very similar DPS layout has been documented by LocalTuya users |
| Very likely same family | essentials portable / mobile air purifier | Appears in Tuya-local supported device lists |
| Worth trying / needs DPS confirmation | Evolar Pure4+ | Looks like the same or a very close white-label device candidate; DPS needs confirmation |
| Possible | Other Tuya / Smart Life air purifiers with similar features | Needs DPS confirmation |
| Not guaranteed | Any random Tuya purifier | Brand name and appearance alone are not enough |
This is a bit hit and miss.
A device can look almost identical and still use a different datapoint layout. Another device can look slightly different but still be internally compatible. The driver therefore does not simply check the brand name. The important part is whether the device exposes a compatible DPS map.
The most important rule is:
Compatibility depends on the internal Tuya DPS map, not the brand name, product photo or outer casing.
If your air purifier uses the Smart Life or Tuya Smart app, has PM2.5, auto/sleep/high mode, filter life, UV, ionizer, timer and display-light modes, it is worth testing.
What the driver supports
The driver exposes the purifier as a normal SmartThings device with local control from the hub.
Main control
- Power on / off
- Fan mode:
- Auto
- High
- Sleep
- Off
- Manual refresh
- Local command handling
- State verification after commands
Sensor and state reporting
- PM2.5 / fine dust value
- Air-quality health concern
- Filter life remaining
- Timer state
- Timer remaining time
- Display light mode
- Ionizer state
- UV state
- Fault datapoint, where exposed by the device
Additional controls
- Ionizer on / off
- UV on / off
- Filter reset
- Display light:
- Off
- Soft
- Standard
- Timer:
- Off
- 2 hours
- 4 hours
- remaining time in minutes
SmartThings capabilities
The driver uses standard SmartThings capabilities wherever possible.
For device-specific functions where SmartThings has no perfect built-in equivalent, the driver uses custom capabilities:
oceancircle09600.airPurifierDisplayLight
oceancircle09600.airPurifierTimer
These provide clean UI controls for:
- Display light mode
- Timer mode
- Timer remaining time
Earlier test versions used fallback switch/level controls for display light and timer. Those worked, but they were not ideal. The current version uses dedicated custom capabilities instead, which makes the SmartThings UI much cleaner and closer to how the device actually works.
Driver settings
The driver requires three Tuya-specific values:
| Setting | Description |
|---|---|
| Host / IP address | The local IP address of the purifier |
| Device ID | The Tuya device ID |
| Local Key | The Tuya local encryption key |
Additional settings may include:
| Setting | Description |
|---|---|
| Poll interval | How often the driver refreshes state from the device |
| IP rediscovery | Helps the driver recover if the purifier receives a new IP address |
| Verbose Tuya logging | Enables detailed packet/debug logging for troubleshooting |
For normal use, verbose logging should stay disabled. It is mainly useful while testing a new device or diagnosing connection problems.
Getting the required Tuya information
To use the driver, the purifier must already be paired with the Smart Life or Tuya Smart app.
You need:
IP address
Device ID
Local Key
The IP address identifies the device on your local network. The Device ID and Local Key are Tuya-specific values required for encrypted local communication.
The Local Key is sensitive. Do not post it publicly.
Complete guide: getting the Device ID and Local Key with TinyTuya
The easiest method is usually TinyTuya.
TinyTuya is a Python tool that can connect to the Tuya IoT platform, download your registered Tuya devices and retrieve their local keys. Its setup wizard creates files such as devices.json, tuya-raw.json and snapshot.json, which are very useful for local Tuya projects.
1. Make sure the purifier is paired
First, add the air purifier to either:
- the Smart Life app, or
- the Tuya Smart app.
Make sure the device is online and controllable from the app.
2. Install TinyTuya
On Linux, macOS or Windows with Python installed:
python -m venv .venv
source .venv/bin/activate
pip install tinytuya
On Windows PowerShell, activating the virtual environment usually looks like this:
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install tinytuya
On Gentoo Linux, I usually use a local virtual environment as well:
mkdir ~/tuya-air-purifier
cd ~/tuya-air-purifier
python -m venv .venv
source .venv/bin/activate
pip install tinytuya
3. Create a Tuya IoT developer account
Go to:
https://iot.tuya.com
Create a free Tuya IoT developer account.
Then create a new cloud project:
- Open Cloud.
- Create a new cloud project.
- Choose a Smart Home / Tuya Smart Life related project type.
- Select the correct data center / region.
- Save the project.
The region is important. For Europe, the region is usually one of the European Tuya data centers. TinyTuya uses region codes such as:
| Region code | Meaning |
|---|---|
eu |
Europe |
eu-w |
Western Europe |
us |
United States |
us-e |
Eastern United States |
cn |
China |
in |
India |
sg |
Singapore |
If the wizard does not find your devices, the wrong Tuya region is one of the first things to check.
4. Copy the API credentials
Inside your Tuya IoT cloud project, open the project overview and copy:
Access ID / Client ID
Access Secret / Client Secret
TinyTuya will ask for these values.
5. Link your Smart Life / Tuya app account
In the Tuya IoT project:
- Open Devices.
- Choose Link Tuya App Account.
- Add an app account.
- Select the correct app: Smart Life or Tuya Smart.
- Use the QR code method.
- Open the Smart Life / Tuya Smart app on your phone.
- Use the scan function in the app to scan the QR code.
- Confirm the link.
After linking, the devices from your app account should appear in the Tuya IoT project.
If no devices appear, check:
- wrong region / data center,
- wrong app selected,
- account not linked correctly,
- Tuya IoT trial service expired,
- device paired to another account.
6. Run the TinyTuya wizard
Now run:
python -m tinytuya wizard
If the terminal output looks broken because of color codes, use:
python -m tinytuya wizard -nocolor
The wizard asks for:
API ID / Access ID
API Secret / Access Secret
Region code
Sample Device ID
For the sample Device ID, you can either enter one device ID from the Tuya IoT device list or let TinyTuya scan for one.
The wizard then downloads the device list from Tuya and prints entries similar to this:
{
"name": "Air Purifier",
"id": "YOUR_DEVICE_ID",
"key": "YOUR_LOCAL_KEY",
"ip": "192.168.1.xxx",
"version": "3.3"
}
The important fields are:
| Field | Meaning |
|---|---|
id |
Tuya Device ID |
key |
Tuya Local Key |
ip |
Local IP address, if discovered |
version |
Tuya protocol version, often 3.3 |
TinyTuya also saves this information to:
devices.json
7. Scan the local network
To find the current IP address and confirm the device is visible locally:
python -m tinytuya scan
You can also scan for a longer time:
python -m tinytuya scan 50
The scan should show a Tuya device with an IP address, Device ID and protocol version.
If the local key is empty in the scan output, that is normal if TinyTuya only saw the network broadcast. The key comes from the Tuya IoT cloud project via the wizard, not from a plain local scan.
8. Test the device locally
Once devices.json exists, test the purifier:
python -m tinytuya get --name "Air Purifier"
Or use the exact name from your devices.json.
You should see a DPS response similar to:
{
"dps": {
"1": true,
"2": 95,
"3": "auto",
"5": 45,
"6": false,
"9": false,
"11": false,
"18": "cancel",
"19": 0,
"21": "mild",
"22": 0,
"101": "Standard"
}
}
This is the kind of output that helps determine whether your device is compatible with the driver.
9. Optional: test individual functions
You can test power:
python -m tinytuya on --name "Air Purifier"
python -m tinytuya off --name "Air Purifier"
You can test fan modes:
python -m tinytuya set --name "Air Purifier" --dps 3 --value '"auto"'
python -m tinytuya set --name "Air Purifier" --dps 3 --value '"H"'
python -m tinytuya set --name "Air Purifier" --dps 3 --value '"sleep"'
You can test UV and ionizer:
python -m tinytuya set --name "Air Purifier" --dps 6 --value true
python -m tinytuya set --name "Air Purifier" --dps 6 --value false
python -m tinytuya set --name "Air Purifier" --dps 9 --value true
python -m tinytuya set --name "Air Purifier" --dps 9 --value false
You can test display light modes:
python -m tinytuya set --name "Air Purifier" --dps 101 --value '"Close"'
python -m tinytuya set --name "Air Purifier" --dps 101 --value '"Soft"'
python -m tinytuya set --name "Air Purifier" --dps 101 --value '"Standard"'
You can test the timer:
python -m tinytuya set --name "Air Purifier" --dps 18 --value '"cancel"'
python -m tinytuya set --name "Air Purifier" --dps 18 --value '"2h"'
python -m tinytuya set --name "Air Purifier" --dps 18 --value '"4h"'
If your device responds to these values, it is a very strong sign that it belongs to the same compatible family.
10. What to enter in SmartThings
In the SmartThings device settings, enter:
| SmartThings setting | TinyTuya source |
|---|---|
| Host / IP address | ip from devices.json, snapshot.json, router or TinyTuya scan |
| Device ID | id from devices.json |
| Local Key | key from devices.json |
Again: never share the Local Key publicly.
11. Important local-key notes
- The Local Key changes when the device is reset and paired again.
- If commands suddenly stop working after re-pairing, retrieve the new Local Key.
- If TinyTuya finds the device but cannot control it, check the key, IP address and protocol version.
- The SmartThings Hub and the purifier must be on the same local network.
- Firewalls or isolated Wi‑Fi networks can block local control.
- Tuya devices commonly use UDP broadcasts on ports 6666/6667/7000 and local TCP communication on port 6668.
Installing the driver
Once the driver is published in a SmartThings Edge channel, the normal installation flow is:
- Open the driver channel invitation link.
- Enroll your SmartThings Hub.
- Install the Tuya Air Purifier Local driver.
- Open the SmartThings app.
- Scan for nearby devices.
- A new Air Purifier setup device appears.
- Open the device settings.
- Enter:
- Host / IP address
- Device ID
- Local Key
- Save the settings.
- Tap refresh.
- Verify that PM2.5, fan mode, filter life and other states appear.
First test checklist
After setup, I recommend testing the following:
| Test | Expected result |
|---|---|
| Power on/off | Purifier switches on/off locally |
| Fan mode Auto | Device switches to auto mode |
| Fan mode High | Device switches to high mode |
| Fan mode Sleep | Device switches to sleep mode |
| Ionizer | Ionizer state changes |
| UV | UV state changes |
| Display light Off / Soft / Standard | Display mode changes correctly |
| Timer 2h / 4h / Off | Timer mode and remaining time update |
| Filter reset | Filter reset command is accepted |
| Smart Life app change | SmartThings updates after polling |
Technical background
The driver communicates with the purifier locally over TCP using the Tuya local protocol.
The tested device uses Tuya protocol version 3.3 and encrypted local communication. The driver handles:
- Tuya packet framing,
- AES encryption/decryption,
- command sending,
- status requests,
- response parsing,
- DPS-to-capability mapping,
- state verification after commands,
- polling,
- and IP rediscovery.
The core DPS mapping is:
| DPS | Driver mapping |
|---|---|
| 1 | switch |
| 2 | fineDustSensor |
| 3 | airPurifierFanMode |
| 5 | filterState.filterLifeRemaining |
| 6 | Ionizer component |
| 9 | UV component |
| 11 | Filter reset |
| 18 | Custom timer mode |
| 19 | Custom timer remaining |
| 21 | airQualityHealthConcern |
| 22 | Fault state |
| 101 | Custom display light mode |
This is also why the driver can potentially support other devices. If another Tuya / Smart Life purifier exposes the same or compatible DPS layout, the driver should be a good match.
Challenges solved during development
This driver went through several development stages before becoming reliable enough for daily use.
1. Tuya local encryption and packet handling
The first challenge was basic Tuya v3.3 local communication:
- correct packet format,
- encrypted payloads,
- local key handling,
- response decoding,
- and DPS parsing.
Once that worked, the driver could read the full state directly from the purifier.
2. Mapping Tuya datapoints to SmartThings
Tuya devices expose low-level DPS values. SmartThings expects capabilities.
That means the driver has to translate things like:
DPS 101 = "Standard"
into a clean SmartThings capability state:
Display light: Standard
The same applies to fan mode, timer state, PM2.5, air quality, UV, ionizer and filter life.
3. Cleaning up the UI
Early builds used fallback controls for functions like display light and timer. They worked, but they were not ideal.
The current version uses dedicated custom capabilities instead. This makes the SmartThings UI much cleaner and avoids confusing switch/level controls for features that are really enumerated modes.
4. Reliability and command handling
One of the bigger challenges was reliability.
Tuya Wi‑Fi devices can be a little quirky. During testing, the purifier sometimes responded instantly, while at other times commands took longer or needed a more robust command flow.
The driver now uses a more reliable pattern:
- send command,
- wait briefly,
- request updated state,
- verify the result,
- update SmartThings state from the confirmed DPS response.
This made command handling much more reliable than the earlier proof-of-concept versions.
5. IP rediscovery
A manually entered IP address is fragile. If the router gives the purifier a new address, a purely static setup breaks.
The driver therefore includes IP rediscovery logic and matches the device by its Tuya Device ID. The Device ID is the stable identifier; the IP address can change.
Current limitations
This is not a universal driver for every Tuya air purifier.
The driver is designed for devices that share this specific Tuya DPS family. Other Tuya purifiers may use different datapoints, different mode names, or different protocol behavior.
Known limitations:
- Only the tested KLAMER-branded device is confirmed.
- Other devices need DPS confirmation.
- A Tuya Device ID and Local Key are required.
- The device must be on the same LAN as the SmartThings Hub.
- Some devices may use a different DPS layout.
- Some devices may expose additional functions such as child lock or more fan speeds that are not currently mapped.
- Wi‑Fi quality and device firmware behavior can affect response time.
How to check whether your device might be compatible
If you have a similar Tuya / Smart Life air purifier, the most useful information is not just the brand name. The useful information is the DPS map.
A good compatibility report should include:
| Field | Example |
|---|---|
| Brand / model | KLAMER, Tubble, essentials, Evolar, etc. |
| App | Smart Life or Tuya Smart |
| Protocol version | Usually 3.3 |
| Product ID | From TinyTuya |
| DPS 1 | Power |
| DPS 2 | PM2.5 |
| DPS 3 | Mode |
| DPS 5 | Filter life |
| DPS 6 | Ionizer |
| DPS 9 | UV |
| DPS 18/19 | Timer |
| DPS 21 | Air quality |
| DPS 101 | Display light |
Please do not post your Local Key.
A TinyTuya status dump is usually enough to see whether the device belongs to the same family:
python -m tinytuya get --name "Your device name"
The more DPS maps we collect, the easier it becomes to identify which white-label devices are truly compatible.
Conclusion
This driver started as a local SmartThings driver for one KLAMER-branded air purifier.
But the device itself appears to be part of a broader Tuya / Smart Life white-label family. Similar devices are sold under different brands, and at least some of them seem to share the same internal Tuya datapoint structure.
The goal is simple: bring this Tuya air-purifier family into SmartThings properly, locally and with a clean UI.
If you have a similar Tuya / Smart Life air purifier, the most helpful thing you can share is the DPS map. Brand names are useful, but the datapoints tell the real story.
References and useful links
- SmartThings Edge LAN driver documentation: LAN Edge Device Driver Development Guide | Developer Documentation | SmartThings
- TinyTuya GitHub repository and setup wizard: GitHub - jasonacox/tinytuya: Python API and command line tool for Tuya WiFi smart devices using a direct local area network (LAN) connection or the cloud (TuyaCloud API). · GitHub
- Tuya Smart Air Purifier documentation: https://developer.tuya.com/en/docs/iot/air-cleaner?id=Kabt7wammagis
- Tuya standard air purifier instruction set: Standard Instruction Set-Tuya Developer Platform-Tuya Developer
- LocalTuya issue for Tubble Air Purifier Max: Support for Tubble air purifier max · Issue #367 · rospogrigio/localtuya · GitHub
- tuya-local supported device list: tuya-local/DEVICES.md at main · make-all/tuya-local · GitHub
- Evolar Pure4+ product listing: Evolar Pure 4+ Luftreiniger | Leistungsstarke HEPA-Filtration | Evolar.de | Evolar