{"id":15011898,"url":"https://github.com/senseshift/arduino-ble-serial","last_synced_at":"2025-04-12T03:31:59.889Z","repository":{"id":248581791,"uuid":"828534276","full_name":"senseshift/arduino-ble-serial","owner":"senseshift","description":"Customizable Arduino and ESP32 BLE Serial library, compliant with Nordic UART Service and others","archived":false,"fork":false,"pushed_at":"2025-04-09T22:09:10.000Z","size":33,"stargazers_count":17,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-09T22:29:58.729Z","etag":null,"topics":["arduino","arduino-library","bluetooth-low-energy","esp32","nimble","platformio","platformio-library","serial-communication","serialport"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/senseshift.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-14T12:50:19.000Z","updated_at":"2025-04-03T09:40:56.000Z","dependencies_parsed_at":"2025-04-09T22:34:48.680Z","dependency_job_id":null,"html_url":"https://github.com/senseshift/arduino-ble-serial","commit_stats":null,"previous_names":["senseshift/arduino-ble-serial"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/senseshift%2Farduino-ble-serial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/senseshift%2Farduino-ble-serial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/senseshift%2Farduino-ble-serial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/senseshift%2Farduino-ble-serial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/senseshift","download_url":"https://codeload.github.com/senseshift/arduino-ble-serial/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248512809,"owners_count":21116681,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","arduino-library","bluetooth-low-energy","esp32","nimble","platformio","platformio-library","serial-communication","serialport"],"created_at":"2024-09-24T19:41:52.178Z","updated_at":"2025-04-12T03:31:59.654Z","avatar_url":"https://github.com/senseshift.png","language":"C++","funding_links":["https://www.patreon.com/senseshift"],"categories":[],"sub_categories":[],"readme":"# Arduino Serial BLE\n\nThis library allows using Nordic UART Service (NUS) with ESP32 Arduino.\n\n\u003cb\u003eGet 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)\u003c/b\u003e\n\n[![Discord Widget](https://discord.com/api/guilds/966090258104062023/widget.png?style=banner2)](https://discord.gg/YUtRKAqty2)\n\n[![PlatformIO Registry](https://badges.registry.platformio.org/packages/senseshift/library/Serial_BLE.svg)](https://registry.platformio.org/libraries/senseshift/Serial_BLE)\n[![Arduino Library](https://www.ardu-badge.com/badge/Serial_BLE.svg?)](https://www.ardu-badge.com/Serial_BLE)\n[![GitHub release](https://img.shields.io/github/v/release/senseshift/arduino-ble-serial)](https://github.com/senseshift/arduino-ble-serial/releases/latest)\n\n[![PlatformIO CI](https://github.com/senseshift/arduino-ble-serial/actions/workflows/platformio-ci.yml/badge.svg)](https://github.com/senseshift/arduino-ble-serial/actions/workflows/platformio-ci.yml)\n[![PlatformIO CI](https://github.com/senseshift/arduino-ble-serial/actions/workflows/arduino-ci.yml/badge.svg)](https://github.com/senseshift/arduino-ble-serial/actions/workflows/arduino-ci.yml)\n\n[![MIT](https://img.shields.io/github/license/senseshift/arduino-ble-serial)](/LICENSE)\n[![GitHub contributors](https://img.shields.io/github/contributors/senseshift/arduino-ble-serial)](https://github.com/senseshift/arduino-ble-serial/graphs/contributors)\n[![GitHub](https://img.shields.io/github/stars/senseshift/arduino-ble-serial.svg)](https://github.com/senseshift/arduino-ble-serial)\n\n## Features\n\n- [x] [`HardwareSerial`](https://www.arduino.cc/reference/en/language/functions/communication/serial/)-compatible API\n- [x] [ETL (Embedded Template Library)](https://github.com/ETLCPP/etl) support\n- [x] NimBLE support through [NimBLE-Arduino](https://github.com/h2zero/NimBLE-Arduino) library.\n- [x] Custom Server and Characteristics configuration\n\n## Installation\n\n### PlatformIO\n\n```diff\nlib_deps =\n+  senseshift/Serial_BLE\n```\n\n## Client-side usage\n\n- Android:\n  - [nRF connect for mobile](https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp)\n  - [Serial Bluetooth Terminal](https://play.google.com/store/apps/details?id=de.kai_morich.serial_bluetooth_terminal)\n- iOS:\n  - [nRF connect for mobile](https://apps.apple.com/es/app/nrf-connect-for-mobile/id1054362403)\n\n## Usage\n\nFor all examples, take a look at the [`examples`](./examples) folder.\n\n### Basic Example\n\n```ino\n#include \u003cBLESerial.h\u003e\n\nBLESerial\u003c\u003e SerialBLE;\n\nvoid setup() {\n    Serial.begin(9600);\n    SerialBLE.begin(\"ESP32-BLE-Slave\");\n}\n\nvoid loop() {\n    if (Serial.available()) {\n        SerialBLE.write(Serial.read());\n        SerialBLE.flush();\n    }\n    if (SerialBLE.available()) {\n        Serial.write(SerialBLE.read());\n    }\n}\n```\n\n### Custom UART characteristics\n\nUsing 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/)\n\n```ino\n// ...\n\nvoid setup() {\n    // ...\n\n    SerialBLE.begin(\n      \"ESP32-BLE-Slave\",\n      \"49535343-FE7D-4AE5-8FA9-9FAFD205E455\",\n      \"49535343-1E4D-4BD9-BA61-23C647249616\",\n      \"49535343-8841-43F4-A8D4-ECBE34729BB3\"\n    );\n\n    // ...\n}\n\n// ...\n```\n\n#### Alternative\n\n\n```ino\n// ...\n\nvoid setup() {\n    // ...\n\n    BLEDevice::init(\"ESP32-BLE-Slave\");\n    BLEServer* pServer = BLEDevice::createServer();\n\n    auto pService = pServer-\u003ecreateService(\"49535343-FE7D-4AE5-8FA9-9FAFD205E455\");\n\n    auto pRxCharacteristic = pService-\u003ecreateCharacteristic(\"49535343-1E4D-4BD9-BA61-23C647249616\", BLECharacteristic::PROPERTY_WRITE | BLECharacteristic::PROPERTY_WRITE_NR | BLECharacteristic::PROPERTY_NOTIFY);\n    auto pTxCharacteristic = pService-\u003ecreateCharacteristic(\"49535343-8841-43F4-A8D4-ECBE34729BB3\", BLECharacteristic::PROPERTY_READ | BLECharacteristic::PROPERTY_NOTIFY);\n\n    SerialBLE.begin(pRxCharacteristic, pTxCharacteristic);\n\n    // ...\n}\n\n// ...\n```\n\n### Custom Read Buffer\n\n#### ETL (Embedded Template Library)\n\nUsing [ETL](https://github.com/ETLCPP/etl) provides a way to use this library without dynamic memory allocation.\n\n```ino\n#include \u003cEmbedded_Template_Library.h\u003e\n#include \u003cetl/queue.h\u003e\n#include \u003cetl/circular_buffer.h\u003e\n\nBLESerial\u003cetl::queue\u003cuint8_t, 255, etl::memory_model::MEMORY_MODEL_SMALL\u003e\u003e SerialBLE;\nBLESerial\u003cetl::circular_buffer\u003cuint8_t, 255\u003e\u003e SerialBLE;\n```\n\n## NimBLE\n\nUsing the NimBLE library saves a significant amount of RAM and Flash memory.\n\n\u003ctable\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\n            ESP32 BLE\n        \u003c/td\u003e\n        \u003ctd\u003e\n            \u003cpre\u003eRAM:   [=         ]  11.9% (used 39124 bytes from 327680 bytes)\nFlash: [========= ]  85.9% (used 1125553 bytes from 1310720 bytes)\u003c/pre\u003e\n        \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\n            NimBLE-Arduino\n        \u003c/td\u003e\n        \u003ctd\u003e\n            \u003cpre\u003eRAM:   [=         ]   9.3% (used 30548 bytes from 327680 bytes)\nFlash: [====      ]  44.2% (used 579158 bytes from 1310720 bytes)\u003c/pre\u003e\n        \u003c/td\u003e\n    \u003c/tr\u003e\n\u003c/table\u003e\n\n### Arduino IDE\n\n1. Make sure to install `NimBLE-Arduino` library in Arduino IDE.\n2. Update `BLESERIAL_USE_NIMBLE` setting **Before** including library header:\n    ```diff\n    + #define BLESERIAL_USE_NIMBLE true\n    #include \u003cBLESerial.h\u003e\n    ```\n\n    Alternatively, сhange the following line in `BLESerial.h`:\n\n    ```diff\n    - #    define BLESERIAL_USE_NIMBLE false\n    + #    define BLESERIAL_USE_NIMBLE true\n    ```\n\n### PlatformIO\n\nChange your `platformio.ini` file to the following settings:\n\n```diff\nlib_deps = \n+  h2zero/NimBLE-Arduino@^1.4.0\n\nbuild_flags = \n+  -D BLESERIAL_USE_NIMBLE=true\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsenseshift%2Farduino-ble-serial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsenseshift%2Farduino-ble-serial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsenseshift%2Farduino-ble-serial/lists"}