Add README, 'make help', header comments, Copyright notices

FreeRTOS/Source/portable/esp8266/sdk_compat.c

@@ -1,5 +1,10 @@
-/* this file provides function aliasing/etc that are needed for
+/*
-   compatibility with other binary espressif libraries */
+ * Stub functions called by binary espressif libraries
+ *
+ * Part of esp-open-rtos
+ * Copyright (C) 2105 Superhouse Automation Pty Ltd
+ * BSD Licensed as described in the file LICENSE
+ */
 #include <stdlib.h>
 #include <string.h>
 #include "FreeRTOS.h"

README.md

@@ -0,0 +1,86 @@
+# esp-open-rtos
+
+A community developed open source [FreeRTOS](http://www.freertos.org/)-based framework for [ESP8266 WiFi-enabled microcontrollers](https://github.com/esp8266/esp8266-wiki/wiki). Intended for use in both commercial and open source projects.
+
+Similar to, but substantially different from, the [Espressif IOT RTOS SDK](https://github.com/espressif/esp_iot_rtos_sdk).
+
+## Quick Start
+
+* Install [esp-open-sdk](https://github.com/pfalcon/esp-open-sdk/) and make the toolchain available on your PATH. Despite the similar name that project has different maintainers (but we think it's fantastic!)
+
+    (Alternative toolchains can also work, as long as a gcc cross-compiler is available on the PATH. The official Tensilica "xcc" compiler will probably not work.)
+
+* Install [esptool.py](https://github.com/themadinventor/esptool) and make it available on your PATH.
+
+* The build process uses `GNU Make`, and the utilities `sed` and `grep`. Linux & OS X should have these already. Windows users can get these tools a variety of ways, [MingGW](http://www.mingw.org/wiki/mingw) is one option.
+
+* Use git to clone the esp-open-rtos project:
+
+```
+git clone git@github.com:superhouse/esp-open-rtos.git
+cd esp-open-rtos
+```
+
+* Build an example project and flash it to a serial port:
+
+```
+make -j4 -C examples/http_get flash ESPPORT=/dev/ttyUSB0
+```
+
+## 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](https://github.com/superhouse/esp-open-rtos/issues).
+* Leave upstream source clean, for easy interaction with upstream projects.
+* Flexible build and compilation settings.
+
+Current status is alpha quality, under development. AP STATION mode (ie wifi client mode) and UDP/TCP client modes are tested. Other functionality should work. Contributors and testers are welcome!
+
+## Open Source Components
+
+* [FreeRTOS](http://freertos.org) V7.5.2
+* [lwIP](http://lwip.wikia.com/wiki/LwIP_Wiki) v1.4.1, modified via the [esp-lwip project](https://github.com/kadamski/esp-lwip) by @kadamski.
+* [axTLS](http://axtls.sourceforge.net/) compiled from development version v1.5.3, plus modifications for low memory devices.
+
+## Binary Components
+
+Binary libraries (inside the `lib` dir) are all supplied by Espressif as part of their RTOS SDK which is 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 appears to be based on FreeBSD net80211, or a fork of it.
+* 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, and [lwIP](http://lwip.wikia.com/wiki/LwIP_Wiki). LWIP is CopyrighT (C) Swedish Institute of Computer Science.
+
+* 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](https://github.com/espressif/esp_iot_rtos_sdk) were released under the MIT license. Source code components are relicensed here under the BSD license. Components are Copyright (C) Espressif Systems.
+
+## Contributions
+
+Contributions are very welcome!
+
+* If you find a bug, [please raise an issue to report it](https://github.com/superhouse/esp-open-rtos/issues).
+
+* If you have feature additions or bug fixes then please send a pull request.
+
+* There is a list of outstanding TODO items in the [issues list](https://github.com/superhouse/esp-open-rtos/issues). 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](https://github.com/espressif/esp_iot_rtos_sdk/commit/43585fa74550054076bdf4bfe185e808ad0da83e).
+
+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 wiki](https://github.com/esp8266/esp8266-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.
+
+## Sponsors
+
+Work on esp-open-rtos is sponsored by [SuperHouse Automation](http://superhouse.tv/).

axtls/axtls_esp_stubs.c

@@ -1,11 +1,15 @@
+/*
+ * Stub time-related functions for TLS time-related operations
+ *
+ * ESPTODO: Revisit these ASAP as gettimeofday() is used for entropy
+ *
+ * Part of esp-open-rtos
+ * Copyright (C) 2105 Superhouse Automation Pty Ltd
+ * BSD Licensed as described in the file LICENSE
+ */
 #include <time.h>
 #include <sys/time.h>
 #include <stdio.h>
-/*
- * Stub time functions for TLS time-related operations
- *
- * ESPTODO: Revisit these soon as gettimeofday() is used for entropy
- */
 
 time_t time(time_t *t)
 {

common.mk

@@ -1,32 +1,29 @@
 # esp-open-rtos common Makefile
 #
-# To use this Makefile, define the variable TARGET with the program
+# ******************************************************************
-# name (plus any other variables you want to override) in your
+# Run 'make help' in any example subdirectory to see a usage summary
-# progream's makefile, then include common.mk as the last line
+# (or skip to the bottom!)
-# in the Makefile.
+# ******************************************************************
 #
-# See the programs in the 'examples' directory for examples.
+# ESPTODO: Add a documentation link here.
+#
+# Most sections Copyright 2015 Superhouse Automation Pty Ltd
+# BSD Licensed as described in the file LICENSE at top level.
 #
-# Note: your program does not have to be under the top esp-open-rtos
-# directory - you can build out of tree programs.
-
 # This makefile is adapted from the esp-mqtt makefile by @tuanpmt
-# https://github.com/tuanpmt/esp_mqtt, but it has change significantly
+# https://github.com/tuanpmt/esp_mqtt, but it has changed significantly
 # since then.
-
+#
-# To override variables assigned below with ?= for the local system,
-# rather than per-project, add the entries to this optional local.mk
-# file, or specify on the command line, or pass as environment vars.
 -include local.mk
 
-# esptool defaults
-ESPTOOL ?= esptool.py
-ESPBAUD ?= 115200
-
 ifndef TARGET
 	$(error "Set the TARGET environment variable in your Makefile before including common.mk"
 endif
 
+# esptool defaults
+ESPTOOL ?= esptool.py
+ESPBAUD ?= 115200
+
 # Output directors to store intermediate compiled files
 # relative to the target directory
 BUILD_DIR ?= $(TARGET_DIR)build/
@@ -239,3 +236,36 @@ clean:
 # prevent "intermediate" files from being deleted
 .SECONDARY:
 
+# print some useful help stuff
+help:
+	@echo "esp-open-rtos make"
+	@echo ""
+	@echo "Other targets:"
+	@echo ""
+	@echo "all"
+	@echo "Default target. Will build firmware including any changed source files."
+	@echo
+	@echo "clean"
+	@echo "Delete all build output."
+	@echo ""
+	@echo "rebuild"
+	@echo "Build everything fresh from scratch."
+	@echo ""
+	@echo "flash"
+	@echo "Build then upload firmware to MCU. Set ESPPORT & ESPBAUD to override port/baud rate."
+	@echo ""
+	@echo "test"
+	@echo "'flash', then start a GNU Screen session on the same serial port to see serial output."
+	@echo ""
+	@echo "size"
+	@echo "Build, then print a summary of built firmware size."
+	@echo ""
+	@echo "TIPS:"
+	@echo "* You can use -jN for parallel builds. Much faster! Use 'make rebuild' instead of 'make clean all' for parallel builds."
+	@echo "* You can create a local.mk file to create local overrides of variables like ESPPORT & ESPBAUD."
+	@echo ""
+	@echo "SAMPLE COMMAND LINE:"
+	@echo "make -j2 test ESPPORT=/dev/ttyUSB0"
+	@echo ""
+
+

examples/http_get/main.c

@@ -1,3 +1,9 @@
+/* http_get - Retrieves a web page over HTTP GET.
+ *
+ * See http_get_ssl for a TLS-enabled version.
+ *
+ * This sample code is in the public domain.,
+ */
 #include "espressif/esp_common.h"
 
 #include "FreeRTOS.h"

examples/http_get_ssl/main.c

@@ -1,3 +1,11 @@
+/* http_get_ssl - HTTPS version of the http_get example.
+ *
+ * Retrieves a web page over HTTPS (TLS) using GET.
+ *
+ * Does not validate server certificate.
+ *
+ * This sample code is in the public domain.,
+ */
 #include "espressif/esp_common.h"
 
 #include "FreeRTOS.h"
@@ -214,3 +222,4 @@ static void display_cipher(SSL *ssl)
 
     printf("\n");
 }
+

include/esp8266.h

@@ -1,9 +1,8 @@
 /* esp8266.h
  *
-<<<<<<< HEAD
  * ESP-specific SoC-level addresses, macros, etc.
- * Part of esp-open-rtos
  *
+ * Part of esp-open-rtos
  * Copyright (C) 2105 Superhouse Automation Pty Ltd
  * BSD Licensed as described in the file LICENSE
  */