Configuration and Setup

Setup, in its simplest form, is Wi-Fi Setup, also called Wi-Fi provisioning: providing WiConnect with your network ssid and passkey. Once these details are provided, WiConnect automatically brings the network up when it is required by any WiConnect activity.

Setup may also involve Variable Configuration and GPIO Configuration.

To configure your own version of the WiConnect Web App, see Customizing the WiConnect Web App.

Some of the procedures described below use a WiConnect terminal. Connecting a terminal is described in Getting Started.

Wi-Fi Setup

A number of flexible and easy-to-use options are available to set up a module running WiConnect.

WiConnect is so easy to setup, we bet that within just a couple of minutes after plugging your evaluation board in, you'll be connected to a Wi-Fi network. Why not try it right now? With just four WiConnect commands, you can connect to the Internet and download information! Enter the following commands into a WiConnect terminal, substituting the name and password for your access point:

WiConnect Commands Description

set wlan.ssid     "Your AP Name"
set wlan.passkey  "Your secret password"

http_get          https://google.com

stream_read       0 1000


<- Name of your Access Point
<- Password for your Access Point

<- Sample information: get the home page
   from the Google secure web address 
<- Read 1000-bytes of the sample

The setup steps are the first two lines of the example above - connecting to your local Wi-Fi Access Point. For further quick start information see Getting Started.

Setup with a Web browser

WiConnect provides the option to use a web browser running on a network client (such as a smartphone, tablet or computer) to set the wlan_ssid and wlan_passkey. \

In web setup mode, the ACKme module starts a soft AP and an HTTP server. The network client joins the module network via the soft AP and loads a set up page running on the WiConnect HTTP server.

Starting Web Setup Mode on an ACKme Evaluation Board

On an ACKme evaluation board in the factory default state, you can start web setup mode without connecting via a terminal: hold down Button 2, press Reset, and continue to hold down Button 2 for another three seconds. The evaluation board red LED flashes to indicate the WiConnect soft AP is running. See Initiating Setup by GPIO.

Starting Web Setup Mode from a WiConnect Terminal

Alternatively, to start web setup mode, connect via a terminal and enter the command setup web.

WiConnect starts the local network and web server as indicated by the final message: In progress.

> setup web
[Disassociated]
IPv4 address: 10.10.10.1
Web setup started with the SSID: "WiConnect-###"
In progress

Opening the Web Setup Page

Open the Wi-Fi settings on your smartphone, tablet or computer and join the network called Wiconnect-###. The ### represents a unique ID derived from the last 3 characters of the module MAC address, e.g. WiConnect-2D6 for a module with MAC address 4C:55:CC:10:32:D6. The password for the network is simply: password.

The local network name and password, and the web address may be customised to suit your needs. See setup.web.ssid, setup.web.passkey and setup.web.url.

After joining the local network, open a web browser on the network client and direct the browser to setup.com. The WiConnect web page appears, and a scan begins for Wi-Fi access points in range. Select the remote network you wish to join, enter the network password then select Save & Exit and follow the prompts.

Once the settings are successfully saved, WiConnect prints Web Setup Mode exited to the terminal. You can check that the settings were successfully saved using get wlan.ssid and get wlan.passkey.

Web Setup Mode exited
> get wlan.ssid
YOUR_NETWORK_NAME
> get wlan.passkey
YOUR_NETWORK_PASSWORD

Web Setup Timeout

Web Setup times out after a period of user inactivity. If after web setup starts, the user does not open the web page, WiConnect exits setup mode after five minutes. If after opening the page the user does not click any button on the web page for five minutes, the setup web page displays a warning message. If there is no activity for 60 seconds after the message is displayed, the web page exits and web setup stops.

Setup by WiConnect Terminal

Perhaps the most common option used for general setup (and also the most convenient when prototyping) is to use a WiConnect terminal and set variables using WiConnect commands. See Getting Started.

It is straightforward to set the wlan.ssid and wlan.passkey variables manually. Be sure to save afterwards, or the values will be lost when the module reboots. 

> set wlan.ssid YOUR_NETWORK_NAME
Set OK
> set wlan.passkey YOUR_NETWORK_PASSWORD
Set OK
> save
Saved
Success

Any subsequent command requiring network access, such as an ICMP (Internet Control Message Protocol) ping, automatically results in the module attempting to join the network. 

