Skip to content

Library Functions

Jump to bottom
Timothy Woo edited this page Mar 9, 2023 · 79 revisions

Here I'll attempt to concisely describe all available Arduino functions provided by the library, categorized by function. The source code has moved from this repo to another repo to meet Arduino's library manager specifications.

Some notes:

  • All the functions below can be modified in the BotleticsSIM7000.cpp and BotleticsSIM7000.h library files. The example snippets of code below may or may not be fully functional to be directly compiled and are only for reference. Relevant parts of code may need to be included and should be inferred from the example and comments provided.
  • A function is assumed to work across all supported SIMCom modules unless otherwise specified.

List of functions

Function Explanations

modem.begin()

Description

This function begins serial (UART) communication with the module and works for all SIMCom modules. You must set up the serial context with the correct baud rate before using this command, whether software or hardware serial.

Syntax

modem.begin(port)

Parameters

port: This can either be a software serial or hardware serial port which is used for UART communication with the modem.

Returns

  • True if initialization was successful
  • False if initialization failed (timed out)

Example

#include "BotleticsSIM7000.h" // https://github.com/botletics/Botletics-SIM7000/tree/main/src
#include <SoftwareSerial.h>

#define TX 10 // Microcontroller RX, module TX
#define RX 11 // Microcontroller TX, module RX

SoftwareSerial modemSS = SoftwareSerial(TX, RX);
SoftwareSerial *modemSerial = &modemSS;

Botletics_modem_LTE modem = Botletics_modem_LTE(); // Instantiate modem LTE class

void setup() {
  modemSS.begin(115200); // Default SIM7000 shield baud rate

  Serial.println(F("Configuring to 9600 baud"));
  modemSS.println("AT+IPR=9600"); // Manually set baud rate regardless of whether or not modem is actually on 115200
  delay(100); // Short pause to let the command run
  modemSS.begin(9600);
  if (! modem.begin(modemSS)) {
    Serial.println(F("Couldn't find modem"));
    while (1); // Don't proceed if it couldn't find the device
  }
}

void loop() {}

modem.setBaudrate()

Description

This switches the baud rate for communication with the modem over UART.

Syntax

modem.setBaudrate(baud)

Parameters

baud: The desired baud rate that you want the module to switch to. For example, 4800, 9600, 115200, etc. Please note that you must be on the correct baud rate to begin with in order to communicate with the module, otherwise sending this command won't do you any good! For example, if your module is currently on 115200 baud and you want to switch to 9600, you must first start UART communication at 115200 before you can use modem.setBaudRate(9600) to switch to 9600 baud.

NOTE: Software serial is not reliable on 115200 baud and therefore the example code changes it to a lower value. 9600 works well in almost all applications, but 115200 works great with hardware serial.

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

#include "BotleticsSIM7000.h" // https://github.com/botletics/Botletics-SIM7000/tree/main/src
#include <SoftwareSerial.h>

#define TX 10 // Microcontroller RX, module TX
#define RX 11 // Microcontroller TX, module RX

SoftwareSerial modemSS = SoftwareSerial(TX, RX);
SoftwareSerial *modemSerial = &modemSS;

Botletics_modem_LTE modem = Botletics_modem_LTE();

void setup() {
  modemSS.begin(115200); // Default SIM7000 shield baud rate

  Serial.println(F("Configuring to 9600 baud"));
  modemSS.println("AT+IPR=9600"); // Manually set baud rate regardless of whether or not modem is actually on 115200
  delay(100); // Short pause to let the command run
  modemSS.begin(9600);
  if (! modem.begin(modemSS)) {
    Serial.println(F("Couldn't find modem"));
    while (1); // Don't proceed if it couldn't find the device
  }

  Serial.println(F("Switching to 4800 baud"));
  modem.setBaudrate(4800); // Must already have been able to communicate with modem before this!
}

void loop() {}

Stream functions

Description

These functions pass the UART communication stream for the commands available(), write(), read(), peek(), and flush().

Syntax

  • modem.available()
  • modem.write(uint8_t x)
  • modem.read()
  • modem.peek()
  • modem.flush()

Parameters

None. See Arduino stream documentation for more info.

Returns

Nothing

Example

void loop() {
  // Read and print out anything coming from the modem
  Serial.print(F("modem> "));
  while (! Serial.available() ) {
    if (modem.available()) {
      Serial.write(modem.read());
    }
  }

  // Read and print user command from serial monitor
  // and perform an appropriate action depending on what it is
  char command = Serial.read();
  Serial.println(command);

  // Check for the command
  switch (command) {
    case 'a': {
      // Do something here
    }
    case 'b': {
      // Do something else
    }
  }
}

modem.type()

Description

Returns the modem type.

Syntax

modem.type()

Parameters

None

Returns

The type of the SIMCom modem, one of the following: SIM800L, SIM800H, SIM808_V1, SIM808_V2, SIM5320A, SIM5320E, SIM7000A, SIM7000C, SIM7000E, SIM7000G, SIM7500A, SIM7500E.

Example

uint8_t type;
type = modem.type();
Serial.println(F("modem is OK"));
Serial.print(F("Found "));
switch (type) {
  case SIM800L:
    Serial.println(F("SIM800L")); break;
  case SIM800H:
    Serial.println(F("SIM800H")); break;
  case SIM808_V1:
    Serial.println(F("SIM808 (v1)")); break;
  case SIM808_V2:
    Serial.println(F("SIM808 (v2)")); break;
  case SIM5320A:
    Serial.println(F("SIM5320A (American)")); break;
  case SIM5320E:
    Serial.println(F("SIM5320E (European)")); break;
  case SIM7000A:
    Serial.println(F("SIM7000A (American)")); break;
  case SIM7000C:
    Serial.println(F("SIM7000C (Chinese)")); break;
  case SIM7000E:
    Serial.println(F("SIM7000E (European)")); break;
  case SIM7000G:
    Serial.println(F("SIM7000G (Global)")); break;
  case SIM7500A:
    Serial.println(F("SIM7500A (American)")); break;
  case SIM7500E:
    Serial.println(F("SIM7500E (European)")); break;
  default:
    Serial.println(F("???")); break;
}

modem.getIMEI()

Description

Reads the IMEI number length and stores the actual IMEI number to the supplied buffer. The IMEI number is a globally-unique, manufacturer-assigned ID and which can also be found printed on the sticker label of the modem. This is very useful for obtaining unique IDs for posting data in which multiple devices are involved, without having to generate and store IDs on your own.

Syntax

modem.getIMEI(imei)

Parameters

imei: Character array buffer for storing the IMEI number

Returns

  • uint8_t: IMEI number length

Example

char imei[16] = {0}; // MUST use a 16 character buffer for IMEI!

// Print module IMEI number
uint8_t imeiLen = modem.getIMEI(imei);
if (imeiLen > 0) {
  Serial.print("Module IMEI: "); Serial.println(imei);
}

// Can then use IMEI as device ID!

modem.setFunctionality()

Description

Sets the functionality mode of the module using the AT+CFUN command.

Syntax

modem.setFunctionality(option)

Parameters

option: Can choose from the list below:

  • 0 - Minimum functionality
  • 1 - Full functionality
  • 4 - Disable RF
  • 5 - Factory test mode
  • 6 - Restarts module
  • 7 - Offline mode

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

// Set modem to full functionality
modem.setFunctionality(1); // AT+CFUN=1

// Software restart module
modem.setFunctionality(6); // AT+CFUN=6

modem.setNetworkSettings()

Description

This function sets the cellular network's APN and username/password (if applicable) so that the modem can connect to the network. This is usually required to gain access to the network and these credentials are typically specific to the SIM card and type of network you're using.

Syntax

modem.setNetworkSettings(APN, username, password)

Parameters

  • APN: The APN from the cellular provider
  • username: The username, if applicable
  • password: The password, if applicable

Returns

  • True if parameters were saved successfully
  • False if parameters were not saved successfully

Example

// Configure an APN, username, and password.
// You might need to do this to access your network's GPRS/data
// network. Contact your provider for the exact APN, username,
// and password values. Username and password are optional and
// can be removed, but APN is required.
// modem.setNetworkSettings(F("your APN"), F("your username"), F("your password"));

// Examples (only use one of course!):
modem.setNetworkSettings(F("m2m.com.attz")); // For AT&T IoT SIM card
modem.setNetworkSettings(F("telstra.internet")); // For Telstra (Australia) SIM card - CAT-M1 (Band 28)
modem.setNetworkSettings(F("hologram")); // For Hologram SIM card

modem.setPreferredMode()

Description

Sets the preferred mode of operation (connection type) using the AT+CNMP command.

Note: This is only for the LTE class and will not work on 2G or 3G modules.

Syntax

modem.setPreferredMode(mode)

Parameters

mode: An integer that corresponds to the desired mode. Below are the acceptable inputs:

  • 2 - Automatic
  • 13 - GSM only
  • 38 - LTE only
  • 51 - GSM and LTE only

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

modem.setPreferredMode(38); // Use LTE only, not 2G

modem.setPreferredLTEMode()

Description

Sets the preferred mode of operation between LTE CAT-M and NB-IoT using the AT+CMNB command.

