Add ESP32 README.md and build/flash docs (#1873)

README.md

@@ -0,0 +1,65 @@
+# **NodeMCU on ESP32** #
+
+[![Join the chat at https://gitter.im/nodemcu/nodemcu-firmware](https://img.shields.io/gitter/room/badges/shields.svg)](https://gitter.im/nodemcu/nodemcu-firmware?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Build Status](https://travis-ci.org/nodemcu/nodemcu-firmware.svg)](https://travis-ci.org/nodemcu/nodemcu-firmware)
+[![Documentation Status](https://img.shields.io/badge/docs-dev_esp32-yellow.svg?style=flat)](http://nodemcu.readthedocs.io/en/dev-esp32/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](https://github.com/nodemcu/nodemcu-firmware/blob/master/LICENSE)
+
+### A Lua based firmware for ESP32 WiFi SOC
+
+NodeMCU is an [eLua](http://www.eluaproject.net/) based firmware for the [ESP32 WiFi SOC from Espressif](http://http://espressif.com/en/products/hardware/esp32/overview). The firmware is based on the [Espressif IoT Development Framework](https://github.com/espressif/esp-idf) and uses a file system based on [spiffs](https://github.com/pellepl/spiffs). The code repository consists of 98.1% C-code that glues the thin Lua veneer to the SDK.
+
+The NodeMCU *firmware* is a companion project to the popular [NodeMCU dev kits](https://github.com/nodemcu/nodemcu-devkit-v1.0), ready-made open source development boards with ESP8266-12E chips.
+
+# Summary
+
+- Easy to program wireless node and/or access point
+- Based on Lua 5.1.4 (without *debug, os* modules)
+- Asynchronous event-driven programming model
+- 10+ built-in modules
+- Firmware available with or without floating point support (integer-only uses less memory)
+- Up-to-date documentation at [https://nodemcu.readthedocs.io](https://nodemcu.readthedocs.io)
+
+# Programming Model
+
+The NodeMCU programming model is similar to that of [Node.js](https://en.wikipedia.org/wiki/Node.js), only in Lua. It is asynchronous and event-driven. Many functions, therefore, have parameters for callback functions. To give you an idea what a NodeMCU program looks like study the short snippets below. For more extensive examples have a look at the [`/lua_examples`](lua_examples) folder in the repository on GitHub.
+
+```lua
+-- a simple HTTP server
+srv = net.createServer(net.TCP)
+srv:listen(80, function(conn)
+	conn:on("receive", function(sck, payload)
+		print(payload)
+		sck:send("HTTP/1.0 200 OK\r\nContent-Type: text/html\r\n\r\n<h1> Hello, NodeMCU.</h1>")
+	end)
+	conn:on("sent", function(sck) sck:close() end)
+end)
+```
+```lua
+-- connect to WiFi access point
+wifi.mode(wifi.STATION, true)
+
+wifi.sta.on("connected", function() print("connected") end)
+wifi.sta.on("got_ip", function(event, info) print("got ip "..info.ip) end)
+
+-- mandatory to start wifi after reset
+wifi.start()
+wifi.sta.config({ssid="SSID", pwd="password", auto=true}, true)
+```
+
+# Documentation
+
+The entire [NodeMCU documentation](https://nodemcu.readthedocs.io/en/dev-esp32/) is maintained right in this repository at [/docs](docs). The fact that the API documentation is maintained in the same repository as the code that *provides* the API ensures consistency between the two. With every commit the documentation is rebuilt by Read the Docs and thus transformed from terse Markdown into a nicely browsable HTML site at [https://nodemcu.readthedocs.io/en/dev-esp32/](https://nodemcu.readthedocs.io/en/dev-esp32/). 
+
+- How to [build the firmware](https://nodemcu.readthedocs.io/en/dev-esp32/en/build/)
+- How to [flash the firmware](https://nodemcu.readthedocs.io/en/dev-esp32/en/flash/)
+- How to [upload code and NodeMCU IDEs](https://nodemcu.readthedocs.io/en/dev-esp32/en/upload/)
+- API documentation for every module
+
+# Support
+
+See [https://nodemcu.readthedocs.io/en/dev/en/support/](https://nodemcu.readthedocs.io/en/dev/en/support/).
+
+# License
+
+[MIT](https://github.com/nodemcu/nodemcu-firmware/blob/master/LICENSE) © [zeroday](https://github.com/NodeMCU)/[nodemcu.com](http://nodemcu.com/index_en.html)

docs/en/build.md

@@ -1,12 +1,86 @@
 There are essentially three ways to build your NodeMCU firmware: cloud build service, Docker image, dedicated Linux environment (possibly VM).
 
-**Building manually**
+## Tools
 
-## Cloud Build Service
+### Cloud Build Service
-NodeMCU "application developers" just need a ready-made firmware. There's a [cloud build service](http://nodemcu-build.com/) with a nice UI and configuration options for them.
+~NodeMCU "application developers" just need a ready-made firmware. There's a [cloud build service](http://nodemcu-build.com/) with a nice UI and configuration options for them.~
 
-## Docker Image
+Not available yet.
-Occasional NodeMCU firmware hackers don't need full control over the complete tool chain. They might not want to setup a Linux VM with the build environment. Docker to the rescue. Give [Docker NodeMCU build](https://hub.docker.com/r/marcelstoer/nodemcu-build/) a try.
 
-## Linux Build Environment
+### Docker Image
-NodeMCU firmware developers commit or contribute to the project on GitHub and might want to build their own full fledged build environment with the complete tool chain. There is a [post in the esp8266.com Wiki](http://www.esp8266.com/wiki/doku.php?id=toolchain#how_to_setup_a_vm_to_host_your_toolchain) that describes this.
+~Occasional NodeMCU firmware hackers don't need full control over the complete tool chain. They might not want to setup a Linux VM with the build environment. Docker to the rescue. Give [Docker NodeMCU build](https://hub.docker.com/r/marcelstoer/nodemcu-build/) a try.~
+
+Not available yet.
+
+### Linux Build Environment
+NodeMCU firmware developers commit or contribute to the project on GitHub and might want to build their own full fledged build environment with the complete tool chain.
+
+Run the following command for a new checkout from scratch. This will fetch the nodemcu repo, checkout the `dev-esp32` branch and finally pull all submodules:
+
+```
+git clone --branch dev-esp32 --recurse-submodules https://github.com/nodemcu/nodemcu-firmware.git nodemcu-firmware-esp32
+```
+
+The `make` command initiates the build process, which will start with the configuration menu to set the build options.
+
+Updating your clone from upstream needs an additional command to update the submodules as well:
+```
+git pull origin dev-esp32
+git submodule update --recursive
+```
+
+## Build Options
+
+All configuration options are accessed from the file `sdkconfig`. It's advisable to set it up with the interactive `make menuconfig` - on a fresh checkout you're prompted to run through it by default.
+
+The most notable options are described in the following sections.
+
+### Select Modules
+
+Follow the menu path
+```
+Component config --->
+  NodeMCU modules --->
+```
+Tick or untick modules as required.
+
+### UART default bit rate
+
+Follow the menu path
+```
+Component config --->
+  Platform config --->
+    UART console default bit rate --->
+```
+
+### CPU Frequency
+
+Follow the menu path
+```
+Component config --->
+  ESP32-specific --->
+    CPU frequency --->
+```
+
+### Stack Size
+
+If you experience random crashes then increase the stack size and feed back your observation on the project's issues list.
+
+Follow the menu path
+```
+Component config --->
+  ESP32-specific --->
+    Main task stack size --->
+```
+
+### Flashing Options
+
+Default settings for flashing the firmware with esptool.py are also configured with menuconfig:
+
+```
+Serial flasher config --->
+  Default serial port
+  Default baud rate
+  Flash SPI mode --->
+  Detect flash size when flashing bootloader --->
+```

docs/en/flash.md

@@ -0,0 +1,16 @@
+Below you'll find all necessary information to flash a NodeMCU firmware binary to ESP32. Note that this is a reference documentation and not a tutorial with fancy screen shots. Turn to your favorite search engine for those.
+
+!!! attention
+
+    Keep in mind that the ESP32 needs to be [put into flash mode](#putting-device-into-flash-mode) before you can flash a new firmware!
+
+## Tool overview
+
+### esptool.py
+> A Python-based, open source, platform independent, utility to communicate with the ROM bootloader in Espressif ESP8266.
+
+Source: [https://github.com/espressif/esptool](https://github.com/espressif/esptool)
+
+Supported platforms: OS X, Linux, Windows, anything that runs Python
+
+Execute `make flash` to build and flash the firmware. See [Flashing Options](build.md#flashing-options) for the configuration of esptool.py.

docs/index.md

@@ -1,6 +1,6 @@
 # NodeMCU Documentation
 
-NodeMCU is an [eLua](http://www.eluaproject.net/) based firmware for the [ESP8266 WiFi SOC from Espressif](http://espressif.com/en/products/esp8266/).  The NodeMCU *firmware* is a companion project to the popular [NodeMCU dev kits](https://github.com/nodemcu/nodemcu-devkit-v1.0), ready-made open source development boards with ESP8266-12E chips.
+NodeMCU is an [eLua](http://www.eluaproject.net/) based firmware for the [ESP32](http://http://espressif.com/en/products/hardware/esp32/overview) and [ESP8266 WiFi SOC from Espressif](http://espressif.com/en/products/esp8266/).  The NodeMCU *firmware* is a companion project to the popular [NodeMCU dev kits](https://github.com/nodemcu/nodemcu-devkit-v1.0), ready-made open source development boards with ESP8266-12E chips.
 
 Support for the new [ESP32 WiFi/BlueTooth SOC from Espressif](http://www.espressif.com/en/products/hardware/esp32/overview) is under way.
 

mkdocs.yml

@@ -24,6 +24,7 @@ pages:
 - Overview: 'index.md'
 - English:
     - Building the firmware: 'en/build.md'
+    - Flashing the firmware: 'en/flash.md'
     - Uploading code: 'en/upload.md'
     - FAQs:
         - Lua Developer FAQ: 'en/lua-developer-faq.md'