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

Re-organize documentation

Drops support for localized content, #2213

Restructure some content to match more closely what we have in master, #2542
parent f03a8e45
......@@ -11,4 +11,4 @@ NodeMCU "application developers" just need a ready-made firmware. There's a [clo
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.
## 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.
\ No newline at end of file
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.
# NodeMCU Dokumentation
NodeMCU ist eine [eLua](http://www.eluaproject.net/)-basierende firmware für den [ESP8266 WiFi SOC von Espressif](http://espressif.com/en/products/esp8266/). Dies ist ein Partnerprojekt für die beliebten [NodeMCU dev kits](https://github.com/nodemcu/nodemcu-devkit-v1.0) - open source NodeMCU boards mit ESP8266-12E chips.
Diese firmware nutzt das Espressif NON-OS SDK, das Dateisystem basiert auf [spiffs](https://github.com/pellepl/spiffs).
# 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 firmware is based on the Espressif NON-OS SDK 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.
## 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` 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.setmode(wifi.STATION)
wifi.sta.config("SSID", "password")
```
```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
end)
```
```lua
-- manipulate hardware like with Arduino
pin = 1
gpio.mode(pin, gpio.OUTPUT)
gpio.write(pin, gpio.HIGH)
print(gpio.read(pin))
```
## Getting Started
1. [Build the firmware](build.md) with the modules you need.
1. [Flash the firmware](flash.md) to the chip.
1. [Upload code](upload.md) to the firmware.
# Getting started
## Obtain the firmware
[Build the firmware](build.html) or download it from ?
## Flash the firmware
There are a number of tools for flashing the firmware.
# NodeMCU Documentation
!!! attention
This branch is frozen at the last commit before the Espressif SDK was upgraded to 2.0!
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 [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.
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.
## Up-To-Date Documentation
At the moment the only up-to-date documentation maintained by the current NodeMCU team is in [English](en/index.md). It is part of the source code repository (`/docs` subfolder) and kept in sync with the code.
## 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.
```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.setmode(wifi.STATION)
wifi.sta.config("SSID", "password")
```
```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
end)
```
We encourage you to help transferring the outdated translations (see below) into the repository.
```lua
-- manipulate hardware like with Arduino
pin = 1
gpio.mode(pin, gpio.OUTPUT)
gpio.write(pin, gpio.HIGH)
print(gpio.read(pin))
```
## Outdated And Sparse Documentation
The following translations are based on outdated documentation, use them with caution. The links point to the [NodeMCU wiki on GitHub](https://github.com/nodemcu/nodemcu-firmware/wiki).
## Releases
- Chinese, [中文](https://github.com/nodemcu/nodemcu-firmware/wiki/nodemcu_api_cn)
- Russian, [русский](https://github.com/nodemcu/nodemcu-firmware/wiki/nodemcu_api_ru)
- Spanish, [español](https://github.com/nodemcu/nodemcu-firmware/wiki/nodemcu_api_es)
\ No newline at end of file
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.
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.
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();
fixSearch();
hideNavigationForAllButSelectedLanguage();
addLanguageSelectorToRtdFlyOutMenu();
replaceRelativeLinksWithStaticGitHubUrl();
});
......@@ -44,96 +37,6 @@ var nodemcu = nodemcu || {};
}
}
/*
* RTD messes up MkDocs' search feature by tinkering with the search box defined in the theme, see
* https://github.com/rtfd/readthedocs.org/issues/1088. This function sets up a DOM4 MutationObserver
* to react to changes to the search form (triggered by RTD on doc ready). It then reverts everything
* the RTD JS code modified.
*/
function fixSearch() {
var target = document.getElementById('rtd-search-form');
var config = {attributes: true, childList: true};
var observer = new MutationObserver(function(mutations) {
// if it isn't disconnected it'll loop infinitely because the observed element is modified
observer.disconnect();
var form = $('#rtd-search-form');
form.empty();
form.attr('action', 'https://' + window.location.hostname + '/en/' + determineSelectedBranch() + '/search.html');
$('<input>').attr({
type: "text",
name: "q",
placeholder: "Search docs"
}).appendTo(form);
});
if (window.location.origin.indexOf('readthedocs') > -1) {
observer.observe(target, config);
}
}
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
......@@ -148,48 +51,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 (window.location.origin.indexOf('readthedocs') > -1) {
// 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 {
// 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
......@@ -220,4 +81,4 @@ var nodemcu = nodemcu || {};
}
return values;
}
}());
\ No newline at end of file
}());
# ADC Module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2014-12-24 | [Zeroday](https://github.com/funshine) | [jmattsson](https://github.com/jmattsson) | [adc.c](../../../app/modules/adc.c)|
| 2014-12-24 | [Zeroday](https://github.com/funshine) | [jmattsson](https://github.com/jmattsson) | [adc.c](../../app/modules/adc.c)|
The ADC module provides access to the in-built ADC.
......
# ADXL345 Module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2016-04-08 | [Jason Schmidlapp](https://github.com/jschmidlapp) | [Jason Schmidlapp](https://github.com/jschmidlapp) | [adxl345.c](../../../app/modules/adxl345.c)|
| 2016-04-08 | [Jason Schmidlapp](https://github.com/jschmidlapp) | [Jason Schmidlapp](https://github.com/jschmidlapp) | [adxl345.c](../../app/modules/adxl345.c)|
This module provides access to the [ADXL345](https://www.sparkfun.com/products/9836) triple axis accelerometer.
......
# AM2320 Module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2016-02-14 | [Henk Vergonet](https://github.com/hvegh) | [Henk Vergonet](https://github.com/hvegh) | [am2320.c](../../../app/modules/am2320.c)|
| 2016-02-14 | [Henk Vergonet](https://github.com/hvegh) | [Henk Vergonet](https://github.com/hvegh) | [am2320.c](../../app/modules/am2320.c)|
This module provides access to the [AM2320](https://akizukidenshi.com/download/ds/aosong/AM2320.pdf) humidity and temperature sensor, using the i2c interface.
......
# APA102 Module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2016-01-26 | [Robert Foss](https://github.com/robertfoss)| [Robert Foss](https://github.com/robertfoss)| [apa102.c](../../../app/modules/apa102.c)|
| 2016-01-26 | [Robert Foss](https://github.com/robertfoss)| [Robert Foss](https://github.com/robertfoss)| [apa102.c](../../app/modules/apa102.c)|
This module provides Lua access to [APA102 RGB LEDs](https://youtu.be/UYvC-hukz-0) which are similar in function to the common [WS2812](ws2812) addressable LEDs.
......
# bit Module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2014-12-24 | [https://github.com/LuaDist/bitlib](https://github.com/LuaDist/bitlib), [Zeroday](https://github.com/funshine) | [Zeroday](https://github.com/funshine) | [bit.c](../../../app/modules/bit.c)|
| 2014-12-24 | [https://github.com/LuaDist/bitlib](https://github.com/LuaDist/bitlib), [Zeroday](https://github.com/funshine) | [Zeroday](https://github.com/funshine) | [bit.c](../../app/modules/bit.c)|
Bit manipulation support, on 32bit integers.
......
# BME280 module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2016-02-21 | [vsky279](https://github.com/vsky279) | [vsky279](https://github.com/vsky279) | [bme280.c](../../../app/modules/bme280.c)|
| 2016-02-21 | [vsky279](https://github.com/vsky279) | [vsky279](https://github.com/vsky279) | [bme280.c](../../app/modules/bme280.c)|
This module provides a simple interface to [BME280/BMP280 temperature/air presssure/humidity sensors](http://www.bosch-sensortec.com/bst/products/all_products/bme280) (Bosch Sensortec).
......
# BMP085 Module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2015-08-03 | [Konrad Beckmann](https://github.com/kbeckmann) | [Konrad Beckmann](https://github.com/kbeckmann) | [bmp085.c](../../../app/modules/bmp085.c)|
| 2015-08-03 | [Konrad Beckmann](https://github.com/kbeckmann) | [Konrad Beckmann](https://github.com/kbeckmann) | [bmp085.c](../../app/modules/bmp085.c)|
This module provides access to the [BMP085](https://www.sparkfun.com/tutorials/253) temperature and pressure sensor. The module also works with BMP180.
......
# CJSON Module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2015-03-16 | [Mark Pulford](http://kyne.com.au/~mark/software/lua-cjson.php), [Zeroday](https://github.com/funshine) | [Zeroday](https://github.com/funshine) | [cjson](../../../app/modules/cjson.c) |
| 2015-03-16 | [Mark Pulford](http://kyne.com.au/~mark/software/lua-cjson.php), [Zeroday](https://github.com/funshine) | [Zeroday](https://github.com/funshine) | [cjson](../../app/modules/cjson.c) |
The JSON support module. Allows encoding and decoding to/from JSON.
......
# CoAP Module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2015-02-04 | Toby Jaffey <toby@1248.io>, [Zeroday](https://github.com/funshine) | [Zeroday](https://github.com/funshine) | [coap.c](../../../app/modules/coap.c) |
| 2015-02-04 | Toby Jaffey <toby@1248.io>, [Zeroday](https://github.com/funshine) | [Zeroday](https://github.com/funshine) | [coap.c](../../app/modules/coap.c) |
The CoAP module provides a simple implementation according to [CoAP](http://tools.ietf.org/html/rfc7252) protocol.
The basic endpoint server part is based on [microcoap](https://github.com/1248/microcoap), and many other code reference [libcoap](https://github.com/obgm/libcoap).
......
# crypto Module
| Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ |
| 2015-06-02 | [DiUS](https://github.com/DiUS), [Johny Mattsson](https://github.com/jmattsson) | [Johny Mattsson](https://github.com/jmattsson) | [crypto.c](../../../app/modules/crypto.c)|
| 2015-06-02 | [DiUS](https://github.com/DiUS), [Johny Mattsson](https://github.com/jmattsson) | [Johny Mattsson](https://github.com/jmattsson) | [crypto.c](../../app/modules/crypto.c)|
The crypto modules provides various functions for working with cryptographic algorithms.
......
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