Cellular

setBandSelect()

Cellular::setBandSelect, setBandSelect, Cellular.setBandSelect

Since 0.5.0: Sets the cellular bands currently set in the modem. Bands are the carrier frequencies used to communicate with the cellular network.

Caution: The Band Select API is an advanced feature designed to give users selective frequency control over their device. When changing location or between cell towers, you may experience connectivity issues if you have only set one specific frequency for use. Because these settings are permanently saved in non-volatile memory, it is recommended to keep the factory default value of including all frequencies with mobile applications. Only use the selective frequency control for stationary applications, or for special use cases.

  • Make sure to set the count to the appropriate number of bands set in the CellularBand object before calling setBandSelect().
  • Use the .isBand(int) helper function to determine if an integer value is a valid band. It still may not be valid for the particular modem you are using, in which case setBandSelect() will return false and .ok will also be set to false.
  • When trying to set bands that are already set, they will not be written to Non-Volatile Memory (NVM) again.
  • When updating the bands in the modem, they will be saved to NVM and will be remain as set when the modem power cycles.
  • Setting .band[0] to BAND_0 or BAND_DEFAULT and .count to 1 will restore factory defaults.

There are two supported functions for setting bands, one uses the CellularBand object, and the second allow you to pass in a comma delimited string of bands:

bool Cellular.setBandSelect(const char* band_set);

bool Cellular.setBandSelect(CellularBand &band_set);

// SYNTAX
CellularBand band_set;
Cellular.setBandSelect(band_set);

// or

Cellular.setBandSelect("850,1900"); // set two bands
Cellular.setBandSelect("0"); // factory defaults
// EXAMPLE
Serial.println("Setting bands to 850 only");
CellularBand band_set;
band_set.band[0] = BAND_850;
band_set.band[1] = BAND_1900;
band_set.count = 2;
if (Cellular.setBandSelect(band_set)) {
    Serial.print(band_set);
    Serial.println(" band(s) set! Value will be saved in NVM when powering off modem.");
}
else {
    Serial.print(band_set);
    Serial.println(" band(s) not valid! Use getBandAvailable() to query for valid bands.");
}
// EXAMPLE
Serial.println("Restoring factory defaults with the CellularBand object");
CellularBand band_set;
band_set.band[0] = BAND_DEFAULT;
band_set.count = 1;
if (Cellular.setBandSelect(band_set)) {
    Serial.println("Factory defaults set! Value will be saved in NVM when powering off modem.");
}
else {
    Serial.println("Restoring factory defaults failed!");
}
// EXAMPLE
Serial.println("Restoring factory defaults with strings");
if (Cellular.setBandSelect("0")) {
    Serial.println("Factory defaults set! Value will be saved in NVM when powering off modem.");
}
else {
    Serial.println("Restoring factory defaults failed!");
}

Gen 2 Devices:

Band available and band select APIs are only available on Gen 2 cellular devices (Electron and E Series).