fix paths in makefile; first cut at new readme

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
+# Base directory for the compiler. Needs a / at the end;
-# the PATH.
+XTENSA_TOOLS_ROOT ?= $(abspath ../esp-open-sdk/xtensa-lx106-elf/bin)/
-XTENSA_TOOLS_ROOT ?= 
 
-# base directory of the ESP8266 SDK package, absolute
+# Base directory of the ESP8266 SDK package, absolute
-SDK_BASE	?= /opt/Espressif/ESP8266_SDK
+SDK_BASE	?= $(abspath ../esp_iot_sdk_v1.0.1)
 
 #Esptool.py path and port
 ESPTOOL		?= esptool.py

README

@@ -1,41 +1,73 @@
-esp-httpd README
+ESP8266 - Bridge
-
+================
-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.
+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
-ABOUT THE WEBSERVER
+LPC800-series ARM microcontrollers via the ESP8266.
-
+
-The Good (aka: what's awesome)
+The firmware includes a tiny HTTP server based on
- - Supports multiple connections, for eg simultaneous html/css/js/images downloading
+[esphttpd](http://www.esp8266.com/viewforum.php?f=34)
- - Static files stored in flash, in an (optionally compressed) RO filesystem
+with a simple web interface.
- - Pluggable using external cgi routines
+
- - Simple template engine for mixed c and html things
+Hardware info
-
+-------------
-The Bad (aka: what can be improved)
+This firmware is designed for esp8266 modules which have most esp I/O pins available.
- - Not built for speediness, although it's reasonable fast.
+The expected connections are:
- - Built according to what I remember of the HTTP protocol, not according to the
+- URXD: connect to TX of microcontroller
-   RFCs. Should work with most modern browsers, though.
+- UTXD: connect to RX of microcontroller
- - No support for https.
+- GPIO12: connect to RESET of microcontroller
-
+- GPIO13: connect to ISP of LPC/ARM microcontroller (not used with Arduino/AVR)
-The Ugly (aka: bugs, misbehaviour)
+- GPIO0: optionally connect green "conn" LED to 3.3V (indicates wifi status)
-- Possible buffer overflows (usually not remotely exploitable) due to no os_snprintf
+- GPIO2: optionally connect yellow "ser" LED to 3.3V (indicates serial activity)
-  This can be theoretically remedied by either Espressif including an os_snprintf in 
+If you are using an FTDI connector, GPIO12 goes to DTR and GPIO13 goes to CTS
-  their libs or by using some alternate printf lib, like elm-chans xprintf
+
-
+Initial flashing
-ABOUT THE EXAMPLE
+----------------
-
+If you want to simply flash the provided firmware binary, you can use your favorite
-When you flash the example into an ESP8266(EX) module, you get a small webserver with a few example
+ESP8266 flashing tool and flash the following:
-pages. If you've already connected your module to your WLAN before, it'll keep those settings. When
+- `boot_v1.3(b3).bin` from the official `esp_iot_sdk_v1.0.1` to 0x00000
-you haven't or the settings are wrong, keep GPIO0 for >5 seconds. The module will reboot into
+- `blank.bin` from the official SDK to 0x7e000
-its STA+AP mode. Connect a computer to the newly formed access point and browse to 
+- `./firmware/user1.bin` to 0x01000
-http://192.168.4.1/wifi in order to connect the module to your WiFi network. The example also
+Note that the firmware assumes a 512KB flash chip, which most of the esp-01 thru esp-11
-allows you to control a LED that's connected to GPIO2.
+modules appear to have.
-
+
-BUILDING EVERYTHING
+Wifi configuration
-
+---------------------
-For this, you need an environment that can compile ESP8266 firmware. Environments for this still
+After you have serially flashed the module it will create a wifi access point (AP) with an
-are in flux at the moment, but I'm using esp-open-sdk: https://github.com/pfalcon/esp-open-sdk .
+SSID of the form `ESP_012ABC` where 012ABC is a piece of the module's MAC address.
-You probably also need an UNIX-like system; I'm working on Debian Linux myself. 
+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
+Flashing the firmware
-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.
+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`,
-The 2nd step is to pack the static files the webserver will serve and flash that. Reset the module into
+which assumes that you set ESP_HOSTNAME to the hostname or IP address of your esp-bridge.
-bootloader mode again and enter 'make htmlflash'.
+
-
+The flashing, restart, and re-associating with your wireless network takes about 15 seconds
-You should have a working webserver now.
+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
-WRITING CODE FOR THE WEBSERVER
+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.
-...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.
-