Example showing all possible functionality

This shows most of the functionality of the library at once. It has code in it for every possible sensor and modem and for both AVR and SAMD boards. This example should never be used directly; it is intended to document all possibilities and to verify compilating.

To create your own code, I recommend starting from a much simpler targeted example, like the Logging to MMW example, and then adding to it based on only the parts of this menu example that apply to you.

Walking Through the Code

Defines and Includes

Defines for the Arduino IDE

The top few lines of the examples set defines of buffer sizes and yields needed for the Arduino IDE. That IDE read any defines within the top few lines and applies them as build flags for the processor. This is not standard behavior for C++ (which is what Arduino code really is) - this is a unique aspect of the Arduino IDE.

#ifndef TINY_GSM_RX_BUFFER
#define TINY_GSM_RX_BUFFER 64
#endif
#ifndef TINY_GSM_YIELD_MS
#define TINY_GSM_YIELD_MS 2
#endif
#ifndef MQTT_MAX_PACKET_SIZE
#define MQTT_MAX_PACKET_SIZE 240
#endif

If you are using PlatformIO, you should instead set these as global build flags in your platformio.ini. This is standard behaviour for C++.

build_flags =
    -DSDI12_EXTERNAL_PCINT
    -DNEOSWSERIAL_EXTERNAL_PCINT
    -DMQTT_MAX_PACKET_SIZE=240
    -DTINY_GSM_RX_BUFFER=64
    -DTINY_GSM_YIELD_MS=2

Library Includes

Next, include the libraries needed for every program using ModularSensors.

// The Arduino library is needed for every Arduino program.
#include <Arduino.h>

// Include the main header for ModularSensors
#include <ModularSensors.h>

Logger Settings

Creating Extra Serial Ports

This section of the example has all the code to create and link to serial ports for both AVR and SAMD based boards. The EnviroDIY Mayfly, the Arduino Mega, UNO, and Leonardo are all AVR boards. The Arduino Zero, the M0 and the Sodaq Autonomo are all SAMD boards.

Many different sensors communicate using some sort of serial or transistor-transistor-logic (TTL) protocol. Among these are any sensors using RS232, RS485, RS422. Generally each serial variant (or sometimes each sensor) needs a dedicated serial "port" - its own connection to the processor. Most processors have built in dedicated wires for serial communication - "Hardware" serial. See the page on Arduino streams for much more detail about serial connections with Arduino processors.

AVR Boards

Most Arduino AVR style boards have very few (ie, one, or none) dedicated serial ports available after counting out the programming serial port. So to connect anything else, we need to try to emulate the processor serial functionality with a software library. This example shows three possible libraries that can be used to emulate a serial port on an AVR board.

AltSoftSerial

AltSoftSerial by Paul Stoffregen is the most accurate software serial port for AVR boards. AltSoftSerial can only be used on one set of pins on each board so only one AltSoftSerial port can be used. Not all AVR boards are supported by AltSoftSerial. See the processor compatibility page for more information on which pins are used on supported boards.

#include <AltSoftSerial.h>
AltSoftSerial altSoftSerial;

NeoSWSerial

NeoSWSerial is the best software serial that can be used on any pin supporting interrupts. You can use as many instances of NeoSWSerial as you want. Each instance requires two pins, one for data in and another for data out. If you only want to use the serial line for incoming or outgoing data, set the other pin to -1. Not all AVR boards are supported by NeoSWSerial.

#include <NeoSWSerial.h>          // for the stream communication
const int8_t neoSSerial1Rx = 11;  // data in pin
const int8_t neoSSerial1Tx = -1;  // data out pin
NeoSWSerial  neoSSerial1(neoSSerial1Rx, neoSSerial1Tx);
// To use NeoSWSerial in this library, we define a function to receive data
// This is just a short-cut for later
void neoSSerial1ISR() {
    NeoSWSerial::rxISR(*portInputRegister(digitalPinToPort(neoSSerial1Rx)));
}

When using NeoSWSerial we will also have to actually set the data receiving (Rx) pin modes for interrupt in the setup function.

SoftwareSerial with External Interrupts

