Introducing the Adafruit WICED Feather WiFi

by lady ada and

published March 23, 2016, last edited March 26, 2024

posted in Adafruit Products Internet of Things - IOT/ Wireless Feather/ Feather Boards

Intermediate

Product guide

AdafruitFeather

AdafruitFeather is the main class that you will use for common operations like connecting to an access point (AP), checking error codes, getting your IP address, or working with stored AP profiles.

AdafruitFeather API

The following functions are available in AdafruitFeather (which is normally accessible as Feather.* in all of your sketches, for example 'Feather.factoryReset()').

Download File

Copy Code

char const* bootloaderVersion ( void );
char const* sdkVersion        ( void );
char const* firmwareVersion   ( void );
char const* arduinoVersion    ( void );

int         scanNetworks      ( wl_ap_info_t ap_list[], uint8_t max_ap );

bool        connect           ( void );
bool        connect           ( const char *ssid );
bool        connect           ( const char *ssid, const char *key, int enc_type = ENC_TYPE_AUTO );

bool        begin             ( void );
bool        begin             ( const char *ssid );
bool        begin             ( const char *ssid, const char *key, int enc_type = ENC_TYPE_AUTO );

void        disconnect        ( void );

bool        connected         ( void );
uint8_t*    macAddress        ( uint8_t *mac );
uint32_t    localIP           ( void );
uint32_t    subnetMask        ( void );
uint32_t    gatewayIP         ( void );
char*       SSID              ( void );
int32_t     RSSI              ( void );
int32_t     encryptionType    ( void );
uint8_t*    BSSID             ( uint8_t* bssid );

IPAddress   hostByName        ( const char* hostname );
bool        hostByName        ( const char* hostname, IPAddress& result );
bool        hostByName        ( const String &hostname, IPAddress& result );

uint32_t    ping              ( char const* host );
uint32_t    ping              ( IPAddress ip );

void        factoryReset      ( void );
void        nvmReset          ( void );

bool        randomNumber      ( uint32_t* random32bit );

bool        getISO8601Time    ( iso8601_time_t* iso8601_time );
uint32_t    getUtcTime        ( void );

bool        useDefaultRootCA  ( bool enabled );
bool        initRootCA        ( void );
bool        addRootCA         ( uint8_t const* root_ca, uint16_t len);
bool        clearRootCA       ( void );

void        printVersions     ( Print& p = Serial );
void        printNetwork      ( Print& p = Serial );
void        printEncryption   ( int32_t enc, Print& p = Serial );

void setDisconnectCallback (void (*fp) (void));

char const* bootloaderVersion ( void );
char const* sdkVersion        ( void );
char const* firmwareVersion   ( void );
char const* arduinoVersion    ( void );

int         scanNetworks      ( wl_ap_info_t ap_list[], uint8_t max_ap );

bool        connect           ( void );
bool        connect           ( const char *ssid );
bool        connect           ( const char *ssid, const char *key, int enc_type = ENC_TYPE_AUTO );

bool        begin             ( void );
bool        begin             ( const char *ssid );
bool        begin             ( const char *ssid, const char *key, int enc_type = ENC_TYPE_AUTO );

void        disconnect        ( void );

bool        connected         ( void );
uint8_t*    macAddress        ( uint8_t *mac );
uint32_t    localIP           ( void );
uint32_t    subnetMask        ( void );
uint32_t    gatewayIP         ( void );
char*       SSID              ( void );
int32_t     RSSI              ( void );
int32_t     encryptionType    ( void );
uint8_t*    BSSID             ( uint8_t* bssid );

IPAddress   hostByName        ( const char* hostname );
bool        hostByName        ( const char* hostname, IPAddress& result );
bool        hostByName        ( const String &hostname, IPAddress& result );

uint32_t    ping              ( char const* host );
uint32_t    ping              ( IPAddress ip );

void        factoryReset      ( void );
void        nvmReset          ( void );

bool        randomNumber      ( uint32_t* random32bit );

bool        getISO8601Time    ( iso8601_time_t* iso8601_time );
uint32_t    getUtcTime        ( void );

bool        useDefaultRootCA  ( bool enabled );
bool        initRootCA        ( void );
bool        addRootCA         ( uint8_t const* root_ca, uint16_t len);
bool        clearRootCA       ( void );

void        printVersions     ( Print& p = Serial );
void        printNetwork      ( Print& p = Serial );
void        printEncryption   ( int32_t enc, Print& p = Serial );

void setDisconnectCallback (void (*fp) (void));

Firmware Version Management

