设备端OTA升级的MQTT通信流程与数据格式 - IoT Platform

IoT Platform mendukung fitur over-the-air (OTA). Anda dapat menggunakan fitur OTA untuk memperbarui perangkat. Topik ini menjelaskan cara menggunakan fitur OTA untuk memperbarui perangkat ketika Message Queuing Telemetry Transport (MQTT) digunakan untuk menghubungkan perangkat ke IoT Platform. Topik ini juga mencakup topik-topik dan format data yang digunakan selama penerusan data dalam pembaruan OTA.

Proses

Gambar berikut menunjukkan proses melakukan pembaruan OTA melalui MQTT.

Catatan

Untuk melakukan pembaruan diferensial, perangkat harus mengirimkan nomor versi modul OTA. Untuk pembaruan penuh, perangkat tidak perlu mengirimkan nomor versi modul OTA. Jika nomor versi tidak dikirimkan, Anda tidak dapat menentukan versi sumber saat mengonfigurasi pembaruan massal. Untuk informasi lebih lanjut, lihat Memulai Pembaruan Massal.
Perangkat hanya perlu mengirimkan nomor versi sekali selama startup sebelum pembaruan pertama. Setelah pembaruan diinstal pada perangkat, perangkat harus segera mengirimkan nomor versi saat ini.
Saat Anda mulai memperbarui beberapa perangkat di konsol IoT Platform, setiap perangkat akan berada dalam status Menunggu Pembaruan.
Ketika IoT Platform menerima kemajuan pembaruan yang dikirim oleh perangkat, status perangkat berubah menjadi Memperbarui.
Catatan Setelah perangkat menerima notifikasi pembaruan dari IoT Platform, perangkat dapat mengunduh paket pembaruan dan melakukan pembaruan segera atau selama jam-jam sepi bisnis.
IoT Platform memeriksa apakah pembaruan OTA berhasil berdasarkan nomor versi yang dikirimkan oleh perangkat.
Perangkat offline tidak dapat menerima notifikasi pembaruan dari IoT Platform.
Setelah perangkat online, IoT Platform memeriksa apakah perangkat perlu diperbarui. Jika pembaruan diperlukan, IoT Platform mengirimkan notifikasi pembaruan ke perangkat. Jika tidak, tidak ada notifikasi yang dikirim.

Format pesan

Untuk informasi lebih lanjut tentang cara menggunakan SDK berbasis bahasa untuk mengimplementasikan pembaruan OTA pada perangkat, lihat Dokumentasi Link SDK.

Langkah-langkah berikut menjelaskan proses melakukan pembaruan OTA:

Opsional. Hubungkan perangkat ke layanan OTA dari IoT Platform dan kirimkan nomor versi.

Nomor versi didorong ke topik berikut melalui MQTT: /ota/device/inform/${productKey}/${deviceName}. Contoh pesan:

{
    "id": "123",
    "params": {
        "version": "1.0.1",
        "module": "MCU"
    }
}

Tabel 1. Parameter
Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat.
version	String	Versi modul OTA.
module	String	Nama modul OTA. Catatan Jika perangkat mengirimkan versi modul default, parameter module bersifat opsional. Versi modul default menunjukkan versi firmware perangkat.

Di konsol IoT Platform, tambahkan paket pembaruan, periksa paket pembaruan, lalu mulai pembaruan massal.
Untuk informasi lebih lanjut, lihat Ikhtisar.

Setelah Anda memulai pembaruan di konsol IoT Platform, perangkat menerima URL paket pembaruan dari sebuah topik.

Pesan yang mencakup URL dikirim dari layanan OTA IoT Platform ke topik berikut: /ota/device/upgrade/${productKey}/${deviceName}. Setelah IoT Platform mengirimkan permintaan pembaruan OTA ke perangkat, perangkat menerima URL paket pembaruan dari topik tersebut.

Contoh pesan:

Contoh informasi tentang paket pembaruan OTA yang berisi satu file:

