Add ESP32 README.md and build/flash docs (#1873)
This commit is contained in:
Arnim Läuger
Marcel Stör
parent
1116bb2c71
commit
1935a642b2
|
|
@ -0,0 +1,65 @@
|
|||
# **NodeMCU on ESP32** #
|
||||
|
||||
[](https://gitter.im/nodemcu/nodemcu-firmware?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
||||
[](https://travis-ci.org/nodemcu/nodemcu-firmware)
|
||||
[](http://nodemcu.readthedocs.io/en/dev-esp32/)
|
||||
[](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)
|
||||
|
|
@ -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 --->
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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,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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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'
|
||||
|
|
|
|||
Loading…
Reference in New Issue