@ -3,7 +3,7 @@ ESP-LINK
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
LPC800-series ARM microcontrollers via the ESP8266.
LPC800-series and other ARM microcontrollers via the ESP8266.
The firmware includes a tiny HTTP server based on
[esphttpd ](http://www.esp8266.com/viewforum.php?f=34 )
@ -11,10 +11,12 @@ with a simple web interface, many thanks to Jeroen Domburg for making it availab
[](https://gitter.im/jeelabs/esp-link?utm_source=badge& utm_medium=badge& utm_campaign=pr-badge& utm_content=badge)
[_Latest release_ ](releases )
Eye Candy
---------
These screen shots show the Home page, the Wifi configuration page, the console for the attached microcontroller,
and the pin assignments card:
These screen shots show the Home page, the Wifi configuration page, the console for the
attached microcontroller, a nd the pin assignments card:
< img width = "45%" src = "https://cloud.githubusercontent.com/assets/39480/8261425/6ca395a6-167f-11e5-8e92-77150371135a.png" >
< img width = "45%" src = "https://cloud.githubusercontent.com/assets/39480/8261427/6caf7326-167f-11e5-8085-bc8b20159b2b.png" >
@ -23,7 +25,8 @@ and the pin assignments card:
Hardware info
-------------
This firmware is designed for esp8266 modules which have most ESP I/O pins available.
This firmware is designed for esp8266 modules which have most ESP I/O pins available and
512KB flash.
The default connections are:
- URXD: connect to TX of microcontroller
- UTXD: connect to RX of microcontroller
@ -34,17 +37,15 @@ The default connections are:
If you are using an FTDI connector, GPIO12 goes to DTR and GPIO13 goes to CTS.
The GPIO pin assignments can be changed dynamicall in the web UI and are saved in flash.
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!)
(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 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 following:
- `boot_v1.3(b3).bin` to 0x00000
- `blank.bin` to 0x7e000
- `user1.bin` to 0x01000
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
modules appear to have. A larger flash chip should work but has not been tested.
@ -56,11 +57,14 @@ 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
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`
2. you join your laptop to the esp-link's network as a station and you configure
2. you join your laptop or phone to the esp-link's network as a station and you configure
the esp-link wifi with your network info by pointing your browser at http://192.168.4.1/
3. the 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 the esp-link.local hostname (depends on your DHCP/DNS config)
3. the 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,
you reconnect your laptop/phone to your normal network and access esp-link via its hostname
or IP address
LED indicators
--------------
@ -70,8 +74,8 @@ status as follows:
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 15 seconds)
- 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 15 seconds)
The yellow "ser" LED will blink briefly every time serial data is sent or received by the esp-link.
@ -86,8 +90,9 @@ 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.
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
@ -104,17 +109,22 @@ cannot connect to your network it will revert back to AP+STA mode after 15 secon
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.
Troubleshooting
---------------
- verify that you have sufficient power, borderline power can cause the esp module to seemingly
function until it tries to transmit
- check the "conn" LED to see which mode esp-link is in (LED info above)
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)
- 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
- if you do not know the esp-link's IP address on your network, try ` esp-link.local`
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
@ -122,38 +132,32 @@ Building the firmware
---------------------
The firmware has been built using the [esp-open-sdk ](https://github.com/pfalcon/esp-open-sdk )
on a Linux system. Create an esp8266 directory, install the esp-open-sdk into a sub-directory.
Download the Espressif SDK (1.1.2) and also expand it into a sub-directory. Then clone
this repository into a third sub-directory. This way the relative paths in the Makefile will work.
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
sub-directory. Then clone the esp-link repository into a third sub-directory.
This way the relative paths in the Makefile will work.
If you choose a different directory structure look at the Makefile for the appropriate environment
variables to define. (I have not used the esptool for flashing, so I don't know whether what's
in the Makefile for that works or not.)
variables to define.
In order to OTA-update the esp8266 you should `export ESP_HOSTNAME=...` with the hostname or
IP address of your module.
This project makes use of heatshrink, which is a git submodule. To fetch the code:
```
cd esp-link
git submodule init
git submodule update
```
Now, build the code: `make` in the top-level of esp-link.
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 (v1.1.2 with scan patch for
esp-link release 0.10.0)
- 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
- Make sure `esp-open-sdk/xtensa-lx106-elf/bin` is in the PATH set in the Makefile
Flashing the firmware
---------------------
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.
If you are downloading firmware binaries use `./wiflash.sh ` .
If you are downloading firmware binaries use `./wiflash` .
`make wiflash` assumes that you set `ESP_HOSTNAME` to the hostname or IP address of your esp-link.
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
@ -171,11 +175,12 @@ reconnect to your network within a few seconds and the whole flashing process sh
from beginning to end. If you need to clear the wifi settings you need to reflash the `blank.bin`
using the serial port.
The flash configuration and the OTA upgrade process is described in more detail in flash.md
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` . (There seems to be
a problem with the telnet program, please use nc instead for now.)
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
specifying a serial port of the form /dev/ttyUSB0 use `net:esp-link:23` with avrdude's -P option
@ -183,10 +188,10 @@ specifying a serial port of the form /dev/ttyUSB0 use `net:esp-link:23` with avr
The 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.
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
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
`uploader -t -s -w esp-link:23 build/firmware.bin` should do the trick.
`uploader -t -s -w esp-link:23 build/firmware.bin` does the trick.
The way it works is that the uploader uses telnet protocol escape sequences in order to
make esp-link issue the appropriate "ISP" and reset sequence to the microcontroller to start the
flash programming. If you use a different ARM programming tool it will work as well as long as
@ -196,81 +201,21 @@ Note that multiple connections to port 23 can be made simultaneously. The esp-li
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!
Flash layout
------------
The flash layout dictated by the bootloader is the following (all this assumes a 512KB flash chip
and is documented in Espressif's `99C-ESP8266__OTA_Upgrade__EN_v1.5.pdf` ):
- @0x00000 4KB bootloader
- @0x01000 236KB partition1
- @0x3E000 16KB esp-link parameters
- @0x40000 4KB unused
- @0x41000 236KB partition2
- @0x7E000 16KB system wifi parameters
What this means is that we can flash just about anything into partition1 or partition2 as long
as it doesn't take more than 236KB and has the right format that the boot loader understands.
We can't mess with the first 4KB nor the last 16KB of the flash.
Now how does a code partition break down? that is reflected in the following definition found in
the loader scripts:
```
dram0_0_seg : org = 0x3FFE8000, len = 0x14000
iram1_0_seg : org = 0x40100000, len = 0x8000
irom0_0_seg : org = 0x40201010, len = 0x2B000
```
This means that 80KB (0x14000) are reserved for "dram0_0", 32KB (0x8000) for "iram1_0" and
172KB (0x2B000) are reserved for irom0_0. The segments are used as follows:
- dram0_0 is the data RAM and some of that gets initialized at boot time from flash (static variable initialization)
- iram1_0 is the instruction RAM and all of that gets loaded at boot time from flash
- irom0_0 is the instruction cache which gets loaded on-demand from flash (all functions
with the `ICACHE_FLASH_ATTR` attribute go there)
You might notice that 80KB+32KB+172KB is more than 236KB and that's because not the entire dram0_0
segment needs to be loaded from flash, only the portion with statically initialized data.
You might also notice that while iram1_0 is as large as the chip's instruction RAM (at least
according to the info I've seen) the size of the irom0_0 segment is smaller than it could be,
since it's really not bounded by any limitation of the processor (it simply backs the cache).
When putting the OTA flash process together I ran into loader issues, namely, while I was having
relatively little initialized data and also not 32KB of iram1_0 instructions I was overflowing
the allotted 172KB of irom0_0. To fix the problem the build process modifies the loader scripts
(see the `build/eagle.esphttpd1.v6.ld` target in the Makefile) to increase the irom0_0 segment
to 224KB (a somewhat arbitrary value). This doesn't mean that there will be 224KB of irom0_0
in flash, it just means that that's the maximum the linker will put there without giving an error.
In the end what has to fit into the magic 236KB is the sum of the actual initialized data,
the actually used iram1_0 segment, and the irom0_0 segment.
In addition, the dram0_0 and iram1_0 segments can't exceed what's specified
in the loader script 'cause those are the limitations of the processor.
Now that you hopefully understand the above you can understand the line printed by the Makefile
when linking the firmware, which looks something like:
```
** user1.bin uses 218592 bytes of 241664 available
```
Here 241664 is 236KB and 218592 is the size of what's getting flashed, so you can tell that you have
another 22KB to spend (modulo some 4KB flash segment rounding).
(Note that user2.bin has exactly the same size, so the Makefile doesn't print its info.)
The Makefile also prints a few more details:
```
ls -ls eagle*bin
4 -rwxrwxr-x 1 tve tve 2652 May 24 10:12 eagle.app.v6.data.bin
176 -rwxrwxr-x 1 tve tve 179732 May 24 10:12 eagle.app.v6.irom0text.bin
8 -rwxrwxr-x 1 tve tve 5732 May 24 10:12 eagle.app.v6.rodata.bin
32 -rwxrwxr-x 1 tve tve 30402 May 24 10:12 eagle.app.v6.text.bin
```
This says that we have 179732 bytes of irom0_0, we have 5732+2652 bytes of dram0_0 (read-only data
plus initialized read-write data), and we have 30402 bytes of iram1_0.
There's an additional twist to all this for the espfs "file system" that esphttpd uses.
The data for this is loaded at the end of irom0_0 and is called espfs.
The Makefile modifies the loader script to place the espfs at the start of irom0_0 and
ensure that it's 32-bit aligned. The size of the espfs is shown here:
```
4026be14 g .irom0.text 00000000 _binary_espfs_img_end
40269e98 g .irom0.text 00000000 _binary_espfs_img_start
00001f7c g *ABS* 00000000 _binary_espfs_img_size
```
Namely, 0x1f7c = 8060 bytes.
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 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
- on: the UART log is always on
Note that even if the UART log is always off the bootloader prints to uart0 whenever the
esp8266 comes out of reset. This cannot be disabled.
Contact
-------
If you find problems with esp-link, please create a github issue. If you have a question, please
use the gitter link at the top of this page.
Thorsten von Eicken
9 years ago