The "standard" software serial library uses interrupts that conflict with several other libraries used within this program. I've created a version of software serial that has been stripped of interrupts but it is still far from ideal. This should be used only use if necessary. It is not a very accurate serial port!

Accepting its poor quality, you can use as many instances of SoftwareSerial as you want. Each instance requires two pins, one for data in and another for data out. If you only want to use the serial line for incoming or outgoing data, set the other pin to -1.

const int8_t softSerialRx = A3;  // data in pin
const int8_t softSerialTx = A4;  // data out pin

#include <SoftwareSerial_ExtInts.h>  // for the stream communication
SoftwareSerial_ExtInts softSerial1(softSerialRx, softSerialTx);

When using SoftwareSerial with External Interrupts we will also have to actually set the data receiving (Rx) pin modes for interrupt in the setup function.

Software I2C/Wire

This creates a software I2C (wire) instance that can be shared between multiple sensors. Only Testato's SoftwareWire library is supported.

// A software I2C (Wire) instance using Testato's SoftwareWire
// To use SoftwareWire, you must also set a define for the sensor you want to
// use Software I2C for, ie:
//   `#define MS_RAIN_SOFTWAREWIRE`
//   `#define MS_PALEOTERRA_SOFTWAREWIRE`
// or set the build flag(s):
//   `-D MS_RAIN_SOFTWAREWIRE`
//   `-D MS_PALEOTERRA_SOFTWAREWIRE`
#include <SoftwareWire.h>  // Testato's Software I2C
const int8_t softwareSDA = 5;
const int8_t softwareSCL = 4;
SoftwareWire softI2C(softwareSDA, softwareSCL);

SAMD Boards

The SAMD21 supports up to 6 hardware serial ports, which is awesome. But, the Arduino core doesn't make use of all of them, so we have to assign them ourselves.

This section of code assigns SERCOM's 1 and 2 to act as Serial2 and Serial3 on pins 10/11 and 5/2 respectively. These pin selections are based on the Adafruit Feather M0.

// The SAMD21 has 6 "SERCOM" ports, any of which can be used for UART
// communication.  The "core" code for most boards defines one or more UART
// (Serial) ports with the SERCOMs and uses others for I2C and SPI.  We can
// create new UART ports on any available SERCOM.  The table below shows
// definitions for select boards.

// Board =>   Arduino Zero       Adafruit Feather    Sodaq Boards
// -------    ---------------    ----------------    ----------------
// SERCOM0    Serial1 (D0/D1)    Serial1 (D0/D1)     Serial (D0/D1)
// SERCOM1    Available          Available           Serial3 (D12/D13)
// SERCOM2    Available          Available           I2C (A4/A5)
// SERCOM3    I2C (D20/D21)      I2C (D20/D21)       SPI (D11/12/13)
// SERCOM4    SPI (D21/22/23)    SPI (D21/22/23)     SPI1/Serial2
// SERCOM5    EDBG/Serial        Available           Serial1

// If using a Sodaq board, do not define the new sercoms, instead:
// #define ENABLE_SERIAL2
// #define ENABLE_SERIAL3

#include <wiring_private.h>  // Needed for SAMD pinPeripheral() function

#ifndef ENABLE_SERIAL2
// Set up a 'new' UART using SERCOM1
// The Rx will be on digital pin 11, which is SERCOM1's Pad #0
// The Tx will be on digital pin 10, which is SERCOM1's Pad #2
// NOTE:  SERCOM1 is undefinied on a "standard" Arduino Zero and many clones,
//        but not all!  Please check the variant.cpp file for you individual
//        board! Sodaq Autonomo's and Sodaq One's do NOT follow the 'standard'
//        SERCOM definitions!
Uart Serial2(&sercom1, 11, 10, SERCOM_RX_PAD_0, UART_TX_PAD_2);
// Hand over the interrupts to the sercom port
void SERCOM1_Handler() {
    Serial2.IrqHandler();
}
#endif

#ifndef ENABLE_SERIAL3
// Set up a 'new' UART using SERCOM2
// The Rx will be on digital pin 5, which is SERCOM2's Pad #3
// The Tx will be on digital pin 2, which is SERCOM2's Pad #2
// NOTE:  SERCOM2 is undefinied on a "standard" Arduino Zero and many clones,
//        but not all!  Please check the variant.cpp file for you individual
//        board! Sodaq Autonomo's and Sodaq One's do NOT follow the 'standard'
//        SERCOM definitions!
Uart Serial3(&sercom2, 5, 2, SERCOM_RX_PAD_3, UART_TX_PAD_2);
// Hand over the interrupts to the sercom port
void SERCOM2_Handler() {
    Serial3.IrqHandler();
}
#endif

In addition to creating the extra SERCOM ports here, the pins must be set up as the proper pin peripherals after the serial ports are begun. This is shown in the SAMD Pin Peripherals section of the setup function.

NOTE: The SAMD51 board has an amazing 8 available SERCOM's, but I do not have any exmple code for using them.

Assigning Serial Port Functionality

This section just assigns all the serial ports from the Creating Extra Serial Ports section above to specific functionality. For a board with the option of up to 4 hardware serial ports, like the SAMD21 or Arduino Mega, we use the Serial1 to talk to the modem, Serial2 for modbus, and Serial3 for the Maxbotix.

// If there are additional hardware Serial ports possible - use them!

// We give the modem first priority and assign it to hardware serial
// All of the supported processors have a hardware port available named Serial1
#define modemSerial Serial1

// Define the serial port for modbus
// Modbus (at 9600 8N1) is used by the Keller level loggers and Yosemitech
// sensors
#define modbusSerial Serial2

// The Maxbotix sonar is the only sensor that communicates over a serial port
// but does not use modbus
#define sonarSerial Serial3

For an AVR board where we're relying on a mix of hardware and software ports, we use hardware Serial 1 for the modem, AltSoftSerial for modbus, and NeoSWSerial for the Maxbotix. Depending on how you rank the importance of each component, you can adjust these to your liking.

// We give the modem first priority and assign it to hardware serial
// All of the supported processors have a hardware port available named Serial1
#define modemSerial Serial1

// Define the serial port for modbus
// Modbus (at 9600 8N1) is used by the Keller level loggers and Yosemitech
// sensors
// Since AltSoftSerial is the best software option, we use it for modbus
// If AltSoftSerial (or its pins) aren't avaiable, use NeoSWSerial
// SoftwareSerial **WILL NOT** work for modbus!
#ifdef BUILD_TEST_ALTSOFTSERIAL
#define modbusSerial altSoftSerial  // For AltSoftSerial
#elif defined(BUILD_TEST_NEOSWSERIAL)
#define modbusSerial neoSSerial1  // For Neo software serial
#elif defined(BUILD_TEST_SOFTSERIAL)
#define modbusSerial softSerial1  // For software serial
#else
#define modbusSerial Serial1  // Hardware serial
#endif

// The Maxbotix sonar is the only sensor that communicates over a serial port
// but does not use modbus
// Since the Maxbotix only needs one-way communication and sends a simple text
// string repeatedly, almost any software serial port will do for it.
#ifdef BUILD_TEST_ALTSOFTSERIAL
#define sonarSerial altSoftSerial  // For AltSoftSerial
#elif defined(BUILD_TEST_NEOSWSERIAL)
#define sonarSerial neoSSerial1  // For Neo software serial
#elif defined(BUILD_TEST_SOFTSERIAL)
#define sonarSerial softSerial1  // For software serial
#else
#define sonarSerial Serial1  // Hardware serial
#endif

Logging Options

Here we set options for the logging and dataLogger object. This includes setting the time zone (daylight savings time is NOT applied) and setting all of the input and output pins related to the logger.

// The name of this program file
const char* sketchName = "menu_a_la_carte.ino";
// Logger ID, also becomes the prefix for the name of the data file on SD card
const char* LoggerID = "XXXXX";
// How frequently (in minutes) to log data
const uint8_t loggingInterval = 15;
// Your logger's timezone.
const int8_t timeZone = -5;  // Eastern Standard Time
// NOTE:  Daylight savings time will not be applied!  Please use standard time!

