Cellular

getBandAvailable()

Cellular::getBandAvailable, getBandAvailable, Cellular.getBandAvailable

Since 0.5.0:

Gen 2 Devices (E-Series, Electron, Photon, and P2; does not include E404X):

Gets the cellular bands currently available in the modem. Bands are the carrier frequencies used to communicate with the cellular network. Some modems have 2 bands available (U260/U270) and others have 4 bands (G350).

To use the band select API, an instance of the CellularBand type needs to be created to read or set bands. All band select API functions and the CellularBand object itself return bool - true indicating the last operation was successful and the CellularBand object was updated. For set and get functions, CellularBand is passed by reference Cellular.getBandSelect(CellularBand&); and updated by the function. There is 1 array, 1 integer, 1 boolean and 1 helper function within the CellularBand object:

• ok: (bool) a boolean value false when the CellularBand object is initially created, and true after the object has been successfully updated by the API. If the last reading failed and the bands were not changed from their previous value, this value is set to false.
• count: (int) a value from 0-5 that is the number of currently selected bands retrieved from the modem after getBandAvailble() or getBandSelect() is called successfully.
• band[5]: (MDM_Band[]) array of up to 5 MDM_Band enumerated types. Available enums are: BAND_DEFAULT, BAND_0, BAND_700, BAND_800, BAND_850, BAND_900, BAND_1500, BAND_1700, BAND_1800, BAND_1900, BAND_2100, BAND_2600. All elements set to 0 when CellularBand object is first created, but after getBandSelect() is called successfully the currently selected bands will be populated started with index 0, i.e., (.band[0]). Can be 5 values when getBandAvailable() is called on a G350 modem, as it will return factory default value of 0 as an available option, i.e., 0,850,900,1800,1900.
• bool isBand(int): helper function built into the CellularBand type that can be used to check if an integer is a valid band. This is helpful if you would like to test a value before manually setting a band in the .band[] array.

CellularBand is a Printable object, so using it directly with Serial.println(CellularBand); will print the number of bands that are retrieved from the modem. This will be output as follows:

// EXAMPLE PRINTABLE
CellularBand band_sel;
// populate band object with fake data
band_sel.band[0] = BAND_850;
band_sel.band[1] = BAND_1900;
band_sel.count = 2;
Log.info(band_sel);

// OUTPUT: band[0],band[1]
850,1900

Here's a full example using all of the functions in the Cellular Band Select API

There is one supported function for getting available bands using the CellularBand object:

bool Cellular.getBandAvailable(CellularBand &band_avail);

Note: getBandAvailable() always sets the first band array element .band[0] as 0 which indicates the first option available is to set the bands back to factory defaults, which includes all bands.

// SYNTAX
CellularBand band_avail;
Cellular.getBandAvailable(band_avail);

// EXAMPLE
CellularBand band_avail;
if (Cellular.getBandSelect(band_avail)) {
    Serial.print("Available bands: ");
    for (int x=0; x<band_avail.count; x++) {
        Serial.printf("%d", band_avail.band[x]);
        if (x+1 < band_avail.count) Serial.printf(",");
    }
    Serial.println();
}
else {
    Serial.printlnf("Bands available not retrieved from the modem!");
}