godzil/nodemcu-httpserver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Get README.md is up to date.

Browse Source
This commit is contained in:
Marcos Kirsch 2017-07-02 22:40:15 -05:00
parent 7b25c727fe
commit dacaf31dc6
1 changed files with 47 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
README.md
View File

@ -7,16 +7,16 @@ A (very) simple web server written in Lua for the ESP8266 running the NodeMCU fi
> you are really abusing its intended purpose. When it comes to scoping your ESP8266 > you are really abusing its intended purpose. When it comes to scoping your ESP8266
> applications, the adage Keep It Simple Stupid truly applies. > applications, the adage Keep It Simple Stupid truly applies.
> >
> -- <cite>[Terry Ellison](https://github.com/TerryE)</cite>, nodemcu-firmware maintainer, > -- <cite>[Terry Ellison](https://github.com/TerryE)</cite>, nodemcu-firmware maintainer
Let the abuse begin. Let the abuse begin.
## Features ## Features
* GET, POST, PUT and minor changes to support other methods * GET, POST, PUT (other methods can be supported with minor changes)
* Multiple MIME types * Multiple MIME types
* Error pages (404 and others) * Error pages (404 and others)
* Server-side execution of Lua scripts * *Server-side execution of Lua scripts*
* Query string argument parsing with decoding of arguments * Query string argument parsing with decoding of arguments
* Serving .gz compressed files * Serving .gz compressed files
* HTTP Basic Authentication * HTTP Basic Authentication
@ -24,7 +24,9 @@ Let the abuse begin.
## How to use ## How to use
1. Upload server files using [nodemcu-uploader](https://github.com/kmpm/nodemcu-uploader). 1. Modify your local copy of the configuration file httpserver-conf.lua.
2. Upload server files using [nodemcu-uploader](https://github.com/kmpm/nodemcu-uploader).
The easiest is to use GNU Make with the bundled Makefile. Open the Makefile and modify the The easiest is to use GNU Make with the bundled Makefile. Open the Makefile and modify the
user configuration to point to your nodemcu-uploader script and your serial port. user configuration to point to your nodemcu-uploader script and your serial port.
Type the following to upload the server code, init.lua (which you may want to modify), Type the following to upload the server code, init.lua (which you may want to modify),
@ -32,28 +34,24 @@ Let the abuse begin.
make upload_all make upload_all
If you only want to upload the server code, then type: If you only want to upload just the server code, then type:
make upload_server make upload_server
And if you only want to upload the server files: And if you only want to upload just the files that can be served:
make upload_http make upload_http
Restart the server. This will execute init.lua which will compile the server code. Restart the server. This will execute included init.lua which will compile the server code,
Then, assuming init.lua doesn't have it, start the server yourself by typing: configure WiFi, and start the server.
dofile("httpserver.lc")(80) 3. Want to serve your own files? Put them under the http/ folder and upload to the chip.
For example, assuming you want to serve myfile.html, upload by typing:
In this example, 80 is the port your server is listening at, but you can change it. make upload FILE:=http/myfile.html
2. Want to upload your own files? Move them to the http/ folder. Be careful though, Notice that while NodeMCU's filesystem does not support folders, filenames *can* contain slashes.
the flash memory seems to fill up quickly and get corrupted. We take advantage of that and only files that begin with "http/" will be accessible through the server.
All the files you upload must be prefixed with "http/". Wait, what?
Yes: NodeMCU's filesystem does not support folders, but filenames *can* contain slashes.
Only files that begin with "http/" will be accessible through the server.
3. Visit your server from a web browser. 3. Visit your server from a web browser.
@ -63,21 +61,19 @@ Let the abuse begin.
then index.html is served. By the way, unlike most HTTP servers, nodemcu_httpserver treats the URLs in a then index.html is served. By the way, unlike most HTTP servers, nodemcu_httpserver treats the URLs in a
case-sensitive manner. case-sensitive manner.
4. How to use HTTP Basic Authentication. ## HTTP Basic Authentication.
Modify variables in configuration file httpserver-conf.lua in order to enable and to configure usernames/passwords. It's supported. Turn it on in httpserver-conf.lua.
See comments in that file for more details.
When enabled, HTTP Basic Authentication is global to every file served by the server. Use it with care and don't fall into a false sense of security: HTTP Basic Authentication should not be
considered secure since the server is not using encryption. Username and passwords travel
in the clear.
Remember that HTTP Basic Authentication is a very basic authentication protocol, and should not be ## Server-side scripting using your own Lua scripts
considered as secure since the server is not using encryption. Username and passwords travel
in plain text.
## How to use server-side scripting using your own Lua scripts Yes, you can upload your own Lua scripts! This is pretty powerful.
Just put it under http/ and upload it. Make sure it has a .lua extension.
Similar to static files, upload a Lua script called "http/[name].lua where you replace [name] with your script's name. Your script should return a function that takes three parameters:
The script should return a function that takes three parameters:
return function (connection, req, args) return function (connection, req, args)
-- code goes here -- code goes here
@ -107,42 +103,40 @@ Let the abuse begin.
#### Hardware description #### Hardware description
This example assumes that GPIO1 and GPIO2 on the ESP8266 are connected each to a relay This example assumes that you are using a [Wemos D1 Pro](https://wiki.wemos.cc/products:d1:d1_mini_pro)
that can be controlled. How to wire such thing is outside of the scope of this document with two relay shields and two reed switches.
[but information is easily found online](https://www.google.com/search?q=opening+a+garage+door+with+a+microcontroller).
The relays are controlled by the microcontroller and act as the push button, The relays are controlled by the microcontroller and act as the push button,
and can actually be connected in parallel with the existing mechanical button. and can actually be connected in parallel with the existing mechanical button.
The switches are wired so that the ESP8266 can tell whether the doors are open
or closed at any given time.
#### Software description #### Software description
This example consists of the following files: This example consists of the following files:
* **garage_door_opener.html**: Static HTML displays a button with a link * **garage_door.html**: Static HTML displays a form with all options for controlling the
to the garage_door_opener.lua script. That's it! two garage doors.
* **garage_door_opener.css**: Provides styling for garage_door_opener.html * **garage_door_control.html**: Looks like a garage door remote, how neat!
just so it looks pretty. * **garage_door_control.css**: Provides styling for garage_door_control.html.
* **garage_door_opener.lua**: Does the actual work. The script first sends * **garage_door.lua**: Does the actual work. The script performs the desired action on
a little javascript snippet to redirect the client back to garage_door_opener.html the requested door and returns the results as JSON.
and then toggles the GPIO2 line for a short amount of time (roughly equivalent to
the typical button press for opening a garage door) and then toggles it back.
* **apple-touch-icon.png**: This is optional. Provides an icon that * **apple-touch-icon.png**: This is optional. Provides an icon that
will be used if you "Add to Home Screen" the demo on an iPhone. Now it looks like an app! will be used if you "Add to Home Screen" garage_door_control.html on an iPhone.
Now it looks like an app!
#### Security implications #### Security implications
Be careful permanently installing something like this in your home. The server provides Be careful permanently installing something like this in your home. The server provides
no encryption. Your only layers of security are the WiFi network's password and simple no encryption. Your only layers of security are the WiFi network's password and simple
HTTP authentication which sends your password unencrypted. HTTP authentication (if you enable it) which sends your password unencrypted.
This script is provided simply as an educational example. You've been warned. This script is provided for educational purposes. You've been warned.
## Not supported ## Not supported
* Other methods: HEAD, DELETE, TRACE, OPTIONS, CONNECT, PATCH * Other methods: HEAD, DELETE, TRACE, OPTIONS, CONNECT, PATCH
* Encryption / SSL * Encryption / SSL
* Multiple users (HTTP Basic Authentication) * Old nodemcu-firmware versions prior to January 2017) because I don't bother to test them.
* Only protect certain directories (HTTP Basic Authentication)
* nodemcu-firmware versions older 1.5.1 (January 2016) because that's what I tested on.
## Contributing ## Contributing
@ -151,7 +145,9 @@ Let the abuse begin.
and that you add examples for new features. I won't test all your changes myself but I and that you add examples for new features. I won't test all your changes myself but I
am very grateful of improvements and fixes. Open issues in GitHub too, that's useful. am very grateful of improvements and fixes. Open issues in GitHub too, that's useful.
Please follow the coding style as close as possible: Please keep your PRs focused on one thing. I don't mind lots of PRs. I mind PRs that fix multiple unrelated things.
Follow the coding style as closely as possible:
* No tabs, indent with 3 spaces * No tabs, indent with 3 spaces
* Unix (LF) line endings * Unix (LF) line endings
@ -163,8 +159,9 @@ Let the abuse begin.
The chip is very, very memory constrained. The chip is very, very memory constrained.
* Use a recent nodemcu-firmware with as few optional modules as possible. * Use a recent nodemcu-firmware. They've really improved memory usage and fixed leaks.
* Use a firmware build without floating point support. This takes up a good chunk of RAM as well. * Use only the modules you need.
* Any help reducing the memory needs of the server without crippling its functionality is appreciated! * Use a firmware build without floating point support if you can.
* Compile your Lua scripts in order to reduce their memory usage. The server knows to serve and treat * Any help reducing the memory needs of the server without crippling its functionality is much appreciated!
* Compile your Lua scripts in order to reduce their memory usage. The server knows to serve
both .lua and .lc files as scripts. both .lua and .lc files as scripts.