updated makefile and readme

Makefile

@@ -150,7 +150,7 @@ endif
 # on the release tag, make release, upload esp-link.tgz into the release files
 #VERSION ?= "esp-link custom version"
 DATE    := $(shell date '+%F %T')
-BRANCH  := $(shell if git diff --quiet HEAD; then git describe --tags; \
+BRANCH  ?= $(shell if git diff --quiet HEAD; then git describe --tags; \
                    else git symbolic-ref --short HEAD; fi)
 SHA     := $(shell if git diff --quiet HEAD; then git rev-parse --short HEAD | cut -d"/" -f 3; \
                    else echo "development"; fi)
@@ -409,7 +409,7 @@ release: all
 	$(Q) egrep -a 'esp-link [a-z0-9.]+ - 201' $(FW_BASE)/user1.bin | cut -b 1-80
 	$(Q) egrep -a 'esp-link [a-z0-9.]+ - 201' $(FW_BASE)/user2.bin | cut -b 1-80
 	$(Q) cp $(FW_BASE)/user1.bin $(FW_BASE)/user2.bin $(SDK_BASE)/bin/blank.bin \
-		   "$(SDK_BASE)/bin/boot_v1.4(b1).bin" wiflash release/esp-link-$(BRANCH)
+		   "$(SDK_BASE)/bin/boot_v1.4(b1).bin" wiflash avrflash release/esp-link-$(BRANCH)
 	$(Q) tar zcf esp-link-$(BRANCH).tgz -C release esp-link-$(BRANCH)
 	$(Q) echo "Release file: esp-link-$(BRANCH).tgz"
 	$(Q) rm -rf release

README.md

@@ -4,8 +4,9 @@ ESP-LINK
 This firmware connects an attached micro-controller to the internet using a ESP8266 Wifi module.
 It implements a number of features:
 - transparent bridge between Wifi and serial, useful for debugging or inputting into a uC
-- flash-programming attached Arduino/AVR microcontrollers as well as LPC800-series and other
+- flash-programming attached Arduino/AVR microcontrollers, esp8266 modules, as well as
-  ARM microcontrollers via Wifi
+  LPC800-series and other ARM microcontrollers via Wifi
+- built-in stk500v1 programmer for AVR uC's with optiboot: program using HTTP upload of hex file
 - outbound TCP (and thus HTTP) connections from the attached micro-controller to the internet
 - outbound REST HTTP requests from the attached micro-controller to the internet, protocol
   based on espduino and compatible with [tuanpmt/espduino](https://github.com/tuanpmt/espduino)
@@ -17,11 +18,16 @@ Many thanks to https://github.com/brunnels for contributions around the espduino
 
 ###[Releases](https://github.com/jeelabs/esp-link/releases)
 
-- [V2.0.beta2](https://github.com/jeelabs/esp-link/releases/tag/v2.0.beta2) has REST support but
+- [V2.1.beta1](https://github.com/jeelabs/esp-link/releases/tag/v2.1.beta1) has the new built-in
-  requires a 1MByte or 4MByte ESP8266 flash, e.g. esp-12 or wroom-02
+  stk500v1 programmer and works on all modules (esp-01 through esp-12). This is still beta-ware!
-- [V1.0.1](https://github.com/jeelabs/esp-link/releases/tag/v1.0.1) is _stable_
+- [V2.0.rc1](https://github.com/jeelabs/esp-link/releases/tag/v2.0.rc1) has REST support but
+  requires a 1MByte or 4MByte ESP8266 flash, e.g. esp-12 or wroom-02. Despite being labeled
+  as release candidate this is a pretty stable release.
+- [V1.0.4](https://github.com/jeelabs/esp-link/releases/tag/v1.0.4) is _stable_
   and has the web server, transparent bridge, flash-programming support, but lacks
-  the REST and upcoming MQTT support. V1 works with 512KB flash, e.g. esp-1, esp-3, ...
+  the REST and upcoming MQTT support. V1 works with 512KB flash, e.g. esp-01, esp-03, ...
+  Unless you've been using V1 and want to stay on it, the V1 series is really obsolete and
+  I recommend trying the latest V2 at this point.
 
 For quick support and questions:
 [![Chat at https://gitter.im/jeelabs/esp-link](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jeelabs/esp-link?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
@@ -60,47 +66,64 @@ attached microcontroller, and the pin assignments card:
 
 Hardware info
 -------------
-This firmware is designed for esp8266 modules which have most ESP I/O pins available and
+This firmware is designed for any esp8266 module.
-at least 1MB flash. (The V1 firmware supports modules with 512KB flash).
+The recommended connections for an esp-01 module are:
-The default connections are:
+- URXD: connect to TX of microcontroller
+- UTXD: connect to RX of microcontroller
+- GPIO0: connect to RESET of microcontroller
+- GPIO2: optionally connect green LED to 3.3V (indicates wifi status)
+
+The recommended connections for an esp-12 module 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)
+- GPIO13: connect to ISP of LPC/ARM microcontroller or to GPIO0 of esp8266 being programmed
+  (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.
+If your application has problems with the boot message that is output at ~74600 baud by the ROM
+at boot time you can connect an esp-12 module as follows and choose the "swap_uart" pin assignment
+in the esp-link web interface:
+- GPIO13: connect to TX of microcontroller
+- GPIO15: connect to RX of microcontroller
+- GPIO1/UTXD: connect to RESET of microcontroller
+- GPIO3/URXD: connect to ISP of LPC/ARM microcontroller or to GPIO0 of esp8266 being programmed
+  (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 esp-12 module, you can avoid the initial boot message from the esp8266
+If you are using an FTDI connector, GPIO12 goes to DTR and GPIO13 goes to CTS (or vice-versa, I've
-bootloader by using the swap-pins option. This swaps the esp8266 TX/RX to gpio15/gpio13 respectively.
+seen both used, sigh).
 
 The GPIO pin assignments can be changed dynamically in the web UI and are saved in flash.
 
 Initial flashing
 ----------------
-(This is not necessary if you receive one of the jn-esp or esp-bridge modules from the author!)
+If you want to simply flash a pre-built firmware binary, you can download the latest
-If you want to simply flash the provided firmware binary, you can download the latest
 [release](https://github.com/jeelabs/esp-link/releases) and use your favorite
 ESP8266 flashing tool to flash the bootloader, the firmware, and blank settings.
 Detailed instructions are provided in the release notes.
 
-Note that the firmware assumes a 512KB flash chip, which most of the esp-01 thru esp-11
+_Important_: the firmware adapts automatically to the size of the flash chip using information
-modules appear to have. A larger flash chip should work but has not been tested.
+stored in the boot sector (address 0). This is the standard way that the esp8266 SDK detects
+the flash size. What this means is that you need to set this properly when you flash the bootloader.
+If you use esptool.py you can do it using the -ff and -fs options.
 
 Wifi configuration overview
 ------------------
-For proper operation the end state the esp-link needs to arrive at is to have it
+For proper operation the end state that esp-link needs to arrive at is to have it
 join your pre-existing wifi network as a pure station.
-However, in order to get there the esp-link will start out as an access point and you'll have
+However, in order to get there esp-link will start out as an access point and you'll have
 to join its network to configure it. The short version is:
- 1. the esp-link creates a wifi access point with an SSID of the form `ESP_012ABC`
+ 1. esp-link creates a wifi access point with an SSID of the form `ESP_012ABC` (some modules
- 2. you join your laptop or phone to the esp-link's network as a station and you configure
+    use a different SSID form, such as `ai-thinker-012ABC`)
-    the esp-link wifi with your network info by pointing your browser at http://192.168.4.1/
+ 2. you join your laptop or phone to esp-link's network as a station and you configure
- 3. the esp-link starts to connect to your network while continuing to also be an access point
+    esp-link wifi with your network info by pointing your browser at http://192.168.4.1/
+ 3. esp-link starts to connect to your network while continuing to also be an access point
     ("AP+STA"), the esp-link may show up with a `esp-link.local` hostname
     (depends on your DHCP/DNS config)
- 4. the esp-link succeeds in connecting and shuts down its own access point after 15 seconds,
+ 4. esp-link succeeds in connecting and shuts down its own access point after 15 seconds,
     you reconnect your laptop/phone to your normal network and access esp-link via its hostname
     or IP address
 
@@ -156,7 +179,13 @@ Troubleshooting
 ---------------
 - verify that you have sufficient power, borderline power can cause the esp module to seemingly
   function until it tries to transmit and the power rail collapses
-- check the "conn" LED to see which mode esp-link is in (see LED info above)
+- if you just cannot flash your esp8266 module (some people call it the zombie mode) make sure you
+  have gpio0 and gpio15 pulled to gnd with a 1K resistor, gpio2 tied to 3.3V with 1K resistor, and
+  RX/TX connected without anything in series. If you need to level shift the signal going into the
+  esp8266's RX use a 1K resistor. Use 115200 baud in the flasher.
+  (For a permanent set-up I would use higher resistor values but
+  when nothing seems to work these are the ones I try.)
+- if the flashing succeeded, check the "conn" LED to see which mode esp-link is in (see LED info above)
 - reset or power-cycle the esp-link to force it to become an access-point if it can't
   connect to your network within 15-20 seconds
 - if the LED says that esp-link is on your network but you can't get to it, make sure your
@@ -188,7 +217,15 @@ A few notes from others (I can't fully verify these):
 - Make sure the paths at the beginning of the makefile are correct
 - Make sure `esp-open-sdk/xtensa-lx106-elf/bin` is in the PATH set in the Makefile
 
-Flashing the firmware
+It is possible to build esp-link on Windows, but it requires a gaggle of software to be installed:
+- Install the unofficial sdk, mingw, SourceTree (gui git client), python 2.7, git cli, Java
+- Use SourceTree to checkout under C:\espressif or wherever you installed the unofficial sdk,
+  (see this thread for the unofficial sdk http://www.esp8266.com/viewtopic.php?t=820)
+- Create a symbolic link under c:/espressif for the git bin directory under program files and
+  the java bin directory under program files.
+- ...
+
+Updating the firmware over-the-air
 ---------------------
 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`
@@ -198,10 +235,11 @@ If you are downloading firmware binaries use `./wiflash`.
 You can easily do that using something like `ESP_HOSTNAME=192.168.1.5 make wiflash`.
 
 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
+and is fully automatic. The first 1MB of flash are divided into two 512KB 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.
+using curl as opposed to having the module download it from a cloud server. On a module with
+512KB flash there is only space for one partition and thus no way to do an OTA update.
 
 If you are downloading the binary versions of the firmware (links forthcoming) you need to have
 both `user1.bin` and `user2.bin` handy and run `wiflash.sh <esp-hostname> user1.bin user2.bin`.
@@ -220,12 +258,37 @@ Serial bridge and connections to Arduino, AVR, ARM, LPC microcontrollers
 In order to connect through the esp-link to a microcontroller use port 23. For example,
 on linux you can use `nc esp-hostname 23` or `telnet esp-hostname 23`.
 
-You can reprogram an Arduino / AVR microcontroller by pointing avrdude at port 23. Instead of
+Note that multiple connections to port 23 and 2323 can be made simultaneously. Esp-link will
-specifying a serial port of the form /dev/ttyUSB0 use `net:esp-link:23` with avrdude's -P option
+intermix characters received on all these connections onto the serial TX and it will
-(where `esp-link` is either the hostname of your esp-link or its IP address).
+broadcast incoming characters from the serial RX to all connections. Use with caution!
-The esp-link detects that avrdude starts its connection with a flash synchronization sequence
+
+### Flashing an attached AVR/Arduino
+
+There are three options for reprogramming an attached AVR/Arduino microcontroller:
+- Use avrdude and point it at port 23 of esp-link. Esp-link automatically detects the programming
+  sequence and issues a reset to the AVR.
+- Use avrdude and point it at port 2323 of esp-link. This is the same as port 23 except that the
+  autodectection is not used and the reset happens because port 2323 is used
+- Use curl or a similar tool to HTTP POST the firmware to esp-link. This uses the built-in
+  programmer, which only works for AVRs/Arduinos with the optiboot bootloader (which is std).
+
+To reprogram an Arduino / AVR microcontroller by pointing avrdude at port 23 or 2323 you
+specify a serial port of the form `net:esp-link:23` in avrdude's -P option, where
+`esp-link` is either the hostname of your esp-link or its IP address).
+This is instead of specifying a serial port of the form /dev/ttyUSB0.
+Esp-link detects that avrdude starts its connection with a flash synchronization sequence
 and sends a reset to the AVR microcontroller so it can switch into flash programming mode.
 
+To reprogram using the HTTP POST method you need to first issue a POST to put optiboot into
+programming mode: POST to `http://esp-link/pgm/sync`, this starts the process. Then check that
+synchronization with optiboot has been achieved by issuing a GET to the same URL
+(`http://esp-link/pgm/sync`). Repeat until you have sync (takes <500ms normally). Finally
+issue a POST request to `http://esp-link/pgm/upload` with your hex file as POST data (raw,
+not url-encoded or multipart-mime. Please look into the avrflash script for the curl command-line
+details or use that script directly (`./avrflash esp-link.local my_sketch.hex`).
+
+### Flashing an attached ARM processor
+
 You can reprogram NXP's LPC800-series and many other ARM processors as well by pointing your
 programmer similarly at the esp-link's port 23. For example, if you are using
 https://github.com/jeelabs/embello/tree/master/tools/uploader a command line like
@@ -235,9 +298,12 @@ make esp-link issue the appropriate "ISP" and reset sequence to the microcontrol
 flash programming. If you use a different ARM programming tool it will work as well as long as
 it starts the connection with the `?\r\n` synchronization sequence.
 
-Note that multiple connections to port 23 can be made simultaneously. The esp-link will
+### Flashing an attached esp8266
-intermix characters received on all these connections onto the serial TX and it will
+
-broadcast incoming characters from the serial RX to all connections. Use with caution!
+(This is not well tested, more details forthcoming...)
+Yes, you can use esp-link running on one esp8266 module to flash another esp8266 module!
+For this to work you need a special version of esptool.py that has support for serial over
+telnet.
 
 Debug log
 ---------