Skip to content

Getting Started

Before You Start

You need:

  • an iPhone or iPad with Bluetooth enabled
  • the BLEControlsPi app installed
  • a Raspberry Pi or Linux system set up for your project
  • the matching BLE connect router and ActionController Python code installed and running on that system.

The Python code is required. Without it, the app cannot connect and operate the target system.

The app can connect to Linux systems beyond Raspberry Pi, but the Python code has only been tested on Debian and Ubuntu so far.

Quick Start/test

Create two controls and use them as a means of testing your installation.

scroll down for details of step 4/5, 8 & 9.

  1. Ensure that you have installed the Python Code (how to?) on the Raspberry Pi (RPi) or Linux system.
  2. Open BLEControlsPi app on iPhone/iPad.
  3. Go to the Settings tab.
  4. Create a first control that sends data to the RPi (suggestion: use a toggle or slider). Keep the control code suggested by the app.
  5. Create a second display control: Use Gauge, keep the control code as suggested by the app.
  6. Go to the Controls tab.
  7. Establish a bluetooth connection to your Raspberry Pi or Linux system (Tap Select Device)
  8. After connection is established - Use the first control.
  9. By default, the Python Action Controller is designed to print the control value received from toggle or slider to the log, and will have sent the RPi's cpu temperature to the Gauge you created.

This proves that your installation is working.

How to Create the two controls (steps 4 & 5):

First create a controls that sends data to the RPi:

  1. Go to the Settings tab. Any already create controls appears in the list.
  2. Tap the Create New + text button
  3. A list of all available controls is displayed. Select Slider or Toggle.
  4. Add a label to your control
  5. Do not change the code suggested by the app at this point.

    This code identifies the control and is detected by the provided Python Code. By default, it prints the received control's value to syslog.

  6. Tap Update Now to see a preview of the control.
  7. Tap Create: you are returned to the list of controls already created.

Secondly, create a control that displays information:

  1. Again, Tap the Create New + text button
  2. Scroll to bottom of the list. Select Gauge.
  3. This control allows 2 rows of labels. Enter CPU on first line and temp on the second.
  4. Do not change the code suggested by the app at this point.
  5. Change the initial value to 0. scroll down and tap the red hide button to dismiss the keyboard.
  6. Tap Create: you are returned to the list showing now both controls already created.

Then, adjust size/layout:

  1. Tap Set Layout button (top left)
  2. Tap Resize (top middle)
  3. Grab (Drag) right bottom corner blue arrows of Gauge controls and resize it as desired.
  4. Tap Move (top middle)
  5. Move the controls (drag) as desired
  6. Tap Save (top right)

Finally, View/Use the controls:

Select the Controls tab and confirm the two controls appears there.

although the controls can be manipulated, they are not sending or receiving data, because bluetooth is not connected yet.

How To Connect bluetooth (BLE) to the Raspberry Pi:

The iPhone/iPad BLEControlsPi App must establish a stable Bluetooth Low Energy (BLE) connection with the Raspberry Pi, to allow for controls data to be sent to (or received from) the Raspberry Pi.

  1. Ensure the Python code is installed and running on the RPi.
  2. Go to the controls tab in the App: you see both controls created above.
  3. Tap Select Device or blue antenna icon at the top of the screen. The Connect to Raspberry Pi screen is displayed.
  4. RPi hostnames, for RPi that have the python code installed and running, are displayed in the list (below Select a pi)
  5. Tap the Rpi name you want to connect to.
  6. Wait for connection: status is displayed.
  7. When connected - you are returned to the control tab.
  8. Operate the control that sends data to the RPi (see the value in its log)
  9. Note that if you created a Gauge per above, and did not change the control code (Gauge1) - the RPi will have sent the cpu temperature to the app, and it is displayed on the gauge.

How to view the logs on Raspberry Pi to see the control value (step 9):

If you installed the Python Code using the automated installer as explained here, the ActionController.py code will print controls value received to syslog.

To view the log, and verify that you controls on the iPhone/iPad are correctly sending a value:

  1. Open a terminal session on the RPi (or SSH into it)
  2. Run this command:

journalctl -u bpa-bleconnectrouter -n 200 --no-pager

Next Steps

Create the controls you actually need for your Raspberry Pi:

Use Settings Tab to edit the controls above, or add new ones

Note that you cannot edit the type of control already created. For example, if you wish to change the Slider to a Toggle, you must first delete the Slider, from the list displayed in Settings, then Create New Control of type Toggle.

Modify the ActionController.py code on the Raspberry Pi

Currently, the code provided only prints the value of the control to the log.

You can write python code in the appropriate handler for a given control to have the value of the control do something on the RPi.

For example, a Toggle could be made to switch an LED on/off through the RPi GPIO: The handler would see that True/False was sent from the App for the Toggle (identified by the control code) - and make a GPIO call to the assigned pin number.