Since the Arduino/user code, FeatherLib binary, Broadcom WICED SDK and bootloader version need to work with each other, it's important to make sure that the version numbers of the various components of the WICED Feather are in sync.

The following helper functions are provided to retrieve the current version numbers for the the various components used by your device.

char const* bootloaderVersion ( void )

Returns the current bootloader version string.

Parameters: None

Returns: A null-terminated string containing the current bootloader version in the MAJOR, MINOR, REVISION format, ex: "1.0.0".

char const* sdkVersion ( void )

Returns the current Broadcom WICED SDK version string.

Parameters: None

Returns: A null-terminated string containing the current Broadcom WICED SDK version in the MAJOR, MINOR, REVISION format, ex: "3.5.2".

char const* firmwareVersion ( void )

Returns the current FeatherLib version string.

Parameters: None

Returns: A null-terminated string containing the current FeatherLib version in the MAJOR, MINOR, REVISION format, ex: "0.5.0".

char const* arduinoVersion ( void )

Returns the current Arduino library version string. This corresponds to the library used when building code in the Arduino IDE, which handles the low level communication to FeatherLib.

Parameters: None

Returns: A null-terminated string containing the current Arduino library version in the MAJOR, MINOR, REVISION format, ex: "0.5.0".

Scanning

The following function initiates an access point (AP) scan to determine which APs are in range of the WICED Feather.

int scanNetworks (wl_ap_info_t ap_list[], uint8_t max_ap)

Initiates a new access point scan and returns the device details for any access point(s) within range of the WICED Feather.

Parameters:

ap_list: A pointer to an wl_ap_info_t array where the details for any AP found should be inserted. This array needs to be large enough to hold up to 'max_ap' entries!
max_ap: The maximum number of access points to write to 'ap_list'.

Returns: The number of APs written into ap_list.

See the 'Constants' page in this learning guide for details on the wl_ap_info_t struct.

Connecting

The following functions are used to connect to an access point.

bool connect ( void )

This function will attempt to connect using the list of Profiles stored in non-volatile config memory on the WICED Feather. See the AdafruitFeather: Profiles page in this learning guide for details on how to use the profile system.

Parameters: None

Returns: 'True' (1) if a connection was established with an AP based on the stored profile data, otherwise 'false' (0).

bool connect ( const char *ssid )

Attempts to connect to the open (security type = ENY_TYPE_OPEN) access point matching the 'ssid' parameter.

Parameters:

ssid: A string containing the name of the SSID to attempt to connect to.

Returns: 'True' (1) if the connection was successful, otherwise 'false' (0).

bool connect ( const char ssid, const char key, int enc_type = ENC_TYPE_AUTO )

Attempts to connect to the specified SSID using the supplied password ('key') and optionally a specific security type ('enc_type').

The security type is optional and if no value is provided the WICED Feather will attempt to determine the security type on it's own, but the connection process will terminate more quickly if you provide the appropriate security type since this avoids the need to perform a full access point scan before the connection attempt starts.

Parameters:

ssid: A string containing the name of the SSID to attempt to connect to.
key: The password to use when connecting to the AP
enc_type: The wl_enc_type_t value that indicates what type of security is used by the AP. The default value for this field is ENC_TYPE_AUTO which will cause the WICED Feather to determine this information for you, at the expense of a slower connection interval since we first have to perform a full access point scan. See the Constants page in this learning guide for a list of possible values for this parameter.

Returns: 'True' (1) if the connection was successful, otherwise 'false' (0).

bool begin ( void )

This is an alias for 'bool connect(void)' described above, and is provided to match the Arduino Client interface.

bool begin ( const char *ssid )

This is an alias for 'bool connect(const char* ssid)' described above, and is provided to match the Arduino Client interface.

bool begin ( const char ssid, const char key, int enc_type = ENC_TYPE_AUTO )

This is an alias for 'bool connect(const char *ssid, const char *key, int enc_type)' described above, and is provided to match the Arduino Client interface.

void disconnect (void)

Disconnects from the current access point.

Parameters: None

Returns: Nothing

Network and Connection Details

The following functions provide information about the connection or the network setup when your device is connected to an access point (AP).

bool connected ( void );

Checks if you are currently connected to an AP or not.

Parameters: None

Returns: 'True' (1) if you are currently connected to an access point (AP), otherwise 'false' (0).

uint8_t* macAddress ( uint8_t *mac );

Gets the HW mac address for the WICED Feather.

Parameters:

mac: The 6-byte uint8_t array to assign the mac address to. If you don't wish to use this field and use the optional 'return value' instead simply provide NULL to this parameter.

Returns: A pointer to a 6-byte array containing the 48-bit HW MAC address for your WICED Feather.

uint32_t localIP ( void );

Returns the IPv4 address for your WICED Feather.

Parameters: None

Returns: A 32-bit integer containing the four bytes that make up the IPv4 address for your device.

uint32_t subnetMask ( void );

Returns the IPv4 subnet mask.

Parameters: None

Returns: A 32-bit integer containing the four bytes that make up the IPv4 subnet mask.

uint32_t gatewayIP ( void );

Returns the IPv4 gateway IP.

Parameters: None

Returns: A 32-bit integer containing the four bytes that make up the IPv4 gateway address.

char* SSID ( void );

Returns the SSID for the current access point (AP).

Parameters: None

Returns: A null-terminated string containing the SSID name for the current AP.

int32_t RSSI ( void );

Returns the current return signal strength indicator (RSSI) in dBm, which indicate the strength of the connection between the WICED Feather and the remote access point. The larger the number, the strong the signal is (ex. -90dBm is weaker than -65dBm).

Parameters: None

Returns: The return signal strength indicated in dBm.

int32_t encryptionType ( void );

Returns the current encryption type used by the AP. See wl_enc_type_t on the constants page for a list of possible encryption types.

Parameters: None

Returns: An integer corresponding to the wl_enc_type_t enum list described on the constants page in this learning guide.

uint8_t* BSSID ( uint8_t* bssid );

Gets the access point mac address for the remote AP used by the WICED Feather.

Parameters:

bssid: The 6-byte uint8_t array to assign the BSSID address to. If you don't wish to use this field and use the optional 'return value' instead simply provide NULL to this parameter.

Returns: A pointer to a 6-byte array containing the 48-bit MAC address for the access point your WICED Feather is connected to.

DNS Lookup

The following helper functions allow you to look up a host name on the DNS server, converting it to an IP address:

IPAddress hostByName ( const char* hostname )

Parameters:

hostname: A string representing the domain name to lookup (ex. "www.adafruit.com").

Returns: The IPAddress corresponding to the specified hostname.

bool hostByName ( const char* hostname, IPAddress& result )

Looks up the domain name specified in the 'hostname' string, and assigns it to the IPAddress referenced by the 'result'.

Parameters:

hostname: A string representing the domain name to lookup (ex. "www.adafruit.com").
result: the IPAddress object that the lookup results will be assigned to.

Returns: 'True' (1) if the DNS lookup was successful, otherwise 'false' (0).

bool hostByName ( const String &hostname, IPAddress& result )

Looks up the domain name specified in the 'hostname' string, and assigns it to the IPAddress referenced by the 'result'.

Parameters:

hostname: A string representing the domain name to lookup (ex. "www.adafruit.com").
result: the IPAddress object that the lookup results will be assigned to.

Returns: 'True' (1) if the DNS lookup was successful, otherwise 'false' (0).

Ping

Ping can be used to detect of another server or device is available (although not all devices respond to ping requests!). The following helpers are available for this purpose:

uint32_t ping (char const* host)

Pings the domain name specified in the 'host' string.

Parameters:

host: The domain name to ping (ex. "www.adafruit.com").

Returns: The response time in milliseconds if the domain responded to the ping request, or '0' if the ping failed.

uint32_t ping (IPAddress ip)

Pings the specified IPAddress.

Parameters:

ip: The IPAddress to ping.

Returns: The response time in milliseconds if the IP address responded to the ping request, or '0' if the ping failed.

Factory Reset

If you set your WICED Feather modules into an unknown state of encounter unexpected behaviour, you can try to perform a full factory reset or reset the non-volatile config memory using these helper functions.

void factoryReset ( void )

Performs a full factory reset on the module, with the following consequences:

Erases all config data in non-volatile memory (NVM)
Erases any user code ('Arduino' code) from flash memory
Resets the device to the same state as when it shipped from the factory (although the current FeatherLib will be kept intact)
Performs a system reset, which will send the device into DFU mode since no user code is present on the device.

Parameters: None

Returns: Nothing

void nvmReset ( void )

Erases the non-volatile config memory on the WICED module, resetting the config settings to factory defaults.

Parameters: None

Returns: Nothing

Hardware Random Number Generator

The STM32F205 includes a HW white-noise random number generator that provides better results than a purely software based approach.

This can be used to generate random strings or numeric values for security purposes.

bool randomNumber ( uint32_t* random32bit )

Assigns a random unsigned 32-bit integer value to 'random32bit'.

Parameters:

random32bit: A pointer to the variable where the random number should be assigned

Returns: 'True' (1) if the random number generation was successful, otherwise 'false' (0).

Real Time Clock

The STM32F205 includes a real time clock, and as soon as you connect to an AP with internet access it will try to update the RTC clock based on an NTP server.

The RTC can be read in both Linux Epoch (UTC) time or ISO8601 format.

Epoch time returns a 32-bit unsigned integer value representing the number of seconds since 1 January 1970. For example '1456472597' would convert to:

Fri, 26 Feb 2016 07:43:17 GMT

ISO8601 format timestamps return the time as a specifically formatted string similar to the timestamp below:

2016-02-18T17:12:46.061104

bool getISO8601Time ( iso8601_time_t* iso8601_time )

Updates 'iso8601_time' with the current timestamp in ISO8601 format.

Time is based on GMT and will need to be adjusted for your local timezone, depending on your specific location and any seasonal adjustments (daylight savings time, etc.).

Parameters:

iso8601_time: A pointer to the 'iso8601_time_t' struct that will hold the timestamp data. (The typedef itself is defined in adafruit_constants.h.)

Returns: 'True' (1) if the timestamp was successfully assigned, otherwise 'false' (0).

ISO8601 timestamps use the following struct (defined in 'adafruit_constants.h') to convert the timestamp into something that can be printed as a null-terminated string, but also easily manipulated in code:

Download File

Copy Code

typedef struct ATTR_PACKED
{
    char year[4];        /**< Year         */
    char dash1;          /**< Dash1        */
    char month[2];       /**< Month        */
    char dash2;          /**< Dash2        */
    char day[2];         /**< Day          */
    char T;              /**< T            */
    char hour[2];        /**< Hour         */
    char colon1;         /**< Colon1       */
    char minute[2];      /**< Minute       */
    char colon2;         /**< Colon2       */
    char second[2];      /**< Second       */
    char decimal;        /**< Decimal      */
    char sub_second[6];  /**< Sub-second   */
    char Z;              /**< UTC timezone */

    char nullterm;       // not part of the format, make printf easier
} iso8601_time_t;

typedef struct ATTR_PACKED
{
    char year[4];        /**< Year         */
    char dash1;          /**< Dash1        */
    char month[2];       /**< Month        */
    char dash2;          /**< Dash2        */
    char day[2];         /**< Day          */
    char T;              /**< T            */
    char hour[2];        /**< Hour         */
    char colon1;         /**< Colon1       */
    char minute[2];      /**< Minute       */
    char colon2;         /**< Colon2       */
    char second[2];      /**< Second       */
    char decimal;        /**< Decimal      */
    char sub_second[6];  /**< Sub-second   */
    char Z;              /**< UTC timezone */

    char nullterm;       // not part of the format, make printf easier
} iso8601_time_t;

uint32_t getUtcTime ( void )

Returns the current 'Epoch' time (the number of seconds since the 1 January 1970).

Time is based on GMT and will need to be adjusted for your local timezone, depending on your specific location and any seasonal adjustments (daylight savings time, etc.).

Parameters: None

Returns: A 32-bit unsigned integer representing the number of seconds since the 'Epoch', or 1 January 1970.

TLS Root Certificate Management

Connecting to secure TLS/SSL based servers requires a root certificate to verify that the certificate data from the remote server is valid. A set of common root certificates is included in the Featherlib by default, but custom certificates can also be added to the chain via the .addRootCA helper function, described below.

See the AdafruitTCP documention for more information on TLS and connecting to secure servers.

Default Root Certificates

By default, the following root certificates are included in Featherlib, meaning you only need to add a root certificate authority if it isn't included in the list below.

These default root certificates cover many common websites without any additional effort on your part:

Baltimore CyberTrust Root

adafruit-download.s3.amazonaws.com (may include other Amazon S3 servers)

DigiCert High Assurance EV Root CA

twitter.com
facebook.com
github.com

GeoTrust Global CA

google.com

GeoTrust Primary Certification Authority - G3

adafruit.com

Starfield Services Root Certificate Authority - G2

aws.amazon.com

bool useDefaultRootCA ( bool enabled )

Enables the default list of root CAs in FeatherLib.

Note: These will be enabled automatically by default if you try to use the .connectSSL functions without having previously added any custom root CAs via .addRootCA. This function is provided primarily to disable the default root certificates since they consume a reasonable chunk of heap memory.

Parameters:

enabled: Set this to 'true' (1) to enable the default root CA list, or 'false' (0) to disable them.

Returns: 'True' (1) if the operation succeeded, otherwise 'false' (0).

The default root CA list will be enabled by default unless Feather.enableRootCA(false) or Feather.clearRootCA() is called explicitly.

bool initRootCA (void)