// Set the input and output pins for the logger
// NOTE:  Use -1 for pins that do not apply
const int32_t serialBaud = 115200;  // Baud rate for debugging
const int8_t  greenLED   = 8;       // Pin for the green LED
const int8_t  redLED     = 9;       // Pin for the red LED
const int8_t  buttonPin  = 21;      // Pin for debugging mode (ie, button pin)
const int8_t  wakePin    = 31;  // MCU interrupt/alarm pin to wake from sleep
// Mayfly 0.x, 1.x D31 = A7
// Set the wake pin to -1 if you do not want the main processor to sleep.
// In a SAMD system where you are using the built-in rtc, set wakePin to 1
const int8_t sdCardPwrPin   = -1;  // MCU SD card power pin
const int8_t sdCardSSPin    = 12;  // SD card chip select/slave select pin
const int8_t sensorPowerPin = 22;  // MCU pin controlling main sensor power

Wifi/Cellular Modem Options

This modem section is very lengthy because it contains the code with the constructor for every possible supported modem module. Do NOT try to use more than one modem at a time - it will NOT work.

To create any of the modems, we follow a similar pattern:

First, we'll create a pointer to the serial port (Arduino Stream object) that we'll use for communication between the modem and the MCU. We also assign the baud rate to a variable here. There is a table of Default baud rates of supported modules on the Notes about Modems page. The baud rate of any of the modules can be changed using AT commands or the modem.gsmModem.setBaud(uint32_t baud) function.

Next, we'll assign all the pin numbers for all the other pins connected between the modem and the MCU. Pins that do not apply should be set as -1. There is a table of general Sleep and Reset Pin Labels and Pin Numbers to Use when Connecting to a Mayfly 0.x on the Notes about Modems page.

All the modems also need some sort of network credentials for internet access. For WiFi modems, you need the network name and password (assuming WPA2). For cellular models, you will need the APN assigned to you by the carrier you bought your SIM card from.

Digi XBee Cellular - Transparent Mode

This is the code to use for any of Digi's cellular XBee or XBee3 modules. All of them can be implented as a DigiXBeeCellularTransparent object - a subclass of DigiXBee and loggerModem. To create a DigiXBeeCellularTransparent object we need to know

the serial object name,
the MCU pin controlling modem power,
the MCU pin connected to the status pin,
whether the status pin is the true status pin (ON/SLEEP_N/DIO9) or the CTS_N/DIO7 pin,
the MCU pin connected to the RESET_Npin,
the DTR_N/SLEEP_RQ/DIO8 pin,
and the SIM card's cellular access point name (APN).

Pins that do not apply should be set as -1. A helpful table detailing the pins to use with the EnviroDIY Mayfly is available on the Modem Notes page.

// For any Digi Cellular XBee's
// NOTE:  The u-blox based Digi XBee's (3G global and LTE-M global) can be used
// in either bypass or transparent mode, each with pros and cons
// The Telit based Digi XBees (LTE Cat1) can only use this mode.
#include <modems/DigiXBeeCellularTransparent.h>

// NOTE: Extra hardware and software serial ports are created in the "Settings
// for Additional Serial Ports" section
const int32_t modemBaud = 9600;  // All XBee's use 9600 by default

// Modem Pins - Describe the physical pin connection of your modem to your board
// NOTE:  Use -1 for pins that do not apply
// The pin numbers here are for a Digi XBee with a Mayfly 0.x and LTE adapter
// For options https://github.com/EnviroDIY/LTEbee-Adapter/edit/master/README.md
const int8_t modemVccPin = -1;     // MCU pin controlling modem power
                                   // Option: modemVccPin = A5, if Mayfly SJ7 is
                                   // connected to the ASSOC pin
const int8_t modemStatusPin = 19;  // MCU pin used to read modem status
// NOTE:  If possible, use the `STATUS/SLEEP_not` (XBee pin 13) for status, but
// the CTS pin can also be used if necessary
const bool   useCTSforStatus = false;  // Flag to use the CTS pin for status
const int8_t modemResetPin   = 20;     // MCU pin connected to modem reset pin
const int8_t modemSleepRqPin = 23;     // MCU pin for modem sleep/wake request
const int8_t modemLEDPin =
    redLED;  // MCU pin connected an LED to show modem status

