File System

Most connected applications require the ability to store configuration information or cache local data. WiConnect provides a reliable read/write filesystem and on-board extended flash storage to satisfy application storage requirements. Bulk flash, external to the module, can also be used. See Internal, Extended and Bulk Flash.

With just a few simple commands, WiConnect provides your application with complete access to local and network connected storage.

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:

file_create     hello.txt 12
Hello World!

file_open       hello.txt
stream_read     0 3

stream_read     0 50

file_delete     hello.txt

<- Create file, length 12 bytes
<- Enter file contents
  (echoed if system.cmd.echo = 1)
<- Open file for reading
<- Read no more than 3 bytes 
  (file stream handle = 0)
<- Read no more than 50 bytes 
  (close file if EOF reached)
<- Delete file

File Listing

Most ACKme Wi-Fi modules contain a microprocessor with internal flash and an extended (on module) serial flash. An additional (optional) bulk serial flash is also supported. See Internal, Extended and Bulk Flash.

To obtain a verbose listing of all files on the MCU-internal flash, extended (and bulk) 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  /setup/images.png
#  2 e-FE   0001   52   10525   2.0.0.11  /setup/index.css.gz
#  3 e-FE   0001   65   10155   2.0.0.11  /setup/index.html
#  4 e-FE   0001   55   39247   2.0.0.11  /setup/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  upgrade_app.exe
# 10 i-81   001B   52  178252    2.0.1.8  wiconnect.exe
# 11 e-01   0009    0  203261  5.26.230.3  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, extended or bulk flash:

• i - MCU internal flash
• e - extended serial flash
• b - bulk serial flash

See Internal, Extended and Bulk Flash below.

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

File types are used internally by WiConnect for file management.

WiConnect file types are enumerated in the following table.

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:

With the exception of the Essential and the Unprotected flags, the file flags can be set and used only by WiConnect internally.

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

Examples:

File Version

For files that form part of the WiConnect system, such as wiconnect.exe and upgrade_app.exe, 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:

See the crc_wiconnect.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.

Special Files

Some files with special functions are listed in the following table:

Writing Files to the File System

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

• file_create
• http_download

There are several ways to invoke these commands:

• Via the WiConnect Web App. This is the simplest way to manage files manually.
• Manually, via a WiConnect terminal or a remote terminal
• Under programmed MCU host control
• Via the HTTP Server RESTful API

Writing with the WiConnect Web App File Browser

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

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

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

Writing with a WiConnect 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 to a Stream 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.

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

> fcr -o hello.txt 11
[Opened: 0]
0
> write 0 6
Hello
Success
> write 0 5
World
File created
[Closed: 0]
Success
> fop hello.txt
[Opened: 0]
0
> read 0 1000
Hello World
[Closed: 0]

Create file; leave stream open; specify total length

Response: open stream
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
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 WiConnect system files automatically from ACKme OTA update servers online. Please contact ACKme if you need custom hosting services for your application firmware or files.

Reading Files from the File System

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

• file_open
• http_upload

There are several ways to invoke these commands:

• Via the WiConnect Web App. This is the simplest way to manage files manually.
• Manually, via a WiConnect terminal or a remote terminal
• Under programmed MCU host control
• Via the HTTP Server RESTful API

Reading with the WiConnect Web App File Browser

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

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

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

Reading from a WiConnect Terminal or Remote Terminal

You can read text files directly from the WiConnect 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.

Internal, Extended and Bulk Flash

A WiConnect module contains internal flash inside the microprocessor and an extended flash chip for user storage.

Extended flash is serial flash.

In addition, an external serial flash can be connected to the module using the existing sflash GPIOs. This is referred to as bulk flash. To enable access to bulk flash, configure the chip select GPIO with the system.bflash.cs_gpio variable.

By default WiConnect can support up to 128MB bulk flash.

Internal flash cannot be manipulated by WiConnect commands.

All OTA files and config files (created by the save command) are always stored on extended flash regardless of whether the bulk flash is enabled.

The following commands operate on bulk flash if available, otherwise on extended flash:

• http_download - saves file to bulk flash if available, otherwise to extended flash
• file_create - saves file to bulk flash if available, otherwise to extended flash
• file_open - opens file if found on bulk flash, otherwise on extended flash
• file_delete - deletes file if found on bulk flash, otherwise on extended flash

Extended and bulk flash can be formatted with the format_flash command.

Supported Bulk Flash Chips

Serial flash chips currently supported by WiConnect are as follows:

If you require support for a serial flash chip not listed in the table above, please contact ACKme.

Connecting Bulk Serial Flash to the Module

The WiConnect module is the SPI master. The bulk sflash is the SPI slave.

Connecting bulk sflash to the module requires 4 signals. The GPIO numbers vary depending on the module, as follows:

Use the format_flash bulk command to erase the contents of the sflash.

The bulk sflash uses the same SPI bus as the extended sflash on-board the module. Thus the SPI parameters (clock speed, polarity, etc) are not configurable.