https://github.com/senseshift/arduino-ble-serial
Customizable Arduino and ESP32 BLE Serial library, compliant with Nordic UART Service and others
https://github.com/senseshift/arduino-ble-serial
arduino arduino-library bluetooth-low-energy esp32 nimble platformio platformio-library serial-communication serialport
Last synced: 6 months ago
JSON representation
Customizable Arduino and ESP32 BLE Serial library, compliant with Nordic UART Service and others
- Host: GitHub
- URL: https://github.com/senseshift/arduino-ble-serial
- Owner: senseshift
- License: mit
- Created: 2024-07-14T12:50:19.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-09T22:09:10.000Z (6 months ago)
- Last Synced: 2025-04-09T22:29:58.729Z (6 months ago)
- Topics: arduino, arduino-library, bluetooth-low-energy, esp32, nimble, platformio, platformio-library, serial-communication, serialport
- Language: C++
- Homepage:
- Size: 32.2 KB
- Stars: 17
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Arduino Serial BLE
This library allows using Nordic UART Service (NUS) with ESP32 Arduino.
Get involved: π¬ [Discord](https://discord.gg/YUtRKAqty2) β’ π [Website](https://senseshift.io) β’ π [Issues](https://github.com/senseshift/arduino-ble-serial/issues) β’ π’ [Twitter](https://twitter.com/senseshiftio) β’ π [Patreon](https://www.patreon.com/senseshift)
[](https://discord.gg/YUtRKAqty2)
[](https://registry.platformio.org/libraries/senseshift/Serial_BLE)
[](https://www.ardu-badge.com/Serial_BLE)
[](https://github.com/senseshift/arduino-ble-serial/releases/latest)
[](https://github.com/senseshift/arduino-ble-serial/actions/workflows/platformio-ci.yml)
[](https://github.com/senseshift/arduino-ble-serial/actions/workflows/arduino-ci.yml)
[](/LICENSE)
[](https://github.com/senseshift/arduino-ble-serial/graphs/contributors)
[](https://github.com/senseshift/arduino-ble-serial)
## Features
- [x] [`HardwareSerial`](https://www.arduino.cc/reference/en/language/functions/communication/serial/)-compatible API
- [x] [ETL (Embedded Template Library)](https://github.com/ETLCPP/etl) support
- [x] NimBLE support through [NimBLE-Arduino](https://github.com/h2zero/NimBLE-Arduino) library.
- [x] Custom Server and Characteristics configuration
## Installation
### PlatformIO
```diff
lib_deps =
+ senseshift/Serial_BLE
```
## Client-side usage
- Android:
- [nRF connect for mobile](https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp)
- [Serial Bluetooth Terminal](https://play.google.com/store/apps/details?id=de.kai_morich.serial_bluetooth_terminal)
- iOS:
- [nRF connect for mobile](https://apps.apple.com/es/app/nrf-connect-for-mobile/id1054362403)
## Usage
For all examples, take a look at the [`examples`](./examples) folder.
### Basic Example
```ino
#include
BLESerial<> SerialBLE;
void setup() {
Serial.begin(9600);
SerialBLE.begin("ESP32-BLE-Slave");
}
void loop() {
if (Serial.available()) {
SerialBLE.write(Serial.read());
SerialBLE.flush();
}
if (SerialBLE.available()) {
Serial.write(SerialBLE.read());
}
}
```
### Custom UART characteristics
Using custom UUIDs for [Microchip BM70/RN4870 Transparent UART](https://developerhelp.microchip.com/xwiki/bin/view/applications/ble/android-development-for-bm70rn4870/transparent-uart-service-for-bm70rn4870/)
```ino
// ...
void setup() {
// ...
SerialBLE.begin(
"ESP32-BLE-Slave",
"49535343-FE7D-4AE5-8FA9-9FAFD205E455",
"49535343-1E4D-4BD9-BA61-23C647249616",
"49535343-8841-43F4-A8D4-ECBE34729BB3"
);
// ...
}
// ...
```
#### Alternative
```ino
// ...
void setup() {
// ...
BLEDevice::init("ESP32-BLE-Slave");
BLEServer* pServer = BLEDevice::createServer();
auto pService = pServer->createService("49535343-FE7D-4AE5-8FA9-9FAFD205E455");
auto pRxCharacteristic = pService->createCharacteristic("49535343-1E4D-4BD9-BA61-23C647249616", BLECharacteristic::PROPERTY_WRITE | BLECharacteristic::PROPERTY_WRITE_NR | BLECharacteristic::PROPERTY_NOTIFY);
auto pTxCharacteristic = pService->createCharacteristic("49535343-8841-43F4-A8D4-ECBE34729BB3", BLECharacteristic::PROPERTY_READ | BLECharacteristic::PROPERTY_NOTIFY);
SerialBLE.begin(pRxCharacteristic, pTxCharacteristic);
// ...
}
// ...
```
### Custom Read Buffer
#### ETL (Embedded Template Library)
Using [ETL](https://github.com/ETLCPP/etl) provides a way to use this library without dynamic memory allocation.
```ino
#include
#include
#include
BLESerial> SerialBLE;
BLESerial> SerialBLE;
```
## NimBLE
Using the NimBLE library saves a significant amount of RAM and Flash memory.
ESP32 BLE
RAM: [= ] 11.9% (used 39124 bytes from 327680 bytes)
Flash: [========= ] 85.9% (used 1125553 bytes from 1310720 bytes)
NimBLE-Arduino
RAM: [= ] 9.3% (used 30548 bytes from 327680 bytes)
Flash: [==== ] 44.2% (used 579158 bytes from 1310720 bytes)
### Arduino IDE
1. Make sure to install `NimBLE-Arduino` library in Arduino IDE.
2. Update `BLESERIAL_USE_NIMBLE` setting **Before** including library header:
```diff
+ #define BLESERIAL_USE_NIMBLE true
#include
```
Alternatively, Ρhange the following line in `BLESerial.h`:
```diff
- # define BLESERIAL_USE_NIMBLE false
+ # define BLESERIAL_USE_NIMBLE true
```
### PlatformIO
Change your `platformio.ini` file to the following settings:
```diff
lib_deps =
+ h2zero/NimBLE-Arduino@^1.4.0
build_flags =
+ -D BLESERIAL_USE_NIMBLE=true
```