zentrios 3.4 reference guide official zentrios reference guide is available online at: this document...

ZentriOSReference Guide

ZentriOS v3.4

ZentriOS Reference Guide

ARG-ZentriOS-W-340R ZentriOS Reference Guide2014-2017 Zentri. http://zentri.com September 4, 2017

The official ZentriOS Reference Guide is available online at:

http://docs.zentri.com/zentrios/This document is provided for convenience ONLY and is likely to be out of date!

Please refer to the online version for the latest information about ZentriOS.



http://docs.zentri.com/zentrios/

Disclaimer

While the information provided in this document isbelieved to be accurate, it is under developmentand Zentri reserves the right to make changeswithout further notice to the product describedherein to improve reliability, function, or design,and makes no guarantee or warranty concerningthe accuracy of said information, nor shall it beresponsible for any loss or damage of whatevernature resulting from the use of, or reliance upon,such information. Zentri makes no warranties ofany kind, whether express, implied or arising bycustom or course of trade or performance, andspecifically disclaims the implied warranties oftitle, non-infringement, merchantability, or fitnessfor a particular purpose.

No part of this document may be copied,reproduced, stored in a retrieval system, ortransmitted, in any form or by any means,electronic, mechanical, photographic, or otherwise,or used as the basis for manufacture or sale of anyitems without the prior written consent of Zentri.

Trademarks

Zentri and the Zentri logo are trademarks of Zentri.WICED is a trademark of Broadcom Corporation,Inc. Other trademarks in this document belong totheir respective owners.

Copyright 2014-2016 Zentri, Inc.

Contact

https://www.silabs.com/about-us/contact-us

About this User Guide

This guide provides information andusage instructions for the ZentriOSapplication that runs on Wi-Fimodules available from Zentri.

An on-line version of this documentis available at:

http://docs.zentri.com/zentrios/

Organization

This document is organized into thefollowing sections:

General OverviewGetting StartedZentriOS Web AppSerial InterfaceWi-Fi InterfaceNetworking & SecurityPeripheralsFile SystemMemoryConfiguration and SetupSystem FunctionsUpgrade and RecoveryApplication ExamplesTroubleshooting GuideCommandsVariablesRelease NotesRevision History & Glossary



https://www.silabs.com/about-us/contact-ushttp://docs.zentri.com/zentrios/

4323232333334343435353535353636363737383839394041414143444647474748494950

ContentsContentsGeneral Overview

What is ZentriOS-W?Command APIFeatures and Interfaces

Wi-Fi, Networking & WebPeripherals & SensorsSystem

Getting StartedZentriOS Web AppSerial InterfaceWi-FiNetworking and SecurityPeripheralsFile SystemMemoryConfiguration and SetupSystem FunctionsUpdate and Recovery

Command API QuickstartGetting Started with the ZentriOS Web AppGetting Started with the ZentriOS Terminal

Opening a ZentriOS TerminalConfiguring Wi-Fi Credentials on the Device

Verifying the Internet ConnectionZentriOS ApplicationsGetting Help

ZentriOS Web AppSetup Web ModeLocal ModeInternet Mode

Automatically Connecting in Internet ModeManually Connecting in Internet Mode

ZentriOS Web App FeaturesConnect TabNetwork TabConsole Tab



515152525252535454555657585860606060616364646666676767686868696969707070717272

AliasClearGrepHistoryRemove (rm)

System TabFiles Tab

Folder EmulationNaming Rules for Files tab Folder Emulation

GPIO Configuration TabFirmware ManagementCloud Services

Customizing the ZentriOS Web AppWeb App Recovery

Serial InterfaceUART ProtocolSPI ProtocolIssuing Commands and Streaming Data

Executing a Command on GPIO Assertion or Reboot - Setup GPIOExecuting a Command Automatically to Set Network Credentials - Setup Auto CmdExecuting a Script Containing Multiple Commands

Serial Bus ModeRebooting to COMMAND modeCOMMAND breakout from STREAM modeRebooting to STREAM modeExit from COMMAND Breakout

Using the Remote TerminalEnabling and Connecting the Remote Terminal

Command ModeCommand Mode Configuration

Human Friendly Command ModeMachine Friendly Command Mode

Command ProtocolResponse FormatBuffering Command ResponsesLog Format

Stream ModeStream Mode ConfigurationBreaking out of Stream Mode



737373747474757677777778808081818182838385858586868686878787878788888889898990

Wi-Fi InterfaceWLAN Client Interface

Scanning for NetworksWLAN Security TypeJoining a NetworkWi-Fi Roaming

Access Point (SoftAP) InterfaceNetworking and Security

Procedure for Joining a WLAN NetworkSetting WLAN VariablesStarting the Network Up SequenceThe Network Up Sequence

DHCP ClientDHCP ServerDNS ClientDNS ServerHTTP Client

HTTP POST ExampleHTTP Client File Upload and Download

HTTP Server with RESTful APICommand Request/Response

GET RequestPOST RequestHTTP Response CodesResponse body

Log Request/ResponseGET RequestHTTP Response CodesResponseHTTP Response Codes

HTTP Server Security and AuthorizationClient AuthorizationProtecting or Securing a FileSecuring the REST API, Whitelisting API CallsCORS (Cross Origin Resource Sharing)HTTP Server Security Variables

HTTPS ClientHTTPS ServerNTP Client



91919292939393949494949595979798999999

100100101101102102103103103104104105106106107107107107107108

SMTP ClientTCP Client

TCP Client Auto ConnectTCP Client Connection Retry Sequence

TCP ServerTLS 1.0-1.2 Support

Supported TLS Cipher SuitesTLS Memory Requirements

Increasing Available Memory for TLSTLS Errors

TLS Error FormatTLS Error ExampleTLS Error CodesTLS States

TLS ClientTLS ServerUDP Client

UDP Client Auto ConnectUDP Server

UDP Server Auto ConnectWebSocket ClientWebSocket Server

WebSocket StreamWebSocket URIWebSocket Command Stream

Network Connections and StreamsStream HandlesStream CommandsSerial STREAM ModeStream LimitationsStream Types

Network Status Indication Using GPIOsRemote Terminal AccessNetwork Discovery

Discovery OverviewDiscovery OS Support

AppleWindowsLinux



108108109109110110111111111112112112113114114115116116116116117117117117117118119119120120120121122122123124125125126

AndroidDiscovery in a Nutshell

Discovery Command APIBroadcast Status Announcement

Managing GPIOs and PeripheralsGPIO Commands and Variables

GPIO CommandsGPIO Variables

GPIO Functions and PinsViewing GPIO UsageDeregistering a GPIO

Deregistering a Standard I/O GPIODeregistering Alternative Function GPIOs

Setting GPIO FunctionSystem Indicator FunctionsBus Stream Command GPIOGPIO Controlled Network ConnectionGPIO Controlled ScriptNetwork Status GPIOTCP Server Status GPIOsUDP Server Data GPIOSystem Activity GPIOBulk Flash GPIOSystem Wakeup GPIO

Setting and Getting GPIO ValuesADCs

ADC Lookup TablesPWMsLEDs

GPIO Standard I/O ControlPWM control - Blinking and Dimming LEDs

Communicating Peripheral Information Over the NetworkI2C Master Peripheral Controlling and MonitoringSPI Master Peripheral Controlling and MonitoringPeripheral GPIO Mapping by Function

File SystemListing FilesFile Types

Custom User Types



126127128128129129130130130131131131132132132133133133134134134135135135137137137138139139139140141141141142142143143

File FlagsFile VersionFile ChecksumFile NamesSpecial FilesWriting Files

Writing with the Web App File BrowserWriting with the TerminalWriting File Contents in ChunksHTTP DownloadOTA

Reading FilesReading with the Web App File BrowserReading from a TerminalHTTP Upload

Flash StorageBulk FlashSupported Bulk Flash ChipsConnecting Bulk Serial Flash to the Device

Encrypting ZentriOS FilesEncrypted File FormatEncryption SequenceDecryption Sequence

Preventing File CorruptionMemory

Memory ManagementDetermining Memory UsageMinimizing Memory UsageStreamsMemory Management Variables

HTTP clientsNetwork Buffer

Configuration and SetupWi-Fi Setup

Setup with a Web browserStarting Web Setup Mode on a Zentri Evaluation BoardStarting Web Setup Mode from a ZentriOS TerminalOpening the Web Setup PageWeb Setup Timeout



143144145145146146146147147148148148149149151152153159159159159160160161162162163163163164164164166166166167167167168

Setup by ZentriOS TerminalNetwork Setup Option

Setup by Remote TerminalInitiating Setup by GPIOInitiating Setup on BootSetup by WPS Push-button or PIN

Setup Configuration ScriptConfiguration Scripts

Executing a Script on CommandExecuting a Script on RebootExecuting a Script on GPIO Assertion or RebootDisplaying Comments and Command Output on Script ExecutionConfiguration Script FormatExample - Creating and Running a Configuration Script

Variable ConfigurationVariable Configuration FileDefault Variable ConfigurationResetting Variable Values

Powerup or RebootHard Factory ResetSoft Factory ResetUser Factory ResetLoad User Settings

NVM Backup VariablesGPIO Configuration

Using a GPIO Configuration FileStandard GPIO FunctionsSleep StateAlternative GPIO FunctionsSystem Indicator State OptionsExample GPIO config fileSystem Activity Function

System FunctionsConfiguring ZentriOS Command Mode and ResponsePower management

Sleeping and WakingPowersave Mode

Monitoring System StateControlling the Boot Image



168169169169170170171172172173173173174175176176176176177177178178178179179179179179180180180180180180181181181181181

System Identification and VersionUpdate and Recovery

Secure OTA UpdateSafe Mode

Commands and Variables Available in Safe ModeSafe Mode CommandsSafe Mode Variables

Factory ResetFactory Reset GPIOLocking Variable ValuesFactory Reset with Zentri Evaluation Board ButtonsFactory Reset Command

Web App RecoveryUpdating from WiConnect to ZentriOS

Signing up with the DMSClaim Your DeviceUpdate ZentriOS Using OTAUpdating to a Specific ProductThe ZentriOS dms CommandActivate a Product by Product Code

Application ExamplesNotesRecent ChangesBy Topic

ADC Data TransmissionBroadcast UDPConfigurationFile SystemFirmware Update & Recovery, Safe ModeHTTP UploadHTTP GET and POSTHTTP Server with RESTful API, JavaScript API, Python APISerial HTTP ServermDNS Network DiscoveryPeripheralsPower ManagementSerial InterfaceSoft APSMTP



181182182182182182183183184184185185185185186186187187188189190190190191192192193193194194194195195195196196196196197

Stream ModeTCP ClientTLS ClientTCP ServerUDP ClientUDP ServerWebSocketsWLAN

Broadcast UDP PacketSetupMethod

Open a ZentriOS Terminal to the ZentriOS deviceAssociate Module to Wi-Fi NetworkRun Python ScriptChange Properties in Broadcast UDP PacketSet the IP Address to the Test ComputerSet IP address to Target Other than Test ComputerSend ADC Values and GPIO Values in the Broadcast UDP Packet

Supporting ZentriOS Editions and VersionsChange Log

Creating a Custom ZentriOS BundleDefault Configuration FileCreating the Default Configuration File

Saving the Configuration File to a ComputerModifying the Configuration FileDownloading the Configuration File to the ZentriOS DeviceTesting the Configuration File

Creating a Custom ZentriOS Product BundleOTAing a Custom ZentriOS Bundle

Devices Running ZentriOSDevices Running WiConnect

Updating Your Device to Your Custom BundleSupporting ZentriOS Editions and VersionsChange Log

File SystemPrerequisitesLoading a File onto the ZentriOS Device

Using the Web App Files TabUsing File Create



198199199199201202204204205205206206207207208208208209209210211212213214215215215216217218220222224224226227227227228

Using http_downloadFile TypesVerifying File Integrity with a Checksum

Using file_create with a CRCDownloading Files from an HTTP Server

Downloading Multiple Files with a File ManifestSupporting ZentriOS Editions and VersionsChange Log

Recovery from SafemodeForce Safe ModeListing FaultsReturn to Normal OperationSupporting ZentriOS Editions and VersionsChange Log

HTTP UploadDescriptionSetupCreating Test FilesUploading a Single FileUploading a Single File with a Different Remote File NameUploading Multiple FilesUploading Multiple Files Specifying Remote Names and Mime TypesSupporting ZentriOS Editions and VersionsChange Log

Using the HTTP GET and HTTP POST CommandsDescriptionSetupSending a Simple GET RequestReading the HTTP Status CodeSending a GET Request with Custom HeadersSending a POST RequestSending an HTTP POST Request without ChunkingSupporting ZentriOS Editions and VersionsChange Log

The HTTP RESTful APISetup

Connect Your Device to the Local NetworkEnable the mDNS and HTTP Server

Syntax of REST API ZentriOS Commands



228229229230232233233234234235236236236237237238238238239239239239240244244245246246247247249249249250251252253253253

Sending Commands from a Web BrowserTroubleshootingHow does this work?

Sending Commands Using JavaScript XMLHttpRequestSending Commands Using cURL

ZentriOS VersionVerbose file listOpen and Read a file


HTTPS Intermediate CertificatesOverviewPrerequisite ReadingIntroduction

Self-Signed Certificate Authority (CA)Intermediate CertificateServer CertificateClient Certificate

Certificate GenerationOpenSSLGenerating a Self-Signed CA Certificate

Prepare the DirectoryPrepare the OpenSSL configuration fileCreate the Root CA Certificate Key

Create the Root CA CertificateVerify the Root Certificate

Generating an Intermediate CertificatePrepare the directoryCreate the intermediate keyCreate the intermediate certificateVerify the intermediate certificateCreate the certificate chain file

Generating a Server CertificateCreate a Server KeyCreate a Server CertificateVerify the Server CertificateCreate the Server Certificate chain file

Generating Client CertificatesCreate a Client Key



253254255255255255256257258258258259260261261262262262263263263263264265268268271272274275276276276277277277278278280

Create a Client CertificateVerify the Client CertificateCreate a .p12 for Client Certificate

Running the HTTPS ServerLoad the Server Cert/Key onto the DeviceConfigure Device as HTTPS serverConnect to the HTTPS Server via Web BrowserEnable Client Authentication

Running the HTTPS ClientLoad the Client Cert/Key and CA Cert onto the client DeviceConfigure Device as HTTPS client

Running a TLS Server and ClientAPPENDIXSupporting ZentriOS Editions and VersionsChange Log

Secure HTTP ServerOverview

Command Line ConventionsCommand Line PromptCommand Line Continuation

TLS Certificate OverviewOpenSSL

Generating a Self-Signed CA CertificateGenerating a Server CertificateAuthenticating the Client

Generating a Client Certificate and KeyLoading the Server cert onto the Device (using ZentriOS)Run ZentriOS as a Secure HTTPS ServerHTTP Server / Client AuthenticationHTTP Server Username and PasswordNotes for Windows & Additional LinksSupporting ZentriOS Editions and VersionsChange Log

HTTP Server Simple WebSocket DemonstrationSetup

Configure ZentriOS DeviceDownload and Launch the HTML page

Command ModeStream Mode



281282282282284284285285288288288289289290290290291292293294296296297297298299299300300301302302303303304304305305306

Using Multiple WebsocketsJavaScriptSupporting ZentriOS Editions and VersionsChange Log

Serial HTTP Server ExampleFeatures DemonstratedRequirements and PrerequisitesSetupImplementationSupporting ZentriOS Editions and VersionsChange Log

Web App RecoveryFeatures demonstratedPrerequisitesRecovering WLAN Credentials

Developer ConfigurationEnd User Actions

Recovering the Web AppDeveloper ConfigurationEnd User Actions


Customizing the ZentriOS Web AppThe Web App Development SystemThe Web App Production SystemSet Up and Prerequisites

Web App Languages and LibrariesSetting up the ZentriOS Web App Development EnvironmentSetting up the ZentriOS deviceConfiguring the Module and Development Host Addresses

Building the Web App and Running the Test ServerOpening the Test Web App PageChanging the Logo

Logo Image FileLogo Dimensions and Aspect RatioLogo Background ColorChanging the Logo Link

Changing StylesChanging Features



307307308309309310310310310311312314314315315316317317317318318318319321323324324325325325326329329330331333334335335

Removing a FeatureAdding a Feature

Deploying the Modified Web App to the ZentriOS deviceSupporting ZentriOS Editions and VersionsChange Log

mDNS Device DiscoverySetup

Connect Your Module to the Local NetworkEnable the mDNS Daemon

Ping the Module using the mDNS DomainAdvertise an mDNS ServiceSupporting ZentriOS Editions and VersionsChange Log

Controlling GPIOs and LEDsGPIO UsageLED ControlGPIO InitializationSupporting ZentriOS Editions and VersionsChange Log

GPIO-Controlled Network ConnectionFeatures DemonstratedMethodSetupPerforming a GPIO-Controlled Host ConnectionUsing Stream ModeSupporting ZentriOS Editions and VersionsChange Log

Handling Multiple Clients with OOB InterruptsPrerequisitesSet UpHandling a Single ClientHandling Multiple Clients

Module A SetupConnecting TCP ClientsOOB Interrupt Handler


Sending a Secure SMTP EmailSet Up the Email and SMTP Variables



335335336336336336336337337338341341342342343343344344344345345347347348348349349349349350350351352353354354354355356

Set Maximum TLS versionSet the CA Certificate for your Device

Obtain the CertificateCopy the Certificate to your DeviceSet the Network TLS CA Cert

Configure Gmail to Support Sending Emails from ZentriOSSend the EmailSupporting ZentriOS Editions and VersionsChange Log

TCP Server + softAPSupporting ZentriOS Editions and VersionsChange Log

TCP ClientConnectingWriting DataChecking for DataReading DataSupporting ZentriOS Editions and VersionsChange Log

Multiple TCP ClientsConnectingWriting DataChecking for DataReading DataChange Log

Secure TLS ClientOverviewTLS Certificate Primer

Certificate File TypesCertificate Types

OpenSSLGenerating a Self-Signed CA CertificateGenerating a Server CertificateStarting the Python TLS ServerLoading the CA cert onto the Module (using ZentriOS)

Using the Web App Files TabUsing File Create

Connecting to the Python TLS ServerScripts



356357357358358358359359360360361361361361361362362362363363364364364366367367368368370370372372374374375375375376376

Notes for Windows & Additional LinksSupporting ZentriOS Editions and VersionsChange Log

TCP Client and UDP Client Auto-ConnectDescriptionSetupTCP Auto ConnectUDP Auto ConnectSupporting ZentriOS Editions and VersionsChange Log

Power ManagementSetting Powersave ModeOther Power Management Options

Disable WLAN RSSI AveragingDisable Periodic BroadcastingDisable LED IndicatorsReduce RF Transmit PowerAdjust Bus Stream Buffering


Wireless Serial PortFeatures demonstratedWireless Serial Port using TCP

Module 1 TCP Server Configuration SettingsModule 2 TCP Client Configuration SettingsTCP Wireless Magic!

Wireless Serial Port using UDP Client/Server ConfigurationModule 1 UDP Server Configuration SettingsModule 2 UDP Client Configuration SettingsUDP Wireless Magic!

Wireless Serial Port using UDP Symmetrical Server ConfigurationModule 1 UDP Server Configuration SettingsModule 2 UDP Server Configuration SettingsMore UDP Wireless Magic!High Speed Connections


Wi-Fi Remote TerminalFeatures demonstrated



376376377377378379380380381382382383385387389389390390390391392392393393394394395395395396396397399399400400400401402

Soft AP Remote TerminalSet Up

View the Default State of the Soft AP and Remote Terminal VariablesChange the Soft AP and Remote Terminal VariablesView the Changed State of the Soft AP and Remote Terminal Variables

Connecting the Remote Terminal to the Soft APWLAN Remote Terminal

SetupConnecting the Remote Terminal to the WLAN


High Speed UARTModule 1 - SettingsModule 2 - SettingsNotes for SettingsUsing the Module 1 Soft APSetup Instructions

Update SettingsConnect UARTsRun Python Script


UDP ClientConnectingWriting DataChecking for DataReading DataSupporting ZentriOS Editions and VersionsChange Log

Multi-client WLAN CommunicationsA Simple Message ProtocolImplementation

Setup CommandsVerify it works

Example ZentriOS SessionOther Options?Supporting ZentriOS Editions and VersionsChange Log

ZentriOS FAQ



402402

402402402

402

402

404404404404405405405406406406406407407410410412412413413413415416417418418419424426427429430

I have developed my ZentriOS product. How do I put it into production?Is there a way to run a script from the web setup?Where does the module get the UTC time and which port needs to be open on our firewall for this to function?If I change the baud rate, does it go into effect after a save command, or immediately?Is there anything to be careful about when enabling hardware flow control?How do I turn off all log messages?How do I run the system in stream mode (UART0) and get the logs and all debug and informational responsesfrom UART1?

Troubleshooting GuideBasicsMy device fails to associate to the networkMy device has missing commands or variables. What do I do?Recovery from Safe ModeRecovery from Interrupted OTA UpdateTLS Errors

ZentriOS CommandsNav Tips for HumansShortcutsDocumentation Format

commandCommands by GroupDescription of Commands

adc_take_sampledac_set_leveldms

ClaimActivateUpdateTelemetry

exitfactory_resetfaults_printfaults_resetfile_createfile_deletefile_openfile_statforce_safemodeformat_flash



431432433434435436437438439440443446448450451453455456456458460461462463464465466467469472473474476477478481482483484

getgpio_dirgpio_getgpio_setgpios_dirgpios_getgpios_sethelphttp_add_headerhttp_downloadhttp_gethttp_headhttp_posthttp_read_statushttp_uploadi2c_master_configi2c_master_open

I2C Write CommandI2C Read Command

lsloadmdns_discovernetwork_downnetwork_lookupnetwork_flushnetwork_restartnetwork_upnetwork_verifyotapingpwm_updaterebootsavesetsetupsleepsmtp_sendsoftap_get_rssispi_master_config



486488489490492493495496497499500501502504505507507509510510511511511519534534536536537538540541542544544545546549550

spi_master_openstream_closestream_liststream_pollstream_readstream_writetcp_clienttcp_servertls_clienttls_serveruart_updateudp_clientudp_serverversionwebsocket_clientwlan_get_rssiwlan_scanwps

ZentriOS VariablesShortcutsDocumentation Format

variableList of VariablesVariable Properties

ALLallBroadcastbroadcast.databroadcast.http.hostbroadcast.interfacebroadcast.intervalbroadcast.udp.ipbroadcast.udp.portBusbus.command.read_timeoutbus.command.rx_bufsizebus.command.write_check_enabledbus.command.write_timeoutbus.data_bus



551553554555556558559561561561564565566567568570571572574574575576577578580580581582583585587587588590590591592593594

bus.log_busbus.modebus.stream.cmd_gpiobus.stream.cmd_seqbus.stream.flush_countbus.stream.flush_timebus.stream.flush_time_resetDMS Settingsdms.bundle_iddms.cmd.enableddms.geolocate.intervaldms.ota_hostdms.ota_resultdms.telemetry.adc_maskdms.telemetry.data_maskdms.telemetry.gpio_maskdms.telemetry.intervaldms.tokenEmailemail.name_addressemail.smtp.hostemail.smtp.passwordemail.smtp.portemail.smtp.usernameGPIOgpio.aliasgpio.config_filegpio.initgpio.sleepgpio.usageHTTP Clienthttp.client.retrieshttp.client.retry_periodHTTP Serverhttp.server.api_enabledhttp.server.auth_titlehttp.server.cors_originhttp.server.denied_filenamehttp.server.enabled



595596598599600601602603604605606607608609611613613614615616617618619621621621623624627629629630631632634635636638639

http.server.interfacehttp.server.max_clientshttp.server.notfound_filenamehttp.server.passwordhttp.server.porthttp.server.root_filenamehttp.server.tls_certhttp.server.tls_client_loghttp.server.tls_enabledhttp.server.tls_keyhttp.server.tls_log_clientshttp.server.tls_verify_peerhttp.server.usernamehttp.server.ws_connected_gpiohttp.server.ws_data_gpioIO Connectionioconn.control_gpioioconn.enabledioconn.local_portioconn.protocolioconn.remote_hostioconn.remote_portioconn.status_gpiomDNSmdns.enabledmdns.interfacemdns.namemdns.servicemdns.ttlNetworknetwork.arp.lock_enablednetwork.arp.table_sizenetwork.buffer.rxtx_rationetwork.buffer.control_sizenetwork.buffer.sizenetwork.buffer.usagenetwork.default_interfacenetwork.dns.timeoutnetwork.tcp.delivery_type



641642643644646647648649651651651652652653654655656658658659660661662664665666667669670672672673675676677678679680682

