doc tweaks

TROUBLESHOOTING.md

@@ -0,0 +1,36 @@
+Esp-Link troubleshooting
+========================
+
+### 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
+
+### 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
+- Even on/off at 1HZ: connected to the configured network but no IP address (waiting on DHCP)
+- Steady on with very short off every 3 seconds: connected to the configured network with an
+  IP address (esp-link shuts down its AP after 60 seconds)
+
+The yellow "ser" LED will blink briefly every time serial data is sent or received by the esp-link.

WIFI-CONFIG.md

@@ -0,0 +1,87 @@
+Esp-link Wifi configuration
+===========================
+
+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/`
+ 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
+    (depends on your DHCP/DNS config)
+ 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
+
+### Notes on using AP (access point) mode
+
+Esp-link does not support STA+AP mode, however it does support STA mode and AP mode. What happens
+is that STA+AP mode is used at boot and when making STA changes to allow for recovery: the AP
+mode stays on for a while so you can connect to it and fix the STA mode. Once STA has connected,
+esp-link switches to STA-only mode. There is no setting to stay in STA+AP mode. So... if you want
+to use AP ensure you set esp-link to AP-only mode. If you want STA+AP mode you're gonna have to
+modify the source for yourself. (This stuff is painful to test and rather tricky, so don't expect
+the way it works to change.)
+
+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
+http://192.168.4.1/, you should then see the esp-link web site.
+
+Now configure the wifi. The desired configuration is for the esp-link to be a
+station on your local wifi network so you can communicate with it from all your computers.
+
+To make this happen, navigate to the wifi page and you should see the esp-link scan
+for available networks. You should then see a list of detected networks on the web page and you
+can select yours.
+Enter a password if your network is secure (highly recommended...) and hit the connect button.
+
+You should now see that the esp-link has connected to your network and it should show you
+its IP address. _Write it down_. You will then have to switch your laptop, phone, or tablet
+back to your network and then you can connect to the esp-link's IP address or, depending on your
+network's DHCP/DNS config you may be able to go to http://esp-link.local
+
+At this point the esp-link 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`
+via the serial port as indicated above will reset the wifi settings.
+
+There is a fail-safe, which is that after a reset or a configuration change, if the esp-link
+cannot connect to your network it will revert back to AP+STA mode after 15 seconds and thus
+both present its `ESP_012ABC`-style network and continue trying to reconnect to the requested network.
+You can then connect to the esp-link's AP and reconfigure the station part.
+
+One open issue (#28) is that esp-link cannot always display the IP address it is getting to the browser
+used to configure the ssid/password info. The problem is that the initial STA+AP mode may use
+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
+
+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
+  MAC and IP addresses in your DHCP server (typ. your wifi router). In addition, some DHCP
+  servers will inject these names into the local DNS cache so you can use URLs like
+  `hostname.local`.
+- someday, esp-link will inject the hostname into mDNS (multicast DNS, bonjour, etc...) so 
+  URLs of the form `hostname.local` work for everyone (as of v2.1.beta5 mDNS is disabled due
+  to reliability issues with it)
+
+You can also enter a description of up to 128 characters on the home page (bottom right). This
+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.