Comprehensive Guide to OpenMQTTGateway BLE Parameters

This guide provides a detailed explanation of all key OpenMQTTGateway BLE parameters, including both runtime-configurable and build-time parameters. Understanding these parameters will help you optimize your gateway's performance for various use cases.

Runtime-Configurable Parameters

These parameters can be adjusted during operation using MQTT commands, allowing for easy fine-tuning without rebuilding the firmware.

1. Interval between passive scans

Parameter name: interval

Determines how often the gateway performs a passive Bluetooth scan, listening for advertisements without requesting information.

• Lower values: Quicker device detection and more up-to-date data, but may impact Wi-Fi performance and increase CPU usage.
• Higher values: Reduced network impact and CPU usage, but may miss short-lived advertisements or delay device detection.

Example MQTT command:

2. Interval between active scans

Parameter name: intervalacts

Controls how often the gateway performs an active Bluetooth scan, requesting more information from advertising devices.

• Lower values: More frequent detailed device information, but increased CPU usage and possible interference.
• Higher values: Reduced CPU usage and interference, but less frequent updates for devices requiring active scanning.

Example MQTT command:

3. Scan duration

Parameter name: scanduration

Sets the duration of each Bluetooth scan, whether passive or active.

• Shorter durations: Less CPU time used, but might miss infrequently advertising devices.
• Longer durations: More likely to catch all nearby devices, but uses more CPU time and may impact other gateway functions.

Example MQTT command:

mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/config -m '{"scanduration":3000,"save":true}'

4. Presence detection settings

Parameter name: presenceawaytimer

Determines how long the gateway waits before marking a device as "away" after it's no longer detected.

• Lower values: Quicker "away" status updates, but may lead to false "away" states for inconsistent devices.
• Higher values: Reduces false "away" states, but may delay detection of devices leaving the area.

Example MQTT command:

5. Connection interval

Parameter name: intervalcnct

Sets how often the gateway attempts to establish a direct connection with compatible Bluetooth devices.

• Shorter intervals: More frequent updates for devices requiring connections, but increases CPU usage and network traffic.
• Longer intervals: Reduced system load, but less frequent updates from connection-dependent devices.

Example MQTT command:

Build-Time Parameters

These parameters are set during compilation and require rebuilding the firmware to change. They provide low-level control over the Bluetooth scanning behavior.

1. BLE Scan Interval

Parameter name: BLEScanInterval

Defines how often the Bluetooth scanner switches channels during a scan operation.

• Default value: 52 milliseconds
• Effects:
  • Lower values: Faster device detection, but increased CPU usage.
  • Higher values: Reduced CPU usage, but potentially slower detection of all devices.

To modify (in build configuration):

# define BLEScanInterval 52 // in milliseconds

2. BLE Scan Window

Parameter name: BLEScanWindow

Defines how long the scanner listens on each channel during a scan interval.

• Default value: 30 milliseconds
• Effects:
  • Lower values: Reduced CPU time for scanning, but might miss some advertisements.
  • Higher values: Increased chance of catching advertisements, but uses more CPU time.

To modify (in build configuration):

Relationship between Scan Interval and Scan Window

• BLEScanWindow should always be less than or equal to BLEScanInterval.
• If BLEScanWindow equals BLEScanInterval, the scanner will be in continuous scan mode.
• The difference between BLEScanInterval and BLEScanWindow represents idle time between channel scans.

Example: With default values, the scanner activates every 52ms, scans for 30ms, then remains idle for 22ms before the next interval.

Conclusion

Understanding and properly configuring both runtime and build-time parameters allows for comprehensive optimization of Bluetooth scanning in OpenMQTTGateway. Start by adjusting runtime parameters for easy tweaks, and consider modifying build-time parameters if you need more fundamental changes to the scanning strategy.

Always test thoroughly after making changes to ensure your setup works as expected with your specific Bluetooth devices and use cases. The goal is to find the right balance between responsiveness, data freshness, and system performance for your particular needs.