DICENB / DICEGSM – Library

The DICENB (aka DICEGSM) library handles all modem related operations for dice-IoT applications. It is based and hence compatible to the MKRGSM library and used to establish connections to the internet or send SMS etc. Like all IP handling libraries of the dice package (WiFi, Eth etc.), it comes with the advanced client class ‘GSMHTTPClient‘ that provides additional functions to handle HTTP-GET/POST requests and to establish SSL/TLS connections.

Please see the examples in the Arduino IDE: File > Examples > DICENB and also see the MKRGSM library documentation and examples on the internet.

To use this library

#include "DICENB.h"

DICENB library structure

The library provides the following classes. (ref to MKRGSM library):

Main classes

  • GSM class provides the low level functionality to register and establish a connection to the infrastructure (e.g. starting the modem, handling the PIN number of the SIM card, registering to the LTE / 2G network or shutting the modem down etc.).
  • GPRS class let you establish an internet connection (e.g. getting an IP address, resolving DNS names and pinging a peer etc.)
  • GSMHTTPClient class allows to setup a TCP socket, do HTTP requests, establish SSL connections etc. It is based on the HTTP_Client class and the GSMClient class (incl. SSL) and can be used like them. We recommend to just use objects of the GSMHTTPClient class in your applications for any TCP (http, ssl etc.) socket instead of the base classes.
  • GSMUDP class allows to receive and send UDP/IP messages
  • GSM_SMS class let you send and receive SMS

Utility classes

  • GSMBand allows to retrieve the current radio access technology (e.g. LTE, 2G, NBIoT) the modem is operating in.
  • GSMHTTPClient client class for TCP, SSL, HTTP connection clients.
  • GSMClient is the base class for GSMHTTPClient and is compatible to GSMClient
  • GSMSSLClient is compatible to the MKR GSMSSLClient.
    Note: the GSMHTTPClient also gives you SSL functionality by using connectSSL or httpGETSSL.
  • GSMPIN class can be used to work with the SIM card. e.g. changing, deactivating the PIN number or entering the PUK.
  • GSMScanner class allows to scan for available network, to get the signal strength and the current carrier.
  • GSMSSLUtils class helps installing, updating or deleting SSL certificates a/o key files on the modem.
  • GSMModem class let you get information about the modem (IMEI, firmware version etc.)
  • ModemClass and the automatically generated instance MODEM handles the AT command and control of the modem and its power supply. It is used by all the higher level classes described above. It normally not used by the users application directly.

Example

#include <DICENB.h>
GSM gsmAccess;
GPRS gprs;
GSMHTTPClient myHttpClient;

void setup()
{
  while(!Serial);
  Serial.println("STARTUP: " + BOOTLOADER_SETTING.s_get_app_name()+" (V" + BOOTLOADER_SETTING.u32_get_app_version()+")");

  while((gsmAccess.begin("") != GSM_READY) ||
      gprs.attachGPRS("internet.telekom", "t-mobile", "tm") != GPRS_READY)) 
  { yield(); }
    
  Serial.println("Connected.\nDoing a HTTP GET req.");
  int i_ret = myHttpClient.httpGET("di-ce.de", "/downloads/dice-ascii-logo.txt");
  if(i_ret <= 0)
  {
    Serial.println("failed: "+String(i_ret * (-1)));
		myHttpClient.stop();
		while(1) yield();
  }
  Serial.println("OK.\nContent-Length: "+String(i_ret));
}

void loop()
{
  if (myHttpClient.available()) {
    char c = myHttpClient.read();
    Serial.print(c);
    yield();
  }

  // if the server's disconnected, stop the client:
  if (!myHttpClient.available() && !myHttpClient.connected()) {
    Serial.println("\ndisconnecting.");
    Serial.flush();
    myHttpClient.stop();
    while(1){ yield(); };
  }
}

DICENB library compatibility

See the MKRGSM library documentation and examples on the internet. The classes of the DICENB library and the Arduino MKRGSM library are named the same and also their interface (methods etc.) are compatible. Replace MKRGSM.h by DICENB.h in the include section of your application to run code examples on the dice-IoT.

Note: the correct APN credentials for the SIM (provider) are important for proper operation. (particularly for LTE-CAT M1)
If the APN is missing or incorrect, network registration and connection appear to work, but no actual data is transmitted.

Further information

MKRGSM library
GSMClient
HTTP_Client Class
See examples in the Arduino IDE under: File -> Examples -> DICENB ->

GSM class

Methodes:

GPRS class

GSM Client

GSMUDP

GSMUDP

GSM_SMS

GSM_SMS

GSMScanner

GSMBand

GSMSSLUtils

GSMPIN

GSMModem