You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/ota_updates/ota_updates.md
+61-15
Original file line number
Diff line number
Diff line change
@@ -10,21 +10,50 @@ title: OTA Update
10
10
11
11
## Introduction
12
12
13
-
OTA (Over the Air) update is the process of loading the firmware to ESP module using WiFi connection rather that a serial port. Such functionality became extremely useful in case of limited or no physical access to the module. There is no imposed protection on OTA update process. Such protection should be implemented by developer to ensure that updates are allowed only from legitimate / trusted source.
13
+
OTA (Over the Air) update is the process of loading the firmware to ESP module using WiFi connection rather that a serial port. Such functionality became extremely useful in case of limited or no physical access to the module.
14
14
15
15
OTA may be done from:
16
16
-[Arduino IDE](#arduino-ide)
17
17
-[HTTP server](#http-server)
18
18
19
19
In any case first firmware upload have to be done over a serial port. If OTA routines are correctly implemented in sketch, then all subsequent uploads may be done over the air.
20
20
21
-
The following chapters provide more details and both methods of doing OTA.
21
+
There is no imposed security on OTA process from being hacked. It is up to developer to ensure that updates are allowed only from legitimate / trusted source. Once update is complete module restarts and new code is executed. Developer should ensure that application running on module is shut down and restarted in safe manner. Chapters below provide additinal information regarding security and safety of OTA process.
22
+
23
+
### Security
24
+
25
+
Module has to be exposed wirelessly to get it updated with a new code. That poses chances of module being violently hacked and loaded with some other firmware. To reduce likelihood of being hacked consider protecting your uploads with a password, selecting certain OTA port, etc.
26
+
27
+
Check functionality provided with [ArduinoOTA](https://github.com/esp8266/Arduino/tree/master/libraries/ArduinoOTA) library that may improve security:
28
+
```cpp
29
+
voidsetPort(uint16_t port);
30
+
void setHostname(const char *hostname);
31
+
void setPassword(const char *password);
32
+
```
33
+
If possible implement other means of protection from being hacked, e.g. exposing module for uploads only according to specific schedule, trigger OTA only be user pressing dedicated “Update” button, etc.
34
+
35
+
### Safety
36
+
37
+
OTA process takes ESP’s resources and bandwidth during upload. Then module is restarted and a new sketch executed. Analyse and test how it affects functionality of your existing and new sketch.
38
+
39
+
If ESP is placed in remote location and controlling some equipment, you should put additional attention what happens if operation of this equipment is suddenly interrupted by update process. Therefore decide how to put this equipment into safe state before starting the update. For instance your module may be controlling a garden watering system in a sequence. If this sequence is not properly shut down and a water valve left open, your garden may be flooded if this valve is not closed after OTA is finished and module restarts.
40
+
41
+
The following functions are provided with [ArduinoOTA](https://github.com/esp8266/Arduino/tree/master/libraries/ArduinoOTA) library and intended to handle functionality of your application during specific stages of OTA on or on an OTA error:
42
+
```cpp
43
+
void onStart(OTA_CALLBACK(fn));
44
+
void onEnd(OTA_CALLBACK(fn));
45
+
void onProgress(OTA_CALLBACK_PROGRESS(fn));
46
+
void onError(OTA_CALLBACK_ERROR (fn));
47
+
```
48
+
49
+
The following chapters provide more details and specific methods of doing OTA.
22
50
23
51
24
52
## Basic Requirements
25
53
26
54
- Flash chip size is 2x the size of the sketch.
27
55
56
+
28
57
## Arduino IDE
29
58
30
59
Uploading modules wirelessly from Arduino IDE is intended for the following typical scenarios:
@@ -37,52 +66,69 @@ Uploading modules wirelessly from Arduino IDE is intended for the following typi
37
66
38
67
#### Let's Do It
39
68
40
-
OTA process will be demonstrated using:
41
-
- DNS_SD_Arduino_OTA.ino sketch available from Arduino IDE
42
-
- NodeMCU 1.0 board with ESP-12E module
69
+
Currently there are two software configurations that support OTA updates
70
+
-[Classic OTA](#classic-ota-configuration): Arduino IDE 1.6.5 and [stable](https://github.com/esp8266/Arduino#staging-version-) (July 23, 2015) or [staging](https://github.com/esp8266/Arduino#staging-version-) (Sep 30, 2015) platform package that provides first OTA implementation, yet without support for [ArduinoOTA](https://github.com/esp8266/Arduino/tree/master/libraries/ArduinoOTA) library. This particular configuration is intended for less experienced users. It soon will be depreciated once implementation below is fully released.
71
+
-[ArduinoOTA](#arduinoota-configuration): Arduino-PR-4107-BUILD-421 and latest git version of platform package that includes [ArduinoOTA](https://github.com/esp8266/Arduino/tree/master/libraries/ArduinoOTA) library. This configuration features preliminary build of Arduino IDE and is intended for more experienced users. Please mid your step.
72
+
73
+
Instructions below demonstrate how to configure both [Classic OTA](#classic-ota-configuration) and [ArduinoOTA](#arduinoota-configuration) using NodeMCU 1.0 board with ESP-12E.
74
+
75
+
##### Classic OTA Configuration
43
76
44
77
1. Before you begin, please make sure that you have the following installed:
45
78
- Arduino IDE and ESP8266 board support as described under https://github.com/esp8266/Arduino#installing-with-boards-manager
46
-
- Python 2.7.10 (do not install Python 3.5.0 that is not supported):
47
-
1. Upload Python from https://www.python.org/
48
-
2. Start installer
49
-
3. Select “Add python.exe to Path” (see below – that option is not selected by default)
50
-
4. Complete remaining steps of installation
51
-
79
+
-[Python](https://www.python.org/) 2.7.10 (do not install Python 3.5.0 that is not supported):
80
+
81
+
**Note:** Windows users should select “Add python.exe to Path” (see below – this option is not selected by default)
82
+
52
83
53
84
54
85
2. Now prepare the sketch and configuration for the upload over a serial port.
55
86
56
87
- Start Arduino IDE and load sketch DNS_SD_Arduino_OTA.ino available under File > Examples > ESP8266mDNS
**Note:** This sketch is available only for stable (July 23, 2015) and staging (Sep 30, 2015) releases installed in Arduino IDE using https://github.com/esp8266/Arduino#installing-with-boards-manager. It was removed in [#980](https://github.com/esp8266/Arduino/pull/980) from Github repository.
59
92
60
93
- Update ssid and pass in the sketch so the module can join your WiFi network
61
94
62
-
95
+
63
96
64
97
- Configure upload parameters as below (you may need to adjust configuration if you are using a different module):
65
98
66
-
99
+
67
100
68
101
3. Upload the sketch (Ctrl+U). Once done open Serial Monitor (Ctrl+Shift+M) and check if the module has joined your WiFi network.
69
102
70
103
71
104
72
-
4. Only if module is connected, after a dozen (or two dozens) of seconds the esp8266-ota port will show up in Arduino IDE:
105
+
4. Only if module is connected to network, after a couple of seconds, the esp8266-ota port will show up in Arduino IDE:
73
106
74
107
75
108
76
109
5. Now get ready for your first OTA upload by changing configuration settings as follows:
77
110
78
111
79
112
113
+
**Note:** If you do not see “Upload Using: OTA” option available for “NodeMCU 1.0 (ESP-12E Module)” board, please upload the latest [boards.txt](https://github.com/esp8266/Arduino/blob/master/boards.txt) file from Github repository, replace existing file and restart Arduino IDE.
114
+
80
115
6. If you have successfully completed all the above steps, you can upload (Ctrl+U) the same (or any other) sketch over OTA:
**Note** To be able to upload your sketch over and over again using OTA, you need to embed OTA routines inside. Please use DNS_SD_Arduino_OTA.ino as an example.
0 commit comments