ZentriOS-WZ-3.3 Command API - Zentri Documentation

System

system.adc.vref

Abbreviation	sy a v
Access	get/set

Description

Specify the ADC reference voltage, in millivolts, used by the adc_take_sample command.

Arguments

<mv>

Default

3300

Properties

takes effect immediately

Supported Platforms

Get example

> get system.adc.vref
3300

Set example

> set sy a v 3200
Set OK

system.activity.gpio

Abbreviation	sy a g
Access	get/set

Description

Map GPIO to activity type. When activity is detected, the corresponding GPIO is momentarily set to the level specified by system.activity.gpio_level.

Arguments

''<GPIO#> <type> where:

<GPIO#> - the mapped GPIO. set to -1 to disable the for all configured GPIOs.
<type> - a comma separated list of activity types. The following types are available:
softap_rx
softap_tx
wlan_rx
wlan_tx
uartX_rx - where X is the uart number
uartX_tx - where X is the uart number

Default

none - no GPIOs are mapped to activity types

Properties

save and reboot to apply change

Supported Platforms

Get example

> get system.activity.gpio 1
none

Set example

> set system.activity.gpio 7 softap_rx,softap_tx,wlan_tx
Set OK
> get system.activity.gpio 7
softap_rx,softap_tx,wlan_tx
>
Ready
> set system.activity.gpio -1 softap_rx
Set OK
> get system.activity.gpio 7
softap_tx,wlan_tx

system.activity.gpio_level

Abbreviation	sy a l
Access	get/set

Description

Specify the GPIO level corresponding to activity. See system.activity.gpio.

Arguments

<1/0>

Default

1

Properties

save and reboot to apply change

Supported Platforms

Get example

> get system.activity.gpio_level 1
1

Set example

> set system.activity.gpio_level 0

system.bflash.cs_gpio

Abbreviation	sy f g
Access	get/set

Description

Specify the bulk flash's chip select gpio. Set to -1 to disable the bulk flash feature.

See File System, Flash Storage.

Arguments

<GPIO #>

Default

-1

Properties

save and reboot to apply change

Supported Platforms

Get example

> get system.bflash.cs_gpio
-1

Set example

> set sy f g 4
Set OK

system.boot.image

Abbreviation	sy b i
Access	get/set

Description

Default boot application. The <filename> must be a valid boot application available on the filesystem.

Arguments

<filename>

Default

zentrios

Properties

save and reboot to apply change
available in Safe Mode

Supported Platforms

Get example

> get sy b i
R000018
sys/services.bin

Set example

> set sy b i sys/services.bin
R000008
Set OK

system.build_number

Abbreviation	sy n (in some versions: sy b n)
Access	get

Description

Returns ZentriOS build number.

Arguments

None

Default

N/A

Supported Platforms

Get example

> get sy n
R000009
16eee81

system.cmd.aux_bus

Abbreviation	sy c x
Access	get/set

Description

Allows the log bus to act as an auxiliary command console.

If system.cmd.aux_bus is set to log and bus.data_bus != bus.log_bus then an additional command console is be allocated to bus.log_bus.

The following command sequence shows an example of using this variable. The data bus, UART0, is used in stream mode and the log bus, UART1, is used for receiving logs and sending commands.

set bus.log_bus uart1
set bus.data_bus uart0
set system.cmd.aux_bus log
set bus.mode stream
set wlan.ssid <network name>
set wlan.passkey <network password>
set wlan.auto_join.enabled 1
set tcp.client.auto_start 1
set tcp.client.remote_host test.zentri.com
set tcp.client.remote_port 50007
save
reboot

On rebooting, UART0 will send to, and receive data from, the remote TCP server test.zentri.com.

UART1 can be used to receive logs as well as send commands to ZentriOS.

Note that the $$$ break-in sequence can still be used to break in to command mode via UART0. See Serial Interface, Breaking out of Stream Mode.

Arguments

<none/log> where

none: No auxiliary command bus is available
log: The bus.log_bus acts as an auxiliary command bus

