QUERY · ISSUE

docs: BLE Event handling seems to contradict general guidelines for IRQ handling

openby 32BTopened 2025-01-13updated 2025-11-06

docs

Documentation URL

https://docs.micropython.org/en/latest/library/bluetooth.html#event-handling

Description

In BLE event handling a suggestion is given to create copies of the ringbuffer parameters. This however, would violate the general guidelines given for interrupt routines which specifically warn against instantiating objects.
https://github.com/micropython/micropython/blob/99ac8193ea299e6d836b076149f561e58226ede6/docs/reference/isr_rules.rst?plain=1#L102

Code of Conduct

Yes, I agree

CANDIDATE · PULL REQUEST

extmod/modbluetooth: Misc fixes and improvements

closedby jimmoopened 2019-10-14updated 2019-10-15

extmod

Avoid confusing ENOMEM raised from gap_advertise if there is currently an active connection. This refers to the static connection buffer pre-allocated by Nimble (nothing to do with MicroPython heap memory). Fixed by increasing the max number of connections from 1 to 4 (which is a worthwhile fix anyway).
Clarify behaviour of adv_data and resp_data params to gap_advertise.
Fix IRQ_GATTS_WRITE having conn_handle and value_handle the wrong way around in the data tuple.
Address some issues with the ringbuf handling avoiding a potential overflow.
Pin the NimBLE task on ESP32 to the app core (see commit for more info).
Misc documentation fixes.
Make gap_connect return bool rather than raising OSError(MP_ENOTCONN) when already disconnected.

Assessment

S Sonnet · medium

PR #5211 modifies both docs/library/bluetooth.rst (22 additions, 4 deletions) and ringbuf handling in extmod/modbluetooth.c, overlapping with the components named in the issue. However, the issue's concern is a specific documentation contradiction: the BLE event handling docs recommend making copies of ringbuffer parameters inside the IRQ callback (implying object allocation), which conflicts with the general ISR rules (isr_rules.rst) that explicitly prohibit object instantiation in interrupt context. PR #5211 addresses ringbuf overflow prevention and misc doc clarifications, but there is no indication it resolves this cross-document philosophical inconsistency. The PR also predates the issue by a wide margin (low PR number vs. high issue number), making it unlikely the PR was written to address this concern.

Suggested action

Leave issue #16577 open. The docs contradiction between `docs/library/bluetooth.rst` event handling guidance and `docs/reference/isr_rules.rst` object-allocation warnings needs a targeted documentation fix — either clarifying that BLE IRQ callbacks run in a scheduled context (not a hard ISR) where allocation is permitted, or revising the BLE docs to avoid recommending allocation. Reference PR #5211 as context for the ringbuf design, but it does not close this issue.