Skip to content

Commit 26127f2

Browse files
donghengqazdonghengqaz
committed
Merge branch 'docs/FOTA_from_old_to_new_sdk_v3.1' into 'release/v3.1'
FOTA from an Old SDK to the New ESP8266 RTOS SDK (IDF Style) (backport v3.1) See merge request sdk/ESP8266_RTOS_SDK!748
2 parents 166d91f + e9ba030 commit 26127f2

File tree

2 files changed

+178
-0
lines changed

2 files changed

+178
-0
lines changed

‎docs/en/api-guides/fota-from-old-new.rst

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
FOTA from an Old SDK to the New ESP8266 RTOS SDK (IDF Style)
2+
*************************************************************
3+
4+
FOTA: firmware over the air, herein it means the firmware upgrading through Wi-Fi.
5+
Since the ESP8266 RTOS SDK V3.0, we refactored the SDK to be the ESP-IDF style. This document introduces the FOTA from a non-OS (or an old RTOS that earlier than V3.0) firmware to the new IDF style RTOS firmware.
6+
Please note that users need to make modifications to the application, because the new APIs are not compatible with the old SDKs', due to underlying changes in the architecture.
7+
8+
SDK Partition Map
9+
=================
10+
11+
Here are the partition maps of the old SDK and the new IDF style RTOS SDK:
12+
13+
1. The Old ESP8266 SDK
14+
----------------------
15+
16+
+------------+------------+------------+-------------------------+
17+
| Boot/4KB | APP1 | APP2 | System Parameter/16KB |
18+
+------------+------------+------------+-------------------------+
19+
20+
2. The New ESP8266 SDK (IDF Style)
21+
----------------------------------
22+
23+
+-------------+-----------------------+-----------+------------+------------+
24+
| Boot/16KB | Partition Table/4KB | NVS | APP1 | APP2 |
25+
+-------------+-----------------------+-----------+------------+------------+
26+
27+
In the new IDF style ESP8266 RTOS SDK SDK, each partition's base address is configurable in menuconfig, except boot's.
28+
29+
Firmware Compatibility
30+
======================
31+
32+
To implement FOTA from an old SDK firmware to the new one, users need to download all necessary partitions of the new firmware (including new boot, new partition table, and new application), into the old one's APP partition.
33+
34+
Then the new bootloader will unpack the packed new firmware, and copy each partition data to the target partition address.
35+
36+
When FOTA completing, the partition map may look like the following graph (what will it be is based on your actual partition table):
37+
38+
+--------------------+-----------------+---------------------------+---------------+----------------+----------------+-------------------------+
39+
| old SDK Boot/4KB | new Boot/16KB | new Partition Table/4KB | new NVS | new APP1 | new APP2 | System Parameter/16KB |
40+
+--------------------+-----------------+-------------------------------------------+----------------+----------------+-------------------------+
41+
42+
In this case, there are about 40KB(4KB + 16KB + 4KB + 16KB) flash size cannot be used by users.
43+
44+
Workflow
45+
========
46+
47+
Herein we provide an example of the FOTA.
48+
49+
Step 1: Connect to AP
50+
----------------------
51+
52+
Connect your host PC and the ESP8266 to the same AP.
53+
54+
Step 2: Configure and Build
55+
-----------------------------
56+
57+
Here, we use the [SP8266_RTOS_SDK/examples/system/ota](https://github.com/espressif/ESP8266_RTOS_SDK/tree/master/examples/system/ota) example.
58+
59+
Open a new terminal on your PC, set the following configurations, and then compile the example:
60+
61+
1. Enter the target directory
62+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
63+
64+
- cd $IDF_PATH/examples/system/ota
65+
66+
2. Enable the OTA compatibility function
67+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
68+
69+
- Component config --->
70+
- ESP8266-specific --->
71+
- [*] (**Expected**)ESP8266 update from old SDK by OTA
72+
73+
3. Configure the target custom partition
74+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
75+
76+
The last 16KB flash, which is used to store system parameters of the old SDKs, must be reserved.
77+
78+
ESP8285(ESP8266 + 1MB flash) configuration:
79+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
80+
81+
Set the file "partitions_two_ota_v2tov3.1MB.csv" to configure the partition of the example. Users can refer to its note for the partition layout.
82+
83+
- Partition Table --->
84+
- Partition Table (Custom partition table CSV) --->
85+
- Custom partition table CSV
86+
- (partitions_two_ota_v2tov3.1MB.csv) Custom partition CSV file
87+
- (0x5000) Partition table offset address at flash
88+
- [*] Support to setup partition parameter of APP2
89+
- (0x7000) APP1 partition offset
90+
- (0x77000) APP1 partition size(by bytes)
91+
- (0x85000) APP2 partition offset
92+
- (0x77000) APP2 partition size(by bytes)
93+
94+
- Partition table offset address at flash: partition table layout address
95+
- APP1 partition offset: ota_0 base address
96+
- APP1 partition size: ota_0 size
97+
- APP2 partition offset: ota_1 base address
98+
- APP2 partition size: ota_1 size
99+
100+
ESP8266 + 2MB(including larger size flash) flash configuration:
101+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
102+
103+
Set the file "partitions_two_ota_v2tov3.2MB.csv" to configure the partition of the example. Users can refer to its note for the partition layout.
104+
105+
- Partition Table --->
106+
- Partition Table (Custom partition table CSV) --->
107+
- Custom partition table CSV
108+
- (partitions_two_ota_v2tov3.2MB.csv) Custom partition CSV file
109+
- (0x8000) Partition table offset address at flash
110+
- (0x10000) APP1 partition offset
111+
- (0xEC000) APP1 partition size(by bytes)
112+
113+
- Partition table offset address at flash: partition table layout address
114+
- APP1 partition offset: ota_0 base address
115+
- APP1 partition size: ota_0 size
116+
117+
Configure the flash size according to your actual development board's flash.
118+
119+
- Serial flasher config --->
120+
- Flash size (x MB) ---> real flash size
121+
122+
123+
4. Configure example's parameters
124+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
125+
126+
- Example Configuration --->
127+
- (myssid) WiFi SSID
128+
- (mypassword) WiFi Password
129+
- (192.168.0.3) HTTP Server IP
130+
- (8070)HTTP Server Port
131+
- (/project_template.ota.bin) HTTP GET Filename
132+
133+
- WiFi SSID: Wi-Fi SSID of router
134+
- WiFi Password: Wi-Fi password of router
135+
- HTTP Server IP: It may be the PC's IP address
136+
- HTTP Server Port: HTTP server port
137+
- HTTP GET Filename: Using "ota.ota.bin" which is the target firmware of the example
138+
139+
5. Build the project
140+
^^^^^^^^^^^^^^^^^^^^
141+
142+
Input following command to start building:
143+
144+
- make ota
145+
146+
After compiling, the final firmware "ota.v2_to_v3.ota.bin" will be generated. Then users can download and update to this new firmware when running an old SDK OTA application.
147+
148+
- Note: The finally firmware's name mentioned above will be as "xxx.v2_to_v3.ota.bin", "xxx" is the name of your project.
149+
150+
4. Start HTTP Server
151+
^^^^^^^^^^^^^^^^^^^^
152+
153+
```
154+
cd build
155+
python -m SimpleHTTPServer 8070
156+
```
157+
158+
Note
159+
====
160+
161+
* It will take a lot of time for the new bootloader unpacking the firmware at the first time, please wait a while.
162+
163+
* The terminal will print some log that shows the progress:
164+
* log "I (281) boot: Start unpacking V3 firmware ...", it means that bootloader starts unpacking.
165+
* log "Pack V3 firmware successfully and start to reboot", it means that bootloader unpacked firmware successfully.
166+
167+
* This "unpacking workflow" will only be executed when it is an old SDK firmware that upgrade to the new SDK firmware, for example, V2.0 upgrade to V3.1. After that, the FOTA in later versions (for example, V3.1 upgrade to later) will be the [normal FOTA workflow](https://github.com/espressif/ESP8266_RTOS_SDK/blob/master/examples/system/ota/README.md).
168+

‎examples/system/ota/partitions_two_ota_v2tov3.2MB.csv

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Name, Type, SubType, Offset, Size, Flags
2+
# Note: if you change the phy_init or app partition offset, make sure to change the offset in Kconfig.projbuild
3+
# Bootloader is at 0x1000 - 0x8000, total 28KB
4+
# Partition table is at 0x8000 - 0x9000, total 4KB
5+
# Reserve 4 sectors at the end flash address for V2 updating to V3 and system can read V2 parameters.
6+
nvs, data, nvs, 0x9000, 0x4000
7+
otadata, data, ota, 0xd000, 0x2000
8+
phy_init, data, phy, 0xf000, 0x1000
9+
ota_0, 0, ota_0, 0x10000, 0xEC000
10+
ota_1, 0, ota_1, 0x110000,0xEC000

0 commit comments

Comments
 (0)