ZumLink CLI - FreeWaveTechnologies/ZumIQ GitHub Wiki

All products that support IQ include the ZumLink command-line interface (CLI) for configuration and management of the device. This section covers CLI usage common for app development tasks.

NOTE: Many settings in the CLI are applicable only to the Z9-P/PC/PE radio products and will have no effect on the behavior of the ZIQ-P/PE Application Server.

Contents

System Commands

Once in the CLI, there are a number of commands that can be issued and settings that can be configured. This section describes the commands and settings most pertinent to app development. Details on commands and settings can be found in the ZumLink or ZumIQ User Manual.

Getting Help

The help command (system.help) is used to get additional information about:

  • all commands and settings
  • commands and settings on a specific page, or
  • a specific command or setting.

All Help Information

For all help on all commands and settings, type:

help

(results omitted for clarity)

Single Page Information

For help information for a single page, use the help command with the page name as an argument. Type:

help systemInfo

(results omitted for clarity)

Single Command or Setting Help

For help information for a single command or setting, use the help command with the command or setting names as an argument. Type:

help radioSettings.txPower

Results in:

==========================================================================
                        radioSettings
==========================================================================
radioSettings.txPower=27dbm

Transmit Power
    This item sets the transmit power. A higher power can be used
    to increase link margin.  Use a lower transmit power to reduce
    interference when multiple radio links are in close proximity.
    The maximum transmit power can be limited if radioHoppingMode
    is set to Hopping_On.  See frequencyMasks for more details.

    type:uint32_t default:27dbm
    options:["30dbm","29dbm","28dbm","27dbm","26dbm",
            "25dbm","24dbm","23dbm","22dbm","21dbm",
            "20dbm","19dbm","18dbm","17dbm","16dbm",
            "15dbm","14dbm","13dbm","12dbm","11dbm",
            "10dbm","min"]
    ** Savable Configuration Item **
--------------------------------------------------------------------------
RESULT:0:OK

NOTE: If the setting or command name is unique across all pages, you can eliminate the page name and just use the command name directly (e.g., help txPower is a valid command). This is true any time a command or parameter is accessed.

CLI Organization

The CLI is organized into pages containing related commands and configurable parameters.

A list of all pages can be found by executing the pages command. Type:

pages

Results in:

Pages
   system
   systemInfo
   radioSettings
   radioSettingsHelpers
   encryption
   dataPath
   localDiagnostics
   config
   services
   network
   networkStats
   ntp
   Com1
   Com2
   TerminalServerRelay
   date
   snmp
   security
   runtimeEnvironment
   Modbus
   ioExCom
RESULT:0:OK

Page Descriptions

Page Description
Com1 Configuration of COM1 serial port
Com2 Configuration of COM2 serial port
config Commands to manage configuration
dataPath Configuration of how data is handled
date Contains assorted date and time parameters
encryption Configuration of radio encryption parameters
ioExCom Manages communications with external IO modules
license Configuration of license settings
localDiagnostics Read-only local diagnostics information
Modbus Manages the internal Modbus server
network Configuration of Ethernet port and other network settings
networkStats Read-only network statistics
ntp Configuration of Network Time Protocol settings
radioSettings Configuration of the radio module
radioSettingsHelpers Gives feedback on validity of radio settings
runtimeEnvironment Manages upgrade or reset of the runtime developer environment
security Configuration of miscellaneous security settings
services Configuration of miscellaneous services
snmp Configuration of SNMP security settings
TerminalServerRelay Options for streaming between serial device servers
system System-level commands
systemInfo Mostly read-only device description and identification settings

Seeing All Settings

Type the dump command to view the state of all configurable parameters (and see what commands are available):

dump

Dump Format

The system.dumpFormat command changes the manner in which the results of CLI commands are returned.

IMPORTANT: system.dumpFormat affects the format of responses of ALL commands and setting changes in addition to the dump command.

dumpFormat Short

Displays the page name in a header row, then each setting indented with its value, if applicable:

>dumpFormat Short
dumpFormat=Short
RESULT:0:OK
>
>network
[Page=network]
    mac_address=00:07:e7:00:01:eb
    ip_address=192.168.111.100
    netmask=255.255.255.0
    gateway=192.168.111.1
    stpEnabled=false
    txqueuelen=25
    mtu=1500
    netmaskFilterEnabled=false
    nameserver_address1=8.8.8.8
    nameserver_address2=8.8.4.4