// Network connection information
const char* apn = "xxxxx";  // APN for GPRS connection

// Create the modem object
DigiXBeeCellularTransparent modemXBCT(&modemSerial, modemVccPin, modemStatusPin,
                                      useCTSforStatus, modemResetPin,
                                      modemSleepRqPin, apn);
// Create an extra reference to the modem by a generic name
DigiXBeeCellularTransparent modem = modemXBCT;

Depending on your cellular carrier, it is best to select the proper carrier profile and network. Setting these helps the modem to connect to network faster. This is shows in the XBee Cellular Carrier chunk of the setup function.

Digi XBee3 LTE-M - Bypass Mode

This code is for Digi's LTE-M XBee3 based on the u-blox SARA R410M - used in bypass mode. To create a DigiXBeeLTEBypass object we need to know

the serial object name,
the MCU pin controlling modem power,
the MCU pin connected to the status pin,
whether the status pin is the true status pin (ON/SLEEP_N/DIO9) or the CTS_N/DIO7 pin,
the MCU pin connected to the RESET_Npin,
the DTR_N/SLEEP_RQ/DIO8 pin,
and the SIM card's cellular access point name (APN).

Pins that do not apply should be set as -1. A helpful table detailing the pins to use with the EnviroDIY Mayfly is available on the Modem Notes page.

// For the u-blox SARA R410M based Digi LTE-M XBee3
// NOTE:  According to the manual, this should be less stable than transparent
// mode, but my experience is the complete reverse.
#include <modems/DigiXBeeLTEBypass.h>

// NOTE: Extra hardware and software serial ports are created in the "Settings
// for Additional Serial Ports" section
const int32_t modemBaud = 9600;  // All XBee's use 9600 by default

// Modem Pins - Describe the physical pin connection of your modem to your board
// NOTE:  Use -1 for pins that do not apply
// The pin numbers here are for a Digi XBee with a Mayfly 0.x and LTE adapter
const int8_t modemVccPin    = A5;  // MCU pin controlling modem power
const int8_t modemStatusPin = 19;  // MCU pin used to read modem status
// NOTE:  If possible, use the `STATUS/SLEEP_not` (XBee pin 13) for status, but
// the CTS pin can also be used if necessary
const bool   useCTSforStatus = false;  // Flag to use the CTS pin for status
const int8_t modemResetPin   = 20;     // MCU pin connected to modem reset pin
const int8_t modemSleepRqPin = 23;     // MCU pin for modem sleep/wake request
const int8_t modemLEDPin = redLED;     // MCU pin connected an LED to show modem
                                       // status

// Network connection information
const char* apn = "xxxxx";  // APN for GPRS connection

// Create the modem object
DigiXBeeLTEBypass modemXBLTEB(&modemSerial, modemVccPin, modemStatusPin,
                              useCTSforStatus, modemResetPin, modemSleepRqPin,
                              apn);
// Create an extra reference to the modem by a generic name
DigiXBeeLTEBypass modem = modemXBLTEB;

Depending on your cellular carrier, it is best to select the proper carrier profile and network. Setting these helps the modem to connect to network faster. This is shows in the SARA R4 Cellular Carrier chunk of the setup function.

Digi XBee 3G - Bypass Mode

This code is for Digi's 3G/2G XBee based on the u-blox SARA U201 - used in bypass mode. To create a DigiXBee3GBypass object we need to know

the serial object name,
the MCU pin controlling modem power,
the MCU pin connected to the status pin,
whether the status pin is the "true" status pin (ON/SLEEP_N/DIO9) or the CTS_N/DIO7 pin,
the MCU pin connected to the RESET_Npin,
the DTR_N/SLEEP_RQ/DIO8 pin,
and the SIM card's cellular access point name (APN).

Pins that do not apply should be set as -1. A helpful table detailing the pins to use with the EnviroDIY Mayfly is available on the Modem Notes page.

// For the u-blox SARA U201 based Digi 3G XBee with 2G fallback
// NOTE:  According to the manual, this should be less stable than transparent
// mode, but my experience is the complete reverse.
#include <modems/DigiXBee3GBypass.h>