network.tls.ca_certnetwork.tls.client_certnetwork.tls.client_keynetwork.tls.versionntp.enabledntp.interfacentp.intervalntp.serverOTA Updateota.portota.hostRemote Terminalremote_terminal.enabledremote_terminal.interfaceremote_terminal.passwordremote_terminal.portremote_terminal.timeoutSetupsetup.auto.cmdsetup.gpio.cmdsetup.gpio.control_gpiosetup.gpio.levelsetup.gpio.modesetup.web.client_listsetup.web.idle_timeoutsetup.web.passkeysetup.web.root_filenamesetup.web.ssidsetup.web.urlSoftAP Interfacesoftap.auto_startsoftap.captive_portal_enabledsoftap.channelsoftap.client_listsoftap.dhcp_server.enabledsoftap.dhcp_server.lease_timesoftap.dns_server.enabledsoftap.dns_server.urlsoftap.hide_ssid



683684685686687688690691692692694695697697698700700702702703704705706707708710712713714715716717719720721722723724724

softap.idle_timeoutsoftap.infosoftap.max_clientssoftap.passkeysoftap.rate.protocolsoftap.rate.transmitsoftap.rssi_averagesoftap.ssidsoftap.static.gateway

Use Casessoftap.static.ipsoftap.static.netmaskSPI Settingsspi.master.active_gpiospi.master.active_levelStream Settingsstream.auto_closeSystemsystem.adc.vrefsystem.activity.gpiosystem.activity.gpio_levelsystem.bflash.cs_gpiosystem.boot.imagesystem.build_numbersystem.cmd.aux_bussystem.cmd.bufferedsystem.cmd.echosystem.cmd.gpiosystem.cmd.header_enabledsystem.cmd.modesystem.cmd.prompt_enabledsystem.cmd.timestampsystem.factory_reset.aux_gpiosystem.factory_reset.aux_levelsystem.gotosleep.timeoutsystem.indicator.gpiosystem.indicator.state

WLAN IndicatorNetwork Indicator



724726726728729731732733734736737738739740742743744745747747748749750752753754755756758760760761762763765765766767768

SoftAP Indicatorsystem.memory.usagesystem.msgsystem.oob.event_masksystem.oob.gpiosystem.oob.gpio_levelsystem.oob.rising_edge_masksystem.oob.statussystem.powersave.modesystem.print_levelsystem.safemode.statussystem.safemode.disabledsystem.security_keysystem.uuidsystem.variable_locksystem.versionsystem.wakeup.eventssystem.wakeup.timeoutTCP Clienttcp.client.auto_interfacetcp.client.auto_retriestcp.client.auto_starttcp.client.connect_timeouttcp.client.local_porttcp.client.remote_hosttcp.client.remote_porttcp.client.retriestcp.client.retry_periodtcp.client.tls_enabledTCP Keepalivetcp.keepalive.enabledtcp.keepalive.initial_timeouttcp.keepalive.retry_counttcp.keepalive.retry_timeoutTCP Servertcp.server.auto_interfacetcp.server.auto_starttcp.server.connected_gpiotcp.server.data_gpio



769770771773774775776778778778780780783783784786787788791791792793794795797797798799800801802803806806807808809810812

tcp.server.idle_timeouttcp.server.max_clientstcp.server.porttcp.server.tls_certtcp.server.tls_enabledtcp.server.tls_keytcp.server.tls_verify_peerTimetime.last_settime.rtctime.uptimetime.zoneUARTuart.bauduart.datauart.flowuart.parityuart.stopUDP Clientudp.client.auto_interfaceudp.client.auto_retryudp.client.auto_startudp.client.remote_hostudp.client.remote_portUDP Serverudp.server.auto_interfaceudp.server.auto_startudp.server.data_gpioudp.server.lock_clientudp.server.portudp.server.remote_hostudp.server.remote_portWLAN Interfacewlan.antenna.selectwlan.auto_join.enabledwlan.auto_join.retrieswlan.auto_join.retry_delaywlan.bssidwlan.dhcp.enabled



813814815817818819820822823824825826827828829830831832834835836837839840841842843845846847848849850852853854856857858

wlan.dhcp.cache_enabledwlan.dhcp.hostnamewlan.dhcp.timeoutwlan.hide_passkeywlan.infowlan.join.resultwlan.join.retrieswlan.join.timeoutwlan.macwlan.multicast.addresswlan.network.dnswlan.network.gatewaywlan.network.ipwlan.network.netmaskwlan.network.statuswlan.network.status_gpiowlan.passkeywlan.powersave.listen_intervalwlan.powersave.modewlan.powersave.sleep_delaywlan.rate.protocolwlan.rate.transmitwlan.regionwlan.roam.thresholdwlan.rssi_averagewlan.scan.active_dwellwlan.scan.channel_maskwlan.scan.home_dwellwlan.scan.num_probeswlan.scan.passive_dwellwlan.scan.retrieswlan.scan.typewlan.securitywlan.ssidwlan.static.dnswlan.static.gatewaywlan.static.ipwlan.static.netmaskwlan.tx_power



861862862862863863863864865865865866866867867867868868868869869

ZentriOS GlossaryRelease Notes for ZentriOS-W-3.4

Updating from WiConnectKnown Issues (v3.4.0)Changelog (v3.4.0)

Fixes and ImprovementsCommands ChangedVariables Added

ZentriOS Edition and Version HistoryWi-Fi

ZentriOS-WZZentriOS-WZentriOS-WLWiConnect

BLEZentriOS-STruConnect

Combination Wi-Fi and BLEZentriOS-XZ

Revision HistoryGlossary



General OverviewWhat is ZentriOS-W?ZentriOS-W is a highly-optimized yet feature-packed IoT operating system designed specifically topower hardware platforms with secure Wi-Fi networking capability.

Hardware running ZentriOS provides a product with a powerful and secure wireless connection to amobile device or the cloud.

You can build external MCU apps that communicate with ZentriOS using the extensive Wi-Fi CommandAPI, via serial interface, HTTP REST or a remote terminal.

To update from WiConnect to ZentriOS, see Updating to ZentriOS.

For the Bluetooth Low Energy version of ZentriOS, see ZentriOS-S.

Command APIThe ZentriOS-W Command API is available for applications connecting with a wired serial interface, ora wireless interface using HTTP REST, WebSockets or Remote Terminal. The API provides directaccess to peripherals connected to ZentriOS hardware via interfaces including SPI, I2C, GPIO, PWM,DAC/ADCs. For a quick start guide to using a ZentriOS evaluation board, see Getting Started.

General Overview ZentriOS Reference Guide

ARG-ZentriOS-W-340R ZentriOS Reference Guide2014-2017 Zentri. http://zentri.com Page | 32

http://docs.zentri.com/zentrios/s/latest/http://docs.zentri.com/resources/wifi/nup/network_up_seq1.pnghttp://docs.zentri.com/resources/wifi/tcpconnect/tcpconnect1.png

Features and InterfacesThe ZentriOS-W Command API offers a powerful set of commands for control of connected devices,together with a large number of variables for configuration.

A host MCU communicates with ZentriOS via a UART or SPI serial interface.

A mobile or desktop app communicates with ZentriOS via the HTTP Server RESTful API / Websocketsor by the local or remote terminal interface.

The local or remote host sends commands to control the operation of ZentriOS and to exchange datawith other devices on the network.

A summary of ZentriOS-W features and interfaces is outlined in the following sections.

Wi-Fi, Networking & Web

Multiple interfaces including serial, softAP and WLAN clientConcurrent operation of softAP and WLAN client



https://docs.zentri.com/zentrios/cmd/variables

Servers: TCP/TLS, UDP, HTTP/S, DHCP, DNSClients: TCP/TLS, UDP, NTP, Secure-SMTP, DHCP, DNSNetwork Discovery with support for ZeroConf/mDNS, LLMNR & NetbiosSecure HTTP Server with RESTful API and WebsocketsHTTP file upload/downloadFully-customizable mobile responsive web application with Javascript & Python librariesRemote terminal accessMultiple Wi-Fi setup options including Web setup with softAP, WPS

Peripherals & Sensors

GPIOs/ADCs/DACs/PWM for control, indication and monitoringI2C-master API for interfacing to external peripheralsSPI-master API for interfacing to external peripheralsAutomated broadcast and streaming of sensor dataLocal caching of sensor data

System

Configurable memory and network buffer sizes enabling optimization for receive or transmitintensive applicationsWireless OTA (Over-the-Air) Update to remotely manage firmware using the Zentri DMSFailsafe bootloader and kernel with safemode operationConfigurable power states and sleep/wake timersScripts and configuration filesRead/Write file systemStorage of large files

