Integrasi TapHome dengan Sistem Lain melalui Protokol ASCII

TapHome dapat terhubung dengan sistem pihak ketiga melalui protokol integrasi ASCII yang sederhana.
Dengan metode ini, sistem eksternal dapat:

• Mengambil informasi dari perangkat TapHome secara langsung.
• Mengontrol perangkat TapHome, memungkinkan integrasi otomatisasi yang lebih luas.

TapHome mendukung berbagai lapisan komunikasi untuk integrasi dengan sistem eksternal:

• RS485 – Digunakan dalam protokol seperti Modbus RTU dan ASCII, memungkinkan komunikasi serial yang andal.
• TCP/IP – Memfasilitasi koneksi berbasis Ethernet, termasuk integrasi Modbus TCP dan komunikasi berbasis jaringan lokal atau VPN.
• UDP/IP – Menyediakan metode komunikasi yang lebih cepat dan ringan dibandingkan TCP, berguna dalam aplikasi yang membutuhkan respons cepat.

Protokol mendukung beberapa perintah utama untuk berkomunikasi dengan sistem:

• HELP – Menampilkan daftar perintah yang tersedia dan format penggunaannya.
• LIST – Mengembalikan daftar perangkat yang tersedia dalam sistem.
• GET – Mengambil nilai atau status perangkat yang ditentukan.
• SET – Mengatur nilai atau status perangkat tertentu.
• ACTION – Menjalankan aksi atau perintah pada perangkat.
• HEADER – Menentukan parameter komunikasi yang digunakan dalam transaksi data.
• AUTOSEND – Mengaktifkan pengiriman data secara otomatis ketika terjadi perubahan pada perangkat.

Setiap perintah harus diakhiri dengan karakter CRLF (0x0D 0x0A, atau \r\n).
Ini memastikan bahwa sistem mengenali batas akhir perintah dan memprosesnya dengan benar.

Berikut adalah daftar perintah yang dapat digunakan untuk berinteraksi dengan sistem TapHome melalui protokol ASCII:

• HELP – HELP<\r><\n>
  • Menampilkan informasi dasar tentang perintah yang tersedia.
• HEADER [ON/OFF] – HEADER<\r><\n>
  • Mengaktifkan atau menonaktifkan informasi header dalam komunikasi.
• LIST – LIST<\r><\n>
  • Menampilkan semua perangkat yang telah diekspos dalam sistem.
• GET [ID] – GET<\r><\n>
  • Mengambil nilai atau status dari perangkat dengan ID tertentu.
• SET [ID ST VAL1 .. VALN] – SET<\r><\n>
  • Mengatur status ST dan nilai VAL1 hingga VALN untuk perangkat dengan ID tertentu.
• ACTION [ID NUM VAL] – ACTION<\r><\n>
  • Menjalankan aksi NUM dengan nilai VAL pada perangkat dengan ID tertentu.
• PUSHALL [ON/OFF] – PUSHALL<\r><\n>
  • Mengaktifkan atau menonaktifkan fitur push otomatis ketika ada perubahan pada perangkat.

Perintah HEADER<\r><\n> digunakan untuk mengontrol format output data dalam komunikasi TapHome.

Fungsi dan Penggunaannya:

• HEADER tanpa parameter → Menampilkan informasi tentang status saat ini apakah header aktif atau tidak.
• HEADER ON → Mengaktifkan informasi header, sehingga setiap data yang dikirim disertai dengan deskripsi tambahan.
• HEADER OFF → Menonaktifkan informasi header, sehingga sistem hanya mengirim data tanpa deskripsi tambahan.

Perintah LIST<\r><\n> digunakan untuk menampilkan semua perangkat yang telah diekspos dalam sistem TapHome.

Informasi yang Ditampilkan:

• Device ID – ID numerik unik untuk setiap perangkat.
• Device Type – Deskripsi tipe perangkat, seperti Blind, Switch, Dimmer, dll.
• Device Name – Nama perangkat sebagaimana dikonfigurasi dalam sistem TapHome.
• Device Status – Status perangkat dalam bentuk teks (misalnya, OK, UnknownError).