Default

none

Get example

> get sy c x
none

Set example

> set sy c x log
Set OK

system.cmd.buffered

Abbreviation	sy c b
Access	get/set

Properties

takes effect immediately
available in Safe Mode
preserved by NVM Backup

Supported Platforms

Description

Flag to enable/disable buffering of certain command responses. This is intended for use when reading command output by machine.

If enabled, a command's response is buffered and a stream handle along with the response size in bytes is returned.

The host must use the 'read' command to retrieve the command's response data.

Note that if headers are enabled, the header is returned along with the stream handle and response size.

The following commands are buffered if the system.cmd.buffered flag is set:

scan
ls
help
group getters
stream_list
get softap.client_list
get setup.web.client_list
all getters with all option

See Networking and Security, Network Connections and Streams.

Arguments

<0/off/false/1/on/true>

Default

0

Properties

takes effect immediately

Supported Platforms

Get example

> get sy c b
0

Set example

> set sy c b on
Set OK

system.cmd.echo

Abbreviation	sy c e
Access	get/set

Description

Enable/disable character echo. Only applies to command mode.

Arguments

<0/off/false/1/on/true>

Default

1

Properties

takes effect immediately
available in Safe Mode
preserved by NVM Backup

Supported Platforms

Get example

> get sy c e
R000003
1

Set example

> set sy c e on
R000008
Set OK

system.cmd.gpio

Abbreviation	sy c g
Access	get/set

Description

When configured, this GPIO is asserted HIGH AFTER ZentriOS issues a command response. It is cleared (i.e. set LOW) on the start of the next command.

Note: The system.cmd_gpio is triggered only for commands FROM the serial bus. Commands from other sources such as the remote terminal and REST API have no effect.

This makes sending commands to ZentriOS much easier:

Clear UART RX buffer
Issue command to ZentriOS
Buffer all UART RX data
Wait for the RISING EDGE of the system.cmd.gpio
Once system.cmd.gpio is triggered the RX buffer may be parsed for the command response

With DMA, the processor has to do little work. The command TX and response RX can be done in the background. An external pin interrupt triggers when the command/response sequence is complete.

Arguments

<gpio #>

Default

None

Properties

save and reboot to apply change

Supported Platforms

Set example

> set sy c g 9
R000008
Set OK

Get example

> get sy c g
R000003
9

system.cmd.header_enabled

Abbreviation	sy c h
Access	get/set

Description

Enable/disable a response header for commands. Only applies to command mode. Response headers make it easy to parse responses with a host MCU.

Arguments

<0/off/false/1/on/true>

Default

0

Properties

takes effect immediately
available in Safe Mode
preserved by NVM Backup

Supported Platforms

Get example

> get sy c h
R000003
1

Set example

> set sy c h on
R000008
Set OK

system.cmd.mode

Abbreviation	sy c m
Access	set

Description

Puts the ZentriOS command interface into human or machine mode, further details are provided in Serial Interface, Command Mode. Note!: This variable is NOT readable.

Arguments

<human | machine>

Default

human

Properties

takes effect immediately
available in Safe Mode

Supported Platforms

Set example

> set sy c m human
R000008
Set OK

system.cmd.prompt_enabled

Abbreviation	sy c p
Access	get/set

Description

Enable/disable terminal command prompt. Only applies to command mode. A prompt makes it easy for humans to interact with ZentriOS.

Arguments

<0/off/false/1/on/true>

Default

1

Properties

takes effect immediately
available in Safe Mode
preserved by NVM Backup

Supported Platforms

Get example

> get sy c p
R000003
1

Set example

> set sy c p on
R000008
Set OK

system.cmd.timestamp

Abbreviation	sy c t
Access	get/set

Description

When set to value other than none, adds a millisecond resolution timestamp to each ZentriOS response. The timestamp appears before other output, and is followed by a colon and a space, e.g.
rtc output:

> get wlan.network.ip
1409819199621: 10.5.6.71

utc output:

> get wlan.network.ip
2014-09-04 | 08:27:45: 10.5.6.71

