BLE_Communicator - BLE Communicator CLI/GUI Manual

(Standalone .exe or Python Script)

Version: 1.1 (Updated for Python Script Usage)

1. Introduction

BLE_Communicator is a command-line and graphical tool designed to interact with specific Bluetooth Low Energy (BLE) devices that utilize the standard Battery Service characteristic (00002a19-...) for custom, bi-directional communication. It is available in two forms:

1. BLE_Communicator.exe: A standalone executable for Windows. No Python installation is required.
2. BLE_Communicator.py: A Python script requiring a Python installation and specific libraries.

Functionality (Common to both versions):

• GUI Mode: If run without any command-line arguments, a graphical user interface (GUI) is launched for interactive use.
• CLI Mode: If run with command-line arguments, it operates as a command-line interface (CLI) tool suitable for scripting or terminal use.

This tool allows you to scan for devices, connect to a specific device, send custom text commands (or predefined presets B1-B100), and listen for incoming responses delimited by \r\n (carriage return + line feed). It incorporates workarounds (manual message chunking) for robustness when sending longer messages.

2. Prerequisites

2.1. For BLE_Communicator.exe (Standalone Executable)

• Operating System: Windows.
• Bluetooth Adapter: A working Bluetooth adapter on your computer (ensure necessary drivers are installed and Bluetooth is enabled).
• Permissions: Your user account must have permissions to access Bluetooth hardware.

2.2. For BLE_Communicator.py (Python Script)

• Operating System: Windows (recommended, as underlying BLE library (bleak) works best here). May work on other platforms supported by bleak with potential adjustments.
• Python: A working Python installation (e.g., Python 3.8 or newer recommended).
• pip: Python's package installer (usually included with Python).
• Python Libraries: The following libraries need to be installed:
  • bleak: For BLE communication using terminal only. pip install bleak
  • bleak pyqt6 qasync: For GUI BLE communication. pip install bleak pyqt6 qasync
• Bluetooth Adapter: A working Bluetooth adapter compatible with the bleak library on your OS.
• Permissions: Your user account must have permissions to access Bluetooth hardware.

3. Installation

3.1. BLE_Communicator.exe (Standalone Executable)

1. Obtain the BLE_Communicator.exe file.
2. Place the .exe file in a directory of your choice.
3. (Recommended): Add the directory containing the .exe to your system's PATH environment variable. This allows you to run the tool from any directory simply by typing BLE_Communicator.exe.

3.2. BLE_Communicator.py (Python Script)

1. Obtain the BLE_Communicator.py script file (and any associated helper .py files if it's part of a larger package).
2. Place the script file(s) in a directory of your choice.
3. Open a Command Prompt or PowerShell in that directory.
4. (Recommended): Create and activate a Python virtual environment:

python -m venv venv
# On Windows CMD/PowerShell:
.\venv\Scripts\activate
# On Linux/macOS bash:
# source venv/bin/activate

1. Install the required libraries:

pip install bleak
# Add other libraries if needed, e.g.: pip install PyQt6
# Or, if a requirements.txt file is provided:
# pip install -r requirements.txt

4. Running the Tool

The core commands and options are identical for both the .exe and .py versions. The only difference is how you invoke the tool.

4.1. Using BLE_Communicator.exe

• GUI Mode:
  • Double-click BLE_Communicator.exe in File Explorer.
  • Or, open Command Prompt/PowerShell, navigate to the directory (using cd), and run: .\BLE_Communicator.exe (with no arguments).
• CLI Mode:
  • Open Command Prompt/PowerShell.
  • Navigate to the directory (or use PATH).
  • Run with commands and arguments: BLE_Communicator.exe [global-options] <command> [command-options]

4.2. Using BLE_Communicator.py

• GUI Mode:
  • Open Command Prompt/PowerShell.
  • Activate virtual environment (if created): .\venv\Scripts\activate
  • Navigate to the script's directory (using cd).
  • Run: python BLE_Communicator.py (with no arguments).
• CLI Mode:
  • Open Command Prompt/PowerShell.
  • Activate virtual environment (if created): .\venv\Scripts\activate
  • Navigate to the script's directory (using cd).
  • Run with commands and arguments: python BLE_Communicator.py [global-options] <command> [command-options]

5. Presets File (ble_presets.json)

• Both GUI and CLI modes (for both .exe and .py versions) use a shared file named ble_presets.json to store text associated with presets B1 through B100.
• This file is automatically created/read located in the user's Documents folder, inside a subfolder named BLE_Communicator (e.g., C:\Users\\Documents\BLE_Communicator\ble_presets.json). This default location should be consistent for both versions when run normally.
• You can edit this JSON file manually or use the set-preset command (CLI) or "Set Bx" buttons (GUI) to manage presets.
• CLI Override: The CLI mode allows specifying a different presets file location using the --config global option (works for both .exe and .py).
• Format:

{
  "B1": "[XDMSG|1||GetStatus]",
  "B2": "[XGGROUP|5]",
  "B42": "[Another Specific Command]",
  "B100": "The last one"
}

6. GUI Mode Interface

When run without arguments, the graphical interface provides:

• Scan Devices: Button to discover nearby BLE devices.
• Device List: Dropdown to select a device found during scan.
• Connect/Disconnect: Button to manage the BLE connection.
• Status: Label indicating connection state.
• Received Data: Text area displaying messages received from the device.
• Send Query/Command Input: Text field where you can:
  • Type any text command and press Enter or click "Send Input / Preset".
  • Type a preset name (e.g., B5, b42, B100) and press Enter or click "Send Input / Preset" to send its stored value.
• Quick Presets (B1-B4):
  • Send Buttons (B1-B4): Directly send the command stored in the corresponding preset. (Disabled if not connected). Tooltips show current content.
  • Set Buttons (Set B1 - Set B4): Save the text currently in the "Send Query / Command" input field to the corresponding preset file key. Tooltips show current content.
• Log: Text area displaying application status messages and errors.

7. CLI Mode Global Options

These options can be used before specifying the CLI command:

• --config <filepath>
  • Specifies a custom path to the JSON presets file, overriding the default location.
• -v, --verbose
  • Enables detailed debug logging to the console.

8. CLI Mode Commands

Note: All commands and their options work identically for both BLE_Communicator.exe and python BLE_Communicator.py. Replace BLE_Communicator.exe with python BLE_Communicator.py in the examples below if you are using the script version.

8.1. scan

• Purpose: Discovers nearby BLE devices.
• Usage: [invocation] scan [options]
• Options:
  • -t <seconds>, --timeout <seconds>: Scan duration. (Default: 5.0)
• Example:

# Using EXE:
BLE_Communicator.exe scan -t 10
# Using Python Script:
python BLE_Communicator.py scan -t 10

8.2. set-preset

• Purpose: Saves/Updates text for a preset (B1-B100) in the presets file.
• Usage: [invocation] set-preset <preset_name> <text>
• Arguments:
  • <preset_name>: Preset name (B1-B100, case-insensitive).
  • <text>: Text command (use double quotes " if it contains spaces).
• Example:

# Using EXE:
BLE_Communicator.exe set-preset B42 "[XGGROUP|5]"
# Using Python Script:
python BLE_Communicator.py set-preset B42 "[XGGROUP|5]"

8.3. send

• Purpose: Connects, sends one query/preset, waits (optional), disconnects.
• Usage: [invocation] send <address> [options]
• Arguments:
  • <address>: Target device MAC address.
• Options (Query/Preset - One Required):
  • -q <query_text>, --query <query_text>: Literal text query/command (use quotes " for spaces).
  • -p <preset_name>, --preset <preset_name>: Preset name (B1-B100) to send.
• Options (Wait Behavior - Optional, Mutually Exclusive):
  • -w <seconds>, --wait <seconds>: Inactivity timeout after sending. Resets on received messages.
  • --indefinite: Wait indefinitely after sending; allows interactive input like listen mode. Use quit or Ctrl+C to exit.
  • (No wait option specified): Disconnects shortly after send acknowledgment.
• Examples:

# Send direct query, disconnect quickly (EXE)
BLE_Communicator.exe send AA:BB:CC:DD:EE:FF -q "[GET_STATUS]"

# Send direct query, disconnect quickly (Python)
python BLE_Communicator.py send AA:BB:CC:DD:EE:FF -q "[GET_STATUS]"

# Send preset B1, wait with 5s inactivity timeout (EXE)
BLE_Communicator.exe send AA:BB:CC:DD:EE:FF -p B1 -w 5

# Send preset B1, wait with 5s inactivity timeout (Python)
python BLE_Communicator.py send AA:BB:CC:DD:EE:FF -p B1 -w 5

# Send preset B75, wait indefinitely for interaction (EXE)
BLE_Communicator.exe send AA:BB:CC:DD:EE:FF -p B75 --indefinite

# Send preset B75, wait indefinitely for interaction (Python)
python BLE_Communicator.py send AA:BB:CC:DD:EE:FF -p B75 --indefinite

8.4. listen

• Purpose: Connects, subscribes, and listens interactively for messages. Allows sending commands/presets via terminal input.
• Usage: [invocation] listen <address>
• Arguments:
  • <address>: Target device MAC address.
• Interactive Usage: Type commands or preset names (B1-B100), press Enter to send. Type quit, disconnect, or exit, or press Ctrl+C to stop. Received messages are printed prefixed with RECV:.
• Example:

# Using EXE:
BLE_Communicator.exe listen AA:BB:CC:DD:EE:FF
# Using Python Script:
python BLE_Communicator.py listen AA:BB:CC:DD:EE:FF

9. Output Format (CLI Mode)

• Log Messages: Printed to standard error (stderr). Use -v for debug level.
• Scan Results: Printed to standard output (stdout).
• Received Data (listen/send --indefinite/send -w): Printed to standard output (stdout), prefixed with RECV:.

10. Important Notes & Troubleshooting

10.1. General

• Device Address: Use scan to find the correct MAC address.
• UUIDs: Assumes communication via Battery Service/Level characteristics (0x180F/0x2A19). Modify the script/tool if different UUIDs are needed.
• Write Limit & Chunking: Sends data in <= 20-byte chunks automatically for longer messages.
• Connection Issues: Ensure device is on, in range, not connected elsewhere (if single-connection). Check Windows Bluetooth settings/drivers. Ensure Bluetooth is enabled on your computer.
• Presets File: Ensure the application (.exe or Python script process) has write permission in the user's Documents\BLE_Communicator folder (or the custom folder specified with --config).

10.2. Python Script Specific Issues (BLE_Communicator.py)

• Library Installation Errors: Ensure pip is working correctly and you have the necessary permissions. Check internet connection. If errors mention C++ build tools (especially on Windows), you might need to install the Microsoft C++ Build Tools.
• ModuleNotFoundError: Make sure you have installed all required libraries (e.g., pip install bleak) within the correct Python environment (activate your virtual environment if you created one).
• Python Version: Ensure your Python version meets the requirements of the script and its libraries (especially bleak).
• Virtual Environment: Remember to activate your virtual environment (.\venv\Scripts\activate or source venv/bin/activate) in the terminal before running python BLE_Communicator.py if you installed dependencies there.
• Platform Differences: While bleak is cross-platform, BLE behavior can vary slightly between OS (Windows, Linux, macOS). Functionality is primarily tested on Windows. ```

Replace the content of your .md file on the server with this corrected version, restart the Flask app, and the fenced code blocks should now render correctly (provided the fenced_code extension is active in your website.py and the CSS rule for pre { white-space: pre-wrap; } is in place).