Dalam TapHome, Packet Parser adalah antarmuka perangkat keras (Settings → Hardware → Add new interface → Packet Parser) yang digunakan untuk menghubungkan perangkat pihak ketiga ke kontroler.

• Komunikasi: Perangkat dapat terhubung melalui WiFi atau LAN menggunakan protokol TCP/IP.
• Bahasa Skrip: Packet Parser menggunakan bahasa skrip khusus yang dirancang untuk TapHome, memungkinkan kontrol dan manajemen komunikasi perangkat yang terhubung.

Klik di sini untuk informasi lebih lanjut tentang bahasa skrip TapHome.

Sistem TapHome menggunakan struktur hierarkis untuk mengatur perangkat yang terhubung. Dalam struktur ini, Module berfungsi sebagai perangkat induk dan dapat berkomunikasi serta mengendalikan perangkat anak yang terkait.

Module

Antarmuka dapat berisi satu atau lebih Module, yang dalam sebagian besar kasus menangani komunikasi dengan perangkat fisik secara keseluruhan. Dari sudut pandang konfigurasi, Module menentukan:

• Alamat IP atau nama mDNS dari perangkat
• Port komunikasi
• Koneksi aman: Lihat bagian Otentikasi dalam pengaturan layanan Module
• Abaikan kesalahan sertifikat SSL

Perangkat

Merupakan elemen kontrol atau sensor dalam sistem TapHome. Setiap perangkat harus selalu menjadi bagian dari satu Modul induk.

Perangkat yang Didukung:

• Digital output
• Analog output
• Termostat
• Multi-Value Switch
• Sensor suhu
• Variabel
• Tombol tekan
• Meteran listrik
• Kontak reed
• Tirai, kanopi, katup pencampur
• Lampu RGB
• Lampu putih yang dapat diatur

ℹ️ Contoh: Shelly Plug S
Modul ini berisi informasi tentang alamat IP, serta skrip untuk membaca status, mengatur konfigurasi, dan melakukan tindakan layanan. Modul ini mencakup 2 perangkat:
Meteran Listrik – untuk mengukur konsumsi energi perangkat yang disuplai.
Digital Output (relay) – untuk mengendalikan perangkat yang terhubung.

Skrip untuk Membaca dan Menulis

Unit kontrol TapHome dan perangkat yang terhubung dapat berkomunikasi menggunakan permintaan HTTP atau HTTPS GET / POST.

Parsing Respon:

• Fungsi khusus tersedia untuk memproses respon XML.
• Fungsi lain digunakan untuk memproses respon JSON.
• Fungsi tambahan dapat memproses respon dalam bentuk array byte.

Fungsi-fungsi ini memudahkan interpretasi dan pemanfaatan informasi yang diterima dalam respon, sehingga memungkinkan komunikasi yang lebih efisien dan efektif antara unit kontrol TapHome dan perangkat yang terhubung.

TapHome mendefinisikan beberapa atribut yang dapat berisi bahasa skrip:

• Initialize script: Dijalankan saat perangkat mulai beroperasi (misalnya setelah unit kontrol restart).
• Read script: Digunakan untuk menetapkan nilai variabel global atau membaca status kesalahan.
• Read Value script: Skrip untuk membaca nilai spesifik (misalnya suhu yang disetel pada termostat atau suhu yang diukur pada termostat).
• Write Value script: Menulis nilai ke perangkat yang terhubung.
• Listener script: Dijalankan saat setiap paket diterima. Informasi lebih lanjut tersedia di bagian terpisah di bawah.

Klik di sini untuk informasi lebih lanjut tentang bahasa skrip TapHome.

Definisi Status Kesalahan dari Skrip
Menentukan bagaimana skrip menangani dan mendeteksi status kesalahan pada perangkat atau modul yang terhubung.

Atribut Layanan dan Tindakan
Memungkinkan konfigurasi atribut layanan serta tindakan yang dilakukan dalam sistem TapHome untuk kontrol dan pemeliharaan perangkat.

Skrip dan Variabel Pendukung pada Modul
Digunakan untuk menjalankan logika tambahan atau menyimpan data yang mendukung fungsionalitas modul secara keseluruhan.

Skrip dan Variabel Pendukung pada Perangkat
Membantu dalam pengelolaan kontrol dan pengambilan data spesifik dari perangkat yang terhubung ke sistem TapHome.

Untuk informasi lebih lanjut, lihat halaman dokumentasi Modbus di sini.

• HTTP – Untuk komunikasi berbasis web dan API.
• TCP – Protokol komunikasi yang andal untuk koneksi jaringan.
• UDP – Alternatif cepat untuk TCP, digunakan dalam komunikasi waktu nyata (saat ini tidak didukung oleh TapHome).
• FTP – Transfer file antara sistem melalui jaringan.
• MQTT – Protokol komunikasi ringan yang sering digunakan dalam IoT dan sistem otomatisasi.

SENDHTTPREQUEST

