Understanding the BC127 Bluetooth Module
On this page, we're going to lay the basic groundwork for understanding the BC127 module's functionality and capabilities. Everything we cover is in the BC127 module datasheet, but we're going to pare down what is in the datasheet to make it a bit easier to understand.
If you plan on using the BC127 with the Arduino library we provide, you may still find it useful to read through this page. While the library abstracts away the majority of the under-the-hood stuff, knowing what's going on may still be helpful, especially if you find that the library doesn't support a function you would like to use.
The BC127 has two operational modes: command mode and data mode. In command mode, any data coming in on the serial port is treated as commands and will be parsed accordingly by the module's command interpreter. In data mode, any data arriving over the serial port will be directly piped out over the Bluetooth link, assuming that the module is connected to another device using the Serial Port Protocol.
In command mode, data received locally and appended with a carriage return (typically represented as "\r", or as 0x0D hex) will be parsed as a command. Note that the parser expects only a carriage return; if the device sending commands appends both carriage return and newline (e.g., an Arduino using the println() statement), the parser will have trouble with it. If the newline character precedes the carriage return, the parser may not accept the command at all. If the carriage return comes first, the parser will interpret the newline as a start of another command string, which can cause unexpected error messages from the module.
Throughout the rest of this guide, I will be considering the carriage return at the end of the command to be implicit. Also, while commands are theoretically case-insensitive, commands will always be presented as all-caps and I suggest that you always send all-caps strings for commands, as it sometimes makes a difference.
Finally, the parser isn't very smart about whitespace. Inserting spaces in command strings in unexpected locations will cause errors. More on this later, as we start to talk about specific commands.
To enter data mode, simply input the command "ENTER_DATA". The module will respond with "OK" (more on responses later), whether it is connected as an SPP device or not. From that point on, data will be tranparently passed out via the SPP connection, if one is available. If not, it will simply be ignored--it is not buffered for later delivery when a connection is available.
To exit data mode, a string of four dollar signs must be sent ("$$$$"). In order for this to be interpreted as the command to exit data mode, rather than as data to be passed, there must be a gap before the first $ and after the fourth. The length of that gap can be set by the user, but is, by default, 400ms at either end. Without that gap in place, the string will be treated as data.
Also note that data mode does not support BLE connections, despite the superficial similarity between SPP data transfer and BLE data transfer. That is a constraint of the firmware on the BC127 and may change in the future.
Commands, Responses, and Configuration Parameters
To interface with the BC127 in command mode, you need to be aware of three things: the specific commands it will accept, the responses of the module to those commands, and the various configuration parameters that the user has control over.
We're going to discuss some of the more useful commands here. For each one, we'll provide the syntax, expected responses, and a discussion of the command's actions. Reminder--terminate your command strings with a carriage return only! Extra newlines will cause an error.
RESET - Resets the module to its currently stored default settings. You can see in the screenshot above the expected response. Note that this does not restore the factory defaults.
RESTORE - Resets the module to the factory default settings. Returns
OK when complete. This restoration is only temporary, and upon a
RESET the module will revert to the currently stored settings.
WRITE - Stores the current settings in non-volatile memory, to be used for configuration on next reset or power up. Returns
OK when complete. Many settings require a restart of the module before they take effect; if you don't
WRITE the current settings to non-volatile memory before issuing a
RESET command, they'll be lost and the changes won't take effect.
RESET will return the module to factory defaults and may be a good way to start out any program using the BC127, to provide a known good starting point.
SET - These two commands allow for access to the configuration parameters that we'll delve into below; generally, a
SET command will incur an
OK response, and
GET will cause the module to respond with the current value.
Any command will cause a response to be issued by the module. This will take the form of a string entirely composed of ASCII characters, terminated by both a new line ('\n' or 0x0A) and a carriage return ('\r' or 0x0D), in that order. As with commands, I'll assume that these are implicit whenever I mention a response.
All characters in all response strings will be all caps, unless the repsonse string represents received data in some way.
The two most common responses are "OK" and "ERROR". The receipt of either of these indicates that the characters entered since the last carriage return have been parsed and the input buffer is empty. For commands that take some time to execute (for example, scanning for local advertising BLE devices), many other commands cannot be submitted and will cause an "ERROR" response if submitted before the "OK" response signaling the end of the extended command is received.
Below are some of the responses the module can send in response to actions taken by the remote unit; these are naturally in addition to the responses to locally issued commands that we covered above.
CLOSE_OK SPP - The remote connection has closed the given profile. Note that SPP is just an example; that parameter can be of any type of connection, and in the event of the remote device closing all connections, you will receive one message for each profile that was connected. This can also mean that the remote device has moved out of range or been switched off.
PAIR_PENDING - A remote device is attempting to connect to the module.
PAIR_OKAY - A remote device, with the address immediately reported after the
PAIR_OKAY message, has successfully paired with the BC127. Will be followed by one or more
OPEN_OK messages detailing the types of connections that were established.
AVRCP_BACKWARD - The remote AVRCP device has executed this command. Not all devices will return all of these messages upon execution of a command.
In addtion to the commands listed above, there are numerous configuration parameters which can be set or read back using the
GET commands. Generally, the format for setting a value is
SET PARAM=VALUE1 VALUE2 VALUE3; parameters will always have at least one parameter and may have several. When entering multiple parameters, separate subsequent parameters to the first with a space. Ther should be no whitespace between the parameter name, the equals sign, and the first value; whitespace in that region will cause an error.
It is possible to read back the current state of all configuration parameters by entering the
CONFIG command; many of these values will not be cover here.