Unduh paket pembaruan OTA melalui HTTPS:

{
    "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\":\"Perbarui driver kamera untuk mencegah video buram.\"}"
        }
    }
}

Unduh paket pembaruan OTA melalui MQTT:

{
    "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"
        }
    }
}

Anda dapat mengunduh paket pembaruan OTA yang berisi beberapa file hanya melalui HTTP. Contoh informasi:

{
    "id": "123",
    "code": 200,
    "data": {
        "version": "2.0.0",
        "isDiff": 1,
        "signMethod": "MD5",
        "files":[
            {
                "fileSize":432944,
                "fileName":"file1-name",
                "fileUrl":"https://iotx***.aliyuncs.com/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7***U%3D&security-token=CAISu***",
                "fileMd5":"93230c3bde425a9d7984a594ac55ea1e",
                "fileSign":"93230c3bde425a9d7984a594ac55****"
            },
            {
                "fileSize":432945,
                "fileName":"file2-name",
                "fileUrl":"https://iotx-***.aliyuncs.com/no***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7P***KU%3D&security-token=CAISuQJ***",
                "fileMd5":"93230c3bde425a9d7984a594ac56ea1f",
                "fileSign":"93230c3bde425a9d7984a594ac56****"
           }
        ],
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"Perbarui driver kamera untuk mencegah video buram.\"}"
        }
    }
}

Tabel 2. Parameter
Parameter	Tipe	Deskripsi
id	Long	ID pesan. Setiap ID pesan unik untuk perangkat.
message	String	Pesan respons.
code	String	Kode status HTTP.
version	String	Versi paket pembaruan OTA.
size	Long	Ukuran paket pembaruan. Unit: byte. Parameter ini tersedia jika paket pembaruan OTA berisi satu file.
url	String	URL Object Storage Service (OSS) dari paket pembaruan OTA. Parameter ini tersedia jika paket pembaruan OTA berisi satu file dan protokol unduhan adalah HTTPS.
dProtocol	String	Protokol yang digunakan untuk mengunduh paket pembaruan OTA. Parameter ini tersedia jika protokol unduhan adalah MQTT.
streamId	Long	ID unik yang dihasilkan saat Anda mengunduh paket pembaruan OTA melalui MQTT. Parameter ini tersedia jika protokol unduhan adalah MQTT.
streamFileId	Integer	ID unik dari paket pembaruan OTA yang berisi satu file. Parameter ini tersedia jika protokol unduhan adalah MQTT.
isDiff	Long	Parameter ini tersedia jika paket pembaruan adalah paket pembaruan delta. Atur nilainya menjadi 1. Nilai ini menentukan bahwa paket pembaruan hanya berisi perbedaan antara versi baru dan versi sebelumnya. Dalam hal ini, pembaruan delta dilakukan.
digestsign	String	Tanda tangan paket pembaruan OTA setelah pembaruan aman dilakukan. Parameter ini tersedia jika fitur pembaruan aman diaktifkan untuk paket pembaruan OTA. Untuk informasi lebih lanjut tentang cara mengaktifkan fitur pembaruan aman, lihat Tambahkan paket pembaruan.
sign	String	Tanda tangan paket pembaruan OTA. Parameter ini tersedia jika paket pembaruan OTA berisi satu file.
signMethod	String	Algoritma tanda tangan. Nilai valid: `SHA256` `MD5` Paket pembaruan delta untuk Android hanya mendukung algoritma MD5.
md5	String	Jika algoritma tanda tangan adalah MD5, IoT Platform menentukan nilai untuk parameter sign dan md5. Parameter ini tersedia jika paket pembaruan OTA berisi satu file.
module	String	Nama modul tempat paket pembaruan OTA diterapkan. Catatan Jika paket pembaruan OTA diterapkan ke modul default, IoT Platform tidak mengirimkan parameter module.
extData	Object	Tag batch pembaruan dan informasi kustom yang ingin Anda dorong ke perangkat melalui IoT Platform. _package_udi menentukan informasi kustom. Format setiap tag: `"key":"value"`.
files	Array	Informasi tentang file dalam paket pembaruan. Parameter ini tersedia jika paket pembaruan OTA berisi beberapa file. Informasi tentang satu file: fileSize: ukuran file. fileName: nama file. fileUrl, fileMd5, dan fileSign: Parameter ini sesuai dengan parameter url, md5, dan sign dalam tabel ini.

