Final polishing on several pages

docs/de/index.md

@@ -2,5 +2,5 @@
 
 NodeMCU ist eine [eLua](http://www.eluaproject.net/)-basierende firmware für den [ESP8266 WiFi SOC von Espressif](http://espressif.com/en/products/esp8266/). Dies ist ein Partnerprojekt für die beliebten [NodeMCU dev kits](https://github.com/nodemcu/nodemcu-devkit-v1.0) - open source NodeMCU boards mit ESP8266-12E chips.
 
-Diese firmware nutzt das Espressif SDK v1.4, das Dateisystem basiert auf [spiffs](https://github.com/pellepl/spiffs).
+Diese firmware nutzt das Espressif NON-OS SDK, das Dateisystem basiert auf [spiffs](https://github.com/pellepl/spiffs).
 

docs/en/build.md

@@ -1,10 +1,10 @@
 There are essentially three ways to build your NodeMCU firmware: cloud build service, Docker image, dedicated Linux environment (possibly VM).
 
-## 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.
 
-## Docker image
+## Docker Image
 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
+## 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. 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.

docs/en/faq.md

@@ -2,7 +2,7 @@
 
 **# # # Work in Progress # # #**
 
-*I have started a thread on the ESP8266 forum, [Discussions on my NodeMCU Lua unofficial FAQ](http://www.esp8266.com/viewtopic.php?f=24&t=3311&p=18770).  Please use this to discuss any issues that you have with this FAQ; any areas where you feel that the explanation is unclear or needs further expansion; or any or Qs that you feel need answering and would help others if they were included here.  Thank-you.  [Terry Ellison](https://github.com/TerryE)*
+*This was started by [Terry Ellison](https://github.com/TerryE) as an unofficial FAQ in mid 2015. It never became officially official and it is in need of an overhaul, see [#937](https://github.com/nodemcu/nodemcu-firmware/issues/937). Yet, it is still very valuable and is, therefore, included here.*
  
 ## What is this FAQ for?
 

docs/en/flash.md

@@ -4,6 +4,11 @@ Adafruit provides a really nice [firmware flashing tutorial](https://learn.adafr
 
     Keep in mind that the ESP8266 needs to be put into flash mode before you can flash a new firmware!
 
+To enable ESP8266 firmware flashing GPIO0 pin must be pulled low before the device is reset. Conversely, for a normal boot, GPIO0 must be pulled high or floating.
+
+If you have a [NodeMCU dev kit](https://github.com/nodemcu/nodemcu-devkit-v1.0) then you don't need to do anything, as the USB connection can pull GPIO0 low by asserting DTR and reset your board by asserting RTS.
+
+If you have an ESP-01 or other device without built-in USB, you will need to enable flashing yourself by pulling GPIO0 low or pressing a "flash" switch.
 
 ## esptool
 > A cute Python utility to communicate with the ROM bootloader in Espressif ESP8266. It is intended to be a simple, platform independent, open source replacement for XTCOM.

docs/en/index.md

@@ -1,12 +1,51 @@
 # 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/). This 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 [ESP8266 WiFi SOC from Espressif](http://espressif.com/en/products/esp8266/). The firmware is based on the Espressif NON-OS SDK 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 firmware is based on the Espressif NON-OS SDK and uses a file system based on [spiffs](https://github.com/pellepl/spiffs).
+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.
 
-## Getting started
-- [Build the firmeware](build.md) with the modules you need.
-- [Flash the firmware](flash.md) to the chip.
-- Load your code into the firmware.
+## 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` 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(conn, payload)
+		print(payload)
+		conn:send("<h1> Hello, NodeMCU.</h1>")
+	end)
+	conn:on("sent", function(conn) conn:close() end)
+end)
+```
+```lua
+-- connect to WiFi access point
+wifi.setmode(wifi.STATION)
+wifi.sta.config("SSID", "password")
+```
+
+```lua
+-- register event callbacks for WiFi events
+wifi.sta.eventMonReg(wifi.STA_CONNECTING, function(previous_state)
+	if(previous_state==wifi.STA_GOTIP) then 
+	    print("Station lost connection with access point. Attempting to reconnect...")
+	else
+	    print("STATION_CONNECTING")
+	end
+end)
+```
+
+```lua
+-- manipulate hardware like with Arduino
+pin = 1
+gpio.mode(pin, gpio.OUTPUT)
+gpio.write(pin, gpio.HIGH)
+print(gpio.read(pin))
+```
+
+## Getting Started
+1. [Build the firmeware](build.md) with the modules you need.
+1. [Flash the firmware](flash.md) to the chip.
+1. [Upload code](upload.md) to the firmware.
 
 

docs/en/modules/enduser-setup.md

@@ -1,7 +1,7 @@
 # enduser setup Module
 This module provides a simple way of configuring ESP8266 chips without using a serial interface or pre-programming WiFi credentials onto the chip.
 
-![](https://github.com/robertfoss/esp8266_nodemcu_wifi_setup/blob/images/screenshot.png?raw=true)
+![enduser setup config dialog](../../img/enduser-setup.jpg "enduser setup config dialog")
 
 After running [`enduser_setup.start()`](#enduser_setupstart) a portal like the above can be accessed through a wireless network called SetupGadget_XXXXXX. The portal is used to submit the credentials for the WiFi of the enduser.
 After an IP address has been successfully obtained this module will stop as if [`enduser_setup.stop()`](#enduser_setupstop) had been called.

docs/en/support.md

@@ -1,4 +1,4 @@
-The [issues list on GitHub](https://github.com/nodemcu/nodemcu-firmware/issues) is **not** the right place to ask for help. Use it to report bugs and to place feature requests. "how do I ..." or a "I can't get this to work ..." should be directed to StackOverflow or esp8266.com.
+The [issues list on GitHub](https://github.com/nodemcu/nodemcu-firmware/issues) is **not** the right place to ask for help. Use it to report bugs and to place feature requests. Questions like "how do I ..." or "I can't get this to work ..." should be directed to StackOverflow or esp8266.com.
 
 ## StackOverflow
 StackOverflow is the perfect place to ask coding questions. Use one or several of the following tags: [esp8266](http://stackoverflow.com/tags/esp8266), [nodemcu](http://stackoverflow.com/tags/nodemcu) or [Lua](http://stackoverflow.com/tags/lua).

docs/en/upload.md

@@ -0,0 +1,35 @@
+As with [flashing](flash.md) there are several ways to upload code from your computer to the device.
+
+# ESPlorer
+
+> The essential multiplatforms tools for any ESP8266 developer from luatool author’s, including Lua for NodeMCU and MicroPython. Also, all AT commands are supported. Requires Java (Standard Edition - SE ver 7 and above) installed.
+
+![ESPlorer](../img/ESPlorer.jpg "ESPlorer")
+
+Source: https://github.com/4refr0nt/ESPlorer
+
+Supported platforms: OS X, Linux, Windows, anything that runs Java
+
+# nodemcu-uploader.py
+
+> A simple tool for uploading files to the filesystem of an ESP8266 running NodeMCU as well as some other useful commands.
+
+Source: https://github.com/kmpm/nodemcu-uploader
+
+Supported platforms: OS X, Linux, Windows, anything that runs Python
+
+# NodeMCU Studio
+
+> THIS TOOL IS IN REALLY REALLY REALLY REALLY EARLY STAGE!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Source: https://github.com/nodemcu/nodemcu-studio-csharp
+
+Supported platforms: Windows
+
+# luatool
+
+> Allow easy uploading of any Lua-based script into the ESP8266 flash memory with NodeMcu firmware
+
+Source: https://github.com/4refr0nt/luatool
+
+Supported platforms: OS X, Linux, Windows, anything that runs Python

docs/index.md

@@ -1,10 +1,15 @@
 # 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/). This 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 [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.
 
-The firmware is based on the Espressif SDK v1.4 and uses a file system based on [spiffs](https://github.com/pellepl/spiffs).
+## Up-To-Date Documentation
+At the moment the only up-to-date documentation maintained by the current NodeMCU team is in [English](en/index.md). It is part of the source code repository (`/docs` subfolder) and kept in sync with the code.
 
-[English](en/index.md)
+We encourage you to help transferring the outdated translations (see below) into the repository.
 
-[Deutsch](de/index.md)
+## Outdated And Sparse Documentation
+The following translations are based on outdated documentation, use them with caution. The links point to the [NodeMCU wiki on GitHub](https://github.com/nodemcu/nodemcu-firmware/wiki).
 
+- Chinese, [中文](https://github.com/nodemcu/nodemcu-firmware/wiki/nodemcu_api_cn)
+- Russian, [русский](https://github.com/nodemcu/nodemcu-firmware/wiki/nodemcu_api_ru)
+- Spanish, [español](https://github.com/nodemcu/nodemcu-firmware/wiki/nodemcu_api_es)

mkdocs.yml

@@ -26,6 +26,7 @@ pages:
     - Home: 'en/index.md'
     - Building the firmware: 'en/build.md'
     - Flashing the firmware: 'en/flash.md'
+    - Uploading code: 'en/upload.md'
     - FAQ: 'en/faq.md'
     - Support: 'en/support.md'
     - Modules:
@@ -59,5 +60,5 @@ pages:
         - 'wifi': 'en/modules/wifi.md'
         - 'ws2801': 'en/modules/ws2801.md'
         - 'ws2812': 'en/modules/ws2812.md'
-- Deutsch:
-    - Home: 'de/index.md'
+#- Deutsch:
+#    - Home: 'de/index.md'