ESPEasyDevelopmentGuidelines

Guidelines for contributing to the ESP Easy project

History

ESP Easy has started out as a small prototyping project to make it 'easy' to connect Dallas and DHT sensors to Domoticz. Where 'Easy' mainly means: no programming skills required for regular users, just a friendly web gui to hookup things.

From there, the project has evolved quite a bit and along the line, we merged source code from another project that was based on porting the Nodo project to ESP. We've adopted the Nodo plugin concept and also a lot of existing plugins that were fully optimized for running on a small environment (ATMega328 with only 32k flash). Optimized meaning: using mininum RAM, getting rid of C classes and sometimes bloated libraries, getting rid of device features that we do not really need, etc... We've taken many shortcuts to sqeeuze as much code into the the small MCU as possible, sometimes at the cost of coding quality.

Besides the special origin of this project, there's the prototyping approach that led to many new features without special care taken into a formal design. Just build as you go and see where it ends...

So if you're a developer, you might raise your eyebrows when looking at the source code and ask yourself why things are coded as they are... Maybe this introduction explains a bit...

Current status

Given the history, it currently leaves us in a situation where we need some special guidelines for further development to keep this project on the road. And although a lot of original source code has already been optimized for small size, we have almost reached the limit on the classic 512k flash based ESP modules.

There maybe several solutions to this problem, but as long as we do not have those in place, we need to stick to some rigid guidelines to keep users with classic modules "happy campers".

Contributing

This can be done in many ways but we will focus here on contributing by adding or modifying source code to the project.

We have seen pull requests to the master branch as well as other code samples in the plugin playground or just inline code samples within a forum topic. All contributions are welcome because they can all help in development or just by raising new ideas or concepts. Although it may be very tempting to just merge every pull request into the master repository, it could soon become a bit of a mess and we will soon be hitting the infamous "sketch too big" compiler messages.

So to avoid some confusion, disappointment, frustration or other inconveniences, we do feel the need to adopt some new guidelines.

Goals and challenges

Framework vs plugins

We have to keep a solid distinction between the framework and plugins. The ESP Easy framework consists of all files except the ones starting with an underscore like _Cxxx and _Pxxx. Those _xxxx files are the protocol and device plugins files that build upon the provided framework. The framework only provides basic functionality to control plugins, provide internal commands and support for basic networking protocols like UDP, HTTP, MQTT. Code for any specific device or Home Automation platform should implementen using plugins.

Program size and RAM usage

Because of the limited program size of the original 512K flash ESP modules, we cannot really accept many more plugins in the standard firmware. And some plugins could claim a non-negligible amount of global RAM (so even when they are not selected, they still allocate the RAM) and having to many of those will lead to RAM shortage, leading to system instability.

Expanding the feature set

Plugin development should mainly be routed to the plugin playground first. From that repository, they can be evaluated by others without disturbing the master repository. It is certainly preferable that plugins can be added without changes to the framework. But if changes to the framework are unavoidable, please raise a discussion before creating pull requests or pushing stuff to the playground. Although the playground is open to all contributors without restrictions and prior approvals, regular users will benefit if things will be as simple as just adding a single file to the project folder and recompile. Try to avoid libraries and include the code within the plugin. This has proven to work for many years on the Nodo project and avoids change management issues on libraries.

Don't be fooled that the plugin playground only has experimental unstable stuff! It can be any variety, including stable and useful well structured plugins (that just don't fit the master repository yet because of their size or other dependencies, or the expected user group is just too small).

Guidelines

Development

• Pull requests on the framework can be made to propose bug fixes and chances are high that they will be honored.
• Device or controller specific code should be implemented using plugins
• Try to avoid external libraries
• Try to keep everything within a single plugin file
• All new plugins have to go to the plugin playground first
• Use the range 100-199 for playground plugins, check the playground to obtain the next available number

Adding to the master repository

Adding to the master repository is based on the following considerations

• Is this a very commonly used peripheral, like DHT11/22, Dallas etc. ?
• Stable code or still in development ?
• Does it add a unique measurement, so not just another temperature sensor...
• If we have a choice between similar devices, cheaper sensors are preferred as default
• Is this device easily obtainable (eBay, AliExpress, ..)
• Affordable resource usage?