Wi-Fi and Ethernet Interfaces

There are two Wi-Fi interfaces available for use with Gecko OS, a wlan client (802.11 STA) interface and a softAP (802.11 AP) interface.

Both interfaces share the same physical Wi-Fi radio and antennas.

To set 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 Interface

The wlan client interface enables Gecko OS 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. These interfaces share the Wi-Fi radio, so when operating concurrently it is recommended that they use the same channel, for optimum throughput and reliability.

Gecko OS provides various commands and variables to configure the WLAN interface.

See the documentation for wlan commands and wlan variables .

An overview of WLAN functionality is provided in the following sections.

Scanning for Networks

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

Each of the parameters discussed in the preceding paragraph (plus more) are configurable with Gecko OS. 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 each channel, in active and passive scan mode respectively, is configurable using the wlan.scan.active_dwell and wlan.scan.passive_dwell variables. In active mode, the number of 802.11 probe requests is configurable using wlan.scan.num_probes .

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

WLAN Security Type

Gecko OS supports SOHO security types including Open, WEP, WPA & WPA2, and WPA2 mixed mode.

The wlan.security variable sets security type. The default value is Auto : Gecko OS determines security type automatically, from the network you are attempting to join. If you are planning to use WEP (and we sincerely 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 name and network password the module is attempting to join. You can do this by setting the values of the variables 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 of join 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 passkey is hidden, it is no longer possible to read the passkey until a factory reset is performed. This stops an attacker learning the network password by physically acquiring a product with a Gecko OS device.

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

Once the module is joined to a Wi-Fi network, the received signal strength (signal level) of the Wi-Fi Access 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 module attempts to scan for (and roam to) another known network in range. The received signal level at which roaming 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, it may be necessary to modify one or more of the wlan scan variables discussed in the Scanning for Networks section to minimize packet loss during roaming.

Access Point (SoftAP) Interface

The softAP interface enables a Wi-Fi client such as a notebook, smartphone or tablet to join with Gecko OS.

SoftAP OUI

The SoftAP Organizationally Unique Identifier is related to the WLAN interface MAC address.

The SoftAP address is more correctly called an Organizationally Unique Identifier (OUI), but has the same format as a MAC address.

To see the WLAN MAC address, issue the command:

get wlan.mac

Calculate the SoftAP OUI from the MAC as follows:

SoftAP_OUI = WLAN_MAC OR 0x200000

That is, the SoftAP OUI is obtained from the WLAN MAC address by setting the second-least significant bit of the first octet of the address.

See Wikipedia MAC Address details for more information: https://en.wikipedia.org/wiki/MAC_address#Address_details .

SoftAP Features and Variables

It is possible to use the WLAN and softAP interfaces concurrently. These interfaces share the Wi-Fi radio, so for optimum throughput and reliability it is recommended that they use the same channel. However WLAN and SoftAP can work concurrently on different channels.

The softAP interface is primarily controlled with the softap variables , grouped below according to SoftAP features:

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

SoftAP MAC Filter

The softAP MAC filter allows MAC addresses to be whitelisted or blacklisted for connection to the softAP.

Enable or disable the filter with the softap.mac_filter.enabled variable.

Display current settings with the softap.mac_filter.info variable.

Choose whitelist or blacklist mode with the softap.mac_filter.mode variable. Whitelist mode allows connection by the specified MAC addresses, and excludes others. Blacklist mode prevents connection by the specified MAC addresses, and allows others.

Manage the filter MAC addresses list with the softap_mac_filter_add , softap_mac_filter_clear and softap_mac_filter_remove commands.

Note : The softAP MAC filter, including the list of whitelisted or blacklisted MAC addresses, must be configured before the softAP interface is brought up. The filter cannot be altered dynamically while the softAP interface is running.

Commands :

Variables :

Native C Interface APIs :

Network Bridge

The Network Bridge feature allows data streaming between network interfaces.

Currently it supports the ethernet and softap interfaces. This allows streaming between an Ethernet connection and the device Soft Access Point. Inbound Ethernet packets become outbound Wi-Fi packets on the softAP interface. Input Wi-Fi packets on the softAP interface become outbound Ethernet packets on the Ethernet interface.

The Gecko OS network stack is disabled in Network Bridge mode. Only the device softAP appears on the network. The device does not have an IP address and is not be able to receive or initiate network traffic.

The Network Bridge can be started and stopped by command, or started automatically on boot.

You can control the devices connecting to the softAP interface using the softAP MAC filter .

The command API continues to operate via the UART interface.

The Network Bridge API consists of a Command API command and several variables, and two Native C API functions.

Commands :

Variables :

Native C Interface APIs :

Example Usage

Check default variable values and set up network bridge auto start. 

> get network.bridge.interface_1
none
> get network.bridge.interface_2
none
> get network.bridge.info
state: down
SSID: Gecko_OS_Bridge-#
channel: 0
clients: 0
> get network.bridge.auto_start
0
> set network.bridge.interface_1 ethernet
Set OK
> set network.bridge.interface_2 softap
Set OK
> set network.bridge.auto_start true
Set OK