IoT Platform：Menghubungkan perangkat ke IoT Platform melalui CoAP

Prosedur

Gambar berikut menunjukkan cara menghubungkan perangkat NB-IoT ke IoT Platform.

Menghubungkan perangkat menggunakan enkripsi simetris

1. Terhubung ke server CoAP.
   Endpoint: Untuk informasi tentang cara menghubungkan perangkat ke endpoint instance publik atau instance Enterprise Edition melalui CoAP, lihat Kelola Endpoint Sebuah Instance
2. Verifikasi perangkat.

   Contoh permintaan:

   POST /auth
   Host: ${YourEndpoint}
   Port: 5682
   Accept: application/json atau application/cbor
   Content-Format: application/json atau application/cbor
   payload: {"productKey":"a1NUjcV****","deviceName":"ff1a11e7c08d4b3db2b1500d8e0e55","clientId":"a1NUjcV****&ff1a11e7c08d4b3db2b1500d8e0e55","sign":"F9FD53EE0CD010FCA40D14A9FE******", "seq":"10"}

   Tabel 1. Parameter

   Parameter	Deskripsi
   Method	Metode permintaan. Nilai valid: POST.
   URL	URL. Nilai valid: /auth.
   Host	Endpoint.
   Port	Nomor port. Nilai valid: 5682.
   Accept	Jenis Multipurpose Internet Mail Extensions (MIME) dari data yang diterima oleh perangkat. Nilai valid: application/json dan application/cbor.
   Content-Format	Jenis MIME dari data yang dikirimkan perangkat ke IoT Platform. Nilai valid: application/json dan application/cbor.
   payload	Informasi perangkat dalam format JSON untuk verifikasi. Untuk informasi lebih lanjut, lihat tabel berikut.

   Tabel 2. Field dalam Parameter Payload

   Field	Diperlukan	Deskripsi
   productKey	Ya	ProductKey dalam sertifikat perangkat. ProductKey adalah pengenal unik global (GUID) yang dikeluarkan oleh IoT Platform kepada produk. Anda dapat masuk ke konsol IoT Platform dan melihat ProductKey pada halaman Device Details.
   deviceName	Ya	DeviceName dalam sertifikat perangkat. DeviceName adalah nama perangkat yang ditentukan sistem atau nama kustom saat Anda mendaftarkan perangkat. Anda dapat masuk ke konsol IoT Platform dan melihat DeviceName pada halaman Device Details.
   ackMode	Tidak	Mode komunikasi. Nilai valid: 0: IoT Platform mengembalikan data respons dan Pesan ACK pada saat yang sama. 1: IoT Platform mengembalikan Pesan ACK dan kemudian mengembalikan data respons. Nilai default: 0.
   sign	Ya	Hitung tanda tangan. Anda dapat menggunakan fungsi signmethod(DeviceSecret,content) untuk menghitung tanda tangan. Kemudian, Anda dapat menentukan tanda tangan untuk parameter sign. Algoritma tanda tangan hmacmd5 dan hmacsha1 didukung. Parameter yang diperlukan: signmethod: algoritma tanda tangan. Nilainya harus sama dengan nilai yang Anda tentukan untuk parameter signmethod. DeviceSecret: DeviceSecret perangkat. Anda dapat masuk ke konsol IoT Platform dan melihat DeviceSecret pada halaman Device Details. content: semua parameter yang dikirimkan ke IoT Platform, kecuali parameter version, sign, resources, dan signmethod. Nilai-nilai tersebut digabungkan secara berurutan berdasarkan urutan abjad parameter. Tidak ada simbol penyambung yang digunakan untuk memisahkan nilai-nilai tersebut. Catatan Nilai parameter yang digunakan untuk menghitung tanda tangan harus sama dengan nilai parameter yang Anda tentukan dalam permintaan verifikasi perangkat. Contoh: hmac_md5(mRPVdzSMu2nVBxzK77ERPIMxSYIv****, clientIda1NUjcV****&ff1a11e7c08d4b3db2b1500d8e0e55deviceNameff1a11e7c08d4b3db2b1500d8e0e55productKeya1NUjcV****seq10timestamp1524448722000)
   signmethod	Tidak	Algoritma tanda tangan. Nilai valid: hmacmd5 dan hmacsha1. Nilai default: hmacmd5.
   clientId	Ya	ID klien. ID klien harus memiliki panjang 1 hingga 64 karakter. Kami sarankan Anda menentukan alamat MAC atau SN perangkat sebagai nilai parameter clientId.
   timestamp	Tidak	Timestamp. IoT Platform tidak memverifikasi timestamp.
   seq	Ya	Nomor seri yang terkandung dalam permintaan verifikasi. Nilainya adalah angka acak yang dihasilkan oleh perangkat.

   Contoh respons:

   {"random":"ad2b3a5eb51d6****","seqOffset":1,"token":"MZ8m37hp01w1SSqoDFzo001050****.ad2b"}

   Tabel 3. Parameter Respons

   Parameter	Deskripsi
   random	Kunci yang digunakan untuk mengenkripsi data upstream dan downstream.
   seqOffset	Ofset awal parameter seq.
   token	Token yang dikembalikan jika perangkat diverifikasi.

3. Kirimkan data.

   Contoh permintaan:

   POST /topic/${topic}
   Host: ${YourEndpoint}
   Port: 5682
   Accept: application/json atau application/cbor
   Content-Format: application/json atau application/cbor
   payload: ${your_data}
   CustomOptions: number:2088, 2089

   Tabel 4. Parameter

   Parameter	Diperlukan	Deskripsi
   Method	Ya	Metode permintaan. Nilai valid: POST.
   URL	Ya	URL topik. Format: /topic/${topic}. Ganti variabel ${topic} dengan topik ke mana data dikirim.
   Host	Ya	Endpoint.
   Port	Ya	Nomor port. Nilai valid: 5682.
   Accept	Ya	Jenis MIME dari data yang diterima oleh perangkat. Nilai valid: application/json dan application/cbor.
   Content-Format	Ya	Jenis MIME dari data upstream. IoT Platform tidak memverifikasi data. Nilai valid: application/json dan application/cbor.
   payload	Ya	Data upstream yang dienkripsi menggunakan Standar Enkripsi Lanjutan (AES). Catatan Jika Anda menggunakan AES untuk mengenkripsi data, atur parameter Transform ke AES/CBC/PKCS5Padding dan parameter IV ke 543yhjy97ae7fyfg. Kunci dibuat menggunakan algoritma SHA-256. Contoh: Jika permintaannya adalah deviceSecret=zPwChiLh0EaifR809D5Rc6LDIC6A****, responsnya adalah random=8fe3c8d50e10****. Gabungkan nilai parameter deviceSecret dan random untuk membentuk string dalam format ${deviceSecret},${random}. zPwChiLh0EaifR809D5Rc6LDIC6A****,8fe3c8d50e10**** IoT Platform mengkodekan string sebelumnya dalam format UTF-8, mengenkripsi string yang telah dikodekan menggunakan algoritma SHA-256, dan kemudian mengonversi string menjadi string heksadesimal. 59ea5ac1cb092e5910c405821119959e5297516d185b71e344735cf3f268**** IoT Platform menggunakan fungsi subString(16,48) untuk mengekstrak sub-string sepanjang 32 karakter dari string sebelumnya untuk membentuk kunci. Ekstraksi dimulai dari karakter ke-17 string. 10c405821119959e5297516d185b71e3
   CustomOptions	Ya	Opsi kustom. Nilai valid: 2088: parameter token. Gunakan nilai parameter token yang dikembalikan setelah perangkat diverifikasi. Catatan Parameter token diperlukan saat perangkat mengirimkan data. Jika token telah kedaluwarsa, Anda harus memverifikasi ulang perangkat dan mendapatkan token lain. 2089: parameter seq. Nilainya harus lebih besar dari nilai parameter seqOffset. Nilainya harus berupa angka acak yang unik selama periode validitas verifikasi. Kami sarankan Anda menggunakan nilai yang bertambah berdasarkan parameter seq dalam setiap permintaan dan menggunakan AES untuk mengenkripsi nilai tersebut. Contoh respons: number:2090 2090: ID pesan di IoT Platform. Anda dapat menentukan parameter token dan seq dalam parameter CustomOptions. Anda juga dapat menentukan parameter token dan seq dalam parameter URL. Contoh: /topic/${topic}?token=xxxx&seq=xxxxx. Jika Anda menentukan parameter token dan seq untuk parameter CustomOptions dan URL pada saat yang sama, parameter CustomOptions yang digunakan.

   Setelah pesan dikirim ke IoT Platform, kode status yang menunjukkan permintaan berhasil dan ID pesan yang dihasilkan oleh IoT Platform akan dikembalikan.

Menghubungkan perangkat ke IoT Platform melalui DTLS

1. Terhubung ke server CoAP.
   Endpoint: Untuk informasi tentang cara menghubungkan perangkat ke endpoint instance publik atau instance Enterprise Edition melalui CoAP, lihat Kelola Endpoint Sebuah Instance
