FreeRTOS Task Design Patterns for BLE Applications
Most ESP32 BLE tutorials you’ll find online handle everything inside a single GATT callback. It works on the bench. Then you deploy to production, add a sensor polling loop and some logging, and suddenly your device drops connections every 45 seconds like clockwork. The supervision timeout fires because your BLE host task was starved while your application code hogged the CPU formatting a JSON string inside a write callback.
The root cause is always the same: no deliberate task architecture. FreeRTOS gives you complete flexibility in how you structure tasks. BLE stacks, on the other hand, are deeply opinionated about execution context, timing, and memory. If you don’t design around those constraints, you get dropped connections, stack overflows, and intermittent bugs that only appear under load.
This article gives you a structural blueprint for FreeRTOS BLE task architecture, covering priority assignment, stack sizing, and inter-task communication. The patterns are stack-agnostic where possible, with ESP-IDF/NimBLE specifics called out where concrete examples help.
Why BLE Punishes Sloppy Task Design
BLE isn’t like polling a UART or reading an I2C sensor. It’s event-driven and time-critical at the protocol level. A BLE connection has a supervision timeout, typically a few seconds, and if the host stack can’t process HCI events from the controller within that window, the link dies. No graceful degradation, just a disconnect.
The BLE host task sits at the center of this. It processes HCI packets, manages connection state machines, handles pairing, and dispatches callbacks to your application code. If that task gets preempted by a lower-priority concern, or worse, if your code blocks inside one of its callbacks, every BLE connection on the device suffers.
There’s a memory dimension too. BLE host internals produce deep, variable-depth call chains. A GATT write callback might traverse encryption routines, attribute lookup, and then your handler. Stack sizing isn’t something you can eyeball.
Most BLE stacks (NimBLE, Bluedroid, the Nordic SoftDevice) already create internal tasks. Your job isn’t to write the host loop. It’s to design everything around it correctly.
The Three-Tier RTOS BLE Architecture
The pattern that works reliably across projects is a three-tier model separating the BLE host, your BLE event processing, and your application logic into distinct tasks at distinct priorities:
+---------------------------------------------+
| RTOS Task Architecture |
+---------------------------------------------+
| |
| Priority HIGH |
| +----------------------------------------+ |
| | BLE Host Task | |
| | (created by stack - NimBLE, etc.) | |
| | Stack: 4-8 KB | |
| +----┬───────────────────────────────────+ |
| │ events/callbacks |
| ▼ |
| Priority MEDIUM |
| +----------------------------------------+ |
| | BLE App Task (your code) | |
| | Receives events via FreeRTOS Queue | |
| | Processes GATT reads/writes, | |
| | state machine transitions | |
| | Stack: 3-4 KB | |
| +----┬───────────────────────────────────+ |
| │ processed data / commands |
| ▼ |
| Priority LOW-MEDIUM |
| +----------------------------------------+ |
| | Application Task(s) | |
| | Sensor reads, UI, business logic | |
| | Stack: 2-4 KB | |
| +----------------------------------------+ |
| |
+---------------------------------------------+Tier 1: BLE Host Task. You don’t write this task; the BLE stack creates it. On ESP-IDF, nimble_port_freertos_init() spawns it, and you configure its priority via menuconfig. This task must run unimpeded. Its sole job is processing HCI events and managing the BLE state machine.
Tier 2: BLE App Task. This is your critical design decision. It bridges the gap between raw BLE stack events and your application. It blocks on a FreeRTOS queue, wakes when a BLE event arrives (GATT write, connection state change, notification confirmation), and processes it. This is where your GATT-level state machine lives: decoding characteristic writes, validating data, preparing responses.
Tier 3: Application Tasks. Sensor polling, display updates, business logic, data logging. These tasks consume processed data from the BLE App Task and post commands back when they need to trigger BLE operations (like sending a notification). They should never directly call BLE APIs that depend on the host task processing at equal or higher priority. That’s a textbook priority inversion path.
This separation means a slow sensor read can’t block a BLE event, and a burst of GATT writes can’t starve your application logic indefinitely. Each tier has a clear contract and a clear failure mode.
Getting FreeRTOS Task Priority Right for BLE
Priority assignment is where most architectures succeed or fail. The general rule: BLE Controller > BLE Host > BLE App > Application Logic > Idle.
Priority | Task | Rationale
----------|--------------------|----------------------------------
highest | BLE Controller | Hard real-time radio timing
| | (often ISR/HW — not your concern)
high (5) | BLE Host | Must process HCI without delay
med (3) | BLE App / Events | Event queue consumer
med (2) | App Logic / Sensors | Can tolerate slight delays
low (1) | Logging / Telemetry | Best-effort
idle (0) | IDLE task | FreeRTOS housekeepingTwo common mistakes kill BLE reliability here.
Mistake 1: Same priority for BLE Host and BLE App. With configUSE_TIME_SLICING enabled (the default), same-priority tasks round-robin on each tick. This means your BLE App Task gets interleaved with host processing on a millisecond-level schedule. The host task should always preempt your app task when it has work to do. Assign them different priorities.
Mistake 2: Sensor or UI tasks above the BLE Host. A blocking I2C read at priority 6 will starve your priority-5 BLE host task for the duration. If that duration exceeds a connection interval or two, you’ve just caused a disconnect. For a deeper treatment of inversion scenarios and mitigation, see our FreeRTOS task priority guide.
Stack Sizing: Why BLE Tasks Need More Than You Think
BLE tasks consume more stack than typical embedded tasks. The host task call chain during pairing can be 15+ frames deep: your GATT callback, the attribute lookup, the security manager, the encryption routines. If you’re processing data in your BLE App Task (deserializing CBOR, parsing protobuf, building JSON), that adds another layer.
Start here:
- BLE Host Task: 4,096–8,192 bytes (8 KB if encryption/pairing is involved)
- BLE App Task: 3,072–4,096 bytes
- Application Tasks: 2,048–4,096 bytes depending on workload
Validate with uxTaskGetStackHighWaterMark(). This returns the minimum free stack the task has ever had, in words. The methodology matters: don’t just check it during idle operation. Force worst-case conditions. Initiate pairing, send maximum-length characteristic writes, trigger concurrent operations. If the high-water mark shows less than 20% headroom, increase the allocation. Our FreeRTOS stack sizing guide covers this methodology in detail.
One warning: stack overflow in a BLE task rarely produces a clean crash. It corrupts adjacent memory, and the symptom is typically random disconnects or garbage attribute values, the kind of bug you chase for days.
Moving BLE Events Across Tasks Without Blocking the Stack
Here’s the anti-pattern in almost every BLE tutorial: doing real work inside a GATT write callback. That callback executes in the BLE host task context. Every millisecond you spend there is a millisecond the host can’t process the next HCI event. Spend 50ms writing to flash or formatting a log message, and you’ve potentially blown a connection interval.
The fix is decoupling callbacks from processing via FreeRTOS IPC.
Pattern 1: FreeRTOS Queue (the default choice)
The BLE callback enqueues a lightweight event struct. Your BLE App Task blocks on xQueueReceive() and processes events sequentially.
// In BLE GATT write callback (runs in host task context)
void on_gatt_write(uint16_t attr_handle,
const uint8_t *data, uint16_t len) {
ble_event_t evt = {
.type = BLE_EVT_GATT_WRITE,
.handle = attr_handle,
};
memcpy(evt.payload, data, MIN(len, MAX_EVT_PAYLOAD));
evt.payload_len = len;
xQueueSendToBack(ble_event_queue, &evt, 0); // never block
}
// In BLE App Task
void ble_app_task(void *param) {
ble_event_t evt;
for (;;) {
if (xQueueReceive(ble_event_queue, &evt,
portMAX_DELAY)) {
switch (evt.type) {
case BLE_EVT_GATT_WRITE:
handle_gatt_write(&evt);
break;
// ... other event types
}
}
}
}The zero timeout on xQueueSendToBack is critical. You must never block inside the host task context. If the queue is full, you drop the event. That’s better than stalling the entire BLE stack.
Queue depth depends on your connection interval and processing speed. A 7.5ms connection interval with back-to-back writes generates events fast. Start with 10–20 slots and monitor for drops. If payloads are large (OTA data chunks, for example), enqueue a pointer to a heap-allocated buffer rather than the data itself. The consumer frees it after processing. For more on queue sizing and flow control, see our FreeRTOS queue deep-dive.
Pattern 2: Task Notifications (lightweight signals)
When the event is a simple signal (“disconnect happened,” “advertising started,” “MTU exchanged”), task notifications are faster and use zero additional RAM. You get a single 32-bit value per notification, which is enough to encode an event type or a bitfield of flags.
Use these as a complement to queues, not a replacement. They’re ideal for high-priority wake-ups where you don’t need to carry a payload.
Pattern 3: Stream Buffers (variable-length data)
For BLE serial-over-GATT profiles (custom UART-like characteristics), stream buffers provide a natural fit. They handle variable-length data with a single-writer, single-reader constraint. Useful in specific cases, but not the default choice for general BLE event handling.
OTA Over BLE: The Architecture Stress Test
OTA firmware updates over BLE are worth discussing because they stress every assumption in your task design. You’re receiving large data transfers at sustained throughput while simultaneously writing to flash, an operation that can block for 20–30ms per page erase on some chips.
Flash writes must not execute in the BLE host or BLE app task. OTA typically warrants its own task at a low-medium priority with a dedicated receive buffer, consuming chunks from the BLE App Task’s queue and writing them to flash independently.
Once your baseline three-tier architecture is solid, layering OTA on top becomes manageable rather than heroic. We’ll cover the OTA pipeline pattern in a future article.
Your Task Architecture Checklist
Before you commit your task design, verify:
- ✅ BLE Host task runs at the highest application-level priority
- ✅ Dedicated BLE App task consumes events from a FreeRTOS queue
- ✅ Application logic lives in separate, lower-priority tasks
- ✅ Zero blocking work happens inside BLE callbacks
- ✅ Stack sizes validated with
uxTaskGetStackHighWaterMark()under worst-case conditions (pairing + max writes + concurrency) - ✅ Queue depth sized for burst scenarios, not average throughput
- ✅ No two BLE-related tasks share the same priority level
Start with this architecture verbatim. Profile under real-world conditions. Then adapt based on what the numbers tell you, not what feels right. The three-tier pattern has enough separation to handle most BLE applications, from sensor beacons to connected medical devices, without structural changes.
Hubble Network connects your BLE devices directly to satellites—no gateways, no terrestrial infrastructure. Learn how it works →