convert readme to asciidoc

README.adoc

@@ -1,36 +1,54 @@
-ESP-LINK
+ESP-LINK: Wifi-Serial Bridge w/REST&MQTT
-========
+========================================
+Thorsten von Eicken
+:toc:
+:toc-title!:
+:toc-placement!:
 
 This firmware connects an attached micro-controller to the internet using a ESP8266 Wifi module.
 It implements a number of features:
+
+[options="compact"]
 - transparent bridge between Wifi and serial, useful for debugging or inputting into a uC
 - flash-programming attached Arduino/AVR microcontrollers, esp8266 modules, as well as
   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
+- built-in stk500v1 programmer for AVR uC's: 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
-- outbound REST HTTP requests from the attached micro-controller to the internet, protocol
+- MQTT client pub/sub from the attached micro-controller to the internet
-  based on espduino and compatible with [tuanpmt/espduino](https://github.com/tuanpmt/espduino)
 
 The firmware includes a tiny HTTP server based on
-[esphttpd](http://www.esp8266.com/viewforum.php?f=34)
+http://www.esp8266.com/viewforum.php?f=34[esphttpd]
 with a simple web interface, many thanks to Jeroen Domburg for making it available!
+The REST and MQTT functionality are loosely based on https://github.com/tuanpmt/espduino
+but significantly reqritten and no longer protocol compatible, thanks to tuanpmt for the
+inspiration!
 
 Many thanks to https://github.com/brunnels for contributions in particular around the espduino
 functionality. Thank you also to https://github.com/susisstrolch and https://github.com/bc547 for
 additional contributions!
 
-###[Releases & Downloads](https://github.com/jeelabs/esp-link/releases)
+[float]
+Table of Contents
+-----------------
+
+toc::[]
+
+Releases & Downloads
+--------------------
 
-- [V2.1.7](https://github.com/jeelabs/esp-link/releases/tag/v2.1.7) is the most recent release.
+- https://github.com/jeelabs/esp-link/releases/tag/v2.1.7[V2.1.7] is the most recent release.
   It has the new built-in stk500v1 programmer and works on all modules (esp-01 through esp-12).
-- [V2.2.beta1](https://github.com/jeelabs/esp-link/releases/tag/v2.2.beta1) will be coming
+- https://github.com/jeelabs/esp-link/releases/tag/v2.2.beta2[V2.2.beta2] will be coming
   up shortly with mDNS, sNTP, and syslog support, stay tuned...
+- See https://github.com/jeelabs/esp-link/releases[all releases].
 
-For quick support and questions:
+For quick support and questions chat at
-[![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)
+image:https://badges.gitter.im/Join%20Chat.svg[link="https://gitter.im/jeelabs/esp-link"]
 
-Esp-link goals
+Intro
---------------
+-----
+
+### Esp-link goals
 
 The goal of the esp-link project is to create an advanced Wifi co-processor. Esp-link assumes that
 there is a "main processor" (also referred to as "attached uController") and that esp-link's role
@@ -38,6 +56,7 @@ is to facilitate communication over Wifi. Where esp-link is a bit unusual is tha
 just a Wifi interface or a slave co-processor. In some sense it's the master, because the main
 processor can be reset, controlled and reprogrammed through esp-link. The three main areas of
 functionality in esp-link are:
+
 - reprogramming and debugging the attached uC
 - letting the attached uC make outbound communication and offloading the protocol processing
 - forwarding inbound communication and offloading the protocol processing (this part is the
@@ -49,8 +68,8 @@ actuators directly to it. A few users have taken esp-link as a starting point fo
 things and that's great, but there's also value in keeping the mainline esp-link project
 focused on a clear mission.
 
-Esp-link uses
+### Esp-link uses
--------------
+
 The simplest use of esp-link is as a transparent serial to wifi bridge. You can flash an attached
 uC over wifi and you can watch the uC's serial debug output by connecting to port 23 or looking
 at the uC Console web page.
@@ -71,26 +90,31 @@ the attached uC registers callbacks at start-up such that the code in the esp do
 know which exact sensors/actuators the attached uC has, it learns that through the initial
 callback registration.
 
-Eye Candy
+### Eye Candy
----------
+
 These screen shots show the Home page, the Wifi configuration page, the console for the
 attached microcontroller, and the pin assignments card:
 
-<img width="45%" src="https://cloud.githubusercontent.com/assets/39480/8261425/6ca395a6-167f-11e5-8e92-77150371135a.png">
+image:https://cloud.githubusercontent.com/assets/39480/8261425/6ca395a6-167f-11e5-8e92-77150371135a.png[width="45%"]
-<img width="45%" src="https://cloud.githubusercontent.com/assets/39480/8261427/6caf7326-167f-11e5-8085-bc8b20159b2b.png">
+image:https://cloud.githubusercontent.com/assets/39480/8261427/6caf7326-167f-11e5-8085-bc8b20159b2b.png[width="45%"]
-<img width="45%" src="https://cloud.githubusercontent.com/assets/39480/8261426/6ca7f75e-167f-11e5-827d-9a1c582ad05d.png">
+image:https://cloud.githubusercontent.com/assets/39480/8261426/6ca7f75e-167f-11e5-827d-9a1c582ad05d.png[width="45%"]
-<img width="30%" src="https://cloud.githubusercontent.com/assets/39480/8261658/11e6c64a-1681-11e5-82d0-ea5ec90a6ddb.png">
+image:https://cloud.githubusercontent.com/assets/39480/8261658/11e6c64a-1681-11e5-82d0-ea5ec90a6ddb.png[width="45%"]
+
+Getting Started
+---------------
+
+### Hardware configuration
 
-Hardware info
--------------
 This firmware is designed for any esp8266 module.
 The recommended connections for an esp-01 module 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
@@ -102,6 +126,7 @@ The recommended connections for an esp-12 module are:
 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
@@ -115,10 +140,10 @@ seen both used, sigh).
 
 The GPIO pin assignments can be changed dynamically in the web UI and are saved in flash.
 
-Initial flashing
+### Initial flashing
-----------------
+
 If you want to simply flash a pre-built firmware binary, you can download the latest
-[release](https://github.com/jeelabs/esp-link/releases) and use your favorite
+https://github.com/jeelabs/esp-link/releases[release] and use your favorite
 ESP8266 flashing tool to flash the bootloader, the firmware, and blank settings.
 Detailed instructions are provided in the release notes.
 
@@ -127,16 +152,17 @@ stored in the boot sector (address 0). This is the standard way that the esp8266
 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
+### Wifi configuration overview
-------------------
+
 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 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. esp-link creates a wifi access point with an SSID of the form `ESP_012ABC` (some modules
     use a different SSID form, such as `ai-thinker-012ABC`)
  2. you join your laptop or phone to esp-link's network as a station and you configure
-    esp-link wifi with your network info by pointing your browser at http://192.168.4.1/
+    esp-link wifi with your network info by pointing your browser at `http://192.168.4.1/`
  3. you set a hostname for esp-link on the "home" page, or leave the default ("esp-link")
  4. 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 `${hostname}.local` hostname
@@ -145,10 +171,11 @@ to join its network to configure it. The short version is:
     you reconnect your laptop/phone to your normal network and access esp-link via its hostname
     or IP address
 
-LED indicators
+### LED indicators
---------------
+
 Assuming appropriate hardware attached to GPIO pins, the green "conn" LED will show the wifi
 status as follows:
+
 - Very short flash once a second: not connected to a network and running as AP+STA, i.e.
   trying to connect to the configured network
 - Very short flash once every two seconds: not connected to a network and running as AP-only
@@ -158,8 +185,31 @@ status as follows:
 
 The yellow "ser" LED will blink briefly every time serial data is sent or received by the esp-link.
 
-Wifi configuration details
+### 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
+- 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
+  laptop is on the same network (and no longer on the esp's network)
+- if you do not know the esp-link's IP address on your network, try `esp-link.local`, try to find
+  the lease in your DHCP server; if all fails, you may have to turn off your access point (or walk
+  far enough away) and reset/power-cycle esp-link, it will then fail to connect and start its
+  own AP after 15-20 seconds
+
+Configuration details
+---------------------
+
+### Wifi
+
 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
@@ -193,11 +243,12 @@ used to configure the ssid/password info. The problem is that the initial STA+AP
 channel 1 and you configure it to connect to an AP on channel 6. This requires the ESP8266's AP
 to also switch to channel 6 disconnecting you in the meantime. 
 
-Hostname, description, DHCP, mDNS
+### Hostname, description, DHCP, mDNS
----------------------------------
+
 You can set a hostname on the "home" page, this should be just the hostname and not a domain
 name, i.e., something like "test-module-1" and not "test-module-1.mydomain.com".
 This has a number of effects:
+
 - you will see the first 12 chars of the hostname in the menu bar (top left of the page) so
   if you have multiple modules you can distinguish them visually
 - esp-link will use the hostname in its DHCP request, which allows you to identify the module's
@@ -212,36 +263,19 @@ You can also enter a description of up to 128 characters on the home page (botto
 allows you to leave a memo for yourself, such as "installed in basement to control the heating
 system". This descritpion is not used anywhere else.
 
-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
-- 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
-  laptop is on the same network (and no longer on the esp's network)
-- if you do not know the esp-link's IP address on your network, try `esp-link.local`, try to find
-  the lease in your DHCP server; if all fails, you may have to turn off your access point (or walk
-  far enough away) and reset/power-cycle esp-link, it will then fail to connect and start its
-  own AP after 15-20 seconds
-
 Building the firmware
 ---------------------
-The firmware has been built using the [esp-open-sdk](https://github.com/pfalcon/esp-open-sdk)
+
+### Linux
+
+The firmware has been built using the https://github.com/pfalcon/esp-open-sdk[esp-open-sdk]
 on a Linux system. Create an esp8266 directory, install the esp-open-sdk into a sub-directory
 using the *non-standalone* install (i.e., there should not be an sdk directory in the esp-open-sdk
 dir when done installing, if you use the standalone install you will get compilation errors
 with std types, such as `uint32_t`).
 
 Download the Espressif SDK (use the version mentioned in the release notes) from their
-[download forum](http://bbs.espressif.com/viewforum.php?f=5) and also expand it into a
+http://bbs.espressif.com/viewforum.php?f=5[download forum] and also expand it into a
 sub-directory.
 
 Clone the esp-link repository into a third sub-directory and check out the tag you would like,
@@ -260,12 +294,16 @@ Now, build the code: `make` in the top-level of esp-link. If you want to se the
 issued, use `VERBOSE=1 make`.
 
 A few notes from others (I can't fully verify these):
+
 - You may need to install `zlib1g-dev` and `python-serial`
 - Make sure you have the correct version of the esp_iot_sdk
 - 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
 
+### Windows
+
 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)
@@ -273,8 +311,8 @@ It is possible to build esp-link on Windows, but it requires a gaggle of softwar
   the java bin directory under program files.
 - ...
 
-Updating the firmware over-the-air
+### 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`
 if you are also building the firmware.
@@ -303,6 +341,7 @@ The flash configuration and the OTA upgrade process is described in more detail
 
 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`.
 
@@ -313,6 +352,7 @@ broadcast incoming characters from the serial RX to all connections. Use with ca
 ### 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
@@ -350,11 +390,13 @@ If your AVR doesn't use optiboot then use port 2323 since esp-link may not recog
 sequence and not issue a reset if you use port 23.
 
 If you are having trouble with the built-in programmer and see something like this:
-```
+
+--------------------
 # ./avrflash 192.168.3.104 blink.hex
 Error checking sync: FAILED to SYNC: abandoned after timeout, got:
 :\xF/\x00\xCj\xCz\xCJ\xCZ\xC\xAÜ\xC\xAä\xC\xAÜ\xC\xAä\xC\xBì\xC\xBô\xC\xBì\xC\xBô\xC\xAÜ\xC\xAä\xC
-```
+--------------------
+
 the most likely cause is a baud rate mismatch and/or a bad connection from the esp8266 to the
 AVRs reset line.
 The baud rate used by esp-link is set on the uC Console web page and, as mentioned above, it will
@@ -366,9 +408,11 @@ correct baud rate configured but reset isn't functioning, or reset may be functi
 baud rate may be incorrect.
 
 The output of a successful flash using the built-in programmer looks like this:
-```
+
+--------------------
 Success. 3098 bytes at 57600 baud in 0.8s, 3674B/s 63% efficient
-```
+--------------------
+
 This says that the sketch comprises 3098 bytes of flash, was written in 0.8 seconds
 (excludes the initial sync time) at 57600 baud,
 and the 3098 bytes were flashed at a rate of 3674 bytes per second.
@@ -378,7 +422,7 @@ The efficiency is not 100% because there is protocol overhead (such as sync, rec
 length characters)
 and there is dead time waiting for an ack or preparing the next record to be sent.
 
-#### Details of built-in AVR flash algorithm
+### Details of built-in AVR flash algorithm
 
 The built-in flashing algorithm differs a bit from what avrdude does. The programming protocol
 states that STK_GET_SYNC+CRC_EOP (0x30 0x20) should be sent to synchronize, but that works poorly
@@ -436,7 +480,7 @@ baud rate to 115200 is recommended.)
 
 Another option is to use a serial-to-tcp port forwarding driver and point that to port 2323
 of esp-link. On windows users have reported success with
-[HW Virtual Serial Port](http://www.hw-group.com/products/hw_vsp/hw_vsp2_en.html)
+http://www.hw-group.com/products/hw_vsp/hw_vsp2_en.html[HW Virtual Serial Port]
 
 Now to the interference problem: once the attached esp8266 is reset it
 starts outputting its 26Mhz clock on gpio0, which needs to be attached to
@@ -453,12 +497,13 @@ add a series 100ohm resistor and 100pf capacitor to ground as close to
 the gpio0 pin as possible (basically a low pass filter); and/or pass
 the cable connecting the two esp8266's through a ferrite bead.
 
-Debug log
+### Debug log
----------
+
 The esp-link web UI can display the esp-link debug log (os_printf statements in the code). This
 is handy but sometimes not sufficient. Esp-link also prints the debug info to the UART where
 it is sometimes more convenient and sometimes less... For this reason three UART debug log
 modes are supported that can be set in the web UI (and the mode is saved in flash):
+
 - auto: the UART log starts enabled at boot using uart0 and disables itself when esp-link
   associates with an AP. It re-enables itself if the association is lost.
 - off: the UART log is always off
@@ -470,7 +515,8 @@ esp8266 comes out of reset. This cannot be disabled.
 
 Outbound HTTP REST requests and MQTT client
 -------------------------------------------
-The V2 versions of esp-link support the espduino SLIP protocol that supports simple outbound
+
+The V2 versions of esp-link use the SLIP protocol over the serial link to support simple outbound
 HTTP REST requests as well as an MQTT client. The SLIP protocol consists of commands with
 binary arguments sent from the
 attached microcontroller to the esp8266, which then performs the command and responds back.
@@ -479,13 +525,11 @@ command sent by the uC contains a callback address and the response from the esp
 with that callback address. This enables asynchronous communication where esp-link can notify the
 uC when requests complete or when other actions happen, such as wifi connectivity status changes.
 
-You can find a demo sketch in a fork of the espduino library at
+You can find REST and MQTT libraries as well as demo sketches in the
-https://github.com/tve/espduino in the
+https://github.com/jeelabs/el-client[el-client] repository.
-[examples/demo folder](https://github.com/tve/espduino/tree/master/espduino/examples/demo).
-
-More docs forthcoming...
 
 Contact
 -------
+
 If you find problems with esp-link, please create a github issue. If you have a question, please
 use the gitter chat link at the top of this page.