diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md new file mode 100644 index 0000000..be18e7d --- /dev/null +++ b/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. diff --git a/UCFLASHING.md b/UC-FLASHING.md similarity index 100% rename from UCFLASHING.md rename to UC-FLASHING.md diff --git a/WIFI-CONFIG.md b/WIFI-CONFIG.md new file mode 100644 index 0000000..02e13c3 --- /dev/null +++ b/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.