Networking and Security

Gecko OS includes a full IPv4 networking stack and SSL/TLS security suite that supports a range of popular networking protocols including TCP, UDP, DNS, DHCP. Additional network application libraries 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 and procedures to start and stop the client or server.

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

Other network features include ...

Security features include ...

Procedure for Joining a WLAN Network

Setting WLAN Variables

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

Starting the Network Up Sequence

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

The Network Up Sequence

The following diagram shows the network up sequence. Click to enlarge.

The auto join retry count is set to zero at the beginning of the entire sequence.

Circled step numbers in the diagram above correspond to the numbered steps in the network up sequence below:

  1. check retry count :

    • IF join attempt count >= wlan.join.retries , GOTO step 6: join attempt failed.
    • ELSE continue to next step.

  2. first time? :

    • IF network has previously been joined successfully: skip probe and attempt to join with existing network details. GOTO step 4: attempt to join.
    • ELSE continue to next step.

  3. probe for network details :

    • IF join attempt count == 1, Gecko OS probes for network with wlan.bssid and/or wlan.security if set, else wlan.ssid . Probing uses all wlan.scan.* variables
    • IF probe NOT successful, GOTO step 6: join attempt failed.
    • ELSE continue to next step: attempt to join

  4. attempt to join : Gecko OS attempts to associate using network details found in probe or in stored in previous successful join:

    • IF Gecko OS has network details (i.e. bssid, channel and security), Gecko OS attempts to associate to network, with timeout after wlan.join.timeout ms.
      • IF association successful, goto step 5, get IP address, DNS and gateway values
      • ELSE IF association failed, Gecko OS failed to associate to network. Increment join retry count and GOTO step 1
    • ELSE if network not found in probing, the join attempt failed. GOTO step 6.

  5. get IP address, DNS and gateway values :

    • IF the device successfully joins the network:
    • ELSE the join attempt failed. GOTO step 6, join attempt failed.

  6. join attempt failed : Try again if auto join enabled, WLAN interface not just forced down, and auto join retries not exceeded:

  7. network up sequence complete

Gecko OS has either succeeded or failed in joining the network. You can check wlan.join.result to determine the final result of the network_up sequence.

DHCP Client

The Gecko OS DHCP client obtains an IP address from the WLAN DHCP server when the network is brought up with the wlan interface.

Configure the DHCP client with the variables:

Bring the network up by issuing any command that requires the network, or use the command:

DHCP Server

The Gecko OS DHCP server supplies IP addresses to clients connecting to the soft AP when the network is brought up with the softap interface.

Configure the DHCP server with the variables:

The soft AP starts on reboot when configured to auto-start with the softap.auto_start variable.

You can bring up the soft AP with the network_up command. Either specify the softap interface, or set the network.default_interface variable to softap .

The soft AP starts automatically when you use Web Setup .

DNS Client

The DNS Client works with all the network protocols, including HTTP, TCP and UDP.

The network.dns.timeout variable controls the length of time Gecko OS waits while attempting to resolve a hostname via DNS.

The wlan.network.dns variable returns a list of addresses currently in use by the WLAN interface.

DNS Server

DNS Server features are available for the Soft AP interface.

Configuration options for the soft AP DNS server are:

The setup.web.url variable defines a list of URLs that clients can use to connect to the Gecko OS Web App.

HTTP Client

The HTTP Client consists of a group of commands for HTTP methods:

For a secure TLS transaction, the url scheme specified with the command must be https . See HTTPS Client .

The http_get , http_post and http_head commands have an option to queue the request, prior to sending. While the request is queued, use the http_add_header to add custom headers as required, as shown in the example below. Use the stream_write command to add data to the body of a POST request.

Use the http_read_status command to read the HTTP response after a request is completed.

Connection timeout for the HTTP client commands is controlled by the tcp.client.connect_timeout variable.

Stream Type : HTTP . See Network Connections and Streams, Stream Types .

HTTP POST Example

The following (fictitious) HTTP POST example shows how to post data to an HTTP web server using the Gecko OS HTTP API. The HTTP body data posted in this example is a small piece of JSON (sent using stream_write 0 7 ). Since the -o option is used with the http_post command, a connection stream to the HTTP server is opened, but the HTTP POST is queued locally on the module.

Queuing the HTTP POST locally provides the ability to add HTTP headers using the http_add_header command, and to post data in the HTTP body using the stream_write command. Once all headers and body data are queued, the HTTP POST is sent to the server and completed using the http_post command.

Any response data received from the server may be read using stream_read . 

> http_post -o example.com/hello application/json
[2019-01-01 | 19:40:23: Opening: example.com]
Request POST /hello
Connecting (HTTP): example.com:80
[2019-01-01 | 19:40:23: Opened: 0]
0
> stream_write 0 7
... JSON data goes here ...
Success
> http_read 0
HTTP response: 200
Chunked response
200
> stream_read 0 1000
{
  "response": "howdy!"
}
> stream_close 0
Closing: 0
[2019-01-01 | 19:40:40: Closed: 0]
Success

HTTP Client File Upload and Download

The HTTP Client feature includes commands to handle file upload and download, between the Gecko OS device file system and an HTTP/S host:

The http_upload and http_download commands use HTTP POST requests in the background.

For a secure TLS transaction, the url scheme specified with the command must be https .

See:

HTTP Client Native API

See Native API HTTP Client group .

HTTP Server with RESTful API

The Gecko OS HTTP webserver may be configured to run as a service on either the softAP or WLAN interface.

The server supports HTTP Basic Authentication with (or without) HTTPS security.

There is no network stream associated with the HTTP server. An HTTP client issues a request and the HTTP server sends a response. The client and server do not read or write data outside the request.

Gecko OS provides a simple RESTful API on top of the HTTP server. The API allows for a remote HTTP(S) client to issue any Gecko OS command. The result of the command is returned in a simple JSON format.

The RESTful API can be used in a number of ways:

The HTTP Server is configured with the following variables:

A client can use the RESTful API to issue Gecko OS commands and receive responses, and also for retrieval of module log messages.

The available requests are as follows: 

GET  /command
POST /command
GET  /log
POST /stream

See the HTTP Server RESTful API application note for low-level examples.

The Gecko OS Web App provides a complete demonstration of the HTTP Server RESTful API, and can be customized as required. See Customizing the Gecko OS Web App .

Notes

Command Request/Response

The API supports either a simple GET request or a slightly more complex POST request.

GET Request 

GET /command/<Gecko OS command>

POST Request 

POST /command
{
   "flags"   : <flags>,
   "command" : "<Gecko OS command>",
   "data"    : "<command data>"
}

where:

With the REST API, the procedure for issuing commands is:

  1. Open HTTP socket to server
  2. POST JSON formatted command to device
  3. Device processes request
  4. Device returns a JSON formatted response
  5. HTTP connection closed

To issue another command, repeat steps 1-5.

HTTP Response Codes

Response body 

{
   "id"       : <unique id>,
   "code"     : <response code>,
   "flags"    : <flags>,
   "response" : "<command response>"
}

where:

Log Request/Response

The API also buffers log messages. This is the request to retrieve the log messages.

GET Request 

GET /log

HTTP Response Codes

Response 

{
  "logs" : [ "<log data>", "<log data>", ....] }
}

Note : the log buffer has limited space. Older logs are replaced by newer ones. This should be called periodically to avoid losing logs.

HTTP Response Codes

HTTP Server Security and Authorization

The HTTP server is secured using HTTP Basic Authentication . This requires that a client supplies a username and password. Note that the username/password are sent in the HTTP request header which is encrypted only if the HTTP request itself is encrypted.

Client Authorization

The HTTP Basic Authentication client authorization feature is enabled when both the http.server.username and http.server.password variables are set.

When the HTTP Server username/password settings are set, authorization is required to access certain files and api commands.

The client must supply a username and password that matches the http.server.username and http.server.password variables.

If authorization fails the Gecko OS HTTP Server returns:

Protecting or Securing a File

When client authorization is enabled , authorization is required to download all files (except unprotected files).

To unprotect a file, the -u ( u nprotected) flag must be explicitly specified when the file is created using the file_create or http_download commands.

When client authorization is disabled , all files may be downloaded from the Gecko OS web server.

Securing the REST API, Whitelisting API Calls

