Skip to content

class_tiny_gsm_sim800

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

title: TinyGsmSim800

TinyGsmSim800 (class)

Module: TinyGsmSim800

Class for the SIMCOM SIM800 and SIM900 (with some limitations).

#include <src/TinyGsmClientSIM800.h>

Inherits from TinyGsmModem<TinyGsmSim800, TinyGsmSim800ModemConfig>, TinyGsmGPRS<TinyGsmSim800>, TinyGsmTCP<TinyGsmSim800, TinyGsmSim800TcpConfig>, TinyGsmCalling<TinyGsmSim800>, TinyGsmSMS<TinyGsmSim800>, TinyGsmGSMLocation<TinyGsmSim800>, TinyGsmTime<TinyGsmSim800>, TinyGsmNTP<TinyGsmSim800>, TinyGsmBattery<TinyGsmSim800> Inherited by TinyGsmSim808

Public Types

Name
class GsmClientSim800
Inner client.
class TinyGsmSim800::GsmClientSecureSim800
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 streamClear()
Clear the modem stream attempting to parse any URC's in it.
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.

Socket listening functions

Public Functions

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

Phone call functions

Public Functions

Name
bool callAnswer()
Answer an incoming phone call.
bool callNumber(const String & number)
Make a phone call.
bool callHangup()
Hang up an in-progress phone call.
bool dtmfSend(char cmd, int duration_ms = 100)
Sent a DTMF (dual tone multi frequency) message over a phone call.

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.

GSM location functions

Public Functions

Name
String getGsmLocationRaw()
Get the raw GSM location data.
String getGsmLocation()
Get the GSM location data.
bool getGsmLocationTime(int * year, int * month, int * day, int * hour, int * minute, int * second)
Get the time attached to the GSM location data.

Time functions

Public Functions

Name
String getGSMDateTime(TinyGSMDateTimeFormat format)
Get the Date Time as a String.
bool getNetworkTime(int * year, int * month, int * day, int * hour, int * minute, int * second, float * timezone)
Get the date and time as parts.
bool getNetworkUTCTime(int * year, int * month, int * day, int * hour, int * minute, int * second, float * timezone)
Get the date and time as parts in UTC.
uint32_t getNetworkEpoch(TinyGSM_EpochStart epoch = TinyGSM_EpochStart::UNIX)
Get the Date/Time as an epoch value.

NTP server functions

Public Functions

Name
bool NTPServerSync(const char * server = "pool.ntp.org", int TimeZone = 0)
Synchronize the modem with an NTP server.
bool waitForTimeSync(uint16_t timeout_s = 120)
Wait for the modem to synchronize with the NTP server.

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.

Public Functions

Name
bool setGsmBusy(bool busy = true)
Set the busy status of the modem for calling.
bool setVolume(uint8_t volume = 50)
Set the speaker volume of the modem.
uint8_t getVolume()
Get the current speaker volume of the modem.
bool setMicVolume(uint8_t channel, uint8_t level)
Set the microphone volume of the modem.
bool setAudioChannel(uint8_t channel)
Set the audio channel of the modem.
bool playToolkitTone(uint8_t tone, uint32_t duration)
Play a toolkit tone on the modem.

Public Attributes

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

Public Types Documentation

classGsmClientSim800

classTinyGsmSim800::GsmClientSecureSim800

typedefregStatusType

;

Public Functions Documentation

functionsetGsmBusy

bool setGsmBusy(bool busy = true)
  • Parameters:
    • busy True to set the modem as busy, false to set it as not busy.
  • Return: True if the operation was successful, false otherwise.

functionsetVolume

bool setVolume(uint8_t volume = 50)
  • Parameters:
    • volume The desired volume level (0-100).
  • Return: True if the operation was successful, false otherwise.

functiongetVolume

uint8_t getVolume()
  • Return: The current volume level (0-100).

functionsetMicVolume

bool setMicVolume(uint8_t channel, uint8_t level)
  • Parameters:
    • channel The microphone channel (0-4).
    • level The desired volume level (0-100).
  • Return: True if the operation was successful, false otherwise.

functionsetAudioChannel

bool setAudioChannel(uint8_t channel)
  • Parameters:
    • channel The desired audio channel.
  • Return: True if the operation was successful, false otherwise.

functionplayToolkitTone

bool playToolkitTone(uint8_t tone, uint32_t duration)
  • Parameters:
    • tone The tone to play.
    • duration The duration of the tone in milliseconds.
  • Return: True if the operation was successful, 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_modem_config_preset.html#a50e1676b71360a06d5fa70da58021658" class="m-doc">ModemConfig::<wbr />GSM_OK</a>, [GsmConstStr](../files/_tiny_gsm_common_8h.md#a9c8c9c8249f99863e157f8fae76e7cab) r2 = <a href="struct_tiny_gsm_modem_config_preset.html#ac0ad8f1d209af52405adf767c46cff52" 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.

functionstreamClear

void streamClear()

Warning

Never call this inside of a waitResponse() call or a URC parser!

Todo: todo

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.

Socket listening functions

functionmaintain

void maintain()

Phone call functions

functioncallAnswer

bool callAnswer()
  • Return: True if the call was answered successfully, false otherwise

functioncallNumber

bool callNumber(const String & number)
  • Parameters:
    • number The number to call
  • Return: True if the call was made successfully, false otherwise

functioncallHangup

bool callHangup()
  • Return: True if the call was hung up successfully, false otherwise

functiondtmfSend

bool dtmfSend(char cmd, int duration_ms = 100)
  • Parameters:
    • cmd The command to send
    • duration_ms The tone duration
  • Return: True if the DTMF message was sent successfully, false otherwise

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.

GSM location functions

functiongetGsmLocationRaw

String getGsmLocationRaw()
  • Return: The raw GSM location data as a String.

functiongetGsmLocation

String getGsmLocation()
  • Return: The GSM location data as a String.

functiongetGsmLocationTime

bool getGsmLocationTime(int * year, int * month, int * day, int * hour, int * minute, int * second)
  • Parameters:
    • year Pointer to store the year.
    • month Pointer to store the month.
    • day Pointer to store the day.
    • hour Pointer to store the hour.
    • minute Pointer to store the minute.
    • second Pointer to store the second.
  • Return: True if the time was successfully retrieved, false otherwise.

Time functions

functiongetGSMDateTime

String getGSMDateTime([TinyGSMDateTimeFormat](../files/_tiny_gsm_time_8tpp.md#a4d77a5e8d7107365e5ca6f8815ac5714) format)

functiongetNetworkTime

bool getNetworkTime(int * year, int * month, int * day, int * hour, int * minute, int * second, float * timezone)
  • Parameters:
    • year Reference to an int for the year
    • month Reference to an int for the month
    • day Reference to an int for the day
    • hour Reference to an int for the hour
    • minute Reference to an int for the minute
    • second Reference to an int for the second
    • timezone Reference to a float for the timezone
  • Return: True if the references have been filled with valid values from the GSM module, false otherwise.

functiongetNetworkUTCTime

bool getNetworkUTCTime(int * year, int * month, int * day, int * hour, int * minute, int * second, float * timezone)
  • Parameters:
    • year Reference to an int for the year
    • month Reference to an int for the month
    • day Reference to an int for the day
    • hour Reference to an int for the hour
    • minute Reference to an int for the minute
    • second Reference to an int for the second
    • timezone Reference to a float for the timezone
  • Return: True if the references have been filled with valid values from the GSM module, false otherwise.

functiongetNetworkEpoch

uint32_t getNetworkEpoch([TinyGSM_EpochStart](../files/_tiny_gsm_time_8tpp.md#a5addcc95a1822928505c18c8b9b9a277) epoch = <a href="_tiny_gsm_time_8tpp.html#a5addcc95a1822928505c18c8b9b9a277a15395d0642f86c5992abbca5e56e2b29" class="m-doc">TinyGSM_EpochStart::<wbr />UNIX</a>)
  • Parameters:
    • epoch The epoch start to use.
  • Return: The offset from the start of the epoch or 0 if the epoch could not be retrieved.

NTP server functions

functionNTPServerSync

bool NTPServerSync(const char * server = &quot;pool.ntp.org&quot;, int TimeZone = 0)

Tip

In versions 0.12.0 and prior, this function returned a byte, the meaning of which varied by modem. In some cases the return value indicated success with 0 and failure with other codes. In the current version, it returns a boolean indicating success or failure.

  • Parameters:
    • server The NTP server to use
    • TimeZone The timezone offset
  • Return: True if the synchronization was successful, false otherwise.

functionwaitForTimeSync

bool waitForTimeSync(uint16_t timeout_s = 120)
  • Parameters:
    • timeout_s The timeout in seconds
  • Return: True if the modem synchronized successfully, 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.

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