> ping -g
[Associating to YOUR_NETWORK_NAME]
Security type from probe: WPA2-Mixed
Obtaining IPv4 address via DHCP
IPv4 address: 192.168.0.31
[Associated]
Ping reply in 25ms

Network Setup Option

The network_up command provides a -s option that prompts for the network and passkey. This simplifies the process by scanning for networks and allowing the desired network to be selected by index number, e.g.:

> nup -s
Scanning for networks...
! 5 networks found
!  # Ch RSSI MAC (BSSID)       Network (SSID)
#  0  1  -78 00:0E:E8:B2:FE:FC someone-else
#  1  1  -79 18:33:9D:5F:9E:F3 another-network
#  2  6  -53 84:1B:5E:D8:0F:18 ackme_EXT
#  3  6  -28 30:85:A9:E7:9C:B0 ackme
#  4 11  -84 58:BF:EA:D8:C9:D2 not_us

Type the number # that matches your Network: 3
Type the password for your Network         : <passkey>

After running nup -s you may want to set wlan.auto-join.enabled. Save the variables if you want them to persist through a reboot:

> set wlan.auto_join.enabled 1
Set OK
> save
Saved
Success

Setup by Remote Terminal

An (optionally) password-secured remote terminal provides command line setup convenience (look ma, no wires!) via one of the WiConnect wireless network interfaces. See Application Examples - Remote Terminal. After connecting to the ACKme device via a remote terminal, follow the procedure described above in Setup by WiConnect Terminal.

Initiating Setup by GPIO

Setup can be triggered by changing the level of a specified GPIO. See Automatically Executing a Script.

If setup.gpio.mode is set to gpio, and the GPIO specified by setup.gpio.control_gpio is held to the level specified by setup.gpio.level for 3 seconds during and immediately after reset, then the command specified by setup.gpio.cmd is run.

On ACKme WiConnect evaluation boards, the default factory configuration is:

VariableValue
setup.gpio.control_gpioGPIO corresponding to Button 2: Wallaby: GPIO11, Numbat: GPIO22
setup.gpio.cmdsetup web
setup.gpio.level1
setup.gpio.modegpio

Accordingly, on a default configuration eval board, hold down Button 2, press reset, and continue to hold Button 2 for three seconds to start web setup.

Web Setup Note: On some WiConnect evaluation boards, the web setup GPIO configuration to Button 2 to is lost after a hardware factory_reset using Button 1. In this case use the setup web command to enter web setup mode, or use another configuration method.

Initiating Setup on Boot

Set the value of setup.auto.cmd to the required setup cmd. See Automatically Executing a Script.

Setup by WPS Push-button or PIN

WPS is a Wi-Fi provisioning method originally intended to simplify the process of connecting Wi-Fi clients to Wi-Fi Access Points. WPS offers both a push-button and PIN entry method for configuration. In reality, WPS push-button (as opposed to PIN) is the only method that has gained some level of adoption in the industry, however WPS naturally only works when the Wi-Fi AP supports WPS. Many AP vendors choose not to test and certify APs with the Wi-Fi Alliance, and the lack of a standard WPS logo next to the WPS button on an AP often means many users are unaware that WPS is available. The potential for equipment incompatibility and added user confusion mean it is unwise to rely on WPS as the primary method of Wi-Fi provisioning in the real world. \ Incompatibility and confusion aside, WiConnect provides full support for WPS1.0 & WPS2.0 and the underlying WPS engine has passed Wi-Fi certification. To use WPS in push-button mode, simply enter the wps command into WiConnect, then press the WPS button on your router (if the router supports WPS, and it is enabled, and you can find the button), and wait for the magic to happen.

Setup Configuration Script

A custom configuration script can be set up to execute on boot-up. WiConnect provides a default setup script to step you through the process. The setup script is provided as a file called default_setup.script on the WiConnect file system. The setup script may be customised as required. See Script Format. You can also create your own configuration script and supply the filename as an argument: setup cmd .

For example, the default_setup.script file contents are as follows:

network_up,-s,Configuration network credentials
set wlan.auto_join.enabled,true,Enable network auto-join
save,-,Saving settings

On running the default_setup.script, the output is similar to the following:

> setup cmd
Running setup script: default_setup.script
In progress
> Configuration network credentials
network_up -s
Scanning for networks...
! 9 networks found
!  # Ch RSSI MAC (BSSID)       Network (SSID)
#  0  1  -77 18:33:9D:5F:9E:F2 Some AP
#  1  1  -79 18:33:9D:5F:9E:F4 Another AP
#  2  6  -31 30:85:A9:E7:9C:B0 ackme
#  3  6  -66 E8:08:8B:CA:4A:CC Yet Another AP

