IoT Platform:Ikhtisar pembaruan OTA

Batasan

Perangkat yang menggunakan OTA harus terhubung ke Platform IoT melalui MQTT. Perangkat dapat mengunduh paket pembaruan melalui MQTT atau HTTPS.

• Setiap Akun Alibaba Cloud mendukung hingga 500 paket pembaruan. Semua Pengguna RAM di bawah akun tersebut berbagi kuota ini.

• Batasan berikut berlaku untuk jumlah, ukuran, format, dan wilayah paket pembaruan.

  • Pengunduhan HTTPS: Satu pembaruan dapat mencakup satu atau beberapa file. Ukuran maksimum satu file adalah 1.000 MB. Hanya file dalam format berikut yang didukung: .bin, .dav, .tar, .gz, .zip, .gzip, .apk, .tar.gz, .tar.xz, dan .pack.

  • Pengunduhan MQTT: Hanya mendukung file tunggal hingga 16 MB, dan hanya tersedia di wilayah China (Shanghai), China (Beijing), dan China (Shenzhen). Gunakan C Link SDK untuk mengembangkan pengunduhan file melalui MQTT. Kode contoh.

Cara kerja

Prasyarat

• Hubungkan perangkat Anda ke Platform IoT. Pengguna Link SDK: Dapatkan C Link SDK dan Panduan koneksi perangkat. Pengguna chip AliOS Things: Dokumentasi AliOS Things.

Prosedur pembaruan OTA

Langkah 1: Laporkan nomor versi

1. Konfigurasikan fitur OTA.

   1. Hubungkan perangkat ke Platform IoT. Di Konsol Platform IoT, pilih instans target, lalu pilih Device Management > Devices. Pastikan status perangkat adalah Online.

   2. Inisialisasi fitur OTA.

   3. Konfigurasikan fitur OTA.

2. Laporkan nomor versi saat ini. Perangkat harus melaporkan versinya sebelum pembaruan pertama. Laporkan versi sekali saat startup, bukan secara berkala. Hanya satu versi modul yang dapat dilaporkan per panggilan. Format topik dan pesan: Format pesan di bagian akhir topik ini.

Langkah 2: Dorong informasi paket pembaruan

1. Tambahkan paket pembaruan: Tambahkan modul OTA dan paket pembaruan untuk produk tersebut.

   • Modul: Modul yang dapat diperbarui yang ditentukan pengguna untuk perangkat dari produk yang sama, seperti firmware, perangkat lunak, atau driver. Modul default merepresentasikan firmware keseluruhan perangkat.

   • Paket lengkap: File pembaruan lengkap. Anda dapat menambahkan satu atau beberapa paket. Menambahkan beberapa paket contoh memerlukan C Link SDK. Perangkat tidak perlu melaporkan versi modul OTA sebelum pembaruan penuh, tetapi tanpa versi yang dilaporkan, Anda tidak dapat menargetkan versi tertentu dalam pembaruan batch. Buat pekerjaan pembaruan batch.

   • Paket delta: Hanya berisi perbedaan antara versi saat ini dan versi target. Perangkat melakukan pemulihan delta lokal untuk merekonstruksi paket lengkap sebelum memperbarui. Pembaruan delta mengurangi kuota pembaruan OTA yang digunakan dan traffic unduhan. Perangkat harus melaporkan versi modul OTA sebelum pembaruan delta.

     • Untuk chip AliOS Things, Alibaba Cloud menyediakan pembuatan paket delta dan algoritma pemulihan delta. Panduan Pengguna Alat Delta OTA.

     • Untuk perangkat lain, Anda harus membuat sendiri paket delta dan mengembangkan algoritma pemulihan delta.

2. Opsional: Verifikasi paket pembaruan: Jika Anda mengatur Verify update package ke Yes saat menambahkan paket, Anda harus menguji pada perangkat terpilih sebelum penerapan batch. Paket hanya tersedia setelah perangkat uji berhasil memperbarui.

   Anda dapat mewajibkan konfirmasi aplikasi sebelum pembaruan OTA dilanjutkan:

   1. Kembangkan aplikasi Anda sendiri. Platform tidak mendorong pesan pembaruan ke perangkat — aplikasi harus mengkueri pesan tersebut.

   2. Aplikasi memanggil ListOTAUnfinishedTaskByDevice untuk mengkueri pekerjaan pembaruan perangkat yang belum selesai.

   3. Aplikasi memanggil ConfirmOTATask untuk mengonfirmasi pekerjaan pembaruan. Platform hanya mendorong pesan pembaruan ke perangkat setelah dikonfirmasi.