Arguments

<none/rtc/utc> where:

none - no timestamp appended
rtc - numeric value of RTC with millisecond resolution
utc - human-readable RTC value with millisecond resolution

Default

none

Properties

takes effect immediately
available in Safe Mode
preserved by NVM Backup

Supported Platforms

Get example

> get sy c t
2014-09-04 | 08:32:11: utc

Set example

> set sy c t rtc

system.factory_reset.aux_gpio

Abbreviation	sy r g
Access	get/set

Description

If configured, this GPIO acts as an auxiliary GPIO. It has the same functionality as the hardcoded factory reset GPIO. See Update and Recovery, Factory Reset GPIO.

To disable, use GPIO# = -1:

> system.factory_reset.aux_gpio -1 ZENTRI

To set level, see system.factory_reset.aux_level.

Arguments

<GPIO#> ZENTRI where

<GPIO#>: The number of the GPIO to assign auxiliary factory reset function
ZENTRI: The password ZENTRI is a safeguard to avoid accidentally setting this GPIO function.

Default

-1 (disabled)

Properties

save and reboot to apply change

Supported Platforms

Get example

> get sy r g 
-1

Set example

> set sy r g 20 ZENTRI
Aux factory reset GPIO set
Set OK

system.factory_reset.aux_level

Abbreviation	sy r l
Access	get/set

Description

Configures the active level of system.factory_reset.aux_gpio

Arguments

<0/1>

Default

1

Properties

save and reboot to apply change

Supported Platforms

Get example

> get sy r l
1

Set example

> set sy r l 0
Aux factory reset GPIO level set
Set OK

system.gotosleep.timeout

Abbreviation	sy s t
Access	get/set

Description

The module automatically goes to sleep after a timeout period of <seconds>. The timeout countdown restarts when a wake event occurs and is held off if data is available on open network connections, the minimum timeout is 10 seconds. 0 disables gotosleep. A save and reboot is required before the sleep timeout is enabled.

Arguments

<seconds>

Default

0

Properties

save and reboot to apply change

Supported Platforms

Get example

> get sy s t
R000003
0

Set example

> set sy s t 12
R000008
Set OK

system.indicator.gpio

Abbreviation	sy i g
Access	get/set

Description

The GPIO used for a particular system indicator. System indicators drive LEDs to indicate the state of the wlan, network and softap interfaces. -1 to disable.

Arguments

<wlan/network/softap> <GPIO#>

Default

<varies>

Properties

save and reboot to apply change

Supported Platforms

Get example

> get sy i g network
R000004
11

Set example

> set gpio.alias 11 netstat_gpio   <- Alias GPIO 11 for simplicity
R000008
Set OK
> set sy i g network netstat_gpio
R000008
Set OK

system.indicator.state

Abbreviation	sy i s
Access	get/set

Description

System indicator option for each state as described in the following tables.

WLAN Indicator

Wi-Fi Client status, by default GREEN LED on eval boards

State #	State Description	Default Behavior
state 1	Wi-Fi off	static_off
state 2	Error	fast_blink
state 3	Connecting to AP	medium_blink
state 4	Joined to AP	slow_blink

Network Indicator

Network status, by default YELLOW LED on eval boards

State #	State Description	Default Behavior
state 1	No IP address	fast_blink
state 2	DHCP in-progress	medium_blink
state 3	DHCP successful	slow_blink

SoftAP Indicator

SoftAP status, by default RED LED on eval boards

State #	State Description	Default Behavior
state 1	SoftAP off	static_off
state 2	SoftAP error	medium_blink
state 3	SoftAP active	fast_blink
state 4	Client connected	slow_blink

For blink rates, see Configuration and Setup, System Indicator State Options

Arguments

<wlan/network/softap> <csv list>

Default

See above:

WLAN indicator
Network Indicator
SoftAP Indicator

Properties

save and reboot to apply change

Supported Platforms

Get example

> get sy i s wlan
R000047
static_off|fast_blink|medium_blink|slow_blink

