Bluetooth Classic
Note:
All units
The VBOX Touch unit has a in-built Bluetooth unit. This can be connected to using any other bluetooth device such as your phone or computer.
Callbacks
Some bluetooth commands will need callbacks for you to know when they are finished, others will not. For example the below command scan does not need a callback as you can set a timer that will finish at the exact same time the scan does as you assign the time for the scan to go for. However a bond event can go on for a long time and you most likely want to know what the response is as soon as it is received.
Setting the callback
To set the bluetooth callback you need to call the set_bluetooth_cb() function and pass it a valid function that you want it to callback to.
network.set_bluetooth_cb(cb_func)
When you receive a callback to this function you will be passed a number as a response. The number will be one of the constants in the network module that starts EVENT_BT.
For example if you wish to check that the response you received is a successful bond event you could do the following:
if response == network.EVENT_BT_BOND_SUCCESS:
print("BOND ATTEMPT SUCCEEDED")
elif response == network.EVENT_BT_BOND_FAIL:
raise BondingError("Bonding Error "+network.get_bond_fail_reason())
This will print that it was a success or raise an error if there is a failure with the reason for this failure given by the bluetooth chip.
Note:
The reason for failure is not always accurate.
Scanning for bluetooth devices
To scan for bluetooth devices you need to use the .scan() function. This can perform either a bluetooth or wifi scan so you need to specify that you want a bluetooth connection. This automatically stores the data it receives back in a dictionary called bluetooth_devices_found in the structure device_name : device_MAC_address.
You can also specify how long you want it to scan for but it is advised to keep it on the default of 10s.
network.scan('Bluetooth', time=10000)
To check this dictionary simply get the variable from the class.
print(network.bluetooth_devices_found)
Changing the device name
You can change the name your VBOX Touch unit shows up as. By default this is set as “VBOX Touch “ and the serial number of your device. Unless it is a PBOX in which case it will be “PBOX Touch “ and your serial number.
To change your device name simply pass the device name you wish to assign to the set_bluetooth_name() function
network.set_bluetooth_name("Racelogic's VBOX Touch Test")
Security and Discoverability
The security, pairing toggle, discoverability and connectability can all be assigned and this is done using 1 function.
By default all the values of these will be the following:
security - No security
pairing toggle - Pairing ON
discoverability - Discoverable
connectability - Allowed to connect
When you are performing a connection from your VBOX Touch these are all automatically disabled. This is because an external device connecting attempting to connect at the same time can cause issues.
The different modes that each can be assigned are constants in the network module. They can be found under network.BT_MODE.
network.pairing() # restores the values to the defaults
network.pairing(pairing=BT_MODE_PAIR_OFF, discoverability=BT_MODE_DISC_OFF, connectability=BT_MODE_CONN_OFF) # turns off connections
Note:
The security modes may mean that you can no longer connect your device correctly.
Bonding
Bonding to a device is establishing the base of the connection. For example on your phone a bonded device will appear under ‘paired devices’.
You need to bond to a device before you can pair to it with the VBOX Touch. Before you can bond, however, you have to have performed a scan and found the device you are pairing to in this scan.
network.bond_to_device(device_name)
You need to pass it a string of your device’s name. For most devices you will then have to accept the pairing request.
Unbonding
Unbonding a device will get rid of this base connection. This unbonds the device from the VBOX Touch but not from the other device i.e. the VBOX Touch will still appear in ‘paired devices’.
network.unbond_device(device_name)
You need to pass it a string of your device’s name. You will now not be able to pair to that device anymore.
Connecting
From the VBOX Touch
To connect to bluetooth you need to use the .connect() function from the network object. This connect function is used for every connection other than wifi. You have to pass it the name you want to assign to the connection (typically just the bluetooth device name) as well as the connection type. You will also need to pass the correct arguments, this can be seen in the doc string and in this documentation.
For bluetooth the argument you need to pass is the name of the device you are trying to pair to.
Note:
You will need to have bonded to the device first.
network.connect('device_name', 'Bluetooth', device_name)
Note:
Devices with higher security for example your phone will not accept a connection request from the VBOX Touch however you can connect from your phone to the VBOX Touch.
From an external device
When connecting from an external device you have to try and find the correct bluetooth device. The VBOX Touch will automatically pair with this device and add it to its connected devices.
Note:
If you are not already bonded when trying to connect an external device than the VBOX Touch will try and bond to the device first.
Disconnecting
There are 2 different ways you can disconnect from a device. It is advised however that you use disconnect_connection_using_name. This will disconnect your device given the connection_name you assigned earlier.
If you connected from an external device then:
network.disconnect_connection_using_name(connection_name)
Accessing connections
To access a connection you need to get the object from the network object’s dictionary called connections_id. This is done by address the connections_id object with the correct channel or by using the get_connection_object_from_name function.
network.connections_id[channel_id]
network.get_connection_object_from_name[connection_name]
Both of these will return the function which you can now perform functions on.
Receiving data
Data is automatically received and stored in a list. This list can contain up to 10 items. Once it gets over 10 it will loop back round over the old ones.
You can get the whole list using the get_processed_data function or just the most recent item using the get_recent_data function.
network.get_connection_object_from_name[connection_name].get_processed_data()
network.get_connection_object_from_name[connection_name].get_recent_data()
This will then return the data from these objects provided that they exist.
Sending data
To send data to a location you need to use the send_to_connected function.
This will get the channel_id of the device you are sending data to and then pass this to the send_text function.
bluetooth.send_to_connected(data, device_name)
Currently you can only send text.
Extra commands
If there are any commands that are missing you may be able to code them yourself using the cmd function and the Command documentation or you can request them by contacting Racelogic Support.
bluetooth.cmd('AT+UBTBD')
You can enter any command into here. As you are using the bluetooth class it is advised that you use the commands that are for bluetooth.