Gecko OS provides a flexible command interface that provides access to the Command API via serial and wireless/wired network interfaces.
The serial interface supports various serial protocols and modes, and is easy to use for both humans and machines alike.
Gecko OS currently supports a UART serial interface. A SPI-serial interface is planned for an upcoming release.
A single or dual UART is available for use by the host MCU. If a host can support two UARTs, one UART may be used for control and data communication, and the other used for debug logging. If a single UART is available, control, data and debug logs (if enabled) are interleaved.
SPI provides a higher speed communications interface for higher bandwidth applications such as audio and video.
Commands and Streaming
Applications can use the Gecko OS Command API to send commands via a serial interface such as a UART, or a wired or wireless network interface such as Wi-Fi, Ethernet and others.
First the Gecko OS device is configured to connect to the network and to other hosts on the network. Then the Gecko OS device allows the local host to communicate with other hosts by exchanging data.
By default, the serial bus mode is set up to issue commands via the serial bus. This serial bus mode is called Command Mode.
To exchange data with other hosts, you can stream data transparently between a network interface and the local serial interface. This serial bus mode is called Stream Mode.
You can use Gecko OS commands with a range of interfaces and protocols, via the local serial bus or remotely via a network interface:
- The Gecko OS terminal console on the local serial interface.
The console UART is specified by bus.data_bus. This serial bus mode is called Command Mode.
- The auxiliary console on the local serial interface.
This is specified by bus.log_bus when system.cmd.aux_bus =
- Remote terminal via Telnet.
See Networking and Security, Remote Terminal.
- HTTP RESTful API.
See Networking and Security, HTTP Server.
- WebSocket Server
See WebSocket Command Stream.
- DMS console
This requires dms.cmd.enabled to be TRUE.
Commands can also be executed in response to GPIO assertion or reboot. See:
To configure command mode and format, see Configuring Bus Command Mode.
The local serial interface and the remote terminal are mutually exclusive: connecting a remote terminal disables the local serial interface to the command parser. See Serial Bus Mode.
The local serial interface can either stream data, or send commands and receive responses. It cannot do both simultaneously. See Serial Bus Mode.
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.
The HTTP RESTful API interface is available at all times, if the HTTP server is running and the RESTful API is enabled.
Access to the Gecko OS command parser is determined by:
- serial bus mode
- remote terminal status
- HTTP RESTful server status
Executing a Command on GPIO Assertion or Reboot - Setup GPIO
The Setup GPIO feature allows a command to be executed on reboot, GPIO assertion, or a combination of reboot and GPIO assertion. There are three modes:
boot- execute on reboot
gpio- execute if the control GPIO is asserted for 3 seconds during reboot
any- execute at any time the control GPIO is asserted. The control GPIO cannot be used for another function.
To use the Setup GPIO feature, set the value of the following
For example, the following settings cause the configuration script
my_script.csv to be executed when GPIO 2 is asserted for 3 seconds during a reboot:
> set setup.gpio.cmd "setup cmd my_script.csv" Set OK > set setup.gpio.control_gpio 2 Set OK > set setup.gpio.level 1 Set OK > set setup.gpio.mode gpio Set OK save
Note: the setup.gpio.cmd variable takes a single argument. Enclose the argument in double quotes if it contains spaces, as shown above.
The following settings cause the ls command to execute automatically on reboot:
set setup.gpio.cmd "ls" Set OK > set setup.gpio.mode boot Set OK > save Saved Success > reboot Rebooting [Ready] SILABS-WGM160P-4.0.0, Gecko_OS-STANDARD-4.0.12-1198, WGM160P Executing setup.gpio.cmd: ls > ! # Size Version Filename ... setup.gpio.cmd success...
Executing a Command Automatically to Set Network Credentials - Setup Auto Cmd
To execute a command automatically on boot for setting up network credentials, set the value of setup.auto.cmd to the required command.
The command set in setup.auto.cmd executes only when wlan.ssid is not set. It is intended to execute commands to facilitate setting up the network credentials, wlan.ssid and wlan.passkey. To execute a command independently of the state of
wlan.passkey, use the Setup GPIO feature.
For example, to run the setup web command on reboot (only if wlan.ssid is not set):
> set setup.auto.cmd "setup web" Set OK > save Saved Success > reboot Rebooting [Ready] SILABS-WGM160P-4.0.0, Gecko_OS-STANDARD-4.0.12-1198, WGM160P Executing setup.auto.cmd: setup web > Finding best SoftAP channel ... IPv4 address: 10.10.10.1 HTTP and REST API server listening on port: 80 Web setup started with the SSID: Gecko OS-335 on channel 11 In progress
Note: the setup.auto.cmd variable takes a single argument. Enclose the argument in double quotes if it contains spaces, as shown above.
Executing a Script Containing Multiple Commands
You can create a configuration script with one or more commands, and execute it on reboot, or in response to asserting a GPIO.
See Configuration and Setup, Configuration Scripts.
Serial Bus Mode
Serial bus mode concerns the local UART serial interface.
A module running Gecko OS can operate in two distinct local serial bus modes, determined by the bus.mode variable:
- COMMAND mode — Gecko OS commands are issued via the serial UART interface. A module is in COMMAND mode if it booted with bus.mode set to
- STREAM mode — data is transferred directly between the serial UART interface and the Wi-Fi interface. A module is in STREAM mode if it booted with bus.mode set to
Gecko OS commands can also be issued via the local serial interface when in STREAM mode:
- by sending the breakout sequence specified by the bus.stream.cmd_seq
- by asserting the GPIO specified with the bus.stream.cmd_gpio function
The diagram below shows a schematic representation of access to the command parser via the serial interface and the Wi-Fi interface.
Note that this diagram illustrates access to the command parser only. Access via Gecko OS commands to Wi-Fi ports and other module features is unaffected by serial bus mode or remote terminal status.
Command configuration and protocols are as described in Command Mode and Command Protocol, whether commands are issued via the UART in COMMAND mode or COMMAND breakout, via the remote terminal, or via the HTTP RESTful API.
In STREAM mode, you can stream data between the UART and the Wi-Fi interface, as described in Stream Mode.
As the STREAM mode + Remote Terminal case in the above diagram suggests, you can stream data to a remote host, and at the same time issue commands to the Gecko OS device via the remote terminal or the HTTP Server RESTful API. A command issued to the command parser blocks commands from other interfaces until it is completed.
The state diagram below shows the transitions between serial bus modes.
Rebooting to COMMAND mode
To reboot to COMMAND mode, set the bus.mode variable to
command, save, and reboot:
set bus.mode command save reboot
COMMAND breakout from STREAM mode
To issue commands in STREAM mode, send the breakout character sequence specified by the bus.stream.cmd_seq. This is by default
Alternatively, set up a GPIO to enter command mode by enabling the bus.stream.cmd_gpio GPIO function.
On switching from STREAM mode to local COMMAND mode, Gecko OS responds with
Command Mode Start.
You can then issue any Gecko OS commands.
You can set bus.mode to
command and save, so that on the next reboot the Gecko OS device starts in local COMMAND mode.
When you have entered local COMMAND mode from STREAM mode via a breakout sequence or GPIO, you can return to STREAM mode by issuing the exit command.
Rebooting to STREAM mode
To switch to STREAM mode from command mode, set the bus.mode variable to
stream and reboot:
set bus.mode stream save reboot
Exit from COMMAND Breakout
When you have entered local COMMAND mode, or remote COMMAND mode, from STREAM mode via a breakout sequence or GPIO, you can return to STREAM mode by issuing the exit command. Gecko OS responds with
Command Mode Stop. For example:
|Sequences and Commands||Description|
Using the Remote Terminal
When the remote terminal is enabled and connected via telnet, the local command interface is disabled. However the UART can still stream to the Wi-Fi interface if the module is in STREAM mode. When a Gecko OS device is in COMMAND mode and a remote terminal is connected, disconnecting the remote terminal switches back to COMMAND mode. You can then issue commands via the local serial interface.
Enabling and Connecting the Remote Terminal
Enable the remote terminal with remote_terminal_enabled:
set remote_terminal.enabled 1 save reboot
Then connect a remote device via telnet to the Gecko OS device. The default port is
2000. The host IP or name depends on the Gecko OS configuration.
For details, see the Wi-Fi Remote Terminal application note.
Bus Command Mode
Bus command mode determines whether the serial interface is used for issuing commands (
command mode) or for streaming data (
stream mode). The bus command mode is determined by the variable bus.mode.
In command mode the command API interface can be configured for either a human-readable format or a machine-readable format, using the variable system.cmd.format.
Note: When controlling Gecko OS via an MCU, we suggest using machine format, described below.
Configuring Bus Command Mode
The default bus mode is
command. To switch to
command mode, set bus.mode to
command and reboot.
In command mode, the Gecko OS device effectively provides a slave interface to the host MCU. The host is the master and Gecko OS is the slave. The host initiates all transactions, which follow the sequence:
- host issues a command
- Gecko OS provides a response
Gecko OS commands are used by the host to send control information, read and write Gecko OS variables, and to send and receive data across network connections.
In the bus
command mode, the Command API interface can operate in two main formats:
The variable system.cmd.format is provided for convenience to make it easy to switch between Command API human format and machine format.
Setting system.cmd.format changes the value of several system variables to configure the desired command API format.
Human Command API Format
To configure the serial interface for human friendly operation, set system.cmd.format to
human, or set the following settings.
set system.print_level all -> Turn on all debug & informational messages set system.cmd.header_enabled 0 -> Disable a response header set system.cmd.prompt_enabled 1 -> Turn on the user prompt set system.cmd.echo on -> Turn on echo to see what you're typing
See also System Functions, Configuring Command API Format.
Machine Command API Format
To configure the serial interface for machine friendly operation, set system.cmd.format to
machine, or set the following settings.
set system.print_level 0 -> Turn off all debug & informational messages set system.cmd.header_enabled 1 -> Enable a response header (see Response format) set system.cmd.prompt_enabled 0 -> Turn off the user prompt set system.cmd.echo off -> Turn off character echo
See also System Functions, Configuring Command API Format.
Gecko OS commands are formatted as shown below.
<command name> <arguments>\r\n
<command name>is a Gecko OS command - see Commands
<arguments>may be required depending on the command
In the case of the get and set commands, the arguments are in the form:
<variable name> <arguments>
<variable name>is a Gecko OS variable name. See Variables
<arguments>may be required depending on the variable.
The command is terminated by a carriage return and newline character (
When system.cmd.header_enabled is true, (for example, if machine command API format has been set), responses from Gecko OS follow the format shown in the text below.
RXYYYYY\r\n <response data>
Rdenotes a Response header.
Note: If the module is operating in Safe Mode,
Ris replaced with
Xis the error code (response error codes are listed below).
YYYYYis the response data length in bytes including a trailing
\r\n. The response data length is zero if no data is available, or >2 (including
\r\n) if data is available.
<response data>. If the response data length is >0, the
<response data>is the data returned from Gecko OS in response to the command.
Response Error Codes
0 = Success 1 = Command failed 2 = Parse error 3 = Unknown command 4 = Too few args 5 = Too many args 6 = Unknown variable or option 7 = Invalid argument 8 = Serial command line buffer overflow 9 = Bounds error, command specific, bounds of the command were exceeded
Buffering Command Responses
When reading command output by machine, longer command responses may require buffering. Gecko OS supports buffering responses for a subset of commands with the variable:
If system.print_level is greater than 0, a log header together with one or more informational debug logs may be returned in addition to a response header and response data when a command is issued. Log headers follow the format shown in the table below.
LXYYYYY\r\n <log message>
Ldenotes a Log header.
Xis the log level.
YYYYYis the log message length in bytes including a trailing
\r\n. Log messages are always >2 bytes in length and including terminating
<log message>. The log message returned by Gecko OS in response to the command.
All escape characters are delimited with a backslash.
|Binary Value||Escape Value|
Hex binary values may be represented as:
\x<upper 4 bits><lower 4 bits>
- The decimal number
33has a delimited hex representation of
- The decimal number
254has a delimited hex representation of
Bus Stream Mode
As depicted in the following diagram, bus stream mode provides a transparent connection between a serial port and a network stream such as a UDP or TCP client or server. It is perfect for implementing applications such as a wireless serial port.
Bytes or characters sent from the host to a serial interface are transparently pushed by Gecko OS to a network stream via a wireless interface. Conversely, bytes or characters received by a network stream (from a remote server) via a wireless interface are transparently pushed by Gecko OS to a serial interface connected to the host. A wireless serial port is a typical application that uses stream mode.
Bus stream mode is used primarily by host applications that can handle asynchronous data (with the optional use of hardware flow control). It is perfectly suited to applications that need to use only a single network stream at any one time.
Note: While flow control is optional, we strongly recommend using flow control to prevent data loss.
For networking considerations, see Networking and Security, Serial STREAM Mode.
Configuring Bus Stream Mode
The simplest way to setup a Gecko OS device to use Stream mode is to do all the Gecko OS configuration first using command mode, then reboot into stream mode. Configuration involves just a few simple steps:
- Setup a wireless and network interface to use with stream mode e.g. wlan interface and TCP client. This typically requires setting up the wireless interface and network stream to auto-connect, or enable connection using a GPIO control pin.
- Set the serial bus.mode to
- Then save and reboot the module.
For an example, see the application note Wireless Serial Port.
Both the wlan and softap interfaces have an auto-start on bootup capability using the wlan.auto_join.enabled and softap.auto_start variables. The TCP server has auto-start capability using the tcp_server.auto_start variable. Network clients can be started using a GPIO or manually by breaking out of stream mode as described below.
Breaking out of Stream Mode
When the serial bus is in Stream mode, commands are disabled and every character sent to the serial port is automatically forwarded to a network stream. There are two ways to break out of stream mode and enable command mode entry temporarily. The first method is to send a character sequence, configurable with the bus.stream.cmd_seq, after 3 seconds of inactivity on the serial interface. By default, the stream break out sequence is
$$$. The other option available to break out of stream mode is to use a GPIO configurable with the bus.stream.cmd_gpio variable. When you're done entering commands, return to stream mode by issuing the exit command.
On breaking out of Stream mode, additional network connections may be available.