Doc fixes (#3333)
This commit is contained in:
Gregor Hartmann
GitHub
parent
49b09d050e
commit
63d82131a7
|
|
@ -78,7 +78,7 @@ As a Windows or Mac user you could also resort to [GitHub Desktop](https://deskt
|
|||
You need to sync your fork with the NodeMCU upstream repository from time to time, latest before you rebase (see flow above).
|
||||
|
||||
1. `git fetch upstream`
|
||||
1. `git checkout dev` but you may do this for `master` as well
|
||||
1. `git checkout dev` but you may do this for `release` as well
|
||||
1. `git merge upstream/dev`
|
||||
|
||||
### Commit messages
|
||||
|
|
@ -114,8 +114,8 @@ Don't forget to [reference affected issues](https://help.github.com/articles/clo
|
|||
- Add notes to the description of the milestone in the course of the ~2 months it lives.
|
||||
- Be careful and reluctant to merge PRs once we're past the 6-weeks mark of a milestone. Ideally, we don't merge anything in the last 2 weeks.
|
||||
- Cutting a release
|
||||
- Create a PR for the `master` branch for collaborators to approve.
|
||||
- Create a PR for the `release` branch for collaborators to approve.
|
||||
- Once approved merge it. :exclamation::boom::exclamation: Make sure you do NOT "squash and merge" but make a regular merge commit!
|
||||
- Fetch the changes into your local clone and create an annotated tag like so: `git tag -a <SDK-version>-master_<yyyyMMdd> -m ""`, `git push --tags`
|
||||
- Fetch the changes into your local clone and create an annotated tag like so: `git tag -a <SDK-version>-release_<yyyyMMdd> -m ""`, `git push --tags`
|
||||
- Create a new [release](https://github.com/nodemcu/nodemcu-firmware/releases) based on the tag you just pushed. The version name is the same as the tag name.
|
||||
- Write release notes. Mention breaking changes explicitly. Since every PR that went into this release is linked to from the milestone it should be fairly easy to include important changes in the release notes.
|
||||
|
|
|
|||
22
README.md
22
README.md
|
|
@ -2,8 +2,8 @@
|
|||
|
||||
[](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/master/)
|
||||
[](https://github.com/nodemcu/nodemcu-firmware/blob/master/LICENSE)
|
||||
[](http://nodemcu.readthedocs.io/en/release/)
|
||||
[](https://github.com/nodemcu/nodemcu-firmware/blob/release/LICENSE)
|
||||
|
||||
### A Lua based firmware for ESP8266 WiFi SOC
|
||||
|
||||
|
|
@ -14,9 +14,9 @@ The firmware was initially developed as is a companion project to the popular ES
|
|||
# Summary
|
||||
|
||||
- Easy to program wireless node and/or access point
|
||||
- Based on Lua 5.1.4 but without `debug`, `io`, `os` and (most of the) `math` modules
|
||||
- Based on Lua 5.1.4 or Lua 5.3 but without `debug`, `io`, `os` and (most of the) `math` modules
|
||||
- Asynchronous event-driven programming model
|
||||
- more than **65 built-in modules**
|
||||
- more than **70 built-in C modules** and **close to 20 Lua 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)
|
||||
|
||||
|
|
@ -48,23 +48,23 @@ wifi.sta.config{ssid="SSID", pwd="password"}
|
|||
|
||||
The entire [NodeMCU documentation](https://nodemcu.readthedocs.io) 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](https://nodemcu.readthedocs.io).
|
||||
|
||||
- How to [build the firmware](https://nodemcu.readthedocs.io/en/master/en/build/)
|
||||
- How to [flash the firmware](https://nodemcu.readthedocs.io/en/master/en/flash/)
|
||||
- How to [upload code and NodeMCU IDEs](https://nodemcu.readthedocs.io/en/master/en/upload/)
|
||||
- How to [build the firmware](https://nodemcu.readthedocs.io/en/release/build/)
|
||||
- How to [flash the firmware](https://nodemcu.readthedocs.io/en/release/flash/)
|
||||
- How to [upload code and NodeMCU IDEs](https://nodemcu.readthedocs.io/en/release/upload/)
|
||||
- API documentation for every module
|
||||
|
||||
# Releases
|
||||
|
||||
Due to the ever-growing number of modules available within NodeMCU, pre-built binaries are no longer made available. Use the automated [custom firmware build service](http://nodemcu-build.com/) to get the specific firmware configuration you need, or consult the [documentation](http://nodemcu.readthedocs.io/en/master/en/build/) for other options to build your own firmware.
|
||||
Due to the ever-growing number of modules available within NodeMCU, pre-built binaries are no longer made available. Use the automated [custom firmware build service](http://nodemcu-build.com/) to get the specific firmware configuration you need, or consult the [documentation](http://nodemcu.readthedocs.io/en/release/build/) for other options to build your own firmware.
|
||||
|
||||
This project uses two main branches, `release` and `dev`. `dev` is actively worked on and it's also where PRs should be created against. `release` thus can be considered "stable" even though there are no automated regression tests. The goal is to merge back to `release` roughly every 2 months. Depending on the current "heat" (issues, PRs) we accept changes to `dev` for 5-6 weeks and then hold back for 2-3 weeks before the next snap is completed.
|
||||
|
||||
A new tag is created every time `dev` is merged back to `master`. They are listed in the [releases section here on GitHub](https://github.com/nodemcu/nodemcu-firmware/releases). Tag names follow the \<SDK-version\>-master_yyyymmdd pattern.
|
||||
A new tag is created every time `dev` is merged back to `release`. They are listed in the [releases section here on GitHub](https://github.com/nodemcu/nodemcu-firmware/releases). Tag names follow the \<SDK-version\>-release_yyyymmdd pattern.
|
||||
|
||||
# Support
|
||||
|
||||
See [https://nodemcu.readthedocs.io/en/master/en/support/](https://nodemcu.readthedocs.io/en/master/en/support/).
|
||||
See [https://nodemcu.readthedocs.io/en/release/support/](https://nodemcu.readthedocs.io/en/release/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)
|
||||
[MIT](https://github.com/nodemcu/nodemcu-firmware/blob/release/LICENSE) © [zeroday](https://github.com/NodeMCU)/[nodemcu.com](http://nodemcu.com/index_en.html)
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ If you decide to build with either the Docker image or the native environment th
|
|||
```
|
||||
git clone --recurse-submodules -b <branch> https://github.com/nodemcu/nodemcu-firmware.git
|
||||
```
|
||||
Omitting the optional `-b <branch>` will clone master.
|
||||
Omitting the optional `-b <branch>` will clone release.
|
||||
|
||||
## Build Options
|
||||
|
||||
|
|
@ -104,7 +104,7 @@ either by uncommenting `LUA_NUMBER_INTEGRAL` in `app/include/user_config.h`:
|
|||
```
|
||||
|
||||
OR by overriding this with the `make` command as it's [done during the CI
|
||||
build](https://github.com/nodemcu/nodemcu-firmware/blob/master/.travis.yml#L30):
|
||||
build](https://github.com/nodemcu/nodemcu-firmware/blob/release/.travis.yml#L30):
|
||||
|
||||
```
|
||||
make EXTRA_CCFLAGS="-DLUA_NUMBER_INTEGRAL ....
|
||||
|
|
|
|||
|
|
@ -10,9 +10,9 @@ You will typically do steps 1 and 2 only once, but then repeat step 3 as you dev
|
|||
|
||||
|
||||
!!! caution
|
||||
There's more than one way to skin a cat. For each of the tasks you have a number of choices with regards to tooling. The colored boxes represent an opinionated path to start your journey - the quickest way to success so to speak. Feel free to follow the links above to get more detailed information.
|
||||
For each of the tasks you have a number of choices with regards to tooling and depending on the OS you are on. The colored boxes represent an opinionated path to start your journey - the quickest way to success so to speak. Feel free to follow the links above to get more detailed information.
|
||||
|
||||
### Task / OS selector
|
||||
### Task and OS selector
|
||||
|
||||
<table id="gs">
|
||||
<tr>
|
||||
|
|
@ -80,7 +80,7 @@ You will typically do steps 1 and 2 only once, but then repeat step 3 as you dev
|
|||
<td>native</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th rowspan="2">Build luac.cross</th>
|
||||
<th rowspan="3">Build luac.cross</th>
|
||||
<td>not needed if you use Terry's webservice or Docker to later compile LFS image</td>
|
||||
<td>not needed if you use Terry's webservice or Docker to later compile LFS image</td>
|
||||
<td>not needed if you use Terry's webservice or Docker to later compile LFS image</td>
|
||||
|
|
@ -90,6 +90,11 @@ You will typically do steps 1 and 2 only once, but then repeat step 3 as you dev
|
|||
<td><a href="#macos">native</a></td>
|
||||
<td><a href="#linux">native</a></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a href="https://github.com/nodemcu/nodemcu-firmware/releases">download from release</a></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th rowspan="3">Compile Lua into<br>LFS image</th>
|
||||
<td class="select"><a href="#terrys-lfs-lua-cross-compile-web-service">webservice</a></td>
|
||||
|
|
@ -146,7 +151,7 @@ For everything else the cloud builder GUI is self-explanatory. Hence, no need fo
|
|||
1. Select an LFS size, 64KB is likely going to be large enough
|
||||
1. Select other options and build
|
||||
|
||||
[↑ back to matrix](#task-os-selector)
|
||||
[↑ back to matrix](#task-and-os-selector)
|
||||
|
||||
_Note that this service is not maintained by the NodeMCU team. It's run by a NodeMCU team member as an individual, though._
|
||||
|
||||
|
|
@ -163,7 +168,7 @@ _Note that this service is not maintained by the NodeMCU team. It's run by a Nod
|
|||
1. [Download](https://github.com/marcelstoer/nodemcu-pyflasher) then start PyFlasher
|
||||
1. Select serial port, browse for firmware binary and set the flash options.
|
||||
|
||||
[↑ back to matrix](#task-os-selector)
|
||||
[↑ back to matrix](#task-and-os-selector)
|
||||
|
||||
_Note that this tool is not an official NodeMCU offering. It's maintained by a NodeMCU team member as an individual, though._
|
||||
|
||||
|
|
@ -183,13 +188,13 @@ The [default baud rate](https://github.com/espressif/esptool#baud-rate) is 11520
|
|||
|
||||
More details available on esptool.py GitHub repo.
|
||||
|
||||
[↑ back to matrix](#task-os-selector)
|
||||
[↑ back to matrix](#task-and-os-selector)
|
||||
|
||||
## ESPlorer
|
||||
|
||||
TBD [https://github.com/4refr0nt/ESPlorer](https://github.com/4refr0nt/ESPlorer)
|
||||
|
||||
[↑ back to matrix](#task-os-selector)
|
||||
[↑ back to matrix](#task-and-os-selector)
|
||||
|
||||
## NodeMCU-Tool
|
||||
|
||||
|
|
@ -211,7 +216,7 @@ Quick start:
|
|||
|
||||
Note that you may need to use the `sudo` prefix to install the tool at step 2, and also possibly add the `–unsafe-perm` flag after the install command.
|
||||
|
||||
[↑ back to matrix](#task-os-selector)
|
||||
[↑ back to matrix](#task-and-os-selector)
|
||||
|
||||
## Docker
|
||||
|
||||
|
|
@ -229,7 +234,7 @@ Detailed instructions available in the image's README. As for available config o
|
|||
1. In `app/include/user_config.h` edit the line `#define LUA_FLASH_STORE 0x0` and adjust the size to that needed. Note that this must be a multiple of 4Kb.
|
||||
2. Build as you would otherwise build with this image (i.e. see its README)
|
||||
|
||||
[↑ back to matrix](#task-os-selector)
|
||||
[↑ back to matrix](#task-and-os-selector)
|
||||
|
||||
_Note that this Docker image is not an official NodeMCU offering. It's maintained by a NodeMCU team member as an individual, though._
|
||||
|
||||
|
|
@ -239,17 +244,18 @@ A local copy of `luac.cross` is only needed if you want to compile the Lua files
|
|||
|
||||
### Windows
|
||||
Windows users can compile a local copy of the `luac.cross` executable for use on a development PC. To this you need:
|
||||
- To download the current NodeMCU sources (this [dev ZIP file](https://github.com/nodemcu/nodemcu-firmware/archive/dev.zip) or [master ZIP file](https://github.com/nodemcu/nodemcu-firmware/archive/master.zip)) and unpack into a local folder, say `C:\nodemcu-firmware`; choose the master / dev versions to match the firmware version that you want to use. If you want an Integer buld then edit the `app/includes/user_config.h` file to select this.
|
||||
|
||||
- To download the current NodeMCU sources (this [dev ZIP file](https://github.com/nodemcu/nodemcu-firmware/archive/dev.zip) or [release ZIP file](https://github.com/nodemcu/nodemcu-firmware/archive/release.zip)) and unpack into a local folder, say `C:\nodemcu-firmware`; choose the master / dev versions to match the firmware version that you want to use. If you want an Integer buld then edit the `app/includes/user_config.h` file to select this.
|
||||
- Choose a preferred toolchain to build your `luac.cross` executable. You have a number of options here:
|
||||
- If you are a Windows 10 user with the Windows Subsystem for Linux (WSL) already installed, then this is a Linux environment so you can follow the [Linux build instructions](#Linux) below.
|
||||
- A less resource intensive option which works on all Windows OS variants is to use Cygwin or MinGW, which are varaint ports of the [GNU Compiler Collection](https://gcc.gnu.org/) to Windows and which can both compile to native Windows executables. In the case of Cygwin, [install Cygwin](https://www.cygwin.com/install.html) (selecting the Cygwin core + **gcc-core** + **gnu make** in the install menu). In the case of MinGW you again only need a very basic C build environment so [install the MINGW](http://mingw.org/wiki/InstallationHOWTOforMinGW); you only need the core GCC and mingw32-make. Both both these create a **Cmd** prompt which paths in the relevant GCC toolchain. Switch to the `app/lua/luac_cross` and run make to build the compiler in the NodeMCU firmware root directory. You do this by rning `make` in Cygwin and `mingw32-make -f mingw32-Makefile.mak` in MinGW.
|
||||
- If you can C development experience on the PC and a version of the MS Visual Studio on your PC then you can also simply build the image using the supplied MS project file.
|
||||
- Once you have a built `luac.cross` executable, then you can use this to compile Lua code into an LFS image. You might wish to move this out of the nodemcu-firmware hierarchy, since this folder hierarchy is no longer required and can be trashed.
|
||||
- You can also use MS Visual Studio (free community version is available). Just open the supplied MS solution file (msvc\hosttools.sln) and build it to get the Lua 5.1 luac.cross.exe file. Currently there is no sln file available for the Lua 5.3 version.
|
||||
- Once you have a built `luac.cross` executable, then you can use this to compile Lua code into an LFS image. You might wish to move it out of the nodemcu-firmware hierarchy, since this folder hierarchy is no longer required and can be removed.
|
||||
|
||||
### Linux
|
||||
|
||||
- Ensure that you have a "build essential" GCC toolchain installed.
|
||||
- Download the current NodeMCU sources (this [dev ZIP file](https://github.com/nodemcu/nodemcu-firmware/archive/dev.zip) or [master ZIP file](https://github.com/nodemcu/nodemcu-firmware/archive/master.zip)) and unpack into a local folder; choose the master / dev versions to match the firmware version that you want to use. If you want an Integer buld then edit the `app/includes/user_config.h` file to select this.
|
||||
- Download the current NodeMCU sources (this [dev ZIP file](https://github.com/nodemcu/nodemcu-firmware/archive/dev.zip) or [release ZIP file](https://github.com/nodemcu/nodemcu-firmware/archive/release.zip)) and unpack into a local folder; choose the master / dev versions to match the firmware version that you want to use. If you want an Integer buld then edit the `app/includes/user_config.h` file to select this.
|
||||
- Change directory to the `app/lua/luac_cross` sub-folder
|
||||
- Run `make` to build the executable.
|
||||
- Once you have a built `luac.cross` executable, then you can use this to compile Lua code into an LFS image. You might wish to move this out of the nodemcu-firmware hierarchy, since this folder hierarchy is no longer required and can be trashed.
|
||||
|
|
@ -258,7 +264,7 @@ Windows users can compile a local copy of the `luac.cross` executable for use on
|
|||
|
||||
As for [Linux](#linux)
|
||||
|
||||
[↑ back to matrix](#task-os-selector)
|
||||
[↑ back to matrix](#task-and-os-selector)
|
||||
|
||||
## Compile Lua into LFS image
|
||||
|
||||
|
|
@ -276,6 +282,9 @@ For example to run the Telnet and FTP servers from LFS, put the following files
|
|||
|
||||
You should always include the first two modules, but the remaining files would normally be replaced by your own project files. Also remember that these are examples and that you are entirely free to modify or to replace them for your own application needs.
|
||||
|
||||
!!! Note
|
||||
You will need to grab a luac.cross compiler that matches your configuration regarding float/integer, Lua 5.1/5.3 and possibly the release.
|
||||
|
||||
### Terry's LFS Lua Cross-Compile Web Service
|
||||
|
||||
[https://blog.ellisons.org.uk/article/nodemcu/a-lua-cross-compile-web-service/](https://blog.ellisons.org.uk/article/nodemcu/a-lua-cross-compile-web-service/)
|
||||
|
|
@ -301,7 +310,8 @@ The same Docker image you used to build the NodeMCU firmware can be used to [com
|
|||
|
||||
Note: read up on [selecting Lua files](#select-lua-files-to-be-run-from-lfs) first
|
||||
|
||||
For Windows you will do this from within the WSL / Cygwin command window, both of which use the `bash` shell.
|
||||
For Windows if you built with WSL / Cygwin you will do this from within the respective command window, both of which use the `bash` shell.
|
||||
If you used Visual Studio just use the windows cmd window.
|
||||
|
||||
1. `$ cd <project-dir>`
|
||||
1. `$ luac.cross -o lfs.img -f *.lua`
|
||||
|
|
@ -310,13 +320,13 @@ You will need to adjust the `img` and `lua` paths according to their location, a
|
|||
|
||||
You might also want to add a simple one-line script file to your `~/bin` directory to wrap this command up.
|
||||
|
||||
[↑ back to matrix](#task-os-selector)
|
||||
[↑ back to matrix](#task-and-os-selector)
|
||||
|
||||
## Upload LFS image
|
||||
|
||||
The compiled LFS image file (e.g. `lfs.img`) is uploaded as a regular file to the device file system (SPIFFS). You do this just like with Lua files with e.g. [ESPlorer](#esplorer) or [NodeMCU-Tool](#nodemcu-tool). There is also a new example, [HTTP_OTA.lua](https://github.com/nodemcu/nodemcu-firmware/tree/dev/lua_examples/lfs/HTTP_OTA.lua), in `lua_examples` that can retrieve images from a standard web service.
|
||||
|
||||
Once the LFS image file is on SPIFFS, you can execute the [node.flashreload()](../modules/node/#nodeflashreload) command and the loader will then load it into flash and immediately restart the ESP module with the new LFS loaded, if the image file is valid. However, the call will return with an error _if_ the file is found to be invalid, so your reflash code should include logic to handle such an error return.
|
||||
Once the LFS image file is on SPIFFS, you can execute the [node.flashreload()](modules/node.md#nodeflashreload) command and the loader will then load it into flash and immediately restart the ESP module with the new LFS loaded, if the image file is valid. However, the call will return with an error _if_ the file is found to be invalid, so your reflash code should include logic to handle such an error return.
|
||||
|
||||
### Edit your `init.lua` file
|
||||
|
||||
|
|
@ -325,47 +335,56 @@ Once the LFS image file is on SPIFFS, you can execute the [node.flashreload()](.
|
|||
- Individual functions can be executed directly, e.g. `LFS.myfunc(a,b)`
|
||||
- LFS is now in the require path, so `require 'myModule'` works as expected.
|
||||
|
||||
Do a protected call of this `_init` code: `pcall(node.flashindex("_init"))` and check the error status. See [Programming Techniques and Approachs](lfs.md#programming-techniques-and-approachs) in the LFS whitepaper for a more detailed description.
|
||||
Do a protected call of this `_init` code: `pcall(node.LFS._init())` and check the error status. See [Programming Techniques and Approachs](lfs.md#programming-techniques-and-approachs) in the LFS whitepaper for a more detailed description.
|
||||
|
||||
### Minimal LFS example
|
||||
|
||||
Below is a brief overview of building and running the simplest LFS-based system possible.
|
||||
|
||||
To use LFS, start with a version of NodeMCU with `LUA_FLASH_STORE` set in `app/include/user_config.h`, and load it on the ESP8266 in the usual way (whatever that is for your set up).
|
||||
To use LFS, start with a version of the NodeMCU firmware with LFS enabled. See [the matrix](#task-and-os-selector) section "Build LFS
|
||||
enabled firmware" for how to do that. Load it on the ESP8266 in the usual way (whatever that is for your set up).
|
||||
|
||||
Then build an LFS file system. This can be done in several ways, as discussed above; one of the easiest is to use `luac.cross -f -o lfs.img *lua` on the host machine. The file [lua_examples/lfs/_init.lua](https://github.com/nodemcu/nodemcu-firmware/tree/dev/lua_examples/lfs/_init.lua) should definitely be included in the image, since it's the easiest way of registering the LFS modules. The `lfs.img` file can then be downloaded to the ESP8266 just like any other file.
|
||||
Then build an LFS file system. This can be done in several ways, as discussed above; one of the easiest is to use `luac.cross -o lfs.img -f *lua` on the host machine. Make sure to include a file named `hello_world.lua` with the following one line content: `print("Hello ESP8266 world!")`
|
||||
The file [lua_examples/lfs/_init.lua](https://github.com/nodemcu/nodemcu-firmware/tree/dev/lua_examples/lfs/_init.lua) should definitely be included in the image, since it's the easiest way to integrate the LFS system. The `lfs.img` file can then be downloaded to the ESP8266 just like any other file.
|
||||
|
||||
The next step is to tell the ESP8266 that the LFS file system exists. This is done with eg. [node.flashreload("lfs.img")](../modules/node/#nodeflashreload), which will trigger a reset, followed by [node.flashindex("_init")()](../modules/node/#nodeflashindex) to register the modules; logging into the esp8266 and running the following commands gives an overview of the command sequence, given a main.lua file consisting of the line `print("LFS main() module")`
|
||||
The next step is to tell the ESP8266 that the LFS exists. This is done with [node.LFS.reload("lfs.img")](modules/node.md#nodelfsreload), which will trigger a reset, followed by [node.LFS._init()](modules/node.md#nodelfsget) to better integrate LFS; logging into the esp8266 and running the following commands gives an overview of the command sequence.
|
||||
|
||||
```
|
||||
>
|
||||
> node.flashreload("lfs.img")
|
||||
-- flashreload() triggers a reset here.
|
||||
> print(LFS)
|
||||
nil
|
||||
> node.flashindex("_init")()
|
||||
-- LFS is now initialised.
|
||||
> print(LFS)
|
||||
table: 3fff06e0
|
||||
> node.LFS.reload("lfs.img")
|
||||
-- node.LFS.reload() triggers one or two resets here.
|
||||
-- Call the LFS hello_world.
|
||||
> node.LFS.hello_world()
|
||||
Hello ESP8266 world!
|
||||
-- DONE!
|
||||
|
||||
-- now for some more insights and helpers
|
||||
-- List the modules in the LFS.
|
||||
> print(LFS._list)
|
||||
table: 3fff0728
|
||||
> for k,v in pairs(LFS._list) do print(k,v) end
|
||||
> print(node.LFS.list)
|
||||
function: 3fff0728
|
||||
> for k,v in pairs(node.LFS.list()) do print(k,v) end
|
||||
1 dummy_strings
|
||||
2 _init
|
||||
3 main
|
||||
-- Call the LFS main() module.
|
||||
> LFS.main()
|
||||
LFS main() module
|
||||
3 hello_world
|
||||
-- integrate LFS with SPIFFS
|
||||
> node.LFS._init()
|
||||
-- We now can run and load files from SPIFFS or LFS using `dofile` and `loadfile`.
|
||||
> dofile("hello_world.lua")
|
||||
Hello ESP8266 world!
|
||||
-- `require()` also works the same way now.
|
||||
-- if there was a file called "hello_world.lua" in SPIFFS the that would be executed. But if there isn't a lookup in LFS is made.
|
||||
-- _init.lua also sets a global LFS as a copy of node.LFS. This is somewhat backwards compatibility and might get removed in the future.
|
||||
> print(LFS)
|
||||
table: 3fff06e0
|
||||
>
|
||||
```
|
||||
|
||||
Note that no error correction has been used, since the commands are intended to be entered at a terminal, and errors will become obvious.
|
||||
|
||||
Then you should set up the ESP8266 boot process to check for the existence of an LFS image and run whichever module is required. Once the LFS module table has been registered by running [lua_examples/lfs/_init.lua](https://github.com/nodemcu/nodemcu-firmware/tree/dev/lua_examples/lfs/_init.lua) , running an LFS module is simple a matter of eg: `LFS.main()`.
|
||||
Then you should set up the ESP8266 boot process to check for the existence of an LFS image and run whichever module is required. Once the LFS module table has been registered by running [lua_examples/lfs/_init.lua](https://github.com/nodemcu/nodemcu-firmware/tree/dev/lua_examples/lfs/_init.lua), running an LFS module is simply a matter of eg: `LFS.hello_world()`.
|
||||
|
||||
[node.flashreload()](../modules/node/#nodeflashreload) need only be rerun if the LFS image is updated; after it has loaded the LFS image into flash memory the original file (in SPIFFS) is no longer used, and can be deleted.
|
||||
[node.LFS.reload()](modules/node.md#nodelfsreload) need only be rerun if the LFS image is updated; after it has loaded the LFS image into flash memory the original file (in SPIFFS) is no longer used, and can be deleted.
|
||||
|
||||
Once LFS is known to work, then modules such as [lua_examples/lfs/dummy_strings.lua](https://github.com/nodemcu/nodemcu-firmware/tree/dev/lua_examples/lfs/dummy_strings.lua) can usefully be added, together of course with effective error checking.
|
||||
|
||||
[↑ back to matrix](#task-os-selector)
|
||||
[↑ back to matrix](#task-and-os-selector)
|
||||
|
|
|
|||
|
|
@ -7,19 +7,20 @@ The firmware was initially developed as is a companion project to the popular ES
|
|||
→ [Getting Started](getting-started.md)
|
||||
|
||||
## 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`](https://github.com/nodemcu/nodemcu-firmware/tree/master/lua_examples) folder in the repository on GitHub.
|
||||
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`](https://github.com/nodemcu/nodemcu-firmware/tree/release/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)
|
||||
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 (DO NOT save config to flash)
|
||||
wifi.setmode(wifi.STATION)
|
||||
|
|
@ -32,12 +33,9 @@ wifi.sta.config(station_cfg)
|
|||
|
||||
```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
|
||||
wifi.eventmon.register(wifi.eventmon.STA_CONNECTED, function(T)
|
||||
print("\n\tSTA - CONNECTED".."\n\tSSID: "..T.SSID.."\n\tBSSID: "..
|
||||
T.BSSID.."\n\tChannel: "..T.channel)
|
||||
end)
|
||||
```
|
||||
|
||||
|
|
@ -56,9 +54,9 @@ In September 2018 support for a [Lua Flash Store (LFS)](lfs.md) was introduced.
|
|||
|
||||
## Releases
|
||||
|
||||
This project uses two main branches, `master` and `dev`. `dev` is actively worked on and it's also where PRs should be created against. `master` thus can be considered "stable" even though there are no automated regression tests. The goal is to merge back to `master` roughly every 2 months. Depending on the current "heat" (issues, PRs) we accept changes to `dev` for 5-6 weeks and then hold back for 2-3 weeks before the next snap is completed.
|
||||
This project uses two main branches, `release` and `dev`. `dev` is actively worked on and it's also where PRs should be created against. `release` thus can be considered "stable" even though there are no automated regression tests. The goal is to merge back to `release` roughly every 2 months. Depending on the current "heat" (issues, PRs) we accept changes to `dev` for 5-6 weeks and then hold back for 2-3 weeks before the next snap is completed.
|
||||
|
||||
A new tag is created every time `dev` is merged back to `master`. They are listed in the [releases section on GitHub](https://github.com/nodemcu/nodemcu-firmware/releases). Tag names follow the `<SDK-version>-master_yyyymmdd` pattern.
|
||||
A new tag is created every time `dev` is merged back to `release` branch. They are listed in the [releases section on GitHub](https://github.com/nodemcu/nodemcu-firmware/releases). Tag names follow the `<SDK-version>-release_yyyymmdd` pattern.
|
||||
|
||||
## Up-To-Date Documentation
|
||||
At the moment the only up-to-date documentation maintained by the current NodeMCU team is in English. It is part of the source code repository (`/docs` subfolder) and kept in sync with the code.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# BME280 module
|
||||
| Since | Origin / Contributor | Maintainer | Source |
|
||||
| :----- | :-------------------- | :---------- | :------ |
|
||||
| 2020-10-04 | [vsky279](https://github.com/vsky279) | [vsky279](https://github.com/vsky279) | [bme280.c](../../app/modules/bme280.c)|
|
||||
| 2020-10-04 | [vsky279](https://github.com/vsky279) | [vsky279](https://github.com/vsky279) | [bme280.lua](../../lua_modules/bme280/bme280.lua)|
|
||||
|
||||
This module communicates with [BME280/BMP280 temperature/air presssure/humidity sensors](http://www.bosch-sensortec.com/bst/products/all_products/bme280) (Bosch Sensortec) through [I2C](../modules/i2c.md) interface.
|
||||
|
||||
|
|
|
|||
|
|
@ -76,8 +76,8 @@ It configures I²C backend and returns backend object.
|
|||
In most cases only `sda` and `scl` parameters are required
|
||||
|
||||
#### Parameters
|
||||
- `sda`: I²C data pin. If set to `nil`, I²C bus initialization step via [`i2c.setup`](https://nodemcu.readthedocs.io/en/master/modules/i2c/#i2csetup) will be skipped
|
||||
- `scl`: I²C clock pin. If set to `nil`, I²C bus initialization step via [`i2c.setup`](https://nodemcu.readthedocs.io/en/master/modules/i2c/#i2csetup) will be skipped
|
||||
- `sda`: I²C data pin. If set to `nil`, I²C bus initialization step via [`i2c.setup`](https://nodemcu.readthedocs.io/en/release/modules/i2c/#i2csetup) will be skipped
|
||||
- `scl`: I²C clock pin. If set to `nil`, I²C bus initialization step via [`i2c.setup`](https://nodemcu.readthedocs.io/en/release/modules/i2c/#i2csetup) will be skipped
|
||||
- `busid`: I²C bus ID. Defaults to `0`
|
||||
- `busad`: chip I²C address. Defaults to `0x27` (default PCF8574 address)
|
||||
- `speed`: I²C speed. Defaults to `i2c.SLOW`
|
||||
|
|
|
|||
|
|
@ -244,7 +244,7 @@ The Lua public API has largely been preserved across both Lua versions. Having
|
|||
- NodeMCU features that were in Lua51 and have also been added to Lua53 as part of this migration.
|
||||
- Differences (additions / removals / API changes) that we are not using in our modules and which can therefore be effectively ignored for the purposes of migration.
|
||||
- Some very nice feature enhancements in Lua53, for example the table access functions are now type `int` instead of type `void` and return the type of the accessed TValue. These features have been back-ported to Lua51 so that modules can be coded using Lua53 best practice and still work in a Lua51 runtime environment.
|
||||
- Source differences which can be encapsulated through common macros will be be removed by updating module code to use this common macro set. In a very small number of cases module functionality will be recoded to employ this common API base.
|
||||
- Source differences which can be encapsulated through common macros will be removed by updating module code to use this common macro set. In a very small number of cases module functionality will be recoded to employ this common API base.
|
||||
|
||||
Both the LRM and PiL make quite clear that the public API for C modules is as documented in `lua.h` and all its definitions start with `lua_`. This API strives for economy and orthogonality. The supplementary functions provided by the auxiliary library (`lauxlib.c`) access Lua services and functions through the `lua.h` interface and without other reference to the internals of Lua; this is exposed through `lauxlib.h` and all its definitions start with `luaL_`. All Lua library modules (such as `lstrlib.c` which implements `string`) conform to this policy and only access the Lua runtime via the `lua.h` and `lauxlib.h` interfaces.
|
||||
|
||||
|
|
|
|||
|
|
@ -56,7 +56,7 @@ Determines whether the specified file exists.
|
|||
- `filename` file to check
|
||||
|
||||
#### Returns
|
||||
true of the file exists (even if 0 bytes in size), and false if it does not exist
|
||||
true if the file exists (even if 0 bytes in size), and false if it does not exist
|
||||
|
||||
#### Example
|
||||
|
||||
|
|
|
|||
|
|
@ -358,7 +358,7 @@ srv:on("receive", function(sck, c)
|
|||
end
|
||||
end)
|
||||
-- throttling could be implemented using socket:hold()
|
||||
-- example: https://github.com/nodemcu/nodemcu-firmware/blob/master/lua_examples/pcm/play_network.lua#L83
|
||||
-- example: https://github.com/nodemcu/nodemcu-firmware/blob/release/lua_examples/pcm/play_network.lua#L83
|
||||
```
|
||||
|
||||
#### See also
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@ All other pins can be assigned to any available GPIO:
|
|||
* D/C
|
||||
* RES (optional for some displays)
|
||||
|
||||
Also refer to the initialization sequence eg in [GraphicsTest.lua](https://github.com/nodemcu/nodemcu-firmware/blob/master/lua_examples/ucglib/GraphicsTest.lua):
|
||||
Also refer to the initialization sequence eg in [GraphicsTest.lua](https://github.com/nodemcu/nodemcu-firmware/blob/release/lua_examples/ucglib/GraphicsTest.lua):
|
||||
```lua
|
||||
spi.setup(1, spi.MASTER, spi.CPOL_LOW, spi.CPHA_LOW, 8, 8)
|
||||
```
|
||||
|
|
@ -83,7 +83,7 @@ disp = ucg.ili9341_18x240x320_hw_spi(cs, dc, res)
|
|||
```
|
||||
|
||||
This object provides all of ucglib's methods to control the display.
|
||||
Again, refer to [GraphicsTest.lua](https://github.com/nodemcu/nodemcu-firmware/blob/master/lua_examples/ucglib/GraphicsTest.lua) to get an impression how this is achieved with Lua code. Visit the [ucglib homepage](https://github.com/olikraus/ucglib) for technical details.
|
||||
Again, refer to [GraphicsTest.lua](https://github.com/nodemcu/nodemcu-firmware/blob/release/lua_examples/ucglib/GraphicsTest.lua) to get an impression how this is achieved with Lua code. Visit the [ucglib homepage](https://github.com/olikraus/ucglib) for technical details.
|
||||
|
||||
### Display selection
|
||||
HW SPI based displays with support in u8g2 can be enabled.
|
||||
|
|
|
|||
|
|
@ -1603,46 +1603,46 @@ T: Table returned by event.
|
|||
#### Example
|
||||
|
||||
```lua
|
||||
wifi.eventmon.register(wifi.eventmon.STA_CONNECTED, function(T)
|
||||
print("\n\tSTA - CONNECTED".."\n\tSSID: "..T.SSID.."\n\tBSSID: "..
|
||||
T.BSSID.."\n\tChannel: "..T.channel)
|
||||
end)
|
||||
wifi.eventmon.register(wifi.eventmon.STA_CONNECTED, function(T)
|
||||
print("\n\tSTA - CONNECTED".."\n\tSSID: "..T.SSID.."\n\tBSSID: "..
|
||||
T.BSSID.."\n\tChannel: "..T.channel)
|
||||
end)
|
||||
|
||||
wifi.eventmon.register(wifi.eventmon.STA_DISCONNECTED, function(T)
|
||||
print("\n\tSTA - DISCONNECTED".."\n\tSSID: "..T.SSID.."\n\tBSSID: "..
|
||||
T.BSSID.."\n\treason: "..T.reason)
|
||||
end)
|
||||
wifi.eventmon.register(wifi.eventmon.STA_DISCONNECTED, function(T)
|
||||
print("\n\tSTA - DISCONNECTED".."\n\tSSID: "..T.SSID.."\n\tBSSID: "..
|
||||
T.BSSID.."\n\treason: "..T.reason)
|
||||
end)
|
||||
|
||||
wifi.eventmon.register(wifi.eventmon.STA_AUTHMODE_CHANGE, function(T)
|
||||
print("\n\tSTA - AUTHMODE CHANGE".."\n\told_auth_mode: "..
|
||||
T.old_auth_mode.."\n\tnew_auth_mode: "..T.new_auth_mode)
|
||||
end)
|
||||
wifi.eventmon.register(wifi.eventmon.STA_AUTHMODE_CHANGE, function(T)
|
||||
print("\n\tSTA - AUTHMODE CHANGE".."\n\told_auth_mode: "..
|
||||
T.old_auth_mode.."\n\tnew_auth_mode: "..T.new_auth_mode)
|
||||
end)
|
||||
|
||||
wifi.eventmon.register(wifi.eventmon.STA_GOT_IP, function(T)
|
||||
print("\n\tSTA - GOT IP".."\n\tStation IP: "..T.IP.."\n\tSubnet mask: "..
|
||||
T.netmask.."\n\tGateway IP: "..T.gateway)
|
||||
end)
|
||||
wifi.eventmon.register(wifi.eventmon.STA_GOT_IP, function(T)
|
||||
print("\n\tSTA - GOT IP".."\n\tStation IP: "..T.IP.."\n\tSubnet mask: "..
|
||||
T.netmask.."\n\tGateway IP: "..T.gateway)
|
||||
end)
|
||||
|
||||
wifi.eventmon.register(wifi.eventmon.STA_DHCP_TIMEOUT, function()
|
||||
print("\n\tSTA - DHCP TIMEOUT")
|
||||
end)
|
||||
wifi.eventmon.register(wifi.eventmon.STA_DHCP_TIMEOUT, function()
|
||||
print("\n\tSTA - DHCP TIMEOUT")
|
||||
end)
|
||||
|
||||
wifi.eventmon.register(wifi.eventmon.AP_STACONNECTED, function(T)
|
||||
print("\n\tAP - STATION CONNECTED".."\n\tMAC: "..T.MAC.."\n\tAID: "..T.AID)
|
||||
end)
|
||||
wifi.eventmon.register(wifi.eventmon.AP_STACONNECTED, function(T)
|
||||
print("\n\tAP - STATION CONNECTED".."\n\tMAC: "..T.MAC.."\n\tAID: "..T.AID)
|
||||
end)
|
||||
|
||||
wifi.eventmon.register(wifi.eventmon.AP_STADISCONNECTED, function(T)
|
||||
print("\n\tAP - STATION DISCONNECTED".."\n\tMAC: "..T.MAC.."\n\tAID: "..T.AID)
|
||||
end)
|
||||
wifi.eventmon.register(wifi.eventmon.AP_STADISCONNECTED, function(T)
|
||||
print("\n\tAP - STATION DISCONNECTED".."\n\tMAC: "..T.MAC.."\n\tAID: "..T.AID)
|
||||
end)
|
||||
|
||||
wifi.eventmon.register(wifi.eventmon.AP_PROBEREQRECVED, function(T)
|
||||
print("\n\tAP - PROBE REQUEST RECEIVED".."\n\tMAC: ".. T.MAC.."\n\tRSSI: "..T.RSSI)
|
||||
end)
|
||||
wifi.eventmon.register(wifi.eventmon.AP_PROBEREQRECVED, function(T)
|
||||
print("\n\tAP - PROBE REQUEST RECEIVED".."\n\tMAC: ".. T.MAC.."\n\tRSSI: "..T.RSSI)
|
||||
end)
|
||||
|
||||
wifi.eventmon.register(wifi.eventmon.WIFI_MODE_CHANGED, function(T)
|
||||
print("\n\tSTA - WIFI MODE CHANGED".."\n\told_mode: "..
|
||||
T.old_mode.."\n\tnew_mode: "..T.new_mode)
|
||||
end)
|
||||
wifi.eventmon.register(wifi.eventmon.WIFI_MODE_CHANGED, function(T)
|
||||
print("\n\tSTA - WIFI MODE CHANGED".."\n\told_mode: "..
|
||||
T.old_mode.."\n\tnew_mode: "..T.new_mode)
|
||||
end)
|
||||
```
|
||||
#### See also
|
||||
- [`wifi.eventmon.unregister()`](#wifieventmonunregister)
|
||||
|
|
@ -1655,7 +1655,7 @@ Unregister callbacks for WiFi event monitor.
|
|||
wifi.eventmon.unregister(Event)
|
||||
|
||||
#### Parameters
|
||||
Event: WiFi event you would like to set a callback for.
|
||||
Event: WiFi event you would like to remove the callback for.
|
||||
|
||||
- Valid WiFi events:
|
||||
- wifi.eventmon.STA_CONNECTED
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ handle two led strips at the same time.
|
|||
**WARNING**: In dual mode, you will loose access to the Lua's console
|
||||
through the serial port (it will be reconfigured to support WS2812-like
|
||||
protocol). If you want to keep access to Lua's console, you will have to
|
||||
use an other input channel like a TCP server (see [example](https://github.com/nodemcu/nodemcu-firmware/blob/master/lua_examples/telnet/telnet.lua))
|
||||
use an other input channel like a TCP server (see [example](https://github.com/nodemcu/nodemcu-firmware/blob/release/lua_modules/telnet/telnet.lua))
|
||||
|
||||
## ws2812.init()
|
||||
Initialize UART1 and GPIO2, should be called once and before write().
|
||||
|
|
|
|||
|
|
@ -130,10 +130,10 @@ function bme280_startreadout(self, callback, delay, alt)
|
|||
delay = delay or BME280_SAMPLING_DELAY
|
||||
|
||||
if self._isbme then write_reg(self.id, self.addr, BME280_REGISTER_CONTROL_HUM, self._config[2]) end
|
||||
write_reg(self.id, self.addr, BME280_REGISTER_CONTROL, 4*math_floor(self._config[3]:byte(1)/4)+ 1)
|
||||
write_reg(self.id, self.addr, BME280_REGISTER_CONTROL, 4*math_floor(self._config[3]:byte(1)/4)+ 1) -- LUA51
|
||||
-- 4*math_floor(self._config[3]:byte(1)/4)+ 1
|
||||
-- an awful way to avoid bit operations but calculate (config[3] & 0xFC) | BME280_FORCED_MODE
|
||||
-- Lua 5.3 integer division // would be more suitable
|
||||
-- Lua 5.3: write_reg(self.id, self.addr, BME280_REGISTER_CONTROL, (self._config[3]:byte(1) & 0xFC) | 1)
|
||||
|
||||
tmr_create():alarm(delay, tmr_ALARM_SINGLE,
|
||||
function()
|
||||
|
|
|
|||
Loading…
Reference in New Issue