# Micropython Online Updater
**Repository Path**: walkline/micropython-online-updater
## Basic Information
- **Project Name**: Micropython Online Updater
- **Description**: 为项目提供在线更新功能
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2023-05-23
- **Last Updated**: 2024-04-07
## Categories & Tags
**Categories**: Uncategorized
**Tags**: MicroPython, 在线更新, mpy-cross
## README
Micropython Online Updater
### 项目介绍
`Online Updater`模块在开发板联网后可用于检查、下载项目中需要更新的文件，免去手动上传文件的麻烦（感谢 [jd3096](https://gitee.com/jd3096) 提供的思路）
> 特别注意：需要将项目文件编译到固件中，或转换为`.mpy`格式并手动上传到开发板中，对于`.py`格式的文件**无法**提供在线更新功能
### 实现方法
在线更新项目文件的原理十分简单，只需要联网下载最新版并覆盖本地文件即可
但实际操作中可能会出现一些意外情况导致更新失败甚至项目无法正常运行，此时需要一个`在线更新配置文件`，配置文件中提供每个更新文件的基本属性，可用于检查文件版本和校验文件完整性，这些基本属性包括：
* 文件路径（`path`）
* 文件名（`filename`)
* 文件大小（`size`）
* 下载路径（`url`）
* 版本号（`version`）
客户端下载`在线更新配置文件`后根据每个文件的`版本号`判断是否需要下载更新文件，需要下载的文件首先下载到一个临时目录中，并根据`文件大小`判断文件是否下载成功，在所有文件全部成功下载后再移动（覆盖）到目标`文件路径`，这样做以避免本次更新的文件中存在相互依赖的情况下，只更新部分文件可能会导致项目运行出现异常（当然，最好的做法是避免文件互相依赖的情况出现）
项目中使用`.mpy`格式文件的原因见下图
### 如何使用
使用在线更新功能需要完成以下五个步骤的操作：
1. 在项目文件中增加必要的`版本号`信息
2. 本地生成`在线更新配置文件`
3. 上传配置文件和转换后的项目文件到资源服务器
4. 调用`OnlineUpdater`模块检查并下载更新文件
5. 其它文件调用更新后的项目文件
#### 1.增加版本号信息
在项目文件头部增加`版本号`信息
```python
# update.py
__version_info__ = (0, 1)
```
每次修改文件后都需要对`版本号`进行手动递增，以保证新的`版本号`大于之前的，以下列出的都是大于`(0, 1)`的`版本号`
* `(0, 1, 1)`
* `(0, 2, 0)`
* `(1, 0)`
#### 2.生成配置文件
转换`.mpy`格式文件需要用到`mpy-cross`工具
```bash
# 安装 mpy-cross
pip install mpy-cross
# 更新 mpy-cross
pip install --upgrade mpy-cross
```
使用项目中提供的`配置文件生成工具`可自动生成配置文件
```bash
cd path/to/root/
python ./updatting/config_generator.py
```
在运行生成工具之前，需要根据项目实际情况修改参数设置
```python
# updating/config_generator.py
# 按需选择更新文件
INPUT_FILE_LIST = ('/update.py',)
# 资源服务器地址
URL_PREFIX = 'https://path/to/resource/server/'
```
#### 3.上传更新文件
最终生成的文件位于`updating`目录下，将该文件夹上传到`URL_PREFIX`指定的资源服务器即可
#### 4.开发板下载更新文件
至此，配置文件和更新文件已准备完毕，下一步是在开发板中使用`update.py`文件提供的`OnlineUpdater`模块检查和下载更新文件
首先需要修改`update.py`中的资源服务器地址，使之与`在线更新配置文件`中的地址匹配即可
```python
# update.py
URL_PREFIX = 'https://path/to/resource/server/'
```
把修改后的文件上传至开发板，使用如下代码检查并下载更新文件：
```python
import network
from update import OnlineUpdater
def update_callback(result:int, msg:str, files:dict):
print(f'- update result: {msg}')
print(f' files: {files}')
if network.WLAN(network.STA_IF).isconnected():
updater = OnlineUpdater(update_callback)
updater.check()
```
> 具体示例参考`update.py`文件中提供的测试代码
#### 5.调用更新后的文件
更新后的文件存储在用户分区内，所以使用时需要优先导入用户分区内的文件
```python
# main.py
try:
from test.tools import TestingToolsClass
except ImportError:
TestingToolsClass = __import__('test/tools').TestingToolsClass
if __name__ == '__main__':
print(TestingToolsClass().add(1, 2))
```
> 具体示例参考`main.py`及`test`文件夹中提供的测试代码
### 合作交流
* 联系邮箱：
* QQ 交流群：
* 走线物联：[163271910](https://jq.qq.com/?_wv=1027&k=xtPoHgwL)
* 扇贝物联：[31324057](https://jq.qq.com/?_wv=1027&k=yp4FrpWh)