This function allocates memory for the default list of root certificates and any custom root certificates present.

Normally this function never needs to be called directly, and will be call on an as-needed bases by .addRootCA or .connectSSL. It is provided as a public function so that other classes can have access to it (AdafruitTCP, etc.).

Parameters: None

Returns: 'True' (1) if the root CA initialisation was successful, otherwise 'false' (0).

bool addRootCA (uint8_t const* root_ca, uint16_t len)

This will add the supplied root certificate to the default root certificate list. The combined root list (default plus custom root CAs) will be used when trying to verify any certificate chains provided by a remote secure server.

The root certificate chain suppied via 'root_ca' can contain more than one certificate, but must be a byte array converted from a binary .der file, generated using the python tool included in the '/tools/pycert' folder of the board support package.

Parameters:

root_ca: A pointer to the .der file byte array generated by `/tools/pycert/pycert.py'
len: The size in bytes of the .der byte array

Returns: 'True' (1) if the root certificate chain was successfully set, otherwise 'false' (0).

bool clearRootCA ( void )

Clears any root certificates currently used by the system (freeing up associated heap memory in FeatherLib).

Parameters: None

Returns: 'True' (1) if the operation succeeded, otherwise 'false' (0).

Print Helpers

The following functions are provided to print out common data and simplify user sketches:

void printVersions (Print& p = Serial)

Displays the bootloader and firmware versions used by the WICED Feather in the following order:

Bootloader version
Broadcom WICED SDK version
FeatherLib version
Arduino (User Code) version

Parameters:

p: The 'Print' implementation to use. Leave this field empty and it will default to 'Serial' which is used for the Serial Monitor output.

Returns: Nothing.

void printNetwork (Print& p = Serial)

Displays the following network details when connected to an AP:

SSID Name
SSID Encryption Method
MAC Address
Local IP Address
Gateway Address
Subnet Mask

Parameters:

p: The 'Print' implementation to use. Leave this field empty and it will default to 'Serial' which is used for the Serial Monitor output.

Returns: Nothing.

void printEncryption (int32_t enc, Print& p = Serial)

Displays a string that corresponds to the specified encryption type (see .encryptionType elsewhere in this class):

Parameters:

enc: The security encryption type used by the AP
p: The 'Print' implementation to us. Leave this field empty and it will default to 'Serial' which is used for the Serial Monitor output.

Returns: Nothing

Page last edited February 11, 2016

AdafruitFeather

AdafruitFeather API

Firmware Version Management

char const* bootloaderVersion ( void )

char const* sdkVersion ( void )

char const* firmwareVersion ( void )

char const* arduinoVersion ( void )

Scanning

int scanNetworks (wl_ap_info_t ap_list[], uint8_t max_ap)

Connecting

bool connect ( void )

bool connect ( const char *ssid )

bool connect ( const char *ssid, const char *key, int enc_type = ENC_TYPE_AUTO )

bool begin ( void )

bool begin ( const char *ssid )

bool begin ( const char *ssid, const char *key, int enc_type = ENC_TYPE_AUTO )

void disconnect (void)

Network and Connection Details

bool connected ( void );

uint8_t* macAddress ( uint8_t *mac );

uint32_t localIP ( void );

uint32_t subnetMask ( void );

uint32_t gatewayIP ( void );

char* SSID ( void );

int32_t RSSI ( void );

int32_t encryptionType ( void );

uint8_t* BSSID ( uint8_t* bssid );

DNS Lookup

IPAddress hostByName ( const char* hostname )

bool hostByName ( const char* hostname, IPAddress& result )

bool hostByName ( const String &hostname, IPAddress& result )

Ping

uint32_t ping (char const* host)

uint32_t ping (IPAddress ip)

Factory Reset

void factoryReset ( void )

void nvmReset ( void )

Hardware Random Number Generator

bool randomNumber ( uint32_t* random32bit )

Real Time Clock

bool getISO8601Time ( iso8601_time_t* iso8601_time )

uint32_t getUtcTime ( void )

TLS Root Certificate Management

Default Root Certificates

bool useDefaultRootCA ( bool enabled )

bool initRootCA (void)

bool addRootCA (uint8_t const* root_ca, uint16_t len)

bool clearRootCA ( void )

Print Helpers

void printVersions (Print& p = Serial)

void printNetwork (Print& p = Serial)

void printEncryption (int32_t enc, Print& p = Serial)

Search

Categories

bool connect ( const char ssid, const char key, int enc_type = ENC_TYPE_AUTO )

bool begin ( const char ssid, const char key, int enc_type = ENC_TYPE_AUTO )