Mengirimkan skrip untuk mengurai data TSL - IoT Platform

Topik ini menjelaskan cara menulis skrip untuk mengurai data Thing Specification Language (TSL) pada produk dengan parameter Jenis Data diatur ke Kustom. Topik ini juga menyediakan contoh skrip untuk mengurai data properti upstream dan downstream.

Prasyarat

Parameter Jenis Data produk harus diatur ke Custom saat pembuatan produk. Untuk informasi lebih lanjut, lihat Buat Produk.

Informasi latar belakang

Jika parameter Jenis Data diatur ke ICA Standard Data Format (Alink JSON), perangkat akan menghasilkan data dalam format Alink JSON dan melaporkannya ke IoT Platform. Untuk detail tentang format data Alink JSON, lihat Properti Perangkat, Event, dan Layanan.

Jika parameter Jenis Data diatur ke Custom, IoT Platform menggunakan skrip penguraian data yang Anda kirimkan untuk mengonversi data TSL upstream ke format Alink JSON dan data TSL downstream ke format kustom saat berkomunikasi dengan perangkat.

Catatan

Dalam contoh ini, properti modul default digunakan. Jika menggunakan modul kustom, tentukan setiap pengenal dalam format berikut: ${Pengenal Modul}:${Pengenal Properti}. Contoh: model1:prop_int16.

Langkah 1: Menulis skrip

Buat produk. Di Konsol IoT Platform, buat produk dan atur parameter Data Type ke Custom.
Tambahkan fitur TSL: Definisikan model TSL untuk produk.
Contoh ini mendefinisikan tiga properti. Tabel berikut menjelaskan propertinya.
Pengenal
Tipe data
Nilai valid
Jenis baca/tulis
prop_float
FLOAT
-100~100
Baca dan tulis
prop_int16
INT32
-100~100
Baca dan tulis
prop_bool
BOOLEAN
0: diaktifkan dan 1: dinonaktifkan
Baca dan tulis
Skrip ditulis untuk mengurai data TSL upstream dan downstream berdasarkan model TSL.
Panjang nilai parameter untuk komunikasi data ditentukan dalam contoh ini. Tabel berikut menjelaskan panjangnya.
- Permintaan yang dikirim oleh perangkat untuk melaporkan data
  Parameter
  Jumlah byte
  Tipe Frame
  1 byte
  ID permintaan
  4 byte
  prop_int16
  2 byte
  prop_bool
  1 byte
  prop_float
  4 byte
- Respon terhadap permintaan pelaporan data
  Parameter
  Jumlah byte
  Tipe Frame
  1 byte
  ID permintaan
  4 byte
  Kode hasil
  1 byte
- Permintaan untuk mengonfigurasi properti
  Parameter
  Jumlah byte
  Tipe Frame
  1 byte
  ID permintaan
  4 byte
  prop_int16
  2 byte
  prop_bool
  1 byte
  prop_float
  4 byte
- Respon terhadap permintaan konfigurasi properti
  Parameter
  Jumlah byte
  Tipe Frame
  1 byte
  ID permintaan
  4 byte
  Kode hasil
  1 byte

Tulis skrip.

Di halaman Products, temukan produk yang ingin dikelola dan klik View di kolom Aksi.
Di halaman product details, klik Message Analysis.

Pilih bahasa pemrograman dan tulis skrip di bidang Edit Script.

Bahasa skrip yang didukung	Fungsi yang mengonversi data upstream dalam format kustom ke data berformat Alink JSON:	Fungsi yang mengonversi data berformat Alink JSON ke data downstream dalam format kustom:	Kode contoh
JavaScript (ECMAScript 5)	rawDataToProtocol	protocolToRawData	Contoh skrip JavaScript
Python 2.7	raw_data_to_protocol	protocol_to_raw_data	Contoh skrip Python
PHP 7.2	rawDataToProtocol	protocolToRawData	Contoh skrip PHP

Catatan

