DigiTekXplorer - BLE App User Guide

This guide explains how to use the BLE B_Bot Controller app to control a Raspberry Pi Pico 2 W via Bluetooth Low Energy (BLE).

1. Prerequisites:

• Android Device: An Android device (phone or tablet) with Bluetooth Low Energy (BLE) support, running Android API level 31 (Android 12) or higher.
• Raspberry Pi Pico 2 W:  A Raspberry Pi Pico 2 W configured as a BLE peripheral, running the appropriate server code to receive commands from the app. The Pico 2 W must be programmed with the specific BLE service and characteristics described in the app's documentation (Service UUID: 0000FF10-0000-1000-8000-00805F9B34FB, and characteristics A, B, C, and E).
• App Installation: The BLE B_Bot Controller app (currently BLE_proj9) installed on your Android device.

2. Enabling Bluetooth:

• Ensure Bluetooth is enabled on your Android device. You can usually do this through the device's settings (typically in "Connections" or "Bluetooth"). The app will check if Bluetooth is enabled and prompt you if it needs to be turned on (though direct enabling within the app is deprecated for security reasons).

3. App Overview:

The app's user interface is organized into ten rows,  and a top bar:

• Top Bar: Displays the app's title: "BLE B_Bot Controller".

The ten rows contain the following controls and displays:

• Row 1: Scan:
  • Scan Button: Tap this button to start scanning for nearby BLE devices. A list of       discovered devices (including their names and MAC addresses) will appear       below the button.
  • Device List: Select the Raspberry Pi Pico 2 W from this list. The app will attempt to connect. The app will also automatically try connecting to a device with a       device name of “B_Bot”.
  • Connection Status: Displays "Disconnected", "Connecting...", "Connected", or "Connection Failed". If the connection fails, a message will appear, and the app will automatically retry after 5 seconds.
• Row 2: Send Command:
  • Command Input: Enter a three-character command (e.g., "fwd", "hlt") or a command with a numerical parameter (e.g., "spd,5"). See the "Command Formats" section below.
  • Send Cmd Button:  Tap this button to send the command entered in the input field to the Pico 2 W.
• Row 3: Send Message (Characteristic E):
  • Message Input: Enter a text message.
  • Send Msg Button: Tap to send the entered message to the Pico 2 W.
• Row 4: Speed Control:
  • Speed Slider: Adjust the slider (0-10) to set a speed value.
  • Speed Display: Shows the current slider value.
  • Speed Button: Tap to send a "spd,NNN" command to the Pico 2 W, where NNN is       the displayed speed value.
• Row 5: Turn Angle Control:
  • Turn Angle Slider: Adjust the slider (0-180) to set a turn angle.
  • Turn Angle Display: Shows the current slider value.
  • Turn Angle Button: Tap to send a "trn,NNN" command, where NNN is the displayed angle.
• Row 6: Forward:
  • Forward Button: Tap to send the "fwd" command.
• Row 7: Movement Control:
  • Left Button: Tap to send the "lft" command.
  • Halt Button: Tap to send the "hlt" command.
  • Right Button: Tap to send the "rgt" command.
• Row 8: Reverse:
  • Reverse Button: Tap to send the "rev" command.
• Row 9: Heartbeat (HB) Count:
  • HB Count Display: Shows the current value of a read-only counter from the Pico 2 W (Characteristic A).
  • Update Button: Tap to request an update of the HB Count from the Pico 2 W.
• Row 10: LED Control (Characteristic C):
  • LED Status Text: Displays "LED Status".
  • LED Status Display: Shows the current LED status ("on" or "off") read from the Pico 2 W.
  • On Button: Tap to send the "on" command (turns the LED on).
  • Off Button: Tap to send the "off" command (turns the LED off).

4. Command Formats:

The app sends commands to the Pico 2 W in two formats:

• ccc: Three lowercase ASCII characters (e.g., "fwd", "hlt", "rgt").
• ccc,NN: Three lowercase ASCII characters, a comma, and a numerical parameter (e.g.,      "spd,5", "trn,90"). The numerical parameter can have a variable number of digits.

Important:All commands must be terminated with a carriage return (\r) character. The app automatically appends this, so you do not need to type it.  Note: LED controls “On” and “Off” do not require the app to append a carriage return. 

5. Connecting to the Pico 2 W:

1. Power On: Ensure the Raspberry Pi Pico 2 W is powered on and running its BLE server code.
2. Scan: Tap the "Scan" button in the app.
3. Select Device: From the list of scanned devices, select your Pico 2 W. It might appear as "B_Bot" (if you've set that as the device name) or with its MAC address.
4. Automatic Connection: If your Pico 2 W has the default device name of “B_Bot”, the app will attempt to connect automatically after scanning.
5. Connection Status: Monitor the connection status display. If the connection fails, the app will automatically retry.

6. Controlling the Pico 2 W:

Once connected, you can use the various controls (buttons, sliders, text input fields) to send pre-defined commands and custom messages to the Pico 2 W.  The Pico 2 W's code should be written to interpret these commands and perform the corresponding actions (e.g., move a robot, control LEDs, etc.).

7. Disconnecting:

The app will automatically disconnect from the Pico 2 W when you exit the app. A "Disconnected" message will be briefly displayed.

8. Troubleshooting:

• "Bluetooth not supported on this device": Your Android device does not have BLE hardware.
• "Failed to connect to the Pico. Retrying...":
  • Ensure the Pico 2 W is powered on and within range.
  • Verify the Pico 2 W is running the correct BLE server code.
  • Check for interference from other Bluetooth devices.
  • Try restarting both your Android device and the Pico 2 W.
• No devices found during scan:
  • Make sure Bluetooth is enabled on your Android device.
  • Confirm the Pico 2 W is advertising its BLE service.
  • Ensure your Android device has the necessary location permissions (required for BLE scanning on older Android versions).
• Commands not working:
  • Double-check the command format (three lowercase characters, optional comma and number, terminated by a carriage return – which the app adds automatically).
  • Verify your Pico 2 W code is correctly parsing the commands.
• App crashes:
  • Try restarting your device.
  • Make sure you are running the latest version of the App.

This user guide provides a comprehensive overview of how to use the BLE B_Bot Controller app. Remember to consult the app's source code and the documentation for your Raspberry Pi Pico 2 W's BLE server code for more detailed information.

Next topic.