Skip to content

Device Settings and Configuration

The SMARTA L v2 device offers a range of configurable settings to tailor its operation to specific user needs and environmental conditions. These settings are persistently stored in Non-Volatile Storage (NVS) using the Preferences library, ensuring they are retained across reboots and power cycles.

Settings can be managed through multiple interfaces:

  • Physical Button Interface: A menu accessible via the onboard push button allows users to view and modify key parameters directly on the device, with feedback provided on the OLED display.
  • BLE (Bluetooth Low Energy): A mobile application can connect to the device via BLE to read and write various configuration settings through dedicated BLE characteristics.
  • MQTT: Certain settings can be updated remotely by publishing messages to specific MQTT topics.

Key Configurable Parameters

The following is a list of primary settings that can be configured. They are typically stored under the "settings" namespace in NVS.

Operational Parameters

  • Min Level (min_level):
    • Description: The minimum tank level percentage that triggers pump activation (if triggers_active is true).
    • Interface: Button Menu ("Min Level"), BLE (min:<value> via Pump Control Characteristic), MQTT.
    • Default: 5 (cm)
    • Storage: preferences.getInt("min_level", 5)
  • Max Level (max_level):
    • Description: The maximum tank level percentage that triggers pump deactivation (if triggers_active is true).
    • Interface: Button Menu ("Max Level"), BLE (max:<value> via Pump Control Characteristic), MQTT.
    • Default: 50 (cm)
    • Storage: preferences.getInt("max_level", 50)
  • Triggers Active (triggers_active):
    • Description: Enables or disables automatic pump control based on Min/Max levels.
    • Interface: Button Menu ("Active"), BLE (active:<0_or_1> via Pump Control Characteristic), MQTT.
    • Default: true
    • Storage: preferences.getBool("triggers_active", true) (also preferences.getBool("triggers", true))
  • Mute (mute):
    • Description: Silences the onboard buzzer for alerts and notifications.
    • Interface: BLE (mute:<0_or_1> via Pump Control Characteristic), MQTT.
    • Default: false
    • Storage: preferences.getBool("mute", false)
  • Pump Max Runtime (pump_max):
    • Description: Maximum duration (in seconds) the pump is allowed to run continuously to prevent damage.
    • Interface: BLE, MQTT (specific command not detailed in provided context, but likely settable).
    • Default: 300 (seconds)
    • Storage: preferences.getInt("pump_max", 300)

Sensor and Calibration

  • Sensor Type (sensorType):
    • Description: Specifies the type of pressure sensor being used (e.g., "2bar", "10bar"). This affects how raw ADC values are interpreted.
    • Interface: BLE (cal:${selectedSensor},${rawZero},${totalHeight} via Pump Control Characteristic), MQTT.
    • Default: "2bar"
    • Storage: preferences.getString("sensorType", "2bar")
  • Raw Zero (raw_zero):
    • Description: The raw ADC value from the pressure sensor when the tank is empty. Used for calibration.
    • Interface: Button Menu ("Raw Zero"), BLE (cal:..., rawset:... via Pump Control Characteristic), MQTT.
    • Default: 88 (for 2bar sensor), 3654 (for 10bar sensor)
    • Storage: preferences.getInt("raw_zero", ...)
  • Raw Max (raw_max):
    • Description: The raw ADC value from the pressure sensor when the tank is at the 'known height'. Used for calibration. (Note: height seems to be the more relevant parameter for full scale).
    • Interface: BLE (cal:... via Pump Control Characteristic), MQTT.
    • Default: 27000
    • Storage: preferences.getInt("raw_max", 27000)
  • Height (height):
    • Description: The known height (e.g., in cm) corresponding to the raw_max sensor reading, used for calibration.
    • Interface: BLE (cal:... via Pump Control Characteristic), MQTT.
    • Default: 100
    • Storage: preferences.getInt("height", 100)
  • Sensor MAC Address / ADV ID (adv_id):
    • Description: The MAC address or advertising identifier of the BLE tank level sensor the device should connect to.
    • Interface: Button Menu ("Sensor"), BLE (Sensor MAC Characteristic f3b5a8d4-2b6e-4a1b-8b1e-3c4d5e6f7a96), MQTT.
    • Default: "00:00:00:00:00:00"
    • Storage: preferences.getString("adv_id", "00:00:00:00:00:00")
  • Sensor Communication Loss Threshold (sensorCommsLossThreshold):
    • Description: Time in seconds without receiving sensor data before considering the sensor connection lost.
    • Interface: MQTT (COMMS_LOSS_MAX message type).
    • Default: 120 (seconds)
    • Storage: preferences.getInt("sensorCommsLossThreshold", 120) (from MQTT.ino, SMARTA_L_v2.ino uses level_condition_gap_threshold)
  • Level Condition Gap Threshold (lcgt or level_condition_gap_threshold):
    • Description: Time in milliseconds. If the time since the last valid sensor data exceeds this, the current level reading might be considered stale or invalid.
    • Interface: BLE (lcgt:<value> via Pump Control Characteristic), MQTT.
    • Default: 120000 (ms) or 240000 (ms) depending on source.
    • Storage: preferences.getInt("lcgt", 120000)