Type the number # that matches your Network: 2
Type the password for your Network         : secret_passkey
[Associating to ackme]
> In progress
Enable network auto-join
set wlan.auto_join.enabled true
Set OK
Saving settings
save
Saved
Success
Script executed successfully

Automatically Executing a Script

On Boot

To automatically execute a script on booting an unconfigured module, set the value of setup.auto.cmd to the required setup cmd, e.g. set setup.auto.cmd "setup cmd my.script"

Note: The "setup cmd" value must be enclosed in double quotes because it contains spaces.

On GPIO Assertion or Reboot

To execute a script in response to a reboot, or a GPIO being asserted, set the value of setup.gpio.cmd, e.g. set setup.gpio.cmd "setup cmd my.script.txt" In addition, set the required setup.gpio.control_gpio and setup.gpio.mode.

Displaying Comments and Command Output

To display comments and command output, add the -v option after the setup cmd, e.g. set setup.gpio.cmd "setup cmd -v my.script" See setup cmd.

Script Format

The configuration script is in .csv format. Each line represents a command, in the form: <command>,<arguments>,<comment>

The maximum line length of any line in a setup script is 128 characters (including \r\n).

You can create complex scripts, that run other commands to perform actions such as GPIO configuration. For example, here is part of a goHACK.me setup script:

,,--------------------------------------------- Free up GPIOs
set  ,gpio.init  0 none                        ,\r\n# Free up GPIO configured for user button 1
set  ,gpio.init 22 none                        ,\r\n# Free up GPIO configured for user button 2
set  ,gpio.init 16 none                        ,\r\n# Free up GPIO configured for user LED 1
set  ,gpio.init 13 none                        ,\r\n# Free up GPIO configured for user LED 2
set  ,ghm.solo.gpio all none                   ,\r\n# Free previously configured goHACK.me GPIOs
,,--------------------------------------------- Streams
set  ,ghm.solo.gpio  0 button1 in rising       ,\r\n# Setup Button 1 on GPIO 22 for use with goHACK.me
set  ,ghm.solo.gpio 22 button2 in rising       ,\r\n# Setup Button 2 on GPIO 18 for use with goHACK.me
set  ,ghm.solo.gpio 20 thermistor adc          ,\r\n# Setup Thermistor on GPIO 20 for use with goHACK.me
,,set  ,ghm.solo.gpio 23 gpio23 inpd             ,\r\n# Setup GPIO23 for use with goHACK.me

The comment is printed before the corresponding command is executed.

The comment fields in the above example contain \r\n# characters for formatting purposes only. The effect is to skip a line then print the # character before the text of the comment.

Note: To comment out a line completely, insert two commas at the beginning of the line. See examples above.

Note: Each line of the script is terminated by \r\n ().

Write the script to the WiConnect file system. See Writing Files to the File System.

Now you can run the script as follows:

setup cmd -v test.script

The -v option results in a verbose display of comments and commands in the script:

> setup cmd -v test.script
Running setup script: test.script
In progress
>
#This is a comment
help setup
Usage   : setup <web / status / stop / cmd [script]>
Shortcut: setup
Brief   : Use setup mode to enable device configuration with a softAP and webserver
or a command prompt. Configure the softAP using the setup.web.* variables.
The cmd option runs the default_setup.script on the filesystem, or the [script] specified.
Script executed successfully

Variable Configuration

Variable values are stored in a user variable value storage structure called the Device Configuration Table (DCT). DCT RAM contains the current values of variables. You can save the DCT RAM to DCT flash, so that variable values persist after reboot, with the save command. When you reboot, the module loads the configuration from DCT flash into DCT RAM. There is a single DCT flash area.

In case there is damage to DCT flash, certain critical variable values are backed up in DCT backup. See DCT Backup Variables below for a list of critical variables.

You can save DCT RAM to a file by specifying a configuration filename with the save command, e.g.: save config1.cfg

To store multiple configurations, save multiple files.

You can load a specified variable configuration file with the load command after reboot is complete, e.g.: load config1.cfg

You can save a default variable configuration by saving a file with the name default_config.csv: save default_config.csv

The default variable configuration is loaded in response to a User Factory Reset (see below).