Opsional. Unduh paket pembaruan dalam waktu 24 jam setelah SDK perangkat menerima URL paket pembaruan. Jika tidak, URL akan kedaluwarsa. Perangkat dapat meminta tugas pembaruan baru dari IoT Platform dengan mengirimkan pesan ke topik berikut:

/sys/${productKey}/${deviceName}/thing/ota/firmware/get. Contoh pesan:

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

Tabel 4. Parameter
Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat.
version	String	Versi protokol. Atur nilainya menjadi 1.0.
params	Object	Parameter permintaan.
module	String	Nama modul tempat paket pembaruan OTA diterapkan. Catatan Jika Anda tidak mengonfigurasi parameter ini, informasi paket pembaruan modul default diminta.
method	String	Metode permintaan. Atur nilainya menjadi `thing.ota.firmware.get`.

Setelah IoT Platform menerima permintaan, IoT Platform mengirimkan informasi paket pembaruan ke topik berikut: /sys/${productKey}/${deviceName}/thing/ota/firmware/get_reply.

IoT Platform mengirimkan informasi tentang paket pembaruan terbaru ke perangkat. Contoh respons:

Contoh informasi tentang paket pembaruan OTA yang berisi satu file:

Unduh paket pembaruan OTA melalui HTTPS:

{
    "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\":\"Perbarui driver kamera untuk mencegah video buram.\"}"
        }
    }
}

Unduh paket pembaruan OTA melalui MQTT:

{
    "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"
        }
    }
}

Anda dapat mengunduh paket pembaruan OTA yang berisi beberapa file hanya melalui HTTP. Contoh informasi:

{
    "id": "123",
    "code": 200,
    "data": {
        "version": "2.0.0",
        "isDiff": 1,
        "signMethod": "MD5",
        "files":[
            {
                "fileSize":432944,
                "fileName":"file1-name",
                "fileUrl":"https://iotx***.aliyuncs.com/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7***U%3D&security-token=CAISu***",
                "fileMd5":"93230c3bde425a9d7984a594ac55ea1e",
                "fileSign":"93230c3bde425a9d7984a594ac55****"
            },
            {
                "fileSize":432945,
                "fileName":"file2-name",
                "fileUrl":"https://iotx-***.aliyuncs.com/no***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7P***KU%3D&security-token=CAISuQJ***",
                "fileMd5":"93230c3bde425a9d7984a594ac56ea1f",
                "fileSign":"93230c3bde425a9d7984a594ac56****"
           }
        ],
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"Perbarui driver kamera untuk mencegah video buram.\"}"
        }
    }
}

Tabel 1. Tabel berikut menjelaskan parameter.
Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat. ID pesan dalam respons sama dengan ID pesan dalam permintaan. Anda dapat melihat parameter `id` dalam data yang dikirimkan ke topik /sys/${productKey}/${deviceName}/thing/ota/firmware/get.
code	Integer	Kode status. Nilai 200 menunjukkan permintaan berhasil.
data	String	Informasi tentang paket pembaruan. Untuk informasi lebih lanjut, lihat Dorong informasi paket pembaruan OTA ke perangkat.

IoT Platform mengirimkan respons jika tidak ada informasi paket pembaruan. Contoh respons:
```
{
    "id": "123",
    "code": 200,
    "data": {
    }
}
```

