Bluetooth

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 three 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.


 * The program, 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
Open a Bluetooth connection

BT.OPEN {}
 * Synopsis

The BT.OPEN statement opens Bluetooth and either listens for a secure connection or listens for an insecure connection. If  is omitted or if its value is 1, BT.OPEN listens for a secure connection. If  is provided and its value is 0, BT.OPEN listens for an insecure connection.
 * Description

If the device's Bluetooth receiver is switched off, BT.OPEN puts a dialogue on the screen asking if the user wants to switch Bluetooth on. If the user denies permission to switch Bluetooth on, the BASIC program exits.

When BT.OPEN returns successfully, the connection is in Listening state.

BT.CLOSE
Close any Bluetooth connection

BT.CLOSE
 * Synopsis

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.
 * Description

BT.CONNECT
Connect via Bluetooth

BT.CONNECT {}
 * Synopsis

The BT.CONNECT statement tries to establish a connection over Bluetooth. If  is omitted or if its value is 1, BT.CONNECT tries to establish a secure connection. If  is provided and its value is 0, BT.OPEN tries to establish an insecure connection.
 * Description

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
Break a Bluetooth connection

BT.DISCONNECT
 * Synopsis

The BT.DISCONNECT statement ends a Bluetooth connection, but returns Bluetooth to Listening state (rather than Idle, as BT.CLOSE does). BT.DISCONNECT is comparable to executing BT.CLOSE followed by BT.OPEN.
 * Description

BT.RECONNECT
Re-establish a Bluetooth connection

BT.RECONNECT
 * Synopsis

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.
 * Description

BT.STATUS
Query the Bluetooth status

BT.STATUS {}{, {}{, }}
 * Synopsis

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.
 * Description

If  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:   If  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  to the empty string. To get the name of the paired device, use BT.DEVICE.NAME. If  is present, BT.STATUS sets it to the MAC address of your device. This is a number comprising six hexadecimal digits, such as.

BT.DEVICE.NAME
Return the name of the paired device

BT.DEVICE.NAME 
 * Synopsis

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.
 * Description

Receiving bytes
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
Test whether characters are ready

BT.READ.READY <count_nvar>
 * Synopsis

The BT.READ.READY statement returns in <count_nvar> the number of bytes available for reading.
 * Description

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
Read all available bytes

BT.READ.BYTES <bytes_svar>
 * Synopsis

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.
 * Description

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
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
Write data to the Bluetooth connection

BT.WRITE { {,|;}} ...
 * Synopsis

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.
 * Description

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
Set the UUID for Bluetooth

BT.SET.UUID <uuid_sexp>
 * Synopsis

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.
 * Description

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.