3. Buat pekerjaan pembaruan batch: Platform IoT mengirim informasi pembaruan (URL paket, versi, ukuran) ke perangkat secara batch. Status perangkat berubah menjadi To Be Updated atau To Be Confirmed, lalu menjadi Updating ketika perangkat melaporkan progres.

Langkah 3: Unduh paket pembaruan

1. Dapatkan informasi paket pembaruan. Perangkat offline tidak dapat menerima pesan pembaruan. Saat perangkat online, Platform IoT memeriksa adanya pembaruan tertunda dan mendorong pesan jika diperlukan.

   • Platform IoT mendorong informasi paket pembaruan. Perangkat berlangganan: /ota/device/upgrade/${YourProductKey}/${YourDeviceName}. Perangkat menerima informasi pembaruan pada topik ini dalam dua skenario:

     • Perangkat online saat pekerjaan dibuat: Platform IoT segera mendorong informasi pembaruan.

     • Perangkat offline saat pekerjaan dibuat: Platform IoT mendorong informasi pembaruan setelah perangkat online.

   • Perangkat secara aktif menarik informasi paket pembaruan. Perangkat menerbitkan permintaan ke suatu topik, dan Platform IoT mengembalikan informasi paket pembaruan pada topik respons. Format topik dan pesan: Format pesan di bagian akhir topik ini.

   • Format pesan unduhan HTTPS dan MQTT: Format pesan di bagian akhir topik ini.

2. Perangkat mengunduh paket pembaruan menggunakan protokol HTTPS atau MQTT.

   • Unduh file tunggal melalui HTTPS.

   • Unduh beberapa file melalui HTTPS.

   • Unduh file tunggal melalui MQTT.

3. Laporkan progres pembaruan. Format topik dan pesan: Format pesan di bagian akhir topik ini.

   Penting

   Jika perangkat melaporkan progres lebih sering daripada setiap 3 detik, beberapa entri progres mungkin tidak muncul di tab Batch Details di konsol.

4. Laporkan nomor versi baru. Mulai ulang perangkat segera setelah pembaruan. Laporkan versi baru dalam waktu 2 detik setelah online.

   Penting

   Platform IoT menganggap pembaruan berhasil hanya jika versi yang dilaporkan sesuai dengan versi target. Meskipun progres yang dilaporkan mencapai 100%, pembaruan gagal jika nomor versi baru tidak dilaporkan sebelum periode Device update timeout berakhir.

   • Topik: /ota/device/inform/${YourProductKey}/${YourDeviceName}

   • Format pesan

     {
       "id": 1,
       "params": {
         "version": "2.0.0"
       }
     }

Langkah 4: Lihat hasil pembaruan

1. Lihat status pembaruan: Lihat status pembaruan perangkat target, informasi paket pembaruan, dan lainnya.

2. Lihat versi paket pembaruan dan tingkat keberhasilan: Lihat statistik distribusi versi dan tingkat keberhasilan setelah pembaruan. Analisis penyebab kegagalan pembaruan OTA untuk meningkatkan tingkat keberhasilan.

Referensi

• Pemecahan masalah pembaruan gagal: Bagaimana cara memecahkan masalah pembaruan OTA perangkat yang gagal?.

• Kueri log Platform IoT untuk melihat catatan komunikasi antara Platform IoT, perangkat, dan aplikasi.

• Kode kesalahan sisi perangkat: Kode kesalahan untuk perangkat.

• Meneruskan informasi pembaruan perangkat ke server Anda: Konfigurasikan langganan sisi server menggunakan AMQP. Format data topik OTA setelah diteruskan: Format data.

Format pesan

Laporkan nomor versi

• Topik: /ota/device/inform/${YourProductKey}/${YourDeviceName}

