XBee Cellular topic

Introduction

**_All_** Digi cellular modems can be implented as a DigiXBeeCellularTransparent object - a subclass of DigiXBee and loggerModem. The "transparent" refers to the Digi name for the operating mode of the module. It is transparent in that data received by the module on the serial interface is output directly the connected client - the module becomes transparent allowing data to pass right through.

The power requirements for the cellular XBee's depend on the specific module. The 3G module must have 2 amps of power available. Most of the others can get by with ~1amp (which is still 2x what a standard USB port of Arduino board can provide.) The LTE-M module can just about almost get by on 500mA, but it definitely not ideal.

Manufacturer Documentation

The Digi product page for the various cellular modules is here: https://www.digi.com/products/embedded-systems/digi-xbee/cellular-modems

Modem Constructor

DigiXBeeCellularTransparent::DigiXBeeCellularTransparent(Stream* modemStream, int8_t powerPin, int8_t statusPin, bool useCTSStatus, int8_t modemResetPin, int8_t modemSleepRqPin, const char* apn, const char* user = NULL, const char* pwd = NULL)

Construct a new Digi XBee Cellular Transparent object.

Parameters
modemStream The Arduino stream instance for serial communication.
powerPin The digital pin number of the mcu pin controlling power to the modem (active HIGH).
statusPin The digital pin number of the mcu pin connected to the modem status output pin.
useCTSStatus True to use the CTS_N/DIO7 pin of the XBee as a status indicator rather than the true status (ON/SLEEP_N/DIO9) pin. This inverts the loggerModem::_statusLevel.
modemResetPin The digital pin number of the pin on the mcu attached the the hard or panic reset pin of the modem.
modemSleepRqPin The digital pin number of a pin on the mcu used to request the modem enter its lowest possible power state.
apn The Access Point Name (APN) for the SIM card.
user The user name, if required, associated with the APN; optional, defaulting to NULL
pwd The password, if required, associated with the APN; optional, defaulting to NULL

The constuctor initializes all of the provided member variables, constructs a loggerModem parent class with the appropriate timing for the module, calls the constructor for a TinyGSM modem on the provided modemStream, and creates a TinyGSM Client linked to the modem.

Should be set to a negative number if the modem should be continuously powered or the power cannot be controlled by the MCU. Should be set to a negative number if the modem status pin cannot be read. This can be either the pin named ON/SLEEP_N/DIO9 or CTS_N/DIO7 pin in Digi's hardware reference. Should be set to a negative number if the modem reset pin is not connected to the MCU. This shold be the pin called RESET_N in Digi's hardware reference. Should be set to a negative number if there is no pin usable for deep sleep modes or it is not accessible to the MCU. This shold be the pin called DTR_N/SLEEP_RQ/DIO8 in Digi's hardware reference.



Example Code

Creating the Modem Object

A transparent-mode Digi cellular module is used in the menu a la carte example.

1// For any Digi Cellular XBee's
2// NOTE: The u-blox based Digi XBee's (3G global and LTE-M global) can be used
3// in either bypass or transparent mode, each with pros and cons
4// The Telit based Digi XBees (LTE Cat1) can only use this mode.
5#include <modems/DigiXBeeCellularTransparent.h>
6
7// NOTE: Extra hardware and software serial ports are created in the "Settings
8// for Additional Serial Ports" section
9const int32_t modemBaud = 9600; // All XBee's use 9600 by default
10
11// Modem Pins - Describe the physical pin connection of your modem to your board
12// NOTE: Use -1 for pins that do not apply
13// The pin numbers here are for a Digi XBee with a Mayfly 0.x and LTE adapter
14// For options https://github.com/EnviroDIY/LTEbee-Adapter/edit/master/README.md
15const int8_t modemVccPin = -1; // MCU pin controlling modem power
16 // Option: modemVccPin = A5, if Mayfly SJ7 is
17 // connected to the ASSOC pin
18const int8_t modemStatusPin = 19; // MCU pin used to read modem status
19// NOTE: If possible, use the `STATUS/SLEEP_not` (XBee pin 13) for status, but
20// the CTS pin can also be used if necessary
21const bool useCTSforStatus = false; // Flag to use the CTS pin for status
22const int8_t modemResetPin = 20; // MCU pin connected to modem reset pin
23const int8_t modemSleepRqPin = 23; // MCU pin for modem sleep/wake request
24const int8_t modemLEDPin =
25 redLED; // MCU pin connected an LED to show modem status
26
27// Network connection information
28const char* apn = "xxxxx"; // APN for GPRS connection
29
30// Create the modem object
31DigiXBeeCellularTransparent modemXBCT(&modemSerial, modemVccPin, modemStatusPin,
32 useCTSforStatus, modemResetPin,
33 modemSleepRqPin, apn);
34// Create an extra reference to the modem by a generic name
35DigiXBeeCellularTransparent modem = modemXBCT;

LTE Network Selection

For LTE boards, it is good practice to select which network you'll be connecting to based on your SIM card and signal availability. Example code for this can also be found in the menulink{setup_xbeec_carrier} example.

1 // Extra modem set-up
2 Serial.println(F("Waking modem and setting Cellular Carrier Options..."));
3 modem.modemWake(); // NOTE: This will also set up the modem
4 // Go back to command mode to set carrier options
5 modem.gsmModem.commandMode();
6 // Carrier Profile - 0 = Automatic selection
7 // - 1 = No profile/SIM ICCID selected
8 // - 2 = AT&T
9 // - 3 = Verizon
10 // NOTE: To select T-Mobile, you must enter bypass mode!
11 modem.gsmModem.sendAT(GF("CP"), 2);
12 modem.gsmModem.waitResponse();
13 // Cellular network technology - 0 = LTE-M with NB-IoT fallback
14 // - 1 = NB-IoT with LTE-M fallback
15 // - 2 = LTE-M only
16 // - 3 = NB-IoT only
17 // NOTE: As of 2020 in the USA, AT&T and Verizon only use LTE-M
18 // T-Mobile uses NB-IOT
19 modem.gsmModem.sendAT(GF("N#"), 2);
20 modem.gsmModem.waitResponse();
21 // Write changes to flash and apply them
22 Serial.println(F("Wait while applying changes..."));
23 // Write changes to flash
24 modem.gsmModem.writeChanges();
25 // Reset the cellular component to ensure network settings are changed
26 modem.gsmModem.sendAT(GF("!R"));
27 modem.gsmModem.waitResponse(30000L);
28 // Force reset of the Digi component as well
29 // This effectively exits command mode
30 modem.gsmModem.sendAT(GF("FR"));
31 modem.gsmModem.waitResponse(5000L);

Classes

class DigiXBeeCellularTransparent
The class for any of Digi Cellular XBee or XBee3 modules operating in Digi's "transparent" mode.