[Plugins] List of planned new plugins (request a Plugin-ID here)

[tonhuisman]

As it is sometimes quite hard to find the next available Plugin-ID for a new plugin, this list is supposed to be updated by either me or TD-er once a plugin is planned.
If you are working on a new plugin (for the mega branch, not the ESPEasyPluginPlayground repository, that has its own numbers), you can request a Plugin-ID to be reserved, just add a comment, a short description/title for the plugin and we'll assign an available ID.
Once the plugin is merged it must be removed from this list, as the current list of plugins is available in this Read The Docs page

New plugins, currently being worked on:

• P130 Current - IRMS_ADS1015 ( @handfreezer see ) PR [P130] Add simple circuit to get a current sensor , result is Irms #4009
• P136 Display - SSD1306/SH1106 using AdaGFX helper ( @tonhuisman) PR #(todo)
• P139 Power mgt - AXP2101 Power management ESP32 ( @tonhuisman) PR [P139] Add support for AXP2101 Powermanagement #4977
• P140 Input - CardKB QWERTY Keyboard ( @tonhuisman) PR #(todo)
• P149 Display - ePaper 1.9" 91 segment display ( @tonhuisman) PR #(todo)
• P155 SML smart meter ( @Brommander PR pending )
• P156 Kostal PV inverter ( @Brommander PR pending )
• P157 Varta Storage ( @Brommander PR pending )
• P158 I2C analog 4ch 0-10V ( @Brommander PR pending )
• P160 RF Receiver (433 MHz) ( @tonhuisman) PR #(todo)
• P161 RF Transmitter (433 MHz) ( @tonhuisman) PR #(todo)
• P171 RFID - WL-134 (request) ( @tonhuisman) PR #(todo)
• P174 Generic - CAN Importer ( @bclbruno) PR CAN bus implementation #5120
• P175 Dust - PMSA003i (requested here) ( @tonhuisman) PR [P175] Add Dust - PMSx003i (I2C) Sensor #5142
• P176 Communication - Victron VE.Direct (request) ( @tonhuisman) PR [P176] Add plugin Communication - Victron VE.Direct #5148
• P177 Available

New controllers: (Supported Controllers)

• C020 Siemens PLC S7 ( @Brommander PR pending )
• C021 LoRa (bidirectional communication) ( Warrick (forum link) PR pending )
• C022 CAN Controller ( @bclbruno) PR CAN bus implementation #5120

New notifications: (Supported Notifications)

• N003 Email Advanced (request) ( ?) PR #(todo)

Reference: ESPEasy Development guide

[TD-er]

I added it to the pinned issues.

[handfreezer]

Hello,
I would like to get a plugin number to pull request a plugin : it is intended to measure current through classic SCT013 with and ADS1015, using RMS method.
It is already working based on Arduino pure project, then I forked ESPEasy on my github (I created a P127 plugin for local dev) and convert to a plugin. It is working well too. So I just need a plugin number I guess?

Best regards.

[tonhuisman]

it is intended to measure current through classic SCT013 with and ADS1015, using RMS method.

Isn't that already supported by Plugin 25 ADS1115 (not fully compatible with ADS1015) or the ADS1015 plugin from PluginPlayground? Or is it an extension/improvement of that plugin?
Ideally it should be as generic as possible, so it is also usable for other purposes.

P130 is the next available Plugin ID.

[TD-er]

And add it to the "testing E" set.

[handfreezer]

Hello,
None of us. All the important thing is : "Measure of Current by RMS method" : the fact is to measure the current of a sinus form, and the RMS method require to sample a lot of time in only ONE wave . Say about 50Hz, this means you have to do a lot of adc conversion in only 20ms ! From what I understood from both plugin you suggested, it is not possible.
Note I also added few parameters to do the job right like the availibility to enter the frequency, the number of wave to sample, ...
I based my work on P025 (for structure code), but I had to rework about all the job:
my local dev P127_data_struct.cpp
my local dev P127_data_struct.h
my local dev _P127_IRMS_ADS1015.ino

Remark, I still have to do an improvement : I want to add a setup key to choose sample rate and a "just-in-time reader" in continuous mode sampling.