• Format pesan

  {
    "id": 1,
    "params": {
      "version": "1.0.0",
      "module":"mcu"      // Jika parameter ini tidak ditentukan, nomor versi default digunakan.
    }
  }

  Parameter	Tipe	Deskripsi
  id	String	ID pesan. Dapat berupa string atau bilangan bulat panjang. Rentang nilai: 0 hingga 4294967295. Harus unik per perangkat.
  version	String	Versi modul OTA.
  module	String	Nama modul OTA. Biarkan kosong saat melaporkan versi modul default. Modul default merepresentasikan firmware keseluruhan perangkat.

Ambil paket pembaruan secara aktif

1. Perangkat menerbitkan pesan ke topik: /sys/{productKey}/{deviceName}/thing/ota/firmware/get.

   • Format pesan

     {
         "id": "123",
         "version": "1.0",
         "params": {
             "module": "MCU"
         },
         "method": "thing.ota.firmware.get"
     }

   • Deskripsi parameter

     Parameter	Tipe	Deskripsi
     id	String	ID pesan. Nilainya harus berupa string yang berisi angka dari 0 hingga 4294967295 dan harus unik untuk perangkat saat ini.
     version	String	Versi protokol. Nilainya tetap 1.0.
     params	Object	Parameter permintaan.
     module	String	Nama modul tempat paket pembaruan berada. Jika Anda tidak menentukan parameter ini, informasi paket pembaruan untuk modul default diminta.
     method	String	Metode permintaan. Nilainya adalah thing.ota.firmware.get.

2. Setelah Platform IoT menerima permintaan, platform mengembalikan informasi paket pembaruan ke perangkat pada topik respons: /sys/{productKey}/{deviceName}/thing/ota/firmware/get_reply.

Unduh melalui HTTPS

Unduh paket file tunggal

{
    "id": "123",
    "code": 200,
    "data": {
        "size": 93796291,
        "sign": "f8d85b250d4d787a9f483d89a974***",
        "version": "10.0.1.9.20171112.1432",
        "isDiff": 1,
        "url": "https://the_firmware_url",
        "signMethod": "MD5",
        "md5": "f8d85b250d4d787a9f48***",
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"Update the underlying camera driver to resolve the issue of blurry video images.\"}"
        }
    }
}

Unduh paket multi-file

{
    "code": "1000",
    "data": {
        "version": "2.0.0",
        "isDiff": 1,
        "signMethod": "MD5",
        "files":[
            {
                "fileSize":432944,
                "fileName":"file1-name",
                "fileUrl":"https://***/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=***XJEH0qAKU%3D&security-token=CAISuQJ***",
                "fileMd5":"93230c3bde425a9d***",
                "fileSign":"93230c3bde425a9d****"
            },
            {
                "fileSize":432945,
                "fileName":"file2-name",
                "fileUrl":"https://***/no***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=***qAKU%3D&security-token=***q6Ft5B2y***",
                "fileMd5":"93230c3bde425a92***",
                "fileSign":"93230c3bde425a92****"
            }
        ],
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"Update the underlying camera driver to resolve the issue of blurry video images.\"}"
        }
    },
    "id": 1626969597470,
    "message": "success"
}

Unduhan protokol MQTT

Saat Anda mengunduh paket pembaruan melalui MQTT, hanya paket file tunggal yang didukung. Setelah perangkat memperoleh informasi paket pembaruan OTA, perangkat dapat memilih untuk melakukan full download atau sharded download.

