Lego NXT File Handling- Read Files
By Anna Sandler
This is an advanced topic, please make sure are familiar with
"Introduction To File Handling" tutorial before you continue reading
this chapter.
Upload or transfer files from NXT's brick to your device
In order to get files from NXT's brick, the following operation must be completed:
- The file should be opened for reading purposes using the FileOpenRead command
that is described in this chapter;
- Use the FileRead command to get the bytes of the file.
FileRead command is described below;
- Use the FileClose command to release file's resources (we will go deeper
into that in
NXT File Handling- Save and Close tutorial);
- In your code build a file instance from the bytes and save it to your disc;
File types that are supported for reading purposes
Only a non linear files can be read using the FileRead command.
There is a FileOpenReadLinear command that retrieves a pointer to linear memory
segment,
but the FileRead cannot use this information;
therefore, only the following file types are supported for the reading command:
- rso: Sound 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.
FileOpenRead command
This command is used to open an existing non linear file on NXT's brick by specified file name
for reading operations from the beginning of the file.
When a file is opened successfully, the following operations are performed:
- File handle is created;
- The specified file newly created handle is registered to the tracker table; therefore,
ResolveHandle command will be able to retrieve this file handler according to the
file name (will be discussed in later posts);
All opened files handles will be closed automatically when the program is finished
or failed to open the file.
When the file is closed automatically, unused space inside the specified file is
removed to maximize the free space on the device.
It is important to use the
FileClose command when the file is no longer needed to
free unused resources. There is a limitation of 16 opened file handles (read and
write) in the same thread at the same time.
Syntax
[0x16] [0x00] [0x01] [0x80] [fileName.fileType]
Explanation:
- Byte 0-1: Command length LSB first.
- Byte 2: Command type- system command with a request for a response. Response
should always be requested for this command.
- Byte 3: Command- file open read.
- Byte 4-23: File name including its extension.
The system is case insensitive.
The bytes of file name and type characters should be ASCII encoded.
NULL terminator must appear at the end ('\0').
In case the name of the file is shorter than 15 characters, NULL terminator byte
should be added to the end of the file name extension for each missing character.
Total file name characters, including the NULL terminators, should always be 20.
The reply message that is coming back looks like:
[0x08] [0x00] [0x02] [0x80] [0x00 or error] [Handle id] [File size LSB] [...] [...]
[File size MSB]
Explanation:
- Byte 0-1: Message length LSB first.
- Byte 2: Command type- reply message
- Byte 3: Command that has requested for this reply.
- Byte 4: Command status- 0x00 for success or error number for failure. Check
the
NXT File Handling over Bluetooth- Introduction chapter for error numbers.
- Byte 5: Handle id. The id of handle that has been requested to be opened.
- Byte 6-9: File size. The number of bytes that will be written to the file. LSB first.
Example:
The command that is sent to NXT is:
0x16 0x00 0x01 0x80 RobotAppStore1.txt\0\0
The command that is received from NXT as a reply is:
0x08 0x00 0x02 0x80 0x00 0x04 0x01 0x00 0x00 0x00
FileRead command
This command is used to read opened non-linear file handle, specified bytes of data.
When the reading command is finished successfully, the following operations are
performed:
- Response is sent with data;
- Internal reading cursor is referenced at the end of specified reading bytes; next
reading command will send data from this point and on;
Response message is NOT restricted to 64 bytes that the command telegram is limited to.
Syntax
[0x07] [0x00] [0x01] [0x82] [Handle id] [Required number of bytes LSB] [...] [...]
[Required number of bytes MSB]
Explanation:
- Byte 0-1: Command length LSB first.
- Byte 2: Command type- system command with a request for a response. Response
should always be requested for this command.
- Byte 3: Command- read.
- Byte 4: Handle id. This number is included in the response message of any
of the open file commands.
- Byte 5: How many bytes to read LSB first.
The reply message that is coming back looks like:
[???] [???] [0x02] [0x82] [0x00 or error] [Handle id] [Number of data that have
been read LSB] [Number of data that have been read MSB] [Data]
Explanation:
- Byte 0-1: Message length LSB first.
- Byte 2: Command type- reply message
- Byte 3: Command that has requested for this reply.
- Byte 4: Command status- 0x00 for success or error number for failure. Check
the
NXT File Handling over Bluetooth- Introduction chapter for error numbers.
- Byte 5: Handle id. The id of handle that has been requested to be read from.
- Byte 6-7: The number of bytes that has been actually read LSB first.
- Byte 8-N: Data itself.
Example:
RobotAppStore1.txt has been opened for read with 0x04 handle id. The text inside
this file is: Robot App Store rocks!!! Check for cool stuff at RobotAppStore.com.
We want to read the first 24 bytes.
The command that is sent to NXT is:
0x03 0x00 0x01 0x82 0x04 0x18 0x00
The command that is received from NXT as a reply is:
0x1F 0x00 0x02 0x82 0x00 0x04 0x18 0x00 Robot App Store rocks!!!\0
What's next?