A small guide to talk about the architecture of the components and where to find relevant info / how to contribute.

The Bluetooth Low Energy Advertising (BLE ADV)

Those components are based on BLE ADV Stack, which is the Bluetooth equivalent of Network UDP Broadcast: messages are emitted by a controller (Phone App, physical remote, ESP32) without waiting for an answer, and on the other side devices (ceiling Fan / lights) are listening to the whole traffic and tries to discriminate what is directed to them and extract the command to be applied.

This technology was clearly NOT created for the communication of commands in between a controller and a device, it is supposed to advertise services so that a controller can know a device is near and how to communicate with it. Still this is the technology that was chosen by manufacturers to create Phone App, physical remote and devices, not sure why but this is what we need to cope with!

More details HERE.

Software Architecture

There are 3 esphome components:

• ble_adv_handler

  The main component containing most of the technical framework (interaction with ESP32 BLE ADV Stack, registration of Codecs and Translators, Orchestration of BleAdvDevice), and the functional stack specific to each supported Application (definition of Codecs and Translators)

• ble_adv_controller

  The component representing a Controller. It interacts with HA through Entities (Fan / Light) and with the ble_adv_handler as a BleAdvDevice.

• ble_adv_remote

  The component representing a Physical Remote. It interacts with the ble_adv_handler Orchestrator as a BleAdvDevice.

More Details HERE.

Contributing

There is no need to understand the framework to be able to contribute by adding a codec and a translator for a Physical Remote. Supporting a new Phone Application / Physical only requires a few tasks:

• Adding a codec Class in the software: for a brand new Phone Application it is mandatory, it controls how a BleAdvEncCmd is encoded / decoded into a BLE ADV message
• Adding a translator definition (ble_adv_handler/translator.py). This definition is used to generate Cpp code.
• Adding a codec definition (ble_adv_handler/codec.py) that references the codec Class to use (and its parameters) and the translator to use

More details HERE

Anyone can contribute by opening Pull Requests, still there is no test for those components so modifying the framework should be done with extreme care!!!

Reverse Engineering

Supporting a new Phone Application means understanding how to convert generic commands such as 'turn light ON' or 'set fan speed to 3' into the BLE ADV message sent by the application and understood by the controlled device. One can try to guess, it may be feasible if the encoding only consists in aggregating data such as transaction count, command code and parameters, identifier, but most of the time it can be much more complex as the applications are often doing 'data whitening' or 'encryption' that can hardly be guessed just by looking at the data. Therefore it is needed to find how those messages are encoded and to do so one need to extract the software of the application from its apk: this is called reverse engineering.

More details HERE