1. Full download

   • Format pesan

     {
         "id": "123",
         "code": 200,
         "data":{
             "size":432945,
             "digestsign":"A4WOP***SYHJ6DDDJD9***",
             "version":"2.0.0",
             "isDiff":1,
             "signMethod":"MD5",
             "dProtocol":"mqtt",
             "streamId":1397345,
             "streamFileId":1,
             "md5":"93230c3bde***",
             "sign":"93230c3bde42***",
             "module":"MCU",
             "extData":{
                 "key1":"value1",
                 "key2":"value2"
             }
         }
     }

   • Deskripsi parameter

     Parameter	Tipe	Deskripsi
     id	Long	ID pesan. ID harus unik untuk perangkat saat ini.
     message	String	Informasi hasil.
     code	String	Kode status.
     version	String	Versi paket pembaruan perangkat.
     size	Long	Ukuran file paket pembaruan dalam byte. Parameter ini hanya disertakan jika paket pembaruan OTA berisi satu file.
     url	String	Alamat penyimpanan paket pembaruan di Object Storage Service (OSS). Parameter ini hanya disertakan jika paket pembaruan OTA berisi satu file dan diunduh melalui HTTPS.
     dProtocol	String	Protokol untuk mengunduh paket pembaruan. Parameter ini hanya disertakan jika paket pembaruan diunduh melalui MQTT.
     streamId	Long	Identifier unik untuk mengunduh paket pembaruan OTA melalui MQTT. Parameter ini hanya disertakan jika paket pembaruan diunduh melalui MQTT.
     streamFileId	Integer	Identifier unik file paket pembaruan tunggal. Parameter ini hanya disertakan jika paket pembaruan diunduh melalui MQTT.
     isDiff	Long	Parameter ini hanya disertakan jika paket pembaruan adalah paket delta. Nilai 1 menunjukkan bahwa paket hanya berisi perbedaan antara versi baru dan versi sebelumnya, dan perangkat harus melakukan pemulihan delta.
     digestsign	String	Tanda tangan file paket pembaruan OTA untuk pembaruan aman. Hanya disertakan jika pembaruan aman diaktifkan. Aktifkan fitur ini di Tambahkan paket pembaruan.
     sign	String	Tanda tangan file paket pembaruan OTA. Parameter ini hanya disertakan jika paket pembaruan OTA berisi satu file.
     signMethod	String	Metode penandatanganan. Nilai yang valid: SHA256 MD5 Untuk paket pembaruan delta Android, hanya metode penandatanganan MD5 yang didukung.
     md5	String	Jika metode penandatanganan adalah MD5, nilai diberikan ke parameter sign dan md5. Parameter ini hanya disertakan jika paket pembaruan OTA berisi satu file.
     module	String	Nama modul tempat paket pembaruan berada. Jika nama modul adalah default, Platform IoT tidak mengirim parameter module.
     extData	Object	Daftar tag batch pembaruan dan informasi kustom yang didorong ke perangkat. Bidang _package_udi menunjukkan informasi kustom. Format satu tag adalah: "key":"value".
     files	Array	Daftar informasi beberapa file paket pembaruan. Parameter ini disertakan jika paket pembaruan OTA berisi beberapa file. Informasi untuk setiap file adalah sebagai berikut: fileSize: Ukuran file paket pembaruan. fileName: Nama file paket pembaruan. fileUrl, fileMd5, dan fileSign: Parameter-parameter ini memiliki arti yang sama dengan url, md5, dan sign.