Tulis skrip yang dapat digunakan untuk mengurai data yang dikirim ke topik kustom. Untuk panduan penulisan skrip, lihat Kirim Skrip Analisis Pesan.

Untuk contoh skrip lengkap yang dapat digunakan untuk mengurai data kustom dan data TSL, lihat Contoh Kode JavaScript untuk Mengurai Data Kustom, Kode Contoh Python untuk Mengurai Data Pass-Through atau Kustom, dan Contoh Kode PHP untuk Mengurai Data Kustom.

Langkah 2: Uji skrip secara online

Penting

String heksadesimal dan data berformat JSON yang digunakan dalam contoh ini hanya untuk pengujian dan tidak cocok untuk debugging dalam skenario nyata.

Setelah menulis skrip, konfigurasikan parameter Simulation Type dan tentukan data simulasi di tab Input Simulation untuk menguji skrip.

Uji skrip menggunakan data properti kustom yang dilaporkan oleh perangkat ke IoT Platform.
Atur parameter Jenis Simulasi ke Data Perangkat yang Diupload, masukkan data simulasi berikut, lalu klik Run.
Catatan
Contoh ini menggunakan data JavaScript simulasi. Untuk informasi lebih lanjut tentang contoh skrip JavaScript, lihat Contoh Skrip JavaScript.
Untuk contoh skrip Python dan PHP, lihat Contoh Skrip Python dan Contoh Skrip PHP.
Gunakan alat konversi string ke data heksadesimal untuk mengonversi data berformat JSON menjadi data heksadesimal. Sebagai contoh, jika data heksadesimal yang dikonversi adalah 00002233441232013fa00000, tentukan data berikut:
```
0x00002233441232013fa00000
```
Mesin penguraian data mengonversi data pass-through menjadi data berformat JSON berdasarkan aturan yang didefinisikan dalam skrip.
Klik Parsing Results. Tab Hasil Penguraian menampilkan data yang telah diurai.
```
{
    "method": "thing.event.property.post", 
    "id": "2241348", 
    "params": {
        "prop_float": 1.25, 
        "prop_int16": 4658, 
        "prop_bool": 1
    }, 
    "version": "1.0"
}
```
Uji skrip menggunakan data hasil simulasi yang dikembalikan oleh IoT Platform ke perangkat.
Atur parameter Jenis Simulasi ke Received Device Data, masukkan data berformat JSON berikut, lalu klik Run.
```
{
  "id": "12345",
  "version": "1.0",
  "code": 200,
  "method": "thing.event.property.post",
  "data": {}
}
```
Mesin penguraian data mengonversi data berformat JSON menjadi data berikut:
```
0x0200003039c8
```
Uji skrip menggunakan data simulasi yang dikirim oleh IoT Platform ke perangkat untuk meminta perangkat mengubah properti.
Atur parameter Jenis Simulasi ke Data Perangkat yang Diterima, masukkan data berformat JSON berikut, lalu klik Run.
```
{
    "method": "thing.service.property.set", 
    "id": "12345", 
    "version": "1.0", 
    "params": {
        "prop_float": 123.452, 
        "prop_int16": 333, 
        "prop_bool": 1
    }
}
```
Mesin penguraian data mengonversi data berformat JSON menjadi data berikut:
```
0x0100003039014d0142f6e76d
```
Uji skrip menggunakan data hasil simulasi yang dikembalikan oleh perangkat ke IoT Platform setelah perangkat mengubah properti.
Atur parameter Jenis Simulasi ke Data Perangkat yang Diupload, masukkan data berikut, lalu klik Run.
```
0x0300223344c8
```
Mesin penguraian data mengonversi data pass-through menjadi data berformat JSON berikut:
```
{
  "code": "200",
  "data": {},
  "id": "2241348",
  "version": "1.0"
}
```

Langkah 3: Kirim skrip

Penting

Sebelum IoT Platform dapat menjalankan skrip, Anda harus mengirimkan skrip tersebut. Skrip dalam status Draf tidak dapat dipanggil.

Setelah memastikan bahwa skrip dapat mengurai data sesuai harapan, klik Submit untuk mengirimkan skrip ke IoT Platform. IoT Platform akan menggunakan skrip untuk mengurai data upstream dan downstream.

Langkah 4: Gunakan perangkat fisik untuk debugging

Sebelum menggunakan skrip dalam bisnis Anda, gunakan perangkat fisik untuk berkomunikasi dengan IoT Platform. Ini memungkinkan Anda memeriksa apakah IoT Platform dapat memanggil skrip dan mengurai data upstream dan downstream.

Anda dapat menggunakan SDK Link IoT Platform untuk mengonfigurasi perangkat dan menghubungkannya ke IoT Platform. Untuk informasi lebih lanjut, lihat Link SDK.

Verifikasi bahwa IoT Platform dapat memanggil skrip untuk mengurai data properti upstream.
1. Gunakan perangkat untuk melaporkan data properti ke IoT Platform, seperti 0x00002233441232013fa00000.
2. Di Konsol IoT Platform, pilih Devices > Devices di panel navigasi sisi kiri.
3. Di halaman Perangkat, temukan perangkat dan klik View di kolom Aksi. Di halaman Device Details, klik tab TSL Data lalu tab Status. Periksa apakah data properti yang dilaporkan ada.
Verifikasi bahwa IoT Platform dapat memanggil skrip untuk mengurai data properti downstream.
1. Masuk ke Konsol IoT Platform. Di halaman navigasi sisi kiri, pilih Maintenance > Online Debug.
2. Di halaman Debug Online, pilih produk dan perangkat yang ingin Anda debug lalu pilih Default Module. Pilih pengenal properti yang ingin Anda debug, seperti prop_int16. Atur metode ke Set. Masukkan data berikut dan klik Send Command.
```
{
    "method": "thing.service.property.set", 
    "id": "12345", 
    "version": "1.0", 
    "params": {
        "prop_float": 123.452, 
        "prop_int16": 333, 
        "prop_bool": 1
    }
}
```
3. Periksa apakah perangkat menerima perintah untuk mengonfigurasi properti.
4. Di halaman Device Details, pilih TSL Data > Status. Di tab yang muncul, periksa apakah data properti saat ini dilaporkan oleh perangkat.

(Opsional) Perbarui skrip analisis pesan

Setelah skrip analisis pesan dikirimkan, Anda dapat memodifikasi atau menghapus skrip di tab Message Analysis, kemudian menguji dan mengirimkan skrip baru sesuai dengan langkah-langkah yang dijelaskan dalam topik ini. Setelah pengiriman, skrip akan berlaku untuk semua perangkat produk yang ada dalam waktu sekitar satu menit dan juga akan diterapkan pada perangkat baru dari produk tersebut.

Peringatan

Setelah skrip dimodifikasi dan dikirimkan ulang, pastikan bahwa kode terkait layanan analisis pesan juga dimodifikasi. Jika tidak, gangguan bisnis mungkin terjadi.
Setelah skrip dihapus, layanan analisis pesan menjadi tidak tersedia, yang dapat mengganggu bisnis Anda.

Berhati-hatilah.

Referensi

Untuk informasi tentang proses penguraian data, lihat Penguraian Pesan.
Untuk informasi lebih lanjut tentang cara mengurai data yang dikirim ke topik kustom, lihat Kirim Skrip Analisis Pesan.
Untuk informasi tentang operasi API yang digunakan untuk mengirim pesan ke perangkat, lihat Penggunaan Model TSL dan Pesan.

Pengenal	Tipe data	Nilai valid	Jenis baca/tulis
prop_float	FLOAT	-100~100	Baca dan tulis
prop_int16	INT32	-100~100	Baca dan tulis
prop_bool	BOOLEAN	0: diaktifkan dan 1: dinonaktifkan	Baca dan tulis

Parameter	Jumlah byte
Tipe Frame	1 byte
ID permintaan	4 byte
prop_int16	2 byte
prop_bool	1 byte
prop_float	4 byte