RESULT:0:OK

dumpFormat Full or dumpFormat Result

Displays each setting with its fully-qualified name and value (page.setting=value):

>dumpFormat Full
dumpFormat=Full
RESULT:0:OK
>
>network
network.mac_address=00:07:e7:00:01:eb
network.ip_address=192.168.111.100
network.netmask=255.255.255.0
network.gateway=192.168.111.1
network.stpEnabled=false
network.txqueuelen=25
network.mtu=1500
network.netmaskFilterEnabled=false
network.nameserver_address1=8.8.8.8
network.nameserver_address2=8.8.4.4
RESULT:0:OK

dumpFormat Verbose

Displays each setting with its fully-qualified name and value AND the page name in a header row:

>dumpFormat Verbose
dumpFormat=Verbose
RESULT:0:OK
>
>network
[Page=network]
network.mac_address=00:07:e7:00:01:eb
network.ip_address=192.168.111.100
network.netmask=255.255.255.0
network.gateway=192.168.111.1
network.stpEnabled=false
network.txqueuelen=25
network.mtu=1500
network.netmaskFilterEnabled=false
network.nameserver_address1=8.8.8.8
network.nameserver_address2=8.8.4.4
RESULT:0:OK

dumpFormat Json

Displays the output result in JavaScript Object Notation:

>dumpFormat Json
dumpFormat=Json
,"RESULT":{"RESULT":0, "MESSAGE":"OK"}}

>
>network{"RESPONSE":
{"pages":{
    "network":{
        "mac_address":"00:07:e7:00:01:eb",
        "ip_address":"192.168.111.100",
        "netmask":"255.255.255.0",
        "gateway":"192.168.111.1",
        "stpEnabled":"false",
        "txqueuelen":"25",
        "mtu":"1500",
        "netmaskFilterEnabled":"false",
        "nameserver_address1":"8.8.8.8",
        "nameserver_address2":"8.8.4.4"}}}
,"RESULT":{"RESULT":0, "MESSAGE":"OK"}}

NOTE: When using the web interface CLI, results are returned in JSON format, identical to the format when dumpFormat=Json.

Settings Layout

Use the showLayout command to see a formal description of metadata for each setting. This can be useful when developing programmatic access to CLI commands, as this formally describes the interface.

showLayout

(results omitted for clarity)

This command returns a YAML representation of all pages and settings/commands.

NOTE: Content varies depending on the nature of the setting or command.

The general form is:

%YAML 1.1
---

pages:

   - page1:
      - setting1:
          (metadata fields)
      - setting2:
          (metadata fields)
   - page2:
      - setting3:
          (metadata fields)
      - setting4:
          (metadata fields)
   etc.
Metadata Type Description
default The default value of this setting.
description A detailed description of the setting.
max The maximum allowable value.
min The minimum allowable value.
modbus The Modbus register holding the value of the setting.
options A dictionary of discrete options for multiple-choice settings. When read, the name of the option will be returned, but the option can be set either by its name or its numeric value.
size The size of text field in characters.
tags A collection of tags indicating the scope of this setting.
title A short description of the setting.
type Internal data type representing this setting. Settings of type "execute" are commands that do some additional internal processing that may or may not return a value.

Configuration Commands

There are a number of configuration commands on the config page. The most commonly use are these three:

  • Rebooting the Device
  • Setting Factory Defaults
  • Persisting Configuration Changes

Rebooting the Device

Execute the reset now command:

>reset now

The system is going down for reboot NOW!(console) (Fri Aug 25 21:45:51 2017):
devuser@freewave-ib:~$ exit

NOTE: Unlike other CLI commands, there is no RESULT line that follows this command. The device simply reboots.

Setting Factory Defaults

WARNING! Factory defaults are applied immediately.

When connected to the device using a network connection, that network connection is lost, and you won't be able to contact the device again. This command should only be executed when you have physical access to the device and can configure it via Micro-USB port.

Execute the factoryDefaults set command:

>factoryDefaults set
factoryDefaults=Defaults set
RESULT:0:OK
>

freewave-ib login:

NOTE: Resetting factory defaults only affects the CLI settings. It does NOT impact any files or apps in the Linux filesystem.

Saving Configuration Changes

Configuration changes are applied to the running CLI but will not persist through a reboot unless explicitly saved. This gives the user the option to experiment with changes without committing them to flash storage.

