Cellular
setBandSelect()
Since 0.5.0:
Gen 2 Devices (STM32) (E-Series, Electron, Photon, and P2; does not include E404X):
Band available and band select APIs are only available on Gen 2 (Electron and E-Series), and only for 2G/3G, not LTE Cat M1.
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 callingsetBandSelect()
. - 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 casesetBandSelect()
will returnfalse
and.ok
will also be set tofalse
. - 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]
toBAND_0
orBAND_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!");
}