How arduino-libraries/arduinoble works
Project type and purpose
• ArduinoBLE is an open-source Arduino library that enables Bluetooth Low Energy (BLE) connectivity on various Arduino boards (e.g., MKR WiFi, Nano 33 BLE, UNO R4 WiFi).
• It provides both Peripheral (local) and Central (remote) BLE roles, exposing a high-level API to users’ Arduino sketches.
File structure
• Top-level:
• src/ — core library code, subdivided into:
– src/ArduinoBLE.h — main API header.
– src/*.cpp & .h — high-level classes: BLEDevice, BLEService, BLECharacteristic, BLEDescriptor, typed/string characteristics.
– src/local/ — classes for Peripheral mode (BLELocalDevice, BLELocalService/Characteristic/Descriptor).
– src/remote/ — classes for Central mode (BLERemoteDevice, BLERemoteService/Characteristic/Descriptor).
– src/utility/ — BLE protocol stack and transport layers (GAP, GATT, ATT, L2CAP, HCI, UUID, transports, bit utilities, security).
• examples/ — sample sketches demonstrating Peripheral and Central use cases.
• docs/ — markdown documentation and API reference.
• extras/test/ — unit-test harness with fake devices and transport stubs.
• CI configs (.github/workflows) and project metadata (library.properties, README.md, LICENSE).
README for additional insights
• Core functionality: creating/applying BLE services, characteristics, advertising, scanning.
• Supported hardware dependencies: NINA or ESP32-S3 firmware on specific Arduino boards.
a. Main components
• Application Layer: Arduino sketches (examples) invoking the library.
• API Layer: ArduinoBLE.h + user-facing classes.
• Role Modules:
– Peripheral (src/local/*)
– Central (src/remote/*)
• Protocol Stack (src/utility/*):
– GAP, GATT, ATT, L2CAP, Security (keyDistribution, btct), UUID, linked lists.
• Transport Layer: HCI transports (UART, Cordio, Silabs, Virtual)
• Hardware/Firmware: NINA-W102 or ESP32-S3 module running required firmware.
• Test Harness (extras/test): fake devices and transports for unit testing.
b. Relationships and interactions
• Application → API Layer: calls into BLEDevice, BLEService, etc.
• API Layer → Role Modules: instantiates local or remote objects depending on mode.
• Role Modules ↔ Protocol Stack: use GAP/GATT to build and parse BLE PDUs.
• Protocol Stack → Transport Layer: sends/receives raw HCI commands/events.
• Transport Layer → Hardware/Firmware: physical serial or USB interface to radio module.
• CI workflows and Test Harness → Library Code: compile and run unit tests against fake transports.
c. Architectural patterns and design principles
• Layered architecture: clear separation of API, role logic, protocol, transport, hardware.
• Strategy pattern for transports: interchangeable HCI transport implementations.
• Adapter/facade: ArduinoBLE.h exposes a simplified interface over complex stack.
• Dependency inversion in tests: fake transports/ devices in extras/test to isolate logic.
d. Key technologies, frameworks, libraries
• C++ classes and templates for characteristics (typed vs string).
• HCI transport drivers (UART, Cordio, Silabs, Virtual).
• Arduino build system and CMake for examples/tests.
Detail
• Every src/utility submodule (GAP, GATT, ATT, L2CAP, security) is represented or collapsed under “Protocol Stack.”
• Both Peripheral and Central paths distinctly.
• Conditional dependency on external firmware modules.
• Examples/docs/CI as external consumers/maintainers of the library.