All ZentriOS commands can be issued manually using human mode or under host control usingmachine mode. Human mode should only be used for evaluation and manual testing. Machine mode isstrongly recommended for production.

For human mode, the interfaces are a ZentriOS Terminal, the ZentriOS Web App, or a remote terminal.

Getting StartedTo start using your ZentriOS hardware in human mode, see Getting Started.



https:/github.com/zentri/ZentriOSWebApp/blob/master/README.mdhttps:/github.com/zentrihttps:/github.com/zentrihttp://docs.zentri.com/dms/1.0

ZentriOS Web AppThe ZentriOS Web App provides complete monitoring and control of your ZentriOS hardware using aweb browser.

See ZentriOS Web App.

Serial InterfaceZentriOS provides one of the easiest to use and most flexible serial Wi-Fi networking interfaces in theindustry. The ZentriOS serial interface provides support for multiple serial buses including multi-UARTand serial-SPI, different serial communications modes including command mode and stream mode,and is easily configured for use by humans and machines alike.

See Serial Interface.

Wi-FiZentriOS provides an easy-to-use serial API allowing you to focus your efforts on applicationdevelopment, rather than the time-consuming complexity and interoperability issues associated with thedevelopment of a full-featured secure wireless network stack.

Two Wi-Fi interfaces are supported, including a Wi-Fi client (wlan) and Wi-Fi soft access point (softAP)interface. Each interface may be run independently or concurrently to suit various application needs.

See Wi-Fi Interface.

Networking and SecurityZentriOS includes a full IPv4 networking stack and SSL/TLS security suite that supports a range ofpopular networking protocols including TCP, UDP, DNS, DHCP. Additional network applicationlibraries are provided for native HTTP/S and secure cloud access.

See Networking and Security.

PeripheralsVarious peripheral APIs are available to provide access to general purpose IOs (GPIOs), analog



functions such as analog-digital and digital-analog converters, and timers including a real time clock.Special system and network functions can be assigned to GPIOs to enable handy features including:

automatic LED status indicators to show the state of Wi-Fi and network connections;an indication of when one or more network clients are connected to a local ZentriOS server; andthe ability to control the connection state of a client or server.

See Peripherals.

File SystemMost connected applications require the ability to store configuration information or cache local data.ZentriOS provides a reliable read/write filesystem and on-board flash storage to satisfy applicationstorage requirements. With just a few simple commands, ZentriOS provides your application withcomplete access to local and network connected storage.

See File System.

MemoryFor management of ZentriOS device memory, see Memory.

Configuration and SetupSeveral options are available to setup a module running ZentriOS. The most common option, and alsothe most convenient when prototyping is to use a command line and serial interface such as a UART. APC terminal can be quickly connected to a ZentriOS evaluation board, and within 60 seconds it ispossible to be connected to a Wi-Fi network and downloading HTTP webpages or connecting to aremote TCP server.

Other methods for configuration, setup and Wi-Fi provisioning include:

a softAP and webserver interface, or use of WPS push-button PBC or PIN for Wi-Fi provisioning;an (optionally) password-secured remote terminal that provides command line convenience overone of the ZentriOS wireless network interfaces; andautomatic execution of a custom configuration script on boot-up

See Configuration and Setup.



System FunctionsSystem functions include:

Configuring ZentriOS Command Mode and ResponsePower managementMonitoring System StateControlling the Boot ApplicationSystem Identification and Version

See System Functions.

Update and RecoveryZentriOS is part of a larger sophisticated application framework installed on all ZentriOS devices. Theframework provides a hardened bootloader, read/write file system, safemode recovery mechanism,and over-the-air (OTA) update capability.

Zentri manages a secure on-line OTA server that offers each ZentriOS device with the ability tosecurely update individual files, applications or an entire firmware bundle. In the rare event thatZentriOS fails to regularly execute correctly, the bootloader switches the boot application to safe mode.The safe mode application provides the host with the ability to update the firmware, switch back toZentriOS or even factory reset the module.

See Update and Recovery.



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

To get your ZentriOS device onto a wireless network, you need to supply the device with networkcredentials: the wireless network name (SSID) and password. There are several ways to do this,including:

Getting Started with the ZentriOS Web App. See below.Getting Started with the ZentriOS Terminal. See below.See Configuration and Setup for more ways to configure a ZentriOS device.

Let's get started!

Getting Started with the ZentriOS Web App

Command API Quickstart ZentriOS Reference Guide


The ZentriOS Web App provides a simple way to configure the network credentials on the device usinga web browser. This is particularly convenient for configuring Zentri evaluation boards, which can be putin setup web mode without connecting a ZentriOS terminal. See ZentriOS Web App, Setup WebMode.

Getting Started with the ZentriOS Terminal

Before configuring your ZentriOS device, it may be helpful to ensure the device is in a known state byperforming a factory_reset.

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 tothe device. For pinout information, see Peripherals, GPIO Functions and Pins or the device datasheet.

With the device UART connected:

Open a communication terminal application e.g. TeratermFind the UART serial (COM) port associated with the eval boardSet the communication parameters to 115200 8N1 with NO hardware flow controlPress the enter key. ZentriOS responds with a ready message and command prompt:

Ready>

At the ZentriOS prompt, type version and check for a response similar to the text below.

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

Configuring Wi-Fi Credentials on the Device

You need to provide the device with the name of your wireless network (SSID) and password. To dothis, enter the following commands into a ZentriOS terminal:

ZentriOS Commands Description

set wlan.ssid "YOUR AP NAME"set wlan.passkey "YOUR AP PASSWORD"

Name of your Access PointPassword for your Access Point

When you issue any ZentriOS command that requires network access, ZentriOS attempts to bring thenetwork up using these properties.

Zentri evaluation boards have a network indicator LED to help determine successful association. Enterthe network_up command ( nup ). 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).

To ensure that variables like the AP name and password persist after a reboot, use the savecommand:

save

Verifying the Internet ConnectionTo demonstrate that the device is connecting to the Internet, try downloading a web page:

ZentriOS Commands Description

http_get http://google.comstream_read 0 1000

Print a list of all Commands and Variables help commands -> Print a list of Commands help variables -> Print a list of readable Variables help -> Print help for a specific Command help -> Print help for a specific Variable Additional help is available online at http://docs.zentri.com

Enter help all for a full list of commands and variables.



http:/google.comhttps://docs.zentri.com/zentrios/cmd/variables

Enter help commands to list commands only, or help variables to list variables only.Enter help to show help for an individual command or variable.



ZentriOS Web AppThe ZentriOS Web App provides complete monitoring and control of your ZentriOS device using a webbrowser. It can be completely customized. See Customizing the ZentriOS Web App.

The web app can be run in any one of three modes:

Setup web modeLocal mode, without Internet accessInternet mode, connected to a wireless network with Internet access

The ZentriOS Web App serves as a complete demonstration showing how to use ZentriOS with theHTTP RESTful API.

The web app runs on the ZentriOS device. You can connect it by joining the softAP running on theZentriOS device, or, if the ZentriOS device is connected to a WAN, by joining the same network.

ZentriOS Web App ZentriOS Reference Guide


Setup Web ModeIn the factory default configuration, your module is not configured to connect with a wireless network anddoes not have local wireless network access.

Before configuring your module, you can ensure your module is in a known state by performing afactory_reset.



You can use a Wi-Fi client with a web browser, such as a smartphone, tablet or PC, to connect to theZentriOS web app via the module softAP wireless network to set up access to your wireless network.

ZentriOS evaluation boards are by default configured to enter Setup Web mode when you hold downButton 2, press Reset, and continue to hold down Button 2 for at least three seconds. See Web SetupNote.

On any ZentriOS device you can also make the module start Setup Web mode by opening a ZentriOSterminal and issuing the setup web command:

setup web

On evaluation boards, the red LED blinks when the module soft AP network is turned on and waiting fora connection.

Using the Wi-Fi settings on your computer or mobile device, connect to the module soft AP wirelessnetwork. By default, the soft AP network name (SSID) is ZentriOS-### , where ### is replaced by thelast 3 digits of the module MAC address, e.g. ZentriOS-2D6 . The default password is: password .

Open a web browser and navigate to setup.com or ZentriOS.com .

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

Click the name of your Wi-Fi network to select it.

Supply the network password in the following dialog.



The web app configures your module, saves the variables, and instructs the module to connect to yournetwork.