2. Optional: Sharded download. Setelah memperoleh informasi paket pembaruan di atas, perangkat mengunduh file paket pembaruan OTA secara terbagi menggunakan topik-topik berikut.

   • Topik permintaan: /sys/${productKey}/${deviceName}/thing/file/download

   • Topik respons: /sys/${productKey}/${deviceName}/thing/file/download_reply

   • Format pesan permintaan

     {
      "id": "123456",
      "version": "1.0",
      "params": {
      "fileToken":"1bb8***",
      "fileInfo":{
      "streamId":1234565,
      "fileId":1
      },
      "fileBlock":{
      "size":256,
      "offset":2
      }
      }
     }

   • Deskripsi parameter pesan permintaan

     Parameter	Tipe	Deskripsi
     id	String	ID pesan. Nilainya harus berupa string yang berisi angka dari 0 hingga 4294967295 dan harus unik untuk perangkat saat ini.
     version	String	Versi protokol. Nilainya tetap 1.0.
     params	Object	Parameter permintaan.
     fileToken	String	Token unik file. Parameter ini tidak wajib. Mendukung angka, huruf, garis bawah (_), dan titik (.). Panjang nilainya maksimal 16 karakter. Catatan penggunaan: Jika Anda menentukan parameter ini, Platform IoT akan mengembalikannya dalam respons ke permintaan perangkat. Ini membantu Anda mengonfirmasi file yang diunduh dalam pesan respons pada skenario unduhan multi-file. Jika perangkat tidak perlu menginisiasi permintaan unduhan untuk file lain selama siklus permintaan dan respons untuk file saat ini, Anda dapat mengosongkan parameter ini.
     fileInfo	Object	Informasi file paket pembaruan OTA.
     streamId	Long	Identifier unik untuk mengunduh paket pembaruan OTA melalui MQTT.
     fileId	Integer	Identifier unik file paket pembaruan tunggal.
     fileBlock	Object	Informasi potongan file.
     size	Integer	Ukuran potongan file yang diminta untuk diunduh, dalam byte. Nilainya harus dalam rentang 256 hingga 131072. Untuk potongan file terakhir, nilainya harus dalam rentang 1 hingga 131072.
     offset	Integer	Alamat awal byte yang sesuai dengan potongan file. Nilainya harus dalam rentang 0 hingga 16777216.

   • Struktur pesan respons

     Item struktur	Deskripsi
     JSON Bytes Length	Panjang array byte yang sesuai dengan string JSON dalam data respons. Harus menempati 2 byte, dengan byte orde tinggi terlebih dahulu (big-endian). Contohnya, jika panjang array byte yang dikonversi dari string JSON respons menggunakan encoding UTF-8 adalah 87 dalam desimal (57 dalam heksadesimal), byte orde tinggi adalah 0x00 dan byte orde rendah adalah 0x57.
     JSON String Bytes	Array byte UTF-8 dari string JSON dalam data respons. Detail format: "Format data JSON respons" di bawah.
     File Block Bytes	Array byte dari potongan file saat ini. Byte-byte tersebut diatur dalam urutan naik sesuai offsetnya dari header file.
     CRC16/IBM	Checksum dari potongan file. Hanya CRC16/IBM yang didukung. Harus menempati 2 byte, dengan byte orde rendah terlebih dahulu (little-endian). Contohnya, jika checksum dari potongan file adalah 0x0809, byte orde rendah adalah 0x09 dan byte orde tinggi adalah 0x08.

   • Format pesan respons

     {
      "id": "123456",
      "code":200,
      "msg":"file size has exceeded the limit 16 MB",
      "data": {
      "fileToken":"1bb8***",
      "fileLength":1238848,
      "bSize":1491,
      "bOffset":2
      }
     }

   • Deskripsi parameter pesan respons

     Parameter	Tipe	Deskripsi
     id	String	ID pesan. Nilainya harus berupa string yang berisi angka dari 0 hingga 4294967295 dan harus unik untuk perangkat saat ini. ID pesan yang dikembalikan adalah ID pesan dari permintaan perangkat, yaitu id dalam data untuk topik permintaan /sys/${productKey}/${deviceName}/thing/file/download.
     code	Integer	Kode status. Nilai 200 menunjukkan keberhasilan.
     msg	String	Pesan kesalahan yang dikembalikan jika permintaan gagal.
     data	Object	Data yang dikembalikan ke perangkat.
     fileToken	String	Token unik file. Parameter ini dikembalikan jika nilai fileToken diteruskan dalam parameter permintaan.
     fileLength	Integer	Ukuran total file dalam byte.
     bSize	Integer	Ukuran potongan file saat ini dalam byte.
     bOffset	Integer	Alamat awal byte yang sesuai dengan potongan file saat ini. Nilai ini sama dengan nilai offset dalam data permintaan. Satuannya byte.

Laporkan progres pembaruan

• Perangkat menerbitkan pesan ke topik: /ota/device/progress/${YourProductKey}/${YourDeviceName}.

• Format pesan

  {
      "id": "123",
      "params": {
          "step": "-1",
          "desc": "OTA update failed. Failed to request the update package information.",
          "module": "MCU"
      }
  }

• Format

  Parameter	Tipe	Deskripsi
  id	String	ID pesan. Nilainya harus berupa string yang berisi angka dari 0 hingga 4294967295 dan harus unik untuk perangkat saat ini.
  step	String	Progres pembaruan OTA. Konfigurasikan nilai progres dan deskripsi berdasarkan skenario pembaruan Anda. Konfigurasi sisi perangkat: Kode contoh. Bilangan bulat dari 1 hingga 100: Persentase progres pembaruan. -1: Pembaruan gagal. -2: Pengunduhan gagal. -3: Verifikasi gagal. -4: Pemrograman gagal.
  desc	String	Deskripsi langkah saat ini. Panjang nilainya maksimal 128 karakter. Jika terjadi pengecualian, bidang ini dapat berisi pesan kesalahan.
  module	String	Nama modul untuk paket pembaruan OTA. Detail modul: Tambahkan paket pembaruan. Saat melaporkan progres pembaruan OTA untuk modul default, Anda dapat mengosongkan parameter module.