wirtz
/
esp-link
mirror of https://github.com/jeelabs/esp-link.git
1
0
Fork 0
Code Issues Releases Wiki Activity

docs update

Browse Source
pull/200/head
Thorsten von Eicken 9 years ago
parent 8c495362a2
commit 08a426c50a
No known key found for this signature in database
GPG Key ID: C7F972A59D834B46
3 changed files with 152 additions and 52 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 41
      BUILDING.md
  2. 151
      FLASHING.md
  3. 12
      README.md

41
BUILDING.md
Unescape View File

@ -108,42 +108,5 @@ Please consider installing docker and using the docker image to save yourself gr
the tools installed and working. the tools installed and working.
If you do want to compile "natively" on Windows it certainly is possible. If you do want to compile "natively" on Windows it certainly is possible.
It is possible to build esp-link on Windows, but it requires a gaggle of software to be installed: It is possible to build esp-link on Windows, but it requires a
[gaggle of software to be installed](WINDOWS.md)
- 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`
if you are also building the firmware.
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` or
`ESP_HOSTNAME=es-link.local make wiflash`.
The flashing, restart, and re-associating with your wireless network takes about 15 seconds
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. 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 prebuilt firmware image you will have both
`user1.bin` and `user2.bin` and run `wiflash.sh <esp-hostname> user1.bin user2.bin`.
This will query esp-link for which file it needs, upload the file, and then reconnect to
ensure all is well.
Note that when you flash the firmware the wifi settings are all preserved so esp-link should
reconnect to your network within a few seconds and the whole flashing process should take 15-30
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](FLASH.md). If OTA flashing doesn't work for you the serial flashing is described
in [FLASHING.md](FLASHING.md).

151
FLASHING.md
Unescape View File

@ -40,12 +40,153 @@ The GPIO pin assignments can be changed dynamically in the web UI and are saved
### Initial serial flashing ### Initial serial flashing
If you want to simply flash a pre-built firmware binary, you can download the latest Download the latest [release](https://github.com/jeelabs/esp-link/releases) or use the
[release](https://github.com/jeelabs/esp-link/releases) and use your favorite `user1.bin` and `user2.bin` files that are produced by the build process.
ESP8266 flashing tool to flash the bootloader, the firmware, and blank settings. You will need to flash the bootloader, the firmware, blank wifi settings, and init data.
Detailed instructions are provided in the release notes. Detailed instructions are provided in the release notes.
_Important_: the firmware adapts automatically to the size of the flash chip using information _Important_: the firmware adapts to the size of the flash chip using information
stored in the boot sector (address 0). This is the standard way that the esp8266 SDK detects 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. 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. If you use esptool.py you can do it using the -ff and -fs options. See the end of this page for
instructions on installing esptool.py.
The short version for the serial flashing is:
- flash `boot_v1.X.bin` from the official SDK or from the release tgz to `0x00000`
- flash `blank.bin` from the official SDK or from the tgz to `0x3FE000`
- flash `esp_init_data_default.bin` from the official SDK or from the tgz to `0x3FC000`
- flash `user1.bin` to `0x01000`
- be sure to use the commandline flags when flashing the bootloader to set the correct flash size
- some of the addresses vary with flash chip size
After the initial flashing if you want to update the firmware it is recommended to use the
over-the-air update described further down. If you want to update serially you only need to
reflash `user1.bin`.
### 32Mbit / 4Mbyte module
On Linux using esptool.py this turns into the following for a 32mbit=4MByte flash chip,
such as an esp-12 module typically has (_substitute the appropriate release number and bootloader
version number_):
```
curl -L https://github.com/jeelabs/esp-link/releases/download/v2.2.3/esp-link-v2.2.3.tgz | \
tar xzf -
cd esp-link-v2.2.3
esptool.py --port /dev/ttyUSB0 --baud 230400 write_flash -fs 32m -ff 80m \
0x00000 boot_v1.5.bin 0x1000 user1.bin \
0x3FC000 esp_init_data_default.bin 0x3FE000 blank.bin
```
I use a high baud rate as shown above because I'm impatient, but that's not required.
### 4Mbit / 512Kbyte module
```
curl -L https://github.com/jeelabs/esp-link/releases/download/v2.2.3/esp-link-v2.2.3.tgz | \
tar xzf -
cd esp-link-v2.2.3
esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash -fs 4m -ff 40m \
0x00000 boot_v1.5.bin 0x1000 user1.bin \
0x7C000 esp_init_data_default.bin 0x7E000 blank.bin
```
The `-fs 4m -ff40m` options say 4Mbits and 40Mhz as opposed to 32Mbits at 80Mhz for the 4MByte
flash modules. Note the different address for esp_init_data_default.bin and blank.bin
(the SDK stores its wifi settings near the end of flash, so it changes with flash size).
For __8Mbit / 1MByte__ modules the addresses are 0xFC000 and 0xFE000.
## Updating the firmware over-the-air
This firmware supports over-the-air (OTA) flashing for modules with 1MByte or more flash,
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 and `./wiflash` if you are downloading firmware binaries.
The resulting commandlines are:
```
ESP_HOSTNAME=192.168.1.5 make wiflash
```
or assuming mDNS is working:
```
ESP_HOSTNAME=esp-link.local make wiflash
```
or using wiflash.sh:
```
./wiflash.sh <esp-hostname> user1.bin user2.bin
```
The flashing, restart, and re-associating with your wireless network takes about 15 seconds
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. On a module with
512KB flash there is only space for one partition and thus no way to do an OTA update.
If you need to clear the wifi settings you need to reflash the `blank.bin`
using the serial method.
The flash configuration and the OTA upgrade process is described in more detail
in [FLASH.md](FLASH.md).
## Installing esptool.py on Linux
On Linux use [esptool.py](https://github.com/themadinventor/esptool) to flash the esp8266.
If you're a little python challenged then the following install instructions might help:
- Install ez_setup with the following two commands (I believe this will do something
reasonable if you already have it):
wget https://bootstrap.pypa.io/ez_setup.py
python ez_setup.py
- Install esptool.py:
git clone https://github.com/themadinventor/esptool.git
cd esptool
python setup.py install
cd ..
esptool.py -h
## Installing esptool.py on Windows
Esptool is a pythin pgm that works just fine on windows. These instructions assume that git and
python are available from the commandline.
Start a command line, clone esptool, and run `python setup.py install` in esptool's
directory (this step needs to be done only once):
```
> git clone https://github.com/themadinventor/esptool.git
Cloning into 'esptool'...
remote: Counting objects: 268, done.
emote: Total 268 (delta 0), reused 0 (delta 0), pack-reused 268
Receiving objects: 100% (268/268), 99.66 KiB | 0 bytes/s, done.
Resolving deltas: 100% (142/142), done.
Checking connectivity... done.
> cd esptool
> python setup.py install
running install
...
...
...
Finished processing dependencies for esptool==0.1.0
```
Download and unzip the latest esp-link release package, and start a commandline
in that directory. The command to run is pretty much the same as for linux.
Adjust the path to esptool and the COM port if you don't have the ESP on COM12. 460800
baud worked just fine for me, writing at ~260kbit/s instead of ~80kbit/s.
```
>python "../esptool/esptool.py" --port COM12 --baud 115200 write_flash \
--flash_freq 80m --flash_mode qio --flash_size 32m \
0x0000 boot_v1.6.bin 0x1000 user1.bin \
0x3FC000 esp_init_data_default.bin 0x3FE000 blank.bin
Connecting...
Erasing flash...
Wrote 3072 bytes at 0x00000000 in 0.3 seconds (79.8 kbit/s)...
Erasing flash...
Wrote 438272 bytes at 0x00001000 in 43.4 seconds (80.7 kbit/s)...
Erasing flash...
Wrote 1024 bytes at 0x003fc000 in 0.1 seconds (83.6 kbit/s)...
Erasing flash...
Wrote 4096 bytes at 0x003fe000 in 0.4 seconds (83.4 kbit/s)...
Leaving...
```

12
README.md
Unescape View File

@ -70,10 +70,7 @@ and 3.x will be the addition of custom web pages (this is not ready yet).
- [V2.1.7](https://github.com/jeelabs/esp-link/releases/tag/v2.1.7) is the previous release. - [V2.1.7](https://github.com/jeelabs/esp-link/releases/tag/v2.1.7) is the previous release.
- See [all releases](https://github.com/jeelabs/esp-link/releases). - See [all releases](https://github.com/jeelabs/esp-link/releases).
Intro ## Esp-link goals
-----
### Esp-link goals
The goal of the esp-link project is to create an advanced Wifi co-processor. Esp-link assumes that 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 there is a "main processor" (also referred to as "attached uController") and that esp-link's role
@ -96,7 +93,7 @@ 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 things and that's great, but there's also value in keeping the mainline esp-link project
focused on a clear mission. 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 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 uC over wifi and you can watch the uC's serial debug output by connecting to port 23 or looking
@ -118,7 +115,7 @@ 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 know which exact sensors/actuators the attached uC has, it learns that through the initial
callback registration. callback registration.
### Eye Candy ## Eye Candy
These screen shots show the Home page, the Wifi configuration page, the console for the These screen shots show the Home page, the Wifi configuration page, the console for the
attached microcontroller, and the pin assignments card: attached microcontroller, and the pin assignments card:
@ -150,8 +147,7 @@ From there, more advanced steps are:
and forms and forms
- make changes or enhancements to esp-link and build your own firmware - make changes or enhancements to esp-link and build your own firmware
Serial bridge ### Serial bridge
-------------
In order to connect through the esp-link to a microcontroller use port 23. For example, 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`. on linux you can use `nc esp-hostname 23` or `telnet esp-hostname 23`.

Write Preview
Loading…
Cancel
Save