1 /* 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 * Description: OTA适配层接口（此文件为DEMO，需集成方适配修改） 15 */ 16 #ifndef HILINK_OPEN_OTA_ADAPTER_H 17 #define HILINK_OPEN_OTA_ADAPTER_H 18 19 #include <stdbool.h> 20 #include <stddef.h> 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 /* OTA升级分区1 */ 27 #ifndef UPGRADE_FW_BIN1 28 #define UPGRADE_FW_BIN1 0x00 29 #endif 30 31 /* OTA升级分区2 */ 32 #ifndef UPGRADE_FW_BIN2 33 #define UPGRADE_FW_BIN2 0x01 34 #endif 35 36 /* 只有MCU升级时立即重启 */ 37 #ifndef RESTART_FLAG_NOW 38 #define RESTART_FLAG_NOW 0x01 39 #endif 40 41 /* 有模组时切换分区后再重启 */ 42 #ifndef RESTART_FLAG_LATER 43 #define RESTART_FLAG_LATER 0x02 44 #endif 45 46 /* 模组可以重启 */ 47 #ifndef MODULE_CAN_REBOOT 48 #define MODULE_CAN_REBOOT 0x01 49 #endif 50 51 /* 模组不能重启 */ 52 #ifndef MODULE_CANNOT_REBOOT 53 #define MODULE_CANNOT_REBOOT 0x00 54 #endif 55 56 /* 手动升级 */ 57 #ifndef UPDATE_TYPE_MANUAL 58 #define UPDATE_TYPE_MANUAL 0x00 59 #endif 60 61 /* 自动升级 */ 62 #ifndef UPDATE_TYPE_AUTO 63 #define UPDATE_TYPE_AUTO 0x01 64 #endif 65 66 /* 返回正常 */ 67 #ifndef RETURN_OK 68 #define RETURN_OK 0 69 #endif 70 /* 没有MCU */ 71 #ifndef RETURN_ERROR_NO_MCU 72 #define RETURN_ERROR_NO_MCU (-1) 73 #endif 74 /* 返回其他错误 */ 75 #ifndef RETURN_ERROR 76 #define RETURN_ERROR (-2) 77 #endif 78 /* MCU不需要升级 */ 79 #ifndef RETURN_MCU_NO_NEED_OTA 80 #define RETURN_MCU_NO_NEED_OTA (-3) 81 #endif 82 83 typedef void (*GetOtaVerCb)(const char *version); 84 typedef void (*TrigSelfUpdateCb)(const char *url, const unsigned int size); 85 86 /* 87 * Flash初始化 88 * 返回值是true时，表示初始化正常 89 * 返回值是false时，表示初始化异常 90 */ 91 bool HILINK_OtaAdapterFlashInit(void); 92 93 /* 94 * 判断需要升级的分区 95 * 返回值是UPGRADE_FW_BIN1时，表示升级固件到分区1 96 * 返回值是UPGRADE_FW_BIN2时，表示升级固件到分区2 97 */ 98 unsigned int HILINK_OtaAdapterGetUpdateIndex(void); 99 100 /* 101 * 擦除需要升级的分区 102 * size表示需要擦除的分区大小 103 * 返回值是0时，表示擦除成功 104 * 返回值是-1时，表示擦除失败 105 */ 106 int HILINK_OtaAdapterFlashErase(unsigned int size); 107 108 /* 109 * 升级数据写入升级的分区 110 * buf表示待写入数据 111 * bufLen表示待写入数据的长度 112 * 返回值是0时，表示写入成功 113 * 返回值是-1时，表示写入失败 114 */ 115 int HILINK_OtaAdapterFlashWrite(const unsigned char *buf, unsigned int bufLen); 116 117 /* 118 * 读取升级分区数据 119 * offset表示读写偏移 120 * buf表示输出数据的内存地址 121 * bufLen表示输出数据的内存长度 122 * 返回值是0时，表示读取成功 123 * 返回值是-1时，表示读取失败 124 */ 125 int HILINK_OtaAdapterFlashRead(unsigned int offset, unsigned char *buf, unsigned int bufLen); 126 127 /* 128 * 分区升级结束 129 * 返回值是true时，表示结束正常 130 * 返回值是false时，表示结束异常 131 */ 132 bool HILINK_OtaAdapterFlashFinish(void); 133 134 /* 获取升级区间最大长度 */ 135 unsigned int HILINK_OtaAdapterFlashMaxSize(void); 136 137 /* 138 * 根据标志重启模组 139 * flag表示重启标志 140 * 当flag是RESTART_FLAG_NOW时，表示只有MCU升级时立即重启 141 * 当flag是RESTART_FLAG_LATER时，表示有模组时切换分区后再重启 142 */ 143 void HILINK_OtaAdapterRestart(int flag); 144 145 /* 146 * 开始模组升级 147 * type表示升级类型 148 * 当type是UPDATE_TYPE_MANUAL时，表示本次升级流程是由用户主动发起的手动升级 149 * 当type是UPDATE_TYPE_AUTO时，表示本次升级流程是经过用户同意的自动升级 150 * 返回值是RETURN_OK时，表示处理成功，HiLink SDK将开始启动升级流程 151 * 返回值是RETURN_ERROR时，表示处理不成功，HiLink SDK将终止本次升级流程 152 * 注意：在手动场景场景下，HiLink SDK在接收到用户发出的升级指令后，将直接调用此接口； 153 * 在自动升级场景下，当HiLink SDK在调用HilinkGetRebootFlag接口返回值是MODULE_CAN_REBOOT时，HiLink SDK将调用此接口。 154 * 厂商可在此接口中完成和升级流程相关的处理。 155 * 开机后10分钟到1小时内随机时间检测一次是否有新版本，之后以当前时间为起点，23小时加1小时内随机值周期性检测新版本。 156 * 如果用户打开了自动升级开关，检测到有新版本并且是可以重启的情况下，就进行新版本的下载，下载完成后自动重启。 157 * 自动升级流程可能在凌晨进行，因此厂商在实现升级流程相关功能时，确保在升级的下载安装固件和重启设备时避免对用户产生 158 * 影响，比如发出声音，光亮等。 159 */ 160 int HILINK_OtaStartProcess(int type); 161 162 /* 163 * 模组升级结束 164 * status表示升级结果 165 * 当status是100时，表示升级成功 166 * 当status不是100时，表示升级失败 167 * 返回值是RETURN_OK时，表示处理成功，HiLink SDK将置升级标志或切换运行区标志 168 * 返回值不是RETURN_OK时，表示处理不成功，HiLink SDK将终止本次升级流程 169 * 注意：HiLink SDK在将固件写入到OTA升级区后，且完整性校验通过后，将调用厂商适配的此接口； 170 * 厂商可在此接口中完成和升级流程相关的处理。 171 * 开机后10分钟到1小时内随机时间检测一次是否有新版本，之后以当前时间为起点，23小时加1小时内随机值周期性检测新版本。 172 * 如果用户打开了自动升级开关，检测到有新版本并且是可以重启的情况下，就进行新版本的下载，下载完成后自动重启。 173 * 自动升级流程可能在凌晨进行，因此厂商在实现升级流程相关功能时，确保在升级的下载安装固件和重启设备时避免对用户产生 174 * 影响，比如发出声音，光亮等；升级类型是否为自动升级可参考接口HilinkOtaStartProcess的参数type的描述。 175 */ 176 int HILINK_OtaEndProcess(int status); 177 178 /* 179 * 判断模组是否能立即升级并重启 180 * 返回值是MODULE_CAN_REBOOT时，表示模组可以立即升级并重启，HiLink SDK将开始自动升级流程。 181 * 返回值是MODULE_CANNOT_REBOOT时，表示模组不能立即升级并重启，HiLink SDK将不进行本次自动升级流程。 182 * 注意：在用户同意设备可以自动升级的情况下，HiLink SDK调用此接口获取设备当前业务状态下，模组是否可以立即升级并重启的标志。 183 * 只有当设备处于业务空闲状态时，接口才可以返回MODULE_CAN_REBOOT。 184 * 当设备处于业务非空闲状态时，接口返回MODULE_CANNOT_REBOOT。 185 */ 186 int HILINK_GetRebootFlag(void); 187 188 /* 189 * 触发设备的ota新版本检测 190 * 检测到的版本，sdk将通过cb回调函数上报。如果不需要获取版本号，则可将cb置空。 191 * 上报的version如果为空，则未成功获取到新版本。 192 * 注意:1、建议调用频次最多一天一次 193 * 2、首次通过手机配网成功后不能调用，建议连云成功后至少5s后调用 194 */ 195 void HILINK_TrigOtaVersionCheck(GetOtaVerCb cb); 196 197 /* 198 * 触发设备的ota新版本升级 199 * 检测到的版本，sdk将通过cb回调函数触发升级 200 */ 201 void HILINK_TrigOtaSelfUpdate(TrigSelfUpdateCb cb); 202 203 #ifdef __cplusplus 204 } 205 #endif 206 207 #endif