Skip to content

Commit

Permalink
Updated README.md and new images.
Browse files Browse the repository at this point in the history
  • Loading branch information
eriklins committed Feb 23, 2023
1 parent 40398f4 commit b3462d5
Show file tree
Hide file tree
Showing 5 changed files with 27 additions and 9 deletions.
36 changes: 27 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,25 +9,27 @@ After start the main scan window opens and provides common controls for BLE devi
![InsideBLue BLE Tool Scan Window](images/insideblue_ble_tool_scan_window.png)

### Start/Stop Scanning
Pressing the [Start Scan] button starts scanning for BLE advertisments. Discovered devices will be shown as a panel list underneath. After scanning has started, the button turns into a [Stop Scan] button and BLE scanning stops when pressed again. The [Clear] button clears the panel list of discovered devices.
Pressing the **Start Scan** button starts scanning for BLE advertisments. Discovered devices will be shown as a panel list underneath. After scanning has started, the button turns into a **Stop Scan** button and BLE scanning stops when pressed again. The **Clear** button clears the panel list of discovered devices.

### Filters
Three filters can be applied to the device scanning. Entering a device name or part of it into the left field will only show devices matching. The device name is not case-sensitive. The middle field filters for BLE mac addresses or part of it. The mac address has to be entered as hex numbers separated by colons (aa:bb:cc:dd:ee:ff). The right field allows filtering based on the RSSI value of advertisments which – to some extent – represents the distance of a device. Values have to be entered as positive numbers.


### Log Output
A more detailed log output can be enabled by ticking the Show Log Output box. The main window will extend to the right and show the log output.
Two additonal buttons allow clearing the log output as well as copying the log output into the clipboard. You can also directly select text in the log output and copy.

![InsideBLue BLE Tool Scan Window with Log Output](images/insideblue_ble_tool_scan_window_log.png)

### Scan Data Panel
For each discovered device a panel with device information is shown. It contains device name, connectable status, tx power (if available), RSSI value, mac address, advertised services and manufacturer specific data.

If the UUID of a service or the company ID in the manufacturer data is in the official Bluetooth list of assigned numbers, the official name will be shown. You can hover with the mouse over the name to see the underlying service UUID or full company name with ID.

Manufacturer data can be displayed either as HEX numbers or ASCII string. For ASCII non printable characters are displayed as black boxes.
Connect Device
If a device is connectable you can engage a connection with the Connect button.

### Log Output
A more detailed log output can be enabled by ticking the Show Log Output box. The main window will extend to the right and show the log output.
Two additonal buttons allow clearing the log output as well as copying the log output into the clipboard. You can also directly select text in the log output and copy.

![InsideBLue BLE Tool Scan Window with Log Output](images/insideblue_ble_tool_scan_window_log.png)
### Connect Device
If a device is connectable you can engage a connection with the Connect button.

## Device Connect Window
When connecting to a device, a new device specific window opens and the GATT table of the device is read. Services, characteristics and descriptors are shown in a panel structure grouped by services.
Expand All @@ -40,6 +42,22 @@ Depending on the properties of each characteristic different buttons get added t

Data from/to a characteristic gets displayed or entered into a text field, which is either read/write or read only. You can switch the presentation between HEX numbers or ASCII string. When set to ASCII, non-printable characters are displayed as a black square.

#### Virtual Serial Port (VSP)
Beside the official Bluetooth list of services, there exist proprietary services to expose a virtual serial port service (similar to SPP service from Bluetooth Classic). InsideBlue knows some of these and if recognized it will show their names as well along with a button to fire up a simple VSP terminal window.

## UART VSP Terminal
For known VSP services you can open a terminal window and send/receive text. Line endings can be selected for both send and receive individually. Each sent text line will be added to a history drop down menu and can be selected later for sending certain lines again.

![InsideBLue BLE Tool VSP Terminal Window](images/insideblue_ble_tool_vsp_terminal.png)

(Currently only one VSP terminal can be opened at a time.)

### Modem In/Out Characteristics
Beside the mandatory TX (from peripheral to central) and RX (from central to peripheral) characteristics, some VSP services offer additional Modem In/Out characteristics which are used for handshake signalling much like RTS/CTS signals on a real UART. (These are not yet implemented in InsideBlue.)

### Length of RX Characteristic
The length of the peripheral RX characteristic is not known to the central, hence when sending text lines with too many characters, the BLE write operation will fail.

## Limitations
- Since InsideBlue leverages the PC’s integrated Bluetooth Controller, this ultimately limits what’s achievable from a BT hardware perspective (e.g., number of simultaneous connections).
- It is not possible to tweak BLE settings like scan interval and/or scan window or similar low-level BLE parameters.
Expand All @@ -63,7 +81,7 @@ Since both Lazarus/FreePascal as well as the SimpleBLE library are cross-platfor
Inside Blue BLE Tool is based on the SimpleBLE library (https://github.com/OpenBluetoothToolbox/SimpleBLE) and uses the Pascal bindings for that library (https://github.com/eriklins/Pascal-Bindings-For-SimpleBLE-Library).

## Releases
Pre-built releases for Windows 64 bit are available on the [releases tab](https://github.com/eriklins/InsideBlue-BLE-Tool/releases).
Pre-built releases for Windows 64/32 bit and Linux 64 bit are available on the [releases tab](https://github.com/eriklins/InsideBlue-BLE-Tool/releases).

## Contributing/Feedback
Feedback / improvements / pull-requests / etc. are welcome!
Expand Down
Binary file modified images/insideblue_ble_tool_connect_window.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified images/insideblue_ble_tool_scan_window.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified images/insideblue_ble_tool_scan_window_log.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/insideblue_ble_tool_vsp_terminal.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit b3462d5

Please sign in to comment.