Browse Source

Doc fixes (#3333)

Gregor Hartmann 3 years ago
parent
commit
63d82131a7

+ 3 - 3
CONTRIBUTING.md

@@ -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.

+ 11 - 11
README.md

@@ -2,8 +2,8 @@
 
 [![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-master-yellow.svg?style=flat)](http://nodemcu.readthedocs.io/en/master/)
-[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](https://github.com/nodemcu/nodemcu-firmware/blob/master/LICENSE)
+[![Documentation Status](https://img.shields.io/badge/docs-release-yellow.svg?style=flat)](http://nodemcu.readthedocs.io/en/release/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](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)

+ 2 - 2
docs/build.md

@@ -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 ....

File diff suppressed because it is too large
+ 16 - 10
docs/getting-started.md


+ 12 - 14
docs/index.md

@@ -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 - 1
docs/lua-modules/bme280.md

@@ -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. 
 

+ 2 - 2
docs/lua-modules/liquidcrystal.md

@@ -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`

File diff suppressed because it is too large
+ 1 - 1
docs/lua53.md


+ 1 - 1
docs/modules/file.md

@@ -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
 

+ 1 - 1
docs/modules/net.md

@@ -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

+ 2 - 2
docs/modules/ucg.md

@@ -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.

+ 41 - 41
docs/modules/wifi.md

@@ -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_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_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.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_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.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_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_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_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.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

+ 1 - 1
docs/modules/ws2812.md

@@ -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().

+ 2 - 2
lua_modules/bme280/bme280.lua

@@ -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()

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