ESPHome 2025.7.1
Loading...
Searching...
No Matches
xiaomi_ble.cpp
Go to the documentation of this file.
1#include "xiaomi_ble.h"
3#include "esphome/core/log.h"
4
5#ifdef USE_ESP32
6
7#include <vector>
8#include "mbedtls/ccm.h"
9
10namespace esphome {
11namespace xiaomi_ble {
12
13static const char *const TAG = "xiaomi_ble";
14
15bool parse_xiaomi_value(uint16_t value_type, const uint8_t *data, uint8_t value_length, XiaomiParseResult &result) {
16 // button pressed, 3 bytes, only byte 3 is used for supported devices so far
17 if ((value_type == 0x1001) && (value_length == 3)) {
18 result.button_press = data[2] == 0;
19 return true;
20 }
21 // motion detection, 1 byte, 8-bit unsigned integer
22 else if ((value_type == 0x0003) && (value_length == 1)) {
23 result.has_motion = data[0];
24 }
25 // temperature, 2 bytes, 16-bit signed integer (LE), 0.1 °C
26 else if ((value_type == 0x1004) && (value_length == 2)) {
27 const int16_t temperature = encode_uint16(data[1], data[0]);
28 result.temperature = temperature / 10.0f;
29 }
30 // humidity, 2 bytes, 16-bit signed integer (LE), 0.1 %
31 else if ((value_type == 0x1006) && (value_length == 2)) {
32 const int16_t humidity = encode_uint16(data[1], data[0]);
33 result.humidity = humidity / 10.0f;
34 }
35 // illuminance (+ motion), 3 bytes, 24-bit unsigned integer (LE), 1 lx
36 else if (((value_type == 0x1007) || (value_type == 0x000F)) && (value_length == 3)) {
37 const uint32_t illuminance = encode_uint24(data[2], data[1], data[0]);
38 result.illuminance = illuminance;
39 result.is_light = illuminance >= 100;
40 if (value_type == 0x0F)
41 result.has_motion = true;
42 }
43 // soil moisture, 1 byte, 8-bit unsigned integer, 1 %
44 else if ((value_type == 0x1008) && (value_length == 1)) {
45 result.moisture = data[0];
46 }
47 // conductivity, 2 bytes, 16-bit unsigned integer (LE), 1 µS/cm
48 else if ((value_type == 0x1009) && (value_length == 2)) {
49 const uint16_t conductivity = encode_uint16(data[1], data[0]);
50 result.conductivity = conductivity;
51 }
52 // battery / MiaoMiaoce battery, 1 byte, 8-bit unsigned integer, 1 %
53 else if ((value_type == 0x100A || value_type == 0x4803) && (value_length == 1)) {
54 result.battery_level = data[0];
55 }
56 // temperature + humidity, 4 bytes, 16-bit signed integer (LE) each, 0.1 °C, 0.1 %
57 else if ((value_type == 0x100D) && (value_length == 4)) {
58 const int16_t temperature = encode_uint16(data[1], data[0]);
59 const int16_t humidity = encode_uint16(data[3], data[2]);
60 result.temperature = temperature / 10.0f;
61 result.humidity = humidity / 10.0f;
62 }
63 // formaldehyde, 2 bytes, 16-bit unsigned integer (LE), 0.01 mg / m3
64 else if ((value_type == 0x1010) && (value_length == 2)) {
65 const uint16_t formaldehyde = encode_uint16(data[1], data[0]);
66 result.formaldehyde = formaldehyde / 100.0f;
67 }
68 // on/off state, 1 byte, 8-bit unsigned integer
69 else if ((value_type == 0x1012) && (value_length == 1)) {
70 result.is_active = data[0];
71 }
72 // mosquito tablet, 1 byte, 8-bit unsigned integer, 1 %
73 else if ((value_type == 0x1013) && (value_length == 1)) {
74 result.tablet = data[0];
75 }
76 // idle time since last motion, 4 byte, 32-bit unsigned integer, 1 min
77 else if ((value_type == 0x1017) && (value_length == 4)) {
78 const uint32_t idle_time = encode_uint32(data[3], data[2], data[1], data[0]);
79 result.idle_time = idle_time / 60.0f;
80 result.has_motion = !idle_time;
81 } else if ((value_type == 0x1018) && (value_length == 1)) {
82 result.is_light = data[0];
83 }
84 // MiaoMiaoce temperature, 4 bytes, float, 0.1 °C
85 else if ((value_type == 0x4C01) && (value_length == 4)) {
86 const uint32_t int_number = encode_uint32(data[3], data[2], data[1], data[0]);
87 float temperature;
88 std::memcpy(&temperature, &int_number, sizeof(temperature));
89 result.temperature = temperature;
90 }
91 // MiaoMiaoce humidity, 1 byte, 8-bit unsigned integer, 1 %
92 else if ((value_type == 0x4C02) && (value_length == 1)) {
93 result.humidity = data[0];
94 }
95 // XMWSDJ04MMC humidity, 4 bytes, float, 0.1 °C
96 else if ((value_type == 0x4C08) && (value_length == 4)) {
97 const uint32_t int_number = encode_uint32(data[3], data[2], data[1], data[0]);
98 float humidity;
99 std::memcpy(&humidity, &int_number, sizeof(humidity));
100 result.humidity = humidity;
101 } else {
102 return false;
103 }
104
105 return true;
106}
107
108bool parse_xiaomi_message(const std::vector<uint8_t> &message, XiaomiParseResult &result) {
109 result.has_encryption = message[0] & 0x08; // update encryption status
110 if (result.has_encryption) {
111 ESP_LOGVV(TAG, "parse_xiaomi_message(): payload is encrypted, stop reading message.");
112 return false;
113 }
114
115 // Data point specs
116 // Byte 0: type
117 // Byte 1: fixed 0x10
118 // Byte 2: length
119 // Byte 3..3+len-1: data point value
120
121 const uint8_t *payload = message.data() + result.raw_offset;
122 uint8_t payload_length = message.size() - result.raw_offset;
123 uint8_t payload_offset = 0;
124 bool success = false;
125
126 if (payload_length < 4) {
127 ESP_LOGVV(TAG, "parse_xiaomi_message(): payload has wrong size (%d)!", payload_length);
128 return false;
129 }
130
131 while (payload_length > 3) {
132 if (payload[payload_offset + 1] != 0x10 && payload[payload_offset + 1] != 0x00 &&
133 payload[payload_offset + 1] != 0x4C && payload[payload_offset + 1] != 0x48) {
134 ESP_LOGVV(TAG, "parse_xiaomi_message(): fixed byte not found, stop parsing residual data.");
135 break;
136 }
137
138 const uint8_t value_length = payload[payload_offset + 2];
139 if ((value_length < 1) || (value_length > 4) || (payload_length < (3 + value_length))) {
140 ESP_LOGVV(TAG, "parse_xiaomi_message(): value has wrong size (%d)!", value_length);
141 break;
142 }
143
144 const uint16_t value_type = encode_uint16(payload[payload_offset + 1], payload[payload_offset + 0]);
145 const uint8_t *data = &payload[payload_offset + 3];
146
147 if (parse_xiaomi_value(value_type, data, value_length, result))
148 success = true;
149
150 payload_length -= 3 + value_length;
151 payload_offset += 3 + value_length;
152 }
153
154 return success;
155}
156
158 XiaomiParseResult result;
159 if (!service_data.uuid.contains(0x95, 0xFE)) {
160 ESP_LOGVV(TAG, "parse_xiaomi_header(): no service data UUID magic bytes.");
161 return {};
162 }
163
164 auto raw = service_data.data;
165 result.has_data = raw[0] & 0x40;
166 result.has_capability = raw[0] & 0x20;
167 result.has_encryption = raw[0] & 0x08;
168
169 if (!result.has_data) {
170 ESP_LOGVV(TAG, "parse_xiaomi_header(): service data has no DATA flag.");
171 return {};
172 }
173
174 static uint8_t last_frame_count = 0;
175 if (last_frame_count == raw[4]) {
176 ESP_LOGVV(TAG, "parse_xiaomi_header(): duplicate data packet received (%d).", static_cast<int>(last_frame_count));
177 result.is_duplicate = true;
178 return {};
179 }
180 last_frame_count = raw[4];
181 result.is_duplicate = false;
182 result.raw_offset = result.has_capability ? 12 : 11;
183
184 const uint16_t device_uuid = encode_uint16(raw[3], raw[2]);
185
186 if (device_uuid == 0x0098) { // MiFlora
188 result.name = "HHCCJCY01";
189 } else if (device_uuid == 0x01aa) { // round body, segment LCD
191 result.name = "LYWSDCGQ";
192 } else if (device_uuid == 0x015d) { // FlowerPot, RoPot
194 result.name = "HHCCPOT002";
195 } else if (device_uuid == 0x02df) { // Xiaomi (Honeywell) formaldehyde sensor, OLED display
197 result.name = "JQJCY01YM";
198 } else if (device_uuid == 0x03dd) { // Philips/Xiaomi BLE nightlight
200 result.name = "MUE4094RT";
201 result.raw_offset -= 6;
202 } else if (device_uuid == 0x0347 || // ClearGrass-branded, round body, e-ink display
203 device_uuid == 0x0B48) { // Qingping-branded, round body, e-ink display — with bindkeys
205 result.name = "CGG1";
206 } else if (device_uuid == 0x03bc) { // VegTrug Grow Care Garden
208 result.name = "GCLS002";
209 } else if (device_uuid == 0x045b) { // rectangular body, e-ink display
211 result.name = "LYWSD02";
212 } else if (device_uuid == 0x2542) { // rectangular body, e-ink display — with bindkeys
214 result.name = "LYWSD02MMC";
215 if (raw.size() == 19)
216 result.raw_offset -= 6;
217 } else if (device_uuid == 0x040a) { // Mosquito Repellent Smart Version
219 result.name = "WX08ZM";
220 } else if (device_uuid == 0x0576) { // Cleargrass (Qingping) alarm clock, segment LCD
222 result.name = "CGD1";
223 } else if (device_uuid == 0x066F) { // Cleargrass (Qingping) Temp & RH Lite
225 result.name = "CGDK2";
226 } else if (device_uuid == 0x055b) { // small square body, segment LCD, encrypted
228 result.name = "LYWSD03MMC";
229 } else if (device_uuid == 0x1203) { // small square body, e-ink display, encrypted
231 result.name = "XMWSDJ04MMC";
232 if (raw.size() == 19)
233 result.raw_offset -= 6;
234 } else if (device_uuid == 0x07f6) { // Xiaomi-Yeelight BLE nightlight
236 result.name = "MJYD02YLA";
237 if (raw.size() == 19)
238 result.raw_offset -= 6;
239 } else if (device_uuid == 0x06d3) { // rectangular body, e-ink display with alarm
241 result.name = "MHOC303";
242 } else if (device_uuid == 0x0387) { // square body, e-ink display
244 result.name = "MHOC401";
245 } else if (device_uuid == 0x0A83) { // Qingping-branded, motion & ambient light sensor
247 result.name = "CGPR1";
248 if (raw.size() == 19)
249 result.raw_offset -= 6;
250 } else if (device_uuid == 0x0A8D) { // Xiaomi Mi Motion Sensor 2
252 result.name = "RTCGQ02LM";
253 if (raw.size() == 19)
254 result.raw_offset -= 6;
255 } else {
256 ESP_LOGVV(TAG, "parse_xiaomi_header(): unknown device, no magic bytes.");
257 return {};
258 }
259
260 return result;
261}
262
263bool decrypt_xiaomi_payload(std::vector<uint8_t> &raw, const uint8_t *bindkey, const uint64_t &address) {
264 if ((raw.size() != 19) && ((raw.size() < 22) || (raw.size() > 24))) {
265 ESP_LOGVV(TAG, "decrypt_xiaomi_payload(): data packet has wrong size (%d)!", raw.size());
266 ESP_LOGVV(TAG, " Packet : %s", format_hex_pretty(raw.data(), raw.size()).c_str());
267 return false;
268 }
269
270 uint8_t mac_reverse[6] = {0};
271 mac_reverse[5] = (uint8_t) (address >> 40);
272 mac_reverse[4] = (uint8_t) (address >> 32);
273 mac_reverse[3] = (uint8_t) (address >> 24);
274 mac_reverse[2] = (uint8_t) (address >> 16);
275 mac_reverse[1] = (uint8_t) (address >> 8);
276 mac_reverse[0] = (uint8_t) (address >> 0);
277
278 XiaomiAESVector vector{.key = {0},
279 .plaintext = {0},
280 .ciphertext = {0},
281 .authdata = {0x11},
282 .iv = {0},
283 .tag = {0},
284 .keysize = 16,
285 .authsize = 1,
286 .datasize = 0,
287 .tagsize = 4,
288 .ivsize = 12};
289
290 vector.datasize = (raw.size() == 19) ? raw.size() - 12 : raw.size() - 18;
291 int cipher_pos = (raw.size() == 19) ? 5 : 11;
292
293 const uint8_t *v = raw.data();
294
295 memcpy(vector.key, bindkey, vector.keysize);
296 memcpy(vector.ciphertext, v + cipher_pos, vector.datasize);
297 memcpy(vector.tag, v + raw.size() - vector.tagsize, vector.tagsize);
298 memcpy(vector.iv, mac_reverse, 6); // MAC address reverse
299 memcpy(vector.iv + 6, v + 2, 3); // sensor type (2) + packet id (1)
300 memcpy(vector.iv + 9, v + raw.size() - 7, 3); // payload counter
301
302 mbedtls_ccm_context ctx;
303 mbedtls_ccm_init(&ctx);
304
305 int ret = mbedtls_ccm_setkey(&ctx, MBEDTLS_CIPHER_ID_AES, vector.key, vector.keysize * 8);
306 if (ret) {
307 ESP_LOGVV(TAG, "decrypt_xiaomi_payload(): mbedtls_ccm_setkey() failed.");
308 mbedtls_ccm_free(&ctx);
309 return false;
310 }
311
312 ret = mbedtls_ccm_auth_decrypt(&ctx, vector.datasize, vector.iv, vector.ivsize, vector.authdata, vector.authsize,
313 vector.ciphertext, vector.plaintext, vector.tag, vector.tagsize);
314 if (ret) {
315 uint8_t mac_address[6] = {0};
316 memcpy(mac_address, mac_reverse + 5, 1);
317 memcpy(mac_address + 1, mac_reverse + 4, 1);
318 memcpy(mac_address + 2, mac_reverse + 3, 1);
319 memcpy(mac_address + 3, mac_reverse + 2, 1);
320 memcpy(mac_address + 4, mac_reverse + 1, 1);
321 memcpy(mac_address + 5, mac_reverse, 1);
322 ESP_LOGVV(TAG, "decrypt_xiaomi_payload(): authenticated decryption failed.");
323 ESP_LOGVV(TAG, " MAC address : %s", format_mac_address_pretty(mac_address).c_str());
324 ESP_LOGVV(TAG, " Packet : %s", format_hex_pretty(raw.data(), raw.size()).c_str());
325 ESP_LOGVV(TAG, " Key : %s", format_hex_pretty(vector.key, vector.keysize).c_str());
326 ESP_LOGVV(TAG, " Iv : %s", format_hex_pretty(vector.iv, vector.ivsize).c_str());
327 ESP_LOGVV(TAG, " Cipher : %s", format_hex_pretty(vector.ciphertext, vector.datasize).c_str());
328 ESP_LOGVV(TAG, " Tag : %s", format_hex_pretty(vector.tag, vector.tagsize).c_str());
329 mbedtls_ccm_free(&ctx);
330 return false;
331 }
332
333 // replace encrypted payload with plaintext
334 uint8_t *p = vector.plaintext;
335 for (std::vector<uint8_t>::iterator it = raw.begin() + cipher_pos; it != raw.begin() + cipher_pos + vector.datasize;
336 ++it) {
337 *it = *(p++);
338 }
339
340 // clear encrypted flag
341 raw[0] &= ~0x08;
342
343 ESP_LOGVV(TAG, "decrypt_xiaomi_payload(): authenticated decryption passed.");
344 ESP_LOGVV(TAG, " Plaintext : %s, Packet : %d", format_hex_pretty(raw.data() + cipher_pos, vector.datasize).c_str(),
345 static_cast<int>(raw[4]));
346
347 mbedtls_ccm_free(&ctx);
348 return true;
349}
350
351bool report_xiaomi_results(const optional<XiaomiParseResult> &result, const std::string &address) {
352 if (!result.has_value()) {
353 ESP_LOGVV(TAG, "report_xiaomi_results(): no results available.");
354 return false;
355 }
356
357 ESP_LOGD(TAG, "Got Xiaomi %s (%s):", result->name.c_str(), address.c_str());
358
359 if (result->temperature.has_value()) {
360 ESP_LOGD(TAG, " Temperature: %.1f°C", *result->temperature);
361 }
362 if (result->humidity.has_value()) {
363 ESP_LOGD(TAG, " Humidity: %.1f%%", *result->humidity);
364 }
365 if (result->battery_level.has_value()) {
366 ESP_LOGD(TAG, " Battery Level: %.0f%%", *result->battery_level);
367 }
368 if (result->conductivity.has_value()) {
369 ESP_LOGD(TAG, " Conductivity: %.0fµS/cm", *result->conductivity);
370 }
371 if (result->illuminance.has_value()) {
372 ESP_LOGD(TAG, " Illuminance: %.0flx", *result->illuminance);
373 }
374 if (result->moisture.has_value()) {
375 ESP_LOGD(TAG, " Moisture: %.0f%%", *result->moisture);
376 }
377 if (result->tablet.has_value()) {
378 ESP_LOGD(TAG, " Mosquito tablet: %.0f%%", *result->tablet);
379 }
380 if (result->is_active.has_value()) {
381 ESP_LOGD(TAG, " Repellent: %s", (*result->is_active) ? "on" : "off");
382 }
383 if (result->has_motion.has_value()) {
384 ESP_LOGD(TAG, " Motion: %s", (*result->has_motion) ? "yes" : "no");
385 }
386 if (result->is_light.has_value()) {
387 ESP_LOGD(TAG, " Light: %s", (*result->is_light) ? "on" : "off");
388 }
389 if (result->button_press.has_value()) {
390 ESP_LOGD(TAG, " Button: %s", (*result->button_press) ? "pressed" : "");
391 }
392
393 return true;
394}
395
397 // Previously the message was parsed twice per packet, once by XiaomiListener::parse_device()
398 // and then again by the respective device class's parse_device() function. Parsing the header
399 // here and then for each device seems to be unnecessary and complicates the duplicate packet filtering.
400 // Hence I disabled the call to parse_xiaomi_header() here and the message parsing is done entirely
401 // in the respective device instance. The XiaomiListener class is defined in __init__.py and I was not
402 // able to remove it entirely.
403
404 return false; // with true it's not showing device scans
405}
406
407} // namespace xiaomi_ble
408} // namespace esphome
409
410#endif
uint8_t address
Definition bl0906.h:4
uint8_t raw[35]
Definition bl0939.h:0
bool contains(uint8_t data1, uint8_t data2) const
Definition ble_uuid.cpp:125
bool has_value() const
Definition optional.h:92
bool parse_device(const esp32_ble_tracker::ESPBTDevice &device) override
bool decrypt_xiaomi_payload(std::vector< uint8_t > &raw, const uint8_t *bindkey, const uint64_t &address)
optional< XiaomiParseResult > parse_xiaomi_header(const esp32_ble_tracker::ServiceData &service_data)
bool parse_xiaomi_value(uint16_t value_type, const uint8_t *data, uint8_t value_length, XiaomiParseResult &result)
bool parse_xiaomi_message(const std::vector< uint8_t > &message, XiaomiParseResult &result)
bool report_xiaomi_results(const optional< XiaomiParseResult > &result, const std::string &address)
Providing packet encoding functions for exchanging data with a remote host.
Definition a01nyub.cpp:7
constexpr uint32_t encode_uint24(uint8_t byte1, uint8_t byte2, uint8_t byte3)
Encode a 24-bit value given three bytes in most to least significant byte order.
Definition helpers.h:127
std::string format_hex_pretty(const uint8_t *data, size_t length, char separator, bool show_length)
Format a byte array in pretty-printed, human-readable hex format.
Definition helpers.cpp:261
std::string format_mac_address_pretty(const uint8_t *mac)
Definition helpers.cpp:244
constexpr uint32_t encode_uint32(uint8_t byte1, uint8_t byte2, uint8_t byte3, uint8_t byte4)
Encode a 32-bit value given four bytes in most to least significant byte order.
Definition helpers.h:131
constexpr uint16_t encode_uint16(uint8_t msb, uint8_t lsb)
Encode a 16-bit value given the most and least significant byte.
Definition helpers.h:123
enum esphome::xiaomi_ble::XiaomiParseResult::@155 type
uint16_t temperature
Definition sun_gtil2.cpp:12