Package: micropython-ota
micropython-otaIntroductionMicropython library for upgrading code over-the-air (OTA)PreparationFor OTA updates to work an HTTP/HTTPS 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. There are two supported directory structures of which one must be provided for the OTA updates to work:Version as prefix (default)server-root/
|- <project_name>/
|  |- version
|  |- <version>_<filename1>
|  |- <version>_<filename2>
|  |- ...
|- <project_name>/
   |- version
   |- <version>_<filename1>
   |- <version>_<filename2>
   |- ...Version as subdirectory (by setting the parameteruse_version_prefixtoFalse, seeUsage)server-root/
|- <project_name>/
|  |- version
|  |- <version_subdir>
|     |- <filename1>
|     |- <filename2>
|     |- ...
|- <project_name>/
   |- version
   |- <version_subdir>
      |- <filename1>
      |- <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 either right next to the version-file, prefixed by the version-tag,
or in a subdirectory named with 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 expected location.In the following example two projects "sample" and "big_project" are configured, using the default, version-prefixed directory structure: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.pyInstallationThe library can be installed usingupipormip. Ensure that the device is connected to the network.Installation using upip (Micropython < 1.19)importupipupip.install('micropython-ota')Installation using mip (Micropython >= 1.19)Py-fileimportmipmip.install('github:olivergregorius/micropython_ota/micropython_ota.py')Cross-compiled mpy-fileNOTE: Set the release_version variable accordingly.importmiprelease_version='vX.Y.Z'mip.install(f'https://github.com/olivergregorius/micropython_ota/releases/download/{release_version}/micropython_ota.mpy')UsageThis library provides two methods forhandling code updates during boot (ota_update) andchecking for code updates at regular intervals (check_for_ota_update).Theota_updatemethod might be called in the boot.py file, right after the network connection has been established:importmicropython_ota# connect to networkota_host='http://192.168.2.100'project_name='sample'filenames=['boot.py','main.py']micropython_ota.ota_update(ota_host,project_name,filenames,use_version_prefix=True,hard_reset_device=True,soft_reset_device=False,timeout=5)That's it. On boot the library retrieves the version-file fromhttp://192.168.2.100/sample/versionand 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 infilenamesare updated accordingly and on success the local version-file is updated as well. If theuse_version_prefixis set to True (default) the library expects the 'Version as prefix' directory structure on the server, otherwise it expects the 'Version
as subdirectory' directory structure (seePreparation). If thehard_reset_device-flag is set toTrue(default) the device will be reset
after the successful update by callingmachine.reset(). For just soft-resetting the device the flagsoft_reset_devicecan be set toTrue(defaults toFalse), taking precedence. This will call themachine.soft_reset()-method. The timeout can be set accordingly, by default its value is 5 seconds.For regular checking for code updates the methodcheck_for_ota_updatemight be called in the course of the regular application logic in main.py, e.g.:importmicropython_otaimportutimeota_host='http://192.168.2.100'project_name='sample'whileTrue:# do some other stuffutime.sleep(10)micropython_ota.check_for_ota_update(ota_host,project_name,soft_reset_device=False,timeout=5)In this case on each iteration the library checks for a new version as described above and resets the device if a new version is available. By default a
hard-reset is performed (by callingmachine.reset()). By setting the flagsoft_reset_devicetoTrue(defaults toFalse) the device will just be
soft-reset (by callingmachine.soft_reset()). After the reset theota_update-method called in the boot.py performs the actual update. This method accepts
the timeout setting, too, by default it is set to 5 seconds.HTTP(S) Basic Authenticationota_update()andcheck_for_ota_update()methods allow optionaluserandpasswdparameters.  When specified the library performs a basic authentication
against the server hosting the source files.  Use of HTTPS (versus HTTP) is very highly recommended when using basic authentication as, otherwise, the resulting
username and password are sent as plain text i.e. completely unsecure.Here is the same example as above, but using HTTPS and Basic Authentication:importmicropython_ota# connect to networkota_host='https://example.com'project_name='sample'filenames=['boot.py','main.py']user='otauser'passwd='topsecret'# it's best to place this credential is a secrets.py filemicropython_ota.ota_update(ota_host,project_name,filenames,user=user,passwd=passwd,use_version_prefix=True,hard_reset_device=True,soft_reset_device=False,timeout=5)There are plenty of tutorials online on how to set up secured HTTP file access on your webserver, but the basic steps are:get and install an SSL certificate (Let's Encrypt is by far the best choice)enable HTTPS access on your web serverprevent directories from listing filesenable HTTP Basic Authentication password protection on target directories