diff --git a/Makefile b/Makefile index 2a48f23..a4a35a9 100644 --- a/Makefile +++ b/Makefile @@ -35,12 +35,11 @@ USE_HEATSHRINK ?= yes BUILD_BASE = build FW_BASE = firmware -# Base directory for the compiler. Needs a / at the end; if not set it'll use the tools that are in -# the PATH. -XTENSA_TOOLS_ROOT ?= +# Base directory for the compiler. Needs a / at the end; +XTENSA_TOOLS_ROOT ?= $(abspath ../esp-open-sdk/xtensa-lx106-elf/bin)/ -# base directory of the ESP8266 SDK package, absolute -SDK_BASE ?= /opt/Espressif/ESP8266_SDK +# Base directory of the ESP8266 SDK package, absolute +SDK_BASE ?= $(abspath ../esp_iot_sdk_v1.0.1) #Esptool.py path and port ESPTOOL ?= esptool.py diff --git a/README b/README index bf7c9fc..98bcc7f 100644 --- a/README +++ b/README @@ -1,41 +1,73 @@ -esp-httpd README - -This is a small but powerful webserver for ESP8266(EX) chips. Included is an example of how -to make a module that can have the AP it connects to configured over a webbrowser. - -ABOUT THE WEBSERVER - -The Good (aka: what's awesome) - - Supports multiple connections, for eg simultaneous html/css/js/images downloading - - Static files stored in flash, in an (optionally compressed) RO filesystem - - Pluggable using external cgi routines - - Simple template engine for mixed c and html things - -The Bad (aka: what can be improved) - - Not built for speediness, although it's reasonable fast. - - Built according to what I remember of the HTTP protocol, not according to the - RFCs. Should work with most modern browsers, though. - - No support for https. - -The Ugly (aka: bugs, misbehaviour) -- Possible buffer overflows (usually not remotely exploitable) due to no os_snprintf - This can be theoretically remedied by either Espressif including an os_snprintf in - their libs or by using some alternate printf lib, like elm-chans xprintf - -ABOUT THE EXAMPLE - -When you flash the example into an ESP8266(EX) module, you get a small webserver with a few example -pages. If you've already connected your module to your WLAN before, it'll keep those settings. When -you haven't or the settings are wrong, keep GPIO0 for >5 seconds. The module will reboot into -its STA+AP mode. Connect a computer to the newly formed access point and browse to -http://192.168.4.1/wifi in order to connect the module to your WiFi network. The example also -allows you to control a LED that's connected to GPIO2. - -BUILDING EVERYTHING - -For this, you need an environment that can compile ESP8266 firmware. Environments for this still -are in flux at the moment, but I'm using esp-open-sdk: https://github.com/pfalcon/esp-open-sdk . -You probably also need an UNIX-like system; I'm working on Debian Linux myself. +ESP8266 - Bridge +================ + +This firmware implements a transparent bridge between Wifi and serial using an ESP8266 module. +It also provides support for flash-programming Arduino/AVR microcontrollers as well as +LPC800-series ARM microcontrollers via the ESP8266. + +The firmware includes a tiny HTTP server based on +[esphttpd](http://www.esp8266.com/viewforum.php?f=34) +with a simple web interface. + +Hardware info +------------- +This firmware is designed for esp8266 modules which have most esp I/O pins available. +The expected connections are: +- URXD: connect to TX of microcontroller +- UTXD: connect to RX of microcontroller +- GPIO12: connect to RESET of microcontroller +- GPIO13: connect to ISP of LPC/ARM microcontroller (not used with Arduino/AVR) +- GPIO0: optionally connect green "conn" LED to 3.3V (indicates wifi status) +- GPIO2: optionally connect yellow "ser" LED to 3.3V (indicates serial activity) +If you are using an FTDI connector, GPIO12 goes to DTR and GPIO13 goes to CTS + +Initial flashing +---------------- +If you want to simply flash the provided firmware binary, you can use your favorite +ESP8266 flashing tool and flash the following: +- `boot_v1.3(b3).bin` from the official `esp_iot_sdk_v1.0.1` to 0x00000 +- `blank.bin` from the official SDK to 0x7e000 +- `./firmware/user1.bin` to 0x01000 +Note that the firmware assumes a 512KB flash chip, which most of the esp-01 thru esp-11 +modules appear to have. + +Wifi configuration +--------------------- +After you have serially flashed the module it will create a wifi access point (AP) with an +SSID of the form `ESP_012ABC` where 012ABC is a piece of the module's MAC address. +Using a laptop, phone, or tablet connect to this SSID and then open a browser pointed at +http://192.168.0.1, you should them see the esp8266-bridge web site. + +Now configure the wifi. The typical desired configuration is for the esp-bridge to be a +station on your local wifi network so can communicate with it from all your computers. + +To make this happen, navigate to the wifi page and hit the "change to STA+AP mode" button. +This will cause the esp8266 to restart and yo will have to wait 5-10 seconds until you can +reconnect to the ESP_123ABC wifi network and refres the wifi settings page. + +At this point you should see a list of detected networks on the web page and you can select +yours. Enter a password if your network is secure (recommended...) and hit the connect button. + +You should now see that the esp-bridge has connected to your network and it should show you +its IP address. Write it down and then follow the provided link (you may have to switch your +laptop, phone, or tablet back to your network before you can actually connect). + +At this point the esp-bridge will have switched to STA mode and be just a station on your +wifi network. These settings are stored in flash and thereby remembered through resets and +power cycles. They are also remembered when you flash new firmware. Only flashing `blank.bin` +as indicated above will reset the wifi settings. + +There is a fail-safe, which is that after a reset (need details) the esp-bridge will revert +back to AP+STA mode and thus both present its ESP_012ABC-style network and try to connect to +the requested network, which will presumably not work or it wouldn't be in fail-safe mode +in the first place. You can then connect to the network and reconfigure the station part. + + +Building the firmware +--------------------- +The firmware has been built using the [esp-open-sdk](https://github.com/pfalcon/esp-open-sdk) + +You probably also need an UNIX-like system. To manage the paths to all this, you can source a small shell fragment into your current session. For example, I source a file with these contents: @@ -49,7 +81,7 @@ Actual setup of the SDK and toolchain is out of the scope of this document, so I enough to set up your own if you haven't already. If you have that, you can clone out the source code: -git clone http://git.spritesserver.nl/esphttpd.git/ +git clone http://github.com/jeelabs/esp-bridge This project makes use of heatshrink, which is a git submodule. To fetch the code: cd esphttpd @@ -59,28 +91,15 @@ git submodule update Now, build the code: make -Flash the code happens in 2 steps. First the code itself gets flashed. Reset the module into bootloader -mode and enter 'make flash'. You may want to reset and re-enter the bootloader halfway (at 'sleep 3') for -the 2nd part of this flash to work. - -The 2nd step is to pack the static files the webserver will serve and flash that. Reset the module into -bootloader mode again and enter 'make htmlflash'. - -You should have a working webserver now. - -WRITING CODE FOR THE WEBSERVER - -...errm... to be done. For now, look at the examples. Hey, you probably managed to find out how -the SDK works, this shouldn't be too hard :P - - -CHANGE FROM SDK 0.9.3 (and earlier) TO SDK 0.9.4 (and later): -Change all occurences of -espconn_sent(connData->conn, (uint8 *)buff, len); -to -httpdSend(connData, buff, len) -please. The reason for this is that you can't do multiple espconn_sent calls serially anymore, so -httpd needs to buffer the writes now. This is only needed in your own code; the code that comes -with httpd already has this changed. - +Flashing the firmware +--------------------- +This firmware supports over-the-air (OTA) flashing, so you do not have to deal with serial +flashing again after the initial one! The recommended way to flash is to use `make wiflash`, +which assumes that you set ESP_HOSTNAME to the hostname or IP address of your esp-bridge. + +The flashing, restart, and re-associating with your wireless network takes about 15 seconds +and is fully automatic. The 512KB flash are divided into two 236KB partitions allowing for new +code to be uploaded into one partition while running from the other. This is the official +OTA upgrade method supported by the SDK, except that the firmware is POSTed to the module +using curl as opposed to having the module download it from a cloud server.