Note: This only works for the SIM7000 modem.

Syntax

modem.setPreferredLTEMode(mode)

Parameters

mode: An integer that corresponds to the desired mode. Below are the acceptable inputs:

  • 1 - CAT-M
  • 2 - NB-IoT
  • 3 - CAT-M and NB-IoT

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

modem.setPreferredLTEMode(1); // Use LTE CAT-M only, not NB-IoT

modem.openWirelessConnection()

Description

Opens or closes the wireless connection using the AT+CNACT command. Set the APN with the setNetworkSettings() function before calling this function so that it will use the correct APN when called.

Note: This is only for the LTE class and will not work on 2G or 3G modules.

Syntax

modem.openWirelessConnection(onoff)

Parameters

onoff: True or false (enable or disable)

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

modem.openWirelessConnection(true); // Enable connection

modem.wirelessConnStatus()

Description

Checks the wireless connection status using the AT+CNACT? command.

Note: This is only for the LTE class and will not work on 2G or 3G modules.

Syntax

modem.wirelessConnStatus()

Parameters

None

Returns

  • True if the device is connected
  • False if the command errors or times out, or if device is not connected

Example

bool isConnected = modem.wirelessConnStatus();
if (isConnected) Serial.println("Device is connected!");

modem.setOperatingBand()

Description

Sets the LTE CAT-M or NB-IoT band to operate on using the AT+CBANDCFG command.

Note: Only works on the SIM7000 modem.

Syntax

modem.setOperatingBand(mode, band)

Parameters

  • mode: A string, either "CAT-M" or "NB-IOT"
  • band: An integer corresponding to the EUTRAN band number.

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

// Force the SIM7000 to use AT&T LTE CAT-M only
modem.setOperatingBand("CAT-M", 12); // AT&T uses band 12

// Force the SIM7000 to use Verizon LTE CAT-M only
modem.setOperatingBand("CAT-M", 13); // Verizon uses band 13

modem.enableSleepMode()

Description

Enables or disables UART sleep mode using the AT+CSCLK command. Note that this command will not actually perform the sleep operation but is necessary for sleep to be enabled later. USB must be disconnected before sleep will take effect.

Syntax

modem.enableSleepMode(onoff)

Parameters

onoff: True or false (enable or disable)

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

modem.enableSleepMode(true);

modem.set_eDRX()

Description

Sets the extended-DRX parameters using the AT+CEDRXS command. E-DRX mode significantly reduces power consumption by cutting down the sampling rate while still remaining connected to the network. Note that whatever e-DRX value you set there will be a delay time for receiving incoming messages (like SMS).

Note: Only works on SIM7000 modem.

Syntax

modem.set_eDRX(mode, connType, eDRX_val)

Parameters

  • mode: An integer, one of the following options:
    • 0 - Disable the use of eDRX
    • 1 - Enable the use of eDRX
    • 2 - Enable the use of eDRX and auto report
    • 3 - Disable the use of eDRX(Reserved)
  • connType: An integer, either of the following options:
    • 4 - CAT-M
    • 5 - NB-IoT
  • eDRX_val: A string of the requested eDRX value in 4-bit format ("0000"-"1111"). The eDRX value selects the "sampling rate" from the options below:
    • 0 - 5.12s
    • 1 - 10.24s
    • 2 - 20.48s
    • 3 - 40.96s
    • 4 - 61.44s
    • 5 - 81.92s
    • 6 - 102.40s
    • 7 - 122.88s
    • 8 - 143.36s
    • 9 - 163.84s
    • 10 - 327.68s
    • 11 - 655.36s
    • 12 - 1310.72s
    • 13 - 2621.44s
    • 14 - 5242.88s
    • 15 - 10485.76s

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

modem.set_eDRX(1, 4, "0010"); // Enable eDRX on CAT-M with 20.48s sampling rate

modem.enablePSM()

Description

Enables or disables power saving mode (PSM) using the AT+CPSMS command. PSM drastically reduces the power consumption while remaining connected to the network and can even wake up a host microcontroller from the ring indicator (RI) pin when incoming SMS messages are received (in theory, see below).

Note: This sounds good on paper but has yet to be confirmed on the SIM7000 in real life. Moreover, the modem.enableSleepMode(true) command must be used before this will work and USB port must be disconnected.

Syntax

modem.enablePSM(onoff)

Parameters

onoff: True or false (enable or disable)

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

modem.enableSleepMode(true);
modem.enablePSM(true);

modem.setNetLED()

Description

Sets the function of the network status LED (for the Botletics SIM7000 shield it's the blue LED labeled "NET").

Note: Only works on the SIM7000 modem.

Syntax

modem.setNetLED(onoff, mode, timer_on, timer_off)

Parameters

  • onoff: True or false (enable or disable)
  • mode: Integer, one of the following options:
    • 1 - Set the timer period of the net light when the modem is not registered to the network
    • 2 - Set the timer period of the net light when the modem has already connected to the network
    • 3 - Set the timer period of the net light when the modem is in PPP communication (data enabled basically)
  • timer_on: Timer period of "LED ON" in decimal format which range is 0 or 40-65535(ms)
  • timer_off: Timer period of "LED OFF" in decimal format which range is 0 or 40-65535(ms)

Default settings for ,<timer_on>,<timer_off> are the following:

  • 1,64,800
  • 2,64,3000
  • 3,64,300

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

// Set the LED to periodically blink 64ms on and 3s off when connected to a network
modem.setNetLED(true, 2, 64, 3000); // on/off, mode, timer_on, timer_off

// We could also disable the LED altogether
modem.setNetLED(false); // Disable network status LED

modem.enableRTC()

Description

Enable UTC network time sync and local time stamp with the AT+CLTS command.

Syntax

modem.enableRTC(onoff)

Parameters

onoff: True or false (enable or disable)

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

modem.enableRTC(true);

modem.readRTC()

Description

Read and parse the current time.

Syntax

modem.readRTC(&year, &month, &day, &hour, &minute, &second)

Parameters

  • year: uint8_t integer for storing the two-digit year (not four digits like 2018)
  • month: uint8_t integer for storing the month
  • day: uint8_t integer for storing the day
  • hour: uint8_t integer for storing the hour
  • minute: uint8_t integer for storing the minute
  • second: uint8_t integer for storing the second

Returns

  • True if the AT command ran successfully and time was parsed
  • False if the AT command produced an error or timed out

Example

uint8_t year, month, day, hour, minute, second;
modem.readRTC(&year, &month, &day, &hour, &minute, &second); // Parse the time

// Can also print out to serial for sanity check
Serial.print(F("Year: ")); Serial.println(year);
Serial.print(F("Month: ")); Serial.println(month);
Serial.print(F("Day: ")); Serial.println(day);
Serial.print(F("Hour: ")); Serial.println(hour);
Serial.print(F("Minute: ")); Serial.println(minute);
Serial.print(F("Second: ")); Serial.println(second);

modem.enableNTPTimeSync()

Description

Manage time syncing with an NTP server.

Syntax

modem.enableNTPTimeSync(onoff, ntpserver)

Parameters

  • onoff: True or false (enable or disable)
  • ntpserver: Flash string of the NTP server, F("pool.ntp.org") by default

Returns

  • True if successful
  • False if unsuccessful

Example

// Enable NTP time sync
if (!modem.enableNTPTimeSync(true, F("pool.ntp.org")))
  Serial.println(F("Failed to enable"));
break;

modem.getTime()

Description

Get the current local time and store it in a buffer.

Syntax

modem.getTime(buffer, maxlen)

Parameters

  • buffer: Char buffer for storing the time
  • maxlen: Max length to read from the time

Returns

  • True if reply/parsing was successful
  • False if the AT command produced an error or timed out

Example

// Read the time
char buffer[23];

modem.getTime(buffer, 23); // Make sure replybuffer is at least 23 bytes!
Serial.print(F("Time = ")); Serial.println(buffer);

modem.powerOn()

Description

Power on the modem by pulsing the PWRKEY pin LOW for a certain duration (dependent on the module). Initializes the PWRKEY pin as a digital OUTPUT.

Syntax

modem.powerOn(modem_PWRKEY)

Parameters

  • modem_PWRKEY: uint8_t PWRKEY pin number

Returns

Nothing

Example

const uint8_t modem_PWRKEY = 6; // for botletics SIM7000 shield
modem.powerOn(modem_PWRKEY); // Power on the module

modem.powerDown()

Description

Shut down the modem via software (lowest power consumption state). The module will no longer be able to do anything and will not wake up unless powered back on from the PWRKEY pin.

Syntax

modem.powerDown()

Parameters

None

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

modem.powerDown(); // Shut off the module

modem.getADCVoltage()

Description

Read the voltage of the modem's ADC pin. Note: Please be aware of the maximum allowable voltage on this pin as specified in the hardware design manual of the modem.

Syntax

modem.getADCVoltage(&voltage)

Parameters

  • voltage: uint16_t for storing the voltage value in mV

Returns

  • True if the voltage was read successfully
  • False if the command produced an error or timed out

Example

uint16_t adc;
if (! modem.getADCVoltage(&adc)) {
  Serial.println(F("Failed to read ADC"));
}
else {
  Serial.print(F("ADC = ")); Serial.print(adc); Serial.println(F(" mV"));
}

modem.getBattPercent()

Description

Returns the battery percentage of the 3.7V LiPo battery powering the modem.

Syntax

modem.getBattPercent(&percent)

Parameters

  • percent: uint16_t for storing the battery percentage

Returns

  • True if the percentage was read successfully
  • False if the command produced an error or timed out

Example

if (! modem.getBattPercent(&vbat)) {
  Serial.println(F("Failed to read Batt"));
}
else {
  Serial.print(F("VPct = ")); Serial.print(vbat); Serial.println(F("%"));
}

modem.getBattVoltage()

Description

Returns the supply voltage of the modem (which is the battery voltage if the modem is being powered by a battery).

Syntax

modem.getBattVoltage(&voltage)

Parameters

  • voltage: uint16_t for storing the battery voltage

Returns

  • True if the percentage was read successfully
  • False if the command produced an error or timed out

Example

if (! modem.getBattVoltage(&vbat)) {
  Serial.println(F("Failed to read Batt"));
}
else {
  Serial.print(F("VBat = ")); Serial.print(vbat); Serial.println(F(" mV"));
}

modem.unlockSIM()

Description

Unlock SIM card with PIN.

Syntax

modem.unlockSIM(pin)

Parameters

  • pin: SIM card pin code

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

char PIN[5] = "1234"; // SIM card PIN

if (!modem.unlockSIM(PIN)) {
  Serial.println(F("Failed to unlock SIM card"));
}

modem.getSIMCCID()

Description

Get the SIM card's CCID number. This number is usually printed on the SIM card or the holder it came in.

Syntax

modem.getSIMCCID(buffer)

Parameters

  • buffer: Buffer to hold the CCID

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

char buffer[21];
modem.getSIMCCID(buffer); // Make sure the buffer is at least 21 bytes!
Serial.print(F("SIM CCID = ")); Serial.println(buffer);

modem.getNetworkStatus()

Description

Gets the network registration status of the modem.

Syntax

modem.getNetworkStatus()

Parameters

None

Returns

uint8_t network status number

Example

// Read the network/cellular status
uint8_t n = modem.getNetworkStatus();
Serial.print(F("Network status "));
Serial.print(n);
Serial.print(F(": "));
if (n == 0) Serial.println(F("Not registered"));
if (n == 1) Serial.println(F("Registered (home)"));
if (n == 2) Serial.println(F("Not registered (searching)"));
if (n == 3) Serial.println(F("Denied"));
if (n == 4) Serial.println(F("Unknown"));
if (n == 5) Serial.println(F("Registered roaming"));

modem.getRSSI()

Description

Get the network connection signal strength.

Syntax

modem.getRSSI()

Parameters

None

Returns

uint8_t RSSI value

Example

// Read the raw RSSI value
uint8_t n = modem.getRSSI();
int8_t r;

Serial.print(F("RSSI = ")); Serial.print(n); Serial.print(": ");

// Convert raw RSSI to dBm
if (n == 0) r = -115;
if (n == 1) r = -111;
if (n == 31) r = -52;
if ((n >= 2) && (n <= 30)) {
  r = map(n, 2, 30, -110, -54);
}
Serial.print(r); Serial.println(F(" dBm"));

modem.getNetworkInfo()

Description

Get the network name, connection type, band, and other related information using AT+COPS? and AT+CPSI? commands.

Syntax

modem.getNetworkInfo()

Parameters

None

Returns

  • True if successful
  • False if unsuccessful

Example

modem.getNetworkInfo();

modem.setSMSInterrupt()

Description

Disable or enable the interrupt functionality to be triggered by incoming SMS and/or other things. This feature can be used to trigger the ring indicator (RI) pin to do things like wake up or alert the microcontroller when a certain even occurs.

Syntax

modem.setSMSInterrupt(option)

Parameters

  • option: Pick from the options below:
    • 0 - Off
    • 1 - On (TCPIP, FTP and URC control RI pin)
    • 2 - On (only TCPIP control RI pin)

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

modem.setSMSInterrupt(1); // Enable interrupt to be triggered by TCPIP, FTP and URC

modem.getSMSInterrupt()

Description

Get the interrupt functionality option as described in the previous function.

Syntax

modem.getSMSInterrupt()

Parameters

None

Returns

uint8_t option number as described in the previous function.

Example

uint8_t option = modem.getSMSInterrupt();

modem.getNumSMS()

Description

Get the number of stored SMS messages.

Syntax

modem.getNumSMS()

Parameters

None

Returns

int8_t number of SMS. Returns -1 if there was an error.

Example

int8_t sms_num = modem.getNumSMS();

modem.readSMS()

Description

Read a stored SMS message based on its index.

Syntax

modem.readSMS(sms_num, buffer, maxlen, &smslen)

Parameters

  • sms_num: uint8_t index of the SMS you want to read, starting from 0
  • buffer: Character buffer to hold the contents of the SMS
  • maxlen: uint16_t max length you want to read out from the SMS
  • smslen: uint16_t length of the SMS message

Returns

  • True if successful
  • False if unsuccessful

Example

uint8_t sms_num = 2;
char SMS_content[255];
uint16_t maxlen = 200; // Maybe we only want to read a max of 200
uint16_t smslen = 0;
if (!modem.readSMS(sms_num, SMS_content, maxlen, &smslen)) {
  Serial.println(F("Failed to read SMS!"));
}

modem.sendSMS()

Description

Send a text message (SMS) to a phone number.

Syntax

modem.sendSMS(phoneNum, message)

Parameters

  • phoneNum: Char array with phone number with country code (only numbers, no "+" symbol or anything else!)
  • message: Char array with SMS message content

Returns

  • True if successful
  • False if unsuccessful

Example

const char * phone_number = "0012223334567"; // Include 3-digit country code, only numbers
const char * text_message = "All ur base ar belong 2 us!";

if (!modem.sendSMS(phoneNum, textMessage)) {
  Serial.println(F("Failed to send"));
}
else {
  Serial.println(F("Sent!"));
}

modem.deleteSMS()

Description

Delete a stored SMS based on its index.

Syntax

modem.deleteSMS(index)

Parameters

  • index: The index of the stored SMS.

Returns

  • True if deleted successfully
  • False if otherwise

Example

uint8_t sms_idx = 1;

if (modem.deleteSMS(sms_idx)) {
  Serial.println(F("Deleted!"));
}
else {
  Serial.println(F("Couldn't delete"));
}

modem.getSMSSender()

Description

Retrieve the sender of a specified SMS message and copy it as a string to the buffer.

Syntax

modem.getSMSSender(sms_idx, sender, sender_len)

Parameters

  • sms_idx: uint8_t index of the SMS (SMS "slot")
  • sender: char buffer holding the sender's info
  • sender_len: int max number of characters to copy into the "sender" buffer

Returns

  • True if successful
  • False if no SMS was found in the slot specified by the SMS index

Example

// Retrieve the SMS sender's phone number
uint8_t sms_idx = 3;
char senderBuff[16];
uint8_t maxlen = 30;

if (! modem.getSMSSender(sms_idx, senderBuff, maxlen)) {
  Serial.println("Didn't find SMS message in the slot!");
}

Serial.print(F("FROM: ")); Serial.println(senderBuff);

modem.sendUSSD()

Description

Send a USSD message.

Syntax

modem.sendUSSD(message, replybuffer, maxlen, &ussdlen)

Parameters

  • message: char array of the USSD message
  • replybuffer: char buffer to hold the message reply
  • maxlen: uint16_t max length of the reply that you want to read out
  • ussdlen: uint16_t length of the reply message

Returns

  • True if successful
  • False if unsuccessful

Example

uint16_t ussdlen;
const char * message = "All ur base ar belong 2 us!";
char replybuffer[255];

if (!modem.sendUSSD(message, replybuffer, 250, &ussdlen)) {
  Serial.println(F("Failed"));
}
else {
  Serial.println(F("Sent!"));
  Serial.print(F("***** USSD Reply"));
  Serial.print(" ("); Serial.print(ussdlen); Serial.println(F(") bytes *****"));
  Serial.println(replybuffer);
  Serial.println(F("*****"));
}

modem.setAudio()

Description

Set audio to headset or speaker phone (external). Works on voice-enabled modules only.

Syntax

modem.setAudio(option)

Parameters

  • option: One of the following options:
    • 0 - Headset
    • 1 - Speaker phone (external audio)

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

modem.setAudio(1); // Set to speaker phone for SIM800
// OR, for different module:
modem.setAudio(3); // Set to speaker phone for SIM7500

modem.setVolume()

Description

Set the speaker volume. Works on voice-enabled modules only.

Syntax

modem.setVolume(level)

Parameters

  • level: uint8_t volume level (depends on the module):
    • For SIM800 volume level ranges from 0-100 (softest-loudest)
    • For SIM5320 volume level ranges from 0-8 (softest-loudest)
    • For SIM7500 volume level ranges from 0-5 (softest-loudest) with 4 being the default

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

modem.setVolume(80); // Set volume to 80% on SIM800
// OR on a different module:
modem.setVolume(5); // Max out volume for SIM7500

modem.getVolume()

Description

Set the speaker volume. Works on voice-enabled modules only.

Syntax

modem.getVolume()

Parameters

None

Returns

uint8_t volume level as described in the previous function.

Example

uint8_t volume = modem.getVolume();

modem.playToolkitTone()

Description

Play toolkit tone (pre-defined tones unique to each module). Works on 2G and 3G voice-enabled modules only.

Syntax

modem.playToolkitTone(tone, length)

Parameters

  • tone: See the corresponding AT command manual for a full list of the supported tones
  • length: uint16_t desired duration of the tone in milliseconds. The ranges differ between modules:
    • SIM800: 10-15300000ms
    • SIM5320: Up to 2^16 - 1 (uint16_t)

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

modem.playToolkitTone(8, 5000); // Play ringing tone for SIM800 for 5s

modem.setMicVolume()

Description

Set the microphone gain. Works on 2G voice-enabled modules only.

Syntax

modem.setMicVolume(channel, level)

Parameters

  • channel: One of the following integers corresponding to the audio channel:
    • 0 - Main audio channel
    • 1 - Aux audio channel
    • 2 - Main audio channel hands free mode
    • 3 - Aux audio channel hands free mode
  • level: The gain level, from 0-15 for SIM800. Check AT command manual for full list of corresponding gain levels in decibels (dB).

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

modem.setMicVolume(1, 10); // Use aux audio channel and set mic gain to +15.0dB

modem.playDTMF()

Description

Set the microphone gain. Works on 2G voice-enabled modules only.

Syntax

modem.playDTMF(tone)

Parameters

  • tone: char tone to play (the "note" basically). It can be 0-9, A, B, C, D, E, F, *, or #

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

modem.playDTMF('B'); // Play the note 'B'

modem.tuneFMradio()

Description

Set the FM radio frequency.

Syntax

modem.tuneFMradio(station)

Parameters

  • station: uint16_t ranging from 875-1080 (87.5MHz - 108.0MHz)

Returns

  • True if the AT command ran successfully
  • False if the station is outside the acceptable range or if AT command produced an error or timed out

Example

modem.tuneFMradio(901); // Listen to WABE Atlanta (NPR's station)

modem.FMradio()

Description

Open or close FM radio.

Syntax

modem.FMradio(onoff, channel)

Parameters

  • onoff: True or false (enable or disable)
  • channel: Either 0 (main audio channel) or 1 (aux audio channel), 0 by default

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

modem.FMradio(true, 1); // Enable FM radio on external headset

modem.setFMVolume()

Description

Set the FM radio volume.

Syntax

modem.setFMVolume(volume)

Parameters

  • volume: Volume level, 0-6

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

modem.setFMVolume(6); // Set the FM radio to max volume

modem.getFMVolume()

Description

Get the current FM radio volume.

Syntax

modem.getFMVolume(volume)

Parameters

None

Returns

int8_t FM volume as described in the previous function. Returns 0 if there was an error.

Example

int8_t FM_vol = modem.getFMVolume();

modem.getFMSignalLevel()

Description

Get the signal level of an FM station.

Syntax

modem.getFMSignalLevel(station)

Parameters

  • station: uint16_t station frequency ranging from 875-1080 (87.5MHz - 108.0MHz)

Returns

int8_t signal level. Returns -1 if unsuccessful.

Example

int8_t signal_level = getFMSignalLevel(901); // Get signal level of WABE Atlanta

modem.enableGPRS()

Description

Enable cellular data (2G, 3G, or 4G LTE depending on what module you're using).

Syntax

modem.enableGPRS(onoff)

Parameters

  • onoff: True or false (enable or disable)

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

if (!modem.enableGPRS(true)) {
  Serial.println(F("Failed to enable data"));
}

modem.GPRSstate()

Description

Read the current GPRS state (enabled or disabled) with the AT+CGATT? function.

Syntax

modem.GPRSstate()

Parameters

None

Returns

int8_t state. Returns -1 if there is an error.

Example

int8_t state = modem.GPRSstate();

modem.getGSMLoc()

Description

Get the GSM location based on cell tower triangulation. The first version of the function reads out the reply and the second one parses the reply for latitude and longitude.

Note: Only works on 2G and requires GPRS (data) to be enabled first.

Syntax

  • modem.getGSMLoc(&replycode, buff, maxlen)
  • modem.getGSMLoc(&lat, &long)

Parameters

  • replycode: uint16_t to store the reply code
  • buff: char buffer to store the GSM location response
  • maxlen: unt16_t max length to read from the response
  • lat: float for holding the latitude
  • long: float for holding the longitude

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

// Enable GPRS first
modem.enableGPRS(true);

// Get GSM location
uint16_t returncode;
char replybuffer[255];

if (!modem.getGSMLoc(&returncode, replybuffer, 250))
  Serial.println(F("Failed!"));
if (returncode == 0) {
  Serial.println(replybuffer);
}
else {
  Serial.print(F("Fail code #")); Serial.println(returncode);
}

// Can also get lat/long directly
float latitude, longitude;

if (! modem.getGSMLoc(&latitude, &longitude) {
  Serial.println(F("Failed!"));
}
else {
  Serial.print(F("Lat: ")); Serial.println(latitude, 6); // Print 6 decimal places
  Serial.print(F("Long: ")); Serial.println(longitude, 6);
}

modem.postData()

Description

Post data via HTTP or HTTPS (depending on the module) GET or POST requests. The first method is for 2G and SIM7000 modules, whereas the second is for SIM5320 and SIM7500 (3G and 4G) modules.

Syntax

  • modem.postData(request_type, URL, body, token, bodylen)
  • modem.postData(server, port, connType, URL, body)

Parameters

For the first function usage (2G/SIM7000 modules):

  • request_type: char array containing the type of request, either "GET", "POST", or "HEAD"
  • URL: char array containing the URL for the GET or POST request. Ex: "dweet.io/dweet/for/myDevice123?temp=75.4"
  • body: optional char array containing the JSON body of the POST request if applicable
  • token: optional char array containing the HTTP basic authentication token
  • bodylen: optional uint32_t length of the JSON body. Particularly useful if the body length is very long or passed to the function as a pointer (for example, posting an image)

For the second usage (SIM5320/SIM7500 modules):

  • server: char array containing the server IP address or URL. Ex: "www.dweet.io" or "www.google.com"
  • port: char array containing the connection port
  • connType: char array containing the
  • URL: char array containing the URL for the GET or POST request without the server address. Ex: "GET /dweet/for/myDevice123?temp=75.4"
  • body: optional char array containing the JSON body of the POST request if applicable

Returns

  • True if the server responds with an HTTP code of 200
  • False if any AT command produced an error or if the HTTP code was not 200

Example

Please see the "2" and "3" commands in the LTE_Demo sketch and the IoT_Example sketch for example usage of this function.

modem.enableGPS()

Description

Enable or disable GPS. Only works on modules with GPS (SIM808, SIM5320, SIM7000, SIM7500).

Syntax

modem.enableGPS(onoff)

Parameters

  • onoff: True or false (enable or disable)

Returns

  • True if the AT command ran successfully
  • False if the AT command produced an error or timed out

Example

modem.enableGPS(true); // Enable GPS

modem.GPSstatus()

Description

Check whether or not the GPS has a fix on location.

Syntax

modem.GPSstatus()

Parameters

None

Returns

int8_t status. Returns -1 if there was an error.

  • 0 - GPS fix is unknown or if GPS is not even enabled
  • 1 - No fix, but GPS is enabled (SIM808 V1 only)
  • 2 - 2D fix (SIM808 V1 only)
  • 3 - 3D fix
// Let's say we're using SIM808 V2 or SIM7000
int8_t GPS_status = modem.GPSstatus();
if (GPS_status == 0) {
  Serial.println(F("GPS not even on!"));
}
else if (GPS_status == 3) {
  Serial.println(F("Got a GPS fix!"));
}

modem.getGPS()

Description

Query the GPS location. Only works on modules with GPS (SIM808, SIM5320, SIM7000, SIM7500). There are two function definitions for different applications.

Syntax

  • modem.getGPS(arg, buffer, maxbuff)
  • modem.getGPS(&lat, &lon, &speed_kph, &heading, &altitude, &year, &month, &day, &hour, &min, &sec)

Parameters

For the first function usage:

  • arg: uint8_t command argument (powers of 2, 0 by default) only for SIM808 V1. See SIM808 AT command manual for more details.
  • buffer: char array for containing the module reply with the GPS info
  • maxbuff: uint8_t maximum number of characters to read out into the buffer

For the second usage:

  • lat: float for holding the latitude
  • lon: float for holding the longitude
  • speed_kph: float for holding the speed in kph
  • heading: float for holding the heading (degrees)
  • altitude: float for holding the altitude
  • year: optional uint16_t year (4 digits) parsed from the GPS info
  • month: optional uint8_t month parsed from the GPS info
  • day: optional uint8_t day parsed from the GPS info
  • hour: optional uint8_t hour parsed from the GPS info
  • min: optional uint8_t minute parsed from the GPS info
  • sec: optional float second parsed from the GPS info

Returns

  • For the first function usage, returns uint8_t reply length
  • For the second function usage, returns true or false based on whether everything ran OK

Example

// Let's just read out the GPS info response and store it in the buffer
char replybuffer[255];

if (! modem.getGPS(0, replybuffer, 250)) {
  Serial.println(F("Error!"));
}
else {
  Serial.print(F("GPS Info: ")); Serial.println(replybuffer);
}

// Now let's actually parse the GPS info
float latitude, longitude, speed_kph, heading, altitude, second;
uint16_t year;
uint8_t month, day, hour, minute;

// Use the top line if you want to parse UTC time data as well, the line below it if you don't care
// if (! modem.getGPS(&latitude, &longitude, &speed_kph, &heading, &altitude, &year, &month, &day, &hour, &minute, &second)) {
if (! modem.getGPS(&latitude, &longitude, &speed_kph, &heading, &altitude)) { // Use this line instead if you don't want UTC time
  Serial.println(F("Error!"));
}
else {
  Serial.print(F("Latitude: ")); Serial.println(latitude, 6); // Print out 6 decimal places
  Serial.print(F("Longitude: ")); Serial.println(longitude, 6);
  Serial.print(F("Speed: ")); Serial.println(speed_kph);
  Serial.print(F("Heading: ")); Serial.println(heading);
  Serial.print(F("Altitude: ")); Serial.println(altitude);
  // Comment out the stuff below if you don't care about UTC time
  /*
    Serial.print(F("Year: ")); Serial.println(year);
    Serial.print(F("Month: ")); Serial.println(month);
    Serial.print(F("Day: ")); Serial.println(day);
    Serial.print(F("Hour: ")); Serial.println(hour);
    Serial.print(F("Minute: ")); Serial.println(minute);
    Serial.print(F("Second: ")); Serial.println(second);
    Serial.println(F("---------------------"));
  */
}

modem.enableGPSNMEA()

Description

Enable NMEA output on USB's NMEA COM port. When you plug in the device via USB you should see this port.

Note: You must follow these instructions to install the drivers before you can see the COM port.

Syntax

modem.enableGPSNMEA(option)

Parameters

  • option: For modules other than the SIM808 it can either be 0 to disable NMEA output or 1 to enable. For the SIM808 please reference the AT+CGPSOUT command in the AT command manual for all the available options.

Returns

  • True if the AT commands ran successfully
  • False if any AT command produced an error or timed out

Example

modem.enableGPSNMEA(1); // Turn on NMEA output

modem.TCPconnect()

Description

Connect to a server via TCP. Does not work on SIM5320.

Note: Must enable GPRS/data before using TCP functions.

Syntax

modem.TCPconnect(server, port)

Parameters

  • server: char array containing the server IP address or URL
  • port: uint16_t port number

Returns

  • True if connected to server successfully
  • False otherwise

Example

modem.enableGPRS(true); // Enable data first
if (! modem.TCPconnect("xxx.xxx.x.x", 80)) Serial.println(F("Failed to connect!")); // Connect to server via TCP

modem.TCPclose()

Description

Close TCP connection.

Note: Must enable GPRS/data before using TCP functions.

Syntax

modem.TCPclose()

Parameters

None

Returns

  • True if closed successfully
  • False otherwise

Example

modem.TCPclose(); // Close TCP connection

modem.TCPconnected()

Description

Check if currently connected to a TCP server.

Note: Must enable GPRS/data before using TCP functions.

Syntax

modem.TCPconnected()

Parameters

None

Returns

  • True if it is connected
  • False otherwise

Example

bool isConnected = modem.TCPconnected();

modem.TCPsend()

Description

Send data to the server over TCP connection. Must be already connected to a server to send data.

Note: Must enable GPRS/data before using TCP functions.

Syntax

modem.TCPsend(packet, len)

Parameters

  • packet: char array containing the data being sent
  • len: uint8_t packet length

Returns

  • True if connected to server successfully
  • False otherwise

Example

modem.enableGPRS(true); // Enable data first
if (! modem.TCPconnect("xxx.xxx.x.x", 80)) Serial.println(F("Failed to connect!")); // Connect to server via TCP

// Now let's send data
char packet[] = "testing 123!!!";
if (! modem.TCPsend(packet, sizeof(packet))) Serial.println(F("Failed to send!"));

modem.TCPclose(); // Close TCP connection

modem.TCPavailable()

Description

Check how many bytes are available to read via TCP.

Syntax

modem.TCPavailable()

Parameters

None

Returns

uint16_t number of bytes available. Returns 0 if nothing is available.

Example

uint16_t numBytes = modem.TCPavailable();

modem.TCPread()

Description

Read any available data via TCP.

Syntax

modem.TCPread(buffer, len)

Parameters

  • buffer: char buffer to hold the contents
  • len: max length to read into the buffer

Returns

uint16_t number of bytes read

Example

modem.enableGPRS(true); // Enable data first
if (! modem.TCPconnect("xxx.xxx.x.x", 80)) Serial.println(F("Failed to connect!")); // Connect to server via TCP

// Now let's read data
char replybuffer[255];
uint16_t bytesRead = modem.TCPread(replybuffer, 250);

if (bytesRead == 0) {
  Serial.println(F("Failed to read / nothing available!"));
}
else {
  Serial.print(F("Read ")); Serial.print(bytesRead); Serial.print(F(" bytes!"));
}

modem.TCPclose(); // Close TCP connection

modem.addRootCA()

Description

Add a root CA certificate for SSL to be used in TCP commands. To use it, set #define BOTLETICS_SSL 1 in BotleticsSIM7000.h. In Chrome, you can find a site's root CA by clicking on the padlock next to the URL / Certificate / Details / Copy to File / Base-64 encoded

Syntax

modem.addRootCA(root_cert)

Parameters

  • root_cert: char array of the root CA certificate

Returns

  • True if the root CA was added successfully
  • False otherwise

Example

// Let's use dweet.io's root CA:
const char root_ca = \
"-----BEGIN CERTIFICATE-----\n" \
"MIIFZDCCBEygAwIBAgIQC5GYuhxBWRXWg9AR7lHB1TANBgkqhkiG9w0BAQsFADBG\n" \
"MQswCQYDVQQGEwJVUzEPMA0GA1UEChMGQW1hem9uMRUwEwYDVQQLEwxTZXJ2ZXIg\n" \
"Q0EgMUIxDzANBgNVBAMTBkFtYXpvbjAeFw0yMDA1MjkwMDAwMDBaFw0yMTA2Mjkx\n" \
"MjAwMDBaMBMxETAPBgNVBAMTCGR3ZWV0LmlvMIIBIjANBgkqhkiG9w0BAQEFAAOC\n" \
"AQ8AMIIBCgKCAQEAly3JdZAj2PlUfNXzvNA1BeBGcKJPgS6hXIu6EClQ+Do4Yc/V\n" \
"bdg2dddGFxskay6yRqRC+DC6QVRDE9IIfyD8AOtufdremQh9t8+BLrdjWmpDtCCI\n" \
"775v2IapmWlOx+4o0qAGYuC4n+1OyT/4oT5nvU1fSdX1vCZx0PJ0wlz0aOe4zXdr\n" \
"3MIRc5T+FG9FUrr/PlkrxiOHY8NVJbQAjfHH/7yTGiq0+Q2IHy6AMB7xn/em4ACY\n" \
"V5fDuXNbdNP6SI0j/2me02sfZ3dr9ksPpLWjM603P4yQem+3RE/UEDgSc0zuCdos\n" \
"1RLGsMO2HOeIwLYn1s9Ut8/5SxLjGcLuyVhW0QIDAQABo4ICfzCCAnswHwYDVR0j\n" \
"BBgwFoAUWaRmBlKge5WSPKOUByeWdFv5PdAwHQYDVR0OBBYEFJ3fV4tJ19MGiB2J\n" \
"7OQR6UPFUAVdMB8GA1UdEQQYMBaCCGR3ZWV0LmlvggoqLmR3ZWV0LmlvMA4GA1Ud\n" \
"DwEB/wQEAwIFoDAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwOwYDVR0f\n" \
"BDQwMjAwoC6gLIYqaHR0cDovL2NybC5zY2ExYi5hbWF6b250cnVzdC5jb20vc2Nh\n" \
"MWIuY3JsMCAGA1UdIAQZMBcwCwYJYIZIAYb9bAECMAgGBmeBDAECATB1BggrBgEF\n" \
"BQcBAQRpMGcwLQYIKwYBBQUHMAGGIWh0dHA6Ly9vY3NwLnNjYTFiLmFtYXpvbnRy\n" \
"dXN0LmNvbTA2BggrBgEFBQcwAoYqaHR0cDovL2NydC5zY2ExYi5hbWF6b250cnVz\n" \
"dC5jb20vc2NhMWIuY3J0MAwGA1UdEwEB/wQCMAAwggEDBgorBgEEAdZ5AgQCBIH0\n" \
"BIHxAO8AdgD2XJQv0XcwIhRUGAgwlFaO400TGTO/3wwvIAvMTvFk4wAAAXJeSgSG\n" \
"AAAEAwBHMEUCIQD53CmIkykPjB+pBYEPJJ2lQ9Hq3sdLy3NRGc7oM6808AIgZykt\n" \
"SufDG1B64bn/61NgHoV4paBBGCVLkAIgei63oAQAdQBc3EOS/uarRUSxXprUVuYQ\n" \
"N/vV+kfcoXOUsl7m9scOygAAAXJeSgSlAAAEAwBGMEQCIA6O+1frH2C0e6WG13Vz\n" \
"99ry7EbVn4+PS0FXOC3THYyjAiA7jjMhO4pbTkBbvrsCAuiKPyfY7EyrmMu3EVtr\n" \
"71i9qTANBgkqhkiG9w0BAQsFAAOCAQEATMyRMgkty9dTe0+RQlc5H5XNPIe4gGtF\n" \
"vhZYWlDRUcmashIHfv39MhHhRcyfj1bgaji0a7aZv0qgwSj5NGI45WaCeS7Ug8K9\n" \
"PZ2NrifoJQEYSMP0+ml+SomlvYIV2L/KVCMIaumMYKej95yVuE6xeZ8JjNXRYPJf\n" \
"mIp1jZ/lf0jHKp5Ccr1q/rMwoMX1pGJWbsFUXTnuk6hCDiZ5ajjv0P+xRhZ+RHp0\n" \
"nfumXhDcWf3/1Af/GW4Xe0nNb1P484pVbf5y9CeQwvuiluEdQDfDS2uIW0hu0bjn\n" \
"5DbjjjMwjAEy0ez47HL/FXZqJ5dzNc4PXPvL3ICMsQ/G/vYIFmqNXg==\n" \
"-----END CERTIFICATE-----\n";

modem.addRootCA(root_ca);
modem.TCPconnect("dweet.io", 8883); // Connect with SSL
modem.TCPsend("test", 5);
modem.TCPclose();
// etc...

modem.MQTTconnect()

Description

Send the connect packet to the MQTT broker.

Note: Must have data enabled and must connect to the server via TCP/UDP before using this command.

Syntax

modem.MQTTconnect(protocol, clientID, username, password)

Parameters

  • protocol: string defining the MQTT protocol. Ex: "MQTT" or "MQIsdp" (for CloudMQTT specifically)
  • clientID: string containing the client ID. This can be the device's IMEI number, custom name, etc.
  • username: string containing the username
  • password: string containing the password

Returns

  • True if successfully connected
  • False otherwise

Example

Please see the IoT_Example sketch for examples on how to use the MQTT functions.

modem.MQTTdisconnect()

Description

Send disconnect packet to the MQTT broker. NOTE: FUNCTION IS UNDER CONSTRUCTION!

Note: Must have data enabled and must be connected to MQTT broker before using this command.

Syntax

modem.MQTTdisconnect()

Parameters

None

Returns

  • True if successfully disconnected
  • False otherwise

Example

Please see the IoT_Example sketch for examples on how to use the MQTT functions.

modem.MQTTpublish()

Description

Publish data to an MQTT topic.

Note: Must have data enabled and must be connected to MQTT broker before using this command.

Syntax

modem.MQTTpublish(topic, message)

Parameters

  • topic: string MQTT topic (or channel) to publish data to
  • message: string packet content to send to the topic

Returns

  • True if successfully published data
  • False otherwise

Example

Please see the IoT_Example sketch for examples on how to use the MQTT functions.

modem.MQTTsubscribe()

Description

Subscribe to an MQTT topic.

Note: Must have data enabled and must be connected to MQTT broker before using this command.

Syntax

modem.MQTTsubscribe(topic, QoS)

Parameters

  • topic: string MQTT topic (or channel) to publish data to
  • QoS: byte MQTT quality of service number

Returns

  • True if successfully subscribed to topic
  • False otherwise

Example

Please see the IoT_Example sketch for examples on how to use the MQTT functions.

modem.MQTTsubscribe()

Description

Unsubscribe to an MQTT topic. NOTE: FUNCTION IS UNDER CONSTRUCTION!

Note: Must have data enabled and must be connected to MQTT broker before using this command.

Syntax

modem.MQTTunsubscribe(topic)

Parameters

  • topic: string MQTT topic (or channel) to unsubscribe from

Returns

  • True if successfully unsubscribed from topic
  • False otherwise

Example

Please see the IoT_Example sketch for examples on how to use the MQTT functions.

modem.MQTTreceive()

Description

Unsubscribe to an MQTT topic. NOTE: FUNCTION IS UNDER CONSTRUCTION!

Note: Must have data enabled and must be subscribed to an MQTT topic before using this command.

Syntax

modem.MQTTreceive(topic, buf, maxlen)

Parameters

  • topic: string MQTT topic (or channel) to receive data from
  • buf: char buffer to hold the data content
  • maxlen: uint8_t max number of characters to read

Returns

  • True if successfully subscribed to topic
  • False otherwise

Example

Please see the IoT_Example sketch for examples on how to use the MQTT functions.

modem.MQTT_setParameter()

Description

Sets the MQTT parameters (see MQTT app note for more details on parameter values). One must use the modem.MQTT_connect(true) command to actually invoke the MQTT connection.

Note: This is only for the SIM7000 and will not work on 2G or 3G modules.

Syntax

modem.MQTT_setParameter(parameterTag, parameterValue, serverPort)

Parameters

  • parameterTag: string parameter tag. Can be "CLIENTID", "URL", "KEEPTIME", "CLEANSS", "USERNAME", "PASSWORD", "QOS", "TOPIC", "MESSAGE", or "RETAIN"
  • parameterValue: string parameter value corresponding to the parameter tag
  • serverPort: uint16_t server port (optional, 0 by default to indicate no port number was assigned if not applicable to to the parameter tag)

Returns

  • True if successfully set MQTT parameter
  • False otherwise

Example

Please see the SIM7000_MQTT_Demo sketch for how to use the MQTT functions.

modem.MQTT_connect()

Description

Connects to or disconnects from the MQTT server with the AT+SMCONN or AT+SMDISC commands after setting MQTT parameters with the modem.MQTT_setParameter() function.

Note: This is only for the SIM7000 and will not work on 2G or 3G modules.

Syntax

modem.MQTT_connect(yesno)

Parameters

  • yesno: bool true or false for connect or disconnect

Returns

  • True if command was successful
  • False otherwise

Example

Please see the SIM7000_MQTT_Demo sketch for how to use the MQTT functions.

modem.MQTT_connectionStatus()

Description

Gets the current MQTT connection status.

Note: This is only for the SIM7000 and will not work on 2G or 3G modules.

Syntax

modem.MQTT_connectionStatus()

Parameters

None

Returns

  • True if currently connected
  • False otherwise

Example

Please see the SIM7000_MQTT_Demo sketch for how to use the MQTT functions.

modem.MQTT_subscribe()

Description

Subscribes to a specified MQTT topic with quality of service (QoS) setting.

Note: This is only for the SIM7000 and will not work on 2G or 3G modules.

Syntax

modem.MQTT_subscribe(topic, QoS)

Parameters

  • topic: string MQTT topic name to subscribe to
  • QoS: byte quality of service, from 0-2

Returns

  • True if successfully subscribed to MQTT topic
  • False otherwise

Example

Please see the SIM7000_MQTT_Demo sketch for how to use the MQTT functions.

modem.MQTT_unsubscribe()

Description

Unsubscribe from MQTT topic.

Note: This is only for the SIM7000 and will not work on 2G or 3G modules.

Syntax

modem.MQTT_unsubscribe(topic)

Parameters

  • topic: string MQTT topic name to unsubscribe from

Returns

  • True if successfully unsubscribed from MQTT topic
  • False otherwise

Example

Please see the SIM7000_MQTT_Demo sketch for how to use the MQTT functions.

modem.MQTT_publish()

Description

Publish a message to an MQTT topic.

Note: This is only for the SIM7000 and will not work on 2G or 3G modules.

Syntax

modem.MQTT_publish(topic, message, contentLength, QoS, retain)

Parameters

  • topic: string MQTT topic name to send message to
  • message: string message to send to the topic, up to 512 bytes long
  • contentLength: uint16_t length of the message in bytes
  • QoS: byte quality of service, from 0-2
  • retain: byte server retain flag, 0 or 1

Returns

  • True if successfully sent message to MQTT topic
  • False otherwise

Example

Please see the SIM7000_MQTT_Demo sketch for how to use the MQTT functions.

modem.MQTT_dataFormatHex()

Description

Change MQTT data format to hex or back to normal.

Note: This is only for the SIM7000 and will not work on 2G or 3G modules.

Syntax

modem.MQTT_dataFormatHex(yesno)

Parameters

  • yesno: bool true or false (hex or normal)

Returns

  • True if successfully set data format
  • False otherwise

Example

Please see the SIM7000_MQTT_Demo sketch for how to use the MQTT functions.

modem.FTP_connect()

Description

Connect to FTP server.

Syntax

modem.FTP_connect(serverIP, port, username, password)

Parameters

  • serverIP: string of server IP address
  • port: uint16_t port number
  • username: FTP username
  • password: FTP password

Returns

  • True if connected to server successfully
  • False otherwise

Example

Please see the FTP_Demo sketch for examples on how to use the FTP functions.

modem.FTP_Quit()

Description

Quit FTP.

Syntax

modem.FTP_Quit()

Parameters

None

Returns

  • True if quit successfully
  • False otherwise

Example

Please see the FTP_Demo sketch for examples on how to use the FTP functions.

modem.FTP_Rename()

Description

Rename a file on FTP server.

Syntax

modem.FTP_Rename(filePath, oldName, newName)

Parameters

  • filePath: string with file path. Ex: "/" for root directory, "/photos/cats/" to get into another directory, etc.
  • oldName: string with old name of file. Ex: "lame123"
  • newName: string with new file name. Ex: "awesome123"

Returns

  • True if file rename was successful
  • False otherwise

Example

Please see the FTP_Demo sketch for examples on how to use the FTP functions.

modem.FTP_Delete()

Description

Delete a file from FTP server.

Syntax

modem.FTP_Delete(fileName, filePath)

Parameters

  • fileName: string with name of the file to delete. Ex: "deleteMe.txt"
  • filePath: string with file path. Ex: "/" for root directory, "/photos/cats/" to get into another directory, etc.

Returns

  • True if file was deleted successfully
  • False otherwise

Example

Please see the FTP_Demo sketch for examples on how to use the FTP functions.

modem.FTP_MDTM()

Description

Get the last modification time (MDTM) of a file on the FTP server.

Syntax

modem.FTP_MDTM(fileName, filePath, &year, &month, &day, &hour, &minute, &second)

Parameters

  • fileName: string with name of the file to get a timestamp of. Ex: "updated.txt"
  • filePath: string with file path. Ex: "/" for root directory, "/photos/cats/" to get into another directory, etc.
  • year: uint16_t year (4 digits)
  • month: uint8_t month
  • day: uint8_t day
  • hour: uint8_t hour
  • minute: uint8_t minute
  • second: uint8_t second

Returns

  • True if MDTM was obtained successfully
  • False otherwise

Example

Please see the FTP_Demo sketch for examples on how to use the FTP functions.

modem.FTP_GET()

Description

Perform an FTP GET request to read data from the server. Automatically uses extended GET when requested number of bytes exceeds 1024 bytes.

NOTE: Function not fully tested!

Syntax

modem.FTP_GET(fileName, filePath, numBytes)

Parameters

  • fileName: string with name of the file to read data from. Ex: "plzdontread.txt"
  • filePath: string with file path. Ex: "/" for root directory, "/confidential/" to get into another directory, etc.
  • numBytes: uint16_t number of bytes to read from the file

Returns

char buffer containing the data read from the file.

Example

Please see the FTP_Demo sketch for examples on how to use the FTP functions.

modem.FTP_PUT()

Description

Perform an FTP PUT request to write data to a file on the server. Automatically uses extended PUT when number of bytes exceeds 1024 bytes.

NOTE: Function not fully tested!

Syntax

modem.FTP_PUT(fileName, filePath, content, numBytes)

Parameters

  • fileName: string with name of the file to read data from. Ex: "plzdontread.txt"
  • filePath: string with file path. Ex: "/" for root directory, "/confidential/" to get into another directory, etc.
  • content: string with content to put in the file. Ex: "lorem ipsum dolor sit amet"
  • numBytes: uint16_t number of bytes to read from the file

Returns

  • True if the FTP PUT was successful
  • False otherwise

Example

Please see the FTP_Demo sketch for examples on how to use the FTP functions.

modem.HTTP_init()

Description

Initialize HTTP with AT+HTTPINIT command.

Syntax

modem.HTTP_init()

Parameters

None

Returns

  • True if the AT command ran successfully
  • False otherwise

Example

modem.HTTP_init(); // Initialize HTTP

modem.HTTP_term()

Description

Terminate HTTP with AT+HTTPTERM command.

Syntax

modem.HTTP_term()

Parameters

None

Returns

  • True if the AT command ran successfully
  • False otherwise

Example

modem.HTTP_term(); // Terminate HTTP

modem.HTTP_para_start()

Description

Start HTTP parameters with AT+HTTPPARA command. Note: this does not actually finish the AT command! See other HTTP functions for explanation.

Syntax

modem.HTTP_para_start(parameter, quoted)

Parameters

  • parameter: flash string with parameter to set. Ex: F("URL") or F("CONTENT")
  • quoted: bool true or false for parameter to be in quotes or not

Returns

Nothing

Example

// The following line prints this: AT+HTTPPARA="URL","
modem.HTTP_para_start(F("URL"), true);

modem.HTTP_para_end()

Description

Low-level function to end the AT+HTTPPARA command based on quoted or not. Note: this is not a complete AT command! See next function for a function that runs a full command.

Syntax

modem.HTTP_para_end(quoted)

Parameters

  • quoted: bool true or false for parameter to be in quotes or not

Returns

  • True if the AT command ran successfully
  • False otherwise

Example

modem.HTTP_init(); // Begin HTTP
modem.HTTP_para_start(F("URL")); // Star the AT+HTTPPARA command
modemSS.println("dweet.io/dweet/for/device123?foo=bar"); // Print the actual value using software/hardware serial
modem.HTTP_para_end(true); // Finish the AT command
// In total, this sends the command AT+HTTPPARA="URL","dweet.io/dweet/for/device123?foo=bar"

modem.HTTP_para()

Description

Set HTTP parameters with the AT+HTTPPARA command.

Syntax

modem.HTTP_para(parameter, value)

Parameters

  • parameter: flash string with parameter to set. Ex: F("URL") or F("CONTENT")
  • value: (string, flash string, or int32_t) value of the parameter. Ex: "dweet.io/dweet/for/device123?foo=bar"

Returns

  • True if the AT command ran successfully
  • False otherwise

Example

modem.HTTP_para(F("URL"), "dweet.io/dweet/for/device123?foo=bar"); // Set HTTP URL

modem.HTTP_data()

Description

Input HTTP data with the AT+HTTPDATA command.

Syntax

modem.HTTP_data(size, maxTime)

Parameters

  • size: uint32_t size of the data to input
  • maxTime: uint32_t max time (in ms) before timing out, 10s by default

Returns

  • True if it sees the response "DOWNLOAD" after sending the command
  • False otherwise

Example

modem.HTTP_data(120, 15000); // Run the command AT+HTTPDATA=32,15000

modem.HTTP_action()

Description

Use the AT+HTTPACTION command.

Syntax

modem.HTTP_action(method, status, datalen, timeout)

Parameters

  • method: uint8_t desired method, 0 for HTTP GET request or 1 for HTTP POST request.
  • status: uint16_t number to store the HTTP status code
  • datalen: uint16_t length of the data for GET or POST
  • timeout: int32_t timeout in milliseconds

Returns

  • True if the AT command ran successfully
  • False otherwise

Example

See HTTP_GET_start() function in BotleticsSIM7000.cpp library file.

modem.HTTP_readall()

Description

Read the HTTP server response with the AT+HTTPREAD command.

Syntax

modem.HTTP_readall(datalen)

Parameters

  • datalen: uint16_t expected length of the data to be read

Returns

  • True if the data that is read has the length equal to the expected length
  • False otherwise

Example

modem.HTTP_readall(150); // Read server response, expecting to read exactly 150 bytes

modem.HTTP_ssl()

Description

Enable or disable SSL for HTTP using the AT+HTTPSSL command. Only works for SIM800.

Syntax

modem.HTTP_ssl(onoff)

Parameters

  • onoff: True or false (enable or disable)

Returns

  • True if the command ran successfully
  • False otherwise

Example

modem.HTTP_ssl(true); // Set up HTTP to use SSL

modem.HTTP_GET_start()

Description

High-level function to perform an HTTP GET request.

Syntax

modem.begin(url, status, datalen)

Parameters

  • url: char array containing the URL
  • status: uint16_t for storing HTTP status code
  • datalen: uint16_t length of the server response

Returns

  • True if the AT command ran successfully
  • False otherwise

Example

See the "w" command in the LTE_Demo sketch

modem.HTTP_GET_end()

Description

End HTTP. Calls the function HTTP_term() and written by Adafruit probably just for the sake of naming the function to match the HTTP_GET_start() command.

Syntax

modem.HTTP_GET_end()

Parameters

None

Returns

  • True if the AT command ran successfully
  • False otherwise

Example

modem.HTTP_GET_end(); // Quit HTTP

modem.HTTP_POST_start()

Description

High-level function to perform an HTTP POST request.

Syntax

modem.HTTP_POST_start(url, contenttype, postdata, postdatalen, status, datalen)

Parameters

  • url: string containing the URL
  • contenttype: flash string value of the HTTP Conten-Type header. Ex: F("text/plain")
  • postdata: uint8_t data to post
  • postdatalen: uint16_t length of the data to post
  • status: uint16_t for storing HTTP status code
  • datalen: uint16_t length of the server response

Returns

  • True if the AT command ran successfully
  • False otherwise

Example

See the "W" command in the LTE_Demo sketch

modem.HTTP_POST_end()

Description

End HTTP. Calls the function HTTP_term() and written by Adafruit probably just for the sake of naming the function to match the HTTP_POST_start() command.

Syntax

modem.HTTP_POST_end()

Parameters

None

Returns

  • True if the AT command ran successfully
  • False otherwise

Example

modem.HTTP_POST_end(); // Quit HTTP

modem.setUserAgent()

Description

Set the user agent, "modem" by default if not explicitly set.

Syntax

modem.setUserAgent(useragent)

Parameters

  • useragent: flash string user agent

Returns

Nothing

Example

modem.setUserAgent(F("myAmazingDevice"));

modem.setHTTPSRedirect()

Description

Enables redirects by setting the "REDIR" parameter to 1 in the AT+HTTPPARA command.

Syntax

modem.setHTTPSRedirect(onoff)

Parameters

  • onoff: True or false (enable or disable)

Returns

  • True if the AT command ran successfully
  • False otherwise

Example

modem.setHTTPSRedirect(true); // Enable redirects

modem.HTTP_connect()

Description

Connects to a server via HTTP

Note: This is only for the LTE class and will not work on 2G or 3G modules. By default, sets max body length to 1024 bytes and max header length to 350 bytes

Syntax

modem.HTTP_connect(server)

Parameters

Returns

  • True if connected to server successfully
  • False otherwise

Example

modem.HTTP_connect("http://httpbin.org");

modem.HTTP_addHeader()

Description

Add HTTP header.

Note: This is only for the LTE class and will not work on 2G or 3G modules.

Syntax

modem.HTTP_addHeader(type, value, maxlen)

Parameters

  • type: string with the HTTP header. Ex: "User-Agent", "Connection", etc.
  • value: string with the value corresponding to the header
  • maxlen: max length of the tag or the value in bytes, whiever is larger

Returns

  • True if the AT command ran successfully
  • False otherwise

Example

modem.HTTP_addHeader("User-Agent", "SIM7070", 7);
modem.HTTP_addHeader("Cache-control", "no-cache", 8);
modem.HTTP_addHeader("Connection", "keep-alive", 10);
modem.HTTP_addHeader("Accept", "*\"*", 3);

modem.HTTP_addPara()

Description

Add HTTP parameter.

Note: This is only for the LTE class and will not work on 2G or 3G modules.

Syntax

modem.HTTP_addPara(key, value, maxlen)

Parameters

  • key: string with the HTTP parameter
  • value: string with the value corresponding to the parameter
  • maxlen: max length of the key or the value in bytes, whiever is larger

Returns

  • True if the AT command ran successfully
  • False otherwise

Example

// Add JSON body parameters for HTTP POST
modem.HTTP_addPara("temperature", "21.8", 11);
modem.HTTP_addPara("humidity", "57.5", 8);

modem.HTTP_GET()

Description

Perform HTTP GET request.

Note: This is only for the LTE class and will not work on 2G or 3G modules.

Syntax

modem.HTTP_GET(URI)

Parameters

  • URI: query string with name/value pairs

Returns

  • True if the GET request was successful
  • False otherwise

Example

modem.HTTP_connect("http://dweet.io");
modem.HTTP_GET("/dweet/for/{device_ID}?temperature=21.3&humidity=56.7");

modem.HTTP_POST()

Description

Perform HTTP POST request.

Note: This is only for the LTE class and will not work on 2G or 3G modules.

Syntax

modem.HTTP_POST(URI, body, bodylen)

Parameters

  • URI: string with the URI
  • body: string with the JSON body
  • bodylen: length of the JSON body in bytes

Returns

  • True if the POST request was successful
  • False otherwise

Example

modem.HTTP_connect("http://dweet.io"); // Connect to server
modem.HTTP_addHeader("Content-Type", "application/json", 16); // Add header if needed
char body[100] = "{\"temp\":21.3,\"humidity\":56.7}"; // Format JSON body
modem.HTTP_POST("/dweet/for/{device_ID}", body, strlen(body)); // HTTP POST

modem.setPWM()

Description

Generate pulse width modulation (PWM) for buzzer. Only works for SIM800 and SIM808.

Syntax

modem.setPWM(freq, duty)

Parameters

  • freq: uint16_t frequency, 0-2000 Hz (0 turns it off)
  • duty: uint8_t PWM duty cycle, 50% by default

Returns

  • True if the AT command ran successfully
  • False otherwise

Example

modem.setPWM(1000); // Set to 1kHz

modem.callPhone()

Description

Call a phone!

Syntax

modem.callPhone(phonenum)

Parameters

  • phonenum: string with the phone number, including country code but only digits (excluding "+" sign or dashes). Ex: if your phone number is +1 222-333-4444 then you should use "12223334444"

Returns

  • True if the call was successful
  • False otherwise

Example

const char * phone_number = "12223334444"; // Include country code but only numbers!

if (!modem.callPhone(phone_number)) {
  Serial.println(F("Call failed"));
}
else {
  Serial.println(F("Sent!"));
}

modem.getCallStatus()

Description

Get the current call status.

Syntax

modem.getCallStatus()

Parameters

None

Returns

uint8_t call status, either one of the values below. Returns 1 if failed.

  • 0 - Ready
  • 2 - Unknown
  • 3 - Ringing
  • 4 - Call in progress

Example

uint8_t callstat = modem.getCallStatus();

switch (callstat) {
  case 0: Serial.println(F("Ready")); break;
  case 1: Serial.println(F("Could not get status")); break;
  case 3: Serial.println(F("Ringing (incoming)")); break;
  case 4: Serial.println(F("Ringing/in progress (outgoing)")); break;
  default: Serial.println(F("Unknown")); break;
}

modem.hangUp()

Description

Hang up from a call.

Syntax

modem.hangUp()

Parameters

None

Returns

  • True if hang up successful
  • False otherwise

Example

if (! modem.hangUp()) {
  Serial.println(F("Failed"));
}
else {
  Serial.println(F("OK!"));
}

modem.pickUp()

Description

Pick up an incoming phone call.

Syntax

modem.pickUp()

Parameters

None

Returns

  • True if successful
  • False otherwise

Example

if (! modem.pickUp()) {
  Serial.println(F("Failed"));
}
else {
  Serial.println(F("OK!"));
}

modem.callerIdNotification()

Description

Set calling line identification presentation parameters. This feature allows you to set up an interrupt whenever the modem receives a phone call.

Syntax

modem.callerIdNotification(onoff, interrupt)

Parameters

  • onoff: True or false (enable or disable)
  • interrupt: uint8_t interrupt pin number. See the Arduino attachInterrupt() function for more details.

Returns

  • True if the AT command ran successfully
  • False otherwise

Example

// Let's assume we're using an Arduino Uno
callerIdNotification(true, 0); // Enable interrupt on digital pin 2 (INT0)

modem.incomingCallNumber()

Description

Extract the number of the caller.

Syntax

modem.incomingCallNumber(phonenum)

Parameters

  • phonenum: char buffer to hold the caller's number

Returns

  • True if successful
  • False if there's no incoming call to begin with

Example

char callerNumber[12]; // Buffer to hold the phone number

if (! modem.incomingCallNumber() ) {
  Serial.println(F("No incoming call!"));
}
else {
  Serial.print(F("Caller number:"));
  Serial.println(callerNumber);
}

modem.expectReply()

Description

Read available lines into the buffer and check for a specific reply from the module. Use this command after sending an AT command to the module.

Syntax

modem.expectReply(reply, timeout)

Parameters

  • reply: flash string of the expected reply. Ex: F("OK") or F("DOWNLOAD")
  • timeout: uint16_t timeout in milliseconds, 10s by default

Returns

  • True if the reply matches the expected reply
  • False otherwise

Example

// Use software serial to send AT command
// Doing it this way is only really useful
// when constructing a command composed of
// several parts.
const char * APN = "hologram";

modemSS.print("AT+CGDCONT=1,\"IP\",");
modemSS.println(APN);

// Read the reply and see if it matches "OK"
if (! modem.expectReply(F("OK")) ) {
  Serial.println(F("Command failed!"));
}
else {
  Serial.println(F("Success!"));
}

modem.sendCheckReply()

Description

Send a command and check the reply for a specific response.

Syntax

modem.sendCheckReply(send, reply, timeout)

Parameters

  • send: string or flash string of the command being sent
  • reply: string or flash string of the expected reply
  • timeout: uint16_t timeout in milliseconds, 500ms by default

Returns

  • True if the reply was as expected
  • False if the reply was not as expected or timed out

Example

// Send command "AT+CREG?" and expect "OK" reply with 1s timeout
if (! modem.sendCheckReply("AT+CREG?", "OK", 1000) ) {
  Serial.println(F("Command failed!"));
}
else {
  Serial.println(F("Success!"));
}

Hardware

Home

Board Versions

Pinouts

Assembly

Software

Arduino IDE Setup

Temperature Sensor Test

Shield Demo

Testing AT Commands

USB Drivers

Connecting to Network

GPS Tracker Example

SMS Messages

FTP Image Transfer Tutorial

Library Functions

Updating Firmware

MDM9206 SDK

Current Consumption

Raspberry Pi

Other

FAQ

Success Stories

Clone this wiki locally