Cellular

setCredentials()

Cellular.setCredentials, setCredentials

Sets 3rd party SIM credentials for the Cellular network from within the user application.

Only a subset of Particle cellular devices are able to use a plastic 4FF nano SIM card from a 3rd-party carrier. This table lists external SIM capability and includes the Electron and Boron only. There are also limits on the number of devices with 3rd-party SIM cards in an account. For more information, see the 3rd-party SIM guide.

Device Internal SIM SIM Card Slot APN Saved
Boron 2G/3G (BRN310)
Boron LTE (BRN402)
Electron 3G Americas (E260)    
Electron 3G Europe/Asia/Africa (E270)    
Electron 2G (E350)    
Electron LTE (ELC402)   n/a

Gen 3 Devices (Boron):

Gen 3 devices (Boron 2G/3G, Boron LTE) have both an internal (MFF2 SMD) SIM and an external 4FF nano SIM card slot that can be used for a plastic nano SIM card.

  • You must select which SIM to use in software, it does not automatically switch on Gen 3 devices.
  • The APN is saved in configuration flash and you only need to set it once.
  • The keep-alive is not saved so you will need to set that from your user firmware.
  • On the Boron LTE you must also remove the external SIM card when switching to the internal SIM in software.

On Gen 3 devices, cellular credentials added to the device's non-volatile memory and only need to be set once. The setting will be preserved across reset, power down, and firmware upgrades.

This is different than the Electron and E series where you must call cellular_credentials_set() from all user firmware.

You may set credentials in 3 different ways:

  • APN only
  • USERNAME & PASSWORD only
  • APN, USERNAME & PASSWORD

The following example can be copied to a file called setcreds.ino and compiled and flashed to your device over USB via the Particle CLI. With your device in DFU mode, the command for this is:

particle compile electron setcreds.ino --saveTo firmware.bin && particle flash --local firmware.bin

SYSTEM_MODE(SEMI_AUTOMATIC);

void setup() {
    // Clears any existing credentials. Use this to restore the use of the Particle SIM.
    Cellular.clearCredentials();

    // You should only use one of the following three commands.
    // Only one set of credentials can be stored.

    // Connects to a cellular network by APN only
    Cellular.setCredentials("broadband");

    // Connects to a cellular network with USERNAME and PASSWORD only
    Cellular.setCredentials("username", "password");

    // Connects to a cellular network with a specified APN, USERNAME and PASSWORD
    Cellular.setCredentials("some-apn", "username", "password");

    Particle.connect();
}

void loop() {
}