Doc: clarify NimBLEAddress(uint8_t[6], type) expects MSB-first bytes

[fl4p]

Documentation-only follow-up to #423.

The byte-array NimBLEAddress constructor calls std::reverse_copy on its input — fine for callers passing Bluedroid-style MSB-first bytes (esp_bd_addr_t), but easy to miss for anyone arriving with LSB-first bytes (e.g. straight out of a NimBLE ble_addr_t.val) since both layouts are "native ESP." The original docstring said:

Constructor for compatibility with bluedroid esp library using native ESP representation.

Updated docstring spells out the expected order, contrasts it with NimBLEAddress(ble_addr_t) for LSB-first wire bytes, and points hex-literal users at NimBLEAddress(uint64_t, uint8_t) (which is already well-documented).

No behaviour change.

How this came up

Tracked down a 100% connect-timeout bug in a NimBLE bridge where I had a uint64_t MAC, converted to a uint8_t[6] in LSB-first wire order, and passed that to this constructor. reverse_copy then stored it MSB-first in val[], NimBLE used val[] directly as the on-air LE bytes, and every ble_gap_connect timed out scanning for a peer that doesn't exist. Symptom was indistinguishable from "out of range." Switching to the uint64_t constructor fixed it immediately. Issue #423 has the full diagnostic story.

Summary by CodeRabbit

• Documentation
  • Improved BLE address constructor documentation with enhanced clarity on byte order handling, parameter descriptions, and guidance on alternative constructors for different input formats.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1ff28a15-6272-4b35-b455-a7a2bd355ef9

📥 Commits

Reviewing files that changed from the base of the PR and between 1eddc28 and 56deaf7.

📒 Files selected for processing (1)

• src/NimBLEAddress.cpp

---

📝 Walkthrough

Walkthrough

Ahoy! This here PR be but a documentation voyage, matey. The MSB-first byte-array constructor fer NimBLEAddress now sports expanded Doxygen comments explainin' the byte-order reversal from Bluedroid's esp_bd_addr_t format into NimBLE's LSB-first representation, guidin' scallywags to the right constructor fer their treasure—be it LSB-first bytes or hex integers, yarrr!

Changes

NimBLEAddress Constructor Documentation Clarification

Layer / File(s)	Summary
MSB-first constructor documentation src/NimBLEAddress.cpp	Doxygen comments fer the byte-array constructor (lines 100–112) expanded to explicitly describe byte-order reversal from Bluedroid's MSB-first layout to NimBLE's LSB-first storage, with clearer guidance on choosin' the right constructor based on input format.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related issues

• #423: Both be documentatin' the same constructor's byte-order behavior—clarifying that the byte-array constructor expects a 6-byte MSB-first (Bluedroid) input and reverses it into NimBLE's LSB-first storage, so this PR likely resolves the same issue or be a companion to the same concern.

Poem

📜 A compass of bytes, now clear as the sea,
MSB to LSB, the course we decree,
With words carved like treasure, no sailor can err,
The right constructor awaits—just follow the spur! 🧭

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Doc: clarify NimBLEAddress(uint8_t[6], type) expects MSB-first bytes' directly and specifically describes the main change: updating documentation to clarify byte order expectations for a specific constructor.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}