I don't want to duplicate an already code existing if so. I just suggest my work .

[handfreezer]

And add it to the "testing E" set.

OK
Note : I can't change the first message to inform P130 is in use. May I start a specific thread for this job?

[TD-er]

OK, so it is indeed some different approach.
Have not yet looked at your code, but I will as soon as it appears as a PR. (I will add your nr to the post here)
Just one thought... is it blocking code for longer than a single period?

[handfreezer]

Just one thought... is it blocking code for longer than a single period?

Right : and this is exactly why I:

• added a warning in the setup page of the device,
• I didn't notice any bad effect on 100ms, and as I said, only 40ms is enough (in continuous reading sample mode, only 20ms seems enough),
• also, the final user can choose the comportment by changing in setup page the frequency of the wave AND the number of wave to use for sampling,
• and the measure of the current do not need a high frequency of reading, which means, the interval could be set to something like 30s or 60s

[TD-er]

I can imagine that 20 msec isn't "stable" as you may just start on the "spike" of current on devices with poor power factor.
Then it becomes quite timing critical whether you may include this spike one time or twice. Also the net frequency isn't always constant.
I guess measuring for 30 msec would also be OK and then you need to look for the zero-crossings and measure in between. Just consider that it might need to "loop" on the sample buffer, or actively wait for the zero crossing and then start to accumulate the samples until you saw 2 more zero-crossings (make sure to include a timeout)

Upto roughly 100 msec is OK, but less is better as every blocking code for over 10 msec can lead to missing WiFi packets.
I do highlight the parts in the timing stats for > 100 msec as those are the ones to look at first when running into issues.

But these kinds of discussions are best for the actual PR I guess :)

[handfreezer]

In fact, I wrote my own ino code at beginning (wifimanager + adafruit GFX + adafruit1X15 + MQTT + personnal code), and it was working for 4 months . I decided to switch to easyesp to avoid me managing the Wifi and the MQTT diffusion.
About the timing, from my understand of current RootMeanSquare formula : the most important is to get a half or a full sinus over and under zero, and the formula do the job. So, for a 50Hz voltage, you have to choose a factor of 10ms.

Note/question : I'm not used to pull-request (well, in fact, it will be my first time). I commited on mega branch on my fork of espeasy, but i commited also dirty code before the good one. is it possible to choose only good commit? or may I have to refork a new time, create a branch, and make a clean delivery commit in it?

[tonhuisman]

Have a look at the guide for developers, new to Github and ESPEasy, part of our Read The Docs (RTD) documentation. On that same page, a few paragraphs up, there is also a guide on how to set up your development environment using VSCode and PlatformIO, as that's currently the preferred development environment.

[TD-er]

create a branch, and make a clean delivery commit in it?

That's the main thing you need to do.
No need to fork it again.
Then push the commits on this new branch and go to the Github page of the letscontrolit/ESPEasy repo (either on the pull request or the code page). There you will be presented with a yellow-ish bar asking you to create a pull request and follow those steps.
If you later push new commits to that same branch, those will be appended to that pull request as you essentially link that branch to the pull request.
All is explained in the link posted by Ton.

[handfreezer]

Hello. Sorry for being absent.i should be able to do the job on next two weeks.

20220306: I started to prepare the pull request on my fork in a branch named P130 (I can't use previous commit as they are not clean, and I created my plugin under P127 already used... :-( ). I have to clean up the code as I did tests before ending to this solution. Question : you ask me to add it to "testing E" But, I would like also to have a personnal profile build with only what I need. May I ask you how to do it without pulling it?

[tonhuisman]

I would like also to have a personnal profile build with only what I need. May I ask you how to do it without pulling it?

There are several ways to achieve that, the officially supported ways:

• PlatformIO (VSCode/Atom): Copy file Custom-sample.h to Custom.h and enable all features and settings to your liking. That file is excluded from git to be committed. Then from PlatformIO build any custom configuration, and it will use that .h file. As described in the PlatformIO guide
• When using Arduino IDE, it's a bit more cumbersome, best is to follow the Arduino IDE guide

Some alternatives: (when not using a Custom.h, and assuming you use PlatformIO)

• Modify either (or both) pre_custom_esp8266.py or pre_custom_esp32.py (choose your used CPU-architecture) then build a custom configuration from PlatformIO. Be careful to not commit these files, as they are used for the provided custom builds, and TD-er usually determines what should go in there.
• Modify define_plugin_sets.h to include the plugin in the set you want it to be, like TESTING_E. Then build that configuration from PlatformIO. Only commit the change(s) from this file to include the plugin in the desired set, not any possible other personal changes you've made there.

[handfreezer]

OK, thanks for answer. So, adding a custom personnal env in platformio_esp32_envs.ini is not the right way, isn't it?

[tonhuisman]

adding a custom personnal env in platformio_esp32_envs.ini is not the right way, isn't it?

Adding such environment is only feasible if it adds an improvement to ESPEasy for all to benefit.
In your case it is way easier to have a local Custom.h file. You can of course create several of these, and rename to Custom.h when desired. Just remember to not include them in a PR.

[handfreezer]

@tonhuisman : Thanks for all your answer. Note that compiling TEST_E : I failed sometime with a memory size error, so with customer.h I success each time as keeping only controller/notif/plugin I need, it's perfect!

On my side, I have ended my first cleaning of code to do a first PR (prep on this branch), BUT I would like to document the use of this plugin (with simple schema, and picture). May I ask you where this should be done to win a bit of time?

[tonhuisman]

compiling TEST_E : I failed sometime with a memory size error

Are you building that using VSCode/PlatformIO? And what operating system?

I would like to document the use of this plugin

That is a great initiative 👍

Documentation is part of the source code. The format used is ReStructured Text (.rst files), using the Sphinx tools. Initial setup is documented here. (Need to execute at least once). Once the PR is merged your doc work is available on the ESPEasy readthedocs page.
What to do to add plugin documentation:

• Create a P<pluginid>.rst file (P130.rst) in folder docs\source\Plugin. I usually copy/paste/adapt an existing file. When copying an existing file, rename all placeholders to the new name. Write the documentation using the rst format. Preferably use .png format for screenshots. Photo's can be in .jpg format.
• Add the generic info to docs\source\Plugin\_plugin_substitutions_p13x.repl (file doesn't exist yet, create the file, and copy the P120* entries from _plugin_substitutions_p12x.repl and rename & adjust them.
• Add that _plugin_substitutions_p13x.repl file to _plugin_substitutions.repl.
• Add your plugin reference to _plugin_categories.repl in the mathcing category. Then it will automatically show up on the second part of the Plugin page.
• Add (copy) a line to _Plugin.rst to reflect your plugin P130, like P125 (the current last one in the list, first 'part' of the file).
• Build the documentation as per the instructions (cd docs and .\make.bat html) Most likely that will throw an error on the 'magick' tool, used for normalizing the image sizes, not being available, but AFAICS that will only work on Linux/MacOS, and it's no problem on Windows.
• Open the generated index.html file from docs\build\html in a webbrowser, and review your work.

[handfreezer]

Waouh, ok, it is a lot of stuff, but I don't stop my work here, let me this week to have a look.
About my environment, I'm under W10+VSCode+PlatformIO.

[handfreezer]

Hello, It was more complicated to start writing doc as I was thinking, but it is done, and commited on here .
I feel my plugin is ready to create a PR. Maybe, do you want just to review the doc before? (I'm uploading it here) => note that I left a blank at the end for adding link to aliexpress with your referral to earn points to help the ESPEasy project.

[tonhuisman]

It was more complicated to start writing doc as I was thinking, but it is done

Understood, I've gone through the same learning curve, some time ago, but it is looking good, though there are a few spelling thingies to be resolved.

I feel my plugin is ready to create a PR

It sure does look like that 👍 so, just create the PR, and we'll comment on it (we're always nice 😄), but that is all part of the learning curve.

[handfreezer]

Well, I have a problem:

I fell I'll have to solve this before to check my plugin is always working well.
I'll also include an option to convert Irms value to real value.

[tonhuisman]

I'd not bother about that now and just create the pull request, as suggested, as that merge can be done later without much issue.

[handfreezer]

Pull request created, but I failed to remove some local commit on my repo from pull request like creating a custom build in general config file or adding an alert header in the readme.md file of the project to redirect people to the original project...

=> the pull request

[flashmark]

I would like to play with the ens160 TVOC sensor (gases). This is yeat another I2C based gas sensor. Can I reserve a plugin number for this one? ScioSense provided an Arduino library on GitHub (https://github.com/sciosense/ENS160_driver). Sensor is still traveling from ALi to home...

[TD-er]

There are lots of calls to delay() in that library, so please try to get rid of those as we really don't want to use delays in ESPEasy.

delay(1) is OK when needed, but not much longer.

[flashmark]

Thanks for the warning. Then I have to rewrite it to something more suitable for ESPEasy. Is there any convention on where to put such device specific code in ESPEasy? I see imported libraries in \lib. But if I have to rewrite stuff I assume it is better to put it all in the \src\PluginStructs\Pxxx_data_struct.cpp? For now I will use P164, I can always renumber it.

[tonhuisman]

Is there any convention on where to put such device specific code in ESPEasy? I see imported libraries in \lib

Usually we add the library in the lib folder, and sometimes rename it, depending on the level of changes, or if it's backward compatible, just keep the original name. It's always nice to give the improvements back to the original project, though some of the libs haven't been actively maintained for a long time or even abandoned, so feedback can be slow at times.

[tonhuisman]

The library has a quite peculiar way of controlling the sensor, pulling pins high and low, and also sends logging to the serial port when a variable is set.
And the coding style is, well, 'different' from what's more commonly seen in Arduino libraries.
I suggest to add #ifdef ENS_DEBUG / #endif around those debug statements (add a line // #define ENS_DEBUG in the .h file so it can optionally be enabled during development), as we want to keep the code as lean as possible.

[mgx0]

As per P160 here's a playground plugin update: letscontrolit/ESPEasyPluginPlayground#186

[tonhuisman]

As per P160 here's a playground plugin update: letscontrolit/ESPEasyPluginPlayground#186

I'll start migration soon-ish, still working on other issues and improvements 😉

[andibaciu]

Hello,
I designed a plugins for IKEA Vindstyrka. I would like to integrate this into ESP-Easy so that everyone can use it.
With this plugin you can read next parameters from IKEA device:

• temperature
• humidity
• tVOC
• PM1.0
• PM2.5
• PM4.0
• PM10.0
• and i add a DewPoint parameter (use to calculate relation between temp and humidity)

Can I get a plugin ID for this?

[tonhuisman]

I've assigned P167 to the IKEA Vindstyrka, and hope it can be combined to also support the Sensirion SEN5x devices.
Description for the device should probably be Environment - Sensirion SEN5x (IKEA Vindstyrka), assuming the base sensor is the main feature.

[chemmex]

@tonhuisman would it be hard to also add NOx from SEN55?

[tonhuisman]

@tonhuisman would it be hard to also add NOx from SEN55?

Have to look closely at the PR for P167 (there will be some feedback, as I already had a quick glance at the code 😉), but the NOx measurement is interesting enough to be included in SEN55 mode 👍

[andibaciu]

@tonhuisman would it be hard to also add NOx from SEN55?

After PR for P167 finish, I intend to make an update and integrate standalone SEN54 and SEN55 sensors.

[flashmark]

I am playing with a plugin to control the pump of my floor heating. I want local control with remote override and use a RGB led for status. This made it a bit too complex for rules. However, it is not really a standard plugin, although reusable for thermostats alike control. Question is how to handle such plugins? Is there a reserved plugin range to prevent overlap with the growing amount of plugins? I started with P999, but it looks like the plugin ID is a 8 bit integer, now using P254 locally. Looks likewe are rapidly filling the available space.

[tonhuisman]

We already have the ESPEasyPluginPlayground repository for a long time, but reality is that, because of many improvements to the ESPEasy Core code, and not many updates of the code on the playground, a lot of the plugins there are no longer compatible with the current ESPEasy code. And another issue is that a lot of code is written with quite basic Arduino-knowledge & skills, resulting in, well, less-optimal code, to name it nicely.
I've migrated a few of the plugins there to this repo, and it's usually a lot of work adjusting to both the current code, and fixing inefficient code.

The PluginID is indeed limited to an 8 bit unsigned int (uint8_t), so 254 is a safe limit to apply.

By the gist of your explanation, it seems quite reasonable that other ESPEasy users might be interested in your plugin, so the simple solution is to assign the next available plugin ID (P168), I just need a matching description to add it to the list 😉
The only thermostat-like plugins currently available are the Level Control (P021) and ThermoOLED (P109), so there is room for extension there.

[flashmark]

Thanks for feedback. P109 is too complex for my use case. But I missed P021. This looks close to my prototype, except for the LED feedback. I have to study P021 closely to estimate impact on adding my stuff or just reuse that one.

Current design:

• Several control modes: (OFF, ON, STANDBY, LOCAL, REMOTE)
• Basic thermostat with hysteresis (now swiching on when temperature is high, but can be made configurable) in LOCAL and REMOTE
• Maintenance run (prevent pump is off for too long) in STANDBY, LOCAL, REMOTE
• Completely off in OFF
• Always on in ON
• Receive "on"/"off" from an external controller
  Still to implement the remote control part.

Note I am pretty well aware of real-time software, but more involved with UML and Powerpoint than having C++ experience... So review is required. It would be nice to have a "plugin builders manual" providing references and design guides and rules. I can help with the writing of such documentation as long as I get the right feedback from the architects.

One of the questions for me is how to access IO pins. Direct Arduino function calls ere available, but I also see some ESPEasy abstraction levels. I need to do reverse engineering of existing plugins which could be potentially bad examples. A cookbook would tell me how to do this best...

[flashmark]

Still playing with my pump controller. Probably the name fits best as "regulator - heating pump" or "regulator - pump".
Main difference with P021 is additional control to keep a pump running for a minimum time and to switch it on for s short maintenance run. An optional 3-color LED can be used to see if pump is switched on, switched off or running in maintenance mode. If this sounds as an interesting plugin to share I will add the documentation. I am thinking of ways to make it more versatile. But the main purpose is to keep my heating pump running when needed.

[TD-er]

Not sure if it should be 1 plugin and if it is only a minor extension to an existing plugin, why not adding such a feature to the existing plugin via some parameter or as a command?
Or maybe P021 is not sending an event so maybe that's all what is needed to make it all work?

[tonhuisman]

• Several control modes: (OFF, ON, STANDBY, LOCAL, REMOTE)

The OFF and ON states are clear (as described), but not sure what kind of purpose or meaning Standby, Local or Remote would have?

If the state can be changed by a command, then you have the option of remote-control, as there are several ways of sending commands to a unit, HTTP, UDP (P2P), MQTT, Time based.
One factor to take care of would be long-time timers for the maintenance mode, like 2 weeks or smt. in that range, as you would want that to survive a reboot/power-cycle. And currently, P021 is one of the few plugins that can actually store a value (probably should be a separate task instance), but storing that too often will cause damage to the flash 🤔

Controlling a multi-color led, either 3-color via a few GPIO pins, or a Neopixel that has a full RGB color scale, could be handled from rules, using the correct events. Adding some new events shouldn't be too hard. Currently, an event is generated when the output state changes (sendData(event)).

Controlling GPIO state can be done in the standard 'Arduino' way via digitalWrite(), or using some more low-level, but much faster, functions. Several examples can be found, even in P021.

[flashmark]

Thanks, good food for thoughts and helping me to understand the design patters for ESPEasy.

My initial idea was to configure the "mode" from the web interface and use an on-off command only for remote control. But that can be changed.
Background: Floor heating pump with standard thermostat control. Hot water coming from heater will start the pump. When heater is switched off (low supply temperature) pump will run for a predefined time to spread remaining heat.
However, the pump should run at least once a day for 5 minutes to prevent bearings will become dry and pump fails. Additional modes are OFF: Never switch it on; OF: keep it always running; STANDBY: Keep it off, but still run 5 minutes a day; REMOTE: on demand force pump on by a remote control algorithm.
LED can indeed be separated as long as the internal state is made available. This makes an extension of P021 much easier. I will first finish hardware and current private plugin. Once I get everything running I will study migration to P021.

[scottw-finao]

Is there any chance of a plugin for the Seeedstudio (grove) i2c capacitive water level sensor?

Seeed Wiki page
Github code example
Catalog page

[tonhuisman]

Is there any chance of a plugin for the Seeedstudio (grove) i2c capacitive water level sensor?

I've reserved Plugin ID P170 for the Seeed Studio liquid level sensor, though I'm not yet sure if it should be in the (new) category 'Level', but I couldn't think of a better category to put it in, yet.
I've put it on my name, as from the context you wrote in the forum, I'm assuming you won't be developing this plugin 😅

[flashmark]

I have been playing with my floor heating pump controller plugin. I see some issues in merging it into P021. This will make the new version not backwards compatible with the original P021. The new plugin is simple, keeping all data in the standard structures. Main difference is the state machine I added to implement the additional, pump related, requirements like maintenance runs, operation modes and time extensions. I still tried to keep it generic. In case it is seen as reusable I can refactor it with a new plugin ID. Let me know if the plugin is seen as useful. If so, provide me with a plugin ID and collection.

[tonhuisman]

You could add a Yes/No checkbox to enable/disable your new features. (Add a new settings section below Auto-save interval.) For inspiration of how that's usually done, check P037 MQTT Import, where several features and settings are enabled/shown or disabled/hidden using a checkbox (that can submit the page)

And, most likely and said before, there will be someone interested in functionality like this. Especially if you explain in the documentation how it is intended to be used 👍

[flashmark]

One of the new features is also to provide 2 "values". The output set to the GPIO pin (pump on/off) and the state of the internal state machine. If this can also be managed in a backwards compatible way I will try to merge the two different concepts.

Minor issue is the way how to handle hysteresis. I prefer to use a "switch on" setpoint and a hysteresis value added/subtracted to/from the setpoint to switch off. P021 uses a symmetrical window around the setpoint. But that can be managed too. The concept to modify the setpoint using a command can be merged with the command to force the output to "on" which I need to run my pump whenever the CV is enabled.

I have to investigate if there are enough PCONFIG parameters available to store all the static data. Both plugins use some of them to store timers and other data. Moving to a P021_data_struct make the code a bit more complex.

I am still wondering how this "auto save" should work in P021. Quite some code to guard saving parameters too often. Something my original plugin does not need, but can be added too.

So main question for now is can I add a new value to P021 without breaking existing use cases and can I keep the code lean and mean.

[tonhuisman]

Having a variable number of values, depending on settings, is handled via the GetDeviceValueCount, like done in P026:

    case PLUGIN_GET_DEVICEVALUECOUNT:
    {
      event->Par1 = P026_NR_OUTPUT_VALUES;
      success     = true;
      break;
    }

That setting can also be a conditional returning either 1 or 2, P026 allows setting 1..4 output values 😃

Besides the PCONFIG(0..7) settings values there are also PCONFIG_LONG(0..3) and PCONFIG_FLOAT(0..3) available to store values. And there's an alias (union) PCONFIG_ULONG() parallel on PCONFIG_LONG() to be able to use all 32 bits, as has been done in some plugins like P116 and P150 to store multiple settings (1, 2, 3 4 or 8 bit) in such ulong.

[tonhuisman]

I am still wondering how this "auto save" should work in P021. Quite some code to guard saving parameters too often.

That second sentence is exactly the reason it is implemented. Some people update the value from rules every few seconds, causing an implicit save, that will eventually wear out the flash memory, rendering the ESP useless. To avoid that, the AutoSave feature keeps track of the currently stored value, and only saves to flash after the timeout is reached if the value is effectively changed.
This plugin is one of the few ways of storing a user value that will survive a cold boot/power cycle of the ESP.

Minor issue is the way how to handle hysteresis. I prefer to use a "switch on" setpoint and a hysteresis value added/subtracted to/from the setpoint to switch off. P021 uses a symmetrical window around the setpoint.

A more fine-grained way of handling the hysteresis is certainly an improvement over the current handling, as long as it can be made backward compatible (read: current settings value should still result in the same behavior after an upgrade. No requirement of saving the task to 'fix' that.)