Home

Awesome

esp-open-rtos

A community developed open source FreeRTOS-based framework for ESP8266 WiFi-enabled microcontrollers. Intended for use in both commercial and open source projects.

Originally based on, but substantially different from, the Espressif IOT RTOS SDK.

Resources

Build Status

Email discussion list: https://groups.google.com/d/forum/esp-open-rtos

IRC channel: #esp-open-rtos on Freenode (Web Chat Link).

Github issues list/bugtracker: https://github.com/superhouse/esp-open-rtos/issues

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Quick Start

git clone --recursive https://github.com/Superhouse/esp-open-rtos.git
cd esp-open-rtos
#define WIFI_SSID "mywifissid"
#define WIFI_PASS "my secret password"
make flash -j4 -C examples/http_get ESPPORT=/dev/ttyUSB0

Run make help -C examples/http_get for a summary of other Make targets.

(Note: the -C option to make is the same as changing to that directory, then running make.)

The Build Process wiki page has in-depth details of the build process.

Goals

Current status is alpha quality, actively developed. AP STATION mode (ie wifi client mode) and UDP/TCP client modes are tested. Other functionality should work. Contributors and testers are welcome!

Code Structure

Open Source Components

For details of how third party libraries are integrated, see the wiki page.

Binary Components

Binary libraries (inside the lib dir) are all supplied by Espressif as part of their RTOS SDK. These parts were MIT Licensed.

As part of the esp-open-rtos build process, all binary SDK symbols are prefixed with sdk_. This makes it easier to differentiate binary & open source code, and also prevents namespace conflicts.

Espressif's RTOS SDK provided a "libssl" based on axTLS. This has been replaced with the more up to date mbedTLS library (see below).

Some binary libraries appear to contain unattributed open source code:

Licensing

Components under extras/ may contain different licenses, please see those directories for details.

Contributions

Contributions are very welcome!

If you are contributing code, please ensure that it can be licensed under the BSD open source license. Specifically:

For code submissions based on reverse engineered binary functionality, please either reverse engineer functionality from MIT Licensed Espressif releases or make sure that the reverse engineered code does not directly copy the code structure of the binaries - it cannot be a "derivative work" of an incompatible binary.

The best way to write suitable code is to first add documentation somewhere like the esp8266 reverse engineering wiki describing factual information gained from reverse engineering - such as register addresses, bit masks, orders of register writes, etc. Then write new functions referring to that documentation as reference material.

Coding Style

For new contributions in C, please use BSD style and indent using 4 spaces.

For assembly, please use the following:

If you're an emacs user then there is a .dir-locals.el file in the root which configures cc-mode and asm-mode (you will need to approve some variable values as safe). See also the additional comments in .dir-locals.el, if you're editing assembly code.

Upstream code is left with the indentation and style of the upstream project.

Sponsors

Work on parts of esp-open-rtos has been sponsored by SuperHouse Automation.