From 16f75e996acf75b9992414f223391bffcc519a82 Mon Sep 17 00:00:00 2001
From: galjonsfigur <44552519+galjonsfigur@users.noreply.github.com>
Date: Sat, 22 Jun 2019 00:20:36 +0200
Subject: [PATCH] Updated LFS introduction (#2807)

---
 docs/getting-started.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/docs/getting-started.md b/docs/getting-started.md
index 4c3a76ae..3f16c13a 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -326,4 +326,45 @@ 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.
 
+### Minimal LFS example
+
+Below is a brief overview of building and running the simplest LFS-based system possible.
+
+To use LFS, start with a version of NodeMCU with LUA_FLASH_STORE set in app/include/user_config.h, and load it on the ESP8266 in the usual way (whatever that is for your set up).
+
+Then build an LFS file system. This can be done in several ways, as discussed above; one of the easiest is to use `luac.cross -f -o lfs.img *lua` on the host machine.  The file [lua_examples/lfs/_init.lua](https://github.com/nodemcu/nodemcu-firmware/tree/dev/lua_examples/lfs/_init.lua) should definitely be included in the image, since it's the easiest way of registering the LFS modules.  The `lfs.img` file can then be downloaded to the ESP8266 just like any other file.
+
+The next step is to tell the ESP8266 that the LFS file system exists.  This is done with eg.  [node.flashreload("lfs.img")](../modules/node/#nodeflashreload), which will trigger a reset, followed by [node.flashindex("_init")()](../modules/node/#nodeflashindex) to register the modules; logging into the esp8266 and running the following commands gives an overview of the command sequence, given a main.lua file consisting of the line `print("LFS main() module")`
+
+```
+>
+> node.flashreload("lfs.img")
+-- flashreload() triggers a reset here.
+> print(LFS)
+nil
+> node.flashindex("_init")()
+-- LFS is now initialised.
+> print(LFS)
+table: 3fff06e0
+-- List the modules in the LFS.
+> print(LFS._list)
+table: 3fff0728
+> for k,v in pairs(LFS._list)  do print(k,v) end
+1    dummy_strings
+2    _init
+3    main
+-- Call the LFS main() module.
+> LFS.main()
+LFS main() module
+> 
+```
+
+Note that no error correction has been used, since the commands are intended to be entered at a terminal, and errors will become obvious.
+
+After that, it's a question of setting up the ESP8266 boot process to check for the existence of an LFS image and run whichever module is required.  Once the LFS module table has been registered by running [lua_examples/lfs/_init.lua](https://github.com/nodemcu/nodemcu-firmware/tree/dev/lua_examples/lfs/_init.lua) , running an LFS module is simple a matter of eg: LFS.main()
+
+[node.flashreload()](../modules/node/#nodeflashreload) need only be rerun if the LFS image is updated; ater it has loaded the LFS image into flash memory the original file (in SPIFFS) is no longer used, and can be deleted.
+
+Once LFS is known to work, then modules such as [lua_examples/lfs/dummy_strings.lua](https://github.com/nodemcu/nodemcu-firmware/tree/dev/lua_examples/lfs/dummy_strings.lua) can usefully be added, together of course with effective error checking.
+
 [↑ back to matrix](#task-os-selector)