From bafbbc3145f03621d01a42cabe870319049d5e63 Mon Sep 17 00:00:00 2001
From: Theo Arends <mhtarends@gmail.com>
Date: Tue, 17 Jul 2018 11:38:03 +0200
Subject: [PATCH] Remove Driver only callback IDs and clarify some sensor
 callback IDs

---
 Sensor-API.md | 46 ++++++++++------------------------------------
 1 file changed, 10 insertions(+), 36 deletions(-)

diff --git a/Sensor-API.md b/Sensor-API.md
index e8e604ff..68b6072a 100644
--- a/Sensor-API.md
+++ b/Sensor-API.md
@@ -98,15 +98,9 @@ boolean Xsns<driverID>(byte callback_id) {
 
 ## Callback IDs
 
-### FUNC_PRE_INIT
-???
-
 ### FUNC_INIT
 This callback ID is called when sensor drivers should be initialized.
 
-### FUNC_LOOP
-???
-
 ### FUNC_EVERY_50_MSECOND
 This callback ID is called every 50 milliseconds, e.g. for near real-time operation
 
@@ -114,7 +108,9 @@ This callback ID is called every 50 milliseconds, e.g. for near real-time operat
 This callback ID is called every second.
 
 ### FUNC_PREP_BEFORE_TELEPERIOD
-This callback ID is called before TELEPERIOD and is intended to make provision for your sensor to be ready for polling during FUNC_JSON_APPEND or FUNC_WEB_APPEND for example, amongst the other function call options used by your sensor in the boolean Xsns<driverID>(byte callback_id) function as referenced above.
+NOTE: This callback ID is deprecated as sensors should prepare for more regular updates due to "realtime" rule execution. Use FUNC_EVERY_SECOND instead. See examples used in xsns_05_ds18x20.ino and xsns_09_bmp.ino where updated sensor data is stored in preparation to calls to FUNC_JSON_APPEND and FUNC_WEB_APPEND.
+
+This callback ID is called before TELEPERIOD and is intended to make provision for your sensor to be ready for polling during FUNC_JSON_APPEND or FUNC_WEB_APPEND for example, amongst the other function call options used by your sensor in the boolean Xsns<driverID>(byte callback_id) function as referenced above. 
 
 You would normally want to make sure you've detected and initialised before it is used by JSON_APPEND etc so that its ready to serve data.
 
@@ -138,44 +134,23 @@ void MySensorDetect()
 ```
 
 ### FUNC_JSON_APPEND
-This callback ID is called when `TELEPERIOD` is due to append telemetry data to the MQTT JSON string, e.g.
+This callback ID is called when `TELEPERIOD` is due to append telemetry data to the MQTT JSON string or at approximately every 2 seconds when a rule is checked, e.g.
 ```
 snprintf_P(mqtt_data, sizeof(mqtt_data), PSTR("{\"MPR121%c\":{\"Button%i\":%i}}"), pS->id[i], j, BITC(i,j));
 ```
 
 ### FUNC_WEB_APPEND
-This callback ID is called when HTML code should be added to the Tasmota web-interface main page, e.g.
+This callback ID is called every 2.5 second when HTML code should be added to the Tasmota web-interface main page, e.g.
 ```
 snprintf_P(mqtt_data, sizeof(mqtt_data), PSTR("%s{s}MPR121%c Button%d{m}%d{e}"), mqtt_data, pS->id[i], j, BITC(i,j));
 ```
 It should be wrapped in `#ifdef USE_WEBSERVER ... #endif  // USE_WEBSERVER`
 
 ### FUNC_SAVE_BEFORE_RESTART
-???
+This callback ID is called to allow a sensor to prepare for saving configuration changes. To be used to save volatile data just before a restart.
 
 ### FUNC_COMMAND
-???
-
-### FUNC_MQTT_SUBSCRIBE
-???
-
-### FUNC_MQTT_INIT
-???
-
-### FUNC_MQTT_DATA
-???
-
-### FUNC_SET_POWER
-???
-
-### FUNC_SHOW_SENSOR
-???
-
-### FUNC_RULES_PROCESS
-???
-
-### FUNC_FREE_MEM
-???
+This callback ID is called when a sensor specific command ``Sensor\<xx\>`` is executed where xx is the sensor index.
 
 ## Useful functions
 
@@ -190,19 +165,18 @@ MqttPublishPrefixTopic_P(RESULT_OR_STAT, mqtt_data);
 ### Logging
 ___
 #### void AddLog(byte loglevel)
-This function adds log messages to the local logging system, e.g.
+This function adds log messages stored in ``log_data`` to the local logging system, e.g.
 ```
 snprintf_P(log_data, sizeof(log_data), PSTR(D_LOG_I2C "MPR121(%c) " D_FOUND_AT " 0x%X"), pS->id[i], pS->i2c_addr[i]);
 AddLog(LOG_LEVEL_INFO);
 ```
 #### void AddLogSerial(byte loglevel)
-This function adds log messages to the serial UART, e.g.
+This function adds a log message to the local logging system dumping the serial buffer as hex information, e.g.
 ```
-snprintf_P(log_data, sizeof(log_data), PSTR(D_LOG_I2C "MPR121(%c) " D_FOUND_AT " 0x%X"), pS->id[i], pS->i2c_addr[i]);
 AddLogSerial(LOG_LEVEL_INFO);
 ```
 #### void AddLogMissed(char *sensor, uint8_t misses)
-???
+This function adds a log message to the local logging system about missed sensor reads.
 
 ### I2C interface
 ___