Connecting Two NXTs via Bluetooth Using the NXT's User Interface

1. Use the NXT user interface to select Bluetooth comands.
   
   
   The top left of the NXT LCD status display shows the bluetooth status.The leftmost icon is the BT symbol and indicates that BT is enabled on the NXT. The icon indicates that the NXT BT visibility is enabled -- if visibility is disabled, then the NXT will not respond to search commands from other BT devices. "Dick2" is the friendly nane for the NXT.
   
   
2. Then select "Search" frmcommand and run the command.
   
   
   
3. Once search has been performed, you'll be presented with a menu of the NXTs that were found via Bluetooth. In this case, only a single item -- the device "Dick1" was found.
   
   
   
4. Select the target device for the connection from the search results -- i.e. "Dick1" -- and then select "Connect"
   
   
   
5. The NXT supports connections to up to three "slave" devices. You need to select the appropriate "slot" (1, 2, or 3) for the connection. Select an empty slot -- all three slots are empty in the following picture -- and hit the orange button.
   
   
   
6. The NXT screen will show "Connecting" as the connection is attempted. Depending on the settings on your NXT, you may be prompted for a password.
   
   
   
7. Once the connection is made, the status ICON will change to "<>". The ">" indicates that the NXT is connected to another BT device.
   

Disonnecting Two NXTs via Bluetooth Using the NXT's User Interface

Disconnecting a Bluetooth connection is even easier than making a connection.

1. Use the NXT user interface to select Bluetooth comands.
   
   
   
2. Select the "Connections" Menu item.
   
   
   
3. You now get a list of the devices connected via Bluetooth. In this case, there is a single connection to the "Dick1" Bluetooth device.
   
   
   
4. Select this item. Then select the "Disconnect" command.
   
   
   
5. The connection will be removed and the NXT GUI will return to the Bluetooth commands menu. Note that the Bluetooth status icon in the top-left of the screen has changed from "<>" (visible + connected) to "<" (visible + not connected).
   
   

Sending Messages via Bluetooth

Once you have two NXTs connected via BT, it is very easy to send messages between them. There are only three functions that are needed:

1. cCmdMessageWriteToBluetooth writes a message.
2. cCmdMessageGetSize get the size of the first message in a mailbox containing a queue of received messages.
3. cCmdMessageRead removes the first message from a mailbox queue and copies it to a user buffer.

After calling each of the above functions you should check the returned value to determine the success/failure of the function.

Use the function “cCmdMessageWriteToBluetooth(nQueueID, nXmitBuffer, nSizeOfMessage)” to send a BT message to the far end NXT. Check the error code to make sure message was transmitted successfully. This sends the message (up to 58 bytes in length) in the variable nXmitBuffer to queue or mailbox number nQueueID on the far end NXT. nSizeOfMessage is the length of the message.

When messages are received over BT by a NXT they are automatically added to the end of one of the 10 message or mailbox queues. Use the function “cCmdMessageGetSize(nQueueID)” to determine whether any messages have been received. A positive return value indicates that a message was received and is the number of bytes in the message.

Use the function “cCmdMessageRead(nQueueID, nRcvBuffer, nSizeOfMessage)” to retrieve the first message from the specified mailbox and copy it to a user’s buffer at nRcvBuffer. Only the first nSizeOfMessage bytes of the message are copied. nQueueID is the mailbox number to obtain the message from.

The sample program "NXT BT Messaging No Error Checking.c" is a simple program to show how to use all three of the functions.

Bluetooth Overview and Profiles

Bluetooth (BT) is an industry standard short-distance (up to 10 meters) wireless communications protocol operating at 2.4 GHz. It can optionally use a higher power transmission to achieve distances up to 100 meters. The NXT utilizes the 10 meter option.

BT includes not only the low-level radio transmission (at 2.5 GHz) but also several higher layer message protocols (or profiles) designed for different applications. There are over 25 different BT profiles currently defined. Some of the more popular profiles include:

