Skip to content

TruGanic/ble-native-simulator

BranchesTags

Repository files navigation

📡 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

Built with ❤️ by TruGanic

About

A native Android BLE Peripheral Simulator that transforms any phone into a Smart Logistics Sensor . broadcasting cold chain data (temperature, humidity) over Bluetooth Low Energy in real-time. Mobile companion to the Node.js PC simulator.

Topics

bluetooth-low-energy ble-peripherals iot-device native-android-app

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages