diff --git a/Sensor-API.md b/Sensor-API.md index 8dd86a92..8b0f1a27 100644 --- a/Sensor-API.md +++ b/Sensor-API.md @@ -1,15 +1,13 @@ -# Sensor API +This wiki page is an attempt to document the Tasmota sensor API for sensor driver development. -This wiki page is an attempt to document the sensor API for sensor driver development. - -## File structure +# 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__.ino`, e.g. `xsns_05_ds18b20.ino` where `` is a _unique_ number between 01 and 90 and `` is a human-readable name of the driver. -## API structure -### Pre-processor directives +# API structure +## Pre-processor directives Conditional compiling of a sensor driver is achieved by commenting/uncommenting a pre-processor directive of the scheme `USE_` in `user_config.h`. Accordingly the driver code has to be wrapped in `#ifdef USE_ ... #endif // USE_`. Any Sensor driver must contain a pre-processor directive defining the driver ID by the scheme `#define XSNS_`. -### Callback function +## Callback function Any sensor driver needs a callback function following the scheme ``` /** @@ -45,85 +43,87 @@ boolean Xsns(byte callback_id) ``` -### Callback IDs +## Callback IDs -#### FUNC_PRE_INIT +### FUNC_PRE_INIT ??? -#### FUNC_INIT + +### FUNC_INIT This callback ID is called when sensor drivers should be initialized. -#### FUNC_LOOP +### FUNC_LOOP ??? -#### FUNC_EVERY_50_MSECOND + +### FUNC_EVERY_50_MSECOND This callback ID is called every 50 milliseconds, e.g. for near real-time operation -#### FUNC_EVERY_SECOND +### FUNC_EVERY_SECOND This callback ID is called every second. -#### FUNC_PREP_BEFORE_TELEPERIOD +### FUNC_PREP_BEFORE_TELEPERIOD ??? -#### FUNC_JSON_APPEND +### FUNC_JSON_APPEND 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 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` -#### FUNC_SAVE_BEFORE_RESTART +### FUNC_SAVE_BEFORE_RESTART ??? -#### FUNC_COMMAND +### FUNC_COMMAND ??? -#### FUNC_MQTT_SUBSCRIBE +### FUNC_MQTT_SUBSCRIBE ??? -#### FUNC_MQTT_INIT +### FUNC_MQTT_INIT ??? -#### FUNC_MQTT_DATA +### FUNC_MQTT_DATA ??? -#### FUNC_SET_POWER +### FUNC_SET_POWER ??? -#### FUNC_SHOW_SENSOR +### FUNC_SHOW_SENSOR ??? -#### FUNC_RULES_PROCESS +### FUNC_RULES_PROCESS ??? -#### FUNC_FREE_MEM +### FUNC_FREE_MEM ??? -### Useful functions +## Useful functions -#### void MqttPublishPrefixTopic_P(uint8_t prefix, const char* subtopic, boolean retained) +### 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) +### 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) +### 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) +### void AddLogMissed(char *sensor, uint8_t misses) ??? -### Useful pre-processor directives -### `PSTR("string")` +## Useful pre-processor directives +### PSTR("string") This pre-processor directive save RAM by storing strings in flash instead of RAM \ No newline at end of file