Set example

> set sy i s network static_off|medium_blink|static_on
R000008
Set OK

system.memory.usage

Abbreviation	sy e u
Access	get

Description

Returns the heap memory currently in use, as a percentage of total heap memory. See Memory.

Arguments

-

Default

-

Supported Platforms

Get example

> get sy e u
58

system.msg

Abbreviation	sy m
Access	get/set

Description

Customize system messages for various events: initialized, sleep, wlan_joining, wlan_joined, wlan_leave, wlan_failed, softap_joined, softap_leave, network_opening, network_opened, network_closed, network_failed. Tags may be included to provide dynamic information as shown below.

Tag	Description	Tag is available for ...
@t	Timestamp	All messages
@s	SSID	All wlan messages
@c	Stream handle	network_opened, network_closed
@h	Connection host/port	network_opening, network_failed
@m	Client MAC Address	softap_joined, softap_leave

Arguments

<message name> <message value>

Default

<see get example below>

Properties

takes effect immediately

Supported Platforms

Get example

> get system.msg all
R000397
initialized - [@tReady]
network_closed - [@tDisconnected: @c]
network_failed - [@tConnect failed]
network_opened - [@tConnected: @c]
network_opening - [@tConnecting: @h]
sleep - [@tSleep]
wlan_failed - [@tJoin failed]
wlan_joined - [@tAssociated]
wlan_joining - [@tAssociating to @s]
wlan_leave - [@tDisassociated]
softap_joined - [@t@m associated]
softap_leave - [@t@m disassociated]

Set example

> set sy m wlan_leave "[@t: Bye for now]"
R000008
Set OK

system.oob.event_mask

Abbreviation	sy o e
Access	get/set

Description

The mask of events which assert the OOB GPIO. See system.oob.gpio.

For event/mask mapping, see the system.oob.gpio event mask table.

Arguments

<hex mask> Mask is specified in the form 0xHH where H is a hexadecimal digit 0-F.

Default

0x0

Properties

takes effect immediately

Supported Platforms

Get example

> get sy o e
0x1F

Set example

> set sy o e 0x11
Set OK

system.oob.gpio

Abbreviation	sy o g
Access	get/set

Description

The system.oob variables allow creation of an out-of-band interrupt (OOB) GPIO. This GPIO is asserted whenever one or more of the configured OOB events occurs. It is de-asserted when reading the OOB status register.

Note: OOB events are in most cases related to a corresponding special function GPIO variable. However, the OOB event can be configured without setting the corresponding special function GPIO. For example, the network.status_gpio OOB event can be triggered without setting the wlan.network.status_gpio variable.

Specify the OOB GPIO with the system.oob.gpio variable.

Specify the active level of the OOB GPIO with system.oob.gpio_level.

Specify the events that cause the OOB GPIO to be asserted with system.oob.event_mask.

Specify events that trigger the OOB GPIO only on the rising edge (i.e. when the event is asserted) with system.oob.rising_edge_mask.

Read the events that triggered an OOB interrupt from the system.oob.status variable.

Only one GPIO can be specified as the OOB GPIO. Determine the OOB GPIO by reading the gpio.usage variable or the system.oob.gpio variable.

Events are mapped to the event mask, rising edge mask and status mask as shown in the following table:

OOB Event Name	Mask Value
ioconn.status_gpio	0x001
wlan.network.status_gpio	0x002
tcp.server.connected_gpio	0x004
tcp.server.data_gpio	0x008
udp.server.data_gpio	0x010
tcp.client.data_gpio (see tcp_client -g)	0x020
udp.client.data_gpio (see udp_client -g)	0x040
http.server.ws_connected_gpio	0x080
http.server.ws_data_gpio	0x100
websocket.client.data_gpio (see websocket_client)	0x200
HTTP data ready (see http_get, http_post commands)	0x400

See Handling Multiple Clients with OOB Interrupts for details of use.

Arguments

<GPIO #> The number of the OOB GPIO.

Default

No GPIO assigned to OOB

