Micropython library for upgrading code over-the-air (OTA)
Project description
micropython-ota
Introduction
Micropython library for upgrading code over-the-air (OTA)
Preparation
For OTA updates to work an HTTP server like Apache or nGinx is required to be running and accessible by the device. This server can serve multiple devices and multiple projects at once. The following directory structure must be provided for the OTA updates to work:
server-root/
|- <project_name>/
| |- version
| |- <version>_<filename1>
| |- <version>_<filename2>
| |- ...
|- <project_name>/
|- version
|- <version>_<filename1>
|- <version>_<filename2>
|- ...
For each project a directory must exist in the server's document root. Inside this directory a file "version" exists containing the version-tag to be pulled
by the devices, e.g. v1.0.0
. The source code files to be pulled by the devices are placed right next to the version-file, prefixed by the version-tag.
This structure also provides the ability to do a rollback by simply changing the version-tag in the version-file to an older version-tag, as long as the
relevant source code files still reside in the directory.
In the following example two projects "sample" and "big_project" are configured:
server-root/
|- sample/
| |- version <-- containing v1.0.1
| |- v1.0.0_boot.py
| |- v1.0.0_main.py
| |- v1.0.1 boot.py
| |- v1.0.1 main.py
|- big_project/
|- version <-- containing v1.0.0
|- v1.0.0_boot.py
|- v1.0.0_main.py
|- v1.0.0_data.py
Usage
This library provides two methods for
- handling code updates during boot (
ota_update
) and - checking for code updates at regular intervals (
check_for_ota_update
).
The library can be installed using upip, ensure that the device is connected to the network:
import upip
upip.install('micropython-ota')
The ota_update
method might be called in the boot.py file, right after the network connection has been established:
import micropython_ota
# connect to network
ota_host = 'http://192.168.2.100'
project_name = 'sample'
filenames = ['boot.py', 'main.py']
micropython_ota.ota_update(ota_host, project_name, filenames)
That's it. On boot the library retrieves the version-file from http://192.168.2.100/sample/version
and evaluates its content against a locally persisted
version-file. (Of course, on the first run the local version-file does not exist, yet. This is treated as a new version being available.)
If the versions differ, the source code files listed in filenames
are updated accordingly and on success the local version-file is updated as well.
For regular checking for code updates the method check_for_ota_update
might be called in the course of the regular application logic in main.py, e.g.:
import micropython_ota
import utime
ota_host = 'http://192.168.2.100'
project_name = 'sample'
while True:
# do some other stuff
utime.sleep(10)
micropython_ota.check_for_ota_update(ota_host, project_name)
In this case on each iteration the library checks for a new version as described above and reboots the device if a new version is available. After the reboot
the ota_update
-method called in the boot.py performs the actual update.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.