Contoh Output Perintah LIST:

ID:137,Type:Blind,Name:Virtual blind,Status:OK<\r><\n>
ID:51,Type:Switch,Name:Ex Switch,Status:OK<\r><\n>
ID:2,Type:MultiValueSwitch,Name:Heating & Cooling,Status:OK<\r><\n>
ID:205,Type:PushButton,Name:Push button,Status:OK<\r><\n>
ID:242,Type:Dimmer,Name:Analog output,Status:OK<\r><\n>
ID:68,Type:Thermostat,Name:Thermostat 1,Status:UnknownError<\r><\n>
ID:145,Type:Variable,Name:KNXVariable,Status:OK<\r><\n>
ID:143,Type:Variable,Name:Sun azimuth,Status:OK<\r><\n>

Perintah GET [ID]<\r><\n> digunakan untuk mengambil status dan nilai perangkat dalam sistem TapHome.

Penggunaan dan Format Output:

• GET [ID] – Mengambil status dan nilai dari perangkat dengan ID yang ditentukan.
• Output dapat berisi beberapa nilai, tergantung jenis perangkat yang diakses.

Contoh Output Perintah GET

Dengan header aktif:

ID:137,DeviceStatus:0,BlindsLevel:41,BlindsSlope:41<\r><\n>

Dengan header nonaktif:

137,0,41,41<\r><\n>

Perintah SET [ID ST VAL1 ... VALN]<\r><\n> digunakan untuk mengatur status dan nilai perangkat dalam sistem TapHome.

Struktur Perintah

• ID – ID perangkat yang akan diubah.
• ST – Status baru perangkat yang akan diset.
• VAL1 ... VALN – Nilai yang akan diatur untuk perangkat.
  • Jika perangkat memiliki lebih dari satu nilai, semua parameter yang diperlukan harus disertakan.
  • Contoh: Untuk blind, diperlukan level baru dan sudut baru.

Contoh Output Perintah SET

Dengan header aktif:

ID:137,DeviceStatus:0,BlindsLevel:35,BlindsSlope:80<\r><\n>

Dengan header nonaktif:

137,0,35,80<\r><\n>

Perintah ACTION [ID NUM VAL]<\r><\n> digunakan untuk menjalankan aksi pada perangkat dengan ID tertentu.

Aksi yang Tersedia untuk Blinds:

• 0 → Blind Stop – Menghentikan pergerakan blind secara langsung.
• 1 → Adjust Level – Mengatur level dari posisi saat ini dengan nilai perubahan (±VAL).
• 2 → Adjust Angle – Mengatur sudut dari posisi saat ini dengan nilai perubahan (±VAL).

Contoh Output Perintah ACTION

ACTION 137 1 -20<\r><\n>
ID:137,AdjustBlindsLevel:-20<\r><\n>

Perintah PUSHALL<\r><\n> digunakan untuk mengaktifkan pengiriman otomatis perubahan semua perangkat.
Data yang dikirim memiliki format yang sama dengan respons perintah GET.

Catatan Penting tentang Penggunaan di RS485:

• Potensi konflik pada bus RS485 dapat menyebabkan ketidakcocokan data.
• Direkomendasikan hanya digunakan pada jalur full duplex seperti RS232 atau RS422.
• Bisa diaktifkan pada RS485 hanya dalam sistem monitoring, di mana perintah SET dan ACTION tidak digunakan.
• Jika SET dan ACTION diperlukan, sebaiknya gunakan metode polling berkala melalui perintah GET daripada pemantauan otomatis dengan PUSHALL.

Ketika Interface ID unik telah ditentukan, semua perintah dapat digunakan dalam mode alamat.

Struktur Mode Alamat:

• Header alamat mendahului perintah. Formatnya:

!InterfaceID:

InterfaceID dikonfigurasi dalam pengaturan antarmuka.

• Setiap respons juga diawali dengan header alamat yang sama, memastikan data hanya dikirim ke antarmuka yang benar.
• Hanya antarmuka dengan alamat yang cocok yang akan merespons.
  • Jika alamat tidak cocok, tidak ada respons untuk menunjukkan kesalahan.

