This repository contains a proof of concept (PoC) demonstrating BLE (Bluetooth Low Energy) communication between an IoT device and a customer setup application. The project simulates the common use case of configuring an IoT device with WiFi credentials via BLE.
The project includes two separate implementations:
- IoT Device (Peripheral/GATT Server) – Advertises and accepts configuration data
- Customer App (Central/Client) – Discovers and sends data to the IoT device
- Node.js (v12 or later recommended)
- Bluetooth adapter with BLE support
- Linux/macOS (Node.js BLE libraries have limited Windows support)
- Python 3.9 or later
- Bluetooth adapter with BLE support
- Platform requirements for Bleak:
- macOS 10.15+ (Catalina or newer)
- Linux with BlueZ ≥ 5.43
- Windows 10 (May 2019 Update or newer)
Install dependencies:
Note: Node.js BLE packages may require additional system dependencies:
sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev- Xcode Command Line Tools
Create and activate a virtual environment:
python -m venv venv
source venv/bin/activate # or `venv\Scripts\activate` on WindowsInstall dependencies:
pip install -r requirements.txtStart the IoT device simulator (in one terminal):
node iot-device.jsStart the customer setup app (in another terminal):
python customer-app.py- Service UUID:
12345678-1234-5678-1234-56789abcdef0 - Characteristic UUID:
12345678-1234-5678-1234-56789abcdef1
- IoT device advertises its presence with a specific service UUID
- Customer app scans for devices with that service UUID
- Customer app connects to the IoT device
- Customer app writes configuration data (as JSON) to the characteristic
- IoT device receives and processes the configuration
- Ensure Bluetooth is enabled on your system
- Check that your Bluetooth adapter supports BLE
- Run the applications with elevated permissions if needed (e.g.,
sudoon Linux) - Make sure no other applications are using the Bluetooth adapter
- Verify that the device is discoverable with a Bluetooth scanner app
ISC License