What is a Lego NXT Bluetooth Telegram
By Anna Sandler
A telegram is a bulk of bytes.
This bulk contains a command and its parameters, ready
to be sent to the NXT, for immediate execution.
The commands are divided into two groups:
- System commands- administrative commands that control the administration
of the LEGO brick such as file system operations or protocol \ Communication configuration.
- Direct commands- commands that control robot's motion, sensors…
Some of the commands are just requests for feedback from the robot (get sensors’
data for example). When using Bluetooth for communication, 30 milliseconds must
pass between the time the NXT sends a response and the receipt of a new command.
The structure of the telegram that is sent to the NXT:
1. TELEGRAM LENGTH (Two Bytes)
- Telegram length Least Significant Byte (LSB) unsigned byte
This byte should be sent only when using Bluetooth to send and receive telegrams.
It represents the total length of the command bytes. This does not include the two-bytes-length
descriptor part, A maximum length of 64 bytes is allowed.
- Telegram length Most Significant Byte (MSB) unsigned byte
This byte should be sent only when using Bluetooth to send and receive telegrams.
It represents the total length of the command bytes. This does not include the two-bytes-length
descriptor part, A maximum length of 64 bytes is allowed.
The construction of these bytes (LSB and MSB) will be described on later posts.
2. COMMAND TYPE - unsigned byte
- 0x00: Direct command, reply required
- 0x01: System command, reply required
- 0x80: Direct command, reply not required
- 0x81: System command, reply not required
3. COMMAND NUMBER- unsigned byte
This byte identifies the command itself. We will dive into the commands in the next posts.
4. PARAMETERS - bytes 4-N
Used for additional parameters per command. We will dive into the commands in the
next posts.
The structure of the response telegram that is sent from the NXT:
1. TELEGRAM LENGTH (Two Bytes)
- Telegram length Least Significant Byte (LSB) unsigned byte
This byte is sent only when using Bluetooth to send and receive telegrams. It represents
the total length of the command bytes. This does not include the two-bytes-length
descriptor part, A maximum length of 64 bytes is allowed.
- Telegram length Most Significant Byte (MSB) unsigned byte
This byte is sent only when using Bluetooth to send and receive telegrams. It represents
the total length of the command bytes. This does not include the two-bytes-length
descriptor part, A maximum length of 64 bytes is allowed.
The construction of these bytes (LSB and MSB) are described here (link)
2. COMMAND TYPE - unsigned byte
0x02- This is a reply for a requested command.
3. REQUESTED COMMAND - unsigned byte
The byte that represents the COMMAND that requested this response.
4. STATUS - unsigned byte
Status byte shows whether the command has executed successfully or an error message
has occurred.
- 0x00- Success - the command that has requested this response has been successfully
executed.
- 0x20- Pending communication transaction in progress. The specified port is busy performing a transaction.
- 0x40- Specified mailbox queue is empty.
- 0x81- No more handlers. The system is not able to allocate any more file
handlers for this thread. One of the reasons for this error can be a maximum limit
of 16 opened file handlers that has already been reached for this thread. Try to
send CloseFile command to one of the open file handlers that is no longer in use,
then resend the open file command again.
- 0x82- No space
- 0x83- No more files. The system is not able to create any more files. Most likely, the reason is that you’ve reached the limitation of 127 files the can be
saved on the NXT brick’s flash memory. Try deleting files that are not in use and
resend the create file command again.
- 0x84- End of file expected. Write request exceeded the space available for
the file. Partial write performed. One of the reasons can be a wrong file size calculation
when it was created due to missing null terminator bytes after the file name in
case the name is shorter than 15 characters.
- 0x85- End of file. File operation reached the end of the file.
- 0x86- Not a linear file.
- 0x87- Specified file not found.
- 0x88- Handler already closed.
- 0x89- No linear space. The system is not able to allocate requested linear
file system space for specific file.
- 0x8A- Undefined error.
- 0x8B- File is busy. The system cannot acquire file handler for specified
file because some other operation has opened the file.
- 0x8C- No write buffers. The system cannot open the file for write operation
because all write buffers are already in use. There is a limitation of 4 files that
can be opened for writing at the same time. Try to close one of the opened files
that is no longer in use and resend the open file for write command.
- 0x8D- Append is impossible. Not a textual file or the file is already full.
The only way to use FileOpenAppend command successfully, is to create a textual
file, leave some empty space and close it using the FileClose command.
Bear in mind that once the file is automatically closed by the file system, all
the free space in the file is removed to optimize total free space in the brick.
- 0x8E- File is full. The allocated space for specified file is full. No more
write operations allowed.
- 0x8F- File name exists. The system has failed to create or rename the file due
to name collision. Try to resend the command with a different name.
- 0x90- Module not found.
- 0x91- Out of boundary.
- 0x92- Illegal file name. The file name that has been provided is illegal. Make sure
that the correct file name format is used: [15].[3] characters.
File type can be only one of the following types:
RXE: Executable files compiled from NXT-G, LabVIEW, or another compatible programming
environment.
RPG: 5-step programs created using the “NXT Program” UI on the NXT brick.
RTM: Built-in “Try Me” programs.
RIC: Image files for use with the NXTDrawPicture syscall method in .RXE programs.
RSO: Sound files.
SYS: Internal NXT firmware files.
CAL: Sensor calibration file.
TXT: ASCII text file using carriage return/line feed (CR/LF, Windows) end-of-line
convention.
LOG: Also an ASCII text file, created by the NXT data logging functionality.
- 0x93- Illegal handler. The allocated space for specified file is full, or the
file has been opened for other purposes.
- 0xBD- Request failed. Specified file not found for direct command.
- 0xBE- Unknown command.
- 0xBF- Insane packet.
- 0xC0- Data contains out-of-range values. Make sure fileName contains a NULL terminator byte (0x00) at the end of the string,
and total length of the fileName argument is exactly 20 characters.
If fileName is less than 20 characters, add NULL terminator for each missing character.
In some cases, you will see this error for non existing specified file name as well.
- 0xDD- Communication bus error. The last transaction failed, possibly due to a device failure.
This error message can be caused by either no digital device is connected to the specified port or the connected device is configured incorrectly.
- 0xDE- No free memory in the communication buffer.
- 0xDF- Specified channel/connection is not valid. The specified port is invalid. Port must be between 0 and 3.
- 0xE0- Specified channel/connection not configured or busy. The specified port is not properly configured.
Make sure the type property is set properly, and that invalid data property is false for this port.
- 0xEC- No active program.
- 0xED- Illegal size specified for a direct command. Either buffer or return length arguments exceeded the 16 byte limit or 256 bytes (It depends on the calling command).
Another reason could be that the message is too large. If you are calling the MessageWrite command on a slave NXT brick,
use mailbox queues 10 through 19 as outboxes. When the master NXT brick reads messages, it checks these upper 10 mailboxes for outgoing message on the slave.
- 0xEE- Illegal mailbox queue ID specified. The valid queues are between 0 and 9.
- 0xEF- Attempted to access invalid field of structure.
- 0xF0- Bad input or output specified.
- 0xFB- Insufficient memory available.
- 0xFF- Bad arguments.
5. Byte 3-N
Used for additional information.
What's next?
In order to move forward and learn how to program Lego NXT using Bluetooth communication,
your environment should be configured to communicate with it. We strongly recommend
using a RealTerm terminal even if you are a .NET or a Java developer. At least during
the first steps. As we move on with the programming, you can send commands to NXT
using your code (we will go deeper into that later).
Let's move forward and learn how to send the commands to NXT via RealTerm