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 Command Interface, Commands and Streaming . For command format, see Command 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

Command Description

adc_take_sample

Abbreviation

adc

Description

Take an analog sample of a pin using an onboard Analog-Digital Converter.

To set the ADC reference voltage, see system.adc.vref .

Syntax

> adc_take_sample <gpio#> [-v]|[-l]/[<LUT Filename.csv>]

Note :

The ADC value can be read in three formats:

Platforms

Gecko OS Plugin

Example 

> adc 1
R000007
0x805
> adc 7 therm_celsius_lut.csv
R000009
23.4474
> adc 7 -l
R000009
27.5129
> adc 7
R000007
0x78F
> adc 7 -v
R000006
1559

dac_set_level

Abbreviation

dac

Description

Set the output level of a DAC. The DAC output voltage level is set to 3.3V x <level>/4096 .

Syntax

> dac_set_level <GPIO#> <level>

Platforms

Gecko OS Plugin

Example 

> dac 0 2048
Success

dfu_query

Abbreviation

dfuq

Description

This dfu_query command attempts to connect to the DMS to determine if a firmware update is available. This command returns the following comma separated response:

<status>,<message>

where:

If the -o output is provided, then the device does not connect to the DMS but instead prints the signed query request as the command response in base64 format. By default tue response is in base64 format. Use the -m option to print in msgpack format.

A host can forward this request to the DMS to determine if an update is available. Since the request is signed by the device, the host need not be logged into the DMS.

Syntax 

dfu_query [-o / m]

Platforms

Gecko OS Plugin

dfu_request

Abbreviation

dfur

Description

Generate a signed DFU request to send to the DMS.

After this command is invoked, the device returns a signed DFU request in base64 format. Use the -m option for msgpack format.

The generated request is signed by the device's private key. The DMS verifies the signature before returning a response.

The -l (list) argument, if supplied, helps the DMS determine which files to include in the DFU package. The DMS uses the list to determine which files are out-dated or missing on the Device. If the -l (list) argument is omitted, then the DMS includes all files in the DFU package, increasing the size of the DFU package binary. Using the -l argument may decrease the size of the returned package in the DMS response.

The generated request contains:

If -l list option provided, a list of all files on the device including:

Syntax 

dfu_request [-b <version>] [-i <interfaces>] [-l] [-m]

Options:

Platforms

Gecko OS Plugin

dfu_response

Abbreviation

dfur

Description

After this command is invoked, the device returns a signed DFU response in msgpack format.

The generated response contains:

The generated response is signed by the device's private key.

Syntax 

dfu_response [-m]

where:

Platforms

Gecko OS Plugin

dfu_update

Abbreviation

dfuu

Description

Invoke a Device Firmware Update on the device.

Syntax 

dfu_update [--exit] / [-m <method>] [-i <interface>] [-b <version>] [-r <port>] [--factory] [--multi]

where:

This command immediately returns a response. If it returns success then the DFU is active. If it returns failure then the DFU is not active.

Notes

The variable dfu.status may be used to get more information about the DFU result.

Platforms

Gecko OS Plugin

dms_activate

Abbreviation

dmsa

Description

Activates the current device to the specified product.

This is a production manufacturing procedure, available for production products only.

Syntax

dms_activate <product code> [ update /-o / -m]

where:

Platforms

Gecko OS Plugin

Example 

> dms_activate MY_PRODUCTCODE
Success

dms_claim

Abbreviation

dmsc

Description

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

To obtain a DMS token:

Syntax

Claim with dummy username and token

This option is provided for backward compatibility with the two argument requirement in previous versions.

dms_claim <dummy_username> <token>

Note that the <dummy_username> argument is a placeholder and does not need to be a valid username.

Example 

> dms_claim dummy_username Q3txWTdHYktvRVV5ekhwQkJHeXJGOFdW
Success

Claim with token only

dms_claim <token>

Platforms

Gecko OS Plugin

Example 

> dms_claim Q3txWTdHYktvRVV5ekhwQkJHeXJGOFdW
Success

dms_provision

Abbreviation

dmpr

Description

Provision device in DMS or indicate if device has already been provisioned.

Note : The device must have a provisioning token and possible UUID before issuing this command. See

Syntax

dms_provision

Platforms

Gecko OS Plugin

Example 

> dms_provision
Device already provisioned

dms_telemetry

Abbreviation

dmst

Description

Send device telemetry to the DMS immediately.

Syntax

> dms_telemetry

Platforms

Gecko OS Plugin

Example 

> dms_telemetry
OK

exit

Abbreviation

exit

Description

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

Syntax

> exit

Platforms

Gecko OS Plugin

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>

Platforms

Properties

Gecko OS Plugin

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

Platforms

Properties

Gecko OS Plugin

Example 

> faup
Success

faults_reset

Abbreviation

faur

Description

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

With the --coredumps option, you can also erase sys/core_dump.msgpack files.

Syntax

> faults_reset [--coredumps]

where:

Platforms

Properties

Gecko OS Plugin

Example 

> faur
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 .

Gecko OS writes the file to extended flash or bulk flash, depending on the location option: -l extended/bulk . If neither option is specified, Gecko OS writes to extended flash.

Note : File count and file size may be limited. See File System Limits .

See File System, Writing Files .

Note : to guarantee that no characters are dropped when using the local serial interface, uart.flow must be turned on . This applies at any baud rate.

Note : when the file_create command creates a file, it may take some time to prepare the flash memory. If flow control is not in use, characters may be dropped when sending the file content data immediately after the command. To avoid this problem, we recommend using flow control. Alternatively, pause before sending data:

Syntax

> file_create <filename> <size> [-e][-d][-u][-p][-o] [-v <version>] [-t <type>] [-m <permissions-bitmask>] [-l <extended/bulk>] [-c <checksum>]

