ESPEasyDevelopmentGuidelines

You may hear some construction noise in the background...

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 squeeze 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 has 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 after looking at the source code and you may ask yourself why things are coded as they are... Maybe this introduction explains things 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 512 kB flash based ESP modules.

There may be 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 be implemented by using plugins.

Program size and RAM usage

Because of the limited program size of the original 512 kB 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 within the default package will lead to RAM shortage, leading to system instability.

And despite the fact that the more recent modules have more flash on board, the RAM challenges remain.

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 commit 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. It may not be the best development method but it currently fits our project better.

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

Generic

• Pull requests on the framework can be made to propose bug fixes and chances are high that they will be honored.
• Code that doesnt pass our automated Travis build-tests will not be accepted.
• Device or controller specific code should be implemented by using plugins
• Try to avoid external libraries
• Try to keep everything contained within a single plugin file

Creating new plugins on the playground

If you're creating new plugins that you want to share, please create a pull request on the playground repository: https://github.com/letscontrolit/ESPEasyPluginPlayground

• Use the range 100-199 for playground plugins, check the playground to obtain the next available number.
• Anything kind of plugin you might think is usable for someone is ok.
• We dont check or verify playground code that much.
• We dont have very strict rules for the playground.

Adding plugins to the master repostory

Rules for the master repository are much more strict:

• First add the plugin to the playground and let others test it.
• Is this a very commonly used peripheral, like DHT11/22, Dallas etc. ?
• Did you do some basic testing of the plugin?
• 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?
• Make sure the plugin uses as little IRAM as possible, since we're out of IRAM. If its using too much, we cant include it in the default plugin set.
• Change the plugin id to the next available id in the main repository.

• If your plugin is just new add this:

    #ifdef PLUGIN_BUILD_DEV
    ...
    #define PLUGIN_NAME_123       "Your plugin name [DEVELOPMENT]"
    ...(your plugin)
    #endif

• If your used your plugin yourself for a while and think its pretty ok, add this:

    #ifdef PLUGIN_BUILD_TESTING
    ...
    #define PLUGIN_NAME_123       "Your plugin name [TESTING]"
    ...(your plugin)
    #endif

• After your plugin is added, please create a pull request that removes it from the playground.

Documentation

Continue reading here for program details: ESPEasyDevelopment

Too rigid ?

If you don't feel comfortable with these guidelines: Don't worry as you can always fork your own github repository and be as creative as one can be. We certainly don't mind and may even have a peek to see it we can learn and adopt from your work.

Thanks to the open source community to provide this level of freedom!