Skip to content

class_tiny_gsm_x_bee

Jump to bottom
Sara Damiano edited this page Sep 11, 2026 · 2 revisions

title: TinyGsmXBee

TinyGsmXBee (class)

Module: TinyGsmXBee

Class for the Digi XBee family of modems.

#include <src/TinyGsmClientXBee.h>

Inherits from TinyGsmModem<TinyGsmXBee, TinyGsmXBeeModemConfig>, TinyGsmGPRS<TinyGsmXBee>, TinyGsmWifi<TinyGsmXBee>, TinyGsmTCP<TinyGsmXBee, TinyGsmXBeeTcpConfig>, TinyGsmSMS<TinyGsmXBee>, TinyGsmBattery<TinyGsmXBee>, TinyGsmTemperature<TinyGsmXBee>

Public Types

Name
class GsmClientXBee
Inner client.
class TinyGsmXBee::GsmClientSecureXBee
Inner secure client.
typedef typename ModemConfig::RegStatus regStatusType

Basic functions

Public Functions

Name
bool begin(const char * pin = nullptr)
Sets up the GSM module.
bool init(const char * pin = nullptr)
Sets up the GSM module.
void sendAT(Args... cmd)
Recursive variadic template to send AT commands.
bool setBaud(uint32_t baud)
Set the module baud rate.
bool setDefaultBaud(uint32_t baud)
Set the default baud rate for the modem, ie, the baud rate that the modem will use after a reset or power cycle.
bool forceModemBaud(StreamObject & at_serial, uint32_t targetBaud)
Attempt to set the modem baud rate by trying set the command to change the baud rate to various common baud rates and seeing if the modem responds to AT commands at that baud rate.
bool testAT(uint32_t timeout_ms = 10000L)
Test response to AT commands.
int8_t waitResponse(uint32_t timeout_ms, String & data, GsmConstStr r1 = ModemConfig::GSM_OK, GsmConstStr r2 = ModemConfig::GSM_ERROR, GsmConstStr r3 = nullptr, GsmConstStr r4 = nullptr, GsmConstStr r5 = nullptr, GsmConstStr r6 = nullptr, GsmConstStr r7 = nullptr, GsmConstStr r8 = nullptr)
Listen for responses to commands and handle URCs.
String getConfiguredModem()
Gets the configured modem manufacture and model based on the compile-time traits.
String getModemInfo()
Asks for modem information via the 3GPP TS 27.007 standard ATI command.
String getModemName()
Get the modem name - a combination of the manufacturer and model, as the modem calls itself.
String getModemManufacturer()
Get the modem manufacturer.
String getModemModel()
Get the modem model.
String getModemRevision()
Get the modem revision information.
String getModemSerialNumber()
Get the modem serial number.
bool factoryDefault()
Reset the module to factory defaults.

Power functions

Public Functions

Name
bool restart(const char * pin = nullptr)
Restart the module.
bool poweroff()
Power off the module.
bool powerOff()
Power off the module.
bool radioOff()
Turn off the module radio.
bool sleepEnable(bool enable = true)
Enable sleep on the module.
bool setPhoneFunctionality(uint8_t fun, bool reset = false)
Set the phone functionality.

Generic network functions

Public Functions

Name
regStatusType getRegistrationStatus()
Get the modem registration status on the network.
bool isNetworkConnected()
Confirm whether the module is currently connected to the GSM/GPRS/LTE network.
bool waitForNetwork(uint32_t timeout_ms = 60000L, bool check_signal = false)
Wait until the module has connected to the network.
int16_t getSignalQuality()
Get the signal quality report.
String getLocalIP()
Get the Local IP address assigned to the module by the network as a String.
IPAddress localIP()
Get the Local IP address assigned to the module by the network as an IPAddress object.

Utilities

Public Functions

Name
void streamWrite(T last)
Write a value to the modem stream.
void streamDump(int16_t expected_len)
Dump the modem stream, completely discarding any data in it without attempting to parse any URC's in it.

SIM card functions

Public Functions

Name
bool simUnlock(const char * pin)
Unlock the SIM card with a PIN code.
String getSimCCID()
Get the SIM card's CCID via AT+CCID.
String getIMEI()
Get the modem's TA Serial Number Identification (IMEI) via AT+GSN.
String getIMSI()
Get the modem's International Mobile Subscriber Identity (IMSI) via AT+CIMI.
SimStatus getSimStatus(uint32_t timeout_ms = 10000L)
Get the SIM card status.

