Lego NXT File Handling- Create Files

Please make sure you've read the "Introduction To File Handling" tutorial before you continue reading this chapter.

Download or transfer files to NXT's brick

In order to send files to NXT's brick, the following operation must be completed:

• Create an empty file on the NXT using one of the commands that are described in this chapter (according to file's type);
• Use the FileWrite command to write the transferred file's bytes to the empty file that has just been created (will be discussed in the NXT File Handling- Write To File chapter);
• Use the FileClose command to save the changes in the file (we will go deeper into that in the NXT File Handling- Save and Close tutorial);

Differences between the "File Create" commands

Each command is used for a specific file type.
Executable files (and icons) need a linear (serial) memory allocation when they are created,
while textual files can be fragmented (memory allocation for these files can be done on separate places on the disc).

Use the following create file commands according to file type:

• TextFileOpenWriteCreate- for textual files (txt and log extensions).
  This is the only file type that can be edited and read;
• LinearFileOpenWriteCreate- for executable files and for icons (rxe, sys, rpg, rtm, ric file types);
• FileOpenWriteCreate- for the rest of the file types;

"File Create" commands workflow

When a file is created successfully, the following general operations are performed:

• The file is created in the file system of NXT’s brick or in RAM (It depends on the "Create File" command that was used.), with the specified name and size;
• File handler is created;
• The specified file newly created handler is registered to the tracker table; therefore, ResolveHandle command will be able retrieve this file handler according to a file name (will be discussed in later posts);
• The file is opened for writing purposes;

When a failure has occurred, the following general operations are performed:

• The file is not created; therefore, no open handler is created;
• Fake opened file handler is returned with the response message;

TextFileOpenWriteCreate command

This command is used to create a new textual file (txt, log extensions) on NXT's brick.

When a file is created successfully, the following operations are performed:

• The file is created in the file system of NXT’s brick with the specified name and size;
• File handler is created;
• The specified file newly created handler is registered to the tracker table; therefore, ResolveHandle command will be able retrieve this file handler according to a file name (will be discussed in later posts);
• The file is opened for writing purposes;
• Pending file write buffers are committed to flash memory;

Make sure that specified file name doesn’t exist in the system.

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, four files that can be opened for writing purposes at the same time and 127 files that can be created in the file system.

Syntax

[0x1A] [0x00] [0x01][0x8B] [fileName.fileType] [File size LSB] [...] [...] [File size 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- textual file create and open for writing purposes.
• 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.
• Byte 24-27: File size. The number of bytes that will be written to the file. LSB first.

The reply message that is coming back looks like:

[0x04] [0x00] [0x02] [0x8B] [0x00 or error] [handler id]

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: handler id. The id of handler that has been requested to be created.

Example:

Create a file that its size is 1KB = 1024 Bytes, that is 00000400 in hex or 0x00 0x04 0x00 0x00 LSB first.


The command that is sent to NXT is:
0x1A 0x00 0x01 0x8B RobotAppStore1.txt\0\0 0x00 0x04 0x00 0x00

The command that is received from NXT as a reply is:
0x04 0x00 0x02 0x8B 0x00 0x04

LinearFileOpenWriteCreate command

This command is used to create a new executable or an icon file (rxe, sys, rpg, rtm, ric) on NXT's brick. Executable and icon files cannot be fragmented; therefore the memory allocation for them should be linear.

When a file is created successfully, the following operations are performed:

• The file is created in the RAM of NXT’s brick with the specified name and size;
• File handler is created;
• The specified file newly created handler is registered to the tracker table; therefore, ResolveHandle command will be able retrieve this file handler according to a file name (will be discussed in later posts);
• The file is opened for writing purposes;

Make sure that specified file name doesn’t exist in the system.

All opened files handlers 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 move the file from the RAM to the flash memory (to save the file on the file system) and free unused resources.

Make sure you will finish all the writing operations before closing the file. Existing linear files cannot be opened for editing.

There is a limitation of 16 opened file handlers (read and write) in the same thread, four files that can be opened for writing purposes at the same time and 127 files that can be created in the file system.

Syntax

[0x1A] [0x00] [0x01][0x89] [fileName.fileType] [File size LSB] [...] [...] [File size 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- linear file create and open for writing purposes.
• 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.
• Byte 24-27: File size. The number of bytes that will be written to the file. LSB first.

The reply message that is coming back looks like:

[0x04] [0x00] [0x02] [0x89] [0x00 or error] [handler id]

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: handler id. The id of handler that has been requested to be created.

Example:

In order to create a file that its size is 1KB = 1024 Bytes, that is 00000400 in hex or 0x00 0x04 0x00 0x00 LSB first.
The file will not appear in the file system of the NXT's brick until it is completely filled with relevant rxe data, and FileClose is called.

The command that is sent to NXT is:
0x1A 0x00 0x01 0x89 RobotAppStore1.rxe\0\0 0x00 0x04 0x00 0x00

The command that is received from NXT as a reply is:
0x04 0x00 0x02 0x89 0x00 0x04

FileOpenWriteCreate command

This command is used to create a new non textual and nonlinear file (rso, cal) on NXT's brick.

When a file is created successfully, the following operations are performed:

• The file is created in the file system of NXT’s brick with the specified name and size;
• File handler is created;
• The specified file newly created handler is registered to the tracker table; therefore, ResolveHandle command will be able retrieve this file handler according to a file name (will be discussed in later posts);
• The file is opened for writing purposes;

Make sure that specified file name doesn’t exist in the system.

All opened files handlers 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 move the file from RAM to the flash memory (commit changes), and free unused resources.

Make sure you will finish all the writing operations before closing the file. Only textual files can be opened for editing.

There is a limitation of 16 opened file handlers (read and write) in the same thread, four files that can be opened for writing purposes at the same time and 127 files that can be created in the file system.

Syntax

[0x1A] [0x00] [0x01][0x81] [fileName.fileType] [File size LSB] [...] [...] [File size 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- file create and open for writing purposes.
• 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.
• Byte 24-27: File size. The number of bytes that will be written to the file. LSB first.

The reply message that is coming back looks like:

[0x04] [0x00] [0x02] [0x81] [0x00 or error] [handler id]

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: handler id. The id of handler that has been requested to be created.

Example:

In order to create a file that its size is 1KB = 1024 Bytes, that is 000400 in hex or 0x00 0x04 0x00 0x00 LSB first.
The file will not appear in the file system of the NXT's brick until it is completely filled with relevant rso data, and FileClose is called.

The command that is sent to NXT is:
0x1A 0x00 0x01 0x81 RobotAppStore1.rso\0\0 0x00 0x04 0x00 0x00

The command that is received from NXT as a reply is:
0x04 0x00 0x02 0x81 0x00 0x04

What's next?

Let's move forward and learn how to read a file on NXT's file system over Bluetooth communication protocol (LCP)

click here looking for affair why do wife cheat