WiConnect commands

This page provides a list of WiConnect commands with a full description of how to use each command.

Nav Tips for Humans

WiConnect command mode is friendly for humans too. Use the following tips and you'll be an expert WiConnect terminal jockey in no time flat!

Shortcuts

A shortcut is assigned to each command. Common sense dictates the rules for shortcuts. Commands that are already short do not need a shortcut other than their name, shortcuts for longer commands sometimes take the first three letters of the command name, and other times take the first letter of the name plus several other letters contained in the name. Shortcuts are no longer than six characters and are easy to guess, the ultimate reference however is command help and the documentation on this page.

Documentation Format

Many of the WiConnect responses shown in the examples on this page were captured with system.print_level = all, and system.cmd.header_enabled = true. These settings are provided to make it easy for a host microcontroller to parse responses by examining response headers. Information about machine parsing is available in Serial Interface, MCU Config.

Documentation for each command is provided in the format shown below.

command

Abbreviation

cmd

Description

A description of how to use the command with, together with notes about available options and arguments.

Syntax

Formal command syntax with a listing of all available options and arguments.

Example

One or more examples demonstrating how the command is used.

Alphabetical List of Commands

• A
  • adc_take_sample
• D
  • dac_set_level
• E
  • exit
• F
  • factory_reset
  • faults_print
  • faults_reset
  • file_create
  • file_delete
  • file_open
  • force_safemode
  • format_flash
• G
  • get
  • ghm_activate
  • ghm_capabilities
  • ghm_deactivate
  • ghm_message
  • ghm_read
  • ghm_signup
  • ghm_sync
  • ghm_write
  • gpio_dir
  • gpio_get
  • gpio_set
  • gpios_dir
  • gpios_get
  • gpios_set
• H
  • help
  • http_add_header
  • http_download
  • http_get
  • http_head
  • http_post
  • http_read_status
  • http_upload
• L
  • ls
  • load
• M
  • mdns_discover
• N
  • network_down
  • network_lookup
  • network_up
  • network_verify
• O
  • ota
• P
  • ping
  • pwm_update
• R
  • read
  • reboot
• S
  • save
  • set
  • setup
  • sleep
  • smtp_send
  • stream_close
  • stream_list
  • stream_poll
  • stream_read
  • stream_write
• T
  • tcp_client
  • tcp_server
  • tls_client
  • tls_server
• U
  • udp_client
  • udp_server
• V
  • version
• W
  • wlan_get_rssi
  • wlan_scan
  • wps
  • write

Description of Commands

adc_take_sample

Abbreviation

adc

Description

Take an analog sample of a pin using an onboard Analog-Digital Converter.

To set the ADC reference voltage, see system.adc.vref.

Syntax

> adc_take_sample <gpio#> [<gain>] [-v]/[<LUT Filename.csv>]

• <gain> - optional, defaults to 1 if not specified. The valid values for the adc gain are 1, 2, 4.
• <-v> - optional, return ADC value as voltage. Must NOT be specified with the LUT parameter
• <LUT Filename.csv> - optional, filename of Lookup Table (LUT) to use for converting ADC values. See Peripherals, ADC Lookup Tables for details.

Example

> adc 1 1
R000007
0x805
> adc 20 thermistor.csv
R000009
80.0223

D

dac_set_level

Abbreviation

dac

Description

Set the output level of a DAC. The DAC output voltage level is set to 3.3V x <level>/4096.

Supported hardware: GPIO 0 on AMW004 (Wallaby).

Syntax

> dac_set_level <level>

Example

> dac 0 2048
Success

E

exit

Abbreviation

exit

Description

Exits command mode immediately and returns to stream mode. Only valid when stream mode is operational.

Syntax

> exit

Example

> exit
Command Mode Stop
[Ready]

F

factory_reset

Abbreviation

fac

Description

Reset the application configuration to factory default values. The WLAN MAC address wlan.mac must be provided as an argument to avoid accidental factory reset. Note! The application may also be factory reset by asserting GPIO0 for 10 seconds through a module reset as described in Upgrade and Recovery, Factory Reset.

Syntax

> factory_reset <MAC address>

Example

> get wl m
R000019
4C:55:CC:10:03:44
> fac 4C:55:CC:10:03:44
Success

faults_print

Abbreviation

faup

Description

List system faults. After 8 faults, the system enters Safe Mode. See Upgrade and Recovery, Safe Mode.

Syntax

> faults_print

Example

> faup
Success

faults_reset

Abbreviation

faur

Description

Reset system fault counter. See Upgrade and Recovery, Safe Mode.

Syntax

> faults_reset

Example

> faur
Success

file_create

Abbreviation

fcr

Description

Create a new file <size> bytes in length. After the command is issued, the ensuing <size> number of bytes is written to the file system.

Files can be written in chunks smaller than the specified length, using the -o option.

Additional options include a version, file type and CRC, or checksum.

See Writing Files to the File System.

Syntax

> file_create [-[e][u]] [-o] <filename> <size> [<version> [<type> [<crc>]]]

• hex format: upper or lower case, with or without leading 0x, e.g. 0xFE, fe, 0xe1c8

Example

In the example below, the file content , Hello World! is 12 bytes in length and is entered or sent by the user.

> fcr myfile.txt 12
Hello World!
File created

Example

Create file for writing in chunks

> file_create -o my_file.txt 100
3
> write 3 50
... <50 bytes of data> ...
> write 3 50
... <50 bytes of data> ...
File created

file_delete

Abbreviation

fde

Description

Delete a file from the file system.

Syntax

> file_delete <filename>

Example

> fde myfile.txt
L000014
File deleted
R000009
Success

file_open

Abbreviation

fop

Description

Open a file and return a file stream handle if successful. Once open, the file contents may be read with the stream_read command.

Syntax

> file_open <filename>

Example

> fop myfile.txt
R000003
0

format_flash

Abbreviation

format

Description

Format (i.e. erase all contents) of bulk or extended flash chip. If the extended flash is specified, ALL files BUT the wifi_fw.bin file are erased.

For details on enabling and using bulk flash, see File System, Internal, Extended and Bulk Flash. See also the system.bflash.cs_gpio variable.

Syntax

> format_flash <bulk/extended> <module MAC address>

Example

> format bulk 4C:55:CC:10:10:98
Formatting flash...

force_safemode

Abbreviation

force_safemode

Description

