From 06b2e925c057d2476f17e163e639d735afab9ba3 Mon Sep 17 00:00:00 2001
From: Rene Bartsch <rene@bartschnet.de>
Date: Thu, 12 Jul 2018 15:07:05 +0200
Subject: [PATCH] Verbal clarifications and functions added.

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

diff --git a/Sensor-API.md b/Sensor-API.md
index e5e56030..87cf6325 100644
--- a/Sensor-API.md
+++ b/Sensor-API.md
@@ -27,14 +27,14 @@ Any sensor driver needs a callback function following the scheme
  * @post    None.
  *
  */
-boolean Xsns<driverID>(byte function)
+boolean Xsns<driverID>(byte callback_id)
 {
   // ???
   boolean result = false;
 
   // Check which function is called by Tasmota
-  switch (function) {
-    case <function>:
+  switch (callback_id) {
+    case <callback_id>:
        <code>
     break;
   }
@@ -45,17 +45,45 @@ boolean Xsns<driverID>(byte function)
 ```
 
 
-### Function IDs
+### Callback IDs
 
 #### FUNC_INIT
-FUNC_INIT initializes a sensor driver
+This callback ID is called when sensor drivers should be initialized.
 
 #### FUNC_EVERY_50_MSECOND
-FUNC_EVERY_50_MSECOND is called every 50 milliseconds, e.g. for near real-time operation
+This callback ID is called every 50 milliseconds, e.g. for near real-time operation
 
 #### FUNC_JSON_APPEND
-FUNC_JSON_APPEND is called to append telemetry data to the MQTT JSON string when `TELEPERIOD` is due.
+This callback ID is called when `TELEPERIOD` is due to append telemetry data to the MQTT JSON string, 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
-FUNC_WEB_APPEND is called to add HTML code to the Tasmota web-interface main page.
-It should be wrapped in `#ifdef USE_WEBSERVER ... #endif  // USE_WEBSERVER`
\ No newline at end of file
+This callback ID is called 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`
+
+### Useful functions
+#### `int snprintf_P(char * __s,	size_t __n, const char * format_string, char* text)`
+This function formats text like `printf()`.
+
+#### `void MqttPublishPrefixTopic_P(uint8_t prefix, const char* subtopic, boolean retained)`
+This function publishes MQTT messages immediately, e.g.
+```
+snprintf_P(mqtt_data, sizeof(mqtt_data), PSTR("{\"MPR121%c\":{\"Button%i\":%i}}"), pS->id[i], j, BITC(i,j));
+MqttPublishPrefixTopic_P(RESULT_OR_STAT, mqtt_data);
+```
+#### void AddLog(byte loglevel)
+```
+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)
+```
+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)
\ No newline at end of file