If you choose the Reconnect to device option, the web app restarts your module and reconnects to itvia your network, in Internet mode. This assumes that after disconnecting from the module soft APnetwork, your computer also reconnects to your network automatically. If the web app fails to reconnect,check the Wi-Fi on your computer or mobile device has roamed back to your network.

Note that the Reconnect to device option is available only in Setup Web mode.

Local Mode



Local mode provides all web app features (tabs) that do not require Internet access. Features requiringInternet access are Firmware Management and Cloud Services.

You can connect in Local mode via the module soft AP interface or via the module wlan interface.

To set up the HTTP server for the ZentriOS Web App, see the instructions in Internet Mode.

Internet ModeInternet mode requires a Wi-Fi network with Internet access. All features (tabs) are available.

Automatically Connecting in Internet Mode

The simplest way to use the ZentriOS Web App in Internet mode is to set up the module with the webapp in Setup Web mode, and check the Reconnect to device option. The web app performs all thenecessary configuration to reconnect in Internet mode.

Manually Connecting in Internet Mode

Alternatively, you can manually configure the module to run the ZentriOS Web App as described below.

Issue the following commands from a terminal:

set wlan.ssid set wlan.passkey set wlan.auto_join.enabled 1set http.server.enabled 1set http.server.api_enabled 1set mdns.enabled 1set mdns.name savereboot

For example:



set wlan.ssid Zentriset wlan.passkey secretpasswordset wlan.auto_join.enabled 1set http.server.enabled 1set http.server.api_enabled 1set mdns.enabled 1set mdns.name mymodulesavereboot

After a reboot, the response from ZentriOS is similar to the following:

Obtaining IPv4 address via DHCPIPv4 address: 10.5.6.59Starting mDNSmDNS domain: mymodule.localHTTP and REST API server listening on port: 80[2015-01-15 | 23:48:42: Associated]

The module automatically connects to your network if wlan.auto_join.enabled is configured asdescribed above.

With your computer or mobile device also connected to your network, open a web browser andnavigate to the address of the Web App.

The address is the module IP address. In the example above, you can connect a browser to http://10.5.6.59 to use the ZentriOS Web App.

