Freetz-Ble

BLE Advertisement controller for freetz (FRITZ!Box)

This proof of concept shows a mode to continuously collect BLE advertisements sent by Smart Home wireless consumer sensors via a FRITZ!Box router/modem and store data in clear form to a local DB in the FRITZ!Box. At the moment the code is just an example.

The BLE stack is managed through an Ai-Thinker TB-03F-KIT adapter module connected via USB-to-serial interface.

To configure a FRITZ!Box device in order to run this project, freetz-ng must be installed. freetz is a modified extension of the AVM stock firmware.

While freetz directly supports Bluetooth 2.0 USB adapters with BlueZ protocol stack (installing related packages), it cannot manage modern BLE 5.x devices (especially with support of passive scanning to preserve the sensor coin battery and LE Coded PHY¹ for longer range on sensors supporting this coding schema) due to the need of updated Linux kernel, with at least version 5.10 (current FRITZ!Box kernel is 4.9), and updated BlueZ, with at least version 5.56 (current BlueZ in freetz is the old 2.25).

Using a BLE SoC chip interfaced via a USB-to-serial adapter, like the Ai-Thinker TB-03F-KIT, the Bluetooth stack is completely offloaded, saving kernel and user space resources, other than solving incompatibilities.

The low-cost Ai-Thinker TB-03F-KIT includes a Telink TLSR8253 BLE 5.0 SoC. Main features of the module:

• it completely offloads the BLE stack, offering USB serial port via CH340 USB-to-serial interface (and related driver is included in freetz),
• it includes advanced BLE 5 support, comprehensive of passive scanning, Mesh², Coded PHY¹,
• it features 2 LEDs, a 3-color RGB LED, a reset button and a user-defined button,
• it also provides configurable PWM, I2C, GPIO and ADC interfaces, so that, other than BLE, it can also connect the FRITZ!Box with local sensors (like, e.g., an I2C air quality sensor chip),
• it allows to distance the BLE antenna from the FRITZ!Box, for reduced interferences.

This project includes a Python module with symmetric parsing and building support of a wide set of BLE modules:

• potentially all Xiaomi Mijia BLE sensors,
• all BT Home DIY sensors implementing BTHome v1 and v2 protocols,
• Xiaomi Mijia Thermometers with custom firmware (ATC_MiThermometer) developed by atc1441 and pvvx.

At the moment, the following BLE home sensors have been tested:

• SJWS01LM (Xiaomi Mijia Flood Detector)
• MCCGQ02HL (Xiaomi Mijia Door and Window Sensor 2)
• LYWSD03MMC (Xiaomi Mijia Temperature And Humidity Monitor)

Tested AVM device (at the moment): FRITZ!Box 7590 AX.

When the TB-03F-KIT is connected to the FRITZ!Box device, freetz allows accessing it via the serial device driver /dev/ttyUSB0.

Project software

Included folders in this repository:

• ble-adv-telink: Ai-Thinker TB-03F-KIT firmware (including compilation and installation instructions),

• freetz-ble-python: test Python code (running with freetz),

• aes_ccm_codec: shared library to support AES CCM encryption, which is typically used by consumer BLE devices; this library can be invoked by Python code.

For each software, see instructions README in the related project folder.

Configuration notes

Suggested make menuconfig configuration:

• Packages > Python 2.7.18 > Compress .pyc files; all binary modules (but test)
• Debug helpers > usbutils 007
• Shared libraries > USB&FTDI > libusb-1.0
• Kernel Modules: drivers > ch341.ko and usbserial.ko
• Busybox lsusb

Move Python and all other possible packages to freetz External Processing.

Footnotes

1. Coded PHY is not currently supported. ↩ ↩²

2. Mesh is not currently supported. ↩