Skip to content

User Configuration File

Previously, on Project Configuration, we have seen how to configure rhomb.IoT to work with each microcontroller using PlatformIO, but we have many other parameters to configure how our application will work. The list may be a little long but don't worry, you'll also find ready-made settings that you can simply copy and paste.

The configuration file is located on conf/conf-user.h and is composed of a list of C++ MACROS that we can edit.

A small example

We want to configure the network to transmit data with GPRS. Open conf-user.h, search and edit:

#define USE_NET true
#define NET_MODEM NET_SIM868

With these two options we are enabling the network module (USE_NET true) and configuring the communication module NET_SIM868. Other modems will be listed below.

In this article you will learn about the different sections of the configuration file and how to change the values.

All the options

Warning

This list may be outdated, please see the source code for the last versiĆ³n: conf-user.sample.h

#define CFG_VERSION 1  // change to invalidate previous stored config

// -----------------------------------------------------------------------------
// DEVICE NAME/ID
// See core/device.h for info
#define DEVICE_NAME ""  // [String] device name (for humans)
#define DEVICE_ID ""    // [String] device id

// -----------------------------------------------------------------------------
// SERIAL / UART
#define USE_SERIAL false              // Enable disable all serial functions
#define USE_SERIAL_SOFTWARE           // Load Arduino SoftwareSerial Library
#define SERIAL_DEBUG RH_SERIAL_DEBUG  // Serial object for debug monitor
#define SERIAL_DEBUG_BAUDS 115200     // Speed
#define SERIAL_DEBUG_RX 0             // If software serial enabled, tx pin
#define SERIAL_DEBUG_TX 0             // If software serial enabled, rx pin
#define SERIAL_DEBUG_WAIT false  // wait after begin() for leonardo and zero
#define SERIAL_AT -1             // Serial object for Module1
#define SERIAL_AT_BAUDS 115200   // Speed
#define SERIAL_AT_RX 0           // If software serial enabled, tx pin
#define SERIAL_AT_TX 0           // If software serial enabled, rx pin
#define SERIAL_AT_WAIT false     // wait after begin() for leonardo and zero
#define SERIAL_EXT -1            // Serial object for Module2
#define SERIAL_EXT_BAUDS 0       // Speed
#define SERIAL_EXT_RX 0          // If software serial enabled, tx pin
#define SERIAL_EXT_TX 0          // If software serial enabled, rx pin
#define SERIAL_EXT_WAIT false    // wait after begin() for leonardo and zero
#define SERIAL_CLI -1            // Select a serial to enable (SERIAL_DEBUG)

// -----------------------------------------------------------------------------
// DEBUG
#define DEBUG_LEVEL 3  // 1=error | 2=1+warning | 3=2+info | 4=3+verbose | 0=off

// -----------------------------------------------------------------------------
// NETWORK
#define USE_NET false        // Enable communication module
#define NET_MODEM -1         // Select communication module
#define NET_SERIAL -1        // Assign a serial object (SERIAL_AT or SERIAL_EXT)
#define REMOTE_SERVER1 ""    // Remote server ip/domain
#define REMOTE_SERVER2 ""    // Secondary remote server ip/domain
#define REMOTE_PORT1 0       // Remote server port
#define REMOTE_PORT2 0       // Backup remote server port
#define KEEP_TCP_OPEN false  // Keep TCP open for fast transmissions
#define ADD_MSG_GSM false    // Add GSM coverage value to messages
#define BATCH_TRANSMIT 0     // Transmit multiple messages at once
#define WIFI_SSID ""         // wifi ssid when MODEM_ESP32/ESP8266
#define WIFI_PASS ""         // wifi pasword when MODEM_ESP32/ESP8266
#define WIFI_AP_SSID "rhomb.iot"  // Wifi hotspot SSID for ESP32/8266
#define WIFI_AP_PASS "12345678"   // Wifi hotspot SSID for ESP32/8266
#define SIM_APN ""                // SIM APN
#define SIM_USER ""               // SIM APN User
#define SIM_PASS ""               // SIM APN Pass
#define NET_RESET_ISR NMI  // Reset pin to enable Wifi AP mode. -1 disable

// -----------------------------------------------------------------------------
// BLUETOOTH MODEM
#define USE_BL false  // Enable Bluetooth module
#define BL_MODEM -1   // Select bluetooth modem

// -----------------------------------------------------------------------------
// GPS MODEM
#define USE_GPS false           // Enable GPS module
#define GPS_MODEM -1            // Select GPS module, GPS_L86 or GPS_868
#define GPS_SERIAL -1           // Assign a serial object, SERIAL_AT/SERIAL_EXT
#define ADD_MSG_LOCATION false  // Add GPS location to messages
#define ADD_MSG_ALT false       // Add GPS altitude to messages
#define ADD_MSG_SOG false       // Add GPS speed over ground to messages
#define ADD_MSG_COG false       // Add orientation to messages
#define ADD_MSG_SATS false      // Add number of satellites to messages
#define ADD_MSG_HDOP false      // Add HDOP status to messages

// -----------------------------------------------------------------------------
// Sleep & Watchdog
#define USE_WDT false          // Enable the watchgog timer
#define USE_SLEEP false        // Enable sleep mode
#define USE_DEEPSLEEP false    // Turn OFF external device (when posible)
#define SLEEP_TIME -1          // Sleep time in seconds.
#define SLEEP_AFTER_MSG false  // Set to false to enter sleep only with battery

// -----------------------------------------------------------------------------
// GPIOs
#define ADD_MSG_PINS -1  // Comma separated list of pins to add to messages
#define OUTPUT_PINS      // Comma separated list of OUTPUT pins
#define INPUT_PINS       // Comma separated list of INPUT pins

// -----------------------------------------------------------------------------
// LED
#define USE_LED -1  // Set led module, -1 to disable

// -----------------------------------------------------------------------------
// Interruptions
#define ISR_MODE ISR_SIMPLE          // Set ISR with simple or advance mode
#define ISR_PIN -1                   // Set ISR pin
#define ISR_PINS -1, -1, -1, -1, -1  // Comma separeted list of ISR pins

// -----------------------------------------------------------------------------
// SENSORS
#define USE_SENSORS false  // Enable reading data sensors
#define USE_SENS_ACCEL     // Enable accelerometer
#define USE_SENS_TEMP -1   // Enable temperature sensor BME280, DHT11, SHT20...
#define USE_SENS_HUMI -1   // Enable humidity BME280, DHT11, SHT20...
#define USE_SENS_PRESS -1  // Enable atmospheric pressure BME280
#define USE_SENS_ACCEL -1  // Enable the accelerometer
#define USE_SENS_NFC -1    // Enable NFC module PN532
#define USE_SENS_RFID -1   // Enable RFID module RC522
#define USE_SENS_TOUCH -1  // Enable sensor Touch SF
#define USE_SENS_GAS -1
#define USE_SENS_LOCKER -1

// Configuration properties for sensor modules
#define DHT_PIN -1                 // DHT GPIO (IO0, IO1...)
#define TOUCH_PIN -1               // Touch or Button GPIO (IO0, IO1...)
#define LOCKER_SERIAL SERIAL_EXT   // Serial port for the Locker
#define LOCKER_RS465_READ_IO PWM0  // Pin to put RS465 in read mode
#define MQ_PIN AD0                 // Analog pin for MQ gas sensor
#define PN532_IRQ IO6              // Interruption pin for NFC sensor
#define PN532_RESET RSTOUT         // Reset for PN532
#define RC522_SS CS0               // Chip select for RFID RC522

// -----------------------------------------------------------------------------
// ADC
#define USE_ADC ADC_ARDUINO  // Enable reading data ADC
#define ADD_MSG_ADC FALSE    // Add ADC to messages

// Configuration properties for ADC
#define ADC_PINS AD3                  // Set ADC pins
#define ADC_Resolution 12             // Set ADC resolution
#define ADC_Reference AR_INTERNAL1V0  // Set ADC reference
#define ADC_Reading_Mode Combined     // Set ADC reading mode
#define ADC_PIN_COMPB AD2             // Set the second ADC pin, it is for doing
// the difference between COMPA y COMPB (COMPA-COMPB)
#define ADC_PIN_COMPA AD3

// -----------------------------------------------------------------------------
// DISPLAYS
#define USE_DISPLAY DISPLAY_TFT_240
#define DISPLAY_TFT_240_PIN_CS -1
#define DISPLAY_TFT_240_PIN_DC IO6
#define DISPLAY_TFT_240_PIN_MOSI MOSI
#define DISPLAY_TFT_240_PIN_SCLK SCK
#define DISPLAY_TFT_240_PIN_RST MISO
#define DISPLAY_TFT_240_PIN_MISO -1
#define DISPLAY_ROTATION 0  // 0-> Vertical
#define DISPLAY_BACKGROUND ILI9341_LIGHTGREY
#define USE_BITMAPS 1
#define USE_DISPLAY_TOP 1
#define USE_DISPLAY_BOTTOM 1

// -----------------------------------------------------------------------------
// TIME & TIMERS
#define ADD_MSG_TIME false  // Add time marks to server messages
#define TICK_TIMER1 60      // Main time interval for message creation
#define TICK_TIMER2 10      // Secondary time interval

// -----------------------------------------------------------------------------
// DATA LOGGER
#define USE_LOG -1  // Data logger module to backup messages

// -----------------------------------------------------------------------------
// STORAGE
#define USE_STORAGE -1  // Memory method for persistent configuration

// -----------------------------------------------------------------------------
// BATTERY
#define USE_BATT -1         // Enable battery module
#define ADD_MSG_VBAT false  // Add VBAT (lithium battery) to messages
#define ADD_MSG_VIN false   // Add VIN (pin VIN) to messages
#define ADD_MSG_VSYS false  // Add VSYS (usb connector) to messages
#define REQUIRED_VBAT 0     // minimum vbat before enter sleep mode
#define REQUIRED_VSYS 0     // minimum vsys before enter sleep mode
#define REQUIRED_VIN 0      // minimum vin before enter sleep mode

// -----------------------------------------------------------------------------
// BUFFERS
#define BUFFER_SIZE 120
#define BUFFER_SIZE_MSG 120
#define BUFFER_SIZE_APN 15
#define BUFFER_SIZE_APN_USER 1
#define BUFFER_SIZE_APN_PASS 1
#define BUFFER_SIZE_REMOTE_SERVER 15
#define BUFFER_SIZE_SMS_NUMBER 1
#define BUFFER_SIZE_DEVICE_NAME 15
#define BUFFER_SIZE_DEVICE_ID 15
#define BUFFER_SIZE_WIFI_NAME 15

Along this article we will explain these options.

Property Default value Desc
CFG_VERSION [Int] 1 Change to invalidate previous stored config. When there is a configuration saved on EEPROM the device will omit de user-conf and use the saved config. You have to invalidate saved conf if you make a change in your user conf file
DEVICE_NAME [String] "" Name for your device. It will be visible in web dashboard, when making a Bluetooth connection or while using Bluetooth.
DEVICE_ID [String] "" The device ID. It is usually set automatically when using a net modem like SIM868 (with SIM IMEI) or ESP32 (Wifi MAC address)

Serial Ports

Property Default value Desc
USE_SERIAL_SOFTWARE [Bool] false Enables the library SoftwareSerial of Arduino. You can use it with Duino Uno or ESP8266.
SERIAL_DEBUG [HardwareSerial] Serial Corresponding Arduino hardware Serial object for debug monitor. Usually is Serial, Serial1, Serial2, SerialUSB, SerialX... Use SERIAL_SOFTWARE to enable software library for this serial.
SERIAL_DEBUG_BAUDS [Int] 115200 Bauds for debug monitor
SERIAL_DEBUG_TX [Int] 0 TX pin if software serial is enabled. You should connect this pin to the RX of an external FTDItoUSB device connected to your computer.
SERIAL_DEBUG_RX [Int] 0 RX pin if software serial is enabled. As TX, connect to an external FTDItoUSB (TX pin)
SERIAL_DEBUG_WAIT [Bool] false Wait after SERIAL_DEBUG.begin(), for Duino Leonardo and Duino Zero
SERIAL_AT [HardwareSerial] Serial2 Serial object for modem communication (At commands). Bellow you can assign this serial to a Slave Module like SIM800/SIM868 or GPS L86, or any other module that requires UART communication. Use SERIAL_SOFTWARE to enable software library for this serial.
SERIAL_AT_BAUDS [Int] 115200 Bauds speed for AT UART
SERIAL_AT_RX [Int] 0 TX pin if software serial is enabled
SERIAL_AT_TX [Int] 0 RX pin if software serial is enabled
SERIAL_AT_WAIT [Bool] false Wait after SERIAL_DEBUG.begin(), for Duino Leonardo and Duino Zero
SERIAL_EXT [HardwareSerial] -1 Serial object for external UART controller
SERIAL_EXT_BAUDS [Int] 0 Bauds for EXT UART
SERIAL_EXT_RX [Int] 0 TX pin if software serial is enabled
SERIAL_EXT_TX [Int] 0 RX pin if software serial is enabled
SERIAL_EXT_WAIT [Int] false Wait after SERIAL_DEBUG.begin(), for Duino Leonardo and Duino Zero

Net Communication

Property Default value Desc
USE_NET [Bool] true Enable communication module. Set to false to use your device only as data logger without remote communication capabilities.
KEEP_TCP_OPEN [Bool] false Keep TCP open for fast transmissions. True if your TICK1 (transmission time interval) is less than 30 or 10 seconds, false otherwise.
BATCH_TRANSMIT [Int] 5 Transmit multiple messages at once. Each created message will be saved in a buffer (module storage), when the limit of messages is reached the transmission of all will begin. This option will help you save on battery and data connection costs. The max number of messages is relative to the selected storage module.
REMOTE_SERVER1 [String] "192.168.1.37" Main remote server ip/domain. You should receive this information if you are using M2M System Source service
REMOTE_PORT1 [Int] 3000 Main remote server port.
REMOTE_SERVER2 [String] "" Backup remote server ip/domain
REMOTE_PORT2 [Int] 3000 Backup remote server port
NET_MODEM [Int] MODEM_ESP32 Select communication module. Available options MODEM_ESP32 orMODEM_SIM800` (SIM800 and SIM868)
NET_SERIAL [Int] -1 Assign a serial object, SERIAL_AT or SERIAL_EXT (previously defined). -1 to not use serial for this port (not recommended)
WIFI_SSID [String] "" Wifi ssid if assigned NET_MODEM = MODEM_ESP32. Keep empty to use the AP mode
WIFI_PASS [String] "" Wifi pass if assigned NET_MODEM = MODEM_ESP32. Keep empty to use the AP mode
WIFI_AP_SSID [String] "rhomb.iot" Wifi hot spot user for AP modem if assigned NET_MODEM = MODEM_ESP32. The device can generate a Wifi network (hotspot). You can connect to this wifi from your phone using this SSID as network name.
WIFI_AP_PASS [String] "12345678" Wifi hot spot pass for AP modem if using NET_MODEM = MODEM_ESP32
SIM_APN [String] "" SIM APN server when using SIM800/SIM868 for GPRS Data
SIM_USER [String] "rhomb.iot" SIM APN user when using SIM800/SIM868 for GPRS Data
SIM_PASS [String] "12345678" SIM APN pass when using SIM800/SIM868 for GPRS Data

Bluetooth

Property Default value Desc
USE_BL [Bool] false Enable Bluetooth module. This is under development and not ready for production
BL_MODEM [Int] false Bluetooth module name, available options: MODEM_ESP32BLC, MODEM_ESP32BLE and MODEM_SIM868BL

GPS Communication

Property Default value Desc
USE_GPS [Bool] false Enable GPS module
GPS_MODEM [Int] -1 Select GPS module, GPS_L86 or GPS_868
GPS_SERIAL [Int] -1 Assign a serial object, SERIAL_AT or SERIAL_EXT (previously defined)

Sleep & Watchdog

Property Default value Desc
USE_WDT [Bool] false Enable or disable the watchdog. Usually it should be enable
USE_SLEEP [Bool] false Enable or disable Sleep. When enable the device will enter on sleep after transmit a message. Set sleep time with SLEEP_TIME
USE_DEEPSLEEP [Bool] false The deep sleep function may be use with other module to enable a los power mode. For example a GPRS modem can be turn off to save battery but this can also mean that upon awakening, an activation process has to be carried out (connect again to GSM network)
SLEEP_TIME [Int] -1 Duration of sleep mode in seconds. Set to 0 to use the TICK_TIMER1 when USE_SLEEP true

GPIOs

Property Default value Desc
ADD_MSG_PINS [Int] NMI Comma separated list of pins to add to messages. When a message is created the GPIO module will read the status of this GPIOS, configured as outputs.
OUTPUT_PINS [Int] NMI Comma separated list of OUTPUT pins. On startup the method pinMode(GPIO; OUTPUT) of arduino will be executed on each pin.
INPUT_PINS [Int] NMI Comma separated list of INPUT pins. On startup the method pinMode(GPIO; INPUT) of arduino will be executed on each pin.

Leds

Property Default value Desc
USE_LED [Int] -1 Enable the Led module. Set -1 to turn off the led always or one of the avalable modules: LEDLED_RGB_ESP32 or LED_ON_BOARD

Interruptions

Property Default value Desc
ISR_MODE [Int] ISR_SIMPLE Select the ISR module, ISR_SIMPLE or ISR_ADVANCE
ISR_PIN [Int] NMI ISR pin for module ISR_SIMPLE
ISR_PINS [Int] NMI, -1, -1, -1, -1 Pin interruption for module ISR_ADVANCE. There is a list of 5 available pins. The list should have always 5 values, with -1 for those not in use

Sensors

Property Default value Desc
USE_SENSORS [Bool] false Enable reading data sensors
USE_SENS_TEMP [Int] -1 Enable temperature sensor. Available options: SENSOR_DHT11, SENSOR_BME280 or -1 to disable
USE_SENS_HUMI [Int] -1 Enable humidity. Available options: SENSOR_DHT11, SENSOR_BME280 or -1 to disable
USE_SENS_PRESS [Int] -1 Enable atmospheric pressure. Available options: SENSOR_BME280 or -1 to disable
USE_SENS_NFC [Int] -1 Enable NFC module. Available modules: SENSOR_NFC_PN532 or -1 to disable
USE_SENS_TOUCH [Int] -1 Enable touch module. Available options: SENSOR_TOUCH_SF or -1 to disable

Time

Property Default value Desc
ADD_MSG_TIME [Bool] true Add date and time to messages
TICK_TIMER1 [Int] 10 Main time interval for message creation. 0 to disable.
TICK_TIMER2 [Int] 0 Secondary time interval. 0 to disable.

Data Logger Module

Property Default value Desc
USE_LOG [Int] -1 Data logger module to backup failed message transmissions. Currently only available with ESP32 using SPIFFS. Available options: LOG_ESP_SPIFF for ESP32 or -1 for others.

Storage Module

Property Default value Desc
USE_STORAGE [Int] -1 Memory method for persistent configuration. Available options are STORAGE_EEPROM_ARDUINO for AVR (Uno, Mega Leonardo) and ESP; STORAGE_EEPROM_ZERO For Duino Zero (SAMD21)

Battery Management

Property Default value Desc
ADD_BATT_MSG [Int] -1 Enable reading battery status. Available options: BATT_TLA2024 when using a Halley or Hydra PCB; BATT_DEIMOS when using a Deimos PCB with Power Shield; BATT_SIMCOM A reading of battery using the Slave Module SIM868. The most complete option is BATT_TLA2024, with support for reading VBAT, VSYS/VUSB and VIN.
ADD_VBAT_MSG [Int] true Read VBAT (lithium battery) and add to the message
ADD_VSYS_MSG [Int] true read VSYS (usb connector) and add to the message
ADD_VIN_MSG [Int] true read VIN (pin VIN) and add to the message
REQUIRED_VBAT [Int] 0 When VBAT reaches this value the system will enter in sleep mode. 0 To disable sleep mode (not recommended).
REQUIRED_VSYS [Int] 0 When VSYS/VSUB reaches this value the system will enter in sleep mode. 0 To disable sleep mode.
REQUIRED_VIN [Int] 0 When VIN reaches this value the system will enter in sleep mode. 0 To disable sleep mode (not recommended).

Buffer sizes

Property Default value Desc
BUFFER_SIZE 120 Max size for Global buffer. Modules can use it as a temporary space to save any data.
BUFFER_SIZE_MSG 120 Max size for messages
BUFFER_SIZE_APN 15 Max size for APN server
BUFFER_SIZE_APN_USER 1 Max size for APN user
BUFFER_SIZE_APN_PASS 1 Max size for APN pass
BUFFER_SIZE_REMOTE_SERVER 15 Max size for remote server string
BUFFER_SIZE_DEVICE_NAME 15 Max size for device name
BUFFER_SIZE_DEVICE_ID 15 Max size for device ID
BUFFER_SIZE_WIFI_NAME 15 Max size for wifi APN SSID/Pass

Comments