RaftBLEManagerSettings

BLE Configuration Parameters

Setting	Description	Type	Default Value	Example / Comments
enable	Enables or disables BLE functionality.	bool	false
peripheral	Enables BLE peripheral role (advertising and connection). Note that some ESP32 devices support simultaneous peripheral and central roles but this increases resource usage and is not tested in Raft currently.	bool	true
central	Enables BLE central role (scanning only). This is used to support IoT devices like BTHome which broadcast their state in advertisements. Connection to peripherals is not currently supported in Raft.	bool	false
busConnName	The name of the bus connection used for the BLE central role when disseminating data.	string	Empty string	"BLEBus"
mtuSize	Preferred MTU size for BLE communication. This can have a significant impact on throughput and should ideally be set at the max value which is 512 unless there is a good reason not to do so.	int	512
maxPktLen	Maximum packet length for BLE communication. The Raft comms sub-system breaks messages larger than this into chunks to avoid overloading the channel.	int	500
outQSize	Size of the outbound message queue. The Raft comms sub-system uses queues to decouple tasks used to generate and send BLE messages. This setting needs to be large enough that the queue doesn't overflow and optimal setting will depend on sending rate, system load and memory availability.	int	30
taskEnable	If true, a separate task is used for sending BLE messages. This doesn't seem to significantly improve performance so is normally not enabled.	bool	false
taskCore	Core on which the BLE sending task runs.	int	0
taskPriority	Priority of the BLE sending task.	int	1
taskStack	Stack size of the BLE sending task.	int	4000
sendUseInd	Sends using indication instead of notification. This affects performance when sending from the device as Notifications are not acknowledged and Indications are.	bool	true
minMsBetweenSends	Minimum time between sending outbound messages (in milliseconds). This can be used to avoid swamping the BLE connection and helps if high priority messages are being sent along with frequent low priority ones.	int	50
outMsgsInFlightMax	Maximum number of outbound messages in flight at a time.	int	10
outMsgsInFlightMs	Timeout for outbound messages in flight (milliseconds).	int	500
outQResvNonPub	Number of queue slots reserved for non-publish messages. Publish messages are only queued if at least this many slots remain free, ensuring command responses and other high-priority messages are not blocked. Set to 0 to allow publish to use the full queue. A value >= outQSize effectively prevents publish messages from being queued.	int	10
llPacketTimePref	Preferred Link Layer packet time (in microseconds).	int	2500
llPacketLengthPref	Preferred Link Layer packet length.	int	251
advIntervalMs	BLE advertising interval (in milliseconds). Selecting a longer advertising interval reduces power consumption which can be important when running on batteries.	int	0 (uses NimBLE default)
advManufID	BLE advertising manufacturer ID	string	0x004c (Espressif)
advManufData	BLE advertising manufacturer data	string	0x123456	Hex data is added to the manufacturer data field after ID.
advManufValue	BLE advertising manufacturer value	string	serialNo	Add a value to the manufacturer data field - Serial No is currently all that is supported
advManufValueBytes	BLE advertising manufacturer value max bytes	int	4	Limit the number of bytes added to the manufacturer data field (this number is in addition to the ID and any bytes in the advManufData)
connIntvPrefMs	Preferred connection interval (in milliseconds). The minimum connection interval (7.5ms) maximizes throughput but does not allow for light-sleep to occur so may not be ideal for battery-powered devices. Longer intervals such as 50ms will reduce power consumption considerably but also reduce max throughput. This is a key balance parameter when tuning power consumption of low power devices.	int	15
connLatencyPref	Preferred connection latency.	int	0
uuidCmdRespService	UUID for the command-response service.	string	Empty string	"12345678-1234-5678-1234-567812345678"
uuidCmdRespCommand	UUID for the command characteristic.	string	Empty string	"87654321-4321-8765-4321-876543218765"
uuidCmdRespResponse	UUID for the response characteristic.	string	Empty string	"abcdef12-3456-7890-abcd-ef1234567890"
uuidFilterService	UUID for the filtering devices. Can be combined with serial number to create a UUID that can be used in WebBLE or other device filters when scanning and connecting to devices.	string	Empty string	"aa76677e-9cfd-4626-0000-000000000000"
uuidFilterMaskChars	Number of characters to replace with serial number digits in uuidFilterService (starting from right hand end of UUID as represented in string format above).	int	16
stdServices	A list of standard BLE services to enable (e.g., Battery, Device Info).	array	[]	["battery", "devInfo"]
scanPassive	In the central role, passive scanning is used if this setting is true (and advertising response packets are not requested).	bool	false
scanNoDup	Avoids duplicate scan results when scanning. This may reduce system overhead if all scans are not needed.	bool	false
scanLimited	Scans for limited advertising packets. See https://novelbits.io/bluetooth-low-energy-advertisements-part-1/	bool	false
scanBTHome	Enables scanning for BTHome devices. See https://bthome.io/	bool	false
scanIntervalMs	Scanning interval in milliseconds.	int	200
scanWindowMs	Scanning window duration in milliseconds.	int	150
scanForSecs	Duration in seconds to continue scanning - 0 indicates forever	int	0
pairIO	System I/O capability that can be used for pairing. Some BLE peripherals have a display and keyboard, others have more limited I/O.	int	3	0 = Display Only, 1 = Display Yes/No, 2 = Keyboard Only, 3 = no I/O capability, 4 = Keyboard & Display
pairSecureConn	Enables secure connections during pairing.	bool	false
supvTimeoutPrefMs	Preferred supervisory timeout in milliseconds.
int	10000
logLevel	Set logging level for this SysMod	String		N, E, W, I, D, V (None, Error, Warn, Info, Debug, Verbose)
nimLogLev	Logging level to use with NimBLE library	String		N, E, W, I, D, V (None, Error, Warn, Info, Debug, Verbose)
stdServices	JSON object StandardServices (see below)

Standard Services Configuration

Setting	Description	Type	Default Value	Example
name	Name of service.	String		DeviceInfo or Battery or HeartRate
enable	True (or 1) to enable	bool	true
read	True to enable attribute read operation	true
notify	True to use notify BLE operation for updates	false
indicate	True to use indicate BLE operation for updates	false
updateIntervalMs	time in ms between updates of the value. 0 indicates no updates. Note that read operations do not trigger an update of the value but just read the latest updated value. So it is necessary to set a non-zero update rate at a level suitable for the rate of reading (or notify/indicating) of the value.	1000
settings	A JSON Service Attribute Settings object containing settings used to access any values to be reported (see below).

Service Attribute Settings

The values reported by BLE standard services are accessed through the named-value mechanism (getNamedValue function) which requires the name of a SysMod and the name of a named-value in order to access information.

Setting	Description	Type	Default Value	Example
sysMod	Name of the SysMod to access attribute data from	String
namedValue	Name of the named-value to use for attribute data access	String

Examples

"BLEMan": {
    "enable": 1,
    "central": 0,
    "peripheral": 1,
    "outQSize": 15,
    "sendUseInd": 1,
    "advIntervalMs": 200,
    "connIntvPrefMs": 50,
    "scanIntervalMs": 200,
    "scanWindowMs": 150,
    "scanPassive": 1,
    "scanNoDup": 0,
    "scanLimited": 0,
    "scanBTHome": 1,
    "busConnName": "BusBLE",
    "uuidCmdRespService": "aa76677e-9cfd-4626-a510-0d305be57c8d",
    "uuidCmdRespCommand": "aa76677e-9cfd-4626-a510-0d305be57c8e",
    "uuidCmdRespResponse": "aa76677e-9cfd-4626-a510-0d305be57c8f",
    "logLevel": "D",
    "nimLogLev": "E",
    "stdServices":
    [
        {
            "name": "Battery",
            "enable": 1,
            "notify": 1,
            "read": 1,
            "updateIntervalMs": 30000,
            "settings": {
                "sysMod": "MyPowerManager",
                "namedValue": "batteryPC"
            }
        },
        {
            "name": "HeartRate",
            "enable": 1,
            "notify": 1,
            "read": 1,
            "updateIntervalMs": 500,
            "settings": {
                "sysMod": "MyHeartRateMonitor",
                "namedValue": "heartRate"
            }
        },
        {
            "name": "DeviceInfo",
            "enable": 1,
            "read": 1
        }
    ]
},