Commit b126c6b2 authored by Marcel Stör's avatar Marcel Stör
Browse files

Re-organize documentation

Drop support for localized content, #2213

Restructure some content to match more closely what we have in master, #2542
parent 87b3ffa6
......@@ -37,23 +37,14 @@ Run the following command to flash an *aggregated* binary as is produced for exa
### NodeMCU PyFlasher
> Self-contained [NodeMCU](https://github.com/nodemcu/nodemcu-firmware) flasher with GUI based on [esptool.py](https://github.com/espressif/esptool) and [wxPython](https://www.wxpython.org/).
![NodeMCU PyFlasher](../img/NodeMCU-PyFlasher.png "NodeMCU PyFlasher")
![NodeMCU PyFlasher](img/NodeMCU-PyFlasher.png "NodeMCU PyFlasher")
Source: [https://github.com/marcelstoer/nodemcu-pyflasher](https://github.com/marcelstoer/nodemcu-pyflasher)
Supported platforms: anything that runs Python, runnable .exe available for Windows and .dmg for macOS
Supported platforms: anything that runs Python, runnable `.exe` available for Windows and `.dmg` for macOS
Disclaimer: the availability of [NodeMCU PyFlasher was announced on the NodeMCU Facebook page](https://www.facebook.com/NodeMCU/posts/663197460515251) but it is not an official offering of the current NodeMCU firmware team.
### NodeMCU Flasher
> A firmware Flash tool for NodeMCU...We are working on next version and will use QT framework. It will be cross platform and open-source.
Source: [https://github.com/nodemcu/nodemcu-flasher](https://github.com/nodemcu/nodemcu-flasher)
Supported platforms: Windows
Note that this tool was created by the initial developers of the NodeMCU firmware. **It hasn't seen updates since September 2015** and is not maintained by the current NodeMCU *firmware* team. Be careful to not accidentally flash the very old default firmware the tool is shipped with.
## Putting Device Into Flash Mode
To enable ESP8266 firmware flashing GPIO0 pin must be pulled low before the device is reset. Conversely, for a normal boot, GPIO0 must be pulled high or floating.
......
......@@ -325,4 +325,4 @@ Once the LFS image file is on SPIFFS, you can execute the [node.flashreload()](.
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.
[↑ back to matrix](#task-os-selector)
\ No newline at end of file
[↑ back to matrix](#task-os-selector)
# NodeMCU Documentation
NodeMCU is an open source [Lua](https://www.lua.org/) based firmware for the [ESP8266 WiFi SOC from Espressif](http://espressif.com/en/products/esp8266/) and uses an on-module flash-based [SPIFFS](https://github.com/pellepl/spiffs) file system. NodeMCU is implemented in C and is layered on the [Espressif NON-OS SDK](https://github.com/espressif/ESP8266_NONOS_SDK).
NodeMCU is an open source [Lua](https://www.lua.org/) based firmware for the [ESP8266 WiFi SOC from Espressif](http://espressif.com/products/esp8266/) and uses an on-module flash-based [SPIFFS](https://github.com/pellepl/spiffs) file system. NodeMCU is implemented in C and is layered on the [Espressif NON-OS SDK](https://github.com/espressif/ESP8266_NONOS_SDK).
The firmware was initially developed as is a companion project to the popular ESP8266-based [NodeMCU development modules](https://github.com/nodemcu/nodemcu-devkit-v1.0), but the project is now community-supported, and the firmware can now be run on _any_ ESP module.
[Getting Started](en/getting-started.md)
[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.
......@@ -45,10 +45,10 @@ gpio.write(pin, gpio.HIGH)
print(gpio.read(pin))
```
[Getting Started](en/getting-started.md)
[Getting Started](getting-started.md)
## Lua Flash Store (LFS)
In September 2018 support for a [Lua Flash Store (LFS)](en/lfs.md) was introduced. LFS allows Lua code and its associated constant data to be executed directly out of flash-memory; just as the firmware itself is executed. This now enables NodeMCU developers to create Lua applications with up to 256Kb Lua code and read-only constants executing out of flash. All of the RAM is available for read-write data!
In September 2018 support for a [Lua Flash Store (LFS)](lfs.md) was introduced. LFS allows Lua code and its associated constant data to be executed directly out of flash-memory; just as the firmware itself is executed. This now enables NodeMCU developers to create Lua applications with up to 256Kb Lua code and read-only constants executing out of flash. All of the RAM is available for read-write data!
## Releases
......@@ -57,4 +57,4 @@ This project uses two main branches, `master` and `dev`. `dev` is actively worke
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.
## 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.
\ No newline at end of file
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.
var nodemcu = nodemcu || {};
(function () {
'use strict';
//var languageCodeToNameMap = {en: 'English', de: 'Deutsch'};
var languageCodeToNameMap = {en: 'English'};
var languageNames = values(languageCodeToNameMap);
var defaultLanguageCode = 'en';
$(document).ready(function () {
addToc();
hideNavigationForAllButSelectedLanguage();
addLanguageSelectorToRtdFlyOutMenu();
replaceRelativeLinksWithStaticGitHubUrl();
});
......@@ -45,75 +38,13 @@ var nodemcu = nodemcu || {};
}
}
function hideNavigationForAllButSelectedLanguage() {
var selectedLanguageCode = determineSelectedLanguageCode();
var selectedLanguageName = languageCodeToNameMap[selectedLanguageCode];
// Finds all subnav elements and hides them if they're /language/ subnavs. Hence, all 'Modules' subnav elements
// won't be hidden.
// <ul class="subnav">
// <li><span>Modules</span></li>
// <li class="toctree-l1 ">
// <a class="" href="EN/modules/node/">node</a>
// </li>
$('.subnav li span').not(':contains(' + selectedLanguageName + ')').each(function (index) {
var spanElement = $(this);
if ($.inArray(spanElement.text(), languageNames) > -1) {
spanElement.parent().parent().hide();
}
});
}
/**
* Adds a language selector to the RTD fly-out menu found bottom left. Example:
*
* <dl>
* <dt>Languages</dt>
* <dd><a href="http://nodemcu.readthedocs.io/en/<branch>/de/">de</a></dd>
* <strong>
* <dd><a href="http://nodemcu.readthedocs.io/en/<branch>/en/">en</a></dd>
* </strong>
* </dl>
*
* UGLY! That fly-out menu is added by RTD with an AJAX call after page load. Hence, we need to
* react to the subsequent DOM manipulation using a DOM4 MutationObserver. The provided structure
* is as follows:
*
* <div class="rst-other-versions">
* <!-- Inserted RTD Footer -->
* <div class="injected">
*/
function addLanguageSelectorToRtdFlyOutMenu() {
var flyOutWrapper = $('.rst-other-versions');
// only relevant on RTD
if (flyOutWrapper.size() > 0) {
var observer = new MutationObserver(function (mutations) {
// since mutation on the target node was triggered we can safely assume the injected RTD div has now been added
var injectedDiv = $('.rst-other-versions .injected');
var selectedLanguageCode = determineSelectedLanguageCode();
var dl = document.createElement('dl');
var dt = document.createElement('dt');
dl.appendChild(dt);
dt.appendChild(document.createTextNode('Languages'));
for (var languageCode in languageCodeToNameMap) {
dl.appendChild(createLanguageLinkFor(languageCode, selectedLanguageCode === languageCode));
}
injectedDiv.prepend(dl);
// no need for that observer anymore
observer.disconnect();
});
// observed target node is the fly-out wrapper, the only event we care about is when children are modified
observer.observe(flyOutWrapper[0], {childList: true});
}
}
/**
* The module doc pages contain relative links to artifacts in the GitHub repository. For those links to work both
* on GitHub (i.e. when the page is viewed on GitHub) and on RTD they are defined with a relative URL. This function
* replaces the relative path with an absolute path based on the selected branch.
*/
function replaceRelativeLinksWithStaticGitHubUrl() {
var relativePath = isOnRtd() ? "../../../.." : "../../..";
var relativePath = isOnRtd() ? "../../.." : "../..";
var gitHubPath = "https://github.com/nodemcu/nodemcu-firmware/tree/" + determineSelectedBranch();
var gitHubLinks = $("a[href^='" + relativePath + "']").each(function (index) {
var url = $(this).attr('href');
......@@ -121,48 +52,6 @@ var nodemcu = nodemcu || {};
});
}
function createLanguageLinkFor(languageCode, isCurrentlySelected) {
var strong;
// split[0] is an '' because the path starts with the separator
var pathSegments = window.location.pathname.split('/');
var dd = document.createElement("dd");
var href = document.createElement("a");
href.setAttribute('href', '/' + pathSegments[1] + '/' + pathSegments[2] + '/' + languageCode);
href.appendChild(document.createTextNode(languageCode));
dd.appendChild(href);
if (isCurrentlySelected) {
strong = document.createElement("strong");
strong.appendChild(dd);
return strong;
} else {
return dd;
}
}
/**
* Analyzes the URL of the current page to find out what the selected language is. It's usually
* part of the location path. The code needs to distinguish between running MkDocs standalone
* and docs served from RTD. If no valid language could be determined the default language is
* returned.
*
* @returns 2-char language code
*/
function determineSelectedLanguageCode() {
var selectedLanguageCode, path = window.location.pathname;
if (isOnRtd()) {
// path is like /en/<branch>/<lang>/build/ -> extract 'lang'
// split[0] is an '' because the path starts with the separator
selectedLanguageCode = path.split('/')[3];
} else if (!window.location.href.startsWith('file://')) {
// path is like /<lang>/build/ -> extract 'lang'
selectedLanguageCode = path.substr(1, 2);
}
if (!selectedLanguageCode || selectedLanguageCode.length > 2) {
selectedLanguageCode = defaultLanguageCode;
}
return selectedLanguageCode;
}
/**
* Analyzes the URL of the current page to find out what the selected GitHub branch is. It's usually
* part of the location path. The code needs to distinguish between running MkDocs standalone
......
# BH1750 Module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2015-01-30 | [Martin Han](https://github.com/MarsTechHAN) | [Martin Han](https://github.com/MarsTechHAN) | [bh1750.lua](../../../lua_modules/bh1750/bh1750.lua) |
| 2015-01-30 | [Martin Han](https://github.com/MarsTechHAN) | [Martin Han](https://github.com/MarsTechHAN) | [bh1750.lua](../../lua_modules/bh1750/bh1750.lua) |
This Lua module provides access to [BH1750](https://www.mouser.com/ds/2/348/bh1750fvi-e-186247.pdf) I²C ambient light sensor.
......@@ -70,4 +70,4 @@ print("lux: "..(l / 100).."."..(l % 100).." lx")
-- release module
bh1750 = nil
package.loaded["bh1750"] = nil
```
\ No newline at end of file
```
# DS18B20 Module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2014-12-08 | [Huang Rui](https://github.com/vowstar) | [Huang Rui](https://github.com/vowstar) | [ds18b20.lua](../../../lua_modules/ds18b20/ds18b20.lua) |
| 2014-12-08 | [Huang Rui](https://github.com/vowstar) | [Huang Rui](https://github.com/vowstar) | [ds18b20.lua](../../lua_modules/ds18b20/ds18b20.lua) |
This Lua module provides access to [DS18B20](https://datasheets.maximintegrated.com/en/ds/DS18B20.pdf) 1-Wire digital thermometer.
......@@ -75,4 +75,4 @@ A table with sensors present on the bus. It includes its address (8 bytes) and i
A table with readout values (also passed as a parameter to callback function). It is addressed by sensor addresses.
#### Notes
Other examples of using this module can be found in [ds18b20-example.lua](../../../lua_modules/ds18b20/ds18b20-example.lua) and [ds18b20-web.lua](../../../lua_modules/ds18b20/ds18b20-web.lua) files.
\ No newline at end of file
Other examples of using this module can be found in [ds18b20-example.lua](../../lua_modules/ds18b20/ds18b20-example.lua) and [ds18b20-web.lua](../../lua_modules/ds18b20/ds18b20-web.lua) files.
# DS3231 Module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2015-01-19 | [Tobie Booth](https://github.com/tobiebooth) | [Tobie Booth](https://github.com/tobiebooth) | [ds3231.lua](../../../lua_modules/ds3231/ds3231.lua) |
| 2015-01-19 | [Tobie Booth](https://github.com/tobiebooth) | [Tobie Booth](https://github.com/tobiebooth) | [ds3231.lua](../../lua_modules/ds3231/ds3231.lua) |
This Lua module provides access to [DS3231](https://datasheets.maximintegrated.com/en/ds/DS3231.pdf) I²C real-time clock.
......@@ -299,4 +299,4 @@ package.loaded["ds3231"] = nil
```
#### Notes
Other examples of using this module can be found in [ds3231-example.lua](../../../lua_modules/ds3231/ds3231-example.lua) and [ds3231-web.lua](../../../lua_modules/ds3231/ds3231-web.lua) files.
\ No newline at end of file
Other examples of using this module can be found in [ds3231-example.lua](../../lua_modules/ds3231/ds3231-example.lua) and [ds3231-web.lua](../../lua_modules/ds3231/ds3231-web.lua) files.
# FTPServer Module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2018-07-02 | [Terry Ellison](https://github.com/TerryE) | [Terry Ellison](https://github.com/TerryE) | [ftpserver.lua](../../../lua_modules/ftp/ftpserver.lua) |
| 2018-07-02 | [Terry Ellison](https://github.com/TerryE) | [Terry Ellison](https://github.com/TerryE) | [ftpserver.lua](../../lua_modules/ftp/ftpserver.lua) |
This Lua module implementation provides a basic FTP server for the ESP8266. It has been tested against a number of Table, Windows and Linux FTP clients and browsers.
......@@ -12,7 +12,7 @@ It provides a limited subset of FTP commands that enable such clients to transfe
### Limitations
- FTP over SSH or TLS is not currently supported so transfer is unencrypted.
- The client session , must, authentical against a single user/password.
- The client session , must, authenticate against a single user/password.
- Only the SPIFFS filesystem is currently supported, so changing directories is treated as a NO-OP.
- This implementation has been optimized for running in LFS.
- Only PASV mode is supported as the `net` module does not allow static allocation of outbound sockets.
......@@ -85,4 +85,4 @@ None
#### Example
```Lua
FTP.close()
```
\ No newline at end of file
```
# HDC1000 Module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2015-03-07 | [Francesco Truzzi](https://github.com/ftruzzi) | [Francesco Truzzi](https://github.com/ftruzzi) | [hdc1000.lua](../../../lua_modules/hdc1000/HDC1000.lua) |
| 2015-03-07 | [Francesco Truzzi](https://github.com/ftruzzi) | [Francesco Truzzi](https://github.com/ftruzzi) | [hdc1000.lua](../../lua_modules/hdc1000/HDC1000.lua) |
This Lua module provides access to [HDC1000](https://www.ti.com/lit/ds/symlink/hdc1000.pdf) I²C digital humidity and temperature sensor. It should also work with HDC1008 sensor bout this haven't been tested.
......@@ -105,4 +105,4 @@ print(string.format("Temperature: %.2f °C\nHumidity: %.2f %%", HDC1000.getTemp(
HDC1000 = nil
package.loaded["HDC1000"] = nil
```
\ No newline at end of file
```
# HTTP Server Module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2015-01-19 | [Vladimir Dronnikov](https://github.com/dvv) | [Vladimir Dronnikov](https://github.com/dvv) | [http.lua](../../../lua_modules/http/http.lua) |
| 2015-01-19 | [Vladimir Dronnikov](https://github.com/dvv) | [Vladimir Dronnikov](https://github.com/dvv) | [http.lua](../../lua_modules/http/httpserver.lua) |
This Lua module provides a simple callback implementation of a [HTTP 1.1](https://www.w3.org/Protocols/rfc2616/rfc2616.html) server.
......@@ -51,4 +51,4 @@ The second object holds functions:
- `send_header(self, header_name, header_data)`: Function to send HTTP headers to client. `self` is `req` object, `header_name` is HTTP header name and `header_data` is HTTP header data for client.
- `finish([data])`: Function to finalize connection, optionally sending data. `data` is optional data to send on connection finalizing.
Full example can be found in [http-example.lua](../../../lua_modules/http/http-example.lua)
\ No newline at end of file
Full example can be found in [http-example.lua](../../lua_modules/http/http-example.lua)
# IMAP Module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2015-03-12 | [AllAboutEE](https://github.com/AllAboutEE) | [AllAboutEE](https://github.com/AllAboutEE) | [imap.lua](../../../lua_modules/email/imap.lua) |
| 2015-03-12 | [AllAboutEE](https://github.com/AllAboutEE) | [AllAboutEE](https://github.com/AllAboutEE) | [imap.lua](../../lua_modules/email/imap.lua) |
This Lua module provides a simple implementation of an [IMAP 4rev1](http://www.faqs.org/rfcs/rfc2060.html) protocol that can be used to read e-mails.
......@@ -145,4 +145,4 @@ Sends the IMAP command to logout of the email session.
`nil`
#### Example
Example use of `imap` module can be found in [read_email_imap.lua](../../../lua_examples/email/read_email_imap.lua) file.
\ No newline at end of file
Example use of `imap` module can be found in [read_email_imap.lua](../../lua_examples/email/read_email_imap.lua) file.
# LM92 Module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2015-05-17 | [Levente Tamas](https://github.com/elgarbe) | [Levente Tamas](https://github.com/elgarbe) | [lm92.lua](../../../lua_modules/lm92/lm92.lua) |
| 2015-05-17 | [Levente Tamas](https://github.com/elgarbe) | [Levente Tamas](https://github.com/elgarbe) | [lm92.lua](../../lua_modules/lm92/lm92.lua) |
This Lua module provides access to [LM92](http://www.ti.com/lit/ds/symlink/lm92.pdf) I²C ±0.33C 12bit+sign temperature sensor.
......@@ -204,4 +204,4 @@ print("Got High: "..t.." C")
```
#### TODO:
- add full support of the features, including interrupt and critical alert support
\ No newline at end of file
- add full support of the features, including interrupt and critical alert support
# MCP23008 Module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2015-03-02 | [AllAboutEE](https://github.com/AllAboutEE) | [AllAboutEE](https://github.com/AllAboutEE) | [mcp23008.lua](../../../lua_modules/mcp23008/mcp23008.lua) |
| 2015-03-02 | [AllAboutEE](https://github.com/AllAboutEE) | [AllAboutEE](https://github.com/AllAboutEE) | [mcp23008.lua](../../lua_modules/mcp23008/mcp23008.lua) |
This Lua module provides access to [MCP23008](http://ww1.microchip.com/downloads/en/DeviceDoc/21919e.pdf) I²C I/O Expander.
......@@ -110,4 +110,4 @@ None
The GPPU byte i.e. state of all internal pull-up resistors
#### Notes
Other examples of using this module can be found in [mcp23008_buttons.lua](../../../lua_examples/mcp23008/mcp23008_buttons.lua) and [mcp23008_leds.lua](../../../lua_examples/mcp23008/mcp23008_leds.lua) files.
\ No newline at end of file
Other examples of using this module can be found in [mcp23008_buttons.lua](../../lua_examples/mcp23008/mcp23008_buttons.lua) and [mcp23008_leds.lua](../../lua_examples/mcp23008/mcp23008_leds.lua) files.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment