wirtz
/
AutoConnect
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Adds the OTA Update documentation (continues)

Browse Source
pull/123/head
Hieromon Ikasamo 6 years ago
parent 8314b0bf1a
commit be22522ca2
6 changed files with 115 additions and 32 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. 3
      examples/Simple/Simple.ino
  2. 37
      mkdocs/apiupdate.md
  3. 49
      mkdocs/otaserver.md
  4. 48
      src/updateserver/README.md
  5. 5
      src/updateserver/python2/updateserver.py
  6. 5
      src/updateserver/python3/updateserver.py

3
examples/Simple/Simple.ino
Unescape View File

@ -99,6 +99,9 @@ void rootPage() {
"<html>"
"<head>"
"<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">"
"<script type=\"text/javascript\">"
"setTimeout(\"location.reload()\", 1000);"
"</script>"
"</head>"
"<body>"
"<h2 align=\"center\" style=\"color:blue;margin:20px;\">Hello, world</h2>"

37
mkdocs/apiupdate.md
Unescape View File

@ -7,18 +7,43 @@ AutoConnectUpdate(const String& host, const uint16_t port, const String& uri, co
```
<dl class="apidl">
<dt>**Parameters**</dt>
<dd><span class="apidef">host</span><span class="apidesc">Update server address</span></dd>
<dd><span class="apidef">port</span><span class="apidesc">Port number. **AUTOCONNECT_UPDATE_PORT**</span></dd>
<dd><span class="apidef">uri</span><span class="apidesc"></span></dd>
<dd><span class="apidef">timeout</span><span class="apidesc">**AUTOCONNECT_UPDATE_TIMEOUT**</span></dt>
<dd><span class="apidef">ledOn</span><span class="apidesc">Active signal to light the LED ticker during the update. specifies **HIGH** or **LOW**</span></dt>
<dd><span class="apidef">host</span><span class="apidesc">Update server address. Specifies IP address or FQDN.</span></dd>
<dd><span class="apidef">port</span><span class="apidesc">Specifies HTTP port for the updating process. The default is defined as the **AUTOCONNECT_UPDATE_PORT** macro in the `AutoConnectDefs.h` header file.</span></dd>
<dd><span class="apidef">uri</span><span class="apidesc">Specifies a URI on the update server that has deployed available binary sketch files.</span></dd>
<dd><span class="apidef">timeout</span><span class="apidesc">Specifies the maximum response time for the update server. The default is defined as the **AUTOCONNECT_UPDATE_TIMEOUT** macro in the `AutoConnectDefs.h` header file.</span></dt>
<dd><span class="apidef">ledOn</span><span class="apidesc">Active signal to light the LED ticker during the update. Specifies **HIGH** or **LOW**</span></dt>
</dl>
## <i class="fa fa-code"></i> Public member functions
### <i class="fa fa-caret-right"></i> attach
### <i class="fa fa-caret-right"></i> enabled
```cpp
void AutoConnectUpdate::attach(AutoConnect& portal)
```
Attaches the [AutoConnectUpdate](apiupdate.md) to the AutoConnect which constitutes the bedrock of the update process. This function creates a [dialog page](otaserver.md#behavior-of-the-autoconnectupdate-class) for the update operation as an instance of [AutoConnectAux](apiaux.me) and participates in the [AutoConnect menu](menu.md).
<dl class="apidl">
<dt>**Parameter**</dt>
<dd><span class="apidef">portal</span><span class="apidesc">Specifies a reference to the AutoConnect instance to attach.</span></dd>
</dl>
### <i class="fa fa-caret-right"></i> disable
```cpp
void AutoConnectUpdate::disable(const bool activate)
```
Disable the Update item in [AutoConnect menu](menu.md). The [AutoConnect::disable](#disable) function only hides the Update item from the menu, and the [AutoConnectUpdate](apiupdate.md) class is still active with the parameter condition. You can use the [AutoConnectUpdate::enable](#enable) function to appear it again in the menu.
<dl class="apidl">
<dt>**Parameter**</dt>
<dd><span class="apidef">activate</span><span class="apidesc">If specified the **true** then the Update item will be displayed on the [AutoConnect menu](menu.md) and OTA update will be available during the WiFi status is WL_CONNECTED. For the **false**, the OTA update feature is disabled.</span></dd>
</dl>
### <i class="fa fa-caret-right"></i> enable
```cpp
void AutoConnectUpdate::enable(void)
```
Makes [AutoConnectUpdate](apiupdate.md) class available by incorporating the OTA update function into the [AutoConnect menu](menu.md). In ordinally, the [AutoConnectUpdate](apiupdate.md) class becomes available by just calling the [AutoConnectUpdate::attach](#attach) function.
### <i class="fa fa-caret-right"></i> handleUpdate

49
mkdocs/otaserver.md
Unescape View File

@ -57,7 +57,7 @@ The substance of the available firmware list is a custom Web page by AutoConnect
<img src="images/updating.png" width="240" />
<img style="margin-left:30px;" src="images/updated.png" width="240" />
The AutoConnectUpdate class performs the above series of operations in conjunction with the update server. All you need to do is attach the AutoConnectUpdate class to AutoConnect and execute the [AutoConnect::handleClient](api.md#handleclient) function.
The AutoConnectUpdate class performs the above series of operations in conjunction with the update server. All you need to do is attach the AutoConnectUpdate class to AutoConnect and perform the [AutoConnect::handleClient](api.md#handleclient) function.
### <i class="fas fa-server"></i> Update server for the AutoConnectUpdate class
@ -74,35 +74,40 @@ updateserver.py [-h] [--port PORT] [--bind IP_ADDRESS] [--catalog CATALOG] [--lo
<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">**--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: HOST IP or 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"
1. Python
First, prepare a Python environment. It is also possible with a tiny single-board computer like the [raspberry pi](https://www.raspberrypi.org/). Popular distributions such as Ubuntu for Linux include Python. You can easily set up a Python 2 or 3 environment. If you are using a Mac, you already have the Python 2 environment. macOS is equipped with Python 2.7 by default. In the case of Windows OS, it is necessary to install the Python environment intentionally. Please refer to the [Python official page](https://wiki.python.org/moin/BeginnersGuide/Download) to install Python in your environment.
2. command line example
For example, to start the update server on the host with IP address 172.16.1.10 using 8080 port[^3], execute the following command:
```bash
python updateserver.py --port 8080 --bind 172.16.1.10 --catalog bin --log debug
```
In this example assumes that the binary sketch files are deployed under the path `bin` from the current directory.
First, prepare a Python environment. It is also possible with a tiny single-board computer like the [raspberry pi](https://www.raspberrypi.org/). Popular distributions such as Ubuntu for Linux include Python. You can easily set up a Python 2 or 3 environment. If you are using a Mac, you already have the Python 2 environment. macOS is equipped with Python 2.7 by default. In the case of Windows OS, it is necessary to install the Python environment intentionally. Please refer to the [Python official page](https://wiki.python.org/moin/BeginnersGuide/Download) to install Python in your environment.
[^3]: The port of the update server and the port used by the AutoConnectUpdate class must be the same.
2. Deploy the binary sketch files
Use the Arduino IDE to output a binary file of sketches and deploy it[^3] under the update server. The path which specifies for the **--catalog** option of updateServer.py is the path of the binary sketch files you deployed.
3. Start updateserver.py
For example, to start the update server on the host with IP address 172.16.1.10 using 8080 port[^4], execute the following command:
```bash
python updateserver.py --port 8080 --bind 172.16.1.10 --catalog bin --log debug
```
In this example assumes that the binary sketch files are deployed under the path `bin` from the current directory.
[^3]: Deploying the binary sketch file output by Arduino IDE is usually just copying to the folder for deployment. However, its folder must be accessible from the updateserver.py script.
[^4]: The port of the update server and the port used by the AutoConnectUpdate class must be the same.
!!! note "Limitations of the updateserver.py"
The updateserver.py script equips only the minimum facility because it assumes a private small OTA platform without identifying individual modules and version restrictions etc. To operate a larger OTA platform, it is necessary to identify the individual ESP module and to consider version control and security.
### <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 worked together the AutoConnectUpdate class can be prepared individually by yourself. If you want to improve the update server that can operate more broadly by equipping the extensions such as version control and authentications, it must implement the handshake requirements for 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. [^4]
- Send an updating binary file and MD5 hash to a client in response to URI request (HTTP GET). [^5]
- The update server notifies the catalog list of updatable binary files which stored in the update server to the client agent. [^5]
- Send an updating binary file and MD5 hash to a client in response to URI request (HTTP GET). [^6]
[^4]: The **client agent** is an instance of the AutoConnectUpdate class.
[^5]: The client agent will send its URI request to the update server.
[^5]: The **client agent** is an instance of the AutoConnectUpdate class.
[^6]: The client agent will send its URI request to the update server.
Above requirements will be implemented on along the HTTP protocol. The AutoConnectUpdate 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:
@ -141,12 +146,22 @@ The response (that is, the catalog list) to the above query from the server is t
<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]
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.[^7]
[^4]: It should be represented as `Content-Type: application/json` in the HTTP response header.
[^7]: It should be represented as `Content-Type: application/json` in the HTTP response header.
#### 3. The binary sketch file used for updating
The AutoConnectUpdate class issues a HTTP GET request with the specified host address and URI. The update server responds by sending back a binary sketch file with the following header:
```
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="BINARY_SKETCH_FILE_NAME"
Content-Length: LENGTH_OF_CONTENT
x-MD5: HEXDIGEST
```
The header **x-MD5** is a 128-bit hash value (digest in hexadecimal) that represents the checksum of the binary sketch file for updates required for the ESP8266HTTPUpdate class.
<script>
window.onload = function() {

48
src/updateserver/README.md
Unescape View File

@ -1,9 +1,47 @@
## A simple update server for AutoConnect update feature
## OTA Updates with AutoConnect using an updateserver.py
AutoConnect since v1.0.0 release provides a new function for updating the sketch firmware of ESP8266 or ESP32 module via OTA as AutoConnectUpdate class. The AutoConnectUpdate class is an implementation of the sketch binary update by the HTTP server mentioned in the OTA update of the ESP8266 document, which inherits from the ESP8266 HTTPUpdate class (HTTPUpdate class in the case of ESP32). It acts as a client agent for a series of update operations.
AutoConnect since v1.0.0 release provides a new function for updating the sketch firmware of ESP8266 or ESP32 module via OTA as AutoConnectUpdate class. The [AutoConnectUpdate](https://hieromon.github.io/AutoConnect/apiupdate.html) class is an implementation of the binary sketch update using the HTTP server mentioned in the OTA Updates of the [ESP8266 Arduino Core documentation](https://arduino-esp8266.readthedocs.io/en/latest/ota_updates/readme.html#ota-updates), which inherits from the ESP8266 HTTPUpdate class (HTTPUpdate class in the case of ESP32). It acts as a client agent for a series of update operations.
<img src="../../mkdocs/images/updateserver.png" width="380" />
<img src="../../mkdocs/images/updatemodel.png" width="540" />
updateserver.py
## A simple update server for the AutoConnectUpdate class
Details for the [AutoConnect documentation](https://hieromon.github.io/AutoConnect/otaupdate.html#updates-with-the-update-server).
The [updateserver.py](https://hieromon.github.io/AutoConnect/update-server-for-the-autoconnectupdate-class) script is a simple server for OTA updates effected by the AutoConnectUpdate class implemented in Python and can serve in Python 2 or 3 environment.
### Supported Python environment
* Python 2.7 for [python2/updateserver.py](../python2/updateserver.py)
* Python 3.6 or higher for [python3/updateserver.py](../python3/updateserver.py)
### updateserver.py command line options
```bash
updateserver.py [-h] [--port PORT] [--bind IP_ADDRESS] [--catalog CATALOG] [--log LOG_LEVEL]
```
<dl>
<dt>--help | -h</dt>
<dd>Show help message and exit.</dd>
<dt>--port | -p</dt><dd>Specifies **PORT** number (Default: 8000)</dd>
<dt>--bind | -b</dt><dd>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: HOST IP or 127.0.0.0)</dd>
<dt>--catalog | -d</dt>
<dd>Specifies the directory path on the update server that contains the binary sketch files. (Default: The current directory)</dd>
<dt>--log | -l</dt>
<dd>Specifies the level of logging output. It accepts the <a href="https://docs.python.org/3/library/logging.html?highlight=logging#logging-levels">Logging Levels</a> specified in the Python logging module.</dd>
</dl>
### Usage updateserver.py
1. Python
First, prepare a Python environment. It is also possible with a tiny single-board computer like the [raspberry pi](https://www.raspberrypi.org/). Popular distributions such as Ubuntu for Linux include Python. You can easily set up a Python 2 or 3 environment. If you are using a Mac, you already have the Python 2 environment. macOS is equipped with Python 2.7 by default. In the case of Windows OS, it is necessary to install the Python environment intentionally. Please refer to the [Python official page](https://wiki.python.org/moin/BeginnersGuide/Download) to install Python in your environment.
2. Deploy the binary sketch files
Use the Arduino IDE to output a binary file of sketches and deploy it under the update server. The path which specifies for the **--catalog** option of updateServer.py is the path of the binary sketch files you deployed.
3. Start updateserver.py
For example, to start the update server on the host with IP address 172.16.1.10 using 8080 port, execute the following command:
```bash
python updateserver.py --port 8080 --bind 172.16.1.10 --catalog bin --log debug
```
In this example assumes that the binary sketch files are deployed under the path `bin` from the current directory.
Details for the [AutoConnect documentation](https://hieromon.github.io/AutoConnect/otaserver.html).

5
src/updateserver/python2/updateserver.py
Unescape View File

@ -12,6 +12,7 @@ import json
import logging
import os
import re
import socket
import time
import urllib2, urllib, urlparse
from itertools import imap
@ -163,8 +164,8 @@ if __name__ == "__main__":
parser = argparse.ArgumentParser()
parser.add_argument('--port', '-p', action='store', default=8000, type=int,
help='Port number [default:8000]')
parser.add_argument('--bind', '-b', action='store', default='127.0.0.1',
help='Specifies address to which it should bind. [default:127.0.0.1]')
parser.add_argument('--bind', '-b', action='store', default=socket.gethostbyname(socket.gethostname()),
help='Specifies address to which it should bind. [default:HOST IP or 127.0.0.1]')
parser.add_argument('--catalog', '-d', action='store', default=os.getcwdu(),
help='Catalog directory')
parser.add_argument('--log', '-l', action='store', default='INFO',

5
src/updateserver/python3/updateserver.py
Unescape View File

@ -10,6 +10,7 @@ import json
import logging
import os
import re
import socket
import time
import urllib.parse
@ -159,8 +160,8 @@ if __name__ == "__main__":
parser = argparse.ArgumentParser()
parser.add_argument('--port', '-p', action='store', default=8000, type=int,
help='Port number [default:8000]')
parser.add_argument('--bind', '-b', action='store', default='127.0.0.1',
help='Specifies address to which it should bind. [default:127.0.0.1]')
parser.add_argument('--bind', '-b', action='store', default=socket.gethostbyname(socket.gethostname()),
help='Specifies address to which it should bind. [default:HOST IP or 127.0.0.1]')
parser.add_argument('--catalog', '-d', action='store', default=os.getcwd(),
help='Catalog directory')
parser.add_argument('--log', '-l', action='store', default='INFO',

Write Preview
Loading…
Cancel
Save