Properties

save and reboot to apply change

Supported Platforms

Get example

> get sy o g
22

Set example

> set system.oob.gpio 22
Set OK

system.oob.gpio_level

Abbreviation	sy o l
Access	get/set

Description

The active level of the OOB GPIO. See system.oob.gpio.

Arguments

<0/1>

Default

1

Properties

takes effect immediately

Supported Platforms

Get example

> get sy o l
1

Set example

> set sy o l 0
Set OK

system.oob.rising_edge_mask

Abbreviation	sy o r
Access	get/set

Description

The mask of events which should trigger the OOB GPIO only on the rising edge (i.e. when an event is asserted). See system.oob.gpio.

If the mask is cleared, then the OOB GPIO is asserted on both rising and falling edges.

For instance, when the module connects, the network status event event is considered asserted. When the module disconnects, the event is considered de-asserted.

For event/mask mapping, see the system.oob.gpio event mask table.

Arguments

<hex mask> Mask is specified in the form 0xHH where H is a hexadecimal digit 0-F.

Default

0x0

Properties

takes effect immediately

Supported Platforms

Get example

> get sy o r
0x1F

Set example

> set sy o r 0x11
Set OK

system.oob.status

Abbreviation	sy o s
Access	get

Description

The mask of triggered events. When an event is triggered, the OOB GPIO is asserted and the status mask is updated with the triggering event. Reading this variable returns a mask of events that caused the OOB gpio to be asserted.

Reading this variable de-asserts the OOB GPIO and clears the status mask.

For event/mask mapping, see the system.oob.gpio event mask table.

Arguments

-

Default

0x0

Supported Platforms

Get example

get sy o e
0x0

system.powersave.mode

Abbreviation	sy p m
Access	get/set

Description