GPRS functions

Public Functions

Name
bool gprsConnect(const char * apn, const char * user = nullptr, const char * pwd = nullptr)
Connect to a GPRS network.
bool gprsDisconnect()
Disconnect from the GPRS network.
bool isGprsConnected()
Check if currently attached to GPRS/EPS service.
String getOperator()
Get the current network operator.
String getProvider()
Get the current network provider.

WiFi functions

Public Functions

Name
bool networkConnect(const char * ssid, const char * pwd)
Connect to a WiFi network.
bool networkDisconnect()
Disconnect from the WiFi network.

Socket listening functions

Public Functions

Name
void maintain()
Maintain the modem connection and check for incoming data.

Text messaging (SMS) functions

Public Functions

Name
String sendUSSD(const String & code)
Send a USSD code to the network.
bool sendSMS(const String & number, const String & text)
Send an SMS message.
bool sendSMS_UTF16(const char *const number, const void * text, size_t len)
Send an SMS message in UTF-16 encoding.

Battery functions

Public Functions

Name
int16_t getBattVoltage()
Get the current battery voltage.
int8_t getBattPercent()
Get the current battery percent.
int8_t getBattChargeState()
Get the battery charging state.
bool getBattStats(int8_t & chargeState, int8_t & percent, int16_t & milliVolts)
Get the all battery state.

Temperature functions

Public Functions

Name
float getTemperature()
Get the modem chip temperature in degrees celsius.

Public Functions

Name
String getBeeName()
Get the name of the XBee module currently in use.
void getSeries(void )
Get the series of the XBee module and store it internally.
void streamClear(void )
Clear out the stream buffer.
bool commandMode(uint8_t retries = 5)
Put the XBee into command mode.
bool writeChanges(void )
Write changes to flash and apply them.
void exitCommand(void )
Exit command mode.
bool exitAndFail(void )
Exit command mode and return false.
String readResponseString(uint32_t timeout_ms = 1000)
Reads a response from the XBee module as a string, waiting up to timeout_ms milliseconds for data to become available.
int16_t readResponseInt(uint32_t timeout = 1000L)
Reads a response from the XBee module as an integer, waiting up to timeout milliseconds for data to become available.
String sendATGetString(GsmConstStr cmd)
Send an AT command to the XBee module and read the response as a string.
bool changeSettingIfNeeded(GsmConstStr cmd, int16_t newValue, uint32_t timeout_ms = 1000L)
Sends an AT command to the XBee module and changes the setting if needed.
bool changeSettingIfNeeded(GsmConstStr cmd, String newValue, uint32_t timeout_ms = 1000L)
Sends an AT command to the XBee module and changes the setting if needed.
bool gotIPforSavedHost()
Verifies if the saved host has a valid IP address.

Public Attributes

Name
Stream & stream
Stream used to communicate with the modem.

Public Types Documentation

classGsmClientXBee

classTinyGsmXBee::GsmClientSecureXBee

typedefregStatusType

;

Public Functions Documentation

functiongetBeeName

String getBeeName()
  • Return: The name of the current XBee module.

functiongetSeries

void getSeries(void )

functionstreamClear

void streamClear(void )

functioncommandMode

bool commandMode(uint8_t retries = 5)

If it is already in command mode, this function will return true. If it is not in command mode, it will attempt to enter command mode.

  • Parameters:
    • retries The number of times to retry entering command mode.
  • Return: True if the XBee is in command mode, false otherwise.

functionwriteChanges

bool writeChanges(void )
  • Return: True if the changes were written and applied successfully, false otherwise.

functionexitCommand

void exitCommand(void )

functionexitAndFail

bool exitAndFail(void )

This is a convenience function for use in functions that need to exit command mode and return false on failure.

  • Return: False, always.

functionreadResponseString

String readResponseString(uint32_t timeout_ms = 1000)
  • Parameters:
    • timeout_ms The maximum time to wait for a response, in milliseconds.
  • Return: The response from the XBee module as a string.

functionreadResponseInt

int16_t readResponseInt(uint32_t timeout = 1000L)
  • Parameters:
    • timeout The maximum time to wait for a response, in milliseconds.
  • Return: The response from the XBee module as an integer.

functionsendATGetString

String sendATGetString([GsmConstStr](../files/_tiny_gsm_common_8h.md#a9c8c9c8249f99863e157f8fae76e7cab) cmd)
  • Parameters:
    • cmd The AT command to send.
  • Return: The response from the XBee module as a string.

functionchangeSettingIfNeeded

bool changeSettingIfNeeded([GsmConstStr](../files/_tiny_gsm_common_8h.md#a9c8c9c8249f99863e157f8fae76e7cab) cmd, int16_t newValue, uint32_t timeout_ms = 1000L)
  • Parameters:
    • cmd The AT command to send.
    • newValue The new value to set.
    • timeout_ms The maximum time to wait for a response, in milliseconds.
  • Return: True if the setting was changed successfully, false otherwise.

functionchangeSettingIfNeeded

bool changeSettingIfNeeded([GsmConstStr](../files/_tiny_gsm_common_8h.md#a9c8c9c8249f99863e157f8fae76e7cab) cmd, String newValue, uint32_t timeout_ms = 1000L)
  • Parameters:
    • cmd The AT command to send.
    • newValue The new value to set.
    • timeout_ms The maximum time to wait for a response, in milliseconds.
  • Return: True if the setting was changed successfully, false otherwise.

functiongotIPforSavedHost

bool gotIPforSavedHost()
  • Return: True if the saved host has a valid IP address, false otherwise.

Public Attributes Documentation

variablestream

Stream & stream;

Public Functions Documentation

Basic functions

functionbegin

bool begin(const char * pin = nullptr)
  • Parameters:
    • pin A pin code to unlock the SIM, if necessary
  • Return: True if the module was set up as expected, false otherwise.

functioninit

bool init(const char * pin = nullptr)
  • Parameters:
    • pin A pin code to unlock the SIM, if necessary
  • Return: True if the module was set up as expected, false otherwise.

functionsendAT

void sendAT(Args... cmd)
  • Parameters:
    • cmd The commands to send

functionsetBaud

bool setBaud(uint32_t baud)

Note

After setting and applying the new baud rate, you will have to end() and begin() the serial object.

  • Parameters:
    • baud The baud rate to use
  • Return: True if the baud rate was set successfully, false otherwise.

functionsetDefaultBaud

bool setDefaultBaud(uint32_t baud)
  • Parameters:
    • baud The baud rate to set the modem to use after a reset or power cycle.
  • Return: True if the command was successful, false otherwise.

functionforceModemBaud

bool forceModemBaud(StreamObject & at_serial, uint32_t targetBaud)

Unlike TinyGsmAutoBaud, this function will try to set the baud rate on the modem and will attempt to communicate with the modem at the new baud rate whether or not it gets a response at the old baud rate. This is useful in cases where the modem is set to a baud rate that is just a little too fast for the processor, where you might get a response but it will be garbled and not recognized as a response, because in this case you still want to try to set the baud rate.

Note

After setting and applying the new baud rate, you will have to end() and begin() the serial object.

  • Parameters:
    • at_serial The serial object to use for communicating with the modem
    • targetBaud The final baud rate to try to set the modem to
  • Return: True if the modem responded after the baud rate was set, false otherwise.

functiontestAT

bool testAT(uint32_t timeout_ms = 10000L)
  • Parameters:
    • timeout_ms the amount of time to test for; optional with a default value of 10s.
  • Return: True if the module responded to AT commands, false otherwise.

functionwaitResponse

int8_t waitResponse(uint32_t timeout_ms, String & data, [GsmConstStr](../files/_tiny_gsm_common_8h.md#a9c8c9c8249f99863e157f8fae76e7cab) r1 = <a href="struct_tiny_gsm_x_bee_modem_config.html#acf5b52d6b960e96077f239e940a1fa69" class="m-doc">ModemConfig::<wbr />GSM_OK</a>, [GsmConstStr](../files/_tiny_gsm_common_8h.md#a9c8c9c8249f99863e157f8fae76e7cab) r2 = <a href="struct_tiny_gsm_x_bee_modem_config.html#a37e3eeea0e47ac734d764f3edea70907" class="m-doc">ModemConfig::<wbr />GSM_ERROR</a>, [GsmConstStr](../files/_tiny_gsm_common_8h.md#a9c8c9c8249f99863e157f8fae76e7cab) r3 = nullptr, [GsmConstStr](../files/_tiny_gsm_common_8h.md#a9c8c9c8249f99863e157f8fae76e7cab) r4 = nullptr, [GsmConstStr](../files/_tiny_gsm_common_8h.md#a9c8c9c8249f99863e157f8fae76e7cab) r5 = nullptr, [GsmConstStr](../files/_tiny_gsm_common_8h.md#a9c8c9c8249f99863e157f8fae76e7cab) r6 = nullptr, [GsmConstStr](../files/_tiny_gsm_common_8h.md#a9c8c9c8249f99863e157f8fae76e7cab) r7 = nullptr, [GsmConstStr](../files/_tiny_gsm_common_8h.md#a9c8c9c8249f99863e157f8fae76e7cab) r8 = nullptr)
  • Parameters:
    • timeout_ms The time to wait for a response
    • data A string of data to fill in with response results
    • r1 The first output to test against, optional with a default value of "OK"
    • r2 The second output to test against, optional with a default value of "ERROR"
    • r3 The third output to test against, optional with a default value of nullptr
    • r4 The fourth output to test against, optional with a default value of nullptr
    • r5 The fifth output to test against, optional with a default value of nullptr
    • r6 The sixth output to test against, optional with a default value of nullptr
    • r7 The seventh output to test against, optional with a default value of nullptr
    • r8 The eighth output to test against, optional with a default value of nullptr
  • Return: the index of the response input

functiongetConfiguredModem

String getConfiguredModem()

Tip

This does not query the modem for its actual manufacture and model, but rather returns the values that were set at compile time.

  • Return: The configured modem manufacture and model based on the compile-time traits.

functiongetModemInfo

String getModemInfo()

Note

The actual value and style of the response is quite varied

  • Return: Some info about the GSM module.

functiongetModemName

String getModemName()
  • Return: The modem name

functiongetModemManufacturer

String getModemManufacturer()
  • Return: The modem manufacturer

functiongetModemModel

String getModemModel()
  • Return: The modem model, as it calls itself

functiongetModemRevision

String getModemRevision()

What is returned as the revision may be either a hardware or a firmware version or some combination of both.

  • Return: The modem revision information

functiongetModemSerialNumber

String getModemSerialNumber()

This is usually equivalent to the IMEI for cellular modems and the MAC address for WiFi modems.

  • Return: The modem serial number

functionfactoryDefault

bool factoryDefault()

This generally restarts the module as well.

  • Return: True if the module successfully reset to default, false otherwise.

Power functions

functionrestart

bool restart(const char * pin = nullptr)
  • Parameters:
    • pin A pin code to unlock the SIM, if necessary
  • Return: True if the module was successfully restarted, false otherwise.

functionpoweroff

bool poweroff()

Deprecated: deprecated

  • Deprecated: deprecated
  • Return: True if the module was successfully powered down, false otherwise.

functionpowerOff

bool powerOff()
  • Return: True if the module was successfully powered down, false otherwise.

functionradioOff

bool radioOff()
  • Return: True if the module radio was successfully turned off, false otherwise.

functionsleepEnable

bool sleepEnable(bool enable = true)

For some modules this immediately puts the module to sleep, for others this sets them to be able to sleep based on pin levels.

  • Parameters:
    • enable True to enable sleep, false to disable
  • Return: True if sleep was successfully enabled or disabled, false otherwise.

functionsetPhoneFunctionality

bool setPhoneFunctionality(uint8_t fun, bool reset = false)
  • Parameters:
    • fun The phone functionality setting. The value and meaning of this varies by module; check your documentation.
    • reset True to reset the module before changing the functionality.
  • Return: True if the phone functionality was successfully changed, false otherwise.

Generic network functions

functiongetRegistrationStatus

regStatusType getRegistrationStatus()
  • Return: The modem-specific registration status value.

functionisNetworkConnected

bool isNetworkConnected()
  • Return: True if the module is connected to the network, false otherwise.

functionwaitForNetwork

bool waitForNetwork(uint32_t timeout_ms = 60000L, bool check_signal = false)
  • Parameters:
    • timeout_ms The time to wait for attachment in milliseconds. Optional with a default value of 1 minute.
    • check_signal True to alternate between checking for connection and checking the signal strength.
  • Return: True if the module is now connected to the network, false otherwise.

functiongetSignalQuality

int16_t getSignalQuality()

This is often a "CSQ" value ranging from 0 to 32, but may be an RSSI or a percent.

  • Return: The signal quality

functiongetLocalIP

String getLocalIP()
  • Return: The local IP address

functionlocalIP

IPAddress localIP()
  • Return: The local IP address

Utilities

functionstreamWrite

void streamWrite(T last)
  • Parameters:
    • last The value to write.

functionstreamDump

void streamDump(int16_t expected_len)

This is good for discarding an expected number of characters from the stream without waiting a full timeout for each character.

Todo: todo

  • Parameters:
    • expected_len The number of characters to discard from the stream.

SIM card functions

functionsimUnlock

bool simUnlock(const char * pin)
  • Parameters:
    • pin The PIN code to unlock the SIM card.
  • Return: True if the SIM card was successfully unlocked, false otherwise

functiongetSimCCID

String getSimCCID()
  • Return: The SIM card's CCID as a String.

functiongetIMEI

String getIMEI()
  • Return: The modem's IMEI as a String.

functiongetIMSI

String getIMSI()
  • Return: The modem's IMSI as a String.

functiongetSimStatus

[SimStatus](../files/_tiny_gsm_g_p_r_s_8tpp.md#a88faf9e645594ddb7300d159bc0fe5e0) getSimStatus(uint32_t timeout_ms = 10000L)
  • Parameters:
    • timeout_ms The timeout in milliseconds to wait for a response.
  • Return: The SIM card status as a SimStatus enum value.

GPRS functions

functiongprsConnect

bool gprsConnect(const char * apn, const char * user = nullptr, const char * pwd = nullptr)
  • Parameters:
    • apn The Access Point Name (APN) of the network.
    • user The username for the APN (optional).
    • pwd The password for the APN (optional).
  • Return: True if the connection was successful, false otherwise.

functiongprsDisconnect

bool gprsDisconnect()
  • Return: True if the disconnection was successful, false otherwise.

functionisGprsConnected

bool isGprsConnected()
  • Return: True if connected, false otherwise.

functiongetOperator

String getOperator()
  • Return: The current network operator as a String.

functiongetProvider

String getProvider()
  • Return: The current network provider as a String.

WiFi functions

functionnetworkConnect

bool networkConnect(const char * ssid, const char * pwd)
  • Parameters:
    • ssid The SSID of the WiFi network
    • pwd The password of the WiFi network
  • Return: True if successfully connected to the WiFi network, false otherwise.

functionnetworkDisconnect

bool networkDisconnect()
  • Return: True if successfully disconnected from the WiFi network, false otherwise.

Socket listening functions

functionmaintain

void maintain()

Text messaging (SMS) functions

functionsendUSSD

String sendUSSD(const String & code)
  • Parameters:
    • code The USSD code to send.
  • Return: The response from the network as a String.

functionsendSMS

bool sendSMS(const String & number, const String & text)
  • Parameters:
    • number The recipient's phone number.
    • text The message text.
  • Return: True if the message was successfully sent, false otherwise.

functionsendSMS_UTF16

bool sendSMS_UTF16(const char *const number, const void * text, size_t len)
  • Parameters:
    • number The recipient's phone number.
    • text The message text in UTF-16 encoding.
    • len The length of the message text.
  • Return: True if the message was successfully sent, false otherwise.

Battery functions

functiongetBattVoltage

int16_t getBattVoltage()

Note

Unless you have a battery directly connected to your modem module, this will be the input voltage going to the module from your main processor board, not the battery voltage of your main processor.

  • Return: The battery voltage measured by the modem module.

functiongetBattPercent

int8_t getBattPercent()

Note

Unless you have a battery directly connected to your modem module, this will be the percent from the input voltage going to the module from your main processor board, not the battery percent of your main processor.

  • Return: The current battery percent.

functiongetBattChargeState

int8_t getBattChargeState()
  • Return: The battery charge state.

functiongetBattStats

bool getBattStats(int8_t & chargeState, int8_t & percent, int16_t & milliVolts)
  • Parameters:
    • chargeState A reference to an int to set to the battery charge state
    • percent A reference to an int to set to the battery percent
    • milliVolts A reference to an int to set to the battery voltage
  • Return: True if the battery stats were updated by the module, false otherwise.

Temperature functions

functiongetTemperature

float getTemperature()
  • Return: The modem chip temperature in degrees celsius.

Generated by Doxygen and m.css with templates from doxybook2 Updated on 2026-09-11

If you like TinyGSM library - give it a star, or fork it and contribute! GitHub stars GitHub forks

TinyGSM logo

TinyGSM

Documentation Pages

Supported Modules

Contributed Pages

Clone this wiki locally