diff --git a/README.md b/README.md index b03e225..62e59f3 100644 --- a/README.md +++ b/README.md @@ -11,27 +11,29 @@ A (very) simple web server written in Lua for the ESP8266 firmware NodeMCU. ## How to use -1. Upload server files using [luatool.py](https://github.com/4refr0nt/luatool) or equivalent. +1. Upload server files using [nodemcu-uploader](https://github.com/kmpm/nodemcu-uploader) or similar. Or, even better, use GNU Make with the bundled makefile. Type the following to upload - server code, init.lua (which you may want to modify), and some example files. + server code, init.lua (which you may want to modify), and some example files: make upload - Compile the server files so that it uses less memory. This needs free memory so I suggest - you do it after a fresh node.restart(). + If you only want to upload the server code, then type: - node.compile("httpserver.lua") - node.compile("httpserver-static.lua") - node.compile("httpserver-error.lua") + make upload_server - If this is not in init.lua, then start the server by typing: + And if you only want to upload the http files: + + make upload_http + + Restart the server. This will execute init.lua which will compile the server code. + Then, assuming init.lua doesn't have it, start the server yourself by typing: dofile("httpserver.lc")(80) In this example, 80 is the port your server is listening at but you can change it. -2. Upload files you want to serve. - Again, use luatool.py or similar and upload the HTML and other files. +2. Want to upload your own files? Move them to the http/ folder. Be careful though, + the flash memory seems to fill up quickly and get corrupted. All the files you upload must be prefixed with "http/". Wait, what? @@ -41,13 +43,14 @@ A (very) simple web server written in Lua for the ESP8266 firmware NodeMCU. 3. Visit your server from a web browser. __Example:__ Say the IP for your ESP8266 is 2.2.2.2 and the server is - running in the default port 80. Go to http://2.2.2.2/index.html using your web browser. The ESP8266 will serve you with the contents - of the file "http/myPage.html" (if it exists). If you visit the root (/) - then index.html is served. By the way, unlike some http servers, the URLs are case-sensitive. + running in the default port 80. Go to (http://2.2.2.2/index.html)[http://2.2.2.2/index.html] using your web browser. + The ESP8266 will serve you with the contents of the file "http/index.html" (if it exists). If you visit the root (/) + then index.html is served. By the way, unlike most HTTP servers, nodemcu_httpserver treats the URLs in a + case-sensitive manner. ## How to create dynamic Lua scripts - Similar to static files, upload a Lua script called "http/[name].lua where you replace [name] with the script's name. + Similar to static files, upload a Lua script called "http/[name].lua where you replace [name] with your script's name. The script should return a function that takes two parameters: return function (connection, args) @@ -65,7 +68,7 @@ A (very) simple web server written in Lua for the ESP8266 firmware NodeMCU. coroutine.yield() - Look at the included example scripts for more ideas. + The easiest is to check out the included example scripts for more ideas. ### Example: Garage door opener @@ -122,29 +125,21 @@ A (very) simple web server written in Lua for the ESP8266 firmware NodeMCU. * HTTP authentication * Encryption -## Open issues - -* File system doesn't like long names, need to protect: - - PANIC: unprotected error in call to Lua API (httpserver.lua:78: filename too long) - -* nodemcu firmware with floating point doesn't have enough memory to compile nor run the server. See below. - -* luatool.py which is used by the makefile, doesn't support uploading binary files (yet?). - But I've successfully used [nodemcu-uploader](https://github.com/kmpm/nodemcu-uploader). The only - thing to know is that after uploading a file, you need to file.rename() it to add the http/ prefix. - ## Notes on memory usage. - The chip is very, very memory constrained. You must use a recent build of nodemcu-firmware that supports - node.compile() since the server expects the helper scripts to be compiled. + The chip is very, very memory constrained. You must use a build of nodemcu-firmware recent enough to support + node.compile() since the server expects all server scripts to be compiled. - * If you can't compile the server code without error even after a fresh restart, then you may need a build - of the firmware without floating point. In file nodemcu-firmware/app/lua/luaconf.h right around line 572 (line number - may change in the future) add + * It is recommended you use a firmware build without support for floating point. + In the (nodemcu-firmware releases page)[https://github.com/nodemcu/nodemcu-firmware/releases] these would be the ones + with the term "integer" in them. If you want to build your own, then edit file nodemcu-firmware/app/lua/luaconf.h right + around line 572 (line number may change) by adding #define LUA_NUMBER_INTEGRAL Then rebuild and re-flash the firmware. * Any help reducing the memory needs of the server without crippling its features are appreciated! + + * You can compile your Lua scripts in order to reduce their memory usage. The server knows to treat + both .lua and .lc files as scripts.