📡 BLE Virtual Device Simulator & Mock Server

Create, configure, simulate, and **mock** a local Bluetooth Low Energy (GATT Server) peripheral directly from VS Code for testing.

Demo Video / GIF (See the extension in action below)

✨ Why use this extension?

Designed for IoT developers, mobile engineers (Flutter, React Native, iOS, Android), and engineering students, this extension removes the need for physical hardware. Easily mock BLE devices during the early stages of Bluetooth testing and application development.

It creates a real-time communication bridge between your computer and your IoT simulators (like Wokwi) via WebSocket, or emits real Bluetooth signals (depending on your OS).

Key Features

🎛️ Live Control Panel: View and modify your BLE characteristic values in real-time.
🔌 Wokwi WebSocket Bridge: Instant bidirectional synchronization on port 8080.
💾 Profile Library: Build your Service/Characteristic tree and save it locally to load it with a single click.
🔠 Smart Encoding: Modify payloads via an intuitive interface supporting Hexadecimal (HEX), plain text (TEXT), and dynamic integers (INT).
🛡️ Graceful Degradation: If your hardware doesn't support radio transmission, the extension safely falls back to a "Pure Simulator" mode via WebSocket.
🎬 Scenarios (Pro): Record and replay complex sequences of BLE events automatically to test your mobile apps effortlessly.

🚀 Quick Start

Open the VS Code command palette (Cmd/Ctrl + Shift + P).
Type BLE Simulator: Start.
Set your Device Name.
Add a Service (e.g., 180D for Heart Rate) and Characteristics (e.g., 2A37).
Click Start Advertising.
Connect with your mobile app or your Wokwi ESP32 simulator!

💎 All Features Unlocked (Community Feedback Phase)

[!NOTE] 100% Free & Unlocked: To collect feedback and help early adopters, all advanced features (Multi-Devices, Scenario Recorder & Player, CSV Export) are currently completely free and unlocked without requiring any license key!

Feature	Community Access
Simulate 1 BLE Device	✅ Free
Live Control Panel	✅ Free
Wokwi WebSocket Bridge	✅ Free
Multi-Devices (Simulate multiple ports)	✅ Unlocked
Scenario Recorder (Automate interactions)	✅ Unlocked
Scenario Player (Replay complex tests)	✅ Unlocked
Export Session Logs to CSV	✅ Unlocked

Enjoy testing and don't hesitate to share your feedback or feature requests!

🖥️ OS Compatibility

The ability to emit actual Bluetooth signals (Broadcasting) depends on your operating system:

🍏 macOS: 100% Plug & Play. Native radio broadcasting works out of the box.
🐧 Linux: Full support via the BlueZ stack. (Includes auto-configuration for permissions).
🪟 Windows: "Wokwi Simulator" mode only. Because Windows restricts direct access to BLE chips, radio broadcasting is disabled, but the WebSocket bridge remains 100% operational.

A badge at the top of the interface will always indicate your hardware status: 🟢 Active or 🟠 Disabled (Sim Only).

🔌 Connecting to Wokwi (WebSocket Bridge)

The extension exposes a local bridge on ws://127.0.0.1:8080.

Important for Wokwi users: Add this to your wokwi.toml file to allow port forwarding:

[wokwi]
version = 1
[[net.forward]]
port = 8080

JSON Payloads

VS Code ➡️ ESP32 When you modify a value in the Live Control Panel, your ESP32 receives:

{
  "action": "write",
  "uuid": "2a37",
  "valueHex": "32342e35",
  "valueText": "24.5"
}

ESP32 ➡️ VS Code To update a value in the extension from your ESP32, send:

{
  "action": "update",
  "uuid": "2a37",
  "value": "24.5",
  "format": "text" 
}

❓ FAQ & Troubleshooting

Why does my Wokwi simulator fail to connect on port 8080 (Connection Refused)?

By default, Wokwi blocks access to your local machine. You must explicitly allow the WebSocket bridge by adding port 8080 to your wokwi.toml file under [[net.forward]].

Why does the Hardware BLE status say "Disabled (Sim Only)" on Windows?

The Windows operating system severely restricts direct low-level access to the Bluetooth chip for creating GATT Servers. To prevent crashes, the extension automatically disables the native radio and falls back to the WebSocket Simulator mode. You can still fully test your IoT flows using Wokwi!

I get a permission error on Linux when trying to start Advertising.

On Linux, the BlueZ bluetooth stack requires special privileges to broadcast signals. The extension will show an "Auto-Configure" button: click it to automatically generate the necessary sudo apt-get and setcap commands in your terminal.

How can I simulate multiple BLE devices at the same time?

Simply click the "+" icon in the device tabs to spawn a new isolated virtual peripheral. Multi-device simulation is currently fully unlocked for all users without any license required!

💬 Feedback & Support

Found a bug or have a feature request? Open an issue on GitHub.
Enjoying the extension? Leave a review on the VS Code Marketplace to help us grow! ⭐️

Developed with ❤️ by CodeHorizon.