1# OTA Upgrade<a name="EN-US_TOPIC_0000001052170816"></a> 2 3- [Limitations and Constraints](#section691733275418) 4- [Generating a Public/Private Key Pair](#section94411533155010) 5- [Generating an Upgrade Package](#section632383718539) 6- [Uploading the Upgrade Package](#section5772112473213) 7- [Downloading the Upgrade Package](#section251732474917) 8- [Integrating OTA Update Capabilities](#section298217330534) 9- [API Application Scenario \(Default\)](#section7685171192916) 10 - [How to Develop](#section0745926153017) 11 - [Sample Code](#section1337111363306) 12 13- [API Application Scenario \(Custom\)](#section1686395317306) 14 - [How to Develop](#section524515314317) 15 - [Sample Code](#section525974743120) 16 17- [Upgrading the System](#section151997114334) 18 19Over the Air \(OTA\) is a technology that makes it easier for you to remotely update devices, such as IP cameras. A device can be upgraded with a full or differential package. A full package contains all content of a new system, and a differential package contains the differences between the old and new systems. Currently, only the full-package upgrade is supported. 20 21## Limitations and Constraints<a name="section691733275418"></a> 22 23- The open-source suites for devices developed based on Hi3861, Hi3518E V300 and Hi3516D V300 are supported. 24- Devices developed based on Hi3518E V300 and Hi3516D V300 must support the SD card in the Virtual Festival of Aerobatic Teams \(VFAT\) format. 25 26## Generating a Public/Private Key Pair<a name="section94411533155010"></a> 27 281. Download the OpenSSL tool from the following website and install it on a Windows PC, and configure environment variables. 29 30 [http://slproweb.com/products/Win32OpenSSL.html](http://slproweb.com/products/Win32OpenSSL.html) 31 322. Access the **tools\\update\_tools\\update\_pkg\_tools** directory, download the upgrade package making tool, and save it to a local directory, for example, **D:\\ota\_tools**. 333. Run **Generate\_public\_private\_key.bat** in the **ota\_tools\\key** directory to generate **Metis\_PUBLIC.key**, **private.key**, and **public\_arr.txt** that contains public values, as shown in the following figure. Keep the private key properly. 34 35 **Figure 1** Generating a Public/Private Key Pair<a name="fig12913135294011"></a> 36 37 38  39 404. Use the array written in **public\_arr.txt** as a substitute for **g\_pubKeyBuf** in **base\\update\\ota\_lite\\frameworks\\source\\verify\\hota\_verify.c** of the OTA module. 41 42 Example array in **public\_arr.txt**: 43 44 ``` 45 0x30,0x82,0x1,0xa,0x2,0x82,0x1,0x1,0x0,0xc7,0x8c,0xf3,0x91,0xa1,0x98,0xbf,0xb1,0x8c, 46 0xbe,0x22,0xde,0x32,0xb2,0xfa,0xec,0x2c,0x69,0xf6,0x8f,0x43,0xa7,0xb7,0x6f,0x1e,0x4a,0x97, 47 0x4b,0x27,0x5d,0x56,0x33,0x9a,0x73,0x4e,0x7c,0xf8,0xfd,0x1a,0xf0,0xe4,0x50,0xda,0x2b,0x8, 48 0x74,0xe6,0x28,0xcc,0xc8,0x22,0x1,0xa8,0x14,0x9,0x46,0x46,0x6a,0x10,0xcd,0x39,0xd,0xf3, 49 0x4a,0x7f,0x1,0x63,0x21,0x33,0x74,0xc6,0x4a,0xeb,0x68,0x40,0x55,0x3,0x80,0x1d,0xd9,0xbc, 50 0xd4,0xb0,0x4a,0x84,0xb7,0xac,0x43,0x1d,0x76,0x3a,0x61,0x40,0x23,0x3,0x88,0xcc,0x80,0xe, 51 0x75,0x10,0xe4,0xad,0xac,0xb6,0x4c,0x90,0x8,0x17,0x26,0x21,0xff,0xbe,0x1,0x82,0x16,0x76, 52 0x9a,0x1c,0xee,0x8e,0xd9,0xb0,0xea,0xd5,0x50,0x61,0xcc,0x9c,0x2e,0x78,0x15,0x2d,0x1f,0x8b, 53 0x94,0x77,0x30,0x39,0x70,0xcf,0x16,0x22,0x82,0x99,0x7c,0xe2,0x55,0x37,0xd4,0x76,0x9e,0x4b, 54 0xfe,0x48,0x26,0xc,0xff,0xd9,0x59,0x6f,0x77,0xc6,0x92,0xdd,0xce,0x23,0x68,0x83,0xbd,0xd4, 55 0xeb,0x5,0x1b,0x2a,0x7e,0xda,0x9a,0x59,0x93,0x41,0x7b,0x4d,0xef,0x19,0x89,0x4,0x8d,0x5, 56 0x7d,0xbc,0x3,0x1f,0x77,0xe6,0x3d,0xa5,0x32,0xf5,0x4,0xb7,0x9c,0xe9,0xfa,0x6e,0xc,0x9f, 57 0x4,0x62,0xfe,0x2a,0x5f,0xbf,0xeb,0x9a,0x73,0xa8,0x2a,0x72,0xe3,0xf0,0x57,0x56,0x5c,0x59, 58 0x14,0xdd,0x79,0x11,0x42,0x3a,0x48,0xf7,0xe8,0x80,0xb1,0xaf,0x1c,0x40,0xa2,0xc6,0xec,0xf5, 59 0x67,0xc1,0x88,0xf6,0x26,0x5c,0xd3,0x11,0x5,0x11,0xed,0xb1,0x45,0x2,0x3,0x1,0x0,0x1, 60 ``` 61 62 Example configuration for the public key of the OTA module: 63 64 ``` 65 #define PUBKEY_LENGTH 270 66 67 static uint8 g_pubKeyBuf[PUBKEY_LENGTH] = { 68 0x30, 0x82, 0x01, 0x0A, 0x02, 0x82, 0x01, 0x01, 0x00, 0xBF, 0xAA, 0xA5, 0xB3, 0xC2, 0x78, 0x5E, 69 0x63, 0x07, 0x84, 0xCF, 0x37, 0xF0, 0x45, 0xE8, 0xB9, 0x6E, 0xEF, 0x04, 0x88, 0xD3, 0x43, 0x06, 70 ``` 71 725. \(Optional\) For Hi3518E V300 and Hi3516D V300 suites, further replace the array written in **g\_pub\_key** with that in **public\_arr.txt**. The **g\_pub\_key** file is provided in **device\\hisilicon\\third\_party\\uboot\\u-boot-2020.01\\product\\hiupdate\\verify\\update\_public\_key.c** of the U-Boot module. 73 74 Example configuration for the public key of the U-Boot module: 75 76 ``` 77 static unsigned char g_pub_key[PUBKEY_LEN] = { 78 0x30, 0x82, 0x01, 0x0A, 0x02, 0x82, 0x01, 0x01, 79 0x00, 0xBF, 0xAA, 0xA5, 0xB3, 0xC2, 0x78, 0x5E, 80 ``` 81 82 83## Generating an Upgrade Package<a name="section632383718539"></a> 84 851. Save the files to be upgraded in the **ota\_tools\\Components** directory. 86 87 **Figure 2** Location of original image files<a name="fig98691649182817"></a> 88 89 90  91 92 **Table 1** Files to be upgraded 93 94 <a name="table49058318812"></a> 95 <table><thead align="left"><tr id="row16905131385"><th class="cellrowborder" valign="top" width="18.790000000000003%" id="mcps1.2.3.1.1"><p id="p390543111811"><a name="p390543111811"></a><a name="p390543111811"></a>File</p> 96 </th> 97 <th class="cellrowborder" valign="top" width="81.21000000000001%" id="mcps1.2.3.1.2"><p id="p139066318815"><a name="p139066318815"></a><a name="p139066318815"></a>Description</p> 98 </th> 99 </tr> 100 </thead> 101 <tbody><tr id="row3906631180"><td class="cellrowborder" valign="top" width="18.790000000000003%" headers="mcps1.2.3.1.1 "><p id="p14906331987"><a name="p14906331987"></a><a name="p14906331987"></a>u-boot.bin</p> 102 </td> 103 <td class="cellrowborder" valign="top" width="81.21000000000001%" headers="mcps1.2.3.1.2 "><p id="p11368820172317"><a name="p11368820172317"></a><a name="p11368820172317"></a>Renamed from the <strong id="b996114032518"><a name="b996114032518"></a><a name="b996114032518"></a>u-boot-hi351XevX00.bin</strong> file generated after compilation.</p> 104 </td> 105 </tr> 106 <tr id="row775316253222"><td class="cellrowborder" valign="top" width="18.790000000000003%" headers="mcps1.2.3.1.1 "><p id="p14753102517226"><a name="p14753102517226"></a><a name="p14753102517226"></a>kernel.bin</p> 107 </td> 108 <td class="cellrowborder" valign="top" width="81.21000000000001%" headers="mcps1.2.3.1.2 "><p id="p675362582216"><a name="p675362582216"></a><a name="p675362582216"></a>Renamed from the <strong id="b4150615191011"><a name="b4150615191011"></a><a name="b4150615191011"></a>liteos.bin</strong> or <strong id="b115001531019"><a name="b115001531019"></a><a name="b115001531019"></a>kernel</strong> file generated after compilation.</p> 109 </td> 110 </tr> 111 <tr id="row2171010122214"><td class="cellrowborder" valign="top" width="18.790000000000003%" headers="mcps1.2.3.1.1 "><p id="p2017171022212"><a name="p2017171022212"></a><a name="p2017171022212"></a>rootfs.img</p> 112 </td> 113 <td class="cellrowborder" valign="top" width="81.21000000000001%" headers="mcps1.2.3.1.2 "><p id="p618310192211"><a name="p618310192211"></a><a name="p618310192211"></a>Renamed from the <strong id="b168991949142619"><a name="b168991949142619"></a><a name="b168991949142619"></a>rootfs_xxxxx.img</strong> file generated after compilation.</p> 114 </td> 115 </tr> 116 <tr id="row1499631732214"><td class="cellrowborder" valign="top" width="18.790000000000003%" headers="mcps1.2.3.1.1 "><p id="p999617175226"><a name="p999617175226"></a><a name="p999617175226"></a>config</p> 117 </td> 118 <td class="cellrowborder" valign="top" width="81.21000000000001%" headers="mcps1.2.3.1.2 "><p id="p199621712227"><a name="p199621712227"></a><a name="p199621712227"></a>Provides development board and kernel information. For details, see the SD card burning description of the corresponding open-source suite.</p> 119 </td> 120 </tr> 121 <tr id="row8996101712222"><td class="cellrowborder" valign="top" width="18.790000000000003%" headers="mcps1.2.3.1.1 "><p id="p4996141772214"><a name="p4996141772214"></a><a name="p4996141772214"></a>OTA.tag</p> 122 </td> 123 <td class="cellrowborder" valign="top" width="81.21000000000001%" headers="mcps1.2.3.1.2 "><p id="p1735535514293"><a name="p1735535514293"></a><a name="p1735535514293"></a>Contains 32 bytes in the <strong id="b1017052314336"><a name="b1017052314336"></a><a name="b1017052314336"></a>package_type:otaA1S2D3F4G5H6J7K8</strong> format. The last 16 bytes are random, varying with the version.</p> 124 </td> 125 </tr> 126 </tbody> 127 </table> 128 1292. Open the **packet\_harmony.xml** file in **ota\_tools\\xml** to modify **compAddr** as follows. Other items are reserved. 130 131 Example configuration for the component information: 132 133 ``` 134 <group name="own"> 135 <list> 136 <component compAddr="rootfs" compId="0x0017" resType="0x05" isDelete="0x00" compType ="0x00" compVer="1.0">.\Components\rootfs_jffs2.img</component> 137 <component compAddr="kernel_A" compId="0x0018" resType="0x05" isDelete="0x00" compType ="0x00" compVer="1.1">.\Components\liteos.bin</component> 138 <component compAddr="data" compId="0x0019" resType="0x05" isDelete="0x00" compType ="0x00" compVer="1.2">.\Components\userfs_jffs2.img</component> 139 </list> 140 ``` 141 1423. Configure the paths of private and public keys in **packet\_harmony.xml**. 143 144 Example configuration for paths of private and public keys: 145 146 ``` 147 <encryption> 148 <privateKey type="der">.\key\private.key</privateKey> 149 <publicKey type="der">.\key\Metis_PUBLIC.key</publicKey> 150 </encryption> 151 ``` 152 1534. Configure the product name and software version in **ota\_tools\\VersionDefine.bat** for anti-rollback. 154 155 Example configuration for the product name and software version: 156 157 ``` 158 set FILE_PRODUCT_NAME=Hisi 159 160 @rem Set the software version number to a string of no more than 16 characters. 161 set SOFTWARE_VER=OpenHarmony 1.1 162 ``` 163 1645. Run **Make\_Harmony\_PKG.bat** in the **ota\_tools** directory to generate the **Hisi\_OpenHarmony 1.1.bin** upgrade package. The upgrade package is signed using **SHA-256** and **RSA 2048** to ensure its integrity and validity. 165 166 **Figure 3** Upgrade package making tool<a name="fig046712449315"></a> 167 168 169  170 171 172## Uploading the Upgrade Package<a name="section5772112473213"></a> 173 174Upload the **Hisi\_OpenHarmony 1.1.bin** upgrade package to the vendor's OTA server. 175 176## Downloading the Upgrade Package<a name="section251732474917"></a> 177 1781. Download the **Hisi\_OpenHarmony 1.1.bin** upgrade package from the OTA server. 1792. \(Optional\) Insert an SD card \(capacity greater than 100 MB\) if the device is developed based on Hi3518E V300 or Hi3516D V300. 180 181## Integrating OTA Update Capabilities<a name="section298217330534"></a> 182 183- If vendors request OTA capabilities, use the dynamic library **libhota.so** and include the header files **hota\_partition.h** and **hota\_updater.h** in **base\\update\\ota\_lite\\interfaces\\kits**. 184- The **libhota.so** source code is stored in **base\\update\\ota\_lite\\frameworks\\source**. 185- For details about how to use APIs, see [API Application Scenario \(Default\)](#section7685171192916) and OTA APIs in _API Reference_. 186- If the development board needs to be adapted, see the **base\\update\\ota\_lite\\hals\\hal\_hota\_board.h** header file. 187 188## API Application Scenario \(Default\)<a name="section7685171192916"></a> 189 190The upgrade package is generated by following the instructions provided in [Generating a Public/Private Key Pair](#section94411533155010) and [Generating an Upgrade Package](#section632383718539). 191 192### **How to Develop**<a name="section0745926153017"></a> 193 1941. Download the upgrade package for the current device, and then call the **HotaInit** function to initialize the OTA module. 1952. Call the **HotaWrite** function to verify, parse, and write data streams into the device. 1963. Call the **HotaRestart** function to restart the system. 197 198 If you want to cancel the upgrade, call the **HotaCancel** function. 199 200 201### **Sample Code**<a name="section1337111363306"></a> 202 203Perform an OTA update using the upgrade package format and verification method provided by OpenHarmony. 204 205``` 206int main(int argc, char **argv) 207{ 208 printf("this is update print!\r\n"); 209 if (HotaInit(NULL, NULL) < 0) { 210 printf("ota update init fail!\r\n"); 211 return -1; 212 } 213 int fd = open(OTA_PKG_FILE, O_RDWR, S_IRUSR | S_IWUSR); 214 if (fd < 0) { 215 printf("file open failed, fd = %d\r\n", fd); 216 (void)HotaCancel(); 217 return -1; 218 } 219 int offset = 0; 220 int fileLen = lseek(fd, 0, SEEK_END); 221 int leftLen = fileLen; 222 while (leftLen > 0) { 223 if (lseek(fd, offset, SEEK_SET) < 0) { 224 close(fd); 225 printf("lseek fail!\r\n"); 226 (void)HotaCancel(); 227 return -1; 228 } 229 int tmpLen = leftLen >= READ_BUF_LEN ? READ_BUF_LEN : leftLen; 230 (void)memset_s(g_readBuf, READ_BUF_LEN, 0, READ_BUF_LEN); 231 if (read(fd, g_readBuf, tmpLen) < 0) { 232 close(fd); 233 printf("read fail!\r\n"); 234 (void)HotaCancel(); 235 return -1; 236 } 237 if (HotaWrite((unsigned char *)g_readBuf, offset, tmpLen) != 0) { 238 printf("ota write fail!\r\n"); 239 close(fd); 240 (void)HotaCancel(); 241 return -1; 242 } 243 offset += READ_BUF_LEN; 244 leftLen -= tmpLen; 245 } 246 close(fd); 247 printf("ota write finish!\r\n"); 248 printf("device will reboot in 10s...\r\n"); 249 sleep(10); 250 (void)HotaRestart(); 251 return 0; 252} 253``` 254 255## API Application Scenario \(Custom\)<a name="section1686395317306"></a> 256 257The upgrade package is generated in other ways instead of by referring to the preceding two sections. 258 259### **How to Develop**<a name="section524515314317"></a> 260 2611. Download the upgrade package for the current device, and then call the **HotaInit** function to initialize the OTA module. 2622. Call the **HotaSetPackageType** function to set the package type to **NOT\_USE\_DEFAULT\_PKG**. 2633. Call the **HotaWrite** function to write data streams into the device. 2644. Call the **HotaRead** function to read data. Vendors can choose to verify the data. 2655. \(Optional\) Call the **HotaSetBootSettings** function to set the startup tag used for entering the U-Boot mode after restarting the system. 2666. Call the **HotaRestart** function to restart the system. 267 268 If you want to cancel the upgrade, call the **HotaCancel** function. 269 270 271### **Sample Code**<a name="section525974743120"></a> 272 273Perform an OTA update using the upgrade package format and verification method not provided by OpenHarmony. 274 275``` 276int main(int argc, char **argv) 277{ 278 printf("this is update print!\r\n"); 279 if (HotaInit(NULL, NULL) < 0) { 280 printf("ota update init fail!\r\n"); 281 (void)HotaCancel(); 282 return -1; 283 } 284 (void)HotaSetPackageType(NOT_USE_DEFAULT_PKG); 285 int fd = open(OTA_PKG_FILE, O_RDWR, S_IRUSR | S_IWUSR); 286 if (fd < 0) { 287 printf("file open failed, fd = %d\r\n", fd); 288 (void)HotaCancel(); 289 return -1; 290 } 291 int offset = 0; 292 int fileLen = lseek(fd, 0, SEEK_END); 293 int leftLen = fileLen; 294 while (leftLen > 0) { 295 if (lseek(fd, offset, SEEK_SET) < 0) { 296 close(fd); 297 printf("lseek fail!\r\n"); 298 (void)HotaCancel(); 299 return -1; 300 } 301 int tmpLen = leftLen >= READ_BUF_LEN ? READ_BUF_LEN : leftLen; 302 (void)memset_s(g_readBuf, READ_BUF_LEN, 0, READ_BUF_LEN); 303 if (read(fd, g_readBuf, tmpLen) < 0) { 304 close(fd); 305 printf("read fail!\r\n"); 306 (void)HotaCancel(); 307 return -1; 308 } 309 if (HotaWrite((unsigned char *)g_readBuf, offset, tmpLen) != 0) { 310 printf("ota write fail!\r\n"); 311 close(fd); 312 (void)HotaCancel(); 313 return -1; 314 } 315 offset += READ_BUF_LEN; 316 leftLen -= tmpLen; 317 } 318 close(fd); 319 printf("ota write finish!\r\n"); 320 leftLen = fileLen; 321 while (leftLen > 0) { 322 int tmpLen = leftLen >= READ_BUF_LEN ? READ_BUF_LEN : leftLen; 323 (void)memset_s(g_readBuf, READ_BUF_LEN, 0, READ_BUF_LEN); 324 if (HotaRead(offset, READ_BUF_LEN, (unsigned char *)g_readBuf) != 0) {} 325 printf("ota write fail!\r\n"); 326 (void)HotaCancel(); 327 return -1; 328 } 329 /* do your verify and parse */ 330 offset += READ_BUF_LEN; 331 leftLen -= tmpLen; 332 } 333 /* set your boot settings */ 334 (void)HotaSetBootSettings(); 335 printf("device will reboot in 10s...\r\n"); 336 sleep(10); 337 (void)HotaRestart(); 338 return 0; 339} 340``` 341 342## Upgrading the System<a name="section151997114334"></a> 343 344Vendor applications call APIs of the OTA module to perform functions such as signature verification of the upgrade package, anti-rollback, burning and data flushing-to-disk. After the upgrade is complete, the system automatically restarts. 345 346For Hi3518E V300 and Hi3516D V300 open-source suites, the value of **LOCAL\_VERSION** needs to be modified for anti-rollback, for example, modifying **ohos default 1.0** to **ohos default 1.1**. The macro **LOCAL\_VERSION** is provided in **device\\hisilicon\\third\_party\\uboot\\u-boot-2020.01\\product\\hiupdate\\ota\_update\\ota\_local\_info.c**. 347 348Example for modification of the local version: 349 350``` 351const char *get_local_version(void) 352{ 353#if defined(CONFIG_TARGET_HI3516EV200) || \ 354 defined(CONFIG_TARGET_HI3516DV300) || \ 355 defined(CONFIG_TARGET_HI3518EV300) 356#define LOCAL_VERSION "ohos default 1.0" /* increase: default release version */ 357``` 358 359