Mengirim permintaan HTTP dengan parameter yang ditentukan, lalu menunggu respons dan mengembalikan hasil dalam bentuk string JSON dengan nilai sebagai:

• Content (isi respons)
• Headers (header respons)
• HTTP result code (kode hasil HTTP)

Fungsi ini hanya didukung dalam skrip Packet Parser yang menggunakan protokol HTTP.

SENDHTTPREQUEST( path, method, body, header1, header2… )
SENDHTTPREQUEST( HttpRequest )

Examples:

SENDHTTPREQUEST("/getValue")		Result is:
{
  "Headers": [
    {
      "Key": "Content-Type", “Value": [“application/json"]
    },
    {
      "Key": "Content-Length", “Value": ["1007"]
    },
  ],
  "Content": "{\"value\":31}”,
  "ReasonPhrase": "OK",
  "StatusCode": 200,
  "IsSuccess": true
}

SENDHTTPREQUEST("/doSomething", “POST”, “someData”, “header1:value1”, “header2:value2”, “header3:value3”)

VAR request := HTTPREQUEST(“/path”, “PUT”, “someData”);
request.Headers := { “name1: value1”, “name2: value2” … };
request.Method := “POST”;
VAR response := SENDHTTPREQUEST(request);
 
IF response.IsSuccess
	VAR content := response.Content;
	…
END

SENDDATA

Mengirim data yang ditentukan (string atau Collection UInt8) menggunakan protokol TCP atau UDP.

• Jika data berupa string, maka secara otomatis dikonversi ke bytes menggunakan encoding iso-8859-1.
• Fungsi ini hanya didukung dalam skrip Packet Parser dengan protokol TCP atau UDP.
• Bytes yang diterima dapat diproses dalam Listener script.

SENDDATA( string/Collection )

Examples:

SENDATA(BYTECOLLECTION(“0a dd ef a2”)
SENDATA(“{\”value\”:212}”)

COMPLETESERVICEATTRIBUTE

Fungsi ini digunakan dalam Listener scripts pada Packet Parser dengan protokol TCP/UDP untuk memberitahukan penyelesaian permintaan nilai atribut layanan.

• Contoh penggunaan:

• Anda membuat permintaan dalam Service attribute script menggunakan fungsi SENDDATA.
• Setelah menerima data dalam Listener script, Anda menyelesaikan pembacaan atribut layanan menggunakan COMPLETESERVICEATTRIBUTE.

COMPLETESERVICEATTRIBUTE( attributeName, value, error )

Examples:

COMPLETESERVICEATTRIBUTE(“Uptime”, “2d:21h:43m”)
COMPLETESERVICEATTRIBUTE(“Status”, “”, “Device is offline”)

COMPLETESERVICEACTION

Fungsi ini digunakan dalam Listener scripts pada Packet Parser dengan protokol TCP/UDP, untuk memberitahukan penyelesaian permintaan tindakan layanan.

Contoh Penggunaan:

• Anda membuat permintaan dalam Service action script menggunakan fungsi SENDDATA.
• Setelah menerima data dalam Listener script, Anda menyelesaikan tindakan layanan menggunakan COMPLETESERVICEACTION.

COMPLETESERVICEACTION( actionName, result )

Examples:

COMPLETESERVICEACTION(“Reboot”, “Rebooted successfully”)
COMPLETESERVICEACTION(“Enable cloud”, “Device is offline”)

FTPDOWNLOAD

Mengembalikan data file dalam bentuk Collection UInt8 dari server FTP.

• Fungsi ini hanya didukung dalam skrip Packet Parser yang menggunakan protokol FTP.

FTPDOWNLOAD( pathToFile )

Examples:

FTPDOWNLOAD(“/path/to/file”) 		(Result is Collection)

FTPUPLOAD

Mengunggah data (Collection UInt8 atau string) ke file di server FTP.

• Fungsi ini hanya didukung dalam skrip Packet Parser yang menggunakan protokol FTP.

FTPUPLOAD( pathToFile, data, mode )

Examples:

FTPUPLOAD(“/path/to/file”, “some data”, “write”)
FTPUPLOAD(“/path/to/file”, BYTECOLLECTION(“a7 ff e2”), “append”)

Selain opsi komunikasi lainnya, sistem TapHome memungkinkan komunikasi dengan perangkat pihak ketiga menggunakan protokol MQTT.

• MQTT (Message Queuing Telemetry Transport) adalah protokol pesan publish/subscribe yang ringan, dirancang untuk komunikasi yang efisien dan andal dalam konteks machine-to-machine (M2M) dan Internet of Things (IoT).

Mengaktifkan Komunikasi MQTT di TapHome

Untuk menghubungkan perangkat pihak ketiga menggunakan MQTT, Anda perlu membuat modul terpisah melalui:
➡ Settings → Hardware → Add new interface → MQTT Broker

• Modul ini bertindak sebagai perantara antara perangkat pihak ketiga dan unit kontrol.
• MQTT Broker dapat berjalan secara mandiri di unit kontrol, memungkinkan komunikasi yang independen dan efisien antara perangkat pihak ketiga dan sistem TapHome.

MQTTPUBLISH

Fungsi ini digunakan pada perangkat PacketParser dengan protokol MQTT untuk menerbitkan (publish) pesan ke MQTT broker.

• Memungkinkan pengiriman data ke topik tertentu dalam sistem MQTT.
• Berguna untuk komunikasi perangkat IoT dan otomasi rumah dalam ekosistem TapHome.

MQTTPUBLISH( topic, message )

Examples:

MQTTPUBLISH(“shellies/deviceid/relay/0/command”, “off”)

Dalam TapHome, Listener Script dipicu setiap kali paket diterima. Untuk MQTT, skrip ini dipanggil saat pesan tiba melalui MQTT, dengan Topic yang cocok dengan Topic filter yang telah ditentukan dalam TapHome. Karena bisa ada ratusan pesan per menit, penting untuk mengoptimalkan pemrosesan.

Dua Hal Penting dalam Listener Script:

1. Gunakan Topic Filter yang Restriktif
   • Pastikan hanya pesan yang benar-benar relevan yang masuk.
   • Misalnya, jika hanya ingin pesan dari a.b.c.d, gunakan filter a.b.c.d, bukan hanya a.b.
2. Hindari Pemrosesan Pesan yang Tidak Diperlukan

• Beberapa perangkat menghasilkan banyak pesan dengan topik yang sama.
• Kadang, kita harus menggunakan filter a.b karena kita ingin pesan a.b.c.d dan a.b.x.y, tapi ini juga bisa menyebabkan masuknya pesan a.b.k.l.m yang tidak relevan.
• Beberapa perangkat seperti Zigbee2MQTT mengirim metadata besar setiap beberapa detik, sehingga perlu dilakukan pengelolaan yang efisien.

Menghindari Beban Berlebih dalam MQTT Listener Script:

• Pastikan skrip segera menghentikan eksekusi jika pesan tidak relevan, daripada mengolah data yang tidak diperlukan.
• TapHome memiliki mekanisme untuk mencegah kelebihan beban dari pesan MQTT, tetapi filter yang terlalu longgar dan volume pesan besar tetap bisa menyebabkan peningkatan waktu respons pada kontroler.

Variabel RECEIVEDMSG dalam Listener Script:

• RECEIVEDMSG.Payload → Data pesan yang diterima (BLOB – objek biner besar).
  • Jika payload berupa string, gunakan fungsi TOSTRING untuk mengonversinya.
• RECEIVEDMSG.Topic → Berisi nilai Topic dari pesan MQTT.
• Lebih cepat dan efisien dibandingkan metode lama menggunakan RECEIVEDBYTES.

Improvements in version 2024.1

Instead of:

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);

