Skip to content

Commit 2c426d8

Browse files
TD-erTD-er
authored
Merge pull request #4899 from tonhuisman/feature/Docs-corrections-and-improvements-dec-2023
[Docs] Updates, corrections and improvements, Dec. 2023
2 parents a34ad10 + 240737a commit 2c426d8

8 files changed

+192
-33
lines changed

‎README.md

+18-11
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Introduction https://espeasy.readthedocs.io/en/latest/ (and, mostly outdated, wi
1313
This is the development branch of ESPEasy. All new features go into this branch, and it has become the current stable branch. If you want to do a bugfix, do it on this branch.
1414

1515

16-
Check here to learn how to use this branch and help us improving ESPEasy: http://www.letscontrolit.com/wiki/index.php/ESPEasy#Source_code_development
16+
Check here to learn how to use this branch and help us improving ESPEasy: [Starter guide for (local) development on ESPEasy](https://espeasy.readthedocs.io/en/latest/Participate/PlatformIO.html#starter-guide-for-local-development-on-espeasy)
1717

1818
## Web based flasher (experimental)
1919

@@ -58,6 +58,7 @@ hard | hardware specific builds | Minimal
5858
minimal | minimal plugins for specific use-cases | Switch and Controller |
5959
spec_* | specialized technical builds | Not intended for regular use |
6060
IRext | Infra-red hardware specific | Sending and receiving IR cmd |
61+
safeboot | (Experimental) `safeboot` build to enable<br>most/all plugins on 4MB Flash boards | None |
6162

6263

6364
*[opt-arduino-library]* (optional) can be any of:
@@ -81,6 +82,8 @@ ESP32solo1 | Espressif ESP32-Solo1 generic boards |
8182
ESP32s2 | Espressif ESP32-S2 generic boards |
8283
ESP32c3 | Espressif ESP32-C3 generic boards |
8384
ESP32s3 | Espressif ESP32-S3 generic boards |
85+
ESP32c2 | Espressif ESP32-C2 generic boards |
86+
ESP32c6 | Espressif ESP32-C6 generic boards |
8487
ESP32-wrover-kit | Espressif ESP32 wrover-kit boards |
8588
SONOFF | Sonoff hardware specific |
8689
other_POW | Switch with power measurement |
@@ -98,6 +101,7 @@ Flash size | Description |
98101
1M | 1 MB with 128 kB filesystem |
99102
2M | 2 MB with 128 kB filesystem |
100103
2M256 | 2 MB with 256 kB filesystem |
104+
2M320k | 2 MB with 320 kB filesystem |
101105
4M1M | 4 MB with 1 MB filesystem |
102106
4M2M | 4 MB with 2 MB filesystem |
103107
16M | 16 MB with 14 MB filesystem |
@@ -106,18 +110,21 @@ Flash size | Description |
106110
16M1M | 16 MB with 1 MB filesystem |
107111
16M8M | 16 MB with 8 MB filesystem |
108112

113+
N.B. Starting with release 2023/12/25, All ESP32 LittleFS builds use IDF 5.1, to support newer ESP32 chips like ESP32-C2 and ESP32-C6. Other SPIFFS based ESP32 builds will be migrated to LittleFS as SPIFFS is no longer available in IDF 5 and later. A migration plan will be made available in 2024.
109114

110115
*[opt-build-features]* can be any of:
111-
Build features | Description |
112-
----------------|----------------------------------------------------------------------------|
113-
LittleFS | Use LittleFS instead of SPIFFS filesystem (SPIFFS is unstable \> 2 MB) |
114-
VCC | Analog input configured to measure VCC voltage (ESP8266 only) |
115-
OTA | Arduino OTA (Over The Air) update feature enabled |
116-
Domoticz | Only Domoticz controllers (HTTP+MQTT) and plugins included |
117-
FHEM_HA | Only FHEM/OpenHAB/Home Assistant (MQTT) controllers and plugins included |
118-
ETH | Ethernet interface enabled (ESP32 only) |
119-
OPI_PSRAM | Specific configuration to enable PSRAM detection, ESP32-S3 only |
120-
CDC | Support USBCDC/HWCDC-serial console on ESP32-C3, ESP32-S2 and ESP32-S3 |
116+
Build features | Description |
117+
----------------|-----------------------------------------------------------------------------------------------------------|
118+
LittleFS | Use LittleFS instead of SPIFFS filesystem (SPIFFS is unstable \> 2 MB, and no longer supported in IDF \> 5) |
119+
VCC | Analog input configured to measure VCC voltage (ESP8266 only) |
120+
OTA | Arduino OTA (Over The Air) update feature enabled |
121+
Domoticz | Only Domoticz controllers (HTTP) and plugins included |
122+
Domoticz_MQTT | Only Domoticz controllers (MQTT) and plugins included |
123+
FHEM_HA | Only FHEM/OpenHAB/Home Assistant (MQTT) controllers and plugins included |
124+
ETH | Ethernet interface enabled (ESP32-classic only) |
125+
OPI_PSRAM | Specific configuration to enable PSRAM detection, ESP32-S3 only |
126+
CDC | Support USBCDC/HWCDC-serial console on ESP32-C3, ESP32-S2, ESP32-S3 and ESP32-C6 |
127+
noOTA/NO_OTA | Does not support OTA (Over The Air-updating of the firmware) Use [the flash page](https://td-er.nl/ESPEasy/) or ESPTool via USB Serial |
121128

122129
Some example firmware names:
123130
Firmware name | Hardware | Included plugins |

‎docs/source/Hardware/Hardware.rst

+3
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,9 @@ ESPEasy has a separate setting for Slow I2C devices, and per I2C device this slo
5555

5656
.. image:: Device_I2COptionsShort.png
5757

58+
Added: 2023-11-23
59+
60+
A device flag has been added for specific devices to have **Force Slow I2C speed** set by default. After adding the device this option will be checked, but can still be unchecked to use (try) Fast I2C speed (400 kHz).
5861

5962
---------------
6063
I2C Multiplexer

‎docs/source/Reference/Command.rst

+14-3
Original file line numberDiff line numberDiff line change
@@ -597,10 +597,10 @@ P077 :ref:`P077_page`
597597
.. include:: ../Plugin/P077_commands.repl
598598

599599

600-
.. P078 :ref:`P078_page`
601-
.. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
600+
P078 :ref:`P078_page`
601+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
602602

603-
.. .. include:: ../Plugin/P078_commands.repl
603+
.. include:: ../Plugin/P078_commands.repl
604604

605605

606606
P079 :ref:`P079_page`
@@ -637,6 +637,12 @@ P088 :ref:`P088_page`
637637
.. include:: ../Plugin/P088_commands.repl
638638

639639

640+
P089 :ref:`P089_page`
641+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
642+
643+
.. include:: ../Plugin/P089_commands.repl
644+
645+
640646
P091 :ref:`P091_page`
641647
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
642648

@@ -784,6 +790,11 @@ P153 :ref:`P153_page`
784790

785791
.. include:: ../Plugin/P153_commands.repl
786792

793+
P159 :ref:`P159_page`
794+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
795+
796+
.. include:: ../Plugin/P159_commands.repl
797+
787798
.. .. *** Insert regular plugin commands above this remark! ***
788799
789800
.. _AdafruitGFX Helper commands:

‎docs/source/Reference/Events.rst

+4-3
Original file line numberDiff line numberDiff line change
@@ -236,10 +236,10 @@ P036 :ref:`P036_page`
236236
.. include:: ../Plugin/P036_events.repl
237237

238238

239-
.. P037 :ref:`P037_page`
240-
.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
239+
P037 :ref:`P037_page`
240+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
241241

242-
.. .. include:: ../Plugin/P037_events.repl
242+
.. include:: ../Plugin/P037_events.repl
243243

244244

245245
.. P038 :ref:`P038_page`
@@ -544,6 +544,7 @@ P138 :ref:`P138_page`
544544
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
545545

546546
.. include:: ../Plugin/P138_events.repl
547+
547548
P143 :ref:`P143_page`
548549
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
549550

‎docs/source/Reference/SystemVariable.rst

+4
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,10 @@ More uses of these system variables can be seen in the rules section and formula
139139
- 5 (05)
140140
- Current second (ss). ``%syssec%`` omits leading zeros.
141141
- Yes
142+
* - ``%syssec_d%``
143+
- 83682
144+
- Seconds since midnight.
145+
-
142146
* - ``%sysday%`` (``%sysday_0%``)
143147
- 7 (07)
144148
- Current day of month (DD). ``%sysday%`` omits leading zeros.

‎docs/source/Rules/Rules.rst

+110
Original file line numberDiff line numberDiff line change
@@ -2404,3 +2404,113 @@ This rule can be used to calculate the moving average for, f.e., a temperature s
24042404
24052405
This assumes that a Controller has been configured, and the Dummy task is configured to send out its values via the controller.
24062406

2407+
Register daily working time
2408+
---------------------------
2409+
2410+
To register the daily time in seconds that a device is active, these rules have been developed (from the forum).
2411+
2412+
Required device tasks:
2413+
2414+
* Sensor (temperature in the example)
2415+
* Dummy device (named ``Dummy`` in this example, minimal 2 values, ``LoggingON`` and ``LoggingOFF``), Interval can be set to 0
2416+
2417+
.. code-block:: none
2418+
2419+
On System#Boot Do
2420+
TaskValueSet,Dummy,LoggingON,1 // Make sure timer is started and Heater ON message is sent
2421+
Endon
2422+
2423+
On DS1#Temperature Do // Check tmeperature
2424+
If %eventvalue1% < 40
2425+
GPIO,5,0
2426+
AsyncEvent,HeaterON=%eventvalue1%
2427+
Endif
2428+
If %eventvalue1% > 55
2429+
GPIO,5,1
2430+
AsyncEvent,HeaterOFF=%eventvalue1%
2431+
Endif
2432+
Endon
2433+
2434+
On HeaterON Do // Optional 1st argument is the temperature, defaults to the value of DS1#Temperature if not provided
2435+
If [Dummy#LoggingON] = 1
2436+
Let,1,%syssec_d% // Store current nr of seconds of today in var#1
2437+
PostToHTTP,192.168.1.20,8080,/receiver.php,'','%lcltime% !!! Temp = %eventvalue1|[DS1#Temperature]% -> Heater ON'
2438+
TaskValueSet,Dummy,LoggingON,0
2439+
TaskValueSet,Dummy,LoggingOFF,1
2440+
TaskRun,Dummy
2441+
Endif
2442+
Endon
2443+
2444+
On HeaterOFF Do // Optional 1st argument is the temperature, defaults to the value of DS1#Temperature if not provided
2445+
If [Dummy#LoggingOFF] = 1
2446+
Let,2,[int#2]+%syssec_d%-[int#1] // Add run time to var#2
2447+
PostToHTTP,192.168.1.20,8080,/receiver.php,'','%lcltime% !!! Temp = %eventvalue1|[DS1#Temperature]% -> Heater OFF'
2448+
TaskValueSet,Dummy,LoggingON,1
2449+
TaskValueSet,Dummy,LoggingOFF,0
2450+
TaskRun,Dummy
2451+
Endif
2452+
Endon
2453+
2454+
On Clock#Time=All,00:00 Do // At midnight
2455+
// Send value of [int#2] to wherever you need it
2456+
PostToHTTP,192.168.1.20,8080,/receiver.php,'','%lcltime% !!! Total RunningTime = [int#2] Seconds'
2457+
Let,1,0 // Reset start time
2458+
Let,2,0 // Reset total counter
2459+
Endon
2460+
2461+
2462+
Register power used for a heater
2463+
--------------------------------
2464+
2465+
As a variation on the running time, we can also measure the time and calculate the total power used, as long as the used device-power is known. Parts from the above example have been re-used.
2466+
2467+
This example uses a ``Generic - Dummy Device``, so the values can also be viewed on the Devices page. This has name: Power, output data type: Dual (or Triple or Quad, must be able to store decimals!), value names: Seconds (0 decimmals) and PowerUsed (4 decimals).
2468+
2469+
The time is counted while GPIO-14 (D5 on a Wemos or NodeMCU ESP8266) has a low state, and power is calculated once the power goes off. The not-On state will need a pull-up resistor to pull the level to 3V3!
2470+
2471+
After loading this code, either reboot the ESP, or run the command ``event,system#boot`` to set up the GPIO monitoring and wattage of the device.
2472+
2473+
.. code-block:: none
2474+
2475+
// Used variables: 1,3,4,5
2476+
2477+
On GPIO#14 Do // GPIO-14 = D5 on Wemos/NodeMCU ESP8266 boards
2478+
If %eventvalue1%=0 // On state
2479+
Let,1,%syssec_d% // Store current nr of seconds of today in var#1
2480+
Else // Off state
2481+
Event,CalcPower // Don't queue
2482+
Event,TransmitPower // Send out to receiver
2483+
Endif
2484+
Let,5,!%eventvalue1% // 0 = On, to invert on/off state change to: Let,5,%eventvalue1%
2485+
LogEntry,"Power [int#5#O#C], measured: [Power#Seconds] sec. [Power#PowerUsed#d.4] kWh"
2486+
Endon
2487+
2488+
On CalcPower Do
2489+
TaskValueSet,Power,Seconds,[Power#Seconds]+%syssec_d%-[int#1] // Add run time to Power#Seconds
2490+
Let,4,[Power#Seconds]*[var#3] // Wattseconds
2491+
If [var#4]>0
2492+
TaskValueSet,Power,PowerUsed,[var#4]/3600000 // Wattseconds to kWh
2493+
Endif
2494+
TaskRun,Power
2495+
Endon
2496+
2497+
On TransmitPower Do
2498+
// Send value of [Power#Seconds] and [Power#PowerUsed] to wherever you need it, adjust as needed
2499+
PostToHTTP,192.168.1.20,8080,/receiver.php,'','%lcltime% !!! Total RunningTime = [Power#Seconds] Seconds, PowerUsed = [Power#PowerUsed] kWh'
2500+
Endon
2501+
2502+
On Clock#Time=All,00:00 Do // At midnight
2503+
// Include power used until midnight
2504+
If [Plugin#GPIO#PinState#14]=0 // Still on?
2505+
Event,CalcPower // Don't queue
2506+
Endif
2507+
Let,1,0 // Reset start time
2508+
Event,TransmitPower // Send out remainder of the day
2509+
TaskValueSet,Power,Seconds,0 // Reset total counter
2510+
TaskValueSet,Power,PowerUsed,0 // Reset total power
2511+
Endon
2512+
2513+
On System#Boot Do
2514+
Monitor,gpio,14 // Generate an event when the GPIO state changes
2515+
Let,3,250 // Wattage of the load, adjust as needed
2516+
Endon

‎src/_P151_Honeywell_pressure.ino

+9
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,15 @@ boolean Plugin_151(uint8_t function, struct EventStruct *event, String& string)
8484
break;
8585
}
8686

87+
# if FEATURE_I2C_GET_ADDRESS
88+
case PLUGIN_I2C_GET_ADDRESS:
89+
{
90+
event->Par1 = P151_I2C_ADDR;
91+
success = true;
92+
break;
93+
}
94+
# endif // if FEATURE_I2C_GET_ADDRESS
95+
8796
case PLUGIN_SET_DEFAULTS:
8897
{
8998
P151_I2C_ADDR = 0x28;

‎src/_Pxxx_PluginTemplate.ino

+30-16
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,22 @@
11
/* This file is a template for Plugins */
22

3-
/* References:
4-
https://www.letscontrolit.com/wiki/index.php/ESPEasyDevelopment
5-
https://www.letscontrolit.com/wiki/index.php/ESPEasyDevelopmentGuidelines
3+
/*
4+
This guide shows the setup of VSCode and some required and a few optional extensions for development on ESPEasy:
5+
https://espeasy.readthedocs.io/en/latest/Participate/PlatformIO.html
6+
7+
We even have a starter guide for development on ESPEasy with all steps from beginning to end including writing the documentation:
8+
https://espeasy.readthedocs.io/en/latest/Participate/PlatformIO.html#starter-guide-for-local-development-on-espeasy
9+
10+
Other References:
11+
https://www.letscontrolit.com/wiki/index.php/ESPEasyDevelopment (No longer updated)
12+
https://www.letscontrolit.com/wiki/index.php/ESPEasyDevelopmentGuidelines (No longer updated)
613
https://github.com/letscontrolit/ESPEasyPluginPlayground
7-
https://diyprojects.io/esp-easy-develop-plugins/
814
915
A Plugin should have an ID.
1016
The official plugin list is available here: https://www.letscontrolit.com/wiki/index.php/Official_plugin_list
1117
The plugin playground is available here: https://github.com/letscontrolit/ESPEasyPluginPlayground
1218
13-
Use the next available ID. The maximum number of Plugins is defined in ESPEasy-Globals.h (PLUGIN_MAX)
19+
Request a new PluginID via this Github issue: https://github.com/letscontrolit/ESPEasy/issues/3839
1420
1521
The Plugin filename should be of the form "_Pxxx_name.ino", where:
1622
xxx is the ID
@@ -28,12 +34,12 @@
2834
- set plugin status to DEVELOPMENT and distribute to other users for testing
2935
- after sufficient usage and possible code correction, set plugin status to TESTING and perform testing with more users
3036
- finally, plugin will be accepted in project, then the TESTING tag can be removed.
31-
- along with the plugin source code, prepare a wiki page containing:
37+
- along with the plugin source code, prepare the Read The Docs documentation (included in the repository) containing:
3238
- instructions on how to make the necessary configuration
3339
- instructions on commands (if any)
3440
- examples: plugin usage, command usage,...
3541
- when a plugin is removed (deleted), make sure you free any memory it uses. Use PLUGIN_EXIT for that
36-
- if your plugin creates log entries, prefix your entries with your plugin id: "[Pxxx] my plugin did this"
42+
- if your plugin creates log entries, prefix your entries with your plugin id: "Pxxx : my plugin did this"
3743
- if your plugin takes input from user and/or accepts/sends http commands, make sure you properly handle non-alphanumeric characters
3844
correctly
3945
- After ESP boots, all devices can send data instantly. If your plugin is for a sensor which sends data, ensure it doesn't need a delay
@@ -186,7 +192,7 @@ boolean Plugin_xxx(uint8_t function, struct EventStruct *event, String& string)
186192
// The position in the config parameters used in this example is PCONFIG(Pxxx_OUTPUT_TYPE_INDEX)
187193
// Must match the one used in case PLUGIN_GET_DEVICEVALUECOUNT (best to use a define for it)
188194
// IDX is used here to mark the PCONFIG position used to store the Device VType.
189-
// see P026_Sysinfo.ino for more examples.
195+
// see _P026_Sysinfo.ino for more examples.
190196
event->idx = Pxxx_OUTPUT_TYPE_INDEX;
191197
event->sensorType = static_cast<Sensor_VType>(PCONFIG(event->idx));
192198
success = true;
@@ -219,7 +225,9 @@ boolean Plugin_xxx(uint8_t function, struct EventStruct *event, String& string)
219225
// # if FEATURE_I2C_GET_ADDRESS
220226
// case PLUGIN_I2C_GET_ADDRESS:
221227
// {
222-
// event->Par1 = 0x77; // or: = PCONFIG(0);
228+
// // Called to show the configured I2C address on the Devices page
229+
//
230+
// event->Par1 = 0x77; // or: = Pxxx_I2C_ADDR
223231
// success = true;
224232
// break;
225233
// }
@@ -254,11 +262,15 @@ boolean Plugin_xxx(uint8_t function, struct EventStruct *event, String& string)
254262
255263
// For strings, always use the F() macro, which stores the string in flash, not in memory.
256264
257-
// String dropdown[5] = { F("option1"), F("option2"), F("option3"), F("option4")};
258-
// addFormSelector(string, F("drop-down menu"), F("plugin_xxx_displtype"), 4, dropdown, nullptr, PCONFIG(0));
265+
// const __FlashStringHelper dropdownList[] = { F("option1"), F("option2"), F("option3"), F("option4")};
266+
// const int dropdownOptions[] = { 1, 2, 3, 4 };
267+
// constexpr int dropdownCount = NR_ELEMENTS(dropdownOptions);
268+
// addFormSelector(string, F("drop-down menu"), F("dsptype"), dropdownCount, dropdownList, dropdownOptions, PCONFIG(0));
269+
270+
// number selection (min_value - max_value)
271+
addFormNumericBox(string, F("description"), F("desc"), PCONFIG(1), min_value, max_value);
259272
260-
// number selection (min-value - max-value)
261-
addFormNumericBox(string, F("description"), F("plugin_xxx_description"), PCONFIG(1), min - value, max - value);
273+
// If custom tasksettings need to be loaded and displayed, this is the place to add that
262274
263275
// after the form has been loaded, set success and break
264276
success = true;
@@ -269,7 +281,9 @@ boolean Plugin_xxx(uint8_t function, struct EventStruct *event, String& string)
269281
{
270282
// this case defines the code to be executed when the form is submitted
271283
// the plugin settings should be saved to PCONFIG(x)
272-
// ping configuration should be read from CONFIG_PIN1 and stored
284+
// PCONFIG(0) = getFormItemInt(F("dsptype"));
285+
// pin configuration will be read from CONFIG_PIN1 and stored
286+
// If custom tasksettings need to be stored, then here is the place to add that
273287
274288
// after the form has been saved successfuly, set success and break
275289
success = true;
@@ -317,15 +331,15 @@ boolean Plugin_xxx(uint8_t function, struct EventStruct *event, String& string)
317331
} else {
318332
// do non-specific subcommand
319333
}
320-
success = true; // set to true only if plugin has executed a command successfully
334+
success = true; // set to true **only** if plugin has executed a command/subcommand successfully
321335
}
322336
323337
break;
324338
}
325339
326340
case PLUGIN_EXIT:
327341
{
328-
// perform cleanup tasks here. For example, free memory
342+
// perform cleanup tasks here. For example, free memory, shut down/clear a display
329343
330344
break;
331345
}

0 commit comments

Comments
 (0)