Bluetooth
| Manual contents (Statement index) | |
|---|---|
| Language features | The basics • Arrays • Data structures • Interrupt routines • User-defined functions |
| Interfaces | Audio player • Bluetooth • Files • Graphics • HTML • Keyboard • Sockets • SQL • Telecom |
| Programming notes | Coexisting with Android |
The RFO-BASIC! Bluetooth unit lets a BASIC program exchange 8-bit bytes over a Bluetooth connection with another device, which does not have to be an Android device. It is easy to communicate USASCII text with this facility. UNICODE text and other information such as multimedia can be communicated, but the sending BASIC program has to encode them into 8-bit bytes for transmission and the receiving program has to decode them and assemble the desired information.
Before communication can occur, Bluetooth must be enabled on two devices and the devices have to be paired — that is, made aware of one another. Typically, one of the devices provides a passcode that the user of the other device enters through the keyboard. The way to do this is usually in the Android settings. That is, you must pair your Android device with its Bluetooth partner outside RFO-BASIC! before the BASIC program can open a connection to the partner.
The BASIC Bluetooth connection is always in one of five states: Not enabled, Idle, Listening, Connecting, and Connected. (See the table at BT.STATUS.) Only when the state is Connected can exchange of bytes occur. Either device can drop the connection.
One of the two devices uses BT.OPEN to begin listening for a connection. The other device uses BT.CONNECT to connect with a device that is listening. Each connection is "secure" or "insecure" and both parties are required to specify one or the other type of connection.
The BASIC program can monitor the status of the connection and can be interrupted when bytes from the other device are ready to be read. However, RFO-BASIC! has no interrupt with which to detect a change in the connection status, such as the connection being dropped.
- The program
Sample_Programs/f35_bluetooth.bas, included with the RFO-BASIC! installation, implements a simple text chat. You can use it to verify that two devices are paired and can exchange bytes, to study use of these BASIC statements, and to be the starting point for your own Bluetooth application.
BT.OPEN[edit]
Open a Bluetooth connection
- Synopsis
BT.OPEN {<secure_nexp>}
- Description
The BT.OPEN statement opens Bluetooth and either listens for a secure connection or listens for an insecure connection. If <secure_nexp> is omitted or if its value is 1, BT.OPEN listens for a secure connection. If <secure_nexp> is provided and its value is 0, BT.OPEN listens for an insecure connection.
If the device's Bluetooth receiver is switched off, BT.OPEN displays a pop-up asking if the user wants to turn Bluetooth on. If the user denies this request, BT.OPEN gives the trappable error Bluetooth Not Enabled.
When BT.OPEN returns successfully, the connection is in Listening state.
BT.CLOSE[edit]
Close any Bluetooth connection
- Synopsis
BT.CLOSE
- Description
The BT.CLOSE statement closes any Bluetooth connection that is open. When BT.CLOSE returns, Bluetooth is in Idle state. If no connection is open, then BT.CLOSE has no effect. BASIC automatically closes the Bluetooth connection when the program exits.
BT.CONNECT[edit]
Connect via Bluetooth
- Synopsis
BT.CONNECT {<secure_nexp>}
- Description
The BT.CONNECT statement tries to establish a connection over Bluetooth. If <secure_nexp> is omitted or if its value is 1, BT.CONNECT tries to establish a secure connection. If <secure_nexp> is provided and its value is 0, BT.OPEN tries to establish an insecure connection.
BT.CONNECT puts a dialogue on the screen asking the user to select one of the devices that is paired with it and that is listening for the same type of connection.
When BT.CONNECT returns successfully, Bluetooth is in Connecting state. When the connection is complete, it changes to Connected state.
BT.DISCONNECT[edit]
Drop a Bluetooth connection
- Synopsis
BT.DISCONNECT
- Description
The BT.DISCONNECT statement drops a Bluetooth connection but does not forget the paired device with which RFO-BASIC! was communicating. It returns Bluetooth to Listening state (rather than Idle, as BT.CLOSE does). The BASIC program should eventually call BT.RECONNECT in order to resume communication.
In contrast, executing BT.CLOSE followed by BT.OPEN requires that the user select a paired device again.
BT.RECONNECT[edit]
Re-establish a Bluetooth connection
- Synopsis
BT.RECONNECT
- Description
The BT.RECONNECT statement tries to re-establish a connection to the same paired device that the program dropped using BT.DISCONNECT. Often it is impossible to reconnect; the program should use BT.STATUS to test that the reconnection succeeded in a reasonable amount of time.
Connection status[edit]
BT.STATUS[edit]
Query the Bluetooth status
- Synopsis
BT.STATUS {<status_var>}{, {<name_svar>}{, <mac_svar>}}
- Description
The BT.STATUS statement obtains the status of the device's Bluetooth subsystem. A BASIC program should periodically query the status during a connection. There are many things that could cause the connection to drop, including the paired device moving out of range of Bluetooth radio, being switched off, or its user dismissing the app with which the BASIC program was communicating.
If <status_var> is present, BT.STATUS sets it to one of five values to indicate the Bluetooth status. This variable may be numeric or string. In either case, the following table shows the value to which BT.STATUS sets this variable:
| Numeric value | String value | Meaning |
|---|---|---|
| -1 | Not enabled | Bluetooth is not enabled, or your device has no Bluetooth radio. |
| 0 | Idle | Bluetooth is enabled but not being used. |
| 1 | Listening | The program is listening for connection. |
| 2 | Connecting | The program has selected a partner but a connection has not yet been established. |
| 3 | Connected | Bluetooth is connected and the program can send and receive bytes. |
If <name_svar> is present, BT.STATUS sets it to the friendly name of your device (not the device to which you are connected). If your device has no Bluetooth radio, BT.STATUS sets <name_svar> to the empty string. To get the name of the paired device, use BT.DEVICE.NAME. If <mac_svar> is present, BT.STATUS sets it to the MAC address of your device. This is a number comprising six hexadecimal digits, such as 00:11:22:AA:BB:CC.
- Usage
Depending on real-world conditions including the distance between the paired devices, and on how frequently the BASIC program uses BT.STATUS while communicating, the result could be one of the following:
- 3 (
Connected) — If the connection is dropped and re-established quickly, the BASIC program might not sense the drop at all. - 2 (
Connecting) — This status indicates the devices are in the process of re-establishing the connection. The BASIC program should keep polling until the status becomes 3 (Connected), because only then can the program resume sending and receiving. - 1 (
Listening) — If communication remains impossible for an extended period of time (typically, 7.5 sec), the connection is terminated. The BASIC program can use BT.RECONNECT to re-establish the connection to the same paired device; or use BT.CLOSE and BT.OPEN to let the user pick that or some other device.
BT.DEVICE.NAME[edit]
Return the name of the paired device
- Synopsis
BT.DEVICE.NAME <name_svar>
- Description
If Bluetooth is in the Connected state, then BT.DEVICE.NAME returns in <name_svar> the friendly name of the device at the other end of the connection. If Bluetooth is not Connected, then BT.DEVICE.NAME generates a run-time error.
Receiving bytes[edit]
The BASIC program can receive bytes via Bluetooth either by polling to see when bytes arrive, or by using an interrupt routine.
BT.READ.READY[edit]
Test whether characters are ready
- Synopsis
BT.READ.READY <count_nvar>
- Description
The BT.READ.READY statement returns in <count_nvar> the number of bytes available for reading.
The BASIC program (such as the Bluetooth interrupt routine) typically processes each received byte and calls BT.READ.READY again, until a returned value of 0 indicates there are no more bytes to process.
If a BASIC program is in a loop waiting for bytes to arrive, then as well as calling BT.READ.READY, it should call BT.STATUS; one reason for <count_nvar> to be 0 for a long time is that the Bluetooth connection was lost.
If the count of available bytes changes from zero to nonzero, and if the BASIC program contains a Bluetooth interrupt routine, then an interrupt occurs and the routine receives control.
BT.READ.BYTES[edit]
Read all available bytes
- Synopsis
BT.READ.BYTES <bytes_svar>
- Description
The BT.READ.BYTES statement deposits in <bytes_svar> all the bytes that have arrived over Bluetooth that had not been read previously. If no bytes have arrived, then BT.READ.BYTES sets <bytes_svar> to the empty string.
Each byte is placed in one character of the string; the upper byte of each character is 0. This is similar to BYTE.READ.BUFFER, which reads binary data from a file into a string.
A call to BT.READ.BYTES returns all the bytes that have arrived since the last call. A routine that obtains and processes these bytes might call BT.READ.READY again before returning, in case additional bytes arrived during the processing.
Sending bytes[edit]
On the receive side of the Bluetooth connection, the BASIC program tests whether bytes have arrived or codes an interrupt routine to receive bytes. There is no comparable test on the transmit side. The program can always write bytes; BASIC buffers them and transmits them over Bluetooth at its rated speed.
BT.WRITE[edit]
Write data to the Bluetooth connection
- Synopsis
BT.WRITE {<exp> {,|;}} ...
- Description
The BT.WRITE statement sends text over the Bluetooth connection. It is comparable to the PRINT statement for sending text to the console (with exceptions noted below). The program can provide string or numeric expressions, separated by commas or semicolons. When the program provides a numeric expression, BT.WRITE uses a string representation of its numeric value.
BT.WRITE usually sends a line of text to the paired device, ending with the newline character.
If two expressions are separated by a comma, then BT.WRITE inserts a comma in that position in the text. If two expressions are separated by a semicolon, then BT.WRITE does not separate them at all. If the semicolon is at the end of the parameter list, then the usual newline character is omitted. A BT.WRITE statement with no parameter list sends a newline character by itself.
BT.WRITE has the following conceptual differences from the PRINT statement:
- A PRINT statement that ends with a semicolon defers printing until the program provides the remainder of the text line. A BT.WRITE statement that ends with a semicolon is transmitted immediately; the newline character is simply omitted.
- The BT.WRITE statement transmits each character as one byte, discarding the upper byte. It sends binary data and ASCII text correctly, but UNICODE characters might not be.
BT.SET.UUID[edit]
Set the UUID for Bluetooth
- Synopsis
BT.SET.UUID <uuid_sexp>
- Description
A Universally Unique IDentifier (UUID) is a standard format that identifies information, devised so that people working independently are unlikely to create the same UUID for two different things. It is discussed here. There are many UUID generators on the Internet.
BASIC's UUID for Bluetooth is the standard Serial Port Profile (SPP) UUID:
00001101-0000-1000-8000-00805F9B34FB
The BASIC program can change this UUID by passing a different one to the BT.SET.UUID statement as <uuid_sexp>. This should never be necessary.
Sources[edit]
- De Re BASIC! (v1.91), pages 127-130.
- Forum 6505: Making BT.RECONNECT work