WiFi

WiFiCredentials class

This class allows to define WiFi credentials that can be passed to WiFi.setCredentials() function.

// EXAMPLE - defining and using WiFiCredentials class

void setup() {
    // Ensure that WiFi module is on
    WiFi.on();
    // Set up WPA2 access point "My AP" with password "mypassword" and AES cipher
    WiFiCredentials credentials("My AP", WPA2);
    credentials.setPassword("mypassword")
               .setCipher(WLAN_CIPHER_AES);
    // Connect if settings were successfully saved
    if (WiFi.setCredentials(credentials)) {
        WiFi.connect();
        waitFor(WiFi.ready, 30000);
        Particle.connect();
        waitFor(Particle.connected, 30000);
    }
}

void loop() {
}

WiFiCredentials()

Constructs an instance of the WiFiCredentials class. By default security type is initialized to unsecured (UNSEC).

// SYNTAX
WiFiCredentials credentials(SecurityType security = UNSEC); // 1
WiFiCredentials credentials(const char* ssid, SecurityType security = UNSEC); // 2
// EXAMPLE - constructing WiFiCredentials instance
// Empty instance, security is set to UNSEC
WiFiCredentials credentials;
// No SSID, security is set to WPA2
WiFiCredentials credentials(WPA2);
// SSID set to "My AP", security is set to UNSEC
WiFiCredentials credentials("My AP");
// SSID set to "My WPA AP", security is set to WPA
WiFiCredentials credentials("My AP", WPA);

Parameters:

setSsid()

Sets access point SSID.

// SYNTAX
WiFiCredentials& WiFiCredentials::setSsid(const char* ssid);
// EXAMPLE - setting ssid
WiFiCredentials credentials;
credentials.setSsid("My AP");

Parameters:

  • ssid: SSID (string)

setSecurity()

Sets access point security type.

// SYNTAX
WiFiCredentials& WiFiCredentials::setSecurity(SecurityType security);
// EXAMPLE - setting security type
WiFiCredentials credentials;
credentials.setSecurity(WPA2);

Parameters:

setCipher()

Sets access point cipher.

// SYNTAX
WiFiCredentials& WiFiCredentials::setCipher(WLanSecurityCipher cipher);
// EXAMPLE - setting cipher
WiFiCredentials credentials;
credentials.setCipher(WLAN_CIPHER_AES);

Parameters:

setPassword()

Sets access point password.

When configuring credentials for WPA/WPA2 Enterprise access point with PEAP/MSCHAPv2 authentication, this function sets password for username set by setIdentity().

// SYNTAX
WiFiCredentials& WiFiCredentials::setPassword(const char* password);
// EXAMPLE - setting password
WiFiCredentials credentials("My AP", WPA2);
credentials.setPassword("mypassword");

Parameters:

  • password: WEP/WPA/WPA2 access point password, or user password for PEAP/MSCHAPv2 authentication (string)

The password is limited to 64 7-bit ASCII characters. If you pass in a longer password, only the first 64 characters will be saved.

setHidden()

Since 5.5.0:

Allows connecting to a Wi-Fi network with a hidden SSID.

Normally, the P2, Photon 2, M-SoM, and Argon do a Wi-Fi scan and compare this against the list of configured networks to choose a network to connect to. If no connection made to non-hidden networks, then an attempt is made to connect to each hidden network. This will be slower, as each connection attempt needs to time out.

// PROTOTYPE
virtual WiFiCredentials& setHidden(bool hidden = true) 

// EXAMPLE
WiFiCredentials creds;
creds.setSsid("My Secret Network");
creds.setPassword("secret");
creds.setSecurity(SecurityType::WPA2);
creds.setHidden(true);
WiFi.setCredentials(creds);

setValidate()

Since 5.8.0:

When set, validate that the Wi-Fi network can be connected to before setting the credentials. The default is to save without validating when using WiFi.setCredentials().

If Wi-Fi is off, it will be turned on to validate credentials.

If Wi-Fi is on and connected, the current network will be disconnected (including the cloud connection, if connected) to attempt to connect to the new network.

// PROTOTYPE
virtual WiFiCredentials& setValidate(bool validate = true)

// EXAMPLE
WiFiCredentials creds;
creds.setSsid("My Network");
creds.setPassword("secret");
creds.setSecurity(SecurityType::WPA2);
creds.setValidate(true);
WiFi.setCredentials(creds);

setChannel()

Sets access point channel.

// SYNYAX
WiFiCredentials& WiFiCredentials::setChannel(int channel);
// EXAMPLE - setting channel
WiFiCredentials credentials("My AP");
credentials.setChannel(10);

Parameters:

  • channel: WLAN channel (int)

setEapType()

Sets EAP type.

// SYNTAX
WiFiCredentials& WiFiCredentials::setEapType(WLanEapType type);
// EXAMPLE - setting EAP type
WiFiCredentials credentials("My Enterprise AP", WPA2_ENTERPRISE);
credentials.setEapType(WLAN_EAP_TYPE_PEAP);

Parameters:

  • type: EAP type. See WLanEapType enum for a list of supported values.

This is a feature of WPA Enterprise and is only available on the Photon and P1 (Gen 2). It is not available on the Argon (Gen 3), P2, or Photon 2.

setIdentity()

Sets EAP inner identity (username in case of PEAP/MSCHAPv2).

// SYNTAX
WiFiCredentials& WiFiCredentials::setIdentity(const char* identity);
// EXAMPLE - setting PEAP identity (username)
WiFiCredentials credentials("My Enterprise AP", WPA2_ENTERPRISE);
credentials.setEapType(WLAN_EAP_TYPE_PEAP);
credentials.setIdentity("username");

Parameters:

  • identity: inner identity (string)

setOuterIdentity()

Sets EAP outer identity. Defaults to "anonymous".

// SYNTAX
WiFiCredentials& WiFiCredentials::setOuterIdentity(const char* identity);
// EXAMPLE - setting outer identity
WiFiCredentials credentials("My Enterprise AP", WPA2_ENTERPRISE);
credentials.setOuterIdentity("notanonymous");

Parameters:

  • identity: outer identity (string)

This is a feature of WPA Enterprise and is only available on the Photon and P1 (Gen 2). It is not available on the Argon (Gen 3), P2, or Photon 2.

setClientCertificate()

Sets client certificate used for EAP-TLS authentication.

// SYNTAX
WiFiCredentials& WiFiCredentials::setClientCertificate(const char* cert);
// EXAMPLE - setting client certificate
WiFiCredentials credentials;
credentials.setClientCertificate("-----BEGIN CERTIFICATE-----\r\n" \
                                 /* ... */ \
                                 "-----END CERTIFICATE-----\r\n\r\n"
                                );

Parameters:

  • cert: client certificate in PEM format (string)

This is a feature of WPA Enterprise and is only available on the Photon and P1 (Gen 2). It is not available on the Argon (Gen 3), P2, or Photon 2.

setPrivateKey()

Sets private key used for EAP-TLS authentication.

// SYNTAX
WiFiCredentials& WiFiCredentials::setPrivateKey(const char* key);
// EXAMPLE - setting private key
WiFiCredentials credentials;
credentials.setPrivateKey("-----BEGIN RSA PRIVATE KEY-----\r\n" \
                          /* ... */ \
                          "-----END RSA PRIVATE KEY-----\r\n\r\n"
                         );

Parameters:

  • key: private key in PEM format (string)

This is a feature of WPA Enterprise and is only available on the Photon and P1 (Gen 2). It is not available on the Argon (Gen 3), P2, or Photon 2.

setRootCertificate()

Sets one more root (CA) certificates.

// SYNTAX
WiFiCredentials& WiFiCredentials::setRootCertificate(const char* cert);
// EXAMPLE - setting one root certificate
WiFiCredentials credentials;
credentials.setClientCertificate("-----BEGIN CERTIFICATE-----\r\n" \
                                 /* ... */ \
                                 "-----END CERTIFICATE-----\r\n\r\n"
                                );
// EXAMPLE - setting multiple root certificates
WiFiCredentials credentials;
credentials.setClientCertificate("-----BEGIN CERTIFICATE-----\r\n" \
                                 /* ... */ \
                                 "-----END CERTIFICATE-----\r\n"
                                 "-----BEGIN CERTIFICATE-----\r\n" \
                                 /* ... */ \
                                 "-----END CERTIFICATE-----\r\n\r\n"
                                );

Parameters:

  • cert: one or multiple concatenated root certificates in PEM format (string)

This is a feature of WPA Enterprise and is only available on the Photon and P1 (Gen 2). It is not available on the Argon (Gen 3), P2, or Photon 2.