File System (Disk) - Data Storage

 

Since Firmware version 003 (AA003A), µPanel implements a storage disk that can be used by the micro-controller to store non volatile data, such as measurements, calibration parameters, configuration data, and so on. A special filesystem (FS-RT78) has been designed by the µPanel engineers in order to implement an efficient high-reliable disk within the WiFi module flash memory. The main features are: 

  • 163.898 bytes of user space
  • sectors of 3563 bytes
  • file name length up to 12 characters 
  • immediate flush to disk (no latency)
  • write and verify architecture
  • up to 4 file simultaneously open (the same file allowed)
  • supported access modes: read / read-write / append / circular
  • file seek supported
  • case-sensitive names

Since reliability is one of the main feature that has been kept in mind during the design of the file-system, each sector can not contain more that one file. This means that the minimum space consumed by a file is of 3563 bytes and, therefore, no more than 43 files can be stored on the disk. Please note also that to make the file-system as much efficient as possibile, all the file are stored in the same root folder, and no sub-folder structure has been implemented. 

Since one of the most important application for the storage disk on µPanel based-systems is the storage of log or measurement files, a special file mode has been implemented: the circular mode. When a file is open in write-circular or append-circular modes it is possibile to set the number of sectors that the file should use on the disk. When the file size reaches the number of specified sectors, and a new write is required, the oldest sector is deleted and a new one is allocated. This way the disk will be never full and the file will always contains the latest written data. 

Two groups of commands exist to use storage disk:

  • DISK commands (provide functions to manage the disk content)
  • FILE commands (provide functions to work with files)

Disk Commands

Disk commands permit to initialise and manage the disk content. All the implemented commands start with $DISK: followed by a suffix that specifies the command. The full list of command follows.

$DISK:FORMAT (protected)

This command delete all the disk content and prepare the disk to be used. This command must be execute the first time the module is used to prepare the disk.

Command syntax

$DISK: FORMAT


Command results

$WAIT immediately after command reception and execution

$OK-FORMAT on completion

Example

To prepare the disk to be used the first time:  $DISK:FORMAT


$DISK:AUTOFORMAT (protected)

This command calls the $FORMAT command only if the DISK needs to be formatted, otherwise it does nothing

Command syntax

$DISK: AUTOFORMAT


Command results

$WAIT immediately after command reception and upon format execution

$OK-FORMAT on format completion

$OK-AFORMAT if the disk does not require to be formatted

Example

To prepare the disk to be used, formatting it only if necessary:  $DISK:AUTOFORMAT


$DISK:LS (protected)

This command shows a list reporting all the files stored on the disk. The command can be abridged as $DISK:L

Command syntax

$DISK: LS


Command results

$DISK-LS  immediately after command reception before the list is displayed

$LS: size file-name a formatted line reporting one list item (file name begins at column 15)

$OK-LS on completion, after the whole list has been displayed

Example

To obtain the file list:  $DISK:LS  

Command:

$DISK:LS

Response

$DISK-LS
$LS:    34769 measures.txt
$LS:     1755 calib.bin
$OK-LS

 


$DISK:SPACE (protected)

This command shows the amount of free space on the disk. The command can be abridged as $DISK:S

Command syntax

$DISK: SPACE


Command results

$DISK-FREE: x bytes  immediately after command reception before the list is displayed

Example

To obtain the amount of disk free:  $DISK:SPACE  

Command

$DISK:SPACE

Response

$DISK-FREE: 163898 bytes

 


$DISK:DEL (protected)

This command delete one file from the disk. The command can be abridged as $DISK:D

Command syntax

$DISK: DEL:FileName


Command results

$FILE-DELETED  immediately after command reception, after the file is deleted

Example

To delete a file whose name is measures.txt:  $DISK:DEL:measures.txt  

Command

$DISK:DEL:measures.txt

Response

$FILE-DELETED

 


File Commands

This set of commands permits to create, write and read file content. The current µPanel firmware support up to 4 files. Each file is identified by a digit in the range 0 to 3. Each command begins with the prefix $FILE followed by the digit file ID. 

The full list of file commands follows.

$FILE:OPEN (protected)

This command opens a file. The command can be abridged as $FILE:O

Command syntax

$FILE FILE_ID: OPEN: File_Name: File_Mode


Where:

  • FILE_ID is a digit in the range 0 to 3 to be used to identify this file during the file operations
  • FILE_NAME is a string up to 12 character long representing the file name (case sensitive)
  • FILE_MODE is a combination of the following (lower-case) characters that identify the open mode:
    • r - read mode: an existing file is opened for reading its content
    • w - write mode: existing file is deleted, a new file is created
    • a - if the file does not exist, it will be created. If the file exists it is opened in appending mode
    • c - circular mode. This mode has to be used along with w or a and permits to specify the maximum length in KB of the file. After this size the file is written as circular buffer. This parameter can be followed by the number of KB (e.g. wc7 will create a file for circular access with size no larger than 7 KB. Please note that, the c flag will never shrink a file already bigger than the specified size. If no size is specified a default value of 1 KB is used.


Command results

$FILEn:OPEN x bytes  immediately after command reception and file open (where n is the file ID and x the current file size)

Example

To open the file measure.txt in read-write-append mode using the ID 0:  $FILE0:OPEN:measures.txt:a  

Command

$FILE0:OPEN:measures.txt:a

Response

$FILE0:OPEN 34769 bytes

 


$FILE:SEEK (protected)

This command move the current file pointer on a different position. Please note that this command can be used both for read and write modes, however, due to the flash memory, writing on file positions already written can not change the byte values but can only set bits not yet set of those bytes (a full re-write capability may by supported in future releases). The command can be abridged as $FILE:S

Command syntax

$FILE FILE_ID: SEEK: New_Position


Where:

  • FILE_ID is a digit in the range 0 to 3 that identifies an open file
  • NEW_POSITION is the desired position in bytes from the file beginning. If the new position is bigger than the actual file size, the file pointer is positioned at the file end (if the file is opened in read mode), or the file size is increased (with empty bytes) until the pointer reaches the specified value.

Command results

$FILEn:SEEK: x  immediately after command reception and execution (where x is the new file position in bytes)

Example

To read an opened file (with ID 2)  from the byte number 10: $FILE2:SEEK:10 

Command

$FILE2:SEEK:10

Response

$FILE2:SEEK: 10

 


$FILE:WRITE (protected)

This command permits to write data into an open file. The command MUST be abridged as $FILE:W

Command syntax

$FILE FILE_ID: W Write_Mode: DATA


Where:

  • FILE_ID is a digit in the range 0 to 3 that identifies the open file to write into
  • WRITE_MODE is a combination of the following (uppercase) characters that define the write mode:

    • A (ascii) : the file is written in ASCII mode, which means that the DATA content passed in the write command is managed as pure text. Therefore, this mode does not allow to write to file special characters such as return carriage or null bytes.
    • B (binary) : the file is written in BINARY mode where all ASCII codes can be passed in the DATA content with the exception of the ASCII codes \r (13), \n (10), \0 (0), \\ (92), which have  to be "escaped". E.g. to write the ascii code 13 (\r) the sequence composed by the two chars \ and  has to be included into the DATA content.
    • R (return carriage \r) : append a return carriage (ascii code 13) at the end of the DATA content
    • N (new line \n) : append a new line (ascii code 10) at the end of the DATA content 
    • L (line end \r\n) : append a return carriage (ascii code 13) and a new line (ascii code 10) at the end of the DATA content

Please note that either the A or B mode must be specified after the W command. Please also note that if more than one termination option (R,N,L) is specified, the actual write order is L,N,R.

Command results

$FILEn:WR: x bytes immediately after command reception and execution (where x is the number of written bytes)

Example

To write the string "Hello World" terminated with a new line (\n) to the file with ID 1: $FILE1:WAN:Hello World 

Command

$FILE1:WAN:Hello World

Response

$FILE1:WR: 12 bytes

To write the string sequence of bytes 0x41 0x42 0x00 0x13 0x43 to the file with ID 0, the following command can be used:
$FILE0:WB:AB\0\rC 

Command

$FILE0:WB:AB\0\rC

Response

$FILE0:WR: 5 bytes

 


$FILE:READ (protected)

This command permits to read data from an open file. The command MUST be abridged as $FILE:R

Command syntax

$FILE FILE_ID: R Read_Mode :Parameters


Where:

  • FILE_ID is a digit in the range 0 to 3 that identifies the open file to read from
  • READ_MODE is a ONE of the following (uppercase) characters that define the read mode:

    • A (ascii) : the file is read in ASCII mode: the file is managed as text file and it is read line by line. When this file mode is used the Parameter field can specify the number of lines to be read and the maximum number of characters per line. If the line length exceeds the specified number of characters the line is truncated. Please note that the new line character (\n) is used to detect the line end.

      Example 1: $FILE0:RA:5,20 reads from file 0, 5 lines up to 20 characters for each line
      Example 2: $FILE0:RA:3 reads from file 0, 3 lines
      Example 3:
      $FILE0:RA read from file 0 only 1 line

      The command result for each read line has the following format:

      $FILE0:>A:Read_Line

    • B (binary) : the file is read in BINARY mode: a specified number of bytes are read from the file and then sent directly to the micro-controller, without any encoding. Before the bytes are sent, however, a text line is sent reporting the format and the number of read bytes. When this mode is used, the Parameter field can specify the number of bytes to read. The maximum value is 256. If the parameter is not given the default used value is 256.

      Example:
      $FILE0:RB:10 reads 10 bytes from the file with ID 0 and send them to the micro-controller. Before the bytes are sent, however, the following line is also sent (which as always includes the new line terminator \n):

      $FILE0:>B#0010:

      where #0010 represent the number of bytes that will be sent to the micro-controller (without encoding)

    • X (hexadecimal) : the file is read in Hexadecimal mode: a specified number of bytes are read from the file and displayed in hexadecimal format. When this mode is used the Parameter field can specify the number of bytes to read. The maximum number of bytes that can be read with a single command is 256. If the parameter is not specified the default used value is 256.

      Example: $FILE0:RX:8 reads 8 byte from the file with ID 0 and displays them in hexadecimal

      The command result of the previous example would be:

      $FILE0:>X#0008:xx xx xx xx xx xx xx xx

      where #0008 represents the number of following bytes, and xx the read bytes in hex format

    • D (decimal) : the file is read in Decimal mode: a specified number of bytes are read from the file and displayed in decimal format. The parameter syntax is the same as for X mode

      Example: $FILE0:RD:4 reads 4 byte from the file with ID 0 and displays them in decimal (always 2 digit)

      The command result of the previous example would be:

      $FILE0:>D#0004:xxx xxx xxx xxx

      where #0004 represents the number of following bytes, and xxx the read bytes in decimal format (always 3 digits)

Please note that only one of the previous mode can selected. Please also note that the number of bytes actually returned by the reading function can be less than the requested number when the end of file is reached.

Command results

The command results depends on the read mode, please see the previous description

 


$FILE:CLOSE (protected)

This command permits to close an open file, freeing the allocated resources. Please note, that data are written to the file immediately after the write command. Therefore, this command has no effect on the disk content and if the system is turned-off before the close is executed, no data are lost. The command can be abridged as $FILE:C

Command syntax

$FILE FILE_ID: CLOSE


Where:

  • FILE_ID is a digit in the range 0 to 3 that identifies the open file to close

Command results

$FILEn:CLOSED where n is the ID of the file that has been closed

Example

To close the file with ID 1: $FILE1:CLOSE 

Command

$FILE1:CLOSE

Response

$FILE1:CLOSED

 


Error Messages

Different error messages can appear after the execution of DISK and FILE commands. The full list of message follows.

$ERR-FS: 01 (Generic) Internal unexpected error

$ERR-FS: 02 (Memory) No enough memory to complete the operation

$ERR-FS: 03 (Disk) Flash memory support error

$ERR-FS: 04 (Disk IO) Impossible to read or write on flash memory

$ERR-FS: 05 (Generic) Unexpected error looking for a sector

$ERR-FS: 06 (Format) Disk not formatted

$ERR-FS: 07 (Permission) Operation not permitted (e.g. write on read file)

$ERR-FS: 08 (Write) Write operation error

$ERR-FS: 09 (Read) Read operation error

$ERR-FS: 10 (File Not Found) Specified file name not found

$ERR-FS: 11 (Disk Full) Operation not completed since the disk is full