File System

See File System for a general discussion of the Gecko OS file system.

The commands for creating files are file_create and http_download.

Below are provided examples of various uses of the commands for manipulating files.

Prerequisites

It is assumed you have a Gecko OS device with a Gecko OS terminal running.

Both your test platform and the Gecko OS device should be connected to the same network. See Getting Start, Configuring Wi-Fi Credentials on the Device.

In the examples below, "test platform" means your test platform, such as a computer, and "in the Gecko OS terminal" means at the prompt of the Gecko OS terminal connected to your module.

Some examples assume you have python installed on your test platform (available for Windows, Linux or Mac).

Loading a File onto the Gecko OS Device

There are several ways to load a file onto the Gecko OS device.

For full details see File System, Writing Files.

Open a Gecko OS terminal to the device. See Getting Started, Opening a Gecko OS Terminal.

Using the Web App Files Tab

The easiest way to do this is to use the Web App provided with Gecko OS. To start the webapp, issue the following command to the device from the Gecko OS terminal:

> setup web

This starts the Gecko OS softAP and webserver. Connect your computer to the Gecko OS Wi-Fi network. By default, the network name is Gecko OS-XXX, (where XXX is the last 3 digits of the device MAC address).

Then open a web browser and enter the URL: http://setup.com

Wait for the Gecko OS webapp to load, then click on the Files tab. The Files tab enables you to drag and drop files from your test platform file browser to the file system on the Gecko OS device.

On your computer, find the file to load on the Gecko OS device.

Drag this file onto the Gecko OS webapp target area where it says Drop files here. Alternatively, click the button labelled Click to add files.

That's it! The file is now stored in non-volatile memory on the Gecko OS device flash file system.

Using File Create

You can also use the file_create command to load a file onto the Gecko OS device.

Determine the exact size of the file (number of characters, including whitespace and carriage returns). For text files, you can use a text editor.

Issue the following Gecko OS command:

> file_create <filename> <file size>

where <filename> is the name under which the file appears in the Gecko OS file system, and file size is the exact file size in bytes.

Then send the contents of the file to the Gecko OS terminal. This writes the file to the flash file system on the Gecko OS device. If you are sending a text file, you can copy and paste the file contents from a text editor to the Gecko OS terminal.

The file_create command requires the exact file size, so it is critical that the line endings of the file do not change. Ensure that the system you are using to send the file does not convert line endings.

Using http_download

If you are able to place the file on an HTTP server accessible to the Gecko OS device, you can use the http_download command to load the file on the device.

If you have Python installed, you can run a local HTTP server on your test computer using python with the command line:

> python -m SimpleHTTPServer
Serving HTTP on 0.0.0.0 port 8000 ..

The python HTTP server root directory is the directory from which the python command was issued.

Determine the IP address of your computer. If the file to download is in the top level directory from which you issued the python HTTP server command, the file url is http://<server_ip>:<server_port>/<filename>.

In the above example, <server_port> is 8000.

On your Gecko OS terminal, issue the command:

http_download <file_url>

where <file_url> is the url of the file on the HTTP server.

e.g

> hdo http://192.168.6.41:8000/test1.html
Downloading: test1.html to flash file system
Request GET /test1.html
Connecting (http): 192.168.6.41:8000
Success

File Types

File types are used internally by the Gecko OS file system. A range of file types is set aside for custom user types. Unless you have a custom use for the file type, create files with the default type of 0xFE.

The 0xFE type is used by default if you don't provide the <type> parameter to the file_create command or the http_download command. For example:

> file_create my_file.txt 39

If you wish to supply a <crc> parameter for the file_create command, you must supply a <type> argument as a placeholder. See the example below in Using file_create with a CRC.

Verifying File Integrity with a Checksum

A file checksum can be supplied when creating a file, to ensure that only a valid file is stored in the Gecko OS file system.

The algorithm for generating the CRC (Cyclic Redundancy Check) is described in File System, File Checksum.

Using file_create with a CRC

To generate the CRC, download the crc_gecko_os.py python script. This demonstrates the parameters for the CRC algorithm.

Run the demonstration on your test platform, giving the file crc_gecko_os.py as the filename parameter:

python crc_gecko_os.py crc_gecko_os.py

Assuming the file has CR-LF line endings, the length and CRC are calculated as follows in the output:

filepath: crc_gecko_os.py
length:   3409
CRC:      0x3ed6

file_create command:
> fcr <filename> <length> <version> <type> <crc>
Example:
> fcr crc_gecko_os.py 3409 1.0.0 0xFE 0x3ed6

The crc_gecko_os.py output example file_create command shows how to provide the parameters. Note that the file type must be supplied as a placeholder. The default file type of 0xFE is used here.

In the Gecko OS Terminal, issue the command as supplied to create the file crc_gecko_os.py on the module file system:

> fcr crc_gecko_os.py 3409 1.0.0 0xFE 0x3ed6

Immediately after issuing the command, send the contents of the file crc_gecko_os.py to the terminal.

If after the file is created, the calculated CRC doesn't match the CRC specified, the following error is displayed:

Failed to verify checksum

and Gecko OS sets the file type to 0xFF invalid, effectively cancelling file creation.

If the CRC matches, the file is successfully created:

File created

To verify that the file has been created, in the Gecko OS terminal issue the ls -l command.

File created
> ls -l
!  # Type  Flags  Hnd    Size       Version  Filename
...
#  6 e-FE   0021   39    3409       1.0.0.0  crc_gecko_os.py
...

To verify the file contents visually, open the file and read its contents:

> fop crc_gecko_os.py
[2015-03-09 | 05:58:10: Opened: 0]
0
> read 0 3409
#!/usr/bin/env python
# -*- coding: utf8 -*-

# CRC CCITT
...
if __name__ == '__main__':
    main()

[2015-03-09 | 05:58:15: Closed: 0]

You can also supply a CRC with the http_download command.

Downloading Files from an HTTP Server

The http_download command allows you to download one or many files from an HTTP server.

You can run a local HTTP server on your test platform using python with the command line:

> python -m SimpleHTTPServer
Serving HTTP on 0.0.0.0 port 8000 ..

The python HTTP server root directory is the directory from which the python command was issued.

The Web App development system runs a local HTTP server on your system. The file examples shown below refer to the files generated in Web App development. Running the Web App development system is explained in Web App Customization.

Assuming your test platform HTTP server is at the address 10.5.6.60:5002, the following http_download commands, issued in the Gecko OS terminal, download the files from the server to your module file system:

hdo http://10.5.6.60:5002/index.html webapp/index.html
hdo http://10.5.6.60:5002/webapp/unauthorized.html webapp/unauthorized.html
hdo http://10.5.6.60:5002/webapp/Gecko OS.css.gz webapp/Gecko OS.css.gz
hdo http://10.5.6.60:5002/webapp/Gecko OS.js.gz webapp/Gecko OS.js.gz

Note that there's no need to specify the length of the files, as this is supplied by the HTTP server.

The response is similar to the following:

> hdo http://10.5.6.60:5002/index.html webapp/index.html
Downloading: webapp/index.html to flash file system
Request GET /webapp/index.html
Connecting (http): 10.5.6.60:5002
HTTP response: 200
Success
> hdo http://10.5.6.60:5002/index.html webapp/index.html
Downloading: webapp/index.html to flash file system
Request GET /index.html
Connecting (http): 10.5.6.60:5002
HTTP response: 200
Success
> hdo http://10.5.6.60:5002/webapp/Gecko OS.css.gz webapp/Gecko OS.css.gz
Downloading: webapp/Gecko OS.css.gz to flash file system
Request GET /webapp/Gecko OS.css.gz
Connecting (http): 10.5.6.60:5002
HTTP response: 200
Success
> hdo http://10.5.6.60:5002/webapp/Gecko OS.js.gz webapp/Gecko OS.js.gz
Downloading: webapp/Gecko OS.js.gz to flash file system
Request GET /webapp/Gecko OS.js.gz
Connecting (http): 10.5.6.60:5002
HTTP response: 200
Success

Downloading Multiple Files with a File Manifest

The http_download command can download multiple files using a json manifest.

The example below demonstrates downloading the files for a modified Web App from a server at http://10.5.6.60:5002.

Issue the http_download command with the -m option. Note that you must supply the length of the manifest file.

> hdo -m 814

Then immediately send the manifest file. The file length supplied assumes CR-LF line endings.

{
   "path"  : "http://10.5.6.60:5002",
   "files" : [
        {
            "remote"  : "index.html",
            "local"   : "webapp/index.html",
            "version" : "1.0.1",
            "flags"   : "eu",
        },
        {
            "remote"  : "webapp/unauthorized.html",
            "local"   : "webapp/unauthorized.html",
            "version" : "1.0.1",
            "flags"   : "eu",
        },
        {
            "remote"  : "webapp/Gecko OS.css.gz",
            "local"   : "webapp/Gecko OS.css.gz",
            "version" : "1.0.1",
            "flags"   : "eu",
        },
        {
            "remote"  : "webapp/Gecko OS.js.gz",
            "local"   : "webapp/Gecko OS.js.gz",
            "version" : "1.0.1",
            "flags"   : "eu",
        }
    ]
}

The response is similar to the following:

Downloading: webapp/index.html to flash file system
Request GET /index.html
Connecting (http): 10.5.6.60:5002
HTTP response: 200
Downloading: webapp/unauthorized.html to flash file system
Request GET /webapp/unauthorized.html
Connecting (http): 10.5.6.60:5002
HTTP response: 200
Downloading: webapp/Gecko OS.css.gz to flash file system
Request GET /webapp/Gecko OS.css.gz
Connecting (http): 10.5.6.60:5002
HTTP response: 200
Downloading: webapp/Gecko OS.js.gz to flash file system
Request GET /webapp/Gecko OS.js.gz
Connecting (http): 10.5.6.60:5002
HTTP response: 200
Success

Supporting Gecko OS Editions and Versions

Change Log

ModifiedChanges
2015-03-05Created