You can also use network discovery to avoid using the module IP address. The address is the mDNSdomain name .local .(~/networking-and-security#network-discovery). In theexample above, you can connect a browser to http://mymodule.local . Some Windows systemsmay instead need to connect to http://mymodule . For further information see [Networking & Security,Network Discovery].

ZentriOS Web App FeaturesThe ZentriOS Web App provides information and configuration tabs that allow complete monitoring and



control of your module.

All features (tabs) of the web app are available in Internet mode, unlike Setup Web mode and Localmode, in which the Firmware Management and Cloud Services tabs are not available.

Connect Tab

The Connect tab provides a way to join your module to a Wi-Fi network. When the Connect tab opens,it automatically scans for Wi-Fi networks in range and allows you to select your network and enter apassword, as described above in Setup Web Mode.

Network Tab

If your ZentriOS device is already connected to your wireless network, then by default the web appdisplays the Network tab, showing some essential ZentriOS wlan interface variable settings.



Console Tab

The console tab works like a ZentriOS terminal or remote terminal. You can issue any ZentriOScommand from this page. In the background, the web app uses the ZentriOS HTTP RESTful API toissue commands to the module and display responses.



As well as standard ZentriOS terminal behavior, the Console tab provides additional features, exclusiveto the ZentriOS Web App. Additional commands mimic Linux shell commands and include:

aliascleargrephistoryrm

Alias

The console alias command has the following syntax: alias =""This lets you create a short name for a long command. Once an alias is set, you can type the in the console, in place of the full . For example: alias g="get gpio.usage" To remove a previously aliased command, use unalias , e.g. unalias g

Clear



The clear command clears all text on the display and returns the cursor to the top line on the console

Grep

The console grep command allows filtering of output. The following example lists only thosecommands in the history that contain the text http : history | grep http The grep syntax alsoallows regular expressions. The following example lists only those files on the module file system whosenames contain c followed by either s , t or v : ls | grep c[stv] Use the option -v to invert thegrep result and display all lines but those that match the regular expression: ls | grep -v c[stv]

History

The history command displays a list of past commands issued on the console. You can re-issue acommand by copying and pasting from the list, or by typing !i , where i is the index number of thecommand in the list. To return the last X entries in history, issue the command history X .

Remove (rm)

The rm command is identical to the ZentriOS file_delete command. Either command may be usedto delete files from the module file system.

System Tab

The system tab displays a number of system variables, such as version, build date, module, board andMAC address, memory usage and time.



Files Tab

The Files Tab lists files stored on the module file system. You can upload, download and delete files.

To upload files to the module file system, select Click to add files and browse, or drag anddrop to the Drop files here area.To download a file from the module file system, click the file name.To delete a file, click the corresponding trash icon.



Folder Emulation

The ZentriOS file system does not support directories or folders. It treats '/' characters in file names likeany other character. For example, the file a/b/c is a file with a 5 character name.

The ZentriOS Web App Files tab provides folder emulation, to simplify some file operations. Forexample, a file called a/b/c is treated for some purposes as a file in directory 'b' which is itselfcontained in directory 'a'.

You can drill down into folders to display only the files in the folder. The current folder is displayed at thetop of the Files tab. When you drag and drop a file, it is created in the current folder.

To create a folder, right click in the Files tab display and choose New Folder from the context menu.

Folders cannot be renamed or moved. A folder can be deleted if it contains no files or folders. Whenthe folder is empty, right click the folder and choose Delete from the context menu.

Files can be renamed. Right-click the file and choose Rename from the context menu.

Files can be deleted. Click the Trash icon in the file row, or right-click the file and choose Delete fromthe context menu.

Naming Rules for Files tab Folder Emulation



To use Files tab folder emulation, care is required in naming files. The Files tab supports files named inthe form:

filenamedirname/filename

However file names with slashes at the beginning or the end of the file name are not supported. TheFiles tab does not display files or allow manipulation of files named with the following patterns:

/filename

The GPIO configuration tab lists the configuration details for GPIOs in use. This is equivalent to theoutput of the get gpio.usage command. For input GPIOs, the current state is listed. For output GPIOs,buttons are provided to set the state to high or low.

Firmware Management

The firmware management tab allows Over-the-Air (OTA) wireless firmware updates. This is theequivalent of issuing the ota command. This tab is available only with Internet access.



Cloud Services

The Cloud Services tab provides links and configuration settings related to the Zentri DeviceManagement Service (DMS) and the Zentri Cloud service. The Cloud Services tab is available only inInternet mode.



Customizing the ZentriOS Web AppThe ZentriOS Web App can be 100% customized, or subtly modified to suit your needs.

Source code for the customizable version contains all the features listed above with the exception of theConsole tab.

See Application Examples, Customizing the ZentriOS Web App for a comprehensive description.

Web App RecoveryIn the event that the Web App file structure is damaged, ZentriOS provides a Web App Recoverysystem that allows end users to use Setup web mode and recover the Web App. See the Web AppRecovery application note for details.



Serial InterfaceZentriOS provides a flexible serial interface. It supports various serial protocols and modes, and iseasy to use for both humans and machines alike. ZentriOS supports two serial protocols, UART andSPI.

UART ProtocolA single or dual UART is available for use by the host MCU. If a host can support two UARTs, oneUART may be used for control and data communication, and the other used for debug logging. If asingle UART is available, control, data and debug logs (if enabled) are interleaved.

SPI ProtocolSPI provides a higher speed communications interface for higher bandwidth applications such asaudio and video. Full support for a serial-SPI communications interface will be added in an upcomingrelease of ZentriOS.

Issuing Commands and Streaming DataA ZentriOS device connects a host system to a network via Wi-Fi.

First the ZentriOS device is configured to connect to the network and to other hosts on the network.Then the ZentriOS device allows the local host to communicate with other hosts by exchanging data.

To exchange data with other hosts, you can stream data transparently between the Wi-Fi interface andthe local serial interface. This bus mode is called Stream Mode.

Alternatively, you use ZentriOS commands to mediate the exchange of data.

ZentriOS commands can be issued via:

The ZentriOS terminal console on the local serial interface.The console UART is specified by bus.data_bus. This bus mode is called Command Mode.

Serial Interface ZentriOS Reference Guide


The auxiliary console on the local serial interface.This is specified by bus.log_bus when system.cmd.aux_bus = log .Remote terminal via Telnet.See Networking and Security, Remote Terminal.HTTP RESTful API.See Networking and Security, HTTP Server.WebSocket Server /cmdstream .See WebSocket Command Stream.DMS consoleThis requires dms.cmd.enabled to be TRUE.

Commands can also be executed in response to GPIO assertion or reboot. See:

Setup GPIOSetup Auto Cmd

To configure command mode and response, see Command Mode Configuration.

The local serial interface and the remote terminal are mutually exclusive: connecting a remote terminaldisables 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 cannotdo both simultaneously. See Serial Bus Mode.

Note: to guarantee that no characters are dropped when using the local serial interface, uart.flow mustbe 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 RESTfulAPI is enabled.

Access to the ZentriOS command parser is determined by:

serial bus moderemote terminal statusHTTP 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 rebootgpio - execute if the control GPIO is asserted for 3 seconds during rebootany - 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 setup.gpio variables:

setup.gpio.cmdsetup.gpio.control_gpiosetup.gpio.levelsetup.gpio.mode

For example, the following settings cause the configuration script my_script.csv to be executed whenGPIO 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 2Set OK> set setup.gpio.level 1Set OK> set setup.gpio.mode gpioSet OKsave

Note: the setup.gpio.cmd variable takes a single argument. Enclose the argument in double quotes if itcontains 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 bootSet OK> saveSavedSuccess> rebootRebootingJTAG debug enabledZENTRI-AMW106_ZAP-3.4.0.2, 2017-08-01T08:35:32Z, ZentriOS-WZ-3.4.0.2, Board:AMW106-E03.3[Ready]Executing setup.gpio.cmd: ls> ! # Size Version Filename...setup.gpio.cmd success...

Executing a Command Automatically to Set Network Credentials - Setup AutoCmd

To execute a command automatically on boot for setting up network credentials, set the value ofsetup.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 executecommands to facilitate setting up the network credentials, wlan.ssid and wlan.passkey. To execute acommand independently of the state of wlan.ssid and 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> saveSavedSuccess> rebootRebootingJTAG debug enabledZENTRI-AMW106_ZAP-3.4.0.2, 2017-08-01T08:35:32Z, ZentriOS-WZ-3.4.0.2, Board:AMW106-E03.3[Ready]Executing setup.auto.cmd: setup web> Finding best SoftAP channel ...IPv4 address: 10.10.10.1HTTP and REST API server listening on port: 80Web setup started with the SSID: ZentriOS-335 on channel 11In progress

Note: the setup.auto.cmd variable takes a single argument. Enclose the argument in double quotes if itcontains 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 inresponse to asserting a GPIO.

See Configuration and Setup, Configuration Scripts.

Serial Bus ModeSerial bus mode concerns the local UART serial interface.

A module running ZentriOS can operate in two distinct local serial bus modes, determined by thebus.mode variable:

COMMAND mode ZentriOS commands are issued via the serial UART interface. A module is inCOMMAND mode if it booted with bus.mode set to command .STREAM mode data is transferred directly between the serial UART interface and the Wi-Fiinterface. A module is in STREAM mode if it booted with bus.mode set to stream .

ZentriOS 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_seqby 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 serialinterface and the Wi-Fi interface.

Note that this diagram illustrates access to the command parser only. Access via ZentriOS commandsto 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 theremote terminal, or via the HTTP RESTful API.

In STREAM mode, you can stream data between the UART and the Wi-Fi interface, as described inStream Mode.

As the STREAM mode + Remote Terminal case in the above diagram suggests, you can stream datato a remote host, and at the same time issue commands to the ZentriOS device via the remote terminalor the HTTP Server RESTful API. A command issued to the command parser blocks commands fromother 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 commandsavereboot

COMMAND breakout from STREAM mode

To issue commands in STREAM mode, send the breakout character sequence specified by thebus.stream.cmd_seq. This is by default $$$ .

Alternatively, set up a GPIO to enter command mode by enabling the bus.stream.cmd_gpio GPIOfunction.

On switching from STREAM mode to local COMMAND mode, ZentriOS responds with Command Mode Start .

You can then issue any ZentriOS commands.



You can set bus.mode to command and save, so that on the next reboot the ZentriOS device starts inlocal COMMAND mode.

When you have entered local COMMAND mode from STREAM mode via a breakout sequence orGPIO, 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 streamsavereboot

Exit from COMMAND Breakout

When you have entered local COMMAND mode, or remote COMMAND mode, from STREAM modevia a breakout sequence or GPIO, you can return to STREAM mode by issuing the exit command.ZentriOS responds with Command Mode Stop . For example:

Sequences and Commands Description

$$$ver...exit

Break out of STREAM modeIssue some ZentriOS commands

Return to STREAM mode

Using the Remote TerminalWhen the remote terminal is enabled and connected via telnet, the local command interface isdisabled. However the UART can still stream to the Wi-Fi interface if the module is in STREAM mode.When a ZentriOS device is in COMMAND mode and a remote terminal is connected, disconnectingthe remote terminal switches back to COMMAND mode. You can then issue commands via the localserial interface.



Enabling and Connecting the Remote Terminal

Enable the remote terminal with remote_terminal_enabled:

set remote_terminal.enabled 1savereboot

Then connect a remote device via telnet to the ZentriOS device. The default port is 2000 . The host IPor name depends on the ZentriOS configuration.

For details, see the Wi-Fi Remote Terminal application note.

Command ModeCommand mode is the primary mode used to configure ZentriOS. Understanding how command modeworks, and the options provided, is the key to mastering the use of ZentriOS. The serial interface isdesigned to cater for humans and machines alike, and the interface is configurable to suit the needs ofboth.

Note: When controlling ZentriOS via an MCU, we suggest using machine mode, described below.

Command Mode Configuration

In command mode, ZentriOS and the ZentriOS device effectively provides a slave interface to the host.The host is the master and ZentriOS is the slave. The host initiates all transactions, which follow thesequence:

host issues a commandZentriOS provides a response

ZentriOS commands are used by the host to read and write ZentriOS variables, send controlinformation, and send and receive data across network connections.

The variable system.cmd.mode is provided for convenience to make it easy to switch between humanmode and machine mode. Setting system.cmd.mode conveniently changes the value of each of thefollowing variables to configure the desired command mode.




Human Friendly Command Mode

By default, the serial interface is configured to be human friendly with the following settings.

set system.print_level all -> Turn on all debug & informational printsset system.cmd.header_enabled 0 -> Disable a response headerset system.cmd.prompt_enabled 1 -> Turn on the user promptset system.cmd.echo on -> Turn on echo to see what you're typing

See System Functions, Configuring Command Mode and Response.

Machine Friendly Command Mode

To configure the serial interface for machine friendly operation, use the following settings.

set system.print_level 0 -> Turn off all debug & informational printsset system.cmd.header_enabled 1 -> Enable a response header (described below)set system.cmd.prompt_enabled 0 -> Turn off the user promptset system.cmd.echo off -> Turn off character echo

See System Functions, Configuring Command Mode and Response.

Command ProtocolZentriOS commands are formatted as shown below. \r\n where:

is a ZentriOS command - see Commands may be required depending on the command

In the case of the get and set commands, the arguments are in the form: where:

is a ZentriOS variable name. See Variables may be required depending on the variable.

The command is terminated by a carriage return and newline character ( \r\n ).




Response Format

Responses from ZentriOS follow the format shown in the text below.

RXYYYYY\r\n

where ...

R denotes a Response header. NOTE! If the module is operating in Safe Mode, R is replacedwith S .X is the error code (response error codes are listed below).YYYYY is 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. . If the response data length is >0, the is the data returned

from ZentriOS 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.ZentriOS supports buffering responses for a subset of commands with the system.cmd.bufferedvariable.

Log Format

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. Logheaders follow the format shown in the table below.

LXYYYYY\r\n

where ...

L denotes a Log header.X is the log level.YYYYY is the log message length in bytes including a trailing \r\n . Log messages are always >2

bytes in length and including terminating \r\n characters. . The log message returned by ZentriOS in response to the command.

Stream ModeAs depicted in the following diagram, stream mode provides a transparent connection between a serialport and a network stream such as a UDP or TCP client or server. It is perfect for implementingapplications such as a wireless serial port.

Bytes or characters sent from the host to a serial interface are transparently pushed by ZentriOS to anetwork 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 ZentriOS to a serial



interface connected to the host. A wireless serial port is a typical application that uses stream mode.

Stream mode is used primarily by host applications that can handle asynchronous data (with theoptional use of hardware flow control). It is perfectly suited to applications that need to use only a singlenetwork stream at any one time.

For networking considerations, see Networking and Security, Serial STREAM Mode.

Stream Mode Configuration

The simplest way to setup a ZentriOS device to use Stream mode is to do all the ZentriOSconfiguration first using command mode, then reboot into stream mode. Configuration involves just afew simple steps: - Setup a wireless and network interface to use with stream mode e.g. wlaninterface and TCP client. This typically requires setting up the wireless interface and network stream toauto-connect, or enable connection using a GPIO control pin. - Set the serial bus.mode to stream . - Then save and reboot the module.

Both the wlan and softap interfaces have an auto-start on bootup capability using thewlan.auto_join.enabled and softap.auto_start variables. The TCP server has auto-start capability usingthe tcp_server.auto_start variable. Network clients can be started using a GPIO or manually bybreaking 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 serialport is automatically forwarded to a network stream. There are two ways to break out of stream modeand 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. Bydefault, the stream break out sequence is $$$ . The other option available to break out of stream modeis to use a GPIO configurable with the bus.stream.cmd_gpio variable. When you're done enteringcommands, return to stream mode by issuing the exit command.

On breaking out of Stream mode, additional network connections may be available.



Wi-Fi InterfaceThere are two Wi-Fi interfaces available for use with ZentriOS, a wlan client (802.11 STA) interface anda softAP (802.11 AP) interface. Both interfaces share the same physical Wi-Fi radio and antennas. Toset the Wi-Fi transmit power for both interfaces, use the common wlan.tx_power variable.

Likewise, to set the antenna used by both interfaces, use the common wlan.antenna.select variable.

WLAN Client InterfaceThe wlan client interface enables ZentriOS to join with a Wi-Fi access point at home, work or in-between.

It is possible to use the wlan and softap interfaces concurrently, however these interfaces share the Wi-Fi radio and hence must operate on the same Wi-Fi radio channel in concurrent mode. The wlaninterface has priority, and if the wlan interface starts on a different channel to the softap interface, thesoftap channel switches to the wlan channel.

ZentriOS provides various commands and variables to configure the wlan interface. See thedocumentation for wlan commands and wlan variables. An overview of WLAN functionality is providedin the following sections.

Scanning for Networks

There are two methods to scan for networks in range, active scanning and passive scanning. Activescanning involves the Wi-Fi module actively transmitting 802.11 probe request packets. When a Wi-FiAccess Point receives a probe, it replies with an 802.11 probe response. Passive scanning on theother hand avoids actively transmitting, and the Wi-Fi module simply listens for Wi-Fi Access Pointbeacons for a period of time on each channel scanned.

Each of the parameters discussed in the preceding paragraph (plus more) are configurable withZentriOS. To specify the channels to scan, use the wlan.scan.channel_mask variable. The scan type(active or passive) can be set using the wlan.scan.type variable. The time spent listening on eachchannel, in active and passive scan mode respectively, is configurable using thewlan.scan.active_dwell and wlan.scan.passive_dwell variables. In active mode, the number of 802.11probe requests is configurable using wlan.scan.num_probes.

Wi-Fi Interface ZentriOS Reference Guide


To initiate a scan for Wi-Fi networks in range, use the wlan_scan command.

WLAN Security Type

ZentriOS supports all SOHO security types including Open, WEP, WPA & WPA2, and WPA2 mixedmode.

The wlan.security variable sets security type. The default value is Auto : ZentriOS determines securitytype automatically, from the network you are attempting to join. If you are planning to use WEP (and wesincerely hope you are not since WEP IS NOT SECURE), please read the instructions in wlan.security.

Joining a Network

To join a network manually, set the wlan.ssid and wlan.passkey variables to match the network nameand network password the module is attempting to join. You can do this by setting the values of thevariables directly. See Configuration and Setup for other provisioning methods.

See Procedure for Joining a WLAN Network.

If your application is sensitive to latency or power, you should also consider customizing the number ofjoin retry attempts with the wlan.join.retries.

To hide the passkey after it has been set, simply set the wlan.hide_passkey variable. After the passkeyis hidden, it is no longer possible to read the passkey until a factory reset is performed. This stops anattacker learning the network password by physically acquiring a product with a ZentriOS device.

If the application requires the module to auto-join a network after boot up, set thewlan.auto_join.enabled variable. The number of automatic retry attempts and the delay betweenautomatic retries is configurable with the variables wlan.auto_join.retries andwlan.auto_join.retry_delay.

Once the module is joined to a Wi-Fi network, the received signal strength (signal level) of the Wi-FiAccess Point is available with the wlan_get_rssi command.

Wi-Fi Roaming

If the signal strength of the Wi-Fi Access Point the module is joined with drops too low, the moduleattempts to scan for (and roam to) another known network in range. The received signal level at whichroaming is initiated is configured using the wlan.roam.threshold variable. While the module is roaming



on other radio channels, it may miss packets on the home channel. Depending on your application, itmay be necessary to modify one or more of the wlan scan variables discussed in the Scanning forNetworks section to minimize packet loss during roaming.

Access Point (SoftAP) InterfaceThe softAP interface enables a Wi-Fi client such as a notebook, smartphone or tablet to join withZentriOS. The softap interface is primarily controlled with the softap variables:

SoftAP features:

Auto start on reboot:softap.auto_start

Wi-Fi radio channel selectionsoftap.channel

Control of interface settings such as IP address range, DHCP server, DNS redirect server:softap.static.ipsoftap.dhcp_server.enabledsoftap.dns_server.enabled

Options to adjust AP name, password and URL:softap.ssidsoftap.hide_ssidsoftap.passkeysoftap.dns_server.url

Combined use with a web server for provisioning of the WLAN interface:Configuration and Setup, Setup with a Web Browser

Control of data rate:softap.rate.protocolsoftap.rate.transmit

Control of client idle timeout:softap.idle_timeout

Monitoring of connected clients and activity information:softap.client_listsoftap.info

Note: The SoftAP is limited to a maximum of 4 WLAN clients.



Networking and SecurityZentriOS includes a full IPv4 networking stack and SSL/TLS security suite that supports a range ofpopular networking protocols including TCP, UDP, DNS, DHCP. Additional network applicationlibraries are provided for native HTTP/S and secure cloud access.

The Procedure for Joining a WLAN Network is described in detail below.

For each networking client and server there are configuration variables, and commands andprocedures to start and stop the client or server.

DHCP clientDHCP serverDNS clientDNS serverHTTP ClientHTTP Server with RESTful APIHTTPS ClientHTTPS ServerNTP ClientTCP clientTCP serverSMTP ClientTLS 1.0 - 1.2SSL/TLS clientSSL/TLS serverUDP clientUDP serverWebSocket ClientWebSocket Server

When a network connection is established, ZentriOS opens a network stream to write and read data.See Network Connections and Streams.

See the article TCP is a Stream for a discussion of the underlying mechanism of TCP, and how todetermine that data is received.

Networking and Security ZentriOS Reference Guide


http://docs.zentri.com/general/tcp-is-a-stream-robbie-hanson

Note that the term stream has different meanings depending on context. See Glossary, Stream.

Other network features include ...

Network status indication using GPIOsRemote Terminal AccessNetwork Discovery including mDNS, LLMNR & NetbiosBroadcast status announcement

Security features include ...

SSL/TLS client and serverHTTPS webserverHTTPS file upload and downloadCA certificate store

Procedure for Joining a WLAN NetworkSetting WLAN Variables

To join a WLAN network, you need to pre-set some variables. In all cases, save the variable values toNVM with the save command.

Set the wlan.ssid and wlan.passkey variables:Optionally set wlan.bssid and wlan.securityto find the WLAN SSID, you can use the network_up -s or scan commandsAfter the network credentials are set , save them to NVM with the save command

If you want ZentriOS to attempt to join the nework on boot, set wlan.auto_join.enabled to true. Youcan also specify wlan.auto_join.retry_delay and wlan.auto_join.retriesTo control the timeout on join attempts, specify wlan.join.timeout. To control the number of retriesZentriOS attempts, set wlan.join.retriesIf you want to specify static IP address, DNS and gateway values, set the wlan.static.* variables

Starting the Network Up Sequence

To start the network up sequence, do one of the following:

Networking and Security ZentriOS Reference Guide


http://docs.zentri.com/zentri/glossary#stream

Set wlan.auto_join.enabled and reboot/powerupInvoke the network_up commandInvoke any command that requires the network interface

The Network Up

zentrios 3.4 reference guide official zentrios reference guide is available online at: this document...

Documents