Setelah SDK perangkat menerima URL paket pembaruan, perangkat memanggil operasi API di SDK untuk mengunduh paket pembaruan. Untuk informasi lebih lanjut, lihat Ikhtisar.
Catatan Perangkat tidak dapat secara otomatis mengunduh paket pembaruan. Anda harus memanggil operasi yang diperlukan di SDK untuk mengunduh paket pembaruan. Jika perangkat gagal mengunduh paket pembaruan dari URL dalam waktu 24 jam, URL akan kedaluwarsa.
Untuk informasi lebih lanjut tentang log yang dihasilkan saat Anda mengunduh paket pembaruan, lihat topik berikut:

Selama pembaruan, perangkat mengirimkan kemajuan pembaruan ke topik berikut: /ota/device/progress/${productKey}/${deviceName}.

Catatan Kami merekomendasikan Anda mengatur frekuensi pelaporan kemajuan maksimal sekali setiap 3 detik. Jika frekuensi aktual melebihi batas, Anda mungkin gagal melihat semua informasi kemajuan pada halaman Batch Details dari paket pembaruan OTA di konsol IoT Platform.

Contoh pesan:

{
    "id": "123",
    "params": {
        "step": "-1",
        "desc": "Pembaruan OTA gagal karena tidak ditemukan informasi paket pembaruan.",
        "module": "MCU"
    }
}

Tabel 3. Parameter
Parameter	Tipe	Deskripsi
id	String	ID pesan. Nilai valid: 0 hingga 4294967295. Setiap ID pesan harus unik untuk perangkat.
step	String	Kemajuan pembaruan OTA. Nilai valid: Bilangan bulat dari 1 hingga 100: menunjukkan persentase yang mewakili kemajuan pembaruan. `-1`: menunjukkan bahwa pembaruan gagal. `-2`: menunjukkan bahwa unduhan gagal. `-3`: menunjukkan bahwa verifikasi gagal. `-4`: menunjukkan bahwa flashing firmware gagal. Nilai kemajuan dan deskripsi pembaruan OTA dapat dikonfigurasi di perangkat berdasarkan kebutuhan aktual. Untuk informasi lebih lanjut tentang cara mengembangkan fitur pembaruan OTA di perangkat, lihat Contoh kode.
desc	String	Deskripsi langkah saat ini. Deskripsi tidak boleh melebihi 128 karakter. Jika terjadi pengecualian, parameter ini berisi pesan kesalahan.
module	String	Nama modul tempat paket pembaruan OTA diterapkan. Untuk informasi lebih lanjut, lihat Tambahkan paket pembaruan. Catatan Jika perangkat mengirimkan kemajuan pembaruan modul default, parameter module bersifat opsional.

Setelah pembaruan OTA perangkat selesai, perangkat mengirimkan versi firmware saat ini ke topik berikut: /ota/device/inform/${productKey}/${deviceName}. Jika versi yang dikirimkan sama dengan versi yang dikirim oleh layanan OTA ke topik tersebut, pembaruan OTA berhasil. Jika tidak, pembaruan OTA gagal.
Catatan IoT Platform memeriksa apakah pembaruan OTA berhasil berdasarkan versi firmware yang dikirimkan. Sebagai contoh, perangkat mengirimkan kemajuan pembaruan 100%. Namun, jika versi firmware saat ini tidak dikirimkan dalam periode timeout tertentu, IoT Platform menganggap bahwa pembaruan gagal.
Kami merekomendasikan Anda segera me-restart perangkat setelah pembaruan OTA selesai. Setelah perangkat online, kirimkan nomor versi saat ini. Interval antara permintaan untuk menghubungkan perangkat ke IoT Platform dan permintaan untuk mengirimkan nomor versi saat ini tidak boleh melebihi 2 detik.

Kesalahan umum

Tanda tangan tidak valid. Jika URL paket pembaruan tidak valid atau diubah, kesalahan ini terjadi, seperti ditunjukkan pada gambar berikut.
Akses ditolak. Kesalahan terjadi karena URL telah kedaluwarsa. Setiap URL valid selama 24 jam.

Referensi API

Pembaruan OTA