Connectivity Settings

  • Wi-Fi SSID & Password:
    • Description: Credentials for connecting to the local Wi-Fi network.
    • Interface: BLE (Wi-Fi Credentials Characteristic f3b5a8d4-2b6e-4a1b-8b1e-3c4d5e6f7a94, XOR encrypted), Captive Portal.
    • Storage: preferences.getString("ssid", ""), preferences.getString("password", "") under "wifi" namespace.
    • Reset: Via MQTT ("CW" command) to "SMARTA HOTSPOT"/"SMARTA123".
  • LTE APN (apn):
    • Description: Access Point Name for the cellular (LTE) modem.
    • Interface: BLE (apn:<apn_value> via Pump Control Characteristic, or formatted in Wi-Fi Credentials characteristic), MQTT.
    • Default: "internet" (or "" from config.h)
    • Storage: preferences.getString("apn", "internet")
  • MQTT Broker (mqtt_server, mqtt_port, mqtt_user, mqtt_password):
    • Description: Connection details for the MQTT broker.
    • Interface: Primarily defined in config.h. Potentially updatable via remote commands (not fully detailed for all parameters).
    • Defaults: See config.h (e.g., smarta.ganarprojects.co.za, port 1883).
  • MQTT Interval (mqtti):
    • Description: Interval in seconds for publishing MQTT data.
    • Interface: (Likely BLE/MQTT, not explicitly detailed).
    • Default: 30 (seconds)
    • Storage: preferences.getInt("mqtti", 30) (value is multiplied by 1000 for ms).
  • Wi-Fi Only Mode (wifiOnly):
    • Description: If true, the device will only use Wi-Fi and not failover to LTE.
    • Interface: MQTT (WIFI_ONLY message type), BLE.
    • Default: false
    • Storage: preferences.getBool("wifiOnly", false)
  • Reboot on Connectivity Loss (rocl or rebootOnConnectivityLoss):
    • Description: If true, the device will reboot after a certain number of failed attempts to connect to the internet.
    • Interface: BLE (rocl:<0_or_1> via Pump Control Characteristic), MQTT.
    • Default: true
    • Storage: preferences.getBool("rocl", true) (also preferences.getBool("rebootOnConnectivityLoss", true))
  • OTA Base URL (baseUrl):
    • Description: The base URL for fetching firmware updates.
    • Interface: (Likely BLE/MQTT, not explicitly detailed for updates, defined in config.h).
    • Default: "https://smartapms.ganarprojects.co.za/firmware/lite"
    • Storage: preferences.getString("baseUrl", ...)

System & Miscellaneous

  • Device Name (name):
    • Description: A name for the device, potentially used in network identification or MQTT client ID.
    • Interface: (Likely BLE/MQTT).
    • Default: "SMARTA-L"
    • Storage: preferences.getString("name", "SMARTA-L")
  • Push Token (pushtoken):
    • Description: A token for push notifications, likely for a companion mobile app.
    • Interface: BLE (pushtoken:<value> via Pump Control Characteristic), MQTT.
    • Default: "" (empty string)
    • Storage: preferences.getString("pushtoken", "")
  • Local Storage Interval (lsi):
    • Description: Interval in seconds for local data logging (details of what is logged not fully specified).
    • Interface: (Likely BLE/MQTT).
    • Default: 900 (seconds)
    • Storage: preferences.getInt("lsi", 900)
  • Factory Reset Flag (factory_reset):
    • Description: A boolean flag that, if set to true on boot, will trigger a factory reset.
    • Interface: Set internally when factory reset is initiated via Button Menu or MQTT.
    • Storage: preferences.putBool("factory_reset", true) (temporary before reset).

Settings Management in Code

  • Loading Settings:
    • The getSettingValues() function in main.ino is responsible for loading these parameters from NVS into global variables at startup.
  • Saving Settings:
    • Functions like setPreferenceString(), setPreferenceInt(), setPreferenceBool() (helper functions in SMARTA_L_v2.ino) are used throughout the code to save settings to NVS.
    • Changes made via the button menu (handleSettingChange() in SMARTA_L_v2.ino), BLE callbacks (e.g., PumpControlCallbacks::onWrite() in main.ino), or MQTT (handleMessage() in MQTT.ino) will trigger saving the updated values.
  • Button Menu Interaction:
    • The settingsTask() in SMARTA_L_v2.ino manages navigation through the settings menu.
    • handleSettingChange() allows interactive adjustment of numerical settings.
    • showSetting() displays the current setting and value on the OLED.
  • Clearing Settings:
    • resetSettings() and resetWiFiSettings() in main.ino can clear all settings or just Wi-Fi credentials from their respective namespaces.
    • A factory reset (handleFactoryReset() in main.ino) will typically clear relevant settings.

Default Values

Default values are provided in the preferences.get<Type>() calls if a setting is not found in NVS. Some global defaults are also present in config.h.

This document provides a comprehensive overview of the device's settings. For the most precise details on implementation, refer to the source code files mentioned, particularly main.ino, SMARTA_L_v2.ino, MQTT.ino, and config.h.