2. Unduh Sertifikat Root untuk Saluran Aman DTLS. Kemudian, Anda dapat menggunakan library DTLS untuk menghubungkan perangkat ke IoT Platform.

   psk_id: "${authType}" + "|" + "${signMethod}" + "|" + "${productKey}" + "&" + "${deviceName}" + "timestamp"
   psk: signMethod(DeviceSecret, "${productKey}" + "&" + "${deviceName}" + "${timestamp}")

   Tabel 5. Parameter

   Parameter	Diperlukan	Deskripsi
   authType	Ya	Jenis verifikasi. Nilai valid: devicename.
   signMethod	Ya	Algoritma tanda tangan. Nilai valid: hmacmd5, hmacsha1, dan hmacsha256.
   productKey	Ya	ProductKey dari produk tempat perangkat tersebut termasuk.
   deviceName	Ya	DeviceName dari perangkat.
   DeviceSecret	Ya	DeviceSecret dari perangkat.
   timestamp	Ya	Timestamp.

3. Verifikasi perangkat. Anda dapat menggunakan operasi auth untuk memverifikasi perangkat dan mendapatkan token. Parameter token diperlukan saat perangkat mengirimkan data.

   Contoh permintaan:

   POST /auth
   Host: ${YourEndpoint}
   Port: 5684
   Accept: application/json atau application/cbor
   Content-Format: application/json atau application/cbor
   payload: {"productKey":"ZG1EvTE****","deviceName":"NlwaSPXsCpTQuh8FxBGH","clientId":"mylight1000002","sign":"bccb3d2618afe74b3eab12b94042****"}

   Untuk informasi lebih lanjut tentang parameter yang diperlukan dan parameter payload kecuali parameter Port, lihat Menghubungkan Perangkat Menggunakan Enkripsi Simetris.

   Contoh respons:

   response: {"token":"f13102810756432e85dfd351eeb4****"}

   Tabel 7. Kode Respons

   Kode	Pesan	Payload	Deskripsi
   2.05	Content	Token jika perangkat lulus verifikasi.	Permintaan valid.
   4.00	Bad Request	tidak ada payload	Payload dalam permintaan tidak valid.
   4.01	Unauthorized	tidak ada payload	Permintaan tidak sah.
   4.03	Forbidden	tidak ada payload	Permintaan dilarang.
   4.04	Not Found	tidak ada payload	URL yang diminta tidak ada.
   4.05	Method Not Allowed	tidak ada payload	Metode permintaan tidak diizinkan.
   4.06	Not Acceptable	tidak ada payload	Parameter Accept tidak valid.
   4.15	Unsupported Content-Format	tidak ada payload	Konten yang diminta tidak valid.
   5.00	Internal Server Error	tidak ada payload	Permintaan gagal karena masalah timeout atau kesalahan pada server verifikasi.

4. Kirimkan data.
   Perangkat mengirimkan data ke IoT Platform melalui topik kustom.

   Anda dapat membuat topik kustom di konsol IoT Platform. Pergi ke halaman Product Details dari produk tempat perangkat tersebut termasuk, dan klik tab Topic Categories. Hanya topik dengan izin Publikasi yang dapat digunakan untuk mengirimkan data.

   Sebagai contoh, sebuah topik berada dalam format /${YourProductKey}/${YourDeviceName}/pub. Jika DeviceName adalah device dan ProductKey adalah a1GFjLP ****, Anda dapat menggunakan topik a1GFjLP****.coap.cn-shanghai.link.aliyuncs.com:5684/topic/a1GFjLP****/device/pub untuk mengirimkan data.

   Contoh permintaan:

   POST /topic/${topic}
   Host: ${YourEndpoint}
   Port: 5684
   Accept: application/json atau application/cbor
   Content-Format: application/json atau application/cbor
   payload: ${your_data}
   CustomOptions: number:2088

   Tabel 8. Parameter

   Parameter	Diperlukan	Deskripsi
   Method	Ya	Metode permintaan. Nilai valid: POST.
   URL	Ya	/topic/${topic}. Ganti variabel ${topic} dengan topik ke mana data dikirim.
   Host	Ya	Endpoint.
   Port	Ya	Nomor port. Nilai valid: 5684.
   Accept	Ya	Jenis MIME dari data yang diterima oleh perangkat. Nilai valid: application/json dan application/cbor.
   Content-Format	Ya	Jenis MIME dari data upstream. IoT Platform tidak memverifikasi data. Nilai valid: application/json dan application/cbor.
   CustomOptions	Ya	number: Atur nilai menjadi 2088. token: token yang dikembalikan oleh layanan verifikasi. Catatan Parameter token diperlukan saat perangkat mengirimkan data. Jika token telah kedaluwarsa, Anda harus memverifikasi ulang perangkat dan mendapatkan token lain.

Contoh

Untuk informasi tentang contoh cara menghubungkan perangkat ke IoT Platform melalui CoAP, lihat Hubungkan Perangkat ke IoT Platform melalui CoAP.