• The Serial Port Profile (SPP) is used to provide wireless emulation of a conventional RS-232 serial communications cable. This is the only protocol supported on the NXT.
• The Human Interface Device (HID) protocol is used for communication on wireless keyboards and mice. It is also used on some game controllers like the Nintendo Wii or SONY Playstation 3.
• The Headset Profile (HSP) is used to connect wireless headsets to devices like cellphones.

In order to connect two devices via BT, the devices must not only support BT but also support the type of profile that will be used for the connection. The NXT only supports the SPP so that it cannot, for example, directly connect to a Nintendo or Sony game controller.

Connecting via Bluetooth, Pairing

Each BT device is unique identifed by a unique 12 hexadecimal digit address. It's a little awkward to refer to devices with this address so the BT protocols include a "friendly name" that is a more conventional 15-character string. The default friendly name for a NXT brick is "NXT" but you can modify this using the NXT's on-brick user interface, or from the ROBOTC IDE, or directly from within a ROBOTC program.

Before you can connect two devices via BT they must be "paired". The pairing process exchanges messages between the two devices where they share their BT address, their friendly names and their supported profiles. The devices confirm that they support the same profiles and that the (optional) password matches. Once two devices have been paired then you can make susbsequent connections using the friendly name only and the devices remember the passwords so that they don't have to be re-entered.

There's a lot of low-level messages used in establishing a paired connection. Fortunately, this is hidden from the user on the NXT with a simple user interface via the user interface on the NXT.

• From the BT menu on the NXT, a search is performed to build a internal list in the NXT of all the devices that are currently available via BT. The NXT simply broadcasts a "who's available" message over BT and collects a list of all the devices that replied.
• You then select one item from the list and then use the "Connect" command.
• The devices will be paired and a connection established.
• The far end device will be added to the NXT's internal table of paired devices, i.e. the "My Contacts" list on the NXT. Next time you want to make a connection you can select the device from the "My Contacts" and avoid the 30-second search.

NOTE: Sometimes you'll find that you cannot get two previously paired devices to connect. One cause of this is that one device is no longer powered on. Another cause is that somehow the devices have got out of sync on the pairing status where one device has "lost" the paired status. If this happens, try removing both devices from the "My Contacts" list on each NXT and restart the connection using the "Search" function.

Master vs Slave Device

One end of a BT connection is the master device and the other end is the slave device. The master device generates the clocking signal used for the BT connection and the slave device device derives its clock from the received radio signal. This results in the following restrictions:

• A device can be either a slave or a master, but not both.
• A single master can (optionally) make connections to multiple slaves.
• A slave can only connect to a single master. It cannot have connections to other masters as it would then need to support multiple clock sources!

The BT protocol is asymmetric. At its lowest level,

• A master can transmit over radio at any time.
• A slave only transmits in response to a request from a master.
• During the initial connection setup, the two devices negotiate the maximum bandwidth that they will use and how often they are listening for traffic. This allows the devices to use a low-power mode (i.e. the radios are only enabled part of the time) at the expense of lower bandwdith.

Bluecore Implementation

BT implementation on the NXT use a "Bluecore" chip from CSR. Bluecore is a self-contained implementation of BT that manages the BT hardware and protocols. It has a few limitations that are common to many other BT hardware implementations:

• The "search" function requires 100% of the BT resources. When a search is in progress, then no other BT activity can take place on the NXT.
• The module can be in either "command" or "data" mode. They are mutually exclusive states.
  • In command mode, housekeeping functions related to the BT protocol are being performed -- this includes things like searching, pairing, making connections and disconnection.
  • Data mode is used to transfer data between two devices over the BTX wireless link.
• Bluecore supports a single "master" device connecting to up to three 'slave' devices at one time. However, it can only communicate data with one device at a time; it could not simultaneously receive data from all three slaves!

On the radio side, Bluecore can have three connections (or "streams") to different slave devices. However, on the other side -- i.e. the connection from Bluecore to the NXT CPU, only a single connection is possible. It is this implementation that leads to the above restrictions. So, for example:

• If you wanted to add a second slave connection to a NXT, the Bluecore module would be switched into "command" mode. This would interrupt "data" traffic from the original connection. The appropriate commands would be performed to set up the connection and then Bluecore would be switched back to "data" mode.
• In data mode, Bluecore is only connection to one of the two streams/connections at a time. If data from the disconnected stream is received, it is discarded.
• Bluecore can be switched from "data mode on stream 1" to "data mode on stream 2". This is done by switching to "command" mode, sending the "switch stream" command and then switching back to "data" mode; this takes over 100 milliseconds.

NXT-G Bluetooth Messaging

The NXT-G firmware has built a message passing system on top of the NXT Bluectore implementation. It works as follows:

• Messages can contain up to 58 bytes of data. The restriction is that firmware has a fixed 64-byte format for message buffers and there is six bytes of overhead in the structure.
• Single master can connect to up to three slaves.
• Messages can be sent to one of ten queues. The queue number is one of the overhead bytes.
• When a message is sent from the master, it is put on a queue of outgoing BT messages.
  • Messages are transmitted from the queue in a FIFO basis whenever the previous queue item is completed.
  • The firmware looks at the stream ID -- ie. which of the three possible connections -- before transmitting a message.
  • If the stream ID does not match the currently "active" stream, then the active stream is switched to this stream by the 100+ millisecond process described above.
• Slave devices cannot use the above process! The slave does not know whether it's stream is the master's "active" stream. The implementation for messageing from the slave is as follows:
  • An outoging message from the slave is always added to one of the ten outgoing message queues. One queue for each of the ten possible "mailboxes".
  • The message sits in the outoging queue until the slave receives a "poll for message from mailbox N" message from the master.
  • In response to the "poll for message" the slave responds with either "the selected mailbox is empty" or it sends the first message found in the queue.

If there is only a single slave, then the above process does not incur the 100+ msec delays of switching 'active' streams on the master. It still incurs a delay while the slave waits for a polling request from the master.

ROBOTC Bluetooth Messaging

The ROBOTC BT messaging has been optimized for a single slave connecton on the master. This allows for significantly less latency on the BT message link. Slaves can immediately transmit messages without having to wait for a polling request from the master. ROBOTC also allows for multiple slave support, but a description of this is beyond the scope of this tutorial. This optimization gives a performance improvement of three to 20 times over other architecture that support – at a significantly reduced performance level – multiple simultaneous slaves.

ROBOTC measured performance to send a BT message, receive it at far end, process it, generate a reply and receive it at original device is about 36 such transactions per second. Other implementations (e.g. NXT-G) typically support about 13 transactions per second.

ROBOTC allows full duplex operation over a single BT stream. Measured performance indicates each end of the stream can autonomously send 250 messages per second. The half-duplex implementation is limited to 13.

NXT Bluetooth Overview

The NXT contains an integrated Bluetooth (BT) communications link. BT is an industry standard short-distance (up to 10 meters) wireless communications protocol.

• BT communications can be used to connect to the PC instead of the USB link. You can do all functions available over the USB link via BT. Except that NXT firmware can only be upgraded via USB. The USB communications is far faster than BT but requires a tethered link. BT, because it is wireless, is un-tethered.
• BT communications can be used to connect multiple NXTs together.
• BT communications can also be used to connect the NXT to another BT device – like a cell phone – as long as the other device communicates with the protocol specifications in the NXT BT Development Kit.

BT communications can operate in either a master or slave mode. The NXT BT device can only be in one mode or the other at any one time.

• When connected to the PC via RobotC, the NXT is in slave mode and the PC is the master.
• When two NXTs are connected via BT, one is the master device and one is the slave device. A NXT in master mode can support up to three slaves. A NXT in slave mode only supports a single BT connection.

The NXT GUI (Graphical User Interface) provides manual capabilities to manage the BT configuration on the NXT. The set of functions described here provide the ability to do all of the GUI capabilities, and more, within a user application program. You can set up and tear down connections, search for devices, remove items from the contacts list and many more functions.