Execute the save now command to save changes to flash, so that the changes are restored on a reboot.

>save now
save=Saved
RESULT:0:OK
>

Developer Environment Commands

Resetting the Linux File System

To completely reset the Linux File System to a pristine state, the same procedure to activate IQ can be used.

WARNING: This will erase all files in the Linux file system EXCEPT the /ptp directory, which can be used to back up any critical files on the unit itself. All other directories off of "/" are wiped out and reset.

FreeWave Recommends: When backing up files in the /ptp directory, create a single tar file for storage to minimize interference with system files.

Once any files are backed up, follow the procedure described in Activating IQ to reset the Linux file system.

Key Settings

See the ZumLink or ZumIQ User Manual for a comprehensive list of all ZumLink and ZumIQ settings and commands.

Setting most relevant for app development are listed in these pages:

SystemInfo Page

The SystemInfo page contains (mostly) read-only properties related to the identity and firmware status of the Z9-P/PE.

NOTE: SystemInfo settings are read-only unless otherwise specified.

Setting Description
serialNumber The device serial number (Z9-P/PC/PE only).
radioFirmwareVersion The radio module firmware version (Z9-P/PC/PE only).
deviceName The user-supplied device name (writable).
deviceId The Modbus ID of the device (writable).
deviceFirmwareVersion The base device firmware version.
rteVersion The running version of the developer environment.
rteTemplateVersion The developer environment template version.
license This lists any licenses applied to this unit. NOTE: "Custom Apps" indicates that the unit is licensed for app development.

COM1 and COM2 Pages

These pages contain configurable parameters for the two serial ports on the front of the device.

NOTE: Most serial port settings are familiar. The handler setting requires additional explanation.

handler Description
TerminalServer The default setting. Serial data is passed through to the Ethernet port on the TCP port assigned to the TerminalServerPort setting.
Cli The FreeWave CLI is exposed on the serial port.
Trace The FreeWave CLI is exposed on the serial port with trace enabled (for FreeWave internal use only).
Setup The serial port is setup and then released to the operating system for control. When set for COM1, COM1 will be accessible as /dev/ttyO5. When set for COM2, COM2 will be accessible as /dev/ttyO1

Network Page

Setting Description
ip_address IP address of the unit.
netmask Subnet mask of the unit.
gateway Network gateway of the unit.
nameserver_address1 Primary DNS server IP address.
nameserver_address2 Secondary DNS server IP address.

NTP Page

Accurate system time is critical to many applications and is generally required when installing packages using apt-get from the Linux command line. By default, device will attempt to retrieve its time from a network time server (time.nist.gov is the default).

IMPORTANT: There is no battery backed real-time clock. Time MUST BE synchronized with network time servers whenever it is power cycled.

NOTE: Using the setdate.sh script at the Linux command line will attempt to set the time while the system remains powered. However, to ensure that settings are available at boot, they MUST BE configured using the NTP page.

Setting Description
ntpReference Set to "NETWORK_TIME_SERVER" to use the NTP servers listed in the ntp_address settings, or "REFCLK_LOCALCLOCK" to use the internal clock.
ntp_address1..5 Server to use for time synching. Use the IP address or hostname. Set to 0.0.0.0 or blank to disable.
Command Description
ntpRestart Restarts the NTP system.
ntpDate Forces a sync with NTP servers.

Security Page

These settings support disabling interfaces to reduce the attack surface of the device.

NOTE: Changes to settings on the security page require a reboot to take effect, either by executing "reset now" in the CLI or by power-cycling the device.

enablePtpInterface

Controls whether or not the PTP interface is available

Value Behavior
true PTP (drag-and-drop) interface is enabled.
false PTP (drag-and-drop) interface is disabled.

NOTE: When disabled, the device will not be present in Windows File Explorer, and drag-and-drop configuration will not be available

enableEthernetLogin

Controls whether or not SSH logins to the unit are supported.

NOTE: This does NOT affect website logins but does affect only logins via SSH and other related connection mechanisms such as SCP.

Value Behavior
true SSH logins are enabled.
false SSH logins are disabled.

Services Page

timeOutCli

This setting defines the amount of time (in seconds) that the CLI remains active without any user input. After this timeout expires, the user is dropped back to the Bash shell (if logged in as "devuser"), or the connection to the device is closed (if logged in as "admin")