// NOTE: Extra hardware and software serial ports are created in the "Settings
// for Additional Serial Ports" section
const int32_t modemBaud = 9600;  // All XBee's use 9600 by default

// Modem Pins - Describe the physical pin connection of your modem to your board
// NOTE:  Use -1 for pins that do not apply
// The pin numbers here are for a Digi XBee with a Mayfly and LTE adapter
const int8_t modemVccPin    = A5;  // MCU pin controlling modem power
const int8_t modemStatusPin = 19;  // MCU pin used to read modem status
// NOTE:  If possible, use the `STATUS/SLEEP_not` (XBee pin 13) for status, but
// the CTS pin can also be used if necessary
const bool   useCTSforStatus = false;  // Flag to use the CTS pin for status
const int8_t modemResetPin   = 20;     // MCU pin connected to modem reset pin
const int8_t modemSleepRqPin = 23;     // MCU pin for modem sleep/wake request
const int8_t modemLEDPin = redLED;     // MCU pin connected an LED to show modem
                                       // status

// Network connection information
const char* apn = "xxxxx";  // APN for GPRS connection

// Create the modem object
DigiXBee3GBypass modemXB3GB(&modemSerial, modemVccPin, modemStatusPin,
                            useCTSforStatus, modemResetPin, modemSleepRqPin,
                            apn);
// Create an extra reference to the modem by a generic name
DigiXBee3GBypass modem = modemXB3GB;

Digi XBee S6B Wifi

This code is for the Digi's S6B wifi module. To create a DigiXBeeWifi object we need to know

the serial object name,
the MCU pin controlling modem power,
the MCU pin connected to the status pin,
whether the status pin is the "true" status pin (ON/SLEEP_N/DIO9) or the CTS_N/DIO7 pin,
the MCU pin connected to the RESET_Npin,
the DTR_N/SLEEP_RQ/DIO8 pin,
the wifi access point name,
and the wifi WPA2 password.

Pins that do not apply should be set as -1. A helpful table detailing the pins to use with the EnviroDIY Mayfly is available on the Modem Notes page.

// For the Digi Wifi XBee (S6B)
#include <modems/DigiXBeeWifi.h>

// NOTE: Extra hardware and software serial ports are created in the "Settings
// for Additional Serial Ports" section
const int32_t modemBaud = 9600;  // All XBee's use 9600 by default

// Modem Pins - Describe the physical pin connection of your modem to your board
// NOTE:  Use -1 for pins that do not apply
// The pin numbers here are for a Digi XBee direcly connected to a Mayfly 1.x
const int8_t modemVccPin    = 18;  // MCU pin controlling modem power
const int8_t modemStatusPin = 19;  // MCU pin used to read modem status
// NOTE:  If possible, use the `STATUS/SLEEP_not` (XBee pin 13) for status, but
// the CTS pin can also be used if necessary
const bool   useCTSforStatus = true;  // Flag to use the CTS pin for status
const int8_t modemResetPin   = A5;    // MCU pin connected to modem reset pin
const int8_t modemSleepRqPin = 23;    // MCU pin for modem sleep/wake request
const int8_t modemLEDPin = redLED;    // MCU pin connected an LED to show modem
                                      // status

// Network connection information
const char* wifiId  = "xxxxx";  // WiFi access point name
const char* wifiPwd = "xxxxx";  // WiFi password (WPA2)

// Create the modem object
DigiXBeeWifi modemXBWF(&modemSerial, modemVccPin, modemStatusPin,
                       useCTSforStatus, modemResetPin, modemSleepRqPin, wifiId,
                       wifiPwd);
// Create an extra reference to the modem by a generic name
DigiXBeeWifi modem = modemXBWF;

Espressif ESP8266

This code is for the Espressif ESP8266 or ESP32 operating with "AT" firmware. To create a EspressifESP8266 object we need to know

the serial object name,
the MCU pin controlling modem power,
the reset pin (MCU pin connected to the ESP's RSTB/DIO16),
the wifi access point name,
and the wifi WPA2 password.