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/nimble: Run the eventq in micropython.schedule.

closedby andrewleechopened 2020-09-13updated 2020-11-13

extmod

This PR changes the background nimble processing to run the nimble eventq handler via schedule() and remove the ringbuffer system.

This change basically ensures that the python IRQ callback for any BLE operation is run to completion before the next BLE operation is handled.

I've only tested the peripheral mode running my application on reader so far, but it appears to be running very reliably - I've had no transmission sync/order/race issues for many hours where previously I'd have a glitch at least every 10-20 minutes.

I'm looking at how to achieve the same in btstack and it appears far less straightforward there. I can't find anything that looks like a similar functional boundary to split across to schedule().
Event callbacks in btstack_packet_handler() are typically run during the processing of mp_bluetooth_hci_poll_h4(), not going via any sort of event queue.

Perhaps I just need to run the entire mp_bluetooth_hci_poll() function via schedule?

Assessment

S Sonnet · medium

Issue #16577 reports a documentation contradiction: BLE event handling docs recommend creating ringbuffer parameter copies (object instantiation) inside the callback, while ISR guidelines prohibit object instantiation in interrupt handlers. PR #6438 proposes removing the ringbuffer system entirely by routing NimBLE event queue handling through micropython.schedule(), and does modify docs/library/ubluetooth.rst (6 deletions). If merged, the architectural change would eliminate the documented ringbuffer approach and the contradiction with it. However, issue #16577 has a much higher number than PR #6438, suggesting the issue was filed after the PR — meaning either the PR was never merged, or the docs still carried the contradiction post-merge. The PR addresses the root architecture rather than the documentation inconsistency directly, and there is no explicit "Fixes #16577" reference. The connection is real but the PR does not resolve the documentation issue as filed.

Suggested action

Link PR #6438 as context for issue #16577. If PR #6438 was merged, check whether the ringbuffer recommendation still appears in the current docs and update accordingly. If PR #6438 is still open, note that merging it would make the docs fix a natural consequence. Either way, the docs issue should be resolved on its own terms — the current documentation should be audited against the actual current implementation to ensure ISR guidance is internally consistent.