The NXT firmware manages its BT communications through two lists: a connected device array and a contacts list.

• The connected device array has four elements that represent the different possible connections. Index zero (i.e port zero) in the array is always used for a slave NXT to contain information about its single connection. Ports 1 to 3 are used for a NXT in master mode to contain information about its three possible connections to other BT devices.
• The contacts list contains a list of BT devices that have been previously found by a “search” command. Since this is a historical list, the devices in this list may not all be currently accessible. The NXT remembers in this list devices that have previously connected to it and will automatically allow subsequent connection attempts by these devices without manual password entry – the previously used password will automatically be used.

While a NXT in master mode can connect to three slave devices / NXTs simultaneously, it can only communicate with one at a time. This means that a slave NXT/device cannot simply send a message to the master NXT; the master may be in communications mode with one of the other two possible devices and will not be listening to this particular slave. So, the slave must ‘buffer’ its message and wait for a polling request from the master asking for a buffer message. The BT protocol allows for simultaneous transmission over all links; this one at a time restriction is a function of the NXT firmware and the BT chip that it uses.

When compared with USB communications, BT is fairly slow. RobotC typically takes 28 milliseconds to send a message to another device and get a reply. This is almost three times faster than most other NXT firmware solutions.

BT is implemented on the NXT via a special purpose “Bluecore” hardware module. The main CPU on the NXT communicates with the Bluecore module via an internal messaging scheme. The main CPU sends a message to the Bluecore and then waits for a response. This means that the functions described below generally do not complete in a single transaction. Your program needs to request the action and then continually check the status until the transaction has completed and the result communicated back to the NXT CPU.

The Bluecore hardware can be in one of two modes: processing BT commands or data transmission mode. It cannot be in both modes at a time. This means, for example, that if in the middle of program execution that is communicating with one BT device you make a connection to another BT device during the time the connection is being set up the communications with the first device is stalled.

BT devices have a unique 7-character (256 possible values per character) address. This can be fairly cumbersome so the BT specifications have included a “friendly name” (i.e. a standard character string of printable characters) that can be used to refer to a device.

 

NXT Bluetooth Access Functions 

btConnect(nResult, nPort, sFriendlyName);

Attempts to connect BT device with specified name (sFriendlyName) on port nPort. This NXT will be the master and the other the slave.

btDisconnect(nResult, nPort);

Disconnects the BT connection on port nPort.

btDisconnectAll(nResult);

Disconnects all existing BT connections.

btFactoryReset(nResult);

Resets the NXT BT to the factory configuration. All connections will be dropped. The contacts list will be emptied.

btRemoveDevice(nResult, sFriendlyName);

Removes a device with the specified name (sFriendlyName) from the contacts lists

btSearch(nResult);      

Begins a search for BT devices and adds new entries to the contacts lists. The search can take a long time (15 seconds).

btStopSearch(nResult);  

Stops a search that is in progress.

getFirstDevice(nResult, nHandle);

getNextDevice(nResult, nHandle);

These two functions are used to scan through the entries in the contacts list. Get first device will initiate the search from the beginning of the list and get will find the next valid entry in the list.

getDeviceAddr(nResult, nHandle, sAddr);

getDeviceClass(nResult, nHandle, sCOD);

getDeviceName(nResult, nHandle, sName);

getDeviceStatus(nResult, nHandle, nStatus);

These functions are used to retrieve information about a particular entry in the contacts list.

getPortName(nResult, nPort, sPortName);

Gets the name (sPortName) of the device connected on port nPort

readLinkQuality(nResult, nQuality);

Reads the BT link quality (future)

requestLinkQuality(nResult);

Requests the current BT link quality

setBluetoothOff(nResult);

setBluetoothOn(nResult);

Turns Bluetooth ON or OFF on the NXT.

setBluetoothVisibility(nResult, bBluetoothVisible);

Sets whether the NXT BT is visible or invisible to searches from other Bluetooth devices. Invisible status means that the NXT will not respond to “search for devices” requests from other BT devices. However, if a device already knows the name/address of this NXT, then it can make a connection to this NXT.

