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 configuration file is located on conf/conf-user.h and is composed of a list of C++ MACROS.

A small example

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

#define NET_ENABLE true
#define NET_MODEM MODEM_SIM800

With these two options we are enabling the network module (NET_ENABLE true) and configuring the communication module MODEM_SIM800.

All the options

Warning

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

// -----------------------------------------------------------------------------
// DEVICE
#define DEVICE_CFG_VERSION 1  // change to invalidate previous stored config
#define DEVICE_DEBUG_LEVEL 3  // 1=err | 2=warn | 3=info | 4=verbose | 0=off
#define DEVICE_NAME ""        // [String] device name (for humans)
#define DEVICE_ID ""          // [String] device id

// -----------------------------------------------------------------------------
// OPMODE
#define OPMODE_DEFAULT OPMODE_NORMAL  // Main operational mode
#define OPMODE_LOW_TIME 300           // Tick1 time interval when

// -----------------------------------------------------------------------------
// TIME & TIMERS
#define TIME_ADD_MSG false  // Add time marks to server messages
#define TIME_TICK1 60       // Main time interval for message creation
#define TIME_TICK2 10       // Secondary time interval

// -----------------------------------------------------------------------------
// NETWORK
#define NET_ENABLE 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 NET_SERVER1 ""      // Remote server ip/domain
#define NET_SERVER2 ""      // Secondary remote server ip/domain
#define NET_PORT1 0         // Remote server port
#define NET_PORT2 0         // Backup remote server port
#define NET_KEEP_TCP false  // Keep TCP open for fast transmissions
#define NET_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

// -----------------------------------------------------------------------------
// GSM
#define GSM_ADD_MSG false   // Add GSM coverage value to messages
#define GSM_LOCATION false  // Enable GSM location if GPS lost coverage

// -----------------------------------------------------------------------------
// BLUETOOTH MODEM
#define BL_ENABLE false          // Enable Bluetooth module
#define BL_MODEM -1              // Select bluetooth modem
#define BL_DEFAULT_ENABLED true  // Enable Bluetooth on startup

// -----------------------------------------------------------------------------
// GPS MODEM
#define GPS_ENABLE 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 GPS_ADD_MSG_LOCATION false  // Add GPS location to messages
#define GPS_ADD_MSG_ALT false       // Add GPS altitude to messages
#define GPS_ADD_MSG_SOG false       // Add GPS speed over ground to messages
#define GPS_ADD_MSG_COG false       // Add orientation to messages
#define GPS_ADD_MSG_SATS false      // Add number of satellites to messages
#define GPS_ADD_MSG_HDOP false      // Add HDOP status to messages

// -----------------------------------------------------------------------------
// Sleep
#define SLEEP_ENABLE false     // Enable sleep mode
#define SLEEP_DEEPSLEEP false  // Turn OFF external device (when posible)
#define SLEEP_TIME 0           // Sleep time in seconds. 0 to use TIME_TICK1
#define SLEEP_AFTER_MSG false  // Set to true to enter sleep after msg is sent

// -----------------------------------------------------------------------------
// GPIOs
#define GPIO_ADD_MSG_PINS -1  // Comma separated list of pins to add to messages
#define GPIO_OUTPUT_PINS      // Comma separated list of OUTPUT pins
#define GPIO_INPUT_PINS       // Comma separated list of INPUT pins
#define GPIO_MASTER IO6

// -----------------------------------------------------------------------------
// LED
#define LED_MODULE -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           // Comma separeted list of ISR pins
#define ISR_DEBOUNCE_TIME 20  // Interruptions debounce in milliseconds

// -----------------------------------------------------------------------------
// SENSORS
#define SENS_ACCEL -1    // Enable accelerometer
#define SENS_TEMP -1     // Enable temperature sensor BME280, DHT11, SHT20...
#define SENS_HUMI -1     // Enable humidity BME280, DHT11, SHT20...
#define SENS_PRESS -1    // Enable atmospheric pressure BME280
#define SENS_NFC -1      // Enable NFC module PN532
#define SENS_RFID -1     // Enable RFID module RC522
#define SENS_TOUCH -1    // Enable sensor Touch SF
#define SENS_GAS -1      // Enable gas sensor
#define SENS_LOCKER -1   // Enable locker sensor
#define SENS_CURRENT -1  // Enable ACS712 current sensor

// Configuration properties for sensor modules
#define SENS_DHT_PIN -1                 // DHT GPIO (IO0, IO1...)
#define SENS_TOUCH_PIN -1               // Touch or Button GPIO (IO0, IO1...)
#define SENS_LOCKER_SERIAL -1           // Serial port for the Locker
#define SENS_LOCKER_RS465_READ_IO PWM0  // Pin to put RS465 in read mode
#define SENS_MQ_PIN AD0                 // Analog pin for MQ gas sensor
#define SENS_PN532_IRQ IO6              // Interruption pin for NFC sensor
#define SENS_PN532_RESET RSTOUT         // Reset for PN532
#define SENS_RC522_SS CS0               // Chip select for RFID RC522
#define ACS712_PIN -1                   // Analog pin for ACS712 current sensor

// -----------------------------------------------------------------------------
// ADC
#define ADC_MODULE -1        // Enable reading data ADC
#define ADC_ADD_MSG -1       // Add ADC to messages
#define ADC_PINS -1          // Set ADC pins (AD)
#define ADC_CLAMPS -1        // Set the clamp for pin
#define ADC_Resolution -1    // Set ADC resolution
#define ADC_Reference -1     // Set ADC reference
#define ADC_Reading_Mode -1  // Set ADC reading mode
#define ADC_PIN_COMPB 0      // Set the second ADC pin (AD2)
#define ADC_PIN_COMPA 0      // (AD3)
#define ADC_PINS_DIFF -1     // Intern differential for pins of ads1015

// -----------------------------------------------------------------------------
// DISPLAYS
#define USE_DISPLAY -1
#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 DISPLAY_BITMAPS 1
#define DISPLAY_TOP 1
#define DISPLAY_BOTTOM 1

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

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

// -----------------------------------------------------------------------------
// BATTERY
#define BATT_MODULE -1           // Enable battery module
#define BATT_ADD_MSG_VBAT false  // Add VBAT (lithium battery) to messages
#define BATT_ADD_MSG_VIN false   // Add VIN (pin VIN) to messages
#define BATT_ADD_MSG_VSYS false  // Add VSYS (usb connector) to messages
#define BATT_REQUIRED_VBAT 0     // minimum vbat before enter sleep mode
#define BATT_REQUIRED_VSYS 0     // minimum vsys before enter sleep mode
#define BATT_REQUIRED_VIN 0      // minimum vin before enter sleep mode

// -----------------------------------------------------------------------------
// CLI
#define CLI_SERIAL 0

// -----------------------------------------------------------------------------
// BUFFERS
#define BUFFER_SIZE_DEVICE_NAME 15
#define BUFFER_SIZE_DEVICE_ID 15
#define BUFFER_SIZE 300
#define BUFFER_SIZE_MSG 300
#define BUFFER_SIZE_MSG_FULL (BUFFER_SIZE_MSG + BUFFER_SIZE_DEVICE_ID + 10)
#define BUFFER_SIZE_APN 1
#define BUFFER_SIZE_APN_USER 1
#define BUFFER_SIZE_APN_PASS 1
#define BUFFER_SIZE_REMOTE_SERVER 15
#define BUFFER_SIZE_SMS_NUMBER 15
#define BUFFER_SIZE_WIFI_NAME 15
#define BUFFER_PUF_EVENTS 20
#define BUFFER_PUF_CALLBACKS 20
#define BUFFER_CMD_ID 20
#define BUFFER_CMD_PROPS 100

Description of properties

Config Version

Property Default value Desc
DEVICE_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

Property Default value Desc
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)

Docs Api

Operational Mode

Property Default value Desc
OPMODE_DEFAULT [Int] OPMODE_NORMAL

Docs Api

Serial Ports

Note

The serial port configuration is defined by default in the file serial/serial-arduino.h, these macros are here for reference and can be copied to conf-user.h to overwrite the default values. More info in Serial Ports section.

Property Default value Desc
CLI_SERIAL [Int] 0 Set the serial port for the CLI module. 0=SERIAL_DEBUG, 1=SERIAL_S1, 2=SERIAL_S2, -1=Disable CLI
USE_SERIAL_SOFTWARE [Bool] false Enables the library SoftwareSerial of Arduino. You can use it with Duino Uno or ESP8266.
SERIAL_DEBUG [HardwareSerial] -1 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_S1 [HardwareSerial] -1 Serial for Slave Module on Socket 1.
SERIAL_S1_BAUDS [Int] 115200 Bauds speed for AT UART
SERIAL_S1_RX [Int] 0 TX pin if software serial is enabled
SERIAL_S1_TX [Int] 0 RX pin if software serial is enabled
SERIAL_S1_WAIT [Bool] false Wait after SERIAL_DEBUG.begin(), for Duino Leonardo and Duino Zero
SERIAL_S2 [HardwareSerial] -1 Serial for Slave Module on Socket 2
SERIAL_S2_BAUDS [Int] 0 Bauds for EXT UART
SERIAL_S2_RX [Int] 0 TX pin if software serial is enabled
SERIAL_S2_TX [Int] 0 RX pin if software serial is enabled
SERIAL_S2_WAIT [Int] false Wait after SERIAL_DEBUG.begin(), for Duino Leonardo and Duino Zero

Docs Tutorial Api

Net Communication

Property Default value Desc
NET_ENABLE [Bool] true Enable communication module. Set to false to use your device only as data logger without remote communication capabilities.
NET_KEEP_TCP [Bool] false Keep TCP open for fast transmissions. True if your TICK1 (transmission time interval) is less than 30 or 10 seconds, false otherwise.
NET_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.
NET_SERVER1 [String] "192.168.1.37" Main remote server ip/domain. You should receive this information if you are using M2M System Source service
NET_PORT1 [Int] 3000 Main remote server port.
NET_SERVER2 [String] "" Backup remote server ip/domain
NET_PORT2 [Int] 3000 Backup remote server port
NET_MODEM [Int] MODEM_ESP32 Select communication module. Available options MODEM_ESP32 or MODEM_SIM800 (SIM800 and SIM868)
NET_SERIAL [Int] -1 Assign a serial object, SERIAL_S1 or SERIAL_S2 (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

Docs Api

Bluetooth

Property Default value Desc
BL_ENABLE [Bool] false Enable Bluetooth module. BL_MODEM should be set. If this macro is FALSE the bl libraries will not be loaded and never available during the life cycle of the application.
BL_MODEM [Int] MODEM_SIM868BL Bluetooth module name, available options: MODEM_ESP32BLC, MODEM_ESP32BLE and MODEM_SIM868BL. Compatible with ESP32 and SIM868.
BL_DEFAULT_ENABLED [Int] false Set the default status. If TRUE the bluetooth will be enabled and available for pairing at startup, otherwise not. It may be recommended to set as false (disable bluetooth) in low power applications or if you simply do not want to use bluetooth communication.

Docs Api

GPS Communication

Property Default value Desc
GPS_ENABLE [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_S1 or SERIAL_S2 (previously defined)

Docs Api

Sleep

Property Default value Desc
SLEEP_ENABLE [Bool] false Enable or disable Sleep. When enable the device will enter on sleep after transmit a message or low voltage (see battery configuration). Set sleep time with SLEEP_TIME
SLEEP_DEEPSLEEP [Bool] false If deep sleep is enabled all peripherals should enter also in sleep 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] 0 Duration of sleep mode in seconds. Set to 0 to use the TIME_TICK1 when SLEEP_ENABLE true

Docs Api

GPIOs

Property Default value Desc
GPIO_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.
GPIO_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.
GPIO_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.

Docs Tutorial Api

Leds

Property Default value Desc
LED_MODULE [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

Docs Api

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
ISR_DEBOUNCE_TIME [int] 20 Debounce time in milliseconds. The debounce prevents multiple interrupts being generated in a short period of time, which can happen, for example, due to bad contact with external wiring in the hardware. For example if a value of 20 is set, only one interrupt will be generated at least every 20 milliseconds.

Docs Tutorial Api

Sensors

Property Default value Desc
USE_SENSORS [Bool] false Enable reading data sensors
SENS_TEMP [Int] -1 Enable temperature sensor. Available options: SENSOR_DHT11, SENSOR_BME280 or -1 to disable
SENS_HUMI [Int] -1 Enable humidity. Available options: SENSOR_DHT11, SENSOR_BME280 or -1 to disable
SENS_PRESS [Int] -1 Enable atmospheric pressure. Available options: SENSOR_BME280 or -1 to disable
SENS_NFC [Int] -1 Enable NFC module. Available modules: SENSOR_NFC_PN532 or -1 to disable
SENS_TOUCH [Int] -1 Enable touch module. Available options: SENSOR_TOUCH_SF or -1 to disable

Docs Tutorial

Time

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

Data Logger Module

Property Default value Desc
LOG_MODULE [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.

Docs Api

Storage Module

Property Default value Desc
STORAGE_MODULE [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)

Docs Api

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
BATT_REQUIRED_VBAT [Int] 0 When VBAT reaches this value the system will enter in sleep mode. 0 To disable sleep mode (not recommended).
BATT_REQUIRED_VSYS [Int] 0 When VSYS/VSUB reaches this value the system will enter in sleep mode. 0 To disable sleep mode.
BATT_REQUIRED_VIN [Int] 0 When VIN reaches this value the system will enter in sleep mode. 0 To disable sleep mode (not recommended).

Docs Api

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