When the authorization feature is enabled all REST API calls require authorization. It is possible to 'whitelist' certain API calls.

This is done by creating the file: http_whitelist.csv which contains a comma separated list of REST API calls that do not require authorization.

This file also supports a trailing wildcard character * . Some examples of this file are as follows:

CORS (Cross Origin Resource Sharing)

The Gecko OS HTTP server supports CORS (Cross-Origin Resource Sharing) .

The http.server.cors_origin variable allows you to specify origins for which the same-origin policy is relaxed.

This allows control of the module, via the HTTP server, from a remote site provided the module has originally been set up with a http.server.cors_origin domain that allows access from that site. Via the Gecko OS HTTP server Gecko OS JavaScript API , the remote site can issue all Gecko OS commands, including reboot .

Setting the http.server.cors_origin results in the Gecko OS HTTP server inserting a corresponding CORS Access-Control-Allow-Origin (ACAO) response header into resources it delivers. It also results in the Gecko OS HTTP server responding to an OPTION request with a set of options supporting remote control.

When a client connects to the HTTP server, the server validates the client's 'origin' header against http.server.cors_origin . If the origin does not match http.server.cors_origin then the HTTP server immediately terminates the connection.

HTTP Server Security Variables

The variables for managing HTTP Basic Authentication are:

The variable for managing CORS is:

HTTPS Client

HTTPS client commands include:

The HTTP client commands use TLS when the URL supplied has the scheme https .

The TLS CA certificate is supplied as a command argument or by default configured with the variables:

HTTPS Server

The HTTP Server becomes an HTTPS Server when TLS is configured for HTTP Server with the variables:

All the features described above for the HTTP Server are supported for the HTTPS Server.

NTP Client

Network Time Management

Gecko OS devices can obtain time data from an NTP (Network Time Protocol) server.

Configure NTP with the variables:

Time related variables are:

If NTP is enabled, time.last_set returns the seconds since the time was last set by NTP.

To read the time, get time.rtc and to determine the time zone, get time.zone .

SMTP Client

The SMTP Client allows Gecko OS devices to send email messages via an external SMTP server.

Configure email via SMTP with the variables:

Send email with the command:

To use TLS with the SMTP client, set the value of network.tls.ca_cert .

See the Sending a Secure SMTP Email application note.

SMTP Native API

See Native API SMTP group .

TCP Client

Configure the TCP client with the variables:

Start the TCP client with the command:

Stream Type : TCPC . See Network Connections and Streams, Stream Types .

TCP Client Auto Connect

To connect automatically to a remote host when the network is brought up, configure TCP client auto-connect with the variables:

To auto start with a TLS connection, set tcp.client.tls_enabled = TRUE. See TLS Client .

TCP Client Connection Retry Sequence

The TCP client connection retry sequence is shown in the following diagram. Click to enlarge:

TCP Server

Configure the TCP server with the variables:

Start and stop the TCP server with the TCP server command:

Stream Type : TCPS . See Network Connections and Streams, Stream Types .

To use the TCP server with TLS, configure the tcp.server.tls* variables and use the tls_server command. See TLS Server .

TLS 1.0-1.2 Support

Gecko OS supports TLS 1.0 to TLS 1.2.

For a full description of TLS errors and the commands that use TLS, see TLS Errors .

Supported TLS Cipher Suites

Gecko OS supports the following Cipher Suites for TLS 1.0 - 1.2:

OpenSSL Name Key Exchange Encryption Hashing Algorithm
MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 ECDHE AES-128 SHA-256
MBEDTLS_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ECDHE AES-128 SHA-256
MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 ECDHE AES-128 SHA-256
MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA ECDHE AES-128 SHA-1
MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA ECDHE AES-256 SHA-1
MBEDTLS_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA DHE RSA AES-128 SHA-1
MBEDTLS_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 DHE RSA AES-256 SHA-256
MBEDTLS_TLS_DHE_RSA_WITH_AES_256_CBC_SHA DHE RSA AES-256 SHA-1
MBEDTLS_TLS_RSA_WITH_AES_256_CBC_SHA256 RSA AES-256 SHA-256
MBEDTLS_TLS_RSA_WITH_AES_256_CBC_SHA RSA AES-256 SHA-1
MBEDTLS_TLS_RSA_WITH_AES_128_CBC_SHA256 RSA AES-128 SHA-256
MBEDTLS_TLS_RSA_WITH_AES_128_CBC_SHA RSA AES-128 SHA-1

