adafruit / adafruit/Adafruit_CircuitPython_BLE_BroadcastNet

Clarification on broadcast_time arg for broadcast()

Open
#9 1 comment 0 reactions 0 assignees View on GitHub
documentation
Dominant language
Python
Stars
14
Forks
7
PR merge metrics
No merged PRs in 30d

Description

The broadcast function in `adafruit_ble_broadcastnet` takes a `broadcast_time` argument with a default of `0.1` (100ms). The documentation is currently:

> Broadcasts the given measurement for the given broadcast time. If extended is False and the
> measurement would be too long, it will be split into multiple measurements for transmission.

This doesn't explicitly explain that if the message is split then the function actually takes N * `broadcast_time`. There's clearly two approaches here, a cap for the overall broadcast time for all "sub" packets or a period per packet to send for. I'm not sure which approach is the best but whatever is intended/implemented should be documented.

This also offers no control over the advertising interval. It's using `_ble.start_advertising` (note: `_`). The C code has advertising default interval as `(0.1f)`. If the intent is to send one packet then maybe there's a better way to do that, e.g. 0.020 interval and wait for 0.020 sounds like it achieve the same thing for sending a single packet but that returns at least 80ms earlier to caller offering more opportunity to do useful processing.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the broadcast() documentation in adafruit_ble_broadcastnet and inspect its use of _ble.start_advertising, along with the referenced C advertising default. Resolve whether broadcast_time applies to the whole broadcast or each split packet, and document the intended advertising-interval behavior and completion semantics.

Written by the indexing model from the issue text.

Assessment

Tech stack
c, python
Domain
documentation, embedded-iot, networking
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.