Gecko OS Commands

This page lists the Gecko OS Command API with a full description of how to use each command.

There are several interfaces for issuing commands. See Serial Interface, Issuing Commands and Streaming Data . For command format, see Serial Interface, Command Protocol .

Gecko OS Variables , which are used to configure Gecko OS, are accessed using the get and set commands.

The Gecko OS Command API is friendly for humans too. Use the following tips and you'll be an expert Gecko OS terminal jockey in no time flat!

Tip Description
Tab complete Type part of a command or variable name then hit the tab key. The command completes or partially completes, just like a terminal in the linux or DOS world.
History Up to 5 commands of history are available. Press the up-arrow key to access recently entered commands.
Edit The left-arrow , home , end and backspace keys may be used to edit or navigate commands already present on the command line.

Shortcuts

A shortcut is assigned to each command. Common sense dictates the rules for shortcuts. Commands that are already short do not need a shortcut other than their name, shortcuts for longer commands sometimes take the first three letters of the command name, and other times take the first letter of the name plus several other letters contained in the name. Shortcuts are no longer than six characters and are easy to guess, the ultimate reference however is command help and the documentation on this page.

Documentation Format

Many of the Gecko OS responses shown in the examples on this page were captured with system.print_level = all, and system.cmd.header_enabled = true. These settings are provided to make it easy for a host microcontroller to parse responses by examining response headers . Information about machine parsing is available in Serial Interface, MCU Config .

Documentation for each command is provided in the format shown below.

command

Abbreviation

cmd

Description

A description of how to use the command with, together with notes about available options and arguments.

Syntax

Formal command syntax with a listing of all available options and arguments.

Example

One or more examples demonstrating how the command is used.

Commands by Group

Description of Commands

dms_activate

Abbreviation

dmsa

Description

Activates the current device to the specified product.

This command requires the device to have access to the Internet, so network credentials wlan.ssid and wlan.passkey must be set. See Getting Started .

Supported Platforms

Syntax

dms_activate <product_code>

Example 

> dms_activate MY_PRODUCTCODE
Success

dms_claim

Abbreviation

dmsc

Description

Claims the current device, associating it with your DMS account.

This command requires the device to have access to the Internet, so network credentials wlan.ssid and wlan.passkey must be set. See Getting Started .

Syntax

dms_claim <dms_username> <dms_password>

Example 

> dms_claim my_dms_username my_dms_pw
Success

exit

Abbreviation

exit

Description

Exits command mode immediately and returns to stream mode. Only valid when stream mode is operational.

Syntax

> exit

Supported Platforms

Example 

> exit
Command Mode Stop

factory_reset

Abbreviation

fac

Description

Reset the application configuration to factory default values. The WLAN MAC address wlan.mac must be provided as an argument to avoid accidental factory reset.

Note : The application may also be factory reset by asserting GPIO0 for 10 seconds through a module reset as described in Update and Recovery, Factory Reset .

Syntax

> factory_reset <MAC address>

Properties

Supported Platforms

Example 

> get wl m
R000019
4C:55:CC:10:03:44
> fac 4C:55:CC:10:03:44
Success

faults_print

Abbreviation

faup

Description

List system faults. After 8 faults, the system enters Safe Mode. See Update and Recovery, Safe Mode .

Syntax

> faults_print

Properties

Supported Platforms

Example 

> faup
Success

faults_reset

Abbreviation

faur

Description

Reset system fault counter. See Update and Recovery, Safe Mode .

Syntax

> faults_reset

Properties

Supported Platforms

Example 

> faur
Success

file_copy

Abbreviation

fcp

Description

Copy a file.

The new file name must be different to the old file name, and there must be enough space for the new file to be created.

Syntax

> file_copy <old_filename> <new_filename> where

Supported Platforms

Example 

> file_copy myfile.txt mynewfile.txt
R000009
Success

file_create

Abbreviation

fcr

Description

Create a new file <size> bytes in length. After the command is issued, the ensuing <size> number of bytes is written to the file system.

Files can be written in chunks smaller than the specified length, using the -o option.

Additional options include a version, file type and CRC, or checksum .

See File System, Writing Files .

Syntax

> file_create [-o] <filename> <size> [<version> [<type> [<crc>]]]

Option Description
-o Optional. Leave file open for writing.
Default: Off
If the -o option is not specified, then all the file data must come immediately after the command.
If the -o option is specified, the file can be written in chunks. A stream handle is returned after the command. The write command is used to write data to the file. The stream closes automatically after the specified <size> bytes of data is written. The file is not considered 'valid' until it automatically closes.
If the module is rebooted or the close command is issued before all data is written, the file data is lost. It is not possible to restart writing the file after the stream is manually closed.
See Networking and Security, Network Connections and Streams .
filename Name of file to be written.
size Length of file in bytes. After the command is issued, write the file content to the serial interface.
version Specify version number. Default 1.0.0
type The file type, in hex format 1 . See File System, File Types
Default: FE ( MISC_FIX_LEN )
crc optional, CRC16-CCITT checksum of the file data, in hex format 1 . See File System, Checksum

1 : hex format: upper or lower case, with or without leading 0x , e.g. 0xFE , fe , 0xe1c8

Supported Platforms

Examples

Create a file with no special options

In the example below, the file content , Hello World! is 12 bytes in length and is entered or sent by the user. 

> fcr myfile.txt 12
Hello World!
File created

Check result: 

> ls -l
!  # Type  Flags  Hnd    Size       Version  Filename
...
#  6 e-FE   0021  104      12       1.0.0.0  myfile.txt

The associated file handle (Hnd) may vary.

Flags 0021 : Valid User

Create an essential file that is not deleted during an OTA update 

> fcr -e myfile.txt 12
Hello World!
File created

Check result: 