where:

Option Description
<filename> name of file to be created. Mandatory first argument. Length range: 1 to 95
<size> Size in bytes of file to be created. Mandatory second argument.
-e e ssential 1 : Specifies that the file is e ssential and must not be deleted during an OTA. Default: Off
Note : Files are deleted during OTA only if space is required. OTA may fail if files marked essential leave insufficient space.
-d d evice key 1 : The file is to be encrypted with the internally generated device key. Note that because the device key is inaccessible, only the device Gecko OS can read a file encrypted with the -d flag.
-u u ser key encrypt 1 : The file is to be encrypted with the system.security_key , also known as the user key. The system.security_key must be set to a 128 bit AES key prior to using the file_create command with this option.
-p File is p re-encrypted using the system.security_key ( user key).
-o o pen: 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 .
-v <version> v ersion: specify file version string. If omitted, file version defaults to 1.0.0 .
-t <type> t ype: specify file type as integer or hex string 2 . If type is omitted, default type is 0x44 = GENERAL .
-m <permissions> File permissions bit m ask, specified as hex string 2 . If omitted, file permissions default to 0xFFFF = ALL
-l <location> l ocation: File flash memory location. Options are extended/bulk . Default: extended .
-c <checksum> c rc: CRC32 checksum of the file data, in hex format 2 . See File System, Checksum

1 : Some options can be combined with a single dash, e.g. -de , -eu , or supplied as separate options. Order is not important. Incompatible options such as -d and -u cannot be combined.

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

Platforms

Gecko OS Plugin

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
!  # L Hnd Type Flag O Perm    Size    Created   Version Filename
...
#  3 e  81   44 0001 u FFFF      12  946611037     1.0.0 myfile.txt

The associated file handle (Hnd) may vary.

Flags 0001 : Valid (bit1)

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

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

Check result: 

> ls -l
!  # L Hnd Type Flag O Perm    Size    Created   Version Filename
...
#  3 e  7F   44 0201 u FFFF      12  946609785     1.0.0 myfile.txt

Flags 0201 : Essential (bit 9) Valid (bit 0).

Create a file and encrypt it with the device key 

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

Check result: 


> ls -l
!  # L Hnd Type Flag O Perm    Size    Created   Version Filename
...
#  3 e  82   44 0101 d FFFF      44  946612165     1.0.0 myfile.txt

Flags 0101 : Encrypted (bit 8) Valid (bit 0).

Note that you cannot read this file.

Create a file with specified version and user type

(See File System, File Types ) 

> fcr myfile.txt 12 -v 1.1.0 -t 0xAB
Hello World!
File created

Check result: 

> ls -l
!  # L Hnd Type Flag O Perm    Size    Created   Version Filename
...
#  3 e  7E   AB 0001 u FFFF      12  946609639     1.1.0 myfile.txt

Create file for writing in chunks 

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

Check result: 

!  # L Hnd Type Flag O Perm    Size    Created   Version Filename
...
#  3 e  7D   44 0001 u FFFF     100  946609495     1.0.0 myfile.txt

Encryption example

Create a file encrypted on creation with system.security_key , which must be pre-set with a 128 bit AES user key.

In ls output, note file length is 32 bytes more than data content, and the Encrypted flag is set.

This example also demonstrates opening the file with the security key. See file_open .

First set the system.security_key . 

> set system.security_key f12ca2a9dae8bdb48d959e65ec54f6da
User key set
Set OK

Now create the file with the -u option: 

> file_create my_file.txt 100 -u
Here is a test file encrypted with system.security_key
using the file_create -u option. Note flags
File created

Check the file was created: 

> ls -l
!  # L Hnd Type Flag O Perm    Size    Created   Version Filename
...
#  3 e  87   44 0101 u FFFF     132  946613240     1.0.0 my_file_u.txt

Flags 0101 : Encrypted (bit 8) Valid (bit 0).

If you open the file without the key, it is not decrypted. 

file_open my_file_u.txt
[Opened: 0]
0
> read 0 100
J*&^k_WRA7WFJ+SG...

If you supply the correct key the file is correctly decrypted. 

> file_open my_file.txt -k f12ca2a9dae8bdb48d959e65ec54f6da
[Opened: 1]
1
> read 1 100
Here is a test file encrypted with system.security_key
using the file_create -u option. Note flags
[Closed: 1]

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 .

Platforms

Properties

Gecko OS Plugin

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

> file_open <filename> | <memory>-<handle> [-k <security key>]

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 .

Platforms

Gecko OS Plugin

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,location,storage type,file type,flags,handle,hash,owner,perm,time

# Property 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 ver Long File Version File System, File Version
4 loc Location character:
  • i - MCU internal flash
  • e - extended flash
  • b - bulk serial flash
File System, Flash Storage
5 type 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
8 hash File DFU hash as a hex string
9 owner File owner: user / device
10 perm File permissions as hex string
11 time File timestamp in seconds

The ls -v (verbose file listing) command displays all of these properties except the CRC, the DFU hash, and the Owner: 

> ls -v
!  # L Hnd Type Flag O Perm    Size    Created   Version Filename
#  0 e  4E   45 0401 d FFFF     297 1544161842     4.0.6 favicon.ico.gz
#  1 e  61   41 0401 d FFFF    1354 1544161842     4.0.6 globalsign_ca.pem

Syntax

> file_stat <filename>/<memory type>-<handle> [<comma-separated properties>]

where:

Platforms

Gecko OS Plugin

Examples

Display all file properties 

> file_stat globalsign_ca.pem
size:1354,crc:0x00477A85,ver:4.0.6,loc:e,type:0x41,flags:0x0401,handle:0x61,hash:17D952AC38947603,owner:0x02,perm:0xFFFF,time:1544161842
1236,6E5A,3.0.0.11,e,3,1,8

Display specified file properties 

> file_stat globalsign_ca.pem crc,size,ver,type
crc:0x00477A85,size:1354,ver:4.0.6,type:0x41

Display specified file properties by memory type-handle 

> file_stat e-61 crc,size,ver,type
crc:0x00477A85,size:1354,ver:4.0.6,type:0x41

force_safemode

Abbreviation

fsafemode

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> [<safemode type>]

where <safemode type> is one of the following:

The safemode type> option applies for App builds only.

Platforms

Gecko OS Plugin

Example 

> force_safemode 4C:55:CC:10:10:98
Forcing safemode...
Rebooting
[Disassociated]
SILABS-WGM160P-4.0.0, Gecko_OS-STANDARD-4.0.12-1198, WGM160P

*** 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 . See also the system.bflash.cs_gpio variable.

Syntax

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

Platforms

Properties

Gecko OS Plugin

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.

Variables are grouped in categories, and in some cases sub-categories, e.g. http.server , system , or system.oob . To get a group of variables, type get followed by the group or the group abbreviation. Gecko OS lists all the variables in that group with their values.

Syntax

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

Platforms

Properties

Gecko OS Plugin

Example

Get value for a single variable. 

> get time.rtc utc
R000029
2019-01-23T23:54:33.021464Z

Example

Get values for a variable group. 

> 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

Example

Get values for a variable group using abbreviation. 

> get ua
uart.baud: uart0:115200,uart1:115200
uart.data: uart0:8,uart1:8
uart.flow: uart0:off,uart1:off
uart.parity: uart0:none,uart1:none
uart.stop: uart0:1,uart1:1

Example

Get values for a subgroup within a group. 

> get system.oob
system.oob.event_mask: 0x0000
system.oob.gpio: -1
system.oob.gpio_level: 1
system.oob.rising_edge_mask: 0x0000
system.oob.status: 0x0000

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

Platforms

Gecko OS Plugin

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#>

Platforms

Gecko OS Plugin

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>

Platforms

Gecko OS Plugin

Example 

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

gpios_dir

Abbreviation

gdis

Description

Set the direction of all general purpose I/O pins. A direction for all GPIOs must be provided with the direction of GPIO 0 in the first (left-most) position in the array.

Note : This is a run-time only setting: the direction values are 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

> gpios_dir <direction array>

where a <direction array> element may be one of the values in the following table.

Enumerator I/O Type Description
0 Input, with pull-up
1 Input, pull-down
2 Input, high-impedance
3 Output, push-pull
4 Output, open-drain no-pull
5 Output, open-drain pull-up
6 Deregister the GPIO

Platforms

Gecko OS Plugin

Example 

> gdis 10011011333530011000222226622
R000008
Set OK

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

Platforms

Gecko OS Plugin

Example 

> gpios_get
R000031
0XX00X0000000XX10XXX000000000

gpios_set

Abbreviation

gses

Description

Immediately set the value of all general purpose I/O pins. When setting a GPIO, the GPIO direction must be also correctly set using gpio_dir ] or gpios_dir or the command will fail. The value for all GPIOs must be provided, with the value of GPIO 0 in the first (left-most) position in the array.

Syntax

> gpios_set <GPIO value array>

Platforms

Gecko OS Plugin

Example

The examples shown below are for the WGM160P module which has 29 GPIOs, the first example command failed because the GPIO value array contained less than 29 values. 

> gses 100110100101101001001011
L000022
Must supply 29 gpios
R700018
Invalid argument

> gses 10011011001011110100100101111
R000008
Set OK

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>]

Platforms

Gecko OS Plugin

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 .

This command requires an open stream, resulting from issuing either http_get , http_head or http_post with the -o option.

Syntax

> http_add_header <handle> <key>[:extended] <value> where:

Option Description
<handle> the stream handle supplied in response to the http_get , http_head or http_post commands (opened with -o option)
<key> header key
<key:>extended If the <key> argument has :extended appended to it (no spaces) then the <value> argument is omitted and the following line after the command is the value of the HTTP header. The extended HTTP header value may be up to 1024 characters. The extended HTTP header value is terminated with the \r\n characters.
<value> header value (if <key>:extended not used).

Options must be provided in the order shown.

Platforms

Gecko OS Plugin

Example 

> http_get -o example.com
[2019-01-29 | 01:37:17: Connecting: http://example.com]
Request GET /
Connecting (HTTP): example.com:80
[2019-01-29 | 01:37:18: Connected: 0]
0
> had 0 Content-type application/text
Success
> hre 0
HTTP response: 200
200

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, TLS Errors for details of the error response to TLS failure.

See Networking and Security, HTTP Client .

Syntax

The general syntax of the http_download command is as follows: 

http_download ] [-i <interface>] [-x]
 ([-j <manifest-length>] / [-[e][d][u][p]]
 [-t <type>] [-m <permissions-bitmask>] [-l <extended/bulk>]
 [-c <checksum>] <url>/--long_url [<-n filename> [<-s cert_filename>])

where parameters are as follows:

Option Description
-i Optional - Specify interface, MUST come first. If omitted uses network.default_interface .
-j <json_size> Optional - Download multiple files with a j son format manifest of size <json_size> .
MUST come first if -i option not used.
No other parameters are valid with -j option.
See Downloading Multiple Files below for more information.
-e e ssential 1 : Specifies that the file is e ssential and must not be deleted during an OTA. Default: Off
Note : Files are deleted during OTA only if space is required. OTA may fail if files marked essential leave insufficient space.
-d d evice key 1 : The file is to be encrypted with the internally generated device key. Note that because the device key is inaccessible, only the device Gecko OS can read a file encrypted with the -d flag.
-u Encrypt file on creation with the system.security_key ( user key). Set the User Encrypted file flag.
-p Used in conjunction with -u : -up . File contents are pre-encrypted with the system.security_key ( user key). Set the Encrypted and User Encrypted file flags. The system.security_key must be set, or the command fails. See also File System, Encrypting Files for Use by Gecko OS .
-m <permissions> File permissions bit m ask, specified as hex string 2 . If omitted, file permissions default to 0xFFFF = ALL
-l <location> l ocation: File flash memory location. Options are extended/bulk . Default: extended .
-c <CRC> Optional, CRC checksum for file, in hex format 2 . 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 .
-t <type> t ype: specify file type as integer or hex string 2 . If type is omitted, default type is 0x44 = GENERAL .
<url> Full path to a file on an HTTP server. See below for more info about URL.
--long_url <url> allows an aribitrary length URL string, with a maximum length of 1023 characters. The URL string follows the command on the next line.
-n <flash_file_name> Optional - name for saved file. Use url filename if omitted.
-s <cert_filename> Optional - TLS certificate filename.

1 : Some options can be combined with a single dash, e.g. -de , -eu , or supplied as separate options. Order is not important. Incompatible options such as -d and -u cannot be combined.

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

Parameters other than the -j option are applicable when downloading a single file. When downloading multiple files, use a json format manifest, specifying the manifest size with the -j option. See Downloading Multiple Files below.

Download a Single File 

http_download [-i <interface>] [-x]  [-[e][d][u][p]]  [-t <type>] [-m <permissions-bitmask>] [-l <extended/bulk>]  [-c <checksum>] <url>/--long_url [<-n filename> [<-s cert_filename>]]

Downloading Multiple Files

> http_download -j <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,
                    "permissions"  : "0xff",
                    "location"     : "extended"
                },
                { ... }
              ]
}

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

Platforms

Gecko OS Plugin

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 Networking and Security, TLS Errors for details of the error response to TLS failure.

See:

Syntax

> http_get [-i <wlan/softap>] [-g < GPIO#>] [-o] <url> / --long_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.
--long_url If --long_url is given instead of <url> , then immediately following the http_get command should be the URL string, e.g
http_get --long_url\r\n
http://example.com?param1=abvcedfgssassssdfs&param2=asdfadsfasd&param3=11111111111111\r\n
[ca_cert_filename] CA certificate file. Overrides default specified by network.tls.ca_cert

Options must be provided in the order shown.

Platforms

Gecko OS Plugin

Example 

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

> http_get --long_url
http://example.com/arbitrary_page?param1=abvcedfgssassssdfs&param2=asdfadsfasd&param3=11111111111111
[2019-01-11 | 02:26:50: Opening:http://example.com]
Request GET /arbitrary_page?param1=abvcedfgssassssdfs&param2=asdfadsfasd&param3=11111111111111
Connecting (http): example.com:80
[2019-01-11 | 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 ,, softap or ethernet if supported. 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.tls.ca_cert

Options must be provided in the order shown.

Platforms

Gecko OS Plugin

Example 

> hhe example.com
[2019-01-02 | 13:32:28: Connecting: example.com]
Request HEAD /
Connecting (HTTP): example.com:80
[2019-01-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 <content type> [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.
-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.

Platforms

Gecko OS Plugin

Example 

> hpo http://example.com application/json
[2019-01-02 | 13:35:19: Connecting: http://example.com]
Request POST /
Connecting (HTTP): example.com:80
[2019-01-02 | 13:35:20: Connected: 0]
HTTP response: 411
Status: 411
0
> hpo -o example.com:80 application/json
[2019-01-11 | 10:45:50: Opening: example.com:80]
Request POST /
Connecting (HTTP): example.com:80
[2019-01-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>

Platforms

Gecko OS Plugin

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>]  [-k <security key>] <url>  <local filename>
  [<remote filename> [<content type> [<cert filename>]]]

where:

Upload Multiple Files using JSON Manifest

> http_upload [-i <softap/wlan>] -m <manifest_length>

where:

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

{
  "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 .

Platforms

Gecko OS Plugin

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

i2c_master_config

Abbreviation

i2cmc

Description

Configure an I2C slave peripheral such as an accelerometer, humidity sensor, light sensor, etc.

Notes :

See Networking and Security, Network Connections and Streams .

Syntax

> i2c_master_config <slave hex address> <clock rate> [<retries> [<config bitmask>]]

where:

<config bitmask> is a bitmask specifying the various flags for the I2C slave. The bits have the following meanings:

Bit # Name Description
0 Hexify When set, input data to the stream_write command is converted from a hex string to binary.
Output data from the stream_read command is converted from binary to a hex string.
Note : When this flag is set, up to <rx buffer>/2 -1 bytes may be read at a time

Platforms

Gecko OS Plugin

Example 

> i2c_master_config 0x19 standard 0 0x01
Success
> i2c_master_config 0x19
! Addr Clock  Flags Retries
# 0x19 100000 0x01  0

i2c_master_open

Abbreviation

i2cmo

Description

Open an I2C stream for read/write. Optionally specify the size of the read buffer.

The stream can then be used with the stream commands. Stream command behavior is modified for i2c as follows:

Stream Command Description Syntax
stream_read Additional optional arguments read <handle> <read size> [<flags> [<register address> [<slave address>]]]

For details, see I2C Read Command below
stream_write Additional optional arguments write <handle> <write size> [<flags> [<register address> [<slave address>]]]
For details, see I2C Write Command below
stream_close Closes the stream. stream_close <handle>
stream_list List streams - i2c streams are identified with type I2C stream_list

Notes :

Syntax

> i2c_master_open [<rx buffer>]

where:

I2C Write Command

Once an I2C stream is opened, the write command is used to write data to an I2C slave. The write command has additional arguments to specify the register address and slave address to write. write <handle> <write size> [<flags> [<register address> [<slave address>]]] where:

Notes :

I2C Read Command

Once an I2C stream is opened, the read command is used to read data from an I2C slave. The read command has additional arguments to specify the register address and slave address to read.

read <handle> <read size> [<flags> [<register address> [<slave address>]]] where:

Notes :

Platforms

Gecko OS Plugin

Example

The following shows how to read/write the LIS3DH Accelerometer via the I2C bus. The LIS3DH Accelerometer comes with the Seabass and Snapper evaluation boards).

Quick notes about the LIS3DH

Slave address = 0x19

If the MSb of a register address is set then the register address automatically increments for subsequent read/writes. This auto-increment is a feature of the LIS3DH, not of Gecko OS.

Gecko OS Command Log Description 

>i2c_master_config 0x19 standard 0 0x01
Success
> i2c_master_open
[Opened: 0]
0
> read 0 1 0 0x0F
33
> write 0 2 0x01 0xA0
aa
Success

> write 0 2 0x01
bb
Success
> write 0 2 0x01
cc
Success
> write 0 2
dd
Success
> read 0 4 0 0xA0
AABBCCDD



Configure I2C slave address: 0x19,
  'standard' clock, no retries, and hexify flag
Open an I2C stream


Read register 0x0F (aka Who Am I register)
  should return 0x33
Write CTRL_REG 1-4 (0x20 - 0x23),
  use LIS3DH's register auto-increment feature
  by setting MSb of register address.
  Use 'continued write' flag
Write CTRL_REG2 (0x21)
  (recall we're using 'continued write' flag
  and chip's register auto-increment feature)
Write CTRL_REG3 (0x22)


Write CTRL_REG4 (0x23). This is the last write
  so don't use the 'continued write' flag

Read back registers 0x20-0x23
  Set MSb of register address so the register address
  is automatically incremented

load

Abbreviation

load

Description

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

Syntax

> load [-v] <config_file>

where:

Platforms

Gecko OS Plugin

Example 

> load config1.cfg
> Configuration successfully loaded

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. See File System, Listing Files for an explanation of the file listing columns.

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:

Platforms

Properties

Gecko OS Plugin

Example

Long listing, showing additional columns including Type, Flags, and Handles (Hnd) 

ls -l
!  # L Hnd Type Flag O Perm    Size    Created   Version Filename
#  0 e  61   45 0401 d FFFF     743 1528250046     1.0.0 favicon.ico.gz
#  1 e  44   41 0401 d FFFF    1236 1528250046     1.0.0 geotrust_ca.pem
#  2 i   0    1 0607 d 0000  327424 1528250046     0.0.0 sys/kernel.bin
#  3 i  50    7 0607 d 0000  254768 1528250046     1.0.0 sys/plugins.bin
#  4 e   0    2 0605 d 0000  276552 1528250046     1.2.6 sys/wfm_wf200.sec
#  5 e  C4    4 0201 u FFFF    2048         28     1.0.0 sys/wl_table.bin
#  6 e  45   45 0401 d FFFF    2357 1528250046     1.0.0 webapp/index.html
#  7 e  5E   45 0401 d FFFF    9745 1528250046     1.0.0 webapp/unauthorized.html
#  8 e  46   45 0401 d FFFF   22720 1528250046     1.0.0 webapp/gecko_os.css.gz
#  9 e  4C   45 0401 d FFFF   72947 1528250046     1.0.0 webapp/gecko_os.js.gz

Example

Listing showing e xtended memory files only, starting at file handle 0x60 , count limited to 2 files: 

> ls -l -m e -b 0x60 -c 2
!  # L Hnd Type Flag O Perm    Size    Created   Version Filename
#  0 e  61   45 0401 d FFFF     743 1528250046     1.0.0 favicon.ico.gz
#  1 e  62   45 0601 d FFFF    8139 1528250046     1.0.0 .recovery.html

network_bridge

Abbreviation

nbr

Description

Start or stop the network bridge.

See:

Syntax

> network_bridge (start <iface1> <iface2>) | stop | restart

Platforms

Gecko OS Plugin

Example 

> network_bridge start ethernet softap


> network_bridge stop

> set network.bridge.interface_1 ethernet

> set network.bridge.interface_2 softap
> get network.bridge.auto_start
> set network.bridge.auto_start true

> get network.bridge.info

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>]

Platforms

Gecko OS Plugin

Example 

> ndo
L000040
[2019-01-24 | 00:08:48: Disassociated]
R000009
Success

network_flush

Abbreviation

nfl

Description

Flush the DNS cache and/or flush the cached DHCP IP and forcibly renew the DHCP lease. DHCP caching depends on wlan.dhcp.cache_enabled .

If no arguments are supplied, the DNS cache is flushed, and the cached DHCP IP is cleared and the DHCP lease is forcibly renewed.

If the dns argument is supplied only the DNS cache is cleared.

If the dhcp argument is supplied the DHCP IP cache is cleared, and the DHCP lease is forcibly renewed.

Note : This command currently supports only the WLAN interface.

Syntax

> network_flush [ dns / dhcp ]

where:

To flush both DNS and DHCP caches, issue the command with no arguments.

Platforms

Gecko OS Plugin

Example 

> nfl
R000009
Success

network_lookup

Abbreviation

nlo

Description

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

Syntax

> network_lookup [-i <wlan/eth/default>] <domain>

where:

Platforms

Gecko OS Plugin

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:

Platforms

Gecko OS Plugin

Example

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

> nre
[2019-01-01 | 03:02:53: Disassociated]
[2019-01-01 | 03:02:53: Associating to My_Network]
Obtaining IPv4 address via DHCP
IPv4 address: 10.5.6.55
[2019-01-01 | 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 automatically brings up the network interface.

The network_up command is non-blocking (except when the -s option is used) and provided for convenience only.

See:

Syntax

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

Platforms

Gecko OS Plugin

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]

network_verify

Abbreviation

nve

Description

Verify the module can connect to a Wi-Fi network with specific network credentials. This command provides a fast way test the network credentials entered by a user are valid when web setup with softAP is operational, see Configuration & Setup, Web Setup . At present, only the Wi-Fi credentials are verified. No attempt is made to verify whether the module can obtain an IP address using DHCP.

The network verify command can also be used to quickly test network credentials at any time, however if the module is already connected to a network on the wlan client interface, it will be automatically disconnected from that network first.

If the verification attempt is unsuccessful, the command responds with Timeout . Verification may be unsuccessful if either the credentials provided are incorrect, or the verification attempt takes longer than 1 second.

Notes

Syntax

> network_verify wifi <ssid> <bssid> <ap channel> [<security> <psk>] where:

Platforms

Gecko OS Plugin

Examples

Open Security 

> network_verify wifi mynetwork 4C55CC102F1A 1
Success

WEP40 Security 

> network_verify wifi mynetwork 4C55CC102F1A 1 1 1122334455
Success

WPA/WPA2 Security 

> network_verify wifi mynetwork 4C55CC102F1A 1 4 1205089613366e362586ee5f9ac8f485188fb0bdab30f2f1c23295eb863122de
Success

ping

Abbreviation

ping

Description

Send one or more ICMP pings to an IP address or to 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>]

Platforms

Gecko OS Plugin

Example 

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

pwm_update

Abbreviation

pwm

Description

Drive a GPIO with a pulse width modulated signal with duty_cycle in the range 0-100%. The PWM frequency has a module-dependent default and may be optionally set with the frequency option. Use the stop option to turn the PWM off.

See Peripherals, PWMs for frequency defaults and PWM groups for each module. GPIOs in the same PWM group cannot be used independently at the same time.

Syntax

> pwm <GPIO#> <duty_cycle>/stop [<frequency>]

where:

Platforms

Gecko OS Plugin

Example

Set GPIO 10 to 30% duty cycle: 

> pwm_update 10 30
R000009
Success

Blink LED wired to GPIO 21 at 50% duty cycle and frequency of 5Hz: 

> pwm 21 50 5

Stop LED blinking - value remains high: 

> pwm 21 stop

reboot

Abbreviation

reboot

Description

Reboot the application.

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

In human command API format, the response is similar to: 

Rebooting
[2019-01-05 | 00:38:19: Disassociated]
[Ready]
SILABS-WGM160P-4.0.0, Gecko_OS-STANDARD-4.0.12-1198, WGM160P

There may be other messages depending on system settings.

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

R000068
SILABS-WGM160P-4.0.0, Gecko_OS-STANDARD-4.0.12-1198, WGM160P

Syntax

> reboot

Platforms

Properties

Gecko OS Plugin

Example 

> reboot
Rebooting
[2019-01-05 | 00:38:19: Disassociated]
[Ready]
SILABS-WGM160P-4.0.0, Gecko_OS-STANDARD-4.0.12-1198, WGM160P

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.

Save as default_config.csv to create a default settings file. If a file of this name is found, Gecko OS loads the configuration in default_config.csv after a successful OTA or if the factory reset GPIO is asserted for more than 5 seconds but less than 10 seconds. See:

If system.security_key is set, the file is automatically encrypted with that key, and the User Encrypted file flag is set. When Gecko OS reads files for internal use (within the MCU only), it automatically decrypts files encrypted with the system.security_key .

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.

By default the setting file is encrypted. Use the -u option to save the file unencrypted.

Syntax

> save [<config_file>] [-u]

where parameters are as follows:

Option Description
<config_file> Optional. Name of the configuration file to be saved
-u Optional. If -u option specified, save file unencrypted

Platforms

Properties

Gecko OS Plugin

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.

Platforms

Properties

Gecko OS Plugin

Example 

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

setup_cmd

Abbreviation

setupc

Description

This command executes the specified setup script.

Syntax

setup_cmd <script path> [-v] [-e]

where:

Note : There is no default setup script.

Platforms

Gecko OS Plugin

Example 

> setup_cmd my_setup.script

setup_device

Abbreviation

setupd

Description

This command sets up the device for development. When this command completes, the device is fully setup in the DMS and has the latest firmware. It performs the following steps:

Syntax

setup_device <token> [-s] [-p <product-code>] [--noformat]

where:

Notes

Platforms

Gecko OS Plugin

Example 

> setup_device  SkFodmVjS0ZhSmViV2ltQ09YRE16bWt4

setup_web

Abbreviation

setupw

Description

This command invokes web setup mode. You can determine whether web_setup mode is active, start web_setup mode if not running, and stop web_setup mode if it is running.

Syntax

setup_web [status/stop]

where:

Platforms

Gecko OS Plugin

Example 

> setup_web

shutdown

Abbreviation

sdwn

Description

Shut system down to provide the greatest power savings. In system shutdown mode Gecko OS does not retain RAM and the kernel is fully shutdown.

This command requires at least one of the following:

If neither a timeout nor a GPIO is set, the command fails.

Note : The reset GPIO can wake the system without any additional setup.

See System Shutdown .

Arguments

shutdown

Platforms

Gecko OS Plugin

Example

Failure if pre conditions not met: 

> shutdown
ERROR: Must have enabled wakeup option(s) to shutdown
Command failed

If pre-conditions are met, Gecko OS shuts down immediately. 

> set system.shutdown.wakeup_timeout 8
Set OK
> shutdown
[1999-12-31 | 00:00:29: Shutdown]
... 8 seconds later ...
[1999-12-31 | 00:00:00: Ready]
>

smtp_send

Abbreviation

smtp

Description

Send email to a specified email address. See SMTP variables:

Syntax 

> smtp <to address> <subject> <content length>
[<content length> bytes of data ...]

where:

Immediately after issuing the command, <content length> characters of data should be sent. This is the body of the email.

Note that most SMTP servers require SSL/TLS encryption. Some servers, including gmail , use additional authentication methods like OAUTH by default. These additional authentication methods are not supported and may need to be disabled server-side.

Platforms

Gecko OS Plugin

Example 

> smtp_send first.last@youremail.com "World greetings" 5
Hello
[Associating to MY_NETWORK]
Security type from probe: WPA2-AES
Obtaining IPv4 address via DHCP
IPv4 address: 10.5.6.59
[Associated]
Success

softap_get_rssi

Abbreviation

srssi

Description

Get the received signal level (RSSI, in dBm) of a softAP client. The value is averaged to improve accuracy by setting the variable softap.rssi_average .

Syntax

> softap_get_rssi <client Mac>

where:

Platforms

Gecko OS Plugin

Example 

> srssi 11:22:33:44:55:66
R000005
-47

softap_mac_filter_add

Abbreviation

sma

Description

Add a MAC address to the soft AP MAC filter.

See:

Syntax

> softap_mac_filter_add <mac>

where:

Platforms

Gecko OS Plugin

Example 

> sma F8:16:54:35:0F:8E

softap_mac_filter_clear

Abbreviation

smc

Description

Clear all addresses from the soft AP MAC filter and disable the filter.

See:

Syntax

> softap_mac_filter_clear

Platforms

Gecko OS Plugin

Example 

> smc
R000000

softap_mac_filter_remove

Abbreviation

smr

Description

Remove a MAC address from the soft AP MAC filter.

See:

Syntax

> softap_mac_filter_remove <mac>

where:

Platforms

Gecko OS Plugin

Example 

> smr F8:16:54:35:0F:8E
R000000

spi_master_config

Abbreviation

spimc

Description

Configure a SPI slave peripheral such as an accelerometer, humidity sensor, light sensor, etc.

Note : This is a run-time only command. The settings are reset upon a reboot/power-cycle.

This should be issued before using the spi_master_open command to open a SPI stream.

To display the SPI configuration for a previously configured slave-select GPIO, issue the command with only the <slave-select GPIO#> argument.

Syntax

> spi_master_config <slave-select GPIO#> <config bitmask> [<clock rate>]

where:

<config bitmask> is a bitmask specifying the various flags for the SPI slave. The bits have the following meanings:

Bit # Name Description
0 Clock Edge
  • 0 : shift data out on falling-edge, shift data in on rising-edge
  • 1 : shift data out on rising-edge, shift data in on falling-edge
1 Clock Idle Level
  • 0 : clock idles low
  • 1 : clock idles high
2 Data Bit Order
  • 0 : data bytes are shifted out Least-Significant Bit first (LSb)
  • 1 : data is shifted out Most-Significant first (MSb)
3 Read-After-Write When this is specified, when data is written to the SPI slave, the simultaneously read data is buffered.
If this flag is not specified, when data is written, the read data is dropped.
4 Keep Slave Select Signal Asserted Sometimes it is necessary to keep the slave-select asserted between reads/writes.
If this flag is not specified, the slave-select is de-asserted after a read/write command.
When this flag is specified, after a slave-select is asserted for a read/write command, it remains asserted until one of the events occurs:
  • close command is issued for the stream
  • A different &lt;slave-select gpio #&gt; is specified as an argument to a read/write command
  • 0 bytes written to stream (i.e. write <handle> 0 )
5 Hexify When set, input data to the write command is converted from a hex string to binary.
Output data from the read command is converted from binary to a hex string.
NOTE: When this flag is set, up to <rx buffer>/2 -1 bytes may be read at a time

Platforms

Gecko OS Plugin

Example 

> spi_master_config 9 0C
Success
> spimc 9
!  # Flags Clock
#  9 0x0C  2000000
> get gp u
!  # Description
...
#  9 SPI0 CS
...

spi_master_open

Abbreviation

spimo

Description

Open a SPI master stream for read/write. Optionally specify an Rx buffer size.

The stream can then be used with the stream commands. Stream command behavior is modified for SPI as follows:

Stream Command Description Syntax
stream_read Additional optional argument specifies SPI slave select read <handle> <read size> [<slave-select gpio #>]
stream_write Additional optional argument specifies SPI slave select write <handle> <write size> [<slave-select gpio #>]
stream_poll Poll for SPI Rx data poll <handle>
returns 1 if <rx buffer> contains data, else 0 .
stream_close De-asserts the current slave-select and closes the stream. stream_close <handle>
stream_list List streams - SPI streams are identified with type SPI stream_list

Before using spi_master_open command, the <slave-select gpio #> must have been previously configured using the spi_master_config command. If no argument is supplied, the most recently specified <slave-select gpio #> is used.

Note : The caller must ensure that the contents of <rx buffer> is cleared before switching <slave-select gpio #> , as data is always read from <rx buffer> before reading from the SPI bus.

See Networking and Security, Network Connections and Streams .

Syntax

> spi_master_open [<rx buffer>]

where:

Platforms

Gecko OS Plugin

Example

Gecko OS Command Log Description 

> spi_master_open 256
0
> write 0 10 2
...
> read 0 10


open the SPI master stream with <rx buffer> size of 256 bytes
(return stream handle 0)
write 10 bytes to slave 2 as the slave select to SPI bus
(this simultaneously reads 10 bytes)
read 10 bytes from buffer

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

Platforms

Gecko OS Plugin

Example 

> close all
[2019-01-02 | 13:32:04: Disconnected: 0]
[2019-01-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

Platforms

Gecko OS Plugin

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.

If bus.command.write_check_enabled is set, when writing to a network stream, Gecko OS checks the size of the write (TX) buffer, to ensure that a full stream_write can be completed.

Syntax

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

where:

If -r and/or -t argument is included in the command, the response format is as follows:

Poll specific connection 

> poll 0 -r
<status>,<Rx bytes available>
> poll 0 -t
<status>,<Tx bytes available>
> poll 0 -rt
<status>,<Rx bytes available>,<Tx bytes available>

Poll all connections 

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

where:

Platforms

Gecko OS Plugin

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.

Read times out after the period specified in bus.command_read_timeout .

Data Size Returned by stream_read

For network streams, Gecko OS may buffer up to seven packets with each packet containing up to 1460 (MTU) data bytes. To avoid receiving data fragmented across packets, <size> should be set to 1460 bytes.

The number of bytes returned in the response to the stream_read command is determined as follows:

bytes_returned = MIN(Max packet size, <size arg>, poll -r)

i.e. the number of bytes returned is the minimum of:

See Networking and Security, Network Connections and Streams .

Syntax

> stream_read <handle> <size>

where

Platforms

Gecko OS Plugin

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).

For WebSocket client/server streams, data is not locally buffered, however 'continuation' frames are used. When the -f option is specified, each written data chunk is sent as a continuation frame. If -f is not specified, then the 'final frame' flag is set.

Use the -c option to enable automatic continuation frames for large writes to WebSocket client/server streams.

For WebSocket client/server streams, you can use the -p option to send a WebSocket ping frame as a keepalive.

Write times out after the period specified in bus.command.write_timeout .

See Networking and Security, Network Connections and Streams .

If bus.command.write_check_enabled is set, when writing to a network stream, Gecko OS checks the size of the write (TX) buffer, to ensure that a full stream_write can be completed.

Syntax

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

where:

Platforms

Gecko OS Plugin

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 .

Syntax

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

where:

Options must be provided in the order shown.

Platforms

Gecko OS Plugin

Example 

> tcpc google.com 80
L000028
Resolving host: google.com
L000052
[2019-01-24 | 01:07:12: Connecting: google.com:80]
L000036
Connecting (TCP): 74.125.237.96:80
L000039
[2019-01-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 <interface>] start/stop [<port>]

where:

Options must be provided in the order shown.

See Networking and Security, Network Connections and Streams .

Platforms

Gecko OS Plugin

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, TLS Errors for details of the error response to TLS failure.

See Networking and Security, Network Connections and Streams .

Syntax

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

where:

Platforms

Gecko OS Plugin

Example 

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

tls_server

Abbreviation

tlss

Description

Start/stop a TLS server on the specified port.

If starting the server and no port is specified, the default is the port specified by tcp_server_port .

The server certificates must be pre-configured. See Networking and Security, TLS Server .

See Networking and Security, Network Connections and Streams .

Syntax

tls_server <start/stop> [port]

Platforms

Gecko OS Plugin

Example 

> tlss start 5000

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#>

Platforms

Gecko OS Plugin

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>]

Platforms

Gecko OS Plugin

Example 

> udpc 192.168.45.67 3000
L000057
[2019-01-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
[2019-01-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

Start and stop the UDP server. Interface and port may be optionally specified. If no port is specified the default is udp.server.port .

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

where:

read

Read from the UDP client.

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

where :

write

Write to the UDP client.

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

where :

Platforms

Gecko OS Plugin

Example 

> udp_server start 5000
[2019-01-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
[2019-01-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

Platforms

Properties

Gecko OS Plugin

Example 

> ver
R000069
SILABS-WGM160P-4.0.0, Gecko_OS-STANDARD-4.0.12-1198, WGM160P

websocket_client

Abbreviation

webc

Description

Opens a client websocket stream to a remote server. Returns a stream handle which may then be used with the read / write / poll / close commands.

The Websocket client connection can be controlled by a GPIO. See ioconn.protocol web .

Data availability can be determined by an OOB GPIO event. See the system.oob.gpio event websocket.client.data_gpio .

See Networking and Security, Websocket Client .

Websocket Message Format

Websocket data passed between Gecko OS and remote server is sent in messages or frames. These messages start with a header. One element of the header is the message type. Gecko OS supports the 'text' and 'binary' message types. Note that Gecko OS treats all data as binary. The message type is only used by the remote side (for instance so a javascript library can convert the data to the correct format).

For more information see: https://developer.mozilla.org/en-US/docs/WebSockets/Writing_WebSocket_servers

Syntax

> websocket_client [-i <wlan/softap>] [-g <GPIO#> ] [-f <txt/bin>] <url> [<cert filename>]

where:

Platforms

Gecko OS Plugin

Example 

> websocket_client ws://mywsserver.com
0

wlan_get_rssi

Abbreviation

rssi

Description

Get the received signal level (RSSI, in dBm) of the Access Point the wlan interface is connected to. The value is averaged to improve accuracy by setting the variable wlan.rssi_average .

Syntax

> wlan_get_rssi

Platforms

Gecko OS Plugin

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. An asterisk indicates enterprise authentication.
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)

Note : In order to adhere to regulatory restrictions, channels 1 - 11 are actively scanned and 12 - 13 are passively scanned.

Syntax

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

where:

Platforms

Gecko OS Plugin

Example

Verbose scan: 

> 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

Scan for specified channels on a specified SSID: 

scan 1,2,5,6,10,11 MySSID
! 2 networks found
!  # Ch RSSI MAC (BSSID)       Network (SSID)
#  0  6  -42 1C:DE:A7:63:20:49 MySSID
#  1 11  -55 7C:69:F6:37:8F:F9 MySSID