setDefaultPIN(nResult, sPIN);

Sets a default PIN to use for Bluetooth connections (future)

setFriendlyName(nResult, sFriendlyName);

Sets the sFriendlyName that a NXT will be known by. The friendly names is normally displayed on the top status line of the NXT LCD.

transferFile(nResult, nPort, sFileName);

Transfers the file sFileName from this NXT to the NXT connected to port nPort.

nBluetoothCmdStatus     

Gets the status/progress of the last BT 'command'

nBluetoothStatus        

Gets the current BT status. See the enum for more details. Contains a bit map that indicates whether BT is on/off, visible/invisible and connected/not connected. These status bits are used to update the BT icon on the top line status display on the NXT.

nLastBTCommand          

Gets the last BT command issued.

Selected NXT Bluetooth Technical Details

This section provides additional details for the technically inclined on the ROBOTC Bluetooth implementation and the NXT BT hardware. It highlights some of the areas that need careful treatment by software to implement a robust BT messaging scheme.

One of the hardware modules within the NXT is a self-contained Bluetooth (BT) module. It is called Bluecore (BC) by the module manufacturer. The NXT CPU communicates with the BC module via a high-speed serial link. The BC module can have up to three simultaneous connections to other NXTs.

Bluecore Command vs. Data Mode

The NXT CPU and BC need to operate in either CMD or DATA mode. BC cannot operate in both modes simultaneously.

In command mode, the NXT CPU is communicating with BC to perform “housekeeping” functions. Data transmitted between the two is interpreted as commands (and replies) to the BC chip; typical commands are connect/disconnect far end devices, enable/disable visibility, search for devices, etc.

Generally, all the command mode activities are performed at the beginning of a BT session. Once a connection has been set up, data “stream” mode is entered. When a session is complete, command mode is re-entered to drop (i.e. disconnect) the connection.

In data mode, BC simply transfers the data between the RF link and the serial link on the NXT CPU.

ROBOTC provides interfaces that enable user program access to most of the BC commands. For example, you can set up a connection to another NXT from within a user’s program. Programs should perform all “commands” requests first before beginning data transmission (i.e. sending messages) activity.

The NXT firmware smoothly manages the transition between command and data mode. There are a couple of digital I/O pins between the CPU and BC that are used to perform the transition which typically takes several milliseconds.

When in command mode, any data received over the RF link is simply discarded by BC. Similarly the NXT CPU discards any requests for transmission of data packets over the RF link.

One Master Can Connect to Three Slave Devices

BC allows a single “master” NXT to connect to up to three “slave” NXTs. The master provides the overall timing for the RF link used and the slaves derive their RF timing/synchronization from the master. You cannot mix master and slave devices on a single NXT. This limits the size of a network of BT connected NXTs to four devices – one master and three slaves.

BC communicates with the NXT’s CPU over a single high-speed serial link. When a NXT is in master mode, the CPU tells BC which one of the three possible slave ports (streams) should be currently active. BC simply transfers all data on the serial link to/from the active stream. Any data received from either of the two inactive streams is simply discarded by BC.

There is a command for the NXT CPU to tell BC to make a different slave port (stream) the active stream. This involves switching from Command to Data mode and sending a few requests to BC. It takes over 100 milliseconds to perform the active stream switch.

Most NXT Bluetooth Implementations Use Half-Duplex Operation

One implication of an architecture that supports simultaneous multiple slave connections is that the slave devices cannot autonomously send messages to the master device since they have no knowledge of whether their connection is currently the active stream on the master. The architecture requires a half-duplex protocol where the master device has to send a polling message to each slave device requesting any data that is buffered waiting for such a request.

The result is that the RF link is only used in a half-duplex mode. It is only transmitting in one direction at a time.

The incremental transaction delays in simultaneously handling multiple slaves – i.e. 100 to 300 milliseconds per transaction – make it impractical for high-performance real-time operation. It’s simply too slow.