Ayla Device Wi-Fi for Embedded Systems

Device Wi-Fi Features

Ayla Device Wi-Fi (ADW) maintains the Wi-Fi configuration and connection between the device and the cloud. The ADW software is an optional package with the Ayla Embedded Agent, but the ADW requires the Ayla Embedded Agent. The product releases covered in this document are the ADW 1.2, which is currently integrated with Ayla Embedded Agent 1.2.

This section describes limitations in the ADW and interfaces to the Ayla Embedded Agent and the host application.

Limitations in the ADW 1.2 Release

Wi-Fi Protected Setup (WPS) is not supported or planned for future releases.

In some Software Development Kits (SDKs), the AP and STA mode can be used simultaneously only when the AP joined by the STA is not in the same network used by AP mode, 192.168.0.1. If the network being joined conflicts with the AP network, the AP shuts down and the STA connection is maintained. This provides a good Wi-Fi setup, but not a good user experience. You can change the compiled-in AP mode IP address to something that is less likely to conflict. The mobile applications use the gateway address obtained using DHCP. Refer to Step 4 in Section 6.

Interfaces to the Ayla Embedded Agent

ADW relies on the following interfaces that may be provided, but are required by the Ayla Embedded Agent:

• C library functions
• Console logging
• Configuration system
• Encryption services
• HTTP client
• HTTP server
• OS functions: timers, threads, and callbacks
• Networking interfaces

NOTE: We assume you are using the current release of the Ayla Embedded Agent.

Interfaces to the Host Application

The ADW relies on functionality provided by the product integrator. This primarily consists of configuration and an event handler responsible for the indications of connectivity, such as LEDs or other displays. The functionality of the product integrator may also be used to start the Ayla Embedded Agent and launch other services when connectivity is established and to stop services when connectivity is lost.

Major Components of Ayla Device Wi-Fi

This section provides pertinent information on the main components of Ayla Device Wi-Fi (ADW). Each subsection is an ADW component.

Wi-Fi State Machine

The ADW Wi-Fi state machine manages the Wi-Fi connection, AP mode, and scanning. The main objective of this component is to select a profile and connect accordingly.

Wi-FiModuleInterface

The Wi-Fi Module Interface (WMI) is a set of internal APIs that are a part of the platform- specific interface to the software development kit (SDK).

Wi-Fi HTTP Pages

The ADW HTTP server pages are used during the Wi-Fi setup to obtain scan results and initiate the Wi-Fi connection.

When a mobile device first connects to ADW in AP mode, the server can re-direct all requests to the ADW page for Wi-Fi setup using the browser or through a mobile app.

CAUTION: Wi-Fi setup using a browser is not secure because the Wi-Fi passphrase is revealed when sent. Whereas, Wi-Fi setup through the mobile app always uses a cryptographic key exchange protocol on top of HTTP.

Configuration

Configuration of the ADW relies on the features used by the Ayla Embedded Agent running on top of the SDK. The Wi-Fi module has three configuration sets in use:
• running configuration
• startup configuration
• factory configuration

The running configuration is stored in RAM, and if the configuration is not saved, it is erased on each reset.

The startup and factory configurations are stored in flash and the concatenation of them is used to load the running configuration during initialization. If the same name is used for both the factory and startup configurations, the last one saved takes precedence.

There is a setup mode that is usually enabled during initial configuration in the OEM factory settings. You may only enter certain CLI commands in setup mode. When a 'save' is done in setup mode, the running configuration is written to the factory configuration. When the configuration is saved outside of setup mode, the running configuration is written to the startup configuration.

When a factory reset is performed, either by the 'reset factory' CLI command or through an API, the startup configuration is erased, causing the device to revert to the factory configuration that existed when setup mode was disabled.

CAUTION: The OEM should disable setup mode before performing the Wi-Fi setup and connecting to any networks. Otherwise, the new Wi-Fi profile is saved to the factory configuration and is not erased by a factory reset.

Logging

ADW log messages use the module name 'wifi' under the ADA logging subsystem.

CLI Interfaces

The Ayla Embedded Agent provides a small number of CLIs that may be used by the ADW. These interfaces allow some debugging and manufacturing setup of the device.

Multithreading Considerations

Ayla Device Wi-Fi (ADW) code runs in the Ayla Embedded Agent network thread and is asynchronous for the most part. ADW may also launch other threads to perform synchronous operations when necessary. Events and calls from other threads are safe and either performed to completion or queued.

Memory Requirements

Memory requirements for the Ayla Device Wi-Fi (ADW) depend on the features and the chosen Software Development Kit (SDK). The estimates in the following table are based on the memory requirements of a typical small RISC architecture:

Table: Revision History of Content Updates and Changes

NOTE: You may not need to include code, read-only data, and web pages in both RAM and Flash on some platforms.

Integrating Ayla Device Wi-Fi

This section provides the steps required to integrate and use Ayla Device Wi-Fi (ADW) with the Ayla Embedded Agent. As stated earlier, these are delivered together in the same package.

NOTE: You may use the code in 'demo/ayla_demo/demo_wifi.c' as an example for handling initialization and events.

1. In 'demo_wifi.c', call 'demo_wifi_init()' before calling 'ada_init()'.
2. Modify 'OEM_AP_SSID_PREFIX' in 'conf.h' as follows to use as your desired prefix
   for the AP-Mode SSID.
   The format of the AP-Mode SSID is 'Ayla-', for example:
   'Ayla-123456789012'
   Change the prefix from “Ayla” to something more appropriate for your product.
   If you want to change the pattern to something else, change the code in
   'demo_wifi_init()'.
3. Consider turning on 'conditional AP-mode' by doing 'adw_wifi_ap_conditional_set(1)'. This disables the AP-Mode when there is an enabled profile, which is a good security measure, especially if the device loses connectivity and is using AP-Mode registration.
4. Change the IP parameters if your application prefers another set. On some SDKs, you may be advised to use a network that does not conflict with the station-mode network. The IP parameters for AP-Mode are provided in the header file in 'libadw/include/adw/wifi_conf.h'. The definitions are as follows:

• ADW_WIFI_AP_IP - defaults to 192.168.0.1 

• ADW_WIFI_AP_NETMASK - defaults to 255.255.255.0 

• ADW_WIFI_AP_DHCP_START defaults to 192.168.0.21 

• ADW_WIFI_AP_DHCP_END - defaults to 192.168.0.49 

• ADW_WIFI_AP_DHCP_LEASE - Lease time, defaults to 300 seconds.

5. During manufacturing, enter the CLI command, 'wifi enable' to turn on the Wi-Fi. You may prefer to use the equivalent C APIs instead, which is 'adw_wifi_enable()'.
6. When all of the desired factory settings have been made, disable the setup mode and save the settings to the factory configuration using either the CLI 'setup_mode disable', or the C API, 'ada_conf_setup_mode(0)'.

NOTE: This is an important step so that a factory reset can be performed later by the device or from the cloud.

Application Programming Interfaces (APIs)

This section describes the APIs that the Ayla Device Wi-Fi (ADW) supplies to the Ayla Embedded Agent and the host application.

Interfaces Supplied to the Ayla Embedded Agent

The Ayla Embedded Agent requires ADW or any alternative Wi-Fi subsystem to supply the interfaces described in this section. The descriptions in the following table focus on the behavior of the interface under ADW.

Table: Interfaces Supplied to the Ayla Embedded Agent

Interfaces Used by the Host Application

The interfaces in this section may also be used by the host application. The descriptions focus on the behavior of the interface under ADW.

Configuration APIs

The following table provides the interfaces that set the initial configuration options for ADW.

Table: Interfaces that Set the Initial Configuration Options for ADW

Control APIs

The following table provides the interfaces that initialize ADW or allow control of its functions after initialization.
Table: Interfaces that Initialize ADW or Allow Control After Initialization

Status APIs

The host application may use the Status APIs described below to determine the status of the Wi-Fi connection.

• 'adw_wifi_configured()'
  'int adw_wifi_configured(void)'
  Returns a non-zero if any network profiles are enabled.
• 'adw_wifi_event_register()'
  'void adw_wifi_event_register(void (handler)(enum adw_wifi_event_id, void ), void *arg)'

Registers a callback to the application function handler(). The callback is done when certain events occur, such as joining or leaving a network or starting or stopping
AP mode. This allows the application to indicate the status using the LEDs or to start or stop network services. The event ID is any of those listed in the following table.

NOTE: You can only register a handler in this manner one time.

Table: The Event ID Used by the Handler

An example of how the events should be handled by the host application is in the demo program for the platform, which is provided with ADW. For example, for the 'ADW_EVID_AP_UP' event, the application should start a web server and DNS server for handling Wi-Fi setup. When the 'ADW_EVID_AP_DOWN' event occurs, the DNS server may be stopped. On some platforms, these operations may be performed internally by ADW. On other platforms, these operation need to be done by the host application. Consult the demo code for the requirements on your platform.

When the 'ADW_STA_DHCP_UP' event is called, the ADA client should start, along with the web server, mDNS server, and possibly the NTP client, depending on the platform.

NOTE: Not all events need to be handled; some may be ignored. The handler must ignore any events that are not recognized.

• 'int adw_wifi_in_ap_mode()'
  'int adw_wifi_in_ap_mode(void)'
  Returns a non-zero if the AP interface is currently active.

Command Line Interface

This subsection provides the APIs for various command line interfaces (CLI). The host application may use these APIs to include in the host application as main commands or subcommands. The command name used for each one may be changed by the application to something different than specified, but the usage messages indicate the name commonly used, like 'compiled in'.

NOTE: Generally, these commands are only used during setup or development. After a product ships, it is undesirable to have an exposed CLI.

• CLI function arguments
  Most of these functions (like those described below) have prototypes similar to:
  'void adw_wifi_cli(int argc, char **argv)'
  An exception is the 'adw_wifi_show()' function, which takes no argument. A wrapper for a show wifi command generally calls this API.
  Each command is invoked on the CLI as 'wifi arg1 arg2 arg3', with the arguments separated by spaces or some other application-specified separator. The command parser may be provided by the SDK or the host application. The host application may add ADW commands to its own command set.

NOTE: Though not required, it is useful for the parser to accept quoted-string tokens to pass arguments containing spaces to the commands. Without that ability, the CLI is not able to specify an SSID that contains a space.

The first parameter, 'argc', provides a count of the number of arguments, including the command itself. 'argc' should always be at least 1. The second parameter, 'argv', is a pointer to an array of 'argc' string pointers, followed by a NULL pointer.
For example, the CLI for '“wifi profile 0 profile erase”' can be called as:

char *argv[6] = {“wifi”, “profile”, “0”, “profile”, “erase”, NULL};
  adw_wifi_cli(5, &argv);

• 'adw_wifi_show()'
  void adw_wifi_show(void)
  Prints the Wi-Fi status on the serial debug console. Following is an example of the typical output.

Notice in the example above that the output starts with the mode and signal and then provides the MAC and IP parameters for the Station and AP interfaces.

NOTE: The amount of information provided in the output may change in future versions or depending on the current settings and conditions.

Following is a description of the remaining output shown in the above example:
Profiles lists each stored profile, its SSID, security, and any special flags, such as 'disabled' or 'hidden'.
Scan results shows the results from the most recent scan, which includes the SSID, Type, channel, signal strength, and security. The signal strength is that provided by the SDK scaled to be a negative number comparable to the signal strength in dBm over the noise floor. These numbers can be compared to each other as relative strength, but are not absolute signal strength values.
Connection history shows the history of the last 3 to 5 connection attempts. Notice that only the first and last letters of the SSID and the last 2 bytes of the BSSID are shown.

• 'adw_wifi_show_rssi()'
  'void adw_wifi_show_rssi(int argc, char **argv)'
  Shows the RSSI (signal strength). The output displays on the console after sampling a few times.
  The prompt may come back before the RSSI is logged.
• 'adw_wifi_cli()'
  'void adw_wifi_cli(int argc, char **argv)'
  This is the main configuration interface for Wi-Fi.

NOTE: Several of the Wi-Fi commands may not be used until a 'wifi commit' command is issued. This command allows a save to be done before the Wi-Fi changes and changes to several of the parameters in the profile take effect.

Several parameters may be combined on the same line, but their usage can be confusing. The parameters are interpreted sequentially as if they were entered on separate wifi commands. Refer to the following example.

wifi profile 0 ssid mynetwork key mykey1234 security WPA2
wifi profile enable join
wifi profile 9 profile erase

The usage in this example can be confusing because wifi profile 0 enable is equivalent to:

wifi profile 0
wifi enable

However, 'wifi profile 0 enable' is not equivalent to:

wifi profile 0
 wifi profile enable

There may be changes to clear confusion like this in the future since it seems logical to infer that all the arguments apply to the profile if the profile was specified earlier in the command. Scripts using these commands must not rely on the current behavior of using multiple arguments.
The wifi command supports the sub-commands in the following table.

Table: Subcommands Supported by the 'wifi' Command

With regard to the last two subcommands in the above table, if 'save_on_server_connect' is set to '1 'and the agent (client) is disabled, the behavior is as if 'save_on_ap_connect' is set to '1'. Refer to the following example:

wifi profile 0
wifi ssid mynetwork
wifi key mykey1234
wifi security WPA2_Personal
wifi profile enable
wifi join

wifi profile 9
wifi profile erase