Browse Source

Adding "LFS Quick Start" section

Lukáš Voborský 5 years ago
parent
commit
c39891f9de
1 changed files with 57 additions and 0 deletions
  1. 57 0
      docs/en/lfs.md

+ 57 - 0
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: