File System

Most connected applications require the ability to store configuration information or cache local data. ZentriOS provides a reliable read/write filesystem and access to extended flash storage to satisfy application storage requirements.

Zentri Wi-Fi modules contain a microprocessor with internal flash and an extended (on module) serial flash. See Flash Storage. For third-party devices running ZentriOS, an extended serial flash must be provided to store temporary files and to enable wireless OTA updates.

Commands are available to create, delete and open files, and file contents can be easily accessed using one or more stream commands.

Here's a quick example showing how to create, manipulate then delete a file:

ZentriOS Commands Description

> file_create     hello.txt 12
Hello World!

Success
> file_open       hello.txt
0
> stream_read     0 3
Hel
> stream_read     0 50
lo World!
> file_delete     hello.txt
Success

<- Create file, length 12 bytes
<- Enter file contents
  (echoed if system.cmd.echo = 1)

<- Open file for reading
(ZentriOS returns file stream handle = 0)
<- Read no more than 3 bytes

<- Read no more than 50 bytes
  (close file if EOF reached)
<- Delete file

When a file is open, ZentriOS creates a file stream and returns a file stream handle to be used as an argument of the stream_read command. See Network Connections and Streams. The stream type is FILE.

File System Limits

Minimum File Size

Files are created 4KByte aligned; that is, no file can occupy less flash space than 4K.

Maximum File Size

There is no limit to the size of an individual file other than the size of the extended or bulk serial flash connected to the ZentriOS hardware. However the method of creating the file may impose a limit.

When creating files via the file_create command, or via the Web App, which uses file_create in the background, file size is limited by available RAM at file creation.

Typically, it is not possible to create files larger than 30000 bytes, and depending on available RAM, the maximum file size may be smaller.

Maximum File Count

The minimum flash space occupied by files is <number of files> * 4K. For example, in 20K of flash you can create no more than 5 files .

ZentriOS-WL supports a maximum of 32 files on extended serial flash.

Listing Files

To list files, use the ls command.

To obtain a verbose listing of all files on the MCU-internal flash and extended serial flash, use the ls command with the -v option. Users are only permitted to write files to serial flash.

> ls -v
!  # Type  Flags  Hnd    Size    Version  Filename
#  0 e-FE   0001   73    1853   2.0.0.11  /favicon.ico.gz
#  1 e-FE   0001   68   18067   2.0.0.11  webapp/images.png
#  2 e-FE   0001   52   10525   2.0.0.11  webapp/index.css.gz
#  3 e-FE   0001   65   10155   2.0.0.11  webapp/index.html
#  4 e-FE   0001   55   39247   2.0.0.11  webapp/index.js.gz
#  5 e-FB   0001   74   36511    2.0.1.8  command_help.csv
#  6 e-FD   0001   51     135   2.0.0.11  default_setup.script
#  7 e-03   0001   50    1236   2.0.0.11  geotrust_ca.pem
#  8 e-FE   0021   84    2074    1.0.0.0  my_ca.pem
#  9 i-00   001B    0  212736    2.0.1.8  sys/kernel.bin
# 10 i-81   001B   52  178252    2.0.1.8  sys/services.bin
# 11 e-01   0009    0  203261  5.26.230.3  sys/wifi_fw.bin
# 12 b-FE   0021   25 1995261    2.1.0.0  DSC20564.JPEG

File Types

In the ls file listing, Type column, a prefix indicates the location of the file in internal, or extended flash:

See Flash Storage below.

For example, e-FE indicates a file in extended serial flash with a file type of 0xFE.

File types are used internally by ZentriOS for file management.

ZentriOS file types are enumerated in the following table.

File typeID (hex)ID (dec)
KERNEL0x000
WIFI_FW0x011
SHARED_LIB0x022
TLS_CERT0x033
TXT_LOG0x044
NVM0x055
MISC_APP0x80128
SERVICES0x81129
SAFEMODE_APP0x84132
Custom type0x96 - 0xC7150 - 199
TEMPORARY0xF9249
GPIO_CONFIG0xFA250
COMMAND_HELP0xFB251
SDC_CAPS0xFC252
SETUP_SCRIPT0xFD253
MISC_FIX_LEN0xFE254
TYPE_INVALID0xFF255

Custom User Types

The type range from 0x96 (decimal 150) to 0xC7 (decimal 199) is set aside for custom types. Use types in this range for file management specific to your application.

File Flags

Flags are displayed in the file listing in hex format, without a 0x prefix.

The flags correspond to bits as follows:

FlagBitNotes
Valid0
Executable1
Internal3
Bootable4
User5
Essential6This flag can be explicitly set with the -e flag for file_create, http_download
Backup7
Unprotected8This flag can be explicitly set with the -u flag for file_create, http_download
Log9

Only the Essential and the Unprotected flags can be explicitly set using a command.

The file_create and http_download commands provide -e and -u options to set the Essential and Unprotected flags.

Examples:

Flags columnFlags Set
001BValid Executable Internal Bootable
0021Valid User
0061Valid User Essential
0121Valid User Unprotected
0161Valid User Essential Unprotected

File Version

For files that form part of the ZentriOS system, such as services.bin and kernel.bin, the file version follows the scheme:

<major>.<minor>.<patch>.<release_candidate>

When creating a user file, the user can choose the versioning scheme. The file_create and http_download commands provide a version option to set the version.

File Checksum

The checksum used on individual files is calculated using a CCITT CRC-16 algorithm with polynomial 0x1021. The full set of CRC parameters is as follows:

ParameterValue
CRC Order16
CRC Polynomial0x1021
Initial ValueFFFF (direct)
Final XOR0x0
Reverse data bytesYes
Reverse CRCNo

See the crc_zentrios.py python script and the crccitt_test.c C source for demonstrations of calculating the CRC.

The file_create and http_download commands provide an option to set the CRC.

You can view a file CRC with the file_stat command. The CRC is the second item in the comma-separated list.

See also the File System application note.

Writing Files

There are two ZentriOS commands that can write to the file system:

There are several ways to invoke these commands:

Writing with the Web App File Browser

When you open the ZentriOS Web App in a web browser and select the Files tab, you can load files to the device file system using click and browse, or drag and drop.

In the background, the ZentriOS Web App uses the file_create command to write files to the device file system, using the HTTP Server RESTful API.

There are several ways to activate the ZentriOS Web App. See ZentriOS Web App.

Writing with the Terminal

In the ZentriOS terminal or remote terminal, use the file_create command to create the file. Immediately after issuing the command, type the file contents, or alternatively copy and paste the file contents into the terminal after issuing the fcr command. The length of the file must be supplied. The character count includes any line termination characters.

In the example below we create a script that can be run using the command setup cmd -v test.script. In this case the character count is 35.

> fcr test.script 35
help,setup,\r\n#This is a comment

File created
Success

Writing File Contents in Chunks

You can write the file in chunks by leaving the file open after issuing the file_create with the -o option. Write the file chunks to the stream returned by the file_create command. You must know the total size of the file to be created in advance.

When you open the file, ZentriOS returns a stream handle, to be used as an argument of the stream_write command. See Network Connections and Streams.

In the example below a small file is created in two chunks:

Commands and ResponsesDescription

> file_create -o hello.txt 11
[Opened: 0]
0
> stream_write 0 6
Hello
Success
> stream_write 0 5
World
File created
[Closed: 0]
Success
> file_open hello.txt
[Opened: 0]
0
> stream_read 0 1000
Hello World
[Closed: 0]

Create file; leave stream open; specify total length

Response: open stream and return stream handle
Write first chunk; specify chunk length
Send chunk content (includes trailing space)

Write second chunk; specify chunk length
Send chunk content

Stream closed

Open new file

Response: open stream and return stream handle
Read contents

Stream closed

HTTP Download

You can also provide the file for download from a web server accessible to the device, and use the http_download command. For example:

> http_download http://www.google.com.au/images/srpr/logo11w.png test1.png
Downloading: test1.png to flash file system
Request GET /images/srpr/logo11w.png
Connecting (http): www.google.com.au:80
HTTP response: 200
Success
> ls
!  #   Size   Version  Filename
…
#  4  14022     1.0.0  test1.png
…

OTA

OTA wireless updates allow you to update the ZentriOS system files automatically from Zentri OTA update servers online. Please contact Zentri if you need custom hosting services for your application firmware or files.

Reading Files

The following ZentriOS commands can read from the file system:

There are several ways to invoke these commands:

Reading with the Web App File Browser

When you open the ZentriOS Web App in a web browser and select the Files tab, you can download a file from the device file system by clicking the file name.

In the background, the ZentriOS Web App uses the file_open command to read the files from the device file system, using the HTTP Server RESTful API.

There are several ways to activate the ZentriOS Web App. See ZentriOS Web App.

Reading from a Terminal

You can read text files directly from the ZentriOS Terminal or remote terminal. Read the file, using a file_open followed by a stream_read command, specifying the stream index returned from the file open, e.g.:

> fop default_setup.script
[Opened: 0]
0
> read 0 1000
network_up,-s    ,Configuration network credentials
set wlan.auto_join.enabled,true,Enable network auto-join
save,-,Saving settings

[Closed: 0]

HTTP Upload

You can upload the file to an available web server with file upload capability with the http_upload command.

Flash Storage

A ZentriOS device contains internal flash inside the microprocessor and an extended flash chip for user storage.

Extended flash is serial flash. Internal flash cannot be manipulated by ZentriOS commands.

Encrypting ZentriOS Files

The python script crypto_util.py demonstrates encrypting and decrypting files which can be used by ZentriOS.

Encrypted File Format

A ZentriOS encrypted file has the following format:

So an encrypted file is always 32 bytes longer than a file with same contents unencrypted.

Encryption Sequence

The sequence for encrypting a file is as follows:

  1. Generate Initialization Vector (IV)
  2. Initialize AES-128 context with the user AES key
  3. Calculate the Cipher Block Chaining (CBC) of the entire file, IV=0, and pad with 0s to 16 bytes if necessary, the last 16 bytes of the encrypted output is used as the HMAC
  4. Write the initial IV (the IV from step 1) to the output file/buffer
  5. Using the IV from step 1 and AES-128 context from step 2, using CTR mode encrypt HMAC and write to output file/buffer
  6. Using IV from step 5 and AES-128 context from step 2, using CTR mode encrypt file contents and write to output file/buffer

Decryption Sequence

The sequence for decrypting a file is as follows:

  1. Initialize AES-128 context with the user AES key
  2. Read the 16 byte IV from the beginning of the encrypted file
  3. Read the 16 bytes encrypted HMAC from the file
  4. Using the AES context from Step 1 and the IV from Step 2, decrypt the HMAC using AES CTR mode
  5. Using the AES context and IV from step 4, decrypt the rest of the file using AES CTR mode
  6. Calculate the Cipher Block Chaining (CBC) of the decrypted file data from step 5, IV=0, and pad with 0s to 16 bytes if necessary
  7. The final block from step 6 should match the HMAC from step 4. If the two 16 byte values don't match then either the given user key is invalid or the encrypted file is corrupted.

Preventing File Corruption

The ZentriOS file system is designed to be resistant to file corruption. A file does not appear in the file system until it is marked as valid. See File Flags. A file is marked as valid only after all file data is written and validated. When a file is not valid, it cannot be listed with the ls command or opened with the file_open command. A valid file may not be modified. That is, file size and contents cannot be modified after the file is created.

This ensures the file system does not become populated with corrupt files due to sudden power loss, reset, or interruption of the file stream during writing.

The steps in file creation are as follows:

If the module is reset or power cycled, or the file stream is manually closed before the valid flag is set, the created file and any written contents are lost.

Once the valid flag is set, the file may not be modified.