Contoh Permintaan Mode Alamat:

!2:LIST<\r>:

Menyiapkan Integrasi Protokol untuk Ekspos Perangkat

1. Buka "Expose Devices", lalu pilih "Add New Interface".
2. Dari daftar antarmuka yang tersedia, pilih salah satu protokol integrasi:

• Integration Protocol RS485
• Integration Protocol TCP
• Integration Protocol UDP

Konfigurasi Lanjutan Setelah Menambahkan Antarmuka

1. Isi parameter komunikasi sesuai dengan tipe antarmuka yang dipilih.
2. Tetapkan Interface ID yang unik untuk setiap antarmuka jika ingin menggunakan mode alamat (Address Mode).
3. Pilih terminal komunikasi untuk RS485.
4. Setel parameter jalur serial, sesuai dengan spesifikasi sistem yang akan terhubung:
   • Baud Rate
   • Parity
   • Data Bits
   • Stop Bits

Saat mengonfigurasi antarmuka slave dalam sistem TapHome, Anda perlu menentukan TCP port yang digunakan untuk komunikasi.

Untuk konfigurasi antarmuka slave yang menggunakan UDP, Anda perlu menentukan UDP port yang akan digunakan untuk komunikasi.

Setelah antarmuka integrasi dikonfigurasi, gunakan "Add Device" untuk menambahkan perangkat ke daftar perangkat yang diekspos dalam sistem TapHome.

Menambahkan Perangkat ke Antarmuka Protokol Integrasi

1. Pilih perangkat dari daftar yang ditawarkan.
   • Perangkat yang sudah ditambahkan akan ditampilkan dalam keadaan shadowed (redup) untuk membedakannya.
2. Tambahkan perangkat, lalu sistem akan memasukkannya ke daftar perangkat yang tersedia dalam antarmuka protokol integrasi.
3. Periksa daftar untuk memastikan perangkat telah terintegrasi dengan benar dan siap digunakan dalam komunikasi dengan sistem pihak ketiga.

Mengelola Perangkat yang Diekspos dalam Protokol Integrasi

Setelah perangkat ditambahkan, Anda dapat:

• Klik pada perangkat untuk menampilkan informasi detail tentangnya.
• Mengubah ID perangkat yang dihasilkan secara otomatis jika diperlukan.
• Menghapus perangkat dari daftar perangkat yang diekspos jika tidak lagi diperlukan.

Saat ini, perangkat berikut dapat diekspos dalam protokol integrasi TapHome:

• Thermostat – Untuk pengaturan suhu otomatis.
• Switch – Kontrol on/off perangkat.
• Multi-value Switch – Sakelar dengan beberapa nilai yang dapat dikonfigurasi.
• Push Button – Tombol tekan untuk pemicu manual.
• Reed Contact – Sensor kontak magnetik untuk deteksi pintu/jendela.
• Dimmer / Analog Output – Kontrol intensitas cahaya atau output analog.
• Variable – Penyimpanan dan pemrosesan variabel dalam sistem.
• Blind – Kontrol posisi dan sudut blinds.
• RGB Light – Lampu RGB dengan pengaturan warna dan intensitas.

Device type	Write commands	Read commands
Thermostat	SET E.g. "SET 1 0 24.5" Sets thermostat with ID=1 to no error, set point 24.5ºC	GET Response: Set point | Temperature | Humidity E.g. "GET 1"
Switch	SET <0/1> E.g. "SET 1 0 1" Turns on switch with ID=1. No error state.	GET Response: Switch state (0 or 1)
Multi-value Switch	SET E.g. "SET 1 0 3" Sets multi-value switch with ID=1 to value 3. No error state.	GET Response: Value
Push button	SET E.g. "SET 1 0 1" Simulates short press of push button with ID=1. No error state.	GET Response: BUTTON_PRESSED (1 .. 4)
Reed contact	not available	GET Response: State (0 or 1)
Dimmer / Analog output	SET E.g. "SET 1 0 55.5" Sets dimmer with ID=1 to value 55,5%. No error state.	GET Response: Analog output value (DDD.D)
Variable	SET E.g. "SET 1 0 1234.5" Sets variable with ID=1 to value 1234.5. No error state.	GET Response: Variable value (VVV.V)
RGB Light	SET E.g. "SET 1 0 180 100 50" Sets RGB light with ID=1 to cyan color, full saturation, 50% brithtness. No error state.	GET Response: Hue | Saturation | Brightness
Blind	SET LLL ... Blinds level AAA ... Slats angle E.g. "SET 1 0 100 50 Sets blind with ID=1 to level 100%, with 50% angle of slats. ACTION 1 <+/->LLL E.g. "SET 1 1 -10" Moves blind 10% up ACTION 2 <+/-> AAA E.g. "SET 1 2 +25" Set angle of slats to +25% (direction down). ACTION 0 Stop blinds	GET Response: Level | Angle
Blind group	Same as Blind, with without support for Action 0 (Stop).
Slide, Slide group	not supported	not supported
Alarm, Electric meter, Slide group, Brightness sensor, Impulse counter	not supported	not supported

DEVICE_ID

• Ditetapkan secara bertahap untuk setiap perangkat yang ditambahkan ke daftar perangkat yang diekspos.
• Dapat diubah secara manual ke nilai apa pun, memungkinkan fleksibilitas dalam konfigurasi ID perangkat

ERROR

0 ... OK
1 ... Battery Low
2 ... Battery Critical 3 ... Damaged
4 ... Communication Error
5 ... Unknown Error
6 ... Authorization Error
7 ... Configuration Error

BUTTON PRESSED

1 ... Short press
2 ... Long press
3 ... Double press
4 ... Triple press

ℹ️Debugging Komunikasi RS485

Untuk memantau komunikasi RS485, Anda dapat menggunakan USB RS485 adapter yang terhubung ke PC.
Dengan ini, permintaan dan respons akan terlihat melalui aplikasi terminal.

Peralatan yang Dibutuhkan:

1. Konverter USB ke RS485 standar
   • Contoh: FTDI USB-RS485 Serial Converter
   • Catatan: Konverter ini tidak memiliki isolasi galvanis, sehingga GND dari konverter harus terhubung dengan GND Core.
2. Software Terminal untuk Windows

• HTerm: Download di sini

Mengatur HTerm Terminal

Konfigurasi HTerm untuk TapHome Integration Protocol

Berikut adalah langkah-langkah untuk mengatur HTerm agar sesuai dengan TapHome Integration Protocol:

1. Sesuaikan properti koneksi dengan pengaturan dalam TapHome.
   • Baud Rate default: 9600
   • Data Bits, Parity, dan Stop Bits harus sesuai dengan perangkat yang terhubung.
2. Setel "New Line" ke karakter LF agar output ditampilkan dengan format yang benar.
3. Konfigurasi "Send on Enter" ke CR-LF
   • Ini memastikan bahwa setiap perintah yang dikirim akan diakhiri dengan karakter \r\n.
4. Ketik perintah yang diinginkan (contoh: "HELP").
5. Baca respons dari TapHome, yang akan ditampilkan di jendela penerima HTerm.

Catatan:
Jika Anda ingin melihat perubahan perangkat TapHome secara langsung di konsol, gunakan perintah:

Debugging Komunikasi TCP dengan PuTTY

Untuk memonitor komunikasi TCP, Anda dapat menggunakan PuTTY sebagai terminal debugging.
Unduh PuTTY dari situs resmi.

Mengonfigurasi Koneksi TCP dengan PuTTY

Untuk memastikan komunikasi TapHome Core dengan PuTTY, ikuti langkah berikut:

1. Pilih Connection Type → Setel ke "Raw" untuk komunikasi langsung tanpa protokol tambahan.
2. Masukkan alamat IP dari TapHome Core → Gunakan IP yang sesuai dengan konfigurasi sistem.
3. Isi port TCP → Gunakan port yang telah dikonfigurasi dalam Expose TCP Integration Protocol settings.
4. Klik "Open" → Memulai sesi debugging dan memantau komunikasi secara langsung.