if parsejson(jsonResponse, "Topic") = "my-topic"

	Va := todouble(parsejson(jsonResponse, "Payload"));

end

it can be written like this:

if RECEIVEDMSG.TOPIC = "my-topic"

	Va := todouble(TOSTRING(RECEIVEDMSG.PAYLOAD));

end

Peningkatan dalam Penggunaan RECEIVEDMSG

Metode baru dengan RECEIVEDMSG.Topic lebih efisien dibandingkan menggunakan PARSEJSON untuk menemukan nilai Topic dalam pesan MQTT.

Keunggulannya:

• Menghemat satu panggilan ke PARSEJSON, yang berarti pemrosesan lebih cepat.
• Lebih praktis saat menerima banyak pesan MQTT, terutama ketika hanya sebagian pesan yang relevan.

Nilai Khusus MQTT dalam RECEIVEDMSG:

• CLIENTID – Identifikasi klien MQTT.
• DUP – Menunjukkan apakah pesan adalah duplikat.
• CONTENTTYPE – Jenis konten yang dikirim.
• EXPIRY – Masa berlaku pesan.

Kontennya bergantung pada apa yang dikirimkan oleh server MQTT, tetapi sintaks lama tetap berfungsi dan akan terus didukung.

RECEIVEDMSG dalam Protokol TCP dan UDP:

• Dalam TCP dan UDP, RECEIVEDMSG hanya memiliki PAYLOAD dan LENGTH sebagai properti yang tersedia.

Packet analysis

Informasi dalam Service Settings Modul Packet Parser

Service Settings pada modul Packet Parser menyediakan data statistik terkait pesan yang diterima dan dikirim, yang mencakup:

• Jumlah pesan dalam 5 menit terakhir dan 30 menit terakhir.
• Jumlah total byte yang diterima.
• Untuk MQTT, informasi disusun berdasarkan MQTT topics.

Manfaat untuk Debugging:

• Membantu dalam menganalisis lalu lintas pesan, sehingga skrip dapat dioptimalkan.
• Mempermudah pengaturan filter topik MQTT agar hanya pesan yang benar-benar dibutuhkan yang dikirim ke Core, mengurangi beban pemrosesan yang tidak perlu.