You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
99 lines
6.8 KiB
99 lines
6.8 KiB
## Updates with the update server
|
|
|
|
Since the v1.0.0 release, AutoConnect provides new feature for updating sketch firmware of ESP8266 or ESP32 modules via OTA using the [AutoConnectUpdate](apiupdate.md#autoconnectupdate) class that is an implementation of the sketch binary update by the HTTP server mentioned in the [OTA update](https://arduino-esp8266.readthedocs.io/en/latest/ota_updates/readme.html#http-server) of the ESP8266 Arduino Core documentation, which inherits from the ESP8266HTTPUpdate class (as HTTPUpdate class in the case of ESP32). It acts as a client agent for a series of update operations.
|
|
|
|
This method allows you to remotely update the ESP module's firmware across network segments from the update server, as long as you can ensure proper routing and forwarding.
|
|
|
|
<img src="images/updateserver.png" width="380" />
|
|
|
|
If you choose this update method, you must prepare the server process that provides the binary sketch files for the update client agent as a variant of the HTTP server. This server requires to be able to handle the HTTP headers extended for updating the firmware generated by ESP8266HTTPUpdate class as described in the [ESP8266 Arduino Core documentation](https://arduino-esp8266.readthedocs.io/en/latest/ota_updates/readme.html#server-request-handling), and the AutoConnectUpdate class generates those headers for it.
|
|
|
|
There are various implementations of update servers that provide binary sketch files. The ESP8266 Arduino Core documentation publishes a php script for the [Advanced updater](https://arduino-esp8266.readthedocs.io/en/latest/ota_updates/readme.html#id5) which is a process that works fully well with client agents using the ESP8266HTTPUpdate class, as suggested in the implementation. That is, the update server for AutoConnect must work with the client agent, and its implementation should make the handshake well with the AutoConnectUpdate class.
|
|
|
|
### <i class="fa fa-edit"></i> How to embed AutoConnectUpdate to your sketch
|
|
|
|
|
|
### <i class="fas fa-server"></i> Update server for the AutoConnectUpdate class
|
|
|
|
AutoConnect provides the update server scripts implemented in Python. This server script is implemented to fit with the AutoConnectUpdate class as a client agent for updating and separated for Python2 or Python3 environments.[^1]
|
|
|
|
[^1]: The folders containing the script:
|
|
For Python2: *AUTOCONNECT\_LIBRARY\_PATH*/src/updateserver/python2
|
|
For Python3: *AUTOCONNECT\_LIBRARY\_PATH*/src/updateserver/python3
|
|
|
|
```bash
|
|
updateserver.py [-h] [--port PORT] [--bind IP_ADDRESS] [--catalog CATALOG] [--log LOG_LEVEL]
|
|
```
|
|
<dl class="apidl">
|
|
<dt></dt>
|
|
<dd><span class="apidef">**--help | -h**</span><span class="apidesc">Show help message and exit.</span>
|
|
<dd><span class="apidef">**--port | -p**</span><span class="apidesc">Specifies **PORT** number (Default: 8000)</span>
|
|
<dd><span class="apidef">**--bind | -b**</span><span class="apidesc">Specifies the IP address to which the update server binds. Usually, it is the host address of the update server. When multiple NICs configured, specify one of the IP addresses. (Default: 127.0.0.0)</span>
|
|
<dd><span class="apidef">**--catalog | -d**</span><span class="apidesc">Specifies the directory path on the update server that contains the binary sketch files. (Default: The current directory)</span>
|
|
<dd><span class="apidef">**--log | -l**</span><span class="apidesc">Specifies the level of logging output. It accepts the [Logging Levels](https://docs.python.org/3/library/logging.html?highlight=logging#logging-levels) specified in the Python logging module.</span>
|
|
</dl>
|
|
|
|
!!! example "updateserver.py usage"
|
|
python
|
|
|
|
```bash
|
|
python updateserver.py --port 8080 --bind 172.16.1.10 --catalog bin --log debug
|
|
```
|
|
|
|
### <i class="far fa-handshake"></i> HTTP contents and the sequence for the AutoConnectUpdate class
|
|
|
|
The handshake with the AutoConnectUpdate class has two requirements:
|
|
|
|
- The update server notifies the catalog list of updatable binary files which stored in the update server to the client agent. [^2]
|
|
- Send an updating binary file and MD5 hash to a client in response to URI request (HTTP GET). [^3]
|
|
|
|
[^2]: The **client agent** is an instance of the AutoConnectUpdate class.
|
|
[^3]: The client agent will send its URI request to the update server.
|
|
|
|
Above requirements will be implemented on along the HTTP protocol. The AutoConenctUpdate class requests an update server to notify the client for a catalog list of binary sketch files using an HTTP URL query string. The specifications of the HTTP query and the contents of the catalog list to be returned are as follows:
|
|
|
|
#### 1. HTTP URL query for the catalog list of the updatable
|
|
|
|
```
|
|
[address]/_catalog?op=list&path=[path]
|
|
```
|
|
<dl class="apidl">
|
|
<dt></dt>
|
|
<dd><span class="apidef">**address**</span><span class="apidesc">URL of the update server</span>
|
|
<dd><span class="apidef">**/_catalog**</span><span class="apidesc">Request path, it is fixed.</span>
|
|
<dd><span class="apidef">**op**</span><span class="apidesc">Operation command for the update server. Currently, only '**list**' occurs.</span>
|
|
<dd><span class="apidef">**path**</span><span class="apidesc">Path containing the updatable binary files on the update server.</span>
|
|
</dl>
|
|
|
|
#### 2. The catalog list content
|
|
|
|
The response (that is, the catalog list) to the above query from the server is the following specification in JSON format.
|
|
|
|
```js
|
|
{
|
|
"name" : FILE_NAME,
|
|
"type" : FILE_TYPE,
|
|
"date" : FILE_TIMESTAMP_DATED,
|
|
"time" : FILE_TIMESTAMP_TIMED,
|
|
"size" : FILE_SIZE
|
|
}
|
|
```
|
|
<dl class="apidl">
|
|
<dt></dt>
|
|
<dd><span class="apidef">**name**</span><span class="apidesc">Binary sketch file name for update (String)</span>
|
|
<dd><span class="apidef">**type**</span><span class="apidesc">One of '**bin**', '**directory**' or '**file**'. AutoConnect Update recognizes only file types of '**bin**' as update targets. (String)</span>
|
|
<dd><span class="apidef">**date**</span><span class="apidesc">File update date. AutoConnect v1.0.0 treats the file update date as an annotation and is not equip the version control feature yet. (String)</span>
|
|
<dd><span class="apidef">**time**</span><span class="apidesc">File update time. AutoConnect v1.0.0 treats the file update date as an annotation and is not equip the version control feature yet. (String)</span>
|
|
<dd><span class="apidef">**size**</span><span class="apidesc">File byte count (Numeric)</span>
|
|
</dl>
|
|
|
|
The above JSON object is one entry. The actual catalog list is an array of this entry since it assumes that an update server will provide multiple update binary files in production. The update server should respond with the MIME type specified as `application/json` for the catalog list.[^4]
|
|
|
|
[^4]: It should be represented as `Content-Type: application/json` in the HTTP response header.
|
|
|
|
#### 3. The binary sketch file used for updating
|
|
|
|
### <i class="fas fa-microchip"></i> Behavior of the AutoConnectUpdate class
|
|
|
|
|
|
|
|
|