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 Gecko OS 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 softAP 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

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 checksum or CRC (Cyclic Redundancy Check) is described in File System, File Checksum.

Using file_create with a CRC

To generate the CRC, you can use the following python fragment:

import binascii

def crc32(data):
    return binascii.crc32(data) & 0xffffffff

This is demonstrated in the crc_gecko_os.py script. This script takes a filepath as the first argument, calculates its length and checksum, and generates a file_create command including a crc argument.

Download and run the demonstration on your computer, 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:   1304
CRC:      0x14a83225

file_create command:
> fcr <filename> <length> [-v <version>] [-t <type>] [-c <crc>]
Example:
> fcr crc_gecko_os.py 1304 -v 1.0.0 -t 0x44 -c 0x14a83225

The crc_gecko_os.py output example file_create command shows how to provide the parameters. Note that the -v version and -t type parameters are supplied only to demonstrate how they are used. You can use the -c parameter without supplying version or type. The default file type of 0x44 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 1304 -v 1.0.0 -t 0x44 -c 0x14a83225

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
!  # L Hnd Type Flag O Perm    Size    Created   Version Filename
...
#  1 e  F8   44 0401 u FFFF    1304      11296     1.0.0 crc_gecko_os.py
...

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

> fop crc_gecko_os.py
[Opened: 0]
0
> read 0 1304
#!/usr/bin/env python
# -*- coding: utf8 -*-

import binascii


#------------------------------------------------------
def crc32(data):
    return binascii.crc32(data) & 0xffffffff

...
if __name__ == '__main__':
    main()

[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. You can use any files for this demonstration.

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 Versions

Gecko OS 4

Change Log

Modified	Changes
2019-01-01	Created