From 1935a642b2c1e2670e965f2b709e40bd6de9f57f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnim=20L=C3=A4uger?= Date: Fri, 24 Mar 2017 23:51:13 +0100 Subject: [PATCH] Add ESP32 README.md and build/flash docs (#1873) --- README.md | 65 +++++++++++++++++++++++++++++++++++ docs/en/build.md | 88 ++++++++++++++++++++++++++++++++++++++++++++---- docs/en/flash.md | 16 +++++++++ docs/index.md | 2 +- mkdocs.yml | 1 + 5 files changed, 164 insertions(+), 8 deletions(-) create mode 100644 README.md create mode 100644 docs/en/flash.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..03aabec5 --- /dev/null +++ b/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

Hello, NodeMCU.

") + 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) diff --git a/docs/en/build.md b/docs/en/build.md index e6d09d2b..30dc4b73 100644 --- a/docs/en/build.md +++ b/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 ---> +``` diff --git a/docs/en/flash.md b/docs/en/flash.md new file mode 100644 index 00000000..6a8aa020 --- /dev/null +++ b/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. diff --git a/docs/index.md b/docs/index.md index cc00dffb..b2114e93 100644 --- a/docs/index.md +++ b/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. diff --git a/mkdocs.yml b/mkdocs.yml index c8cfbc52..7a1d622e 100644 --- a/mkdocs.yml +++ b/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'