Force the module into safe mode. This command is used by a host to test recovery procedures if the module enters safe mode. See Application Notes, Recovery from Safe Mode for further information.

This is a hidden command that does not appear in the list of commands returned by help commands.

Syntax

> force_safemode <module MAC address>

Example

> force_safemode 4C:55:CC:10:10:98
Forcing safemode...
Rebooting
[Disassociated]
WiConnect-2.1.0.9, Built:2015-01-25 15:58:14 for AMW004.3, Board:AMW004-E03.3

*** Max faults exceeded. Entering Safe Mode.
SAFEMODE>

G

get

Abbreviation

get

Description

Get the value of a WiConnect variable or group of variables.

Syntax

> get <[variable name] / [variable group]> [options]

Example 1

> get time.rtc utc
R000029
2014-03-23T23:54:33.021464Z

Example 2

> get bus
R000166
bus.data_bus: uart0
bus.log_bus: uart0
bus.mode: command
bus.stream.cmd_gpio: 0
bus.stream.cmd_seq: $$$
bus.stream.flush_count: 1500
bus.stream.flush_time: 20

ghm_activate

Abbreviation

gac

Description

Activate the device with goHACK.me. A valid goHACK.me username and password must be provided. If a capabilities filename is provided, the ghm.capabilities variable is updated with the specified filename. See goHACK.me Device Capabilities.

Need a goHACK.me account? Signup at goHack.me and then use ghm_activate to activate your device. See goHACK.me, Basic Account for details of restrictions.

Note: If ghm.solo.enabled is set, the device reboots and automatically connects to goHACK.me after activation completes successfully.

Syntax

> ghm_activate <username> <password> [capabilities filename]

Example

> get ghm.capabilities
ghm_capabilities.json
> ghm_activate your-email@address.com ******** mycaps.json
Request POST /api/activate/login
Connecting (https): gohack.me:443
Starting TLS
HTTP response: 200
Success
> get ghm.capabilities
mycaps.json

ghm_capabilities

Abbreviation

gca

Description

The ghm_capabilities command enables users to download and manipulate goHACK.me device capabilities files. Options include the ability to list example capabilities files on the goHACK.me server, download a specific capabilities file and setup the device to use it, or independently configure which capabilities file to use when the device activates with goHACK.me.

Note! After device activation, the capabilities file is read only. To modify or delete the file, first deactivate the device using ghm_deactivate.

Syntax

Listing Capabilities

> ghm_capabilities <list>

where:

• returns a list of example capabilities files for use with the device

