From 07341e977f9704209a649085475e6c6b8cfc1f5e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcel=20St=C3=B6r?= Date: Sun, 12 Mar 2017 21:43:46 +0100 Subject: [PATCH] Transfer build options from README to docs (#1860) * Transfer build options from README to docs, fixes #1830 * reference tls, u8g, ucg module configuration --- README.md | 54 +------------------------- docs/en/build.md | 72 +++++++++++++++++++++++++++++++---- docs/en/extn-developer-faq.md | 3 +- 3 files changed, 69 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 1221ce19..ac8cd059 100644 --- a/README.md +++ b/README.md @@ -43,10 +43,9 @@ wifi.sta.config("SSID", "password") # Documentation -The entire [NodeMCU documentation](https://nodemcu.readthedocs.io) is maintained right in this repository at [/docs](docs). The fact that the API documentation is mainted 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). +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/dev/en/build/) -- How to [build the filesystem](https://nodemcu.readthedocs.io/en/dev/en/spiffs/) - How to [flash the firmware](https://nodemcu.readthedocs.io/en/dev/en/flash/) - How to [upload code and NodeMCU IDEs](https://nodemcu.readthedocs.io/en/dev/en/upload/) - API documentation for every module @@ -65,53 +64,4 @@ See [https://nodemcu.readthedocs.io/en/dev/en/support/](https://nodemcu.readthed # License -[MIT](https://github.com/nodemcu/nodemcu-firmware/blob/master/LICENSE) © [zeroday](https://github.com/NodeMCU)/[nodemcu.com](http://nodemcu.com/index_en.html) - -# Build Options - -The following sections explain some of the options you have if you want to [build your own NodeMCU firmware](http://nodemcu.readthedocs.io/en/dev/en/build/). - -### Select Modules - -Disable modules you won't be using to reduce firmware size and free up some RAM. The ESP8266 is quite limited in available RAM and running out of memory can cause a system panic. The default configuration is designed to run on all ESP modules including the 512 KB modules like ESP-01 and only includes general purpose interface modules which require at most two GPIO pins. - -Edit `app/include/user_modules.h` and comment-out the `#define` statement for modules you don't need. Example: - -```c -... -#define LUA_USE_MODULES_MQTT -// #define LUA_USE_MODULES_COAP -// #define LUA_USE_MODULES_U8G -... -``` - -### Tag Your Build - -Identify your firmware builds by editing `app/include/user_version.h` - -```c -#define NODE_VERSION "NodeMCU 2.0.0+myname" -#ifndef BUILD_DATE -#define BUILD_DATE "YYYYMMDD" -#endif -``` - -### Set UART Bit Rate - -The initial baud rate at boot time is 115200bps. You can change this by -editing `BIT_RATE_DEFAULT` in `app/include/user_config.h`: - -```c -#define BIT_RATE_DEFAULT BIT_RATE_115200 -``` - -Note that, by default, the firmware runs an auto-baudrate detection algorithm so that typing a few characters at boot time will cause -the firmware to lock onto that baud rate (between 1200 and 230400). - -### Debugging - -To enable runtime debug messages to serial console edit `app/include/user_config.h` - -```c -#define DEVELOP_VERSION -``` +[MIT](https://github.com/nodemcu/nodemcu-firmware/blob/master/LICENSE) © [zeroday](https://github.com/NodeMCU)/[nodemcu.com](http://nodemcu.com/index_en.html) \ No newline at end of file diff --git a/docs/en/build.md b/docs/en/build.md index eaf144d9..0ce62751 100644 --- a/docs/en/build.md +++ b/docs/en/build.md @@ -1,14 +1,72 @@ There are essentially three ways to build your NodeMCU firmware: cloud build service, Docker image, dedicated Linux environment (possibly VM). -**Building manually** +## Tools -Note that the *default configuration in the C header files* (`user_config.h`, `user_modules.h`) is designed to run on all ESP modules including the 512 KB modules like ESP-01 and only includes general purpose interface modules which require at most two GPIO pins. - -## Cloud Build Service +### Cloud Build Service NodeMCU "application developers" just need a ready-made firmware. There's a [cloud build service](http://nodemcu-build.com/) with a nice UI and configuration options for them. -## Docker Image +### Docker Image Occasional NodeMCU firmware hackers don't need full control over the complete tool chain. They might not want to setup a Linux VM with the build environment. Docker to the rescue. Give [Docker NodeMCU build](https://hub.docker.com/r/marcelstoer/nodemcu-build/) a try. -## 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 +### 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. + +## Build Options + +The following sections explain some of the options you have if you want to build your own NodeMCU firmware. + +### Select Modules +Disable modules you won't be using to reduce firmware size and free up some RAM. The ESP8266 is quite limited in available RAM and running out of memory can cause a system panic. The *default configuration* is designed to run on all ESP modules including the 512 KB modules like ESP-01 and only includes general purpose interface modules which require at most two GPIO pins. + +Edit `app/include/user_modules.h` and comment-out the `#define` statement for modules you don't need. Example: + +```c +... +#define LUA_USE_MODULES_MQTT +// #define LUA_USE_MODULES_COAP +// #define LUA_USE_MODULES_U8G +... +``` + +### TLS/SSL Support +To enable TLS support edit `app/include/user_config.h` and uncomment the following flag: + +```c +//#define CLIENT_SSL_ENABLE +``` + +The complete configuration is stored in `app/include/user_mbedtls.h`. This is the file to edit if you build your own firmware and want to change mbed TLS behavior. See the [`tls` documentation](modules/tls.md) for details. + +### Debugging +To enable runtime debug messages to serial console edit `app/include/user_config.h` + +```c +#define DEVELOP_VERSION +``` + +### Set UART Bit Rate +The initial baud rate at boot time is 115200bps. You can change this by +editing `BIT_RATE_DEFAULT` in `app/include/user_config.h`: + +```c +#define BIT_RATE_DEFAULT BIT_RATE_115200 +``` + +Note that, by default, the firmware runs an auto-baudrate detection algorithm so that typing a few characters at boot time will cause +the firmware to lock onto that baud rate (between 1200 and 230400). + +### Tag Your Build +Identify your firmware builds by editing `app/include/user_version.h` + +```c +#define NODE_VERSION "NodeMCU 2.0.0+myname" +#ifndef BUILD_DATE +#define BUILD_DATE "YYYYMMDD" +#endif +``` + +### u8g Module Configuration +Display drivers and embedded fonts are compiled into the firmware image based on the settings in `app/include/u8g_config.h`. See the [`u8g` documentation](modules/u8g.md#displays) for details. + +### ucg Module Configuration +Display drivers and embedded fonts are compiled into the firmware image based on the settings in `app/include/ucg_config.h`. See the [`ucg` documentation](modules/ucg.md#displays) for details. diff --git a/docs/en/extn-developer-faq.md b/docs/en/extn-developer-faq.md index 4cec64f7..67bd9a79 100644 --- a/docs/en/extn-developer-faq.md +++ b/docs/en/extn-developer-faq.md @@ -1,6 +1,7 @@ # Extension Developer FAQ -**# # # Work in Progress # # #** +## Firmware build options +[Building the firmware → Build Options](build.md#build-options) lists a few of the common parameters to customize your firmware *at build time*. ## How does the non-OS SDK structure execution