j3d1/esp-open-rtos
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
No description
170 commits 10 branches 1 tag 25 MiB
C 98.2%
C++ 0.7%
Makefile 0.5%
Assembly 0.2%
Python 0.2%
Other 0.1%
Find a file
Angus Gratton f585ed8f46 Rename GPIO_CONF_PUSH_PULL to GPIO_CONF_OPEN_DRAIN 
Seems I got the functionality of this bit inverted when
initially testing.

In testing it also seems open drain mode is ignored on some pins, which
still source current. Needs more investigation though (may be pullups
internal to the ESP modules or set by default in software.)

Relates to #45
2015-09-12 16:21:26 +10:00
axtls Rework component makefiles to have a default <component>_ROOT 2015-09-08 09:59:59 +10:00
core Rename GPIO_CONF_PUSH_PULL to GPIO_CONF_OPEN_DRAIN 2015-09-12 16:21:26 +10:00
examples libc: Redefine int32_t/uint32_t as 'int' not 'long' 2015-09-05 13:37:00 +10:00
extras Rework component makefiles to have a default <component>_ROOT 2015-09-08 09:59:59 +10:00
FreeRTOS Rework component makefiles to have a default <component>_ROOT 2015-09-08 09:59:59 +10:00
include espressif/esp_wifi.h: Add prereq includes 2015-08-13 17:12:02 +10:00
ld Fix linker script handling of irom/irom0 segments 2015-08-27 13:54:30 -07:00
lib Add exception vectors & low-level handlers 2015-07-28 11:01:57 +10:00
libc libc: More int32_t fixes to not expect 'long' 2015-09-09 16:22:57 +10:00
lwip Rework component makefiles to have a default <component>_ROOT 2015-09-08 09:59:59 +10:00
.dir-locals.el emacs dir-locals.el: Only disable tabs in c-mode (Makefiles need tabs) 2015-07-21 15:26:11 +10:00
.gitignore Minor core header cleanups 2015-06-18 09:04:45 +10:00
.gitmodules Change github URLs to use HTTPS not ssh 2015-06-12 07:44:16 +10:00
.travis.yml Add Travis support - build toolchain, esptool2, all example projects 2015-08-21 15:53:25 +10:00
code_of_conduct.md Add link to mailing list, and code of conduct from CoralineAda/contributor_covenant (thank you!) 2015-09-07 17:04:14 +10:00
common.mk Allow properly for out-of-tree components (was a hack before) 2015-09-08 10:36:19 +10:00
LICENSE Add actual LICENSE file 2015-06-03 07:53:55 +10:00
README.md Update README with some recent developments 2015-09-07 17:52:01 +10:00

README.md

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

Github issues list/bugtracker: http://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

  • Install esp-open-sdk, build it with make STANDALONE=n, then edit your PATH and add the generated toolchain bin directory. (Despite the similar name esp-open-sdk has different maintainers - but we think it's fantastic!)

    (Other toolchains may also work, as long as a gcc cross-compiler is available on the PATH and libhal (and libhal headers) are compiled and available to gcc. The proprietary Tensilica "xcc" compiler will probably not work.)

  • Install esptool.py and make it available on your PATH. If you used esp-open-sdk then this is done already.

  • The esp-open-rtos build process uses GNU Make, and the utilities sed and grep. If you built esp-open-sdk then you have these already.

  • Use git to clone the esp-open-rtos project (note the --recursive):

git clone --recursive https://github.com/Superhouse/esp-open-rtos.git
cd esp-open-rtos
  • To build any examples that use WiFi, edit include/ssid_config.h and change the two macro defines:
#define WIFI_SSID "mywifissid"
#define WIFI_PASS "my secret password"

Remove the #warning line and follow the git ignore instructions written in the header file to keep your credentials from being pushed to Github.

  • Build an example project (found in the 'examples' directory) and flash it to a serial port:
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

  • Provide professional-quality framework for WiFi-enabled RTOS projects on ESP8266.
  • Open source code for all layers above the MAC layer, ideally lower layers if possible (this is a work in progress, see Issues list.
  • Leave upstream source clean, for easy interaction with upstream projects.
  • Flexible build and compilation settings.

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

  • examples contains a range of example projects (one per subdirectory). Check them out!
  • include contains header files from Espressif RTOS SDK, relating to the binary libraries & Xtensa core.
  • core contains source & headers for low-level ESP8266 functions & peripherals. core/include/esp contains useful headers for peripheral access, etc. Minimal to no FreeRTOS dependencies.
  • extras is a directory that contains optional components that can be added to your project. Most 'extras' components will have a corresponding example in the examples directory. Extras include:
  • FreeRTOS contains FreeRTOS implementation, subdirectory structure is the standard FreeRTOS structure. FreeRTOS/source/portable/esp8266/ contains the ESP8266 port.
  • lwip and axtls contain the lwIP TCP/IP library and the axTLS TLS library ('libssl' in the esp8266 SDKs), respectively. See Third Party Libraries wiki page for details.
  • libc contains the newlib libc. Libc details here.

Open Source Components

  • FreeRTOS V7.5.2
  • lwIP v1.4.1, modified via the esp-lwip project by @kadamski.
  • axTLS compiled from development version v1.5.3, plus modifications for low memory devices.
  • newlib v2.2.0, with patches for xtensa support and locking stubs for thread-safe operation on FreeRTOS.

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.

Some binary libraries appear to contain unattributed open source code:

  • libnet80211.a & libwpa.a appear to be based on FreeBSD net80211/wpa, or forks of them. (See this issue).
  • libudhcp has been removed from esp-open-rtos. It was released with the Espressif RTOS SDK but udhcp is GPL licensed.

Licensing

  • BSD license (as described in LICENSE) applies to original source files, lwIP, and axTLS. lwIP is Copyright (C) Swedish Institute of Computer Science. axTLS is Copyright (C) Cameron Rich.

  • FreeRTOS is provided under the GPL with the FreeRTOS linking exception, allowing non-GPL firmwares to be produced using FreeRTOS as the RTOS core. License details in files under FreeRTOS dir. FreeRTOS is Copyright (C) Real Time Engineers Ltd.

  • Source & binary components from the Espressif IOT RTOS SDK were released under the MIT license. Source code components are relicensed here under the BSD license. The original parts are Copyright (C) Espressif Systems.

  • Newlib is covered by several copyrights and licenses, as per the files in the libc directory.

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

Contributions

Contributions are very welcome!

  • If you find a bug, please raise an issue to report it.

  • If you have feature additions or bug fixes then please send a pull request.

  • There is a list of outstanding 'enhancements' in the issues list. Contributions to these, as well as other improvements, are very welcome.

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

  • Code from Espressif IoT SDK cannot be merged, as it is provided under either the "Espressif General Public License" or the "Espressif MIT License", which are not compatible with the BSD license.

  • Recent releases of the Espressif IoT RTOS SDK cannot be merged, as they changed from MIT License to the "Espressif MIT License" which is not BSD compatible. The Espressif binaries used in esp-open-rtos were taken from revision ec75c85, as this was the last MIT Licensed revision.

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, please use BSD style and indent using 4 spaces. If you're an emacs user then there is a .dir-locals.el file in the root which configures cc-mode.

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.