Platform-specific variable values are stored in OTP (One-Time Programmable) memory. For example, settings related to the antennas, buttons or indicator LEDs on Mackerel or Moray evaluation boards are stored in OTP memory.

To summarise, variable values are stored in several places:

Factory Default ValuesStored in firmware
DCT RAMStores current variable values
DCT FlashSaved variable values
DCT BackupBackup of critical variable values
OTP memoryPlatform-specific variable values
Variable filesSnapshot of DCT RAM

Variable values are restored from these storage locations as described below in Resetting Variable Values.

Resetting Variable Values

There are several kinds of reset that affect the value of variables.

Powerup or Reboot

To restore variable values on restart, WiConnect:

Hard Factory Reset

A hard factory reset returns all values to their original default values. This is under user control. To perform a hard factory reset:

either

The factory_reset command requires a MAC address in order to avoid accidental reset. The MAC address can be obtained from the wlan.mac variable.

To restore variable values, WiConnect:

Soft Factory Reset

A soft factory reset restores the DCT from DCT backup. This happens automatically if the DCT is corrupted.

To restore variable values, WiConnect:

User Factory Reset

A user factory reset restores the DCT from DCT backup. This is under user control. To perform a user factory reset:

either

To restore variable values, WiConnect:

Note: The effect of a soft factory reset and a user factory reset is the same. They differ only in how they are invoked.

Load User Settings

This reset takes place when the load command is issued.

The following steps take place, in the following order. WiConnect:

DCT Backup Variables

The values of the following critical user variables are saved in DCT backup, in case there is some damage to DCT flash:

GPIO Configuration

GPIOs are configured in the factory default variable configuration. You can use GPIO commands and variables to configure GPIOs. See Peripherals, GPIO Commands and Variables. It is also possible to use a csv file to configure and initialize GPIOs on bootup.

Using a GPIO Configuration File

The file name is set with the gpio.config_file variable. On some boards a default GPIO configuration script is provided with the filename gpio_config_init.csv.

The GPIO config file format consists of lines, each of which configures a GPIO. The file is of the form:

GPIO#,Alias1,Function1,Initialization1
GPIO#,Alias2,Function2,Initialization2
GPIO#,Alias3,Function3,Initialization3
...

where:

Standard GPIO Functions

Sleep State

To set the sleep state in the gpio config file add the | in the gpio function column.

For example:

Set GPIO 0 with gpio.alias = "reset", gpio.init = "input_pull_down", gpio.sleep = "input_highz":

0,reset,input_pull_down|input_highz

See the gpio.sleep variable description for state options.

Alternative GPIO Functions

System Indicator State Options

State NameBlink PeriodBlink Frequency
static_on--
static_off--
slow_blinkT=2sf=0.5Hz
medium_blinkT=1sf=1Hz
fast_blinkT=0.250sf=4Hz

Example GPIO config file

10,grn,system.indicator.wlan,static_off|fast_blink|medium_blink
11,yel,system.indicator.network,fast_blink|medium_blink|slow_blink
0,red,system.indicator.softap,static_off|fast_blink|medium_blink
4,button1,input_pull_up,
3,button2,input_pull_up,
1,network_status,network.status_gpio,
2,io_status,ioconn.status_gpio,
5,alias_only,,
8,output_high,output,1ds
7,,output,0

goHACKme Solo Functions

See ghm.solo.gpio variable documentation.

Other than the GPIO# parameter, each parameter for the set command is concatenated with a | character. For example, the following commands:

set   ghm.solo.gpio 13 led2-duty pwm led2-freq
set   ghm.solo.gpio 20 thermistor adc therm_celsius_lut.csv
set   ghm.solo.gpio 21 gpio21 input_pd

correspond to the following entries in the gpio_config.csv file:

13,,ghm.solo.gpio,led2-duty|pwm|led2-freq
20,,ghm.solo.gpio,thermistor|adc|therm_celsius_lut.csv
21,,ghm.solo.gpio,gpio21|input_pd

System Activity Function

Other than the GPIO parameter, each parameter for the set command is concatenated with a | character. For example, the following commands:

set system.activity.gpio 10 wlan_rx,wlan_tx
set system.activity.gpio 11 uart1_rx,uart1_tx

correspond to the following entries in the gpio_config.csv file:

10,,system.activity.gpio,wlan_rx|wlan_tx
11,,system.activity.gpio,uart1_rx|uart1_tx