Downloading Capabilities > ghm_capabilities download [<filename / URL> [-s] [-d] [<version>] where:

• <filename> - The name of the capabilities file to download. If no filename is specified, download the default caps file, typically ghm_capabilities.json, and set it for use with goHACK.me
  Note:
  • Example caps files downloaded from ACKme overwrite existing files with the same name.
  • Do not add a JSON extension to the filename
• <URL> - URL specifying the network location of the file. Local caps files with an identical name to a downloaded caps file will not be overwritten. In this case, the command fails. Delete the version of the file manually first.
• [-s] - Download a setup script that works with the capabilities, then run the script to setup the device to run 'solo' in a standalone mode (external host not needed!).
• [-d] - Download the file only, do not set the file for use.
• [version] - Provide a version number for the file.

All parameters are optional. If no parameters are provided, the default capabilities file for the device is downloaded and configured for use with goHACK.me.
Note:

• Device activation is NOT required to use this command
• The capabilities filename on the server is used as the filename on the local file system. If the file already exists on the filesystem, the command fails.

Setup & Querying Capabilities > ghm_capabilities <get/set> where:

• <get> returns the filename of the capabilities used with goHACK.me. The ghm.capabilities variable may also be used to return the capabilities filename.
• <set> sets the filename of the capabilities to be used with goHACK.me

List Example

> ghm_capabilities list
Request GET /1.2/ghmcaps/amw004_e03.4/capabilities_list?do=export_raw
Connecting (http): wiconnect.ack.me:80
HTTP response: 200
======================================================================
Capabilities Filename  Description
======================================================================
ghm_capabilities       Default capabilities
                       -----------------------------------------------
                                    NAME        TITLE
                       Streams  --> button1     Button 1
                                --> button2     Button 2
                                --> thermistor  Thermistor
                       Controls <-> led1        LED 1
                                <-> led2        LED 2
                       Messages --> from-device
                                <-- to-device

Download Example

Download the default capabilities file and run the accompanying setup script for solo mode operation:

> ghm_capabilities download -s
Connecting (http): wiconnect.ack.me:80
HTTP response: 200
Setup file: ghm_capabilities_setup.csv created
Running setup script
>  Setup GPIO for use with goHACK.me
set        ghm.solo.gpio       0    button1
Set OK
>  Setup GPIO for use with goHACK.me
set        ghm.solo.gpio      10       led1
Set OK
>  Set goHACK.me auto sync period for solo mode
set ghm.solo.sync_period                  4
Set OK
>  Enable solo mode for standalone operation
set     ghm.solo.enabled                  1
Set OK
> save
Saved
Success
> get        ghm.solo.gpio              all
!  # Description
#  0 - stream.button1 - in
# 10 - control.led1 - out

Download user-generated capabilities file, set the version to 2.3.0:

> ghm_capabilities download http://myserver.com/my_caps.json 2.3.0
Request GET /1.2/ghmcaps/amw004_e03.4/ghm_capabilities?do=export_raw
Connecting (http): wiconnect.ack.me:80
HTTP response: 200
Capabilities file: ghm_capabilities.json created
Success

ghm_deactivate

Abbreviation

gde

Description

Deactivate the device from goHACK.me. A valid goHACK.me username and password must be provided for successful deactivation.

Syntax

> ghm_deactivate <username> <password>

Example

> ghm_deactivate your-email@address.com ********
Request POST /api/token/deactivate
Connecting (https): gohack.me:443
Starting TLS
HTTP response: 200
Success

ghm_message

Abbreviation

gme

Description

goHACK.me provides the ability for devices to get messages from a message box called to-device and post messages to a message box called from-device. The ghm_message API is used to manipulate messages. The primary message options are list, get, post and delete.

Syntax

Listing Messages

> ghm_message <list> [<-t time> / <-c count>]

where:

• < -t time> - gets all messages since the specified time
• < -c count> - gets 'count' messages, latest first

Getting Messages

> ghm_message <get> [<list_index / msg_id>]  [<all> / <body>]

where:

• <list_index / msg_id> is optional, the latest message is returned if omitted
• <list_index> is the message index returned by ghm_message <list>
• <msg_id> is the ID of a specific message
• <all / body> is optional, only the message text is returned if omitted
• <all> returns the entire message including the message header
• <body> returns the JSON formatted message body

If successful, ghm_message returns a stream handle, the message may then be read using the stream_read command.

Posting Messages > ghm_message <post>

If successful, the ghm_message returns a stream handle. The message may then be written using the stream_write command. To complete and send the message, use the stream_close command.

Deleting Messages > ghm_message <delete> <index / msg ID> where:

• <index / msg ID> is either the message index returned by ghm_message <list> or the ID of a message

List Example

> ghm_message list
Request GET /api/token/messages/to-device/index
Connecting (https): api.gohack.me:443
Starting TLS
HTTP response: 200
! # Message ID                           Timestamp     Length
# 0 09b6a12e-162f-435d-86cd-14463ff5e8a4 1404832747366 0x0010
# 1 6d47011e-ac4d-4501-80fe-4fe8921cabb0 1404832741419 0x000f
# 2 990df780-7d5d-4032-a8d5-f3810c89e459 1404832704239 0x0020
# 3 4b93708b-e387-4a74-8f1f-6dd30b9c84c8 1404830371994 0x0019
# 4 f3f3b532-ef6f-49be-ba41-8db035572beb 1404830267929 0x0017
# 5 fe1bfd74-f1b9-437e-ae8f-7edfd7f56492 1404830260260 0x0013

Get Example

> ghm_message get 2
Request GET /api/token/messages/to-device/990df780-7d5d-4032-a8d5-f3810c...
Connecting (https): api.gohack.me:443
Starting TLS
HTTP response: 200
[2014-07-08 | 15:21:16: Opened: 0]
0
> stream_read 0 100
Hello from goHACK.me!
[2014-07-08 | 15:21:18: Closed: 0]

Post Example

> ghm_message post
Request POST /api/token/messages/from-device
Connecting (https): api.gohack.me:443
Starting TLS
[2014-07-08 | 15:21:55: Opened: 0]
0
> stream_write 0 6
Hello!
Success
> stream_close 0
HTTP response: 200
[2014-07-08 | 15:22:25: Closed: 0]
Success

Delete Example

> ghm_message delete 990df780-7d5d-4032-a8d5-f3810c89e459
Request DELETE /api/token/messages/to-device/990df780-7d5d-4032-a8d5-f3810c89e459
Connecting (https): api.gohack.me:443
Starting TLS
HTTP response: 200
Success

ghm_read

Abbreviation

gre

Description

Read the value of control parameter(s) from a local cache after using ghm_sync to pull the latest values from goHACK.me. If a control parameter name is not provided, the value of all control parameters is returned. The timestamp is returned only if it is non-zero.

Syntax

> ghm_read [control name]

Example

> ghm_read
fanspeed,3|porchlight,on
> ghm_read fanspeed
3
> ghm_read porchlight
on

ghm_signup

Abbreviation

gsi

Description

Signup from devices is no longer supported. Sign up for a goHACK.me account at http://goHACK.me. Once you have an account set up, use ghm_activate to activate your device. See Getting Started with goHACKme for details.

ghm_sync

Abbreviation

gsy

Description

Immediately push locally cached stream samples and control parameters to goHACK.me, and pull control parameters from goHACK.me. If the push or pull option is provided, only a push or pull is performed. If no options are provided, both a push and pull is performed. Control parameters pulled from goHACK.me are stored in a local cache and may be read using ghm_read.

Syntax

> ghm_sync [push/pull]

Example

> ghm_sync
Request GET /api/token
Connecting (https): gohack.me:443
Starting TLS
HTTP response: 200
Success

ghm_write

Abbreviation

gwr

Description

Write the value of one or more stream samples or control parameters. Samples are written to a local cache and `y pushed to goHACK.me when the cache size is exceeded. Control parameters are immediately pushed to goHACK.me.

Use the first example template if only one value is written, and the second example template if more than one value is written. If the optional timestamp is not provided, values are automatically timestamped by the server.

Syntax

> ghm_write <name> <value> [timestamp]
> ghm_write <name1>,<value1>[,timestamp1]|<name2>,<value2>,...
where:
  * <name> is the name of the stream or control parameter
  * <value> is the value to be written
  [timestamp] is an optional timestamp

Control Example

> ghm_write_control led1 1
Request POST /api/token
Connecting (https): gohack.me:443
Starting TLS
HTTP response: 200
Success

Stream Example

> ghm_write dooropen 1
Success
> ghm_write temperature,75,1404833404122|temperature,79,1404833404302
Success

gpio_dir

Abbreviation

gdi

Description

Set the direction of a general purpose I/O pin. To deregister the GPIO, set the direction to either -1 or none.

Note : This is a run-time only setting: the value is not saved with the save command. To set the direction of a GPIO after a reboot, set the variable gpio_init. See Peripherals, Setting GPIO Function.

Syntax

> gpio_dir <GPIO#> <direction> where <direction> may be one of the following values. For each type there are several equivalent alias values, listed with comma separation:

Example

> gdi 12 in_highz
R000008
Set OK

gpio_get

Abbreviation

gge

Description

Get the current value of a general purpose I/O pin.

Syntax

> gpio_get <GPIO#>

Example

> gge 12
R000003
0

gpio_set

Abbreviation

gse

Description

Immediately set the value of a general purpose I/O pin. When setting a GPIO, the GPIO direction must be also correctly set using the command gpio_dir or the command will fail.

Syntax

> gpio_set <GPIO#> <value>

Example

> gse 12 1
L000032
GPIO not configured for output
R100016
Command failed

gpios_dir

Abbreviation

gdis

Description

Set the direction of all general purpose I/O pins. A direction for all GPIOs must be provided with the direction of GPIO 0 in the first (left-most) position in the array.

Note : This is a run-time only setting: the direction values are not saved with the save command. To set the direction of a GPIO after a reboot, set the variable gpio_init. See Peripherals, Setting GPIO Function.

Syntax

> gpios_dir <direction array> where a <direction array> element may be one of the values in the following table.

Example

> gdis 10011011333530011000222226622
R000008
Set OK

gpios_get

Abbreviation

gges

Description

Get the current value of all general purpose I/O pins. The value of standard GPIOs is returned as either 0 or 1. Other GPIO types not configured for GPIO access (such as UART pins or system indicators) are returned as X.

Syntax

> gpios_get

Example

> gpios_get
R000031
0XX00X0000000XX10XXX000000000

gpios_set

Abbreviation

gses

Description

Immediately set the value of all general purpose I/O pins. When setting a GPIO, the GPIO direction must be also correctly set using gpio_dir or gpios_dir or the command will fail. The value for all GPIOs must be provided, with the value of GPIO 0 in the first (left-most) position in the array.

Syntax

> gpios_set <GPIO value array>

Example

The examples shown below are for the AMW004 Wallaby module which has 29 GPIOs, the first example command failed because the GPIO value array contained less than 29 values.

> gses 100110100101101001001011
L000022
Must supply 29 gpios
R700018
Invalid argument

> gses 10011011001011110100100101111
R000008
Set OK

H

help

Abbreviation

help, ?

Description

Return a list of commands or variables; or return help for a specific command or variable.

Syntax

> help [all/commands/variables/<command>/<variable>]

Example

> help
Usage   : help [all/commands/variables/<command>/<variable>]
Shortcut: help
Brief   : Return a list of commands or variables; or return
          help for a specific command, variable or group of
          variables.

http_add_header

Abbreviation

had

Description

Add a custom HTTP header to the HTTP stream specified by <handle>.

Syntax

> http_add_header <handle> <key> <value> where:

Options must be provided in the order shown.

Example

> http_get -o ack.me
[2014-03-29 | 01:37:17: Connecting: http://ack.me]
Request GET /
Connecting (HTTP): ack.me:80
[2014-03-29 | 01:37:18: Connected: 0]
0
> had 0 Content-type application/text
Success
> hre 0
HTTP response: 200
200

http_download

Abbreviation

hdo

Description

Download one or more files from a remote http server and save to the extended or bulk flash.

Timeout is determined by tcp.client.connect_timeout.

Syntax

Download a Single File

> http_download [-i <wlan/softap>] [-m <json_size>] [-d] [-[e][u]] [-c <CRC>] <url>
  [<flash_file_name> [<version> [<type> [<cert_filename>  ] ] ] ]

where parameters are as follows:

• hex format: upper or lower case, with or without leading 0x, e.g. 0xFE, fe, 0xe1c8

Downloading Multiple Files > http_download -m <json_size>

Immediately after issuing this command, send <json size> bytes of a JSON formatted manifest file. An example of the manifest file is as follows:

{
   "path"  : "https://myserver.com/path/to/my/files/",
   "cert"  : "mycert.pem",
   "files" : [
                {
                    "remote"  : "name_of_remote_file.html",
                    "local"   : "name_of_flash_file.html",
                    "version" : "1.0.0",
                    "type"    : 150,
                    "flags"   : "eu",
                    "crc"     : 23423
                },
                { ... }
              ]
}

Notes:

• Only the "remote" parameter is mandatory. The other parameters are optional.
• In the manifest, the file type and crc are expressed in decimal, not hex, unlike in the -c parameter.
• The file type 150 (hex 0x96) is a custom user type.

String Replacement

WiConnect allows string replacement in the URL of the file for download, using a C-like or pythonesque syntax.

If the url contains %s, then the supplied filename is substituted for %s.

Example: hdo 192.168.1.110:50007?id=%s&action=download my_file.txt generates the URL: http://192.168.1.110:50007?id=my_file.txt&action=download and creates the file: my_file.txt in the module file system.

String replacement is also available in the manifest. For example:

{
   "path" : "http://myserver.com?file=%s&user=name&pass=1234",
   "cert" : "mycert.pem",
   "files" : [
                {
                    "remote" : "my_file1.txt",
                },
                {
                    "remote" : "my_file2.txt",
                },
              ]
}

generates the following URLs for download:

http://myserver.com?file=my_file1.txt&user=name&pass=1234
http://myserver.com?file=my_file2.txt&user=name&pass=1234

Example

Save goHACK.me home page as 'goHACKme.html' on extended or bulk flash:

> http_download http://gohack.me goHACKme.html
Downloading: goHACKme.html to flash file system
Request GET /
Connecting (http): gohack.me:80
HTTP response: 301
Redirected to https://gohack.me
Request GET /
Connecting (https): gohack.me:443
Starting TLS
HTTP response: 200
Success
> ls -v
!  # Type  Flags  Hnd    Size    Version  Filename
...
# 19 e-FE   0021   10   13936    1.0.0.0  goHACKme.html
...

http_get

Abbreviation

hge

Description

Perform an HTTP(S) GET request and return a network stream handle if successful.

The protocol is assumed to be HTTP unless otherwise specified in the <url> parameter.

To allow custom headers, use the -o option.

Timeout is determined by tcp.client.connect_timeout.

Syntax

> http_get [-i <wlan/softap>] [-o] <url> [ca_cert_filename] where:

Options must be provided in the order shown.

Example

> hge https://www.google.com.au
[2014-04-02 | 13:27:20: Connecting: https://www.google.com.au]
Request GET /
Connecting (HTTP): www.google.com.au:443
Starting TLS
[2014-04-02 | 13:27:21: Connected: 0]
HTTP response: 200
Status: 200
0
> hge -o example.com:80
[2014-04-11 | 10:48:25: Opening: example.com:80]
Request GET /
Connecting (HTTP): example.com:80
[2014-04-11 | 10:48:25: Opened: 1]
1

http_head

Abbreviation

hhe

Description

Perform an HTTP(S) HEAD request and return a network stream handle if successful.

The protocol is assumed to be HTTP unless otherwise specified in the <url> parameter.

To allow custom headers, use the -o option.

Timeout is determined by tcp.client.connect_timeout.

Syntax

> http_head [-i <wlan/softap>] -o <url> [ca_cert_filename] where:

Options must be provided in the order shown.

Example

> hhe ack.me
[2014-04-02 | 13:32:28: Connecting: ack.me]
Request HEAD /
Connecting (HTTP): ack.me:80
[2014-04-02 | 13:32:29: Connected: 0]
HTTP response: 200
Status: 200
0

http_post

Abbreviation

hpo

Description

Perform an HTTP(S) POST request and return a network stream handle if successful.

The protocol is assumed to be HTTP unless otherwise specified in the <url> parameter.

To allow custom headers, use the -o option.

The HTTP Content-type must be provided.

Timeout is determined by tcp.client.connect_timeout.

Syntax

> http_post [-i <wlan/softap>] -o <url> <content type> [ca_cert_filename] where:

Options must be provided in the order shown.

Example

> hpo http://example.com application/json
[2014-04-02 | 13:35:19: Connecting: http://example.com]
Request POST /
Connecting (HTTP): example.com:80
[2014-04-02 | 13:35:20: Connected: 0]
HTTP response: 411
Status: 411
0
> hpo -o example.com:80 application/json
[2014-04-11 | 10:45:50: Opening: example.com:80]
Request POST /
Connecting (HTTP): example.com:80
[2014-04-11 | 10:45:50: Opened: 1]
1

http_read_status

Abbreviation

hre

Description

Read the HTTP response code returned by the last HTTP transaction on the stream specified by <handle>. If the HTTP request is pending and the transaction is incomplete, http_read_status sends the request and forces completion.

Syntax

> http_read_status <handle>

Example

> hre 1
411

http_upload

Abbreviation

hup

Description

Upload file(s) from the device flash to a remote HTTP server using HTTP POST and file upload.

Timeout is determined by tcp.client.connect_timeout.

Syntax

Upload a Single File

> http_upload [-i <softap/wlan>] <url>  <local filename>
  [<remote filename> [<content type> [<cert filename>]]]

where:

• -i - optional, specify interface, value 'wlan' or 'softap' MUST come first. If omitted uses network.default_interface.
• <url> - URL of remote HTTP server
• <local filename> - name of file on sflash to upload
• <remote filename> - optional, name of file on remote server, use local filename if omitted.
• <content type> - optional, HTTP header content-type, e.g. image/jpeg
• <cert filename> - name of certificate on local serial flash

Upload Multiple Files using JSON Manifest > http_upload [-i <softap/wlan>] -m <json size> where:

• -i - optional, specify interface, value 'wlan' or 'softap' MUST come first
• -m - use JSON manifest for multi-file upload. MUST come first if -i option not used

The manifest must be input directly after the command is issued. Manifest format:

{
  "path" : "https://myserver.com/path/to/save/files",
  "cert" : "mycert.pem", // existing TLS on local sflash
  "files" : [ {
    "local"  : "my_file_to_load.txt",
    "remote" : "file_name_on_server.txt",   // optional
    "name"   : "file",                      // optional
    "type"   : "application/octet-stream",  // optional
    },
    { ... }
  ]
}

Defaults for optional properties are:

• "remote" - The name of the file on the local file system.
• "name" - Populated in the 'name' field of form-data, the default is "file"
• "type" - "application/octet-stream"

Example

> hup http://myserver.com/uploadpage ghm_capabilities.json testfile.json
Uploading: ghm_capabilities.json to server
Request POST /uploadpage
Connecting (http): myserver.com:80
HTTP response: 200
Success

The file is saved on the upload server at myserver.com:80 as testfile.json

L

ls

Abbreviation

ls

Description

Return a list of available files located in internal, extended and bulk flash. Use the -v (or equivalent -l) option for full details.

Syntax

> ls [-v | -l]

Example

> ls -l
R000717
!  # Type  Flags  Hnd    Size      Version  Filename
#  0 i-00   801B    0  212736      2.1.0.0  upgrade_app.exe
#  1 i-81   801B   52  214776      2.1.0.0  wiconnect.exe
#  2 e-FB   0001   75   36578      2.1.0.0  command_help.csv
#  3 e-FD   0001   53     135      2.1.0.0  default_setup.script
#  4 e-FE   0001   74    1897      2.1.0.0  favicon.ico.gz
#  5 e-03   0001   52    1236      2.1.0.0  geotrust_ca.pem
#  6 e-FE   0021   84     422      1.0.0.0  thermistor.csv
#  7 e-FE   0001   55   20250      2.1.0.0  wiconnect_webgui.css.gz
#  8 e-FE   0001   54    1741      2.1.0.0  wiconnect_webgui.html
#  9 e-FE   0001   60   56176      2.1.0.0  wiconnect_webgui.js.gz
# 10 e-01   0009    0  210412  5.26.230.12  wifi_fw.bin

load

Abbreviation

load

Description

Load a configuration from a file previously saved by the save command.

Syntax

> load <config_file>

Example

> load config1.cfg
> Configuration successfully loaded

M

mdns_discover

Abbreviation

mdns

Description

Discover mDNS services on the local network. See variables mdns.enabled, mdns.interface, mdns.name, mdns.service, mdns.ttl

Syntax

> mdns_discover [-v] [<service type>]

where:

• -v - optional, verbosely print the results
• <service type> - optional, a specific service type to discover (e.g. _http._tcp). If omitted, all found services are returned.

Example

> set wlan.ssid ackme
Set OK
> set wlan.passkey secretkey
Set OK
> set mdns.enabled 1
Set OK
> mdns_discover
[Associating to ackme]
Security type from probe: WPA2-AES
Obtaining IPv4 address via DHCP
IPv4 address: 10.5.6.115
Starting mDNS
mDNS domain: wiconnect-102f1a.local
[Associated]
Services found: 4
Service: _csco-api._tcp.local
Name: _jenkins._tcp.local

Service: _https._tcp.local
Name: _workstation._tcp.local

Service: _http._tcp.local
Name: _http._tcp.local

Service: _csco-sb._tcp.local
Name: routera296b6._csco-api._tcp.local
Server: routera296b6._csco-api._tcp.local
Address: 10.5.6.1

N

network_down

Abbreviation

ndo

Description

Bring down a network interface. If provided, the network interface overrides the default specified by the variable network.default_interface. All open streams on the interface will be closed.

Syntax

> network_down [-i <wlan/softap>]

Example

> ndo
L000040
[2014-03-24 | 00:08:48: Disassociated]
R000009
Success

network_lookup

Abbreviation

nlo

Description

Perform a DNS lookup for a domain using the wlan interface.

Syntax

> network_lookup

Example

> nlo google.com
R000016
216.58.220.142

network_up

Abbreviation

nup

Description

Start the process to bring up a network interface. The -s option prompts the user to select from a list of available APs. The -i option overrides the default network interface specified by network.default_interface.

NOTE! Every command that needs access to the network will automatically bring up the network interface. The network_up command is non-blocking (except when the -s option is used) and provided for convenience only.

Syntax

> network_up [<-s> / <-i [wlan]/[softap]>]

Example

> network_up -s
Scanning for networks...
! 3 networks found
!  # Ch RSSI MAC (BSSID)       Network (SSID)
#  0  6  -27 84:1B:5E:29:9D:F7 Take the blue pill
#  1 11  -68 EC:1A:59:36:5B:6C button_xt
#  2 11  -70 2C:B0:5D:31:6F:6A button

Type the number # that matches your Network: 0
Type the password for your Network         : welcome-to-kansas
[Associating to Take the blue pill]
In progress
[Associated]

network_verify

Abbreviation

nve

Description

Verify the module can connect to a Wi-Fi network with specific network credentials. This command provides a fast way test the network credentials entered by a user are valid when web setup with softAP is operational, see Configuration & Setup, Web Setup. At present, only the Wi-Fi credentials are verified. No attempt is made to verify whether the module can obtain an IP address using DHCP.

The network verify command can also be used to quickly test network credentials at any time, however if the module is already connected to a network on the wlan client interface, it will be automatically disconnected from that network first.

If the verification attempt is unsuccessful, the command responds with Timeout. Verification may be unsuccessful if either the credentials provided are incorrect, or the verification attempt takes longer than 1 second.

Notes

• The wlan_scan -v command returns detailed information (including the BSSID, AP channel and security type) of Wi-Fi APs in range. A relevant subset of this information may be passed to the network_verify command.
• For WPA/WPA2, the PSK/PMK is calculated by applying the PBKDF2 key derivation function to the WPA/WPA2 passphrase using the SSID as the salt and 4096 iterations of HMAC-SHA1, see here for additional information.

Syntax

> network_verify wifi <ssid> <bssid> <ap channel> [<security> <psk>] where:

• <ssid> - the name of the Wi-Fi network
• <bssid> - the MAC address of the Wi-Fi Access Point (colons in the MAC are optional)
• <ap channel> - the radio channel of the AP
• <security> - an enumeration of the security type used by the AP:
  • 1 = WEP
  • 2 = WPA-AES
  • 3 = WPA-TKIP
  • 4 = WPA2-AES
  • 5 = WPA2-Mixed
  • 6 = WPA2-TKIP
• <psk> - 64 hex character pre-shared key (aka PMK) for WPA/WPA2 or WEP key

Example (Open Security)

> network_verify wifi mynetwork 4C55CC102F1A 1
Success

Example (WEP40 Security)

> network_verify wifi mynetwork 4C55CC102F1A 1 1 1122334455
Success

Example (WPA/WPA2 Security)

> network_verify wifi mynetwork 4C55CC102F1A 1 4 1205089613366e362586ee5f9ac8f485188fb0bdab30f2f1c23295eb863122de
Success

ota

Abbreviation

ota

Description

Initiate a secure over-the-air update using the ota server specified by the variables ota.host, ota.port. The secure OTA protocol uses industry standard TLS/HTTPS security with both client-side and server-side certificate verification. As an additional measure of security, the server authenticates each device using the universally unique system.uuid embedded inside the hardware of each device.\

Optionally force an update with the -f option. Download a specific firmware bundle version with the -b option.

To activate a module to receive custom firmware & files, use the -a option along with your activation code and password. All modules are activated and licensed for standard WiConnect firmware. If you have firmware customised by ACKme for your application, or you would like ACKme to manage your host firmware or host application files on our secure servers, please contact ACKme to receive an activation code and password.

To maintain a saved configuration through an OTA upgrade, save the configuration as default_config.csv. See save.

Syntax

> ota [-f] [-b <bundle name>] [-a <activation code> <password>]

Example

> ota
Connecting to network
Request POST /ota/05b320df003134534e394b8330333231323a3533/0
Connecting (HTTP): ota.ack.me:443
Starting TLS
HTTP response: 200
Downloading new firmware...
Bundle version: wiconnect-1.0.0.1, Built:2014-04-02 02:23:15 for AMW004.3
Downloading: command_help.csv-1.0.0.1 (25822, 0xFB, 0x1)
Downloading: default_setup.script-1.0.0.1 (189, 0xFD, 0x9)
Downloading: /setup/index.html-1.0.0.1 (9266, 0xFE, 0x1)
Downloading: /setup/images.png-1.0.0.1 (18067, 0xFE, 0x1)
Downloading: upgrade_app.exe-1.0.0.1 (352804, 0x0, 0x801F)
Downloading: wifi_fw.bin-1.0.0.1 (191677, 0x1, 0x8009)
Downloading: wiconnect.exe-1.0.0.1 (83848, 0x80, 0x801F)
Downloading: geotrust_ca.pem-1.0.0.1 (1162, 0x3, 0x9)
Downloading: /favicon.ico.gz-1.0.0.1 (1853, 0xFE, 0x1)
Downloading: /setup/index.css.gz-1.0.0.1 (10539, 0xFE, 0x1)
Downloading: /setup/index.js.gz-1.0.0.1 (38771, 0xFE, 0x1)
Updating Upgrade App to version: 1.0.0.1
Updating firmware files...
Updating file: wifi_fw.bin to version: 1.0.0.1
Updating file: wiconnect.exe to version: 1.0.0.1
Found new bootable app: wiconnect.exe (47), booting to it now!
OTA completed successfully
[Ready]

P

ping

Abbreviation

ping

Description

Send one or more ICMP pings to an IP address or the network gateway using the -g option. If provided, the network interface overrides the default specified by the variable network.default_interface. Options must be provided in the order shown.

Syntax

> ping [-i <wlan/softap>] <[IP address]/[-g]> [# retries]

Example

> ping example.com 3
R000021
Ping reply in 183ms
R000021
Ping reply in 178ms
R000021
Ping reply in 177ms

pwm_update

Abbreviation

pwm

Description

Drive a GPIO with a pulse width modulated signal with duty_cycle in the range 0-100%. The PWM frequency has a module-dependent default and may be optionally set with the frequency option. Use the stop option to turn the PWM off.

See Peripherals, PWMs for frequency defaults and PWM groups for each module. GPIOs in the same PWM group cannot be used independently at the same time.

Syntax

> pwm <GPIO#> <duty_cycle / stop> [frequency]

Example

> pwm_update 10 30
R000009
Success

R

reboot

Abbreviation

reboot

Description

Reboot the application.

Syntax

> reboot

Example

> reboot
R000082
wiconnect-1.0.0.1, Built:2014-04-02 02:23:15 for AMW004.3, Board: AMW004.3-E03.1

S

save

Abbreviation

save

Description

Save all WiConnect variables to non-volatile flash memory.
If a file name is supplied, the saved configuration can be restored with the load command.
Save as default_config.csv to create a default settings file. If a file of this name is found, WiConnect loads the configuration in default_config.csv after a successful OTA or if the factory reset GPIO is asserted for more than 5 seconds but less than 10 seconds. See Upgrade and Recovery, Factory Reset.

Syntax

> save [<config_file>]

Example

> save
L000007
Saved
R000009
Success

Example 2

save config1.cfg
R000009
Success
ls
!  #   Size   Version  Filename
...
#  5   3868     1.0.0  config1.cfg
...

set

Abbreviation

set

Description

Set the value of a WiConnect variable.

Syntax

> set <variable> <args>

Note: The set command displays the Too many args error only if the number of space-separated arguments exceeds the maximum for all variables (5). However the number of arguments for the set command depends on the variable being set, and the form in which the variable is specified: abbreviations for variables vary from one to three arguments in length, and variable settings may require one or two arguments. If you specify too many arguments when setting a specific variable, surplus arguments are ignored. Refer to the variable documentation for the number of arguments for a specific variable.

Example

> set wlan.ssid "My Home Network"
R000008
Set OK

setup

Abbreviation

setup

Description

The setup command simplifies the process of connecting an ACKme module to a Wi-Fi network. It can also be used to automate device configuration and setup.

The setup command allows for set up from the WiConnect terminal, using a command script, or via a web browser.

See Configuration and Setup, Configuration Script and Configuration and Setup, Setup with a Web Browser.

The setup command can be run automatically on boot or in response to asserting a GPIO. See Configuration and Setup, Automatically Executing a Script.

Syntax

> setup <web/status/stop/cmd [-v] [<script_file>]>

Example

> setup cmd
> Scan and select a network:
network_up -s
Scanning for networks...
! 4 networks found
! # Ch RSSI MAC (BSSID)       Network (SSID)
# 0 06  -35 84:1B:5E:29:9D:F7 GameOverMan
# 1 06  -88 28:C6:8E:70:93:18 Philips Home Network_EXT
# 2 11  -65 EC:1A:59:36:5B:6C laboite_xt
# 3 11  -73 2C:B0:5D:31:6F:6A laboite

Type the number # that matches your Network: 0
Type the password for your Network         : pullyourselftogetherhicks
[Associating to GameOverMan]
In progress
> Enabling network auto-join
set wlan.auto_join.enabled true
Set OK
> Saving settings
save
Saved
Success
> Security type from probe: WPA2-Mixed
Obtaining IPv4 address via DHCP
IPv4 address: 192.168.0.32
[Associated]
> Exiting Cmd Setup Mode

sleep

Abbreviation

sleep

Description

Put the application into a low-power sleep state. The application sleeps until the wakeup timeout (system.wakeup.timeout) expires or a wakeup event (system.wakeup.events) occurs.

Syntax

> sleep

Example

> set system.wakeup.events uart0|gpio5
Set OK
> set system.wakeup.timeout 10
Set OK
> sleep

... wait 10 seconds ...

wiconnect-1.1.1.0, Built:2014-04-02 02:23:15 for AMW004.3, Board:AMW004.3-E03.1

smtp_send

Abbreviation

smtp

Description

Send email to a specified email address. See SMTP variables:

• email.name_address
• email.smtp.host
• email.smtp.password
• email.smtp.port
• email.smtp.username Syntax

> smtp <to address> <subject> <content length>
[<content length> bytes of data ...]

where:

• <to address> - email address to send email to
• <subject> - the subject of the email, must be enclosed in double-quotes if spaces are used in the subject.
• <content length> - the length in bytes/characters of the email contents.

Immediately after issuing the command, <content length> characters of data should be sent. This is the body of the email.

Note that most SMTP servers require SSL/TLS encryption. Some servers, including gmail, use additional authentication methods like OAUTH by default. These additional authentication methods are not supported and may need to be disabled server-side.

Example

> smtp_send first.last@youremail.com "World greetings" 5
Hello
[Associating to MY_NETWORK]
Security type from probe: WPA2-AES
Obtaining IPv4 address via DHCP
IPv4 address: 10.5.6.59
[Associated]
Success

stream_close

Abbreviation

close

Description

Close an open network or file stream specified by [handle], or alternatively close all open streams.

Syntax

> stream_close <[handle]/[all]>

Example

> close all
[2014-04-02 | 13:32:04: Disconnected: 0]
[2014-04-02 | 13:32:04: Disconnected: 1]
Success

stream_list

Abbreviation

list

Description

Return a list of open streams.

Syntax

> stream_list

Example

> list
!# Type  Info
#0 TCPC  google.com:80 (32288)
#1 HTTP  ack.me:80 (37289)

stream_poll

Abbreviation

poll

Description

Poll a stream to check if data is available. Returns 0 if open with no data to read, 1 if data is available and 2 if the stream has been closed remotely. Use the all option to return the status of all open streams. To avoid polling, use a GPIO (may be assigned when the stream is opened) as an interrupt line to the host.

Syntax

> stream_poll [all] <handle>

Example

> poll 0
1
> read 0 100
hello!
> poll 0
0
> poll all
0,0|2,1|3,1

stream_read

Abbreviation

read

Description

Read up to <size> bytes from a network or file stream. Returns data immediately (if available), does not wait to receive data. For network streams, WiConnect may buffer up to seven packets with each packet containing up to 1440 (MTU) data bytes. To avoid receiving data fragmented across packets, <size> should be set to 1440 bytes. To check for data, use the stream_poll command or the GPIO (assigned when the stream was opened) as an interrupt line to the host. For file streams, the file is automatically closed if the end of file is reached.

Syntax

> stream_read <handle> <size>

Example

> read 0 200
R000202
<!doctype html><html itemscope="" itemtype="http://schema.org/WebPage"
 lang="en-AU"><head><meta content="/images/google_favicon_128.png"
itemprop="image"><title>Google</title><script>(function(){
wind

stream_write

Abbreviation

write

Description

Write data to a network or file stream. As described in Serial Interface, Command Format, the command must be terminated by \r\n. After issuing the command, WiConnect waits for <size> number of data bytes then immediately sends the data to the stream before returning a response.

Syntax

> stream_write <handle> <size>

Example

> write 3 10
Success

T

tcp_client

Abbreviation

tcpc

Description

Open a TCP stream to a remote server at the network location <host>:<port>. If provided, the network interface overrides the default specified by the variable network.default_interface, and GPIO# specifies which GPIO indicates buffered data is waiting to be read. Options must be provided in the order shown.

Timeout is determined by tcp.client.connect_timeout.

Syntax

> tcp_client [-i <wlan/softap>] [-g GPIO#] <host> <port>

Example

> tcpc google.com 80
L000028
Resolving host: google.com
L000052
[2014-03-24 | 01:07:12: Connecting: google.com:80]
L000036
Connecting (TCP): 74.125.237.96:80
L000039
[2014-03-24 | 01:07:12: Connected: 0]
R000003
0

tcp_server

Abbreviation

tcps

Description

Start/stop a TCP server specified by the variables tcp.server.*. If provided, the network interface and port override defaults specified by the variables network.default_interface and tcp.server.port respectively. Options must be provided in the order shown.

Syntax

> tcp_server [-i <wlan/softap>] <start/stop> [port]

Example

> tcps start
L000036
TCP server listening on port: 3000
R000009
Success

tls_client

Abbreviation

tlsc

Description

Open a secure TCP stream to a remote server at the network location <host>:<port>. If provided, the network interface and CA cert override defaults specified by the variables network.default_interface and network.ca_cert respectively. The optional GPIO# argument specifies which GPIO indicates buffered data is waiting to be read. Options must be provided in the order shown.

Timeout is determined by tcp.client.connect_timeout.

Syntax

> tls_client [-i <wlan/softap>] [-g GPIO#] <host> <port> [ca_cert_filename]

Example

> tlsc www.google.com 443
L000032
Resolving host: www.google.com
L000057
[2014-03-24 | 01:15:53: Connecting: www.google.com:443]
L000038
Connecting (TLS): 74.125.237.211:443
L000039
[2014-03-24 | 01:15:55: Connected: 1]
R000003
1

tls_server

Abbreviation

tlss

Description

Start/stop a TLS server on the specified port.
If starting the server and no port is specified, the default is the port specified by tcp_server_port.\ The server certificates must be pre-configured.

Syntax

tls_server <start/stop> [port]

Example

> tlss start 5000

U

udp_client

Abbreviation

udpc

Description

Open a UDP stream to a remote server at the network location <host>:<port>. If provided, the network interface overrides the default specified by the variable network.default_interface, and GPIO# specifies which GPIO indicates buffered data is waiting to be read. The [local port] may also be provided if desired. Options must be provided in the order shown.

Syntax

> udp_client [-i wlan/softap] [-g GPIO#] <host> <remote port> [local port]

Example

> udpc 192.168.45.67 3000
L000057
[2014-03-24 | 01:16:40: Connecting: 192.168.45.67:3000]
L000031
Resolving host: 192.168.45.67
L000032
Connecting: 192.168.45.67:3000
L000039
[2014-03-24 | 01:16:40: Connected: 2]
R000003
2

udp_server

Abbreviation

udps

Description

Start and stop the UDP server.
When the UDP server is started the read and write sub-commands are available.
When the UDP server is started, it is assigned a stream handle, indicated in the WiConnect response by Opened: <stream>. This allows for the equivalent stream 'read' and 'write' commands.
The read command is functionally the same as: udps read.
The write command is functionally the same as udps write without the <address> and <port> options.

Syntax

> udp_server <start/stop> [port] Start and stop the UDP server. Port may be optionally specified. If no port is specified the default is udp.server.port.
> udp_server read [-q] [<byte_count>] where :

• -q - optionally prepend the client's IP address and port before the data bytes, in a comma-separated list: ip,port,data

• <byte_count> - The number of bytes to read. Note that only a single packet's worth of data is returned
  i.e. data returned = MIN(<byte count>, len(packet))

  > udp_server write <byte_count> [<address> <port>] where :

• <byte_count> - the number of data bytes to write
• <address>, <port> - optional, the remote client's address and port. If omitted, write to last client whose data has been read.

Example

> udp_server start 5000
[2014-11-28 | 07:14:49: Opened: 0]
0
UDP server listening on port: 5000
Success
> udps stop
[2014-11-28 | 07:15:31: Closed: 0]
UDP server stopped
Success
> udp_server write 0 5
Hello
Success
> udp_server read
> udp_server read -q 100
10.5.6.60,52333,Hello World!
> write 0 8
Hi there
Success
> read 0

V

version

Abbreviation

ver

Description

Returns the WiConnect firmware bundle version. This is a convenience command that is equivalent to reading the system.version variable.

Syntax

version

Example

> ver
R000069
wiconnect.exe v1.0.0.0, Built:Apr 03 2014 for AMW004.3-E03.1

W

wlan_get_rssi

Abbreviation

rssi

Description

Get the received signal level (RSSI, in dBm) of the Access Point the wlan interface is connected to. The value is averaged to improve accuracy by setting the variable wlan.rssi_average.

Syntax

> wlan_get_rssi

Example

> rssi
R000005
-47

wlan_scan

Abbreviation

scan

Description

Initiate a Wi-Fi scan and return results; optionally specify a channel and AP SSID to scan for. For verbose scans, -v must be the first argument. Information returned by scan results is described in the following table.

Syntax

> wlan_scan [-v] [<channel> [ssid]]

Example

> scan -v
R000196
! 2 found
! # Ch RSSI BSSID              Rate Security Mode Len SSID
# 0 01  -24 EC:1A:59:36:5B:6C 144.4 Open      Inf  13 Ch1_Nearby_AP
# 1 06  -85 84:1B:5E:29:9D:F7 450.0 WPA2-AES   Ad  14 Ch6_Distant_AP

wps

Abbreviation

wps

Description

Runs Wi-Fi Protected Setup (WPS) to enable the wlan interface to connect with an Access Point. PIN and push-button (PBC) modes are supported, PBC mode is default. To specify a timeout for PBC mode, use \0 as the first argument.

Syntax

> wps [<PIN code>/<\0>] [timeout in seconds] [stop]

Example

> wps
L000023
Starting WPS PBC mode
R000013
In progress