Command API Quickstart

The fastest way to learn about the ZentriOS Command API is to use a desktop machine and a UART terminal application or a web browser over Wi-Fi.

To get your ZentriOS device onto a wireless network, you need to supply the device with network credentials: the wireless network name (SSID) and password.

Let's get started!

There are few steps involved:

When you have set up a ZentriOS terminal, verified your Wi-Fi network credentials and tested the connection, you can work with all the rich capabilities of ZentriOS. One of the most important ZentriOS features is over-the-air update (OTA). This lets you load the latest version of ZentriOS, or load specific ZentriOS products for development purposes. The steps are:

Performing a Factory Reset

You may optionally performing a factory reset to ensure the device is in a known state.
Performing a factory_reset returns variables to the default configuration.

You can factory reset with the factory_reset command, using a ZentriOS terminal.

With a Zentri evaluation board, you can perform a factory reset with the Reset button and Button 1:

Opening a ZentriOS Terminal

You can control your ZentriOS device using the ZentriOS Command API via a UART serial terminal.

For a ZentriOS evaluation board, plug the computer USB port into the evaluation board micro USB port. USB provides power and UART serial connection.

For a device not on an evaluation board, connect the terminal to device UART 1 and provide power to the device. For pinout information, see Peripherals, GPIO Functions and Pins or the device datasheet.

With the device UART connected:

Ready
>
> version
ZentriOS-3.0.0.0, Built:2015-11-11 11:11:11 for AMW106.5, Board:AMWx06-E03.2

If problems arise, see the ZentriOS Troubleshooting Guide.

Setting up Wi-Fi Network Credentials

Your network credentials are stored in the ZentriOS wlan.ssid and wlan.passkey variables.

There are several ways to set these values, including:

Setting up with the Command API

To set up with the command API, open a ZentriOS terminal as described above.

Enter the following commands into a ZentriOS terminal:

ZentriOS Commands Description

set wlan.ssid     YOUR_AP_NAME
set wlan.passkey  YOUR_AP_PASSWORD
save

SSID (Service Set Identifier, or network name) for your Access Point
Password for your Access Point
Save variables so the values persist after reboot

Substitute the appropriate values for the placeholders YOUR_AP_NAME and YOUR_AP_PASSWORD.

Now you can verify the network connection. See below.

Setting Up with the ZentriOS Web App

The ZentriOS Web App provides a graphical interface to configure the network credentials on the device using a web browser. ZentriOS runs a Soft AP and an HTTP server on the ZentriOS device. You connect to the soft AP with a mobile device or computer, and run the Web App in a web browser.

In a ZentriOS terminal, enter the command:

setup web

You can put Zentri evaluation boards into setup web mode without connecting a ZentriOS terminal:

For more details, see ZentriOS Web App, Setup Web Mode.

This starts the ZentriOS Soft AP. By default the Soft AP SSID is ZentriOS-nnn, where nnn is the last three hex digits of the device WLAN MAC address, e.g. ZentriOS-2D6. The default password is password.

Connect a mobile device or Wi-Fi enabled computer to this network. Open a web browser and navigate to setup.com or ZentriOS.com.

The ZentriOS Web App opens the Web App connect tab by default, and scans for Wi-Fi networks in range.

Select your preferred network, enter the network password and click Connect. The Web App verifies the password and connects to the WLAN. If you select the Reconnect to device option, the web app restarts your ZentriOS device, and attempts to reconnect to it via the WLAN. For more details, see ZentriOS Web App, Setup Web Mode.

Now you can verify the network connection. See below.

Verifying the Network Connection

When you issue any ZentriOS command that requires network access, ZentriOS attempts to bring the network up using the values set for wlan.ssid and wlan.passkey.

You can bring the network up with the network_up command.

In the ZentriOS terminal, at the > prompt, enter the command as shown. The response should be similar to the following:

ZentriOS Commands Description

> network_up
In progress
> [Associating to YOUR_AP_NAME]
> Obtaining IPv4 address via DHCP
IPv4 address: 10.5.6.74

<- Bring the network up
ZentriOS responds with progress messages

If your ZentriOS device successfully obtains an IP address, you are connected.

Zentri evaluation boards have a network indicator LED to help determine successful association. The network indicator LED changes its blink rate from fast (no IP address), to medium (DHCP in progress) to slow (DHCP successful, IP address obtained).

If your WLAN is connected to the Internet, you can try an Internet protocol command. For example, ping a known host:

ZentriOS Commands Description

> ping google.com
Ping reply in 7ms

<- ping a Google web address
ZentriOS response indicates success

Claiming Your Device

The Zentri Device Management Service tracks ZentriOS devices, their owners, their firmware configuration and many other details. The DMS handles Over-the-Air (OTA) updates, providing a secure way to update devices in the field.

You need a free DMS account before using DMS features like OTA. To create an account go to the DMS Signup page. The DMS username (your email address) and password you register are used when you claim your device.

To claim your device, in the ZentriOS terminal, issue the dms claim command:

ZentriOS Commands Description

> dms claim YOUR_DMS_USERNAME YOUR_DMS_PASSWORD
Request POST /claim
Connecting (https): ota.zentri.com:443
Starting TLS
{"result":"ok"}

<- claim your device
ZentriOS response shows a successful result

When you have successfully claimed your device, you can OTA. See below.

Performing an OTA

Use OTA to update to the latest version of your device's ZentriOS product, or to load a development ZentriOS device with a specific ZentriOS product or version. You need to claim your device before performing an OTA. See above.

To OTA, in the ZentriOS terminal, issue the ota command:

ZentriOS Commands Description

> ota
Disassociated]
UUID: 06413041000000002E0049001951343438333231
Connecting to network
Security type from probe: WPA2-AES
Request POST /ota
Connecting (https): ota.zentri.com:443
Starting TLS
Bundle size: 729088, Free space: 823296, Core size: 425984
Bundle version: ZENTRI-AMW106-3.4.1.0, 2017-09-01T03:14:19Z, ZentriOS-W-3.4.1.0
...

<- update your device via the DMS server
ZentriOS displays progress messages

Note: If you are updating from ZentriOS-WL-1.0 to a version later than ZentriOS-1.1, you need to run the OTA command twice. The first OTA updates to ZentriOS-WL-1.1. Issue the OTA command again to update to the later version.

ZentriOS Applications

Now that you have established control over your ZentriOS device, you can experiment with the rich set of ZentriOS features using the ZentriOS Command API.

There are many application notes demonstrating ZentriOS networking applications. See Application Examples.

Getting Help

As well as the ZentriOS documentation provided on this website, ZentriOS also provides interactive command line help. At the ZentriOS terminal prompt, issue the help command:

> help
Help options for the ZentriOS Command API ...
  help all        -> Print a list of all Commands and Variables
  help commands   -> Print a list of Commands
  help variables  -> Print a list of readable Variables
  help <command>  -> Print help for a specific Command
  help <variable> -> Print help for a specific Variable

  Additional help is available online at http://docs.zentri.com