📡 BLE Sensor Simulator — Android Native

A native Android application that transforms any phone into a Bluetooth Low Energy (BLE) Peripheral, simulating a smart logistics sensor. It broadcasts real-world cold chain & supply chain data over BLE — no physical sensor hardware required.

This is the mobile companion to the PC-based BLE Sensor Simulator (Node.js/bleno). Both simulators share identical UUIDs, payload formats, and BLE protocol behavior, making them fully interchangeable.

---

🎯 What It Does

The app acts as a BLE GATT Server (Peripheral) that:

1. 📂 Loads 1,000 rows of logistics sensor data from a bundled CSV dataset
2. 📻 Advertises as LogisticsSim over Bluetooth Low Energy
3. 🔄 Cycles through data rows every 2 seconds
4. 📤 Broadcasts each row as a UTF-8 string via Read and Notify characteristics
5. 📊 Displays a real-time dashboard with live payload, sensor values, and event log

A separate device (phone, tablet, or PC) running a BLE client/scanner can discover, connect, and receive the streaming data.

---

📸 App Overview

┌──────────────────────────────────────┐
│     🚛 BLE Sensor Simulator         │
│       Logistics & Cold Chain         │
│                                      │
│  ┌─ SERVICE STATUS ────────────────┐ │
│  │ 🟢 Advertising... Waiting       │ │
│  │    No connections                │ │
│  └──────────────────────────────────┘ │
│                                      │
│  ┌─ BLE CONFIGURATION ────────────┐ │
│  │ Device Name: LogisticsSim       │ │
│  │ Service:  A07498CA-AD5B-...     │ │
│  │ Char:     51FF12BB-3ED8-...     │ │
│  │ Properties: Read | Notify       │ │
│  │ Interval: 2000ms                │ │
│  └──────────────────────────────────┘ │
│                                      │
│  ┌─ CURRENT DATA ──── Row: 42/1000 ┐ │
│  │ BLE Payload:                     │ │
│  │ ┌──────────────────────────────┐ │ │
│  │ │ Truck_7,27.0,67.8,Delayed   │ │ │
│  │ └──────────────────────────────┘ │ │
│  │ 🚚 Truck_7      📦 Delayed      │ │
│  │ 🌡️ 27.0°C       💧 67.8%       │ │
│  └──────────────────────────────────┘ │
│                                      │
│  ┌─ EVENT LOG ─────────────────────┐ │
│  │ [15:30:01] Simulator started    │ │
│  │ [15:30:01] Advertising...       │ │
│  │ [15:30:05] Device connected     │ │
│  │ [15:30:05] Client subscribed    │ │
│  │ [15:30:07] Broadcasting: ...    │ │
│  └──────────────────────────────────┘ │
│                                      │
│  ┌──────────────────────────────────┐ │
│  │     ⏹  STOP SIMULATOR           │ │
│  └──────────────────────────────────┘ │
│                                      │
│    Dataset: sensor_data.csv (1000)   │
└──────────────────────────────────────┘

---

📋 BLE Protocol Specification

This app implements the exact same BLE protocol as the PC simulator:

Parameter	Value
Advertising Name	LogisticsSim
Service UUID	A07498CA-AD5B-474E-940D-16F1FBE7E8CD
Characteristic UUID	51FF12BB-3ED8-46E5-B4F9-D64E2FEC021B
CCCD (Descriptor)	00002902-0000-1000-8000-00805f9b34fb
Properties	Read, Notify
Encoding	UTF-8 String
Update Interval	2000ms
Payload Format	AssetID,Temperature,Humidity,ShipmentStatus

Example Payloads

Truck_7,27.0,67.8,Delayed
Truck_6,22.5,54.3,In Transit
Truck_10,25.2,62.2,In Transit
Truck_9,25.4,52.3,Delivered

---

🛠️ Tech Stack

Component	Technology
Language	Kotlin 1.9.24
Min SDK	26 (Android 8.0 Oreo)
Target SDK	35 (Android 15)
Build System	Gradle 8.9 + AGP 8.7.3
Java	OpenJDK 17
BLE Stack	Android BluetoothLeAdvertiser + BluetoothGattServer
UI	Material Components + ViewBinding
Service	Foreground Service (connectedDevice type)
Architecture	Service ↔ BroadcastReceiver ↔ Activity

---

📦 Installation

Option 1: Download APK (Quick)

1. Transfer BLE-Sensor-Simulator.apk to your Android phone
2. Enable "Install from Unknown Sources" in Settings
3. Open the APK and install

Option 2: Build from Source

Prerequisites:

• Android SDK (API 35)
• Java 17+
• Bluetooth 4.0+ device with BLE Peripheral support

# Clone the repository
git clone https://github.com/TruGanic/ble-native-simulator.git
cd ble-native-simulator

# Build the debug APK
./gradlew assembleDebug

# Install via ADB
adb install app/build/outputs/apk/debug/app-debug.apk

---

🚀 Usage

Starting the Simulator

1. Open BLE Sensor Simulator on your Android phone
2. Grant Bluetooth and Notification permissions when prompted
3. Tap ▶ START SIMULATOR
4. The status will show "Advertising... Waiting for connections"

Connecting a Client

On a separate device, use any BLE client:

Client	Platform
nRF Connect	Android / iOS
BLE Scanner	Android
LightBlue	iOS
Your React Native / Flutter app	Any
PC with noble / bleak	Linux / macOS / Windows

Steps:

1. Scan for BLE devices
2. Connect to "LogisticsSim"
3. Find Service A07498CA-...
4. Open Characteristic 51FF12BB-...
5. Enable Notifications (or do a Read)
6. Data streams every 2 seconds ✓

⚠️ Important: The simulator and scanner must run on separate physical devices. A single phone cannot be both the BLE Peripheral and Central simultaneously for the same service.

---

📊 Dataset

The bundled sensor_data.csv contains 1,000 rows of simulated logistics & cold chain data.

Source: Smart Logistics Supply Chain Dataset by ziya07 on Kaggle.

Field	Example	Used in BLE Payload
Timestamp	2024-03-20 00:11:14
Asset_ID	Truck_7	✅
Latitude	-65.7383
Longitude	11.2497
Inventory_Level	390
Shipment_Status	Delayed	✅
Temperature	27.0	✅
Humidity	67.8	✅
Traffic_Status	Detour
Waiting_Time	38
+ 6 more fields	...

---

🏗️ Project Structure

ble-native-simulator/
├── app/
│   ├── build.gradle.kts                  # App-level build config
│   ├── proguard-rules.pro
│   └── src/main/
│       ├── AndroidManifest.xml            # Permissions & service declaration
│       ├── assets/
│       │   └── sensor_data.csv            # Bundled dataset (1000 rows)
│       ├── java/com/truganic/blesimulator/
│       │   ├── MainActivity.kt            # UI controller, permissions, lifecycle
│       │   ├── BleSimulatorService.kt     # Core BLE peripheral (GATT server)
│       │   ├── CsvDataManager.kt          # CSV parser & row cycling
│       │   └── LogisticsData.kt           # Data model & payload serializer
│       └── res/
│           ├── layout/activity_main.xml   # Dark-themed dashboard layout
│           ├── drawable/                  # Status indicators, backgrounds
│           └── values/                    # Colors, strings, themes
├── build.gradle.kts                       # Root build config
├── settings.gradle.kts                    # Project settings
├── gradle.properties                      # Gradle JVM & Android config
├── gradlew                                # Gradle wrapper script
├── gradle/wrapper/
│   └── gradle-wrapper.properties          # Gradle 8.9 distribution
└── sensor_data.csv                        # Source dataset

---

🔧 How It Works

┌─────────────────────────────────────────────────────────────────┐
│                    Android Phone (Peripheral)                    │
│                                                                  │
│  ┌──────────┐    ┌──────────────────┐    ┌───────────────────┐  │
│  │  CSV      │───▶│  CsvDataManager  │───▶│  BleSimulator     │  │
│  │  Asset    │    │  Parse & Cycle   │    │  Service          │  │
│  │  Data     │    │  Every 2 sec     │    │                   │  │
│  └──────────┘    └──────────────────┘    │  ┌─────────────┐  │  │
│                                          │  │ GATT Server │  │  │
│                                          │  │ Advertiser  │──┼──┼──▶ BLE Radio
│                                          │  └─────────────┘  │  │
│  ┌───────────────────────────────────┐   │                   │  │
│  │         MainActivity              │◀──│  Broadcasts       │  │
│  │  Live Dashboard + Event Log       │   └───────────────────┘  │
│  └───────────────────────────────────┘                           │
└─────────────────────────────────────────────────────────────────┘
                           │
                      BLE Radio Wave
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│              Another Device (Central / Scanner)                  │
│                                                                  │
│  nRF Connect / React Native App / Python bleak / etc.           │
│  ──▶ Scan ──▶ Connect ──▶ Subscribe ──▶ Receive Data           │
│                                                                  │
│  Payload: "Truck_7,27.0,67.8,Delayed"                           │
└─────────────────────────────────────────────────────────────────┘

---

🔀 PC vs Android Simulator

Both simulators are protocol-compatible and interchangeable:

Feature	PC Simulator	Android Simulator
Language	TypeScript / Node.js	Kotlin
BLE Library	@abandonware/bleno	Android BLE API
Platform	Linux (BlueZ)	Android 8.0+
Service UUID	✅ Identical	✅ Identical
Characteristic UUID	✅ Identical	✅ Identical
Payload Format	✅ Identical	✅ Identical
Update Interval	2000ms	2000ms
Advertising Name	LogisticsSim	LogisticsSim
Requires Root	Yes (sudo)	No
Portable	❌ Desktop/RPi only	✅ Any Android phone

---

📱 Compatibility

Requirements

• Android 8.0 Oreo (API 26) or higher
• Bluetooth 4.0+ with BLE Peripheral mode support
• Most phones manufactured after 2015 support this

Tested On

• Android 12 (API 31)
• Android 13 (API 33)
• Android 14 (API 34)

Permissions Used

Permission	Purpose	Android Version
BLUETOOTH_ADVERTISE	BLE advertising	12+ (API 31+)
BLUETOOTH_CONNECT	GATT server connections	12+ (API 31+)
BLUETOOTH	Legacy BLE access	≤11 (API ≤30)
BLUETOOTH_ADMIN	Legacy BLE admin	≤11 (API ≤30)
ACCESS_FINE_LOCATION	Legacy BLE scanning	≤11 (API ≤30)
FOREGROUND_SERVICE	Keep service alive	9+ (API 28+)
POST_NOTIFICATIONS	Service notification	13+ (API 33+)

---

📄 License

ISC

---

🙏 Credits

• Dataset: Smart Logistics Supply Chain Dataset by ziya07
• PC Simulator: TruGanic/ble-sensor-simulator
• BLE Protocol Design: Based on the Bluetooth SIG GATT specification

---

Built with ❤️ by TruGanic