Browse Source

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

Arnim Läuger 7 years ago
parent
commit
1935a642b2
5 changed files with 150 additions and 8 deletions
  1. 51 0
      README.md
  2. 81 7
      docs/en/build.md
  3. 16 0
      docs/en/flash.md
  4. 1 1
      docs/index.md
  5. 1 0
      mkdocs.yml

File diff suppressed because it is too large
+ 51 - 0
README.md


+ 81 - 7
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
-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.
+### 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
-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. 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.
+### 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.~
+
+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 --->
+```

+ 16 - 0
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.

+ 1 - 1
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.
 

+ 1 - 0
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'

Some files were not shown because too many files changed in this diff