Set the system powersave mode where 0 = no powersave, 1 = core powered down on idle with <5 cycles power up latency. Additional powersave modes will be added in an upcoming release. Until then, use [system.gotosleep.timeout](/zentrios/wz/3.3/cmd/variables/system#system-gotosleep-timeout) to put the module into deep sleep.

Note! Wi-Fi powersave is independently configured using wlan.powersave.mode.

Arguments

<mode>

Default

1

Properties

save and reboot to apply change

Supported Platforms

Get example

> get sy p m
R000003
1

Set example

> set sy p m 0
R000008
Set OK

system.print_level

Abbreviation	sy p
Access	get/set

Description

Print levels:

0=None
1=Synchronous system msgs
2=Synchronous logging msgs
3=Asynchronous system msgs
4/all=Asynchronous logging msgs

Each print level includes lower levels.

Set system.print_level to 0 to disable all system and log messages.

Arguments

<[0-4]/[all]>

Default

all

Properties

takes effect immediately
available in Safe Mode
preserved by NVM Backup

Supported Platforms

Get example

> get sy p
R000005
all

Set example

> set sy p 0
R000008
Set OK

system.safemode.status

Abbreviation	sy s
Access	get

Description

Returns a flag to indicate whether the system is in safe mode. The module switches to safe mode after eight exceptions occur with the boot application.

Arguments

-

Default

0

Properties

available in Safe Mode

Supported Platforms

Get example

> get sy s
R000003
0

system.safemode.disabled

Abbreviation	sy d
Access	get/set

Description

Disables safe mode feature when set to true. When safe mode is disabled and 8 or more faults occur, ZentriOS automatically resets the fault counter and runs the boot application configured with system.boot.image. It is strongly recommended to leave this setting false as it may not be possible to recover from a fatal error.

Note: A factory reset returns this setting to the default state of false.

Arguments

<true/1/0/false>

Default

0

Properties

save and reboot to apply change
available in Safe Mode

Supported Platforms

Get example

> get sy d
R000003
0

Set example

> set sy d 1
R000009
Success

system.security_key

Abbreviation	sy k
Access	set

Description

The system.security_key variable specifies an AES-128 encryption key.

The key is stored in a special section of the NVM.

The variable value cannot be read with the get command.

The following commands use this key for encrypting the file saved on flash and set the User Encrypted file flag:

file_create with -s argument
http_download with -s argument
save

When ZentriOS reads a file with the Encrypted flag set, for internal use (within the device MCU only), it automatically decrypts the file with the system.security_key.

For example, this may take place when ZentriOS:

loads a TLS cert
loads default_config.csv
loads gpio_config_init.csv
loads a specific config file with the load command
loads a setup script as a result of settings in setup.auto.cmd or setup.gpio.cmd. See Configuration and Setup, Setup Configuration Script.

To decrypt a file with the Encrypted flag set, use one of the following commands, supplying a <security key> argument matching the system.security_key:

Arguments

<32 hex char string>

Default

Set example

> set sy k 57678F0C...
Set OK

system.uuid

Abbreviation	sy u
Access	get

Properties

available in Safe Mode

Supported Platforms

Description

Returns the hardware UUID of the module.

Arguments

Default

Properties

takes effect immediately

Supported Platforms

Get example

> get sy u
R000042
05B3203FA03133434E39423330363031B2303533

system.variable_lock

Abbreviation	sy l
Access	get/set

Description

Some variables can be locked to prevent their value being changed by factory reset. With system.variable_lock you supply a bitmask indicating which variables to lock. If the corresponding bit is SET, then the variable is locked and its value will persist through factory reset. If the corresponding bit is CLEARED then the variable is not locked.

Notes:

In setting system.variable_lock <mask>, any <mask> bit that has value 0 unlocks the variable, even if the variable was previously locked.
zap.auto_run can be locked only if the zap.auto_run variable has been previously set
0x10 saves all the settings for the bus specified by bus.data_bus.
- Currently only uart.* settings are supported: uart.baud, uart.data, uart.flow, uart.parity, uart.stop.
- Only the values for the bus.data_bus uart are locked (uart0 or uart1).

Arguments

<mask> where <mask>has the following bitmask meaning:

0x01 = zap.auto_run
0x02 = bus.mode
0x04 = bus.data_bus
0x08 = bus.log_bus
0x10 = Settings for bus currently set as bus.data_bus.

Default

0x00

Properties

takes effect immediately

Supported Platforms

Get example

> get sy l
0x00

Set example

> set sy l 0x10
Variable lock set
Set OK

system.version

Abbreviation	sy v
Access	get

Description

Returns the ZentriOS firmware bundle version.

Arguments

-

Default

<varies>

Properties

available in Safe Mode

Supported Platforms

Get example

> get sy v
R000069
ZentriOS-W-3.0.0.0, Built:Dec 09 2015 for AMW004.3-E03.1

system.wakeup.events

Abbreviation	sy w e
Access	get/set

Description

Control which events wake the module from sleep. Multiple options are separated by the '|' character. \0 disables wake events.

Some UART interfaces do not have wake capability. See Peripherals, GPIO Functions and Pins for tables showing GPIOs with wake capability.

Note: On Zentri evaluation boards the Button 2 GPIO (GPIO11 Wallaby, GPIO22 Numbat) is by default set as one of the system.wakeup.events and also associated with the setup.gpio.control_gpio function. When using Button 2 as a wakeup event, either disable the setup.gpio.control_gpio function, or ensure the GPIO is asserted for less than 3 seconds, otherwise the module will enter web setup mode after waking.

Arguments

<[<uartX>|<gpioX>] / [\0]>

Default

uart0

Properties

takes effect immediately

Supported Platforms

Get example

> get sy w e
R000007
uart0

Set example

> set sy w e gpio5|uart0
R000008
Set OK

system.wakeup.timeout

Abbreviation	sy w t
Access	get/set

Description

The module automatically wakes from sleep after timeout . Wake events are configured with system.wakeup.events. 0 disables auto-wakeup.

Arguments

<seconds>

Default

0

Properties

takes effect immediately

Supported Platforms

Get example

> get sy w t
R000003
0

Set example

> set sy w t 60
R000008
Set OK