Skip to content

Latest commit

 

History

History
75 lines (60 loc) · 4.68 KB

README.md

File metadata and controls

75 lines (60 loc) · 4.68 KB

ble_adv_handler

Description

Technical component interacting with the ESP32 BLE ADV Stack. It controls the capture of BLE ADV Messages emitted by Phone Apps and Remotes, and the publication of BLE ADV Messages to controlled device and emitted by ble_adv_controller.

Most of the time there is no need to define it, it is automatically created by other components. It is mostly used at setup stage when you want to listen to the traffic generated by your Phone App or your remote and extract the main parameters needed to configure your ble_adv_controller or your ble_adv_remote. It can also be used to add some logs useful for developers.

Variables

The following variables are available:

  • scan_activated (Optional, Default: True): Put to False to fully deactivate the capture of BLE ADV packets, this will also completely deactivate the functionalities linked to ble_adv_remote.
  • check_reencoding (Optional, Default: False): Debug feature for developers - when a message is received and decoded, it is re encoded with the same encoders and parameters in order to check the exact same message is generated.
  • log_raw (Optional, Default: False): On each new raw BLE ADV message received, log it.
  • log_command (Optional, Default: False): On each ble adv message decoded, log the decoded command.
  • log_config (Optional, Default: False): On each ble adv message decoded, log the config used for the successful decoding.
  • use_max_tx_power (Optional, Default: False): Try to use the max TX Power for the Advertising stack, as defined in Espressif doc. Setup to 'true' if your ESP32 is far from your device and have difficulties to communicate with it.

Listening to traffic

The following configuration allows you to listen to traffic and to log:

  • The raw messages
  • The decoded command
  • The main config parameters
ble_adv_handler:
  log_raw: true
  log_command: true
  log_config: true

WARN: put those options to true ONLY when initially listening to traffic. Once you have configured everything it is recommended to put those options to false (and to configure the logger in INFO mode at least...) as else it will produce unnecessary process and logs and some messages may be lost.

When a button is pressed on the Phone App / Physical Remote, this will produce the following logs:

log_raw:
[13:59:59][D][ble_adv_handler:251]: raw - 02.01.02.1B.16.F0.08.10.00.16.2D.64.D5.B5.BD.22.39.C3.42.12.06.86.2F.C6.63.3D.30.F7.76.1E.21 (31)

log_command:
[13:59:59][D][remote - v3:261]: Decoded OK - tx: 39, gen: LIGHT_ON, enc: 0x10 - param1 0x00 - args[0,0]

log_config:
[13:59:59][D][ble_adv_handler:274]: Configuration Parameters:
[13:59:59]  encoding: remote
[13:59:59]  variant: v3
[13:59:59]  forced_id: 0x2227574
[13:59:59]  index: 0

The log_raw is useful for developers if no command / config could be decoded, or for users that want to send raw commands from HA directly.

The log_command is useful for developers in case you have an inconsistent behaviour from your remote / phone App.

The log_config is to be used to have the parameters needed to setup a ble_adv_controller or a ble_adv_remote.

The phone apps and remotes are producing several messages at the same time for a single button pressed as they send messages for each variants, so you will see several config.

  • for use in ble_adv_remote, you can use any of those config, prefer the one with highest variant version
  • for use in ble_adv_controller, you have to find out which one effectivelly controls the device, you can test them one by one or use the highest variant and then use the Dynamic configuration to switch the variant.

Raw decoding Service

If you captured a raw advertising message emitted by a phone app or a remote, you can try to have it decoded as if it was emitted by a Phone App / Remote and captured by previously defined method.

Use this HA service:

esphome: <device_name>_raw_decode

Just put the raw hexa string in the raw parameters, accepted formats (leading 0x, trailing length, spaces and dots are removed automatically):

0201021B03F9084913F069254E3151BA32080A24CB3B7C71DC8BB89708D04C
0x0201021B03F9084913F069254E3151BA32080A24CB3B7C71DC8BB89708D04C
02 01 02 1B 03 F9 08 49 13 F0 69 25 4E 31 51 BA 32 08 0A 24 CB 3B 7C 71 DC 8B B8 97 08 D0 4C
02.01.02.1B.03.F9.08.49.13.F0.69.25.4E.31.51.BA.32.08.0A.24.CB.3B.7C.71.DC.8B.B8.97.08.D0.4C
02.01.02.1B.03.F9.08.49.13.F0.69.25.4E.31.51.BA.32.08.0A.24.CB.3B.7C.71.DC.8B.B8.97.08.D0.4C (31)

You will see the result of the decoding in the logs of the application (see previous section how to configue this).