Acronyms Used in Above Table

TLS Memory Requirements

Increasing Available Memory for TLS

TLS connections require a considerable amount of RAM. Low memory may result in TLS errors such as TLS malloc failed .

To establish a TLS connection, other memory intensive features may need to be disabled. You can return the device to the default state with a factory reset .

TLS Errors

TLS Error Format

In the event of TLS failure, the response includes an error message with a format similar to the following: 

Error with TLS handshake: <error code> (state: <tls state>, code: <internal error code>)

where:

TLS Error Example 

> http_get https://google.com
[2019-01-01 | 02:50:33: Opening: https://google.com]
Request GET /
Connecting (https): google.com:443
Starting TLS
TLS malloc failed
Error with TLS handshake: 5035
[2019-01-01 | 02:50:33: Open failed]
Command failed

TLS Error Codes

Code Error
2 TIMEOUT
5001 RECEIVE_FAILED
5002 ALERT_NO_CERTIFICATE
5003 ERROR_OUT_OF_MEMORY
5004 ERROR_FEATURE_UNAVAILABLE
5005 ERROR_BAD_INPUT_DATA
5006 ERROR_INVALID_MAC
5007 ERROR_INVALID_RECORD
5008 ERROR_INVALID_MODULUS_SIZE
5009 ERROR_UNKNOWN_CIPHER
5010 ERROR_NO_CIPHER_CHOSEN
5011 ERROR_NO_SESSION_FOUND
5012 ERROR_NO_CLIENT_CERTIFICATE
5013 ERROR_CERTIFICATE_TOO_LARGE
5014 ERROR_CERTIFICATE_REQUIRED
5015 ERROR_PRIVATE_KEY_REQUIRED
5016 ERROR_CA_CHAIN_REQUIRED
5017 ERROR_UNEXPECTED_MESSAGE
5018 ERROR_FATAL_ALERT_MESSAGE
5019 ERROR_PEER_VERIFY_FAILED
5020 ERROR_PEER_CLOSE_NOTIFY
5021 ERROR_BAD_HS_CLIENT_HELLO
5022 ERROR_BAD_HS_SERVER_HELLO
5023 ERROR_BAD_HS_CERTIFICATE
5024 ERROR_BAD_HS_CERTIFICATE_REQUEST
5025 ERROR_BAD_HS_SERVER_KEY_EXCHANGE
5026 ERROR_BAD_HS_SERVER_HELLO_DONE
5027 ERROR_BAD_HS_CLIENT_KEY_EXCHANGE
5028 ERROR_BAD_HS_CERTIFICATE_VERIFY
5029 ERROR_BAD_HS_CHANGE_CIPHER_SPEC
5030 ERROR_BAD_HS_FINISHED
5031 HANDSHAKE_TIMEOUT
5032 HANDSHAKE_ERROR
5033 INIT_FAIL
5034 BAD_MESSAGE
5035 UNTRUSTED_CERTIFICATE
5036 EXPIRED_CERTIFICATE
5037 CERTIFICATE_NAME_MISMATCH
5038 CERTIFICATE_REVOKED
5039 NO_DATA
5040 ERROR_UNSUPPORTED_EXTENSION

TLS States

Code TLS State
0 SSL_HELLO_REQUEST
1 SSL_CLIENT_HELLO
2 SSL_SERVER_HELLO
3 SSL_SERVER_CERTIFICATE
4 SSL_SERVER_KEY_EXCHANGE
5 SSL_CERTIFICATE_REQUEST
6 SSL_SERVER_HELLO_DONE
7 SSL_CLIENT_CERTIFICATE
8 SSL_CLIENT_KEY_EXCHANGE
9 SSL_CERTIFICATE_VERIFY
10 SSL_CLIENT_CHANGE_CIPHER_SPEC
11 SSL_CLIENT_FINISHED
12 SSL_SERVER_CHANGE_CIPHER_SPEC
13 SSL_SERVER_FINISHED
14 SSL_FLUSH_BUFFERS
15 SSL_HANDSHAKE_OVER

TLS Client

TLS client commands include:

See also HTTPS Client .

TLS details must be supplied as a command argument or configured with the variables:

To manually initiate a TLS connection with the TCP client, use the tls_client command.

To auto-start the TCP client with TLS, set:

See TCP Client Auto Connect .

The TCP client, with TLS enabled, has the features described in the TCP Client documentation.

Stream Type : TLSC . See Network Connections and Streams, Stream Types .

OTA always uses TLS.

Commands that use TLS respond to TLS failure with a specially formatted error message. See TLS Error Format .

Connect timeout for the TLS client command is controlled by the tcp.client.connect_timeout variable.

TLS Server

Configure TLS Server with the variables:

See commands:

The TLS server has all the features described in TCP Server .

Stream Type : TLSS . See Network Connections and Streams, Stream Types .

UDP Client

Configure the UDP client with the variables:

Start the UDP client with the command:

Stream Type : UDPC . See Network Connections and Streams, Stream Types .

UDP Client Auto Connect

Configure the UDP client auto-connect with the variables:

UDP Server

Configure the UDP server with the variables:

Start and stop the UDP server with the command:

The udp_server has subcommands to read and write . These are equivalent to the stream read and write commands, with the added option of determining the client address and port.

The UDP server uses a single stream for multiple clients. Using the stream read and write commands applies to all clients. Using the UDP server subcommands allows writing to and reading from a specific client.

Stream Type : UDPS . See Network Connections and Streams, Stream Types .

UDP Server Auto Connect

Configure the UDP server auto-connect with the variables:

WebSocket Client

Configuration options for the websocket client include:

The command to invoke the websocket client is:

See the websocket_client documentation for details on the websocket message format.

The websocket client supports TLS via the websocket URL scheme and the websocket_client cert filename argument.

The websocket_client -g option configures a data ready GPIO for a single websocket.

Read from the Websocket with stream_read .

Write to the Websocket with stream_write .

To send a WebSocket ping frame as a keepalive, use the stream_write with the -p option.

To send data chunks as continuation frames, use the stream_write with the -f option.

Stream Type : WEBC . See Network Connections and Streams, Stream Types .

WebSocket Server

The WebSocket protocol provides full-duplex communication channels over a single TCP connection. Gecko OS WebSocket server support requires the HTTP Server. The HTTP REST API includes WebSocket API calls.

Websocket server CORS policy is discussed in HTTP Server, CORS (Cross Origin Resource Sharing) .

Configuration variables are:

Stream Type : WEBS . See Network Connections and Streams, Stream Types .

WebSocket Stream

To open a WebSocket, issue the API call POST /stream to the Gecko OS HTTP server. Gecko OS opens a WebSocket and creates a network stream. An MCU can read/write data using the Gecko OS stream_read and stream_write commands. See Network Connections and Streams . 

POST /stream
<raw data .... >

See HTTP Server Simple WebSocket Demonstration .

WebSocket URI

When connecting to a Command API WebSocket server, the WebSocket URI is /stream .

When connecting to an App WebSocket server, the WebSocket URI is /zapstreams .

When connecting to a WebSocket command stream, the WebSocket URI is /cmdstream . See WebSocket Command Stream below.

WebSocket Command Stream

The WebSocket command stream lets you issue commands to your Gecko OS device via a WebSocket from a remote host.

The WebSocket command stream is complementary to the REST API. It uses the WebSocket protocol and the /cmdstream route.

When issuing a command via the WebSocket command stream, the sequence is:

  1. Open WebSocket stream with HTTP server via ws://<host>/cmdstream
  2. Issue msgpack formatted message to Gecko OS device. For details of msgpack format, see http://msgpack.org/ .
  3. Gecko OS device processes command message
  4. Gecko OS device returns msgpack formatted response

To issue another command repeat steps 2-4.

You need to import a msgpack library into your webpage or application to use the WebSocket command stream.

The command message is in the following form: 

{
   "command" : "<Gecko OS command>",
   "data" : "<command data>",
   "id" : <command id>
}

where:

The response from Gecko OS is of the following form: 

{
   "id" : <command id>,
   "code" : <response code>,
   "response" : "<command response>"
}

where:

Network Connections and Streams

Streams are associated with:

When Gecko OS opens a network connection, file, or serial connection, it returns a stream handle. The stream commands act on a stream handle to perform actions such as read, write, poll and close. You can list open streams. Each stream has a specific type. See Stream Types .

Stream Handles

When a stream is open, it is assigned a handle number. This handle is used to read/write/poll/close the stream.

Stream Commands

Refer to the following stream commands to use the stream handle:

Use the stream_list command to view open streams. For example: 

> stream_list
! # Type  Info
# 0 TCPS 10.5.6.146:3000 10.5.6.131:63835
# 1 UDPC  107.170.222.80:50007 (15672)
# 2 TCPC  107.170.222.80:50007 (13171)
# 3 FILE  webapp/unauthorized.html-1.0.1.3  (9530, 0)
# 4 FILE  favicon.ico.gz-1.0.1.3  (733, 0)
# 5 FILE  webapp/gecko-os.css.gz-1.0.1.3  (22670, 0)
>
Ready
>

Serial STREAM Mode

In serial STREAM mode, a single network connection (TCP/TLS/UDP/WebSocket client/server) streams to the serial bus. No stream read or write commands are required, as data flows automatically between the serial bus and the open stream. See Serial Interface, Stream Mode .

STREAM mode does not support the following stream types :

Note : When in STREAM mode, a TCP/TLS/WebSocket server is limited to one client connection.

STREAM mode is assigned to the auto-start network stream that opens first.

The STREAM mode enabled stream appears in the stream list. Reading and writing data to the stream is not permitted.

Note : If you create a STREAM mode application with multiple network streams set to auto start, then it may not be possible to predict which will open first and which network connection is streaming. We recommend using only one auto-start network connection when booting to STREAM mode.

Stream Limitations

Gecko OS supports up to 8 simultaneous network streams. Any TCP, Websocket or HTTP stream can be a secure stream. See Stream Types below.

Each stream type in the Stream Types table below uses a single stream, with the following exceptions and qualifications:

Stream Types

List the currently open streams with the stream_list command. Streams are listed with stream handle, type, and information about the stream source.

Note that some stream types support a limited set of operations. The following is a list of stream types, and for each type the command to create it, and the stream operations it supports.

Type Associated Commands Stream Operations Description
CMD buffered commands read / poll / close Buffered command data for commands that are buffered when the variable system.cmd.buffered = '1'
FILE file_open / file_create -o read / poll / close File system handle. See File system
HTTP http_get / http_post / http_head read / write / poll / close HTTP Client
HTTPS http_get / http_post / http_head read / write / poll / close Secure HTTP Client
I2C i2c_master_open read / write / poll / close I2C master serial connection. See Peripherals, I2C Master Peripheral Controlling and Monitoring
SPI spi_master_open read / write / poll / close SPI master serial connection. See Peripherals, SPI Master Peripheral Controlling and Monitoring
TCPC tcp_client read / write / poll / close TCP Client
TCPS tcp_server read / write / poll / close TCP Server client stream. Note that one stream is used per client
TLSC tls_client read / write / poll / close TLS Client
TLSS tls_server read / write / poll / close TLS Server client stream. . Note that one stream is used per client
UDPC udp_client read / write / poll / close UDP Client
UDPS udp_server read / write / poll / close UDP Server . Note that one stream is used for all server clients
WEBS - read / write / poll / close WebSocket Server with a connected client.
WEBC websocket_client read / write / poll / close WebSocket Client

Network Status Indication Using GPIOs

You can configure GPIOs to act as indicators of networking states, such as the state of the WLAN connection, the Soft AP connection, or DHCP progress. You can configure a selection of blink rates to indicate states.

See variables:

See Peripherals, System Indicator Functions .

Remote Terminal Access

You can control a Gecko OS device with a TCP/IP telnet connection via a remote terminal, connected to the device via the Soft AP interface or the WLAN interface.

Configure the remote terminal with the variables:

See the Wi-Fi Remote Terminal application note .

Network Discovery

Network Discovery for Gecko OS is under development.

Discovery Overview

In simple terms, network discovery is used to give the module a name on the local network. So, for instance, if the module has a domain name mymodule.local , a remote client on the same network can connect to the module using the domain mymodule.local even though the domain mymodule.local is not registered with a DNS server. This is useful because the remote client doesn't need to know the IP address of the module.

Gecko OS supports three network discovery protocols: mDNS (multicast Domain Name System), LLMNR (Link-Local Multicast Name Resolution) and NetBIOS. The latter two protocols are used by Windows systems only.

Configure mDNS with the variables:

Discovery OS Support

The remote client must support one or more network discovery protocols for device discovery to work.

Apple

Mac OS X & iOS support mDNS by default, with Bonjour.

Windows

Windows has support for mDNS, but by default it uses the LLMNR and NetBIOS protocols. These protocols are very similar to mDNS so their basic domain resolution features are supported by the module as well. When a domain is entered into the web browser, Windows follows this sequence to resolve the domain:

The LLMNR and NetBIOS queries are broadcast to the local network only. The DNS query is typically sent to the internet.

If network discovery is enabled on the module, the module will receive the LLMNR and NetBIOS queries, compare the query domain to its mdns.name , and if they match respond with the module's IP address. In this way the module can easily be found on the local network from a Windows machine.

A NetBIOS domain can have up to 15 characters (including the '.local'). If mdns.name is longer than 15 characters then the NetBIOS protocol is not used.

Finally, some ISPs hijack the .local domain for their own purposes, including advertising. This may cause a Windows PC to fail to resolve the domain. The solution (for Windows only) is to drop .local from the URL and simply use http://mymodule/ directly.

Linux

Linux needs an additional package installed for mDNS support. The most common package is Avahi.

Android

Android does not support mDNS (or other ZeroConf protocols) at the platform level, so third party Android apps like Chrome may not support mDNS. An Android SDK with mDNS support is available, so you can create an Android app with mDNS support. The Zentri Android Discovery app, available from the Google Play Store, demonstrates using the Android mDNS SDK to provide mDNS discovery on Android devices.

Discovery in a Nutshell

Network discovery provides a way for remote clients to resolve the IP address of the module on a local network using a standard protocol. mDNS has other features which allow the module to advertise various services including HTTP, TCP & UDP servers. Gecko OS supports configuration of these additional features with the mdns.service variable.

mDNS Native API

See Native API mDNS group .

Broadcast Status Announcement

A Gecko OS device broadcasts its properties in JSON format. The properties can be sent either as UDP packets to a UDP host or by a post request to an HTTP host.

Properties include by default the IP address and the MAC address.

Configure broadcast with the variables:

See also the Broadcast UDP Packet Application Note .

Captive Portal

Captive portal is supported during websetup and optionally for the soft AP. When the HTTP Server receives certain requests, it redirects to the root HTTP server web page. See softap.captive_portal_enabled .

Passkeys

The following network passkeys follow the same rules for allowable characters and setting syntax:

Passkey values can be provided as printable ASCII, or as encoded ASCII characters.

Printable ASCII

ASCII passwords must be 8-63 characters long. Any printable ASCII (in the character code range 32 to 127 ) may be used.

Example: 

set wlan.passkey password
set wlan.passkey ~!@#$#@#@#^&(()

Encoded ASCII

Encoded ASCII characters may be used.

An encoding is delimited with a backslash. The following encoding values are supported:

Encoded Value Decoded Value ASCII Hex Value
\0 Null character 0x00
\s Space 0x20
\\ Backslash 0x5C
\t Tab 0x09
\n New line 0x0A
\r Carriage Return 0x0D
\" Double-quote 0x22
\x?? Hex value 0x??

Example: 

set wlan.passkey p\"ss\tw\nor\xFF

Note : The length of the encoded string can be longer than 63 character, however, the length of the decoded string must be 8-63 characters.

The variable getter prints all non-printable characters in their hex encoded representation (e.g. \r -> \x0D )

Pre-generated PSK

A 64 char hex string PSK may be supplied.

Example: 

set wlan.passkey e2e04dcb82891a286e5d524b63f4963ac1f8dc49852bd6b97441d9545054d270

See https://www.wireshark.org/tools/wpa-psk.html for an example of generating a PSK.

Other Notes

Passwords can also be wrapped in double-quotes to insert spaces.

Example: 

set wlan.passkey "this is a password"