From c39891f9de5dd8992a54dc6db9e1c2399a9e3058 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luk=C3=A1=C5=A1=20Voborsk=C3=BD?= Date: Mon, 16 Jul 2018 23:08:08 +0200 Subject: [PATCH 1/3] Adding "LFS Quick Start" section --- docs/en/lfs.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/docs/en/lfs.md b/docs/en/lfs.md index 91327d3c..6d609d53 100644 --- a/docs/en/lfs.md +++ b/docs/en/lfs.md @@ -1,5 +1,62 @@ # Lua Flash Store (LFS) +## LFS Quick Start + +LFS is a way how to execute your Lua code out of ESP8266 flash memory so more RAM is available for variables and data structures. This way large Lua files can be run on ESP8266. There would not be enough RAM to execute such files in a "normal" (out of SPIFFS) way. + +This is a simple step-by-step how to use the LFS feature: +1. Get and flash LFS enabled firmware + + Either you get it from https://nodemcu-build.com/. In the section "LFS options (currently just for dev)" choose the size of the LFS partition (64 KB should be fine). SPIFFS default settings should be fine. + + Another possibility is to compile own firmware and enable LFS in [user_config.h](../../app/include/user_config.h), setting `#define LUA_FLASH_STORE 0x10000`. + + Flash the firmware to ESP8266. + +2. Select Lua files to be run from LFS + + Nice example is to run telnet and ftp client from LFS. Put the following files in 1 directory: + * [lua_examples/lfs/_init.lua](../../lua_examples/lfs/_init.lua) + * [lua_examples/lfs/dummy_strings.lua](../../lua_examples/lfs/dummy_strings.lua) + * [lua_examples/telnet/telnet.lua](../../lua_examples/telnet/telnet.lua) + * [lua_modules/ftp/ftpserver.lua](../../lua_modules/ftp/ftpserver.lua) + + 3. Compile the LFS image + + Windows 10 users can use the Windows Subsystem for Linux. From the directory with Lua files from the previous section run `bash` and execute the command (adjust the path as needed): + ```bash + /mnt/c/GitHub/nodemcu-firmware/luac.cross -f *.lua + ``` + or the following command which includes all Lua files except `init.lua` into LFS image can be used (`init.lua` needs to be in SPIFFS so it does not make sense to include it in the LFS image) + ```bash + /mnt/c/GitHub/nodemcu-firmware/luac.cross -f `find *.lua -not -name 'init.lua'` + ``` + As a result the `luac.out` file is created. + + 4. Upload the LFS image + + This can be done with [ESPlorer](https://github.com/4refr0nt/ESPlorer) tool with "Upload..." (or by other means). + + 5. Flash the LFS image to LFS partition + + Run the following command on ESP + ```Lua + node.flashreload("luac.out") + ``` + + 6. Adjust the `init.lua` file + + Add the following lines: + + ```Lua + -- Execute the LFS init + node.flashindex("_init")() + -- Start telnet server + require("telnet"):open() + -- Start ftp serer + require("ftpserver").createServer('user', 'password') + ``` + ## Background An IoT device such as the ESP8266 has very different processor characteristics from the CPU in a typical PC: From 36029a08e1f74eb7bb9221f06b9820aa02044885 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luk=C3=A1=C5=A1=20Voborsk=C3=BD?= Date: Wed, 18 Jul 2018 22:46:46 +0200 Subject: [PATCH 2/3] Update lfs.md --- docs/en/lfs.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/docs/en/lfs.md b/docs/en/lfs.md index 6d609d53..11a41101 100644 --- a/docs/en/lfs.md +++ b/docs/en/lfs.md @@ -4,24 +4,30 @@ LFS is a way how to execute your Lua code out of ESP8266 flash memory so more RAM is available for variables and data structures. This way large Lua files can be run on ESP8266. There would not be enough RAM to execute such files in a "normal" (out of SPIFFS) way. +The tutorial assumes that you are able to build a nodemcu-firmware on a Windows 10 host. + This is a simple step-by-step how to use the LFS feature: 1. Get and flash LFS enabled firmware - Either you get it from https://nodemcu-build.com/. In the section "LFS options (currently just for dev)" choose the size of the LFS partition (64 KB should be fine). SPIFFS default settings should be fine. - - Another possibility is to compile own firmware and enable LFS in [user_config.h](../../app/include/user_config.h), setting `#define LUA_FLASH_STORE 0x10000`. + Either you get it from [NodeMCU Build](https://nodemcu-build.com/). In the section "LFS options (currently just for dev)" choose the size of the LFS partition (64 KB should be fine). SPIFFS default settings should be fine. + Another possibility is to compile own firmware and enable LFS in [user_config.h](../../app/include/user_config.h), setting `#define LUA_FLASH_STORE 0x10000`. This file includes explanation of how to configure LFS in its comments. + + For details see section [Selecting the firmware](###Selecting-the-firmware) of the LFS documentation. + Flash the firmware to ESP8266. 2. Select Lua files to be run from LFS - Nice example is to run telnet and ftp client from LFS. Put the following files in 1 directory: + The easest way is to maintain Lua files of your project in its own directory tree on your host. Project files will be compiled by `luac.cross` to build the LFS image in next step. + + Nice example is to run telnet and ftp client from LFS. In order to do this put the following files in 1 directory: * [lua_examples/lfs/_init.lua](../../lua_examples/lfs/_init.lua) * [lua_examples/lfs/dummy_strings.lua](../../lua_examples/lfs/dummy_strings.lua) * [lua_examples/telnet/telnet.lua](../../lua_examples/telnet/telnet.lua) - * [lua_modules/ftp/ftpserver.lua](../../lua_modules/ftp/ftpserver.lua) - - 3. Compile the LFS image + * [lua_modules/ftp/ftpserver.lua](../../lua_modules/ftp/ftpserver.lua) + + 3. Build the LFS image Windows 10 users can use the Windows Subsystem for Linux. From the directory with Lua files from the previous section run `bash` and execute the command (adjust the path as needed): ```bash @@ -35,7 +41,9 @@ This is a simple step-by-step how to use the LFS feature: 4. Upload the LFS image - This can be done with [ESPlorer](https://github.com/4refr0nt/ESPlorer) tool with "Upload..." (or by other means). + Now it's time to upload the generate LFS image file (`luasc.out`) as a normal SPIFFS file. Several tools can be used to upload the files from host to SPIFFS. + + One way is to use the [ESPlorer](https://github.com/4refr0nt/ESPlorer) tool, button "Upload...". 5. Flash the LFS image to LFS partition @@ -43,6 +51,7 @@ This is a simple step-by-step how to use the LFS feature: ```Lua node.flashreload("luac.out") ``` + The firmware will reboot the ESP8266 and modules will be available after reboot. 6. Adjust the `init.lua` file From 3f8faf8e55d0cd412752a73c0edde3ca6605e13c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luk=C3=A1=C5=A1=20Voborsk=C3=BD?= Date: Wed, 18 Jul 2018 22:51:14 +0200 Subject: [PATCH 3/3] Update lfs.md --- docs/en/lfs.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/en/lfs.md b/docs/en/lfs.md index 11a41101..c22a7a0e 100644 --- a/docs/en/lfs.md +++ b/docs/en/lfs.md @@ -41,7 +41,7 @@ This is a simple step-by-step how to use the LFS feature: 4. Upload the LFS image - Now it's time to upload the generate LFS image file (`luasc.out`) as a normal SPIFFS file. Several tools can be used to upload the files from host to SPIFFS. + Now it's time to upload the generate LFS image file (`luac.out`) as a normal SPIFFS file. Several tools can be used to upload the files from host to SPIFFS. One way is to use the [ESPlorer](https://github.com/4refr0nt/ESPlorer) tool, button "Upload...". @@ -55,6 +55,8 @@ This is a simple step-by-step how to use the LFS feature: 6. Adjust the `init.lua` file + `init.lua` is the file that is first executed by the NodeMCU firmware. Usually it setups the wifi connection and executes the main Lua file. + Add the following lines: ```Lua