WiFi

setCredentials()

WiFi.setCredentials, setCredentials

Allows the application to set credentials for the Wi-Fi network from within the code. These credentials will be added to the device's memory, and the device will automatically attempt to connect to this network in the future.

  • The Photon and P1 remember the 5 most recently set credentials.
  • The Photon and P1 can store one set of WPA Enterprise credentials in Device OS 0.7.0 and later.
  • The Argon remembers the 10 most recently set credentials.
  • The Argon does not support WPA Enterprise.
// Connects to an unsecured network.
WiFi.setCredentials(ssid);
WiFi.setCredentials("My_Router_Is_Big");

// Connects to a network secured with WPA2 credentials.
WiFi.setCredentials(ssid, password);
WiFi.setCredentials("My_Router", "mypasswordishuge");

// Connects to a network with a specified authentication procedure.
// Options are WPA2, WPA, or WEP.
WiFi.setCredentials(ssid, password, auth);
WiFi.setCredentials("My_Router", "wepistheworst", WEP);

When used with hidden or offline networks, the security cipher is also required.


// for hidden and offline networks on the Photon, the security cipher is also needed
// Cipher options are WLAN_CIPHER_AES, WLAN_CIPHER_TKIP and WLAN_CIPHER_AES_TKIP
WiFi.setCredentials(ssid, password, auth, cipher);
WiFi.setCredentials("SSID", "PASSWORD", WPA2, WLAN_CIPHER_AES);
// Connects to a network with an authentication procedure specified by WiFiCredentials object
WiFi.setCredentials(credentials);
WiFiCredentials credentials;
credentials.setSsid("My_Router")
           .setSecurity(WEP)
           .setPassword("wepistheworst");
WiFi.setCredentials(credentials);

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.


Since 0.7.0:

Note:

WPA Enterprise is only supported on the Photon and P1 (Gen 2). It is not supported on the Argon (Gen 3).

Credentials can be set using WiFiCredentials class.

For information on setting up WPA2 Enterprise from the Particle CLI, see this article.

// WPA2 Enterprise with EAP-TLS

// We are setting WPA2 Enterprise credentials
WiFiCredentials credentials("My_Enterprise_AP", WPA2_ENTERPRISE);
// EAP type: EAP-TLS
credentials.setEapType(WLAN_EAP_TYPE_TLS);
// Client certificate in PEM format
credentials.setClientCertificate("-----BEGIN CERTIFICATE-----\r\n" \
                                 /* ... */ \
                                 "-----END CERTIFICATE-----\r\n\r\n"
                                );
// Private key in PEM format
credentials.setPrivateKey("-----BEGIN RSA PRIVATE KEY-----\r\n" \
                          /* ... */ \
                          "-----END RSA PRIVATE KEY-----\r\n\r\n"
                         );
// Root (CA) certificate in PEM format (optional)
credentials.setRootCertificate("-----BEGIN CERTIFICATE-----\r\n" \
                               /* ... */ \
                               "-----END CERTIFICATE-----\r\n\r\n"
                              );
// EAP outer identity (optional, default - "anonymous")
credentials.setOuterIdentity("anonymous");
// Save credentials
WiFi.setCredentials(credentials);
// WPA Enterprise with PEAP/MSCHAPv2

// We are setting WPA Enterprise credentials
WiFiCredentials credentials("My_Enterprise_AP", WPA_ENTERPRISE);
// EAP type: PEAP/MSCHAPv2
credentials.setEapType(WLAN_EAP_TYPE_PEAP);
// Set username
credentials.setIdentity("username");
// Set password
credentials.setPassword("password");
// Set outer identity (optional, default - "anonymous")
credentials.setOuterIdentity("anonymous");
// Root (CA) certificate in PEM format (optional)
credentials.setRootCertificate("-----BEGIN CERTIFICATE-----\r\n" \
                               /* ... */ \
                               "-----END CERTIFICATE-----\r\n\r\n"
                              );
// Save credentials
WiFi.setCredentials(credentials);

Parameters:

This function returns true if credentials were successfully saved, or false in case of an error.

Note: Setting WPA/WPA2 Enterprise credentials requires use of WiFiCredentials class.

Note: In order for WiFi.setCredentials() to work, the Wi-Fi module needs to be on (if switched off or disabled via non_AUTOMATIC SYSTEM_MODEs call WiFi.on()).