From f45a23927fd8fcaf0ecf435beb2fde1a77224641 Mon Sep 17 00:00:00 2001
From: Rene Bartsch <rene@bartschnet.de>
Date: Thu, 12 Jul 2018 14:05:02 +0200
Subject: [PATCH] Initial version.

---
 Sensor-API.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 Sensor-API.md

diff --git a/Sensor-API.md b/Sensor-API.md
new file mode 100644
index 00000000..e5e56030
--- /dev/null
+++ b/Sensor-API.md
@@ -0,0 +1,61 @@
+# Sensor API
+
+This wiki page is an attempt to document the sensor API for sensor driver development.
+
+## File structure
+Sensor libraries are located in the `lib/` directory. Sensor drivers are located in the `sonoff/` directory. The filename of the sensor driver is `xsns_<driver_ID>_<driver_name>.ino`, e.g. `xsns_05_ds18b20.ino` where `<driver_ID>` is a _unique_ number between 01 and 90 and `<driver_name>` is a human-readable name of the driver.
+
+## API structure
+### Pre-processor directives
+Conditional compiling of a sensor driver is achieved by commenting/uncommenting a pre-processor directive of the scheme `USE_<driver_name>` in `user_config.h`. Accordingly the driver code has to be wrapped in `#ifdef USE_<driver_name> ... #endif  // USE_<driver_name>`. Any Sensor driver must contain a pre-processor directive defining the driver ID by the scheme `#define XSNS_<driver_ID>`.
+
+### Callback function
+Any sensor driver needs a callback function following the scheme
+```
+/**
+ * The function Xsns<driver_ID>() interfaces Tasmota with the driver.
+ *
+ * It provides the function IDs
+ * FUNC_INIT to initialize a driver,
+ * FUNC_EVERY_50_MSECOND for near real-time operation,
+ * FUNC_JSON_APPEND for telemetry data and
+ * FUNC_WEB_APPEND for displaying data in the Tasmota web-interface
+ * `
+ * @param   byte    function  Tasmota function ID.
+ * @return  boolean           ???
+ * @pre     None.
+ * @post    None.
+ *
+ */
+boolean Xsns<driverID>(byte function)
+{
+  // ???
+  boolean result = false;
+
+  // Check which function is called by Tasmota
+  switch (function) {
+    case <function>:
+       <code>
+    break;
+  }
+
+  // Return boolean result
+  return result;
+}
+```
+
+
+### Function IDs
+
+#### FUNC_INIT
+FUNC_INIT initializes a sensor driver
+
+#### FUNC_EVERY_50_MSECOND
+FUNC_EVERY_50_MSECOND 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.
+
+#### 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