Local Bluetooth control of the abandoned Guardian Technologies / GermGuardian smart purifiers (APZ-451 = CDAP4500BCA, APZ-453 = CDAP5500BCA). No cloud, no vendor app, no internet.
Status: test version (0.1.8).
- Local control: works on real hardware (power on/off and status, tested on an APZ-451
with
tools/gg_probe.py). - Pairing through Aplix's server: works. Run against a real APZ-451 with LINK held, it returned the same key the phone app uses (an already-paired unit is read back, not reset).
- Home Assistant: pairing and control confirmed on a real purifier (Raspberry Pi, Home Assistant in Docker). Only on/off has been checked so far; fan speeds, the UV switch, the timer and the sensors are not confirmed yet, so expect to report bugs.
If you already have a key, you do not need pairing at all: paste it in the setup form.
Each purifier is controlled with a 16-byte local key. The official app obtains it from
Aplix's server a.iots.net while you hold the LINK button; that server is still up.
This integration repeats that exchange, reconstructed from the app's code and checked
against a capture of the app's traffic (tools/capture_app.py, see APZ-451-protocol.md
section 14.8). The registration calls themselves have not been captured yet, so the first
real run may need fixes. After pairing, everything is local and works with no internet.
Or skip pairing and paste a key you already have (base64 such as
AAECAwQFBgcICQoLDA0ODw==, or 32 hex characters). Save the key - it is shown by
gg_probe.py --pair and stored in the integration's config entry.
Fan (on/off, 5 speeds, auto preset), UV light switch, timer select (off/1/2/4/8 h),
sensors for air quality, filter hours and life, UV bulb hours and life.
How often it checks (Settings -> Devices & services -> GermGuardian BLE -> Configure): every 30 s, 1 min (default), 2, 5 or 15 min, or only when I send a command. Each check is a short Bluetooth connection; commands always connect right away. With "only when I send a command", changes made with the purifier's own buttons show up after your next command.
On any computer with Bluetooth, Python 3.11+:
pip install bleak bleak-retry-connector cryptography
git clone https://github.com/NicholasBly/ha-germguardian
cd ha-germguardian
python tools/gg_probe.py --pair # start it, walk over, hold LINK; prints your key
python tools/gg_probe.py --key YOUR_KEY # control test
python tools/gg_probe.py --key YOUR_KEY --on # also turns it on
Close the phone app first (the purifier talks to one device at a time). You want to see
AUTHENTICATED and a status line. If it fails, send the full output.
--pair asks Aplix's server which nearby Aplix units are purifiers (a gateway is ignored),
then waits up to 90 s for that purifier's LINK signal, so you can start it and walk to the unit. If Windows never shows the signal, use
--address 00:1C:4D:4B:XX:XX --delay 20 (counts down 20 s, then starts anyway).
- HACS -> three-dot menu -> Custom repositories -> add
https://github.com/NicholasBly/ha-germguardian, category Integration. - Install GermGuardian BLE, then restart Home Assistant.
- The purifier should appear under Settings -> Devices & services as Discovered. If not, click Add integration -> GermGuardian BLE.
- Choose your model. To pair: leave the key empty, press Submit, then within 20 s press
and HOLD LINK and keep holding it until the form finishes - up to about a minute (it
starts as soon as it hears the LINK signal and tries up to 3 times by itself if the
purifier is slow to open its key registry). Do not let go and press again; if it still
fails, wait for the message, then press Submit and hold LINK once more. Otherwise paste a key. Leave the protocol number alone. The form checks
the key against the unit before saving. Pairing writes its steps to the Home Assistant
log as lines starting
pairing:(for Docker:docker logs homeassistant 2>&1 | grep -i pairing).
Home Assistant needs a Bluetooth adapter or an ESPHome Bluetooth proxy within range. Keep the phone app closed.
The message now says why:
- no Bluetooth adapter or proxy: Home Assistant has nothing that can connect to Bluetooth devices. Check Settings -> Devices & services -> Bluetooth.
- can see N devices, none is a purifier: Home Assistant's Bluetooth works but cannot hear
the unit. Put the adapter or proxy within ~10 ft (3 m) of it, make sure the unit is on, and
close the phone app (a connected phone can hide the unit). To see what Home Assistant
hears, open Settings -> Devices & services -> Bluetooth -> Configure -> advertisement
monitor and look for an address starting
00:1C:4D:.
If Settings -> Devices & services -> Bluetooth shows your adapter as Failed setup ...
DBus service not found; docker config may be missing -v /run/dbus:/run/dbus:ro, the
container cannot reach the host's Bluetooth, so nothing (this integration included) can
find a device. Per Home Assistant's Bluetooth docs,
the container needs the host's D-Bus socket and two capabilities. In docker-compose.yml:
cap_add:
- NET_ADMIN
- NET_RAW
volumes:
- /run/dbus:/run/dbus:ro(or --cap-add=NET_ADMIN --cap-add=NET_RAW -v /run/dbus:/run/dbus:ro with docker run).
Apply it by recreating the container (docker compose up -d); a restart is not enough.
The host also needs BlueZ (5.43 or newer, 5.63+ recommended): sudo apt-get install bluez.
Home Assistant OS and Supervised installs set this up automatically.
The purifier accepts one Bluetooth connection at a time, and Home Assistant connects
briefly at each check (every minute by default). Two failed checks in a row are hidden; a
longer gap turns the entities unavailable. The reason is in the Home Assistant log (Settings -> System -> Logs,
search germguardian):
- "the purifier dropped the Bluetooth link ... [x s after connecting]": the link was
made and then lost. Close the phone app and anything else that might be connected (a
laptop running
gg_probe.py, a Bluetooth scanner app), and move the adapter closer or use an ESPHome Bluetooth proxy. The Raspberry Pi's built-in Bluetooth is often weak. Please report the "x s" numbers. - "cannot connect ... last advertisement N s ago": Home Assistant's adapter does not hear the purifier at all. Check it has power, unplug it for 10 seconds, and make sure nothing else is connected to it (a connected unit stops advertising).
- "device did not accept the key": the unit really refused the key twice in a row.
If the log repeats this every minute, the Pi's Bluetooth chip has frozen - the purifier is fine, and so is every other Bluetooth device: Home Assistant just cannot hear anything.
[habluetooth.scanner] hci0 (...): Failed to restart Bluetooth scanner
... Failed to start Bluetooth: passive scanning on Linux requires BlueZ >= 5.56 with --experimental enabled ...
[bluetooth_auto_recovery.recover] Could not cycle the Bluetooth adapter hci0 ...: [Errno 110] Operation timed out
The "passive scanning ... --experimental" part is misleading: Home Assistant tries to start scanning four times and only the last try is passive, so that is just the last error. The real one is the next line: Home Assistant's recovery tried to power-cycle the chip and it did not answer. The Pi's built-in chip sits on a serial line, not USB, so a power-cycle is all Home Assistant can try; once it is frozen, only a driver reload or a reboot brings it back.
- Right now:
sudo reboot. - So it fixes itself: install the watchdog from this repository. Every 2 minutes it
looks for "Failed to restart Bluetooth scanner" in Home Assistant's log; the first time,
it reloads the Bluetooth driver and restarts Home Assistant; if that does not help, it
reboots the Pi (at most once every 6 hours; add
--no-rebootto never reboot).Remove it withcurl -fsSLO https://raw.githubusercontent.com/NicholasBly/ha-germguardian/main/tools/pi-bluetooth-watchdog/bt-watchdog.sh sudo bash bt-watchdog.sh install # container not called homeassistant? add --container NAME journalctl -u bt-watchdog # what it didsudo bt-watchdog uninstall. - To make it stop happening: use a USB Bluetooth adapter (Home Assistant can reset those itself) or an ESPHome Bluetooth proxy, and set the check interval to 2-5 minutes.
tools/capture_app.py runs mitmproxy and logs the app's traffic to a_iots_capture.txt
(it prints the iPhone steps). The log contains your unit's ID and, if you pair during the
capture, your key - do not post it publicly.
The integration connects briefly every 30 s (and for each command), authenticates with the key, reads or writes, and disconnects.
pip install pytest cryptography voluptuous && pytest