From 9159b0e70b6fa446ac6d85101dbe1ca3001d442f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 24 Oct 2026 08:56:11 -0500
Subject: [PATCH] docs: add air purifier filter usage reset and read commands

Document 0x570f4c09 (reset filter usage) and 0x570f4d09 (read filter
usage: status, then used hours big-endian) for the Air Purifier and Air
Purifier Table, and the safe reset sequence (send once, then confirm 0
hours), as implemented in pySwitchbot 3.1.0 (sblibs/pySwitchbot#583).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TYWa2RXoWsaUTWh76oNv8s
---
 README.md                  |  1 +
 devicetypes/airpurifier.md | 69 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 70 insertions(+)
 create mode 100644 devicetypes/airpurifier.md

diff --git a/README.md b/README.md
index be4a5ef..641cb2d 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,7 @@
 
 - [Device Types](#device-type)
 - [UUID Update Notes](#uuid-update-notes)
+- [Air Purifier BLE open API](/devicetypes/airpurifier.md)
 - [Bot BLE open API](/devicetypes/bot.md)
 - [Color Bulb BLE open API](/devicetypes/colorbulb.md)
 - [Contact Sensor BLE open API](/devicetypes/contactsensor.md)
diff --git a/devicetypes/airpurifier.md b/devicetypes/airpurifier.md
new file mode 100644
index 0000000..24769c1
--- /dev/null
+++ b/devicetypes/airpurifier.md
@@ -0,0 +1,69 @@
+## Air Purifier BLE open API
+
+This page covers the Air Purifier (US / JP, Device Type `*` / `+`) and Air
+Purifier Table (US / JP, Device Type `7` / `8`). Air purifiers use an
+encrypted connection; the commands below are shown before encryption, and the
+status byte (Byte 0) of a response is not encrypted.
+
+- [0x0F Expansion command](#0x0f-expansion-command)
+  - [0x570f4c09 reset filter usage](#0x570f4c09-reset-filter-usage)
+  - [0x570f4d09 read filter usage](#0x570f4d09-read-filter-usage)
+- [Resetting the filter safely](#resetting-the-filter-safely)
+
+### 0x0F Expansion command
+
+### 0x570f4c09 reset filter usage
+
+The payload length of the request packet is 0.
+
+Resets the filter's used-hours counter to 0.
+
+<table>
+    <thead>
+        <tr>
+            <th colspan=3>Response</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td rowspan=1>Byte: 0</td>
+            <td rowspan=1>Status</td>
+            <td rowspan=1>0x01 - OK, the reset was accepted</td>
+        </tr>
+    </tbody>
+</table>
+
+### 0x570f4d09 read filter usage
+
+The payload length of the request packet is 0.
+
+<table>
+    <thead>
+        <tr>
+            <th colspan=3>Response</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td rowspan=1>Byte: 0</td>
+            <td rowspan=1>Status</td>
+            <td rowspan=1>0x01 - OK</td>
+        </tr>
+        <tr>
+            <td rowspan=1>Byte: 1</td>
+            <td rowspan=2>Used hours</td>
+            <td rowspan=2>Filter used hours, big-endian (e.g. 0x0768 = 1896 hours)</td>
+        </tr>
+        <tr>
+            <td rowspan=1>Byte: 2</td>
+        </tr>
+    </tbody>
+</table>
+
+### Resetting the filter safely
+
+Send `0x570f4c09` once and do not retry it automatically: if the reply is
+lost, the reset may still have been applied. Then read `0x570f4d09` and treat
+the reset as done only when the status is `0x01` and the used hours are `0`.
+This is how [pySwitchbot](https://github.com/sblibs/pySwitchbot) implements
+`reset_filter_usage`.