> ls -l
!  # Type  Flags  Hnd    Size       Version  Filename
...
#  6 e-FE   0061  104      12       1.0.0.0  myfile.txt

Flags 0061 : Valid User Essential

Create a file with specified version and user type

(See File System, File Types ) 

> fcr myfile.txt 12 1.1.0.1 AB
Hello World!
File created

Check result: 

> ls -l
!  # Type  Flags  Hnd    Size       Version  Filename
...
#  6 e-AB   0021  104      12       1.1.0.1  myfile.txt

Create file for writing in chunks 

> file_create -o my_file.txt 100
3
> write 3 50
... <50 bytes of data> ...
> write 3 50
... <50 bytes of data> ...
File created

Check result: 

!  # Type  Flags  Hnd    Size       Version  Filename
...
#  6 e-FE   0021  107     100       1.0.0.0  my_file.txt

file_delete

Abbreviation

fde

Description

Delete a file from the file system.

Syntax

> file_delete <filename> | <memory>-<handle> where

Note: <memory>-<handle> overrides <filename> - for example, if there exist both a file in extended flash with file handle 234 , and a file named e-234 , then the command file_delete e-234 deletes the file with memory-handle e-234 , rather than the file named e-234 .

Properties

Supported Platforms

Example 

> fde myfile.txt
L000014
File deleted
R000009
Success

Example

To delete the file with handle 234 on e xtended flash: 

> file_delete e-234
L000014
File deleted
R000009
Success

file_open

Abbreviation

fop

Description

Open a file and return a file stream handle if successful. Once open, the file contents may be read with the stream_read command.

See Networking and Security, Network Connections and Streams .

Syntax

where:

Note: <memory>-<handle> overrides <filename> - for example, if there exist both a file in extended flash with file handle 234 , and a file named e-234 , then the command file_open e-234 opens the file with memory-handle e-234 , rather than the file named e-234 .

Supported Platforms

Example 

> fop myfile.txt
R000003
0

Example

To open the file with handle 234 on e xtended flash: 

> file_open e-234
R000003
0

file_stat

Abbreviation

fst

Description

Display file statistics for the specified file.

Statistics are displayed in a comma separated list, in the order:

size,CRC,long version,storage type,file type,flags,handle

# Stat Comment Reference
1 size file size, displayed in decimal format
2 CRC CRC is calculated from the unencrypted file data. Displayed in hex format, with no 0x prefix. File System, File Checksum
3 long version File System, File Version
4 storage type
  • i - MCU internal flash
  • e - extended flash
  • b - bulk serial flash
File System, Flash Storage
5 file type File System, File Types
6 flags File System, File Flags
7 handle Listed in the 'Hnd' column in ls -l output A unique ID assigned to each file

The ls -v (verbose file listing) command displays all of these properties except the CRC.

Syntax

> file_stat <filename>/<memory type>-<handle> where:

Supported Platforms

Example 

> file_stat geotrust_ca.pem
1236,6E5A,3.0.0.11,e,3,1,8
> file_stat e-8
1236,6E5A,3.0.0.11,e,3,1,8

force_safemode

Abbreviation

force_safemode

Description

Force the module into safe mode. This command is used by a host to test recovery procedures if the module enters safe mode. See Application Notes, Recovery from Safe Mode for further information.

This is a hidden command that does not appear in the list of commands returned by help commands .

Syntax

> force_safemode <module MAC address>

Supported Platforms

Example 

> force_safemode 4C:55:CC:10:10:98
Forcing safemode...
Rebooting
[Disassociated]
Gecko OS-2.1.0.9, Built:2015-01-25 15:58:14 for AMW004.3, Board:AMW004-E03.3

*** Max faults exceeded. Entering Safe Mode.
SAFEMODE>

format_flash

Abbreviation

format

Description

Format (i.e. erase all contents) of bulk or extended flash chip. If the extended flash is specified, ALL files BUT the wifi_fw.bin file are erased.

For details on enabling and using bulk flash, see File System, Flash Storage .

Syntax

> format_flash <bulk/extended> <module MAC address>

Properties

Supported Platforms

Example 

> format bulk 4C:55:CC:10:10:98
Formatting flash...

get

Abbreviation

get

Description

Get the value of a Gecko OS variable or group of variables.

Syntax

> get <[variable name] / [variable group]> [options]

Properties

Supported Platforms

Example 1 

> get time.rtc utc
R000029
2014-03-23T23:54:33.021464Z

Example 2 

> get bus
R000166
bus.data_bus: uart0
bus.log_bus: uart0
bus.mode: command
bus.stream.cmd_gpio: 0
bus.stream.cmd_seq: $$$
bus.stream.flush_count: 1500
bus.stream.flush_time: 20

gpio_dir

Abbreviation

gdi

Description

Set the direction of a general purpose I/O pin. To deregister the GPIO, set the direction to either -1 or none .

Note : This is a run-time only setting: the value is not saved with the save command. To set the direction of a GPIO after a reboot, set the variable gpio_init . See Peripherals, Setting GPIO Function .

Syntax

> gpio_dir <GPIO#> <direction name/enum> [0/1]

where:

For each I/O type there is a name and ab enum values. The <direction name/enum> argument can specify either a name or an enum value:

I/O Type Description Direction Name Enum Value
Input, pull-up ipu 0
Input, pull-down ipd 1
Input, high-impedance in 2
Output, push-pull out 3
Output, open-drain no-pull ood 4
Output, open-drain pull-up oodpu 5
Deregister the GPIO none -1

Supported Platforms

Example 

> gdi 12 in
R000008
Set OK

gpio_get

Abbreviation

gge

Description

Get the current value of a general purpose I/O pin.

Syntax

> gpio_get <GPIO#>

Supported Platforms

Example 

> gge 12
R000003
0

gpio_set

Abbreviation

gse

Description

Immediately set the value of a general purpose I/O pin. When setting a GPIO, the GPIO direction must be also correctly set using the command gpio_dir or the command will fail.

Syntax

> gpio_set <GPIO#> <value>

Supported Platforms

Example 

> gse 12 1
L000032
GPIO not configured for output
R100016
Command failed

gpios_get

Abbreviation

gges

Description

Get the current value of all general purpose I/O pins.

The value of standard GPIOs is returned as either 0 or 1 . Other GPIO types not configured for GPIO access (such as UART pins or system indicators) are returned as X . GPIO values are in GPIO number order, increasing from left to right, with value for GPIO0 at left.

Syntax

> gpios_get

Supported Platforms

Example 

> gpios_get
R000031
0XX00X0000000XX10XXX000000000

help

Abbreviation

help, ?

Description

Return a list of commands or variables; or return help for a specific command or variable.

Syntax

> help [all/commands/variables/<command>/<variable>]

Supported Platforms

Example 

> help
Usage   : help [all/commands/variables/<command>/<variable>]
Shortcut: help
Brief   : Return a list of commands or variables; or return
          help for a specific command, variable or group of
          variables.

http_add_header

Abbreviation

had

Description

Add a custom HTTP header to the HTTP stream specified by <handle> .

See Networking and Security, HTTP Client .

Syntax

> http_add_header <handle> <key> <value>

where:

Option Description
<handle> the stream handle supplied in response to the http_head or http_post commands (opened with -o option)
<key> header key
<value> header value

Options must be provided in the order shown.

Supported Platforms

Example 


> had 1 Content-type application/text
Success

http_download

Abbreviation

hdo

Description

Download one or more files from a remote HTTP server and save to the extended or bulk flash.

Timeout is determined by tcp.client.connect_timeout .

Note : The remote HTTP server must return the Content-length header in the HTTP response. The file system must have the size of the file before creating it.

See Networking and Security, HTTP Client .

Syntax

Download a Single File 

> http_download [-i <wlan/softap>] [-m <json_size>] [-d] [-[e]] [-c <CRC>] <url>
  [<flash_file_name> [<version> [<type> [<cert_filename>  ] ] ] ]

where parameters are as follows:

Option Description
-i Optional - Specify interface, MUST come first. If omitted uses network.default_interface .
-m <json_size> Optional - Download multiple files with a json specification of size <json_size> .
MUST come first if -i option not used.
No other parameters are valid with -m option.
See Downloading Multiple Files below for more information.
-d Don't delete duplicate files.
By default all duplicate file names are overwritten; with this option the command will fail on duplicates.
-e Optional flag - Indicates file is e ssential.
-c <CRC> Optional, CRC for file, in hex format*. On download, the file CRC is calculated and compared against this value. The file is not set 'valid' unless the CRCs match. See File System, File Checksum .
<url> Full path to a file on a http server. See below for more info about URL.
<flash_file_name> Optional - name to save file as. Use url filename if omitted
<version> Optional - default 1.0.0 if omitted, set to 0 to use default
<type> Optional - the type of file, default: miscellaneous text file, 0xFE . Type can be in hex or decimal format. See File System, File Types
<cert_filename> Optional - TLS certificate filename

Downloading Multiple Files > http_download -m <json_size>

Immediately after issuing this command, send <json size> bytes of a JSON formatted manifest file. An example of the manifest file is as follows: 

{
   "path"  : "https://myserver.com/path/to/my/files/",
   "cert"  : "mycert.pem",
   "files" : [
                {
                    "remote"  : "name_of_remote_file.html",
                    "local"   : "name_of_flash_file.html",
                    "version" : "1.0.0",
                    "type"    : 150,
                    "flags"   : "eu",
                    "crc"     : 23423
                },
                { ... }
              ]
}

Notes :

String Replacement

Gecko OS allows string replacement in the URL of the file for download, using a C-like or pythonesque syntax.

If the url contains %s , then the supplied filename is substituted for %s .

Example: hdo 192.168.1.110:50007?id=%s&action=download my_file.txt generates the URL: http://192.168.1.110:50007?id=my_file.txt&action=download and creates the file: my_file.txt in the module file system.

String replacement is also available in the manifest. For example: 

{
   "path" : "http://myserver.com?file=%s&user=name&pass=1234",
   "cert" : "mycert.pem",
   "files" : [
                {
                    "remote" : "my_file1.txt",
                },
                {
                    "remote" : "my_file2.txt",
                },
              ]
}

generates the following URLs for download: 

http://myserver.com?file=my_file1.txt&user=name&pass=1234
http://myserver.com?file=my_file2.txt&user=name&pass=1234

Supported Platforms

Example

Save page at example.com to file test.html: 

> hdo http://example.com test.html
Downloading: test.html to flash file system
Request GET /
Connecting (http): example.com:80
HTTP response: 200
Success
> ls -v
!  # Type  Flags  Hnd    Size    Version  Filename
...
#  8 e-FE   0021  108    1270       1.0.0.0  test.html
...

http_get

Abbreviation

hge

Description

Perform an HTTP(S) GET request and return a network stream handle if successful.

The protocol is assumed to be HTTP unless otherwise specified in the <url> parameter.

For a URL longer than 124 characters the command and url exceed the maximum command line length.

In this case use the --long_url option instead of including the URL as a command argument. Send the long URL, terminated by \r\n , immediately after the terminating \r\n of the command.

To allow custom headers, use the -o option.

Timeout is determined by tcp.client.connect_timeout .

See:

Syntax

> http_get [-i <wlan/softap>] [-g < GPIO#>] [-o] <url> [ca_cert_filename]

where:

Parameter Description
-i Network interface. Possible values are wlan or softap . Overrides default specified by network.default_interface
-g <GPIO#> specify a GPIO to indicate buffered data is waiting to be read. Set to -1 to disable
-o Open the HTTP request but do not send. This enables custom header(s) to be added to the request using the http_add_header command.
<url> URL to which request is sent. The URL prefix http:// is optional for standard HTTP transactions, however https:* must be added for secure HTTPS transactions.

Options must be provided in the order shown.

Supported Platforms

Example 

> hge https://www.google.com.au
[2014-04-02 | 13:27:20: Connecting: https://www.google.com.au]
Request GET /
Connecting (HTTP): www.google.com.au:443
Starting TLS
[2014-04-02 | 13:27:21: Connected: 0]
HTTP response: 200
Status: 200
0
> hge -o example.com:80
[2014-04-11 | 10:48:25: Opening: example.com:80]
Request GET /
Connecting (HTTP): example.com:80
[2014-04-11 | 10:48:25: Opened: 1]
1

> http_get --long_url
http://example.com/arbitrary_page?param1=abvcedfgssassssdfs&param2=asdfadsfasd&param3=11111111111111
[2016-05-10 | 02:26:50: Opening:http://example.com]
Request GET /arbitrary_page?param1=abvcedfgssassssdfs&param2=asdfadsfasd&param3=11111111111111
Connecting (http): example.com:80
[2016-05-10 | 02:26:50: Opened: 2]
Status: 200
2

http_head

Abbreviation

hhe

Description

Perform an HTTP(S) HEAD request and return a network stream handle if successful.

The protocol is assumed to be HTTP unless otherwise specified in the <url> parameter.

To allow custom headers, use the -o option.

Timeout is determined by tcp.client.connect_timeout .

See:

Syntax

> http_head [-i <wlan/softap>] -o <url> [ca_cert_filename] where:

Parameter Description
-i Network interface. Possible values are wlan or softap . Overrides default specified by network.default_interface
-o Open the HTTP request but do not send. This enables custom header(s) to be added to the request using the http_add_header command.
<url> URL to which request is sent. The URL prefix http:// is optional for standard HTTP transactions, however https:* must be added for secure HTTPS transactions.
[ca_cert_filename] CA certificate file. Overrides default specified by network.ca_cert

Options must be provided in the order shown.

Supported Platforms

Example 

> hhe example.com
[2014-04-02 | 13:32:28: Connecting: example.com]
Request HEAD /
Connecting (HTTP): example.com:80
[2014-04-02 | 13:32:29: Connected: 0]
HTTP response: 200
Status: 200
0

http_post

Abbreviation

hpo

Description

Perform an HTTP(S) POST request and return a network stream handle if successful.

The protocol is assumed to be HTTP unless otherwise specified in the <url> parameter.

To allow custom headers, use the -o option.

The HTTP Content-type must be provided.

Timeout is determined by tcp.client.connect_timeout .

See:

Syntax

> http_post [-i <wlan/softap>] [-g < GPIO#>] [-o] [-l <content-length>] <url> / --long_url<url> <content type> [ca_cert_filename] where:

Parameter Description
-i Network interface. Possible values are wlan or softap . Overrides default specified by network.default_interface
-o Open the HTTP request but do not send. This enables custom header(s) to be added to the request using the http_add_header command.
-l <content-length> This replaces the default HTTP header Transfer-Encoding : chunked with the header Content-Length: XXX where XXX is the specified content_length .
By default an HTTP request is sent with chunked encoding. If this option is specified then chunked encoding is not used. This may be necessary for HTTP servers that do not support chunked encoding. After issuing the command, the write command must be used to write <content-length> bytes of data.
Note : If the -l option is specified then the connection will be left open, thus the -o option is not needed.
<url> URL to which request is sent. The URL prefix http:// is optional for standard HTTP transactions, however https:* must be added for secure HTTPS transactions.
--long_url <url> allows an aribitrary length URL string, with a maximum length of 1023 characters. The URL string follows the http_post command on the next line
<content_type> The Content-type, (Internet media type, MIME type), of the content to be posted (e.g. application/json ).
[ca_cert_filename] CA certificate file. Overrides default specified by network.tls.ca_cert

Options must be provided in the order shown.

Supported Platforms

Example 

> hpo http://example.com application/json
[2014-04-02 | 13:35:19: Connecting: http://example.com]
Request POST /
Connecting (HTTP): example.com:80
[2014-04-02 | 13:35:20: Connected: 0]
HTTP response: 411
Status: 411
0
> hpo -o example.com:80 application/json
[2014-04-11 | 10:45:50: Opening: example.com:80]
Request POST /
Connecting (HTTP): example.com:80
[2014-04-11 | 10:45:50: Opened: 1]
1

http_read_status

Abbreviation

hre

Description

Read the HTTP response code returned by the last HTTP transaction on the stream specified by <handle> . If the HTTP request is pending and the transaction is incomplete, http_read_status sends the request and forces completion.

See Networking and Security, HTTP Client .

Syntax

> http_read_status <handle>

Supported Platforms

Example 

> hre 1
411

http_upload

Abbreviation

hup

Description

Upload file(s) from the device flash to a remote HTTP server using HTTP POST and file upload.

Timeout is determined by tcp.client.connect_timeout .

See:

Syntax

Upload a Single File 

> http_upload [-i <softap/wlan>] <url>  <local filename>
  [<remote filename> [<content type>]]

where:

Upload Multiple Files using JSON Manifest > http_upload [-i <softap/wlan>] -m <json size> where:

The manifest must be input directly after the command is issued. Manifest format: 

{
  "path" : "https://myserver.com/path/to/save/files",
  "cert" : "mycert.pem",
  "files" : [ {
    "local"  : "my_file_to_load.txt",
    "remote" : "file_name_on_server.txt",
    "name"   : "file",
    "type"   : "application/octet-stream",
    },
    { ... }
  ]
}

The manifest cannot contain javascript style commments.

If provided, the cert must be the name of an existing file in the device sflash.

The following optional properties are given the specified default values only if the properties are completely omitted from the manifest. Leaving them blank results in blank values, not default values.

Property Description Default
remote Name of file on remote system local value - the name of the file on the module file system.
name Appears in the form-data "name" field "file"
type Mime-type of file content "application/octet-stream"

For examples, see the http_upload application note .

Supported Platforms

Example 

> hup http://myserver.com/uploadpage ghm_capabilities.json testfile.json
Uploading: ghm_capabilities.json to server
Request POST /uploadpage
Connecting (http): myserver.com:80
HTTP response: 200
Success

The file is saved on the upload server at myserver.com:80 as testfile.json

ls

Abbreviation

ls

Description

Return a list of available files located in internal, extended and bulk flash.

Use the -v (or equivalent -l ) option for full details.

The -m , -b and -c support paging and limiting the output, for use when there are many files.

Syntax

> ls [-v/-l] [-m <i|e|b>] [-b <base sector>] [-c <max file count>] where:

Properties

Supported Platforms

Example

Long listing, showing Type, Flags, and Handles (Hnd) 

> ls -l
!  # Type  Flags  Hnd    Size       Version  Filename
#  0 e-FE   0041   54    7590       3.3.2.6  .recovery.html
#  1 e-FB   0001   85   44560       3.0.0.6  command_help.csv
#  2 e-FD   0001   62     135       3.0.0.6  default_setup.script
#  3 e-FE   0001   96    5430       3.3.2.6  favicon.ico.gz
#  4 e-03   0001   63    1216       3.0.0.6  geotrust_ca.pem
#  5 i-00   001B  170  327424       3.3.2.6  sys/kernel.bin
#  6 e-84   0005   52     820       3.2.0.0  sys/safemode.bin
#  7 i-81   001B    0  166096       3.3.2.6  sys/services.bin
#  8 e-01   0001    0  210412   5.26.230.12  sys/wifi_fw.bin
#  9 e-FE   0021   97     684       1.0.0.0  test1.html
# 10 e-FE   0001   53    1995       3.3.2.6  webapp/index.html
# 11 e-FE   0001   64    9530       3.3.2.6  webapp/unauthorized.html
# 12 e-FE   0001   56   22720       3.3.2.6  webapp/gecko-os.css.gz
# 13 e-FE   0001   67   72947       3.3.2.6  webapp/gecko-os.js.gz

Example

Listing showing extended memory files only, starting at file handle 56, count limited to 5 files: 

> ls -l -m e -b 56 -c 5
!  # Type  Flags  Hnd    Size       Version  Filename
#  0 e-FE   0001   56   22720       3.3.2.6  webapp/gecko-os.css.gz
#  1 e-FD   0001   62     135       3.0.0.6  default_setup.script
#  2 e-03   0001   63    1216       3.0.0.6  geotrust_ca.pem
#  3 e-FE   0001   64    9530       3.3.2.6  webapp/unauthorized.html
#  4 e-FE   0001   67   72947       3.3.2.6  webapp/gecko-os.js.gz
>

load

Abbreviation

load

Description

Load a configuration from a file previously saved by the save command.

Syntax

> load [-v] <config_file>

where:

Supported Platforms

Example 

> load config1.cfg
> Configuration successfully loaded

network_down

Abbreviation

ndo

Description

Bring down a network interface. If provided, the network interface overrides the default specified by the variable network.default_interface . All open streams on the interface will be closed.

Syntax

> network_down [-i <wlan/softap>]

Supported Platforms

Example 

> ndo
L000040
[2014-03-24 | 00:08:48: Disassociated]
R000009
Success

network_lookup

Abbreviation

nlo

Description

Perform a DNS lookup for a domain using the specified interface.

Syntax

> network_lookup <domain>

where:

Supported Platforms

Example 

> nlo google.com
R000016
216.58.220.142

network_restart

Abbreviation

nre

Description

Restart the network. This command is equivalent to issuing the network_down command followed by the network_up command.

Note : This command is blocking. It does not return until the network has been brought up (or has failed to be brought up).

Syntax

> network_restart [-i <softap/wlan>]

where the -i option specifies the network interface to be restarted.

Supported Platforms

Example

The response shown is an example. Response varies depending on the network settings, time and date and other factors. 

> nre
[2015-03-23 | 03:02:53: Disassociated]
[2015-03-23 | 03:02:53: Associating to Silabs]
Obtaining IPv4 address via DHCP
IPv4 address: 10.5.6.55
[2015-03-23 | 03:02:54: Associated]
Success

network_up

Abbreviation

nup

Description

Start the process to bring up a network interface.

The -s option prompts the user to select from a list of available APs and supply a passkey. If the -s option is used, Gecko OS automatically saves the credentials entered.

The -i option overrides the default network interface specified by network.default_interface .

NOTE! Every command that needs access to the network will automatically bring up the network interface. The network_up command is non-blocking (except when the -s option is used) and provided for convenience only.

Syntax

> network_up [<-s> / <-i [wlan]/[softap]>]

Supported Platforms

Example 

> network_up -s
Scanning for networks...
! 3 networks found
!  # Ch RSSI MAC (BSSID)       Network (SSID)
#  0  6  -27 84:1B:5E:29:9D:F7 Take the blue pill
#  1 11  -68 EC:1A:59:36:5B:6C button_xt
#  2 11  -70 2C:B0:5D:31:6F:6A button

Type the number # that matches your Network: 0
Type the password for your Network         : welcome-to-kansas
[Associating to Take the blue pill]
In progress
[Associated]

ota

Abbreviation

ota

Description

Initiate a secure over-the-air update . The secure OTA protocol uses industry standard TLS/HTTPS security with both client-side and server-side certificate verification.

For details of this process and associated requirements, see Update and Recovery, Secure OTA Update . This process requires you to claim the device using the dms_claim command.

As an additional measure of security, the server authenticates each device using the universally unique system.uuid embedded inside the hardware of each device.

Downloaded bundle files overwrite local files only if the bundle file has a later version. To ensure that bundle files overwrite local files regardless of version, force an update with the -f option.

Download a specific firmware bundle version with the -b option. Specifying a bundle forces an update. Bundle files overwrite local files regardless of version. See the note for the -b option in Syntax below.

To maintain a saved configuration through an OTA update, save the configuration as default_config.csv .

Note : OTA requires a memory-intensive TLS connection, and may fail if memory is low. See Networking and Security, Increasing Available Memory for TLS .

Note : If the ota command fails with the message: 

{"result":"fail","message":"device not claimed"}

then you need to claim the device before running the ota command. See Update and Recovery, the Silabs DMS Server .

Syntax

> ota [-q] [-f] [-b <full version>]

Properties

Supported Platforms

Example 

> ota
Connecting to network
Request POST /ota/05b300df003134534e394b8330393232323a3533/0
Connecting (HTTP): ota.zentri.com:443
Starting TLS
HTTP response: 200
Downloading new firmware...
Bundle version: Gecko OS-1.0.0.1, Built:2015-11-11 02:23:15 for AMW004.3
Downloading: command_help.csv-1.0.0.1 (25822, 0xFB, 0x1)
Downloading: default_setup.script-1.0.0.1 (189, 0xFD, 0x9)
Downloading: /setup/index.html-1.0.0.1 (9266, 0xFE, 0x1)
Downloading: /setup/images.png-1.0.0.1 (18067, 0xFE, 0x1)
Downloading: /sys/kernel.bin-1.0.0.1 (352804, 0x0, 0x801F)
Downloading: wifi_fw.bin-1.0.0.1 (191677, 0x1, 0x8009)
Downloading: /sys/services.bin-1.0.0.1 (83848, 0x80, 0x801F)
Downloading: geotrust_ca.pem-1.0.0.1 (1162, 0x3, 0x9)
Downloading: /favicon.ico.gz-1.0.0.1 (1853, 0xFE, 0x1)
Downloading: /setup/index.css.gz-1.0.0.1 (10539, 0xFE, 0x1)
Downloading: /setup/index.js.gz-1.0.0.1 (38771, 0xFE, 0x1)
Updating kernel to version: 1.0.0.1
Updating firmware files...
Updating file: wifi_fw.bin to version: 1.0.0.1
Updating file: /sys/services.bin to version: 1.0.0.1
Found new bootable app: /sys/services.bin (47), booting to it now!
OTA completed successfully
[Ready]

ping

Abbreviation

ping

Description

Send one or more ICMP pings to an IP address or the network gateway using the -g option. If provided, the network interface overrides the default specified by the variable network.default_interface . Options must be provided in the order shown.

Syntax

> ping [-i <wlan/softap>] <[IP address]/[-g]> [# retries]

Supported Platforms

Example 

> ping example.com 3
R000021
Ping reply in 183ms
R000021
Ping reply in 178ms
R000021
Ping reply in 177ms

reboot

Abbreviation

reboot

Description

Reboot the application.

Note : the response displayed on reboot depends on the system.cmd.format setting.

In human command mode, the response is similar to: 

Rebooting
[2015-08-05 | 00:38:19: Disassociated]
Gecko OS-2.3.1.2, Built:2015-07-21 09:16:43 for AMW004.3, Board:AMW004-E03.3
[Ready]

There may be other messages depending on system settings.

In machine command mode, the response to the reboot command, followed by the reboot and a CR-LF sequence, is similar to: 

R000079
Gecko OS-2.3.1.2, Built:2015-07-21 09:16:43 for AMW004.3, Board:AMW004-E03.3

Syntax

> reboot

Properties

Supported Platforms

Example 

> reboot
Rebooting
[2015-08-05 | 00:38:19: Disassociated]
Gecko OS-2.3.1.2, Built:2015-07-21 09:16:43 for AMW004.3, Board:AMW004-E03.3
[Ready]

save

Abbreviation

save

Description

Save all Gecko OS variables to non-volatile flash memory.

If a file name is supplied, the saved configuration can be restored with the load command.

Note : During the save operation, interrupts are disabled. In particular, the UART rx interrupt may not be serviced during save. To ensure the save operation is completed, wait for the save command response before issuing further commands via the UART.

Syntax

> save [<config_file>]

where parameters are as follows:

Option Description
<config_file> Optional. Name of the configuration file to be saved

Properties

Supported Platforms

Example 

> save
L000007
Saved
R000009
Success

Example 2 

save config1.cfg
R000009
Success
ls
!  #   Size   Version  Filename
...
#  5   3868     1.0.0  config1.cfg
...

set

Abbreviation

set

Description

Set the value of a Gecko OS variable.

Syntax

> set <variable> <args>

Note : The set command displays the Too many args error only if the number of space-separated arguments exceeds the maximum for all variables (5). However the number of arguments for the set command depends on the variable being set, and the form in which the variable is specified: abbreviations for variables vary from one to three arguments in length, and variable settings may require one or two arguments. If you specify too many arguments when setting a specific variable, surplus arguments are ignored. Refer to the variable documentation for the number of arguments for a specific variable.

Properties

Supported Platforms

Example 

> set wlan.ssid "My Home Network"
R000008
Set OK

setup

Abbreviation

setup

Description

The setup command simplifies the process of connecting a Gecko OS device to a Wi-Fi network.

It can be run automatically on boot or in response to asserting a GPIO. It also allows for setup from the Gecko OS terminal.

The setup command allows for setting up network credentials via a web browser. See Configuration and Setup, Setup with a Web Browser .

Syntax

> setup <web/status/stop>

Option Description
web When called with the web option, setup starts a Wi-Fi Access Point and a web server, the Wi-Fi AP credentials are configured using the variables setup.web.ssid and setup.web.passkey . Once connected to the Gecko OS Setup AP, a Wi-Fi client uses a web browser to setup Gecko OS variables and connect to your local Wi-Fi network. Web setup is non-blocking. The root of the web app is configured with the setup.web.root_filename variable.
status The status option allows an MCU host to determine whether setup is in-progress. Response is 1 if setup is in progress, otherwise 0 .
stop The stop option terminates any in-progress setup activity.

Supported Platforms

Example

Setup via Soft AP and Web App 

> setup web
In progress
Rebooting
SILABS-AMW007-2.0.0.4, 2018-08-18T05:32:24Z, Gecko-OS-2.0.0.4, Board:AMW007-E03.2

While In progress is displayed, connect a computer or mobile device to Soft AP, enter password (default password ), in web browser go to web setup DNS (default setup.com ), choose network from scan list and enter network password. See

sleep

Abbreviation

sleep

Description

Put the application into a low-power sleep state. The application sleeps until the wakeup timeout ( system.wakeup.timeout ) expires.

Syntax

> sleep

Supported Platforms

Example 

> set system.wakeup.timeout 10
Set OK
> sleep

... wait 10 seconds ...

SILABS-AMW007-2.0.0, Gecko_OS-2.0.0, AMW007-W0001

stream_close

Abbreviation

close

Description

Close an open network or file stream specified by [handle] , or alternatively close all open streams.

See Networking and Security, Network Connections and Streams .

Syntax

> stream_close <[handle]/[all]>

Supported Platforms

Example 

> close all
[2014-04-02 | 13:32:04: Disconnected: 0]
[2014-04-02 | 13:32:04: Disconnected: 1]
Success

stream_list

Abbreviation

list

Description

Return a list of open streams.

See Networking and Security, Network Connections and Streams .

Syntax

> stream_list

Supported Platforms

Example 

> list
!# Type  Info
#0 TCPC  google.com:80 (32288)
#1 HTTP  example.com:80 (37289)

stream_poll

Abbreviation

poll

Description

Poll a stream to check if data is available. Returns 0 if open with no data to read, 1 if data is available and 2 if the stream has been closed remotely. Use the all option to return the status of all open streams. To avoid polling, use a GPIO (may be assigned when the stream is opened) as an interrupt line to the host.

Determine the number of RX or TX bytes that can be buffered with the -r or -t arguments.

Syntax

> stream_poll [all] <handle> [-r]

where:

If -r argument is included in the command, the response format is as follows:

Poll specific connection 

> poll 0 -r
<status>,<Rx bytes available>

Poll all connections 

> poll all -r
<handle>,<status>,<Rx bytes available>|<handle>,<status>,<Rx bytes available>|...

where:

Supported Platforms

Example 

> poll 0
1
> read 0 100
hello!
> poll 0
0
> poll all
0,0|2,1|3,1

stream_read

Abbreviation

read

Description

Read up to <size> bytes from a network or file stream specified by <handle> . Returns data immediately (if available), does not wait to receive data.

To check for data, use the stream_poll command or the GPIO (assigned when the stream was opened) as an interrupt line to the host.

For file streams, the file is automatically closed if the end of file is reached.

Data Size Returned by stream_read

The stream_read command size parameter is limited to a maximum of 1000 bytes. If a larger size parameter is specified, stream_read returns only 1000 bytes.

See Networking and Security, Network Connections and Streams .

Syntax

> stream_read <handle> <size>

where

Supported Platforms

Example 

> read 0 200
R000202
<!doctype html><html itemscope="" itemtype="http://schema.org/WebPage"
 lang="en-AU"><head><meta content="/images/google_favicon_128.png"
itemprop="image"><title>Google</title><script>(function(){
wind

stream_write

Abbreviation

write

Description

Write data to a network or file stream. As described in Serial Interface, Command Protocol , the command must be terminated by \r\n .

If no option is specified, Gecko OS waits for <size> number of data bytes then immediately sends the data to the stream before returning a response.

If the -f (flush) option is specified, then the written data is buffered to the maximum packet size before being automatically flushed to the remote side. The -f option can be used for the following stream types:

For TCP and TLS streams, the maximum packet size is an MTU (1460 bytes).

See Networking and Security, Network Connections and Streams .

Syntax

> stream_write <handle> <size> [-f]

where:

Supported Platforms

Example 

> write 3 10
Success

tcp_client

Abbreviation

tcpc

Description

Open a TCP stream to a remote server at the specified network location.

Timeout is determined by tcp.client.connect_timeout .

See Networking and Security, Network Connections and Streams .

Note : You cannot use the tcp_client command to open a stream when tcp.client.auto_start is enabled. See the tcp.client.auto_start description and note.

Syntax

> tcp_client [-i <wlan/softap>] [-l <local port>] [-g GPIO#] <host> <port>

where:

Options must be provided in the order shown.

Supported Platforms

Example 

> tcpc google.com 80
L000028
Resolving host: google.com
L000052
[2014-03-24 | 01:07:12: Connecting: google.com:80]
L000036
Connecting (TCP): 74.125.237.96:80
L000039
[2014-03-24 | 01:07:12: Connected: 0]
R000003
0

tcp_server

Abbreviation

tcps

Description

Start/stop a TCP server specified by the variables tcp.server.* . If provided, the network interface and port override defaults specified by the variables network.default_interface and tcp.server.port respectively.

Syntax

> tcp_server [-i <wlan/softap>] <start/stop> [port]

where:

Options must be provided in the order shown.

See Networking and Security, Network Connections and Streams .

Supported Platforms

Example 

> tcps start
L000036
TCP server listening on port: 3000
R000009
Success

tls_client

Abbreviation

tlsc

Description

Open a secure TCP stream to a remote server with the specified properties.

Timeout is determined by tcp.client.connect_timeout .

See Networking and Security, Network Connections and Streams .

Syntax

> tls_client [-i <wlan/softap>] [-l <local_port>] <host> <port> [ca_cert_filename]

where:

Supported Platforms

Example 

> tlsc www.google.com 443
L000032
Resolving host: www.google.com
L000057
[2014-03-24 | 01:15:53: Connecting: www.google.com:443]
L000038
Connecting (TLS): 74.125.237.211:443
L000039
[2014-03-24 | 01:15:55: Connected: 1]
R000003
1

uart_update

Abbreviation

uartu

Description

Update the UART to the current UART variable settings without rebooting the device.

For this command to have an effect, the values of one or more of the uart variables must first be changed:

Syntax

> uart_update <uart#>

Supported Platforms

Example 

> uart_update 0
Success

udp_client

Abbreviation

udpc

Description

Open a UDP stream to a remote server at the network location <host>:<port> . If provided, the network interface overrides the default specified by the variable network.default_interface .

The option -g GPIO# specifies which GPIO indicates buffered data is waiting to be read. See also system.oob.gpio .

The [local port] may also be provided if desired. Options must be provided in the order shown.

See Networking and Security, Network Connections and Streams .

Syntax

> udp_client [-i wlan/softap] [-g GPIO#] <host> <remote port> [local port]

Supported Platforms

Example 

> udpc 192.168.45.67 3000
L000057
[2014-03-24 | 01:16:40: Connecting: 192.168.45.67:3000]
L000031
Resolving host: 192.168.45.67
L000032
Connecting: 192.168.45.67:3000
L000039
[2014-03-24 | 01:16:40: Connected: 2]
R000003
2

udp_server

Abbreviation

udps

Description

Start and stop the UDP server .

When the UDP server is started the read and write sub-commands are available.

When the UDP server is started, it is assigned a stream handle, indicated in the Gecko OS response by Opened: <stream> .

This allows for the equivalent stream read and write commands.

The read command is functionally the same as udps read .

The write command is functionally the same as udps write without the <address> and <port> options. The write command writes to the single UDP server stream, and consequently writes to all clients connected to the UDP server.

See:

Syntax

start, stop

> udp_server <start/stop> [port] Start and stop the UDP server. Port may be optionally specified. If no port is specified the default is udp.server.port .

read

> udp_server read [-q] [<byte_count>] where :

write

> udp_server write <byte_count> [<address> <port>] where :

Supported Platforms

Example 

> udp_server start 5000
[2014-11-28 | 07:14:49: Opened: 0]
0
UDP server listening on port: 5000
> read 0 100
Hello server
> udp_server write 12
Hello client
Success
> udp_server read -q 100
10.5.6.60,52333,Hello again server
> write 0 18
Hello again client
Success
> udps stop
[2014-11-28 | 07:15:31: Closed: 0]
UDP server stopped
Success

version

Abbreviation

ver

Description

Returns the Gecko OS firmware bundle version. This is a convenience command that is equivalent to reading the system.version variable.

Syntax

version

Properties

Supported Platforms

Example 

> ver
R000052
SILABS-AMW007-2.1.5, Gecko OS-2.1.5, AMW007-W00001

wlan_get_rssi

Abbreviation

rssi

Description

Get the received signal level (RSSI, in dBm) of the Access Point the wlan interface is connected to.

Syntax

> wlan_get_rssi

Supported Platforms

Example 

> rssi
R000005
-47

wlan_scan

Abbreviation

scan

Description

Initiate a Wi-Fi scan and return results; optionally specify a channel and AP SSID to scan for. For verbose scans, -v must be the first argument. Information returned by scan results is described in the following table.

Name Description
Ch The WLAN radio channel the AP is operating on
RSSI Signal strength of the AP in units of dBm
BSSID MAC address of the AP
Rate The maximum data rate supported by the AP in kilobits/s
e.g. 54000 = 54Mbit/s
Security Security type used by the AP e.g. Open, WPA2-AES, etc.
Mode AP mode. Inf = Infrastructure, Ad = Ad-hoc
Len Number of characters in the SSID
SSID AP name. APs with a hidden SSID are displayed as

Verbose scans return all columns of data. Non-verbose scans return only columns: # Ch RSSI MAC (BSSID) Network (SSID)

In Gecko OS, the Rate and Mode columns are not supported. These columns are filled with the values of 0 and - respectively.

Syntax

> wlan_scan [-v] [<channel-spec> [ssid]] where:

Supported Platforms

Example 

> scan -v
R000196
! 2 found
! # Ch RSSI BSSID              Rate Security Mode Len SSID
# 0 01  -24 EC:1A:59:36:5B:6C 144.4 Open      Inf  13 Ch1_Nearby_AP
# 1 06  -85 84:1B:5E:29:9D:F7 450.0 WPA2-AES   Ad  14 Ch6_Distant_AP

hboot

Abbreviation

hboot

Description

The host boot command downloads a firmware image from the Gecko OS device file system to the host MCU. If a firmware filename is not supplied, hboot downloads the default firmware image set in the hboot.filename variable.

The download process uses the EFM8 Factory Bootloader protocol described in AN945 EFM8 Factory Bootloader User Guide .

See also: hboot.filename variable.

Syntax

> hboot [<filename>]

where:

<filename> : Name of firmware image to download from the Gecko OS device file system to the host MCU. If a filename is not supplied, downloads the default firmware image set in the hboot.filename variable.

Supported Platforms

Example 

> hboot EFM8/UB1/SpaceInvaders.efm8
Success