Added comments to general.h file

code/espurna/config/general.h

@@ -1,19 +1,23 @@
+//------------------------------------------------------------------------------
+// Do not change this file unless you know what you are doing
+// Configuration settings are in the settings.h file
+//------------------------------------------------------------------------------
+
 //------------------------------------------------------------------------------
 // GENERAL
 //------------------------------------------------------------------------------
 
-#define SERIAL_BAUDRATE         115200
-#define HOSTNAME                DEVICE
-#define BUFFER_SIZE             1024
-#define HEARTBEAT_INTERVAL      300000
-#define UPTIME_OVERFLOW         4294967295
+#define SERIAL_BAUDRATE         115200          // Debugging console boud rate
+#define HOSTNAME                DEVICE          // Hostname
+#define HEARTBEAT_INTERVAL      300000          // Report status every 5 minutes
+#define UPTIME_OVERFLOW         4294967295      // Uptime overflow value
 
 //--------------------------------------------------------------------------------
 // DEBUG
 //--------------------------------------------------------------------------------
 
 #ifndef DEBUG_PORT
-#define DEBUG_PORT              Serial
+#define DEBUG_PORT              Serial          // Default debugging port
 #endif
 
 // Uncomment and configure these lines to enable remote debug via udpDebug
@@ -27,24 +31,24 @@
 // EEPROM
 //--------------------------------------------------------------------------------
 
-#define EEPROM_RELAY_STATUS     0
-#define EEPROM_ENERGY_COUNT     1
-#define EEPROM_CUSTOM_RESET     5
-#define EEPROM_DATA_END         6
+#define EEPROM_RELAY_STATUS     0               // Address for the relay status (1 byte)
+#define EEPROM_ENERGY_COUNT     1               // Address for the energy counter (4 bytes)
+#define EEPROM_CUSTOM_RESET     5               // Address for the reset reason (1 byte)
+#define EEPROM_DATA_END         6               // End of custom EEPROM data block
 
 //--------------------------------------------------------------------------------
 // RESET
 //--------------------------------------------------------------------------------
 
-#define CUSTOM_RESET_HARDWARE   1
-#define CUSTOM_RESET_WEB        2
-#define CUSTOM_RESET_TERMINAL   3
-#define CUSTOM_RESET_MQTT       4
-#define CUSTOM_RESET_RPC        5
-#define CUSTOM_RESET_OTA        6
-#define CUSTOM_RESET_NOFUSS     8
-#define CUSTOM_RESET_UPGRADE    9
-#define CUSTOM_RESET_FACTORY    10
+#define CUSTOM_RESET_HARDWARE   1               // Reset from hardware button
+#define CUSTOM_RESET_WEB        2               // Reset from web interface
+#define CUSTOM_RESET_TERMINAL   3               // Reset from terminal
+#define CUSTOM_RESET_MQTT       4               // Reset via MQTT
+#define CUSTOM_RESET_RPC        5               // Reset via RPC (HTTP)
+#define CUSTOM_RESET_OTA        6               // Reset after successful OTA update
+#define CUSTOM_RESET_NOFUSS     8               // Reset after successful NOFUSS update
+#define CUSTOM_RESET_UPGRADE    9               // Reset after update from web interface
+#define CUSTOM_RESET_FACTORY    10              // Factory reset from terminal
 
 #define CUSTOM_RESET_MAX        10
 
@@ -69,10 +73,10 @@ PROGMEM const char* const custom_reset_string[] = {
 // BUTTON
 //--------------------------------------------------------------------------------
 
-#define BUTTON_DEBOUNCE_DELAY       50
-#define BUTTON_DBLCLICK_DELAY       500
-#define BUTTON_LNGCLICK_DELAY       1000
-#define BUTTON_LNGLNGCLICK_DELAY    10000
+#define BUTTON_DEBOUNCE_DELAY       50          // Debounce delay (ms)
+#define BUTTON_DBLCLICK_DELAY       500         // Time in ms to wait for a second (or third...) click
+#define BUTTON_LNGCLICK_DELAY       1000        // Time in ms holding the button down to get a long click
+#define BUTTON_LNGLNGCLICK_DELAY    10000       // Time in ms holding the button down to get a long-long click
 
 #define BUTTON_EVENT_NONE           0
 #define BUTTON_EVENT_PRESSED        1
@@ -88,8 +92,6 @@ PROGMEM const char* const custom_reset_string[] = {
 #define BUTTON_MODE_PULSE           4
 #define BUTTON_MODE_FACTORY         5
 
-#define BUTTON_DEFAULT_MODE         BUTTON_MODE_TOGGLE
-
 //--------------------------------------------------------------------------------
 // RELAY
 //--------------------------------------------------------------------------------
@@ -136,7 +138,7 @@ PROGMEM const char* const custom_reset_string[] = {
 
 #define TMP_CELSIUS             0
 #define TMP_FAHRENHEIT          1
-#define TMP_UNITS               TMP_CELSIUS
+#define TMP_UNITS               TMP_CELSIUS // Temperature units (TMP_CELSIUS | TMP_FAHRENHEIT)
 
 //--------------------------------------------------------------------------------
 // LED
@@ -151,17 +153,17 @@ PROGMEM const char* const custom_reset_string[] = {
 // WIFI & WEB
 // -----------------------------------------------------------------------------
 
-#define WIFI_RECONNECT_INTERVAL 120000
-#define WIFI_CONNECT_TIMEOUT    30000
-#define WIFI_MAX_NETWORKS       5
-#define ADMIN_PASS              "fibonacci"
-#define FORCE_CHANGE_PASS       1
-#define HTTP_USERNAME           "admin"
-#define WS_BUFFER_SIZE          5
-#define WS_TIMEOUT              1800000
-#define WEBSERVER_PORT          80
-#define DNS_PORT                53
-#define ENABLE_MDNS             1
+#define WIFI_CONNECT_TIMEOUT    30000       // Connecting timeout for WIFI in ms
+#define WIFI_RECONNECT_INTERVAL 120000      // If could not connect to WIFI, retry after this time in ms
+#define WIFI_MAX_NETWORKS       5           // Max number of WIFI connection configurations
+#define HTTP_USERNAME           "admin"     // HTTP username
+#define ADMIN_PASS              "fibonacci" // Default password
+#define FORCE_CHANGE_PASS       1           // Force the user to change the password if default one
+#define WS_BUFFER_SIZE          5           // Max number of secured websocket connections
+#define WS_TIMEOUT              1800000     // Timeout for secured websocket
+#define WEBSERVER_PORT          80          // HTTP port
+#define DNS_PORT                53          // MDNS port
+#define ENABLE_MDNS             1           // Enabled MDNS
 
 #define WEB_MODE_NORMAL         0
 #define WEB_MODE_PASSWORD       1
@@ -169,9 +171,6 @@ PROGMEM const char* const custom_reset_string[] = {
 #define AP_MODE                 AP_MODE_ALONE
 
 // This option builds the firmware with the web interface embedded.
-// You first have to build the data.h file that holds the contents
-// of the web interface by running "gulp buildfs_embed"
-
 #ifndef EMBEDDED_WEB
 #define EMBEDDED_WEB            1
 #endif
@@ -180,32 +179,34 @@ PROGMEM const char* const custom_reset_string[] = {
 // OTA & NOFUSS
 // -----------------------------------------------------------------------------
 
-#define OTA_PORT                8266
-#define NOFUSS_SERVER           ""
-#define NOFUSS_INTERVAL         3600000
+#define OTA_PORT                8266        // OTA port
+#define NOFUSS_SERVER           ""          // Default NoFuss Server
+#define NOFUSS_INTERVAL         3600000     // Check for updates every hour
 
 // -----------------------------------------------------------------------------
 // MQTT
 // -----------------------------------------------------------------------------
 
 #ifndef MQTT_USE_ASYNC
-#define MQTT_USE_ASYNC          1
+#define MQTT_USE_ASYNC          1           // Use AysncMQTTClient (1) or PubSubClient (0)
 #endif
 
-#define MQTT_SERVER             ""
-#define MQTT_PORT               1883
-#define MQTT_TOPIC              "/test/switch/{identifier}"
-#define MQTT_RETAIN             true
-#define MQTT_QOS                0
-#define MQTT_KEEPALIVE          30
-#define MQTT_RECONNECT_DELAY    10000
-#define MQTT_TRY_INTERVAL       30000
-#define MQTT_MAX_TRIES          12
-#define MQTT_SKIP_RETAINED      1
-#define MQTT_SKIP_TIME          1000
-
-#define MQTT_USE_JSON           0
-
+#define MQTT_SERVER             ""          // Default MQTT broker address
+#define MQTT_PORT               1883        // MQTT broker port
+#define MQTT_TOPIC              "/test/switch/{identifier}"     // Default MQTT base topic
+#define MQTT_RETAIN             true        // MQTT retain flag
+#define MQTT_QOS                0           // MQTT QoS value for all messages
+#define MQTT_KEEPALIVE          30          // MQTT keepalive value
+#define MQTT_RECONNECT_DELAY    10000       // Try to reconnect after 10s
+#define MQTT_TRY_INTERVAL       30000       // Timeframe for disconnect retries
+#define MQTT_MAX_TRIES          12          // After these many retries during the previous MQTT_TRY_INTERVAL the board will reset
+#define MQTT_SKIP_RETAINED      1           // Skip retained messages on connection
+#define MQTT_SKIP_TIME          1000        // Skip messages for 1 second anter connection
+
+#define MQTT_USE_JSON           0           // Group messages in a JSON body
+#define MQTT_USE_JSON_DELAY     100         // Wait this many ms before grouping messages
+
+// These particles will be concatenated to the MQTT_TOPIC base to form the actual topic
 #define MQTT_TOPIC_JSON         "data"
 #define MQTT_TOPIC_ACTION       "action"
 #define MQTT_TOPIC_RELAY        "relay"
@@ -226,7 +227,7 @@ PROGMEM const char* const custom_reset_string[] = {
 #define MQTT_TOPIC_TIME         "time"
 #define MQTT_TOPIC_ANALOG       "analog"
 
-// Periodic reports
+// These massages will be reported on heartbeat
 #define MQTT_REPORT_STATUS      1
 #define MQTT_REPORT_IP          1
 #define MQTT_REPORT_MAC         1
@@ -241,16 +242,17 @@ PROGMEM const char* const custom_reset_string[] = {
 #define MQTT_REPORT_VERSION     1
 #define MQTT_REPORT_INTERVAL    0
 
-#define MQTT_STATUS_ONLINE      "1"
-#define MQTT_STATUS_OFFLINE     "0"
+#define MQTT_STATUS_ONLINE      "1"         // Value for the device ON message
+#define MQTT_STATUS_OFFLINE     "0"         // Value for the device OFF message (will)
 
-#define MQTT_ACTION_RESET       "reset"
+#define MQTT_ACTION_RESET       "reset"     // RESET MQTT topic particle
 
+// Internal MQTT events (do not change)
 #define MQTT_CONNECT_EVENT      0
 #define MQTT_DISCONNECT_EVENT   1
 #define MQTT_MESSAGE_EVENT      2
 
-// Custom get and set postfixes6+
+// Custom get and set postfixes
 // Use something like "/status" or "/set", with leading slash
 #define MQTT_USE_GETTER         ""
 #define MQTT_USE_SETTER         ""
@@ -259,11 +261,11 @@ PROGMEM const char* const custom_reset_string[] = {
 // I2C
 // -----------------------------------------------------------------------------
 
-#define ENABLE_I2C              0
-#define I2C_SDA_PIN             4
-#define I2C_SCL_PIN             14
-#define I2C_CLOCK_STRETCH_TIME  200
-#define I2C_SCL_FREQUENCY       1000
+#define ENABLE_I2C              0           // I2C enabled
+#define I2C_SDA_PIN             4           // SDA GPIO
+#define I2C_SCL_PIN             14          // SCL GPIO
+#define I2C_CLOCK_STRETCH_TIME  200         // BRZO clock stretch time
+#define I2C_SCL_FREQUENCY       1000        // BRZO SCL frequency
 
 // -----------------------------------------------------------------------------
 // LIGHT
@@ -282,6 +284,7 @@ PROGMEM const char* const custom_reset_string[] = {
 #define LIGHT_SAVE_DELAY        5
 #define LIGHT_MAX_VALUE         255
 
+// Settings for MY9291 bulbs (AI Light)
 #define MY9291_DI_PIN           13
 #define MY9291_DCKI_PIN         15
 #define MY9291_COMMAND          MY9291_COMMAND_DEFAULT
@@ -298,28 +301,28 @@ PROGMEM const char* const custom_reset_string[] = {
 // -----------------------------------------------------------------------------
 
 #ifndef ENABLE_DOMOTICZ
-    #define ENABLE_DOMOTICZ     1
+#define ENABLE_DOMOTICZ         1               // Enable Domoticz support by default
 #endif
-#define DOMOTICZ_IN_TOPIC       "domoticz/in"
-#define DOMOTICZ_OUT_TOPIC      "domoticz/out"
+#define DOMOTICZ_IN_TOPIC       "domoticz/in"   // Default subscription topic
+#define DOMOTICZ_OUT_TOPIC      "domoticz/out"  // Default publication topic
 
 // -----------------------------------------------------------------------------
 // INFLUXDB
 // -----------------------------------------------------------------------------
 
 #ifndef ENABLE_INFLUXDB
-    #define ENABLE_INFLUXDB     1
+#define ENABLE_INFLUXDB         1               // Enable InfluxDB support by default
 #endif
-#define INFLUXDB_PORT           8086
+#define INFLUXDB_PORT           8086            // Default InfluxDB port
 
 // -----------------------------------------------------------------------------
 // NTP
 // -----------------------------------------------------------------------------
 
-#define NTP_SERVER              "pool.ntp.org"
-#define NTP_TIME_OFFSET         1
-#define NTP_DAY_LIGHT           true
-#define NTP_UPDATE_INTERVAL     1800
+#define NTP_SERVER              "pool.ntp.org"  // Default NTP server
+#define NTP_TIME_OFFSET         1               // Default timezone offset (GMT+1)
+#define NTP_DAY_LIGHT           true            // Enable daylight time saving by default
+#define NTP_UPDATE_INTERVAL     1800            // NTP check every 30 minutes
 
 // -----------------------------------------------------------------------------
 // FAUXMO
@@ -327,7 +330,7 @@ PROGMEM const char* const custom_reset_string[] = {
 
 // This setting defines whether Alexa support should be built into the firmware
 #ifndef ENABLE_FAUXMO
-    #define ENABLE_FAUXMO       1
+#define ENABLE_FAUXMO       1
 #endif
 
 // This is default value for the fauxmoEnabled setting that defines whether

code/espurna/mqtt.ino

@@ -125,7 +125,7 @@ void mqttSend(const char * topic, const char * message, bool force) {
         element.topic = strdup(topic);
         element.message = strdup(message);
         _mqtt_queue.push_back(element);
-        mqttFlushTicker.once_ms(100, _mqttFlush);
+        mqttFlushTicker.once_ms(MQTT_USE_JSON_DELAY, _mqttFlush);
     } else {
         String mqttGetter = getSetting("mqttGetter", MQTT_USE_GETTER);
         String path = mqttTopic + String(topic) + mqttGetter;