Advanced Communication

Halaman ini mencakup metode komunikasi USB lanjutan, port serial, dan socket jaringan. Untuk read dan write dasar, lihat Writes and Reads.

Tipe Transfer USB

Memahami perbedaan antara tipe transfer USB akan membantu Anda memilih metode yang tepat dan men-debug error yang tidak terduga.

Tipe	Metode	Ukuran Tipikal	Kasus Penggunaan
Interrupt	device.write() / device.read()	3–64 byte	Data RGB, perintah kecil, input keyboard/mouse
Bulk	device.write() / device.read()	64–1025 byte	Gambar LCD, pembaruan firmware, blok konfigurasi besar
Control	device.send_report() / device.get_report() / device.control_transfer()	32–192 byte	Autentikasi, laporan fitur HID, konfigurasi perangkat

Fungsi device.write() dan device.read() yang sama digunakan untuk transfer interrupt dan bulk — driver USB menentukan tipe dari endpoint dan ukuran paket.

---

Metode HID Report

device.input_report()

Mengirim transfer kontrol HID GET_INPUT_REPORT. Mirip dengan device.get_report() tetapi secara khusus meminta laporan Input daripada laporan Feature. Gunakan ini ketika get_report() mengembalikan data yang salah karena perangkat memisahkan tipe laporan Input dan Feature-nya.

Parameter	Tipe	Deskripsi	Contoh
DataArray	1D Array	Data permintaan laporan	[0x01]
Length	Int	Ukuran laporan yang diharapkan dalam byte	64

Return	Tipe	Deskripsi
DataArray	1D Array	Byte yang diterima dari perangkat

var inputData = device.input_report([0x01], 64);

---

Metode Raw USB

device.bulk_transfer()

Melakukan transfer bulk atau interrupt langsung ke endpoint USB tertentu. Tidak seperti device.write() dan device.read() yang menggunakan endpoint yang dipilih oleh device.set_endpoint(), ini memungkinkan Anda menarget endpoint mana pun berdasarkan alamatnya.

• Alamat endpoint yang berakhiran 0x80 atau lebih tinggi adalah IN (perangkat → host, baca).
• Alamat endpoint di bawah 0x80 adalah OUT (host → perangkat, tulis).

Parameter	Tipe	Deskripsi	Contoh
Endpoint	Hex	Alamat endpoint USB	0x81
DataArray	1D Array	Data yang dikirim (OUT), atau array kosong (IN)	[0x01, 0x02]
Length	Int	Ukuran transfer dalam byte	64
Timeout	Int	Milidetik sebelum menyerah	100

Return	Tipe	Deskripsi
DataArray	1D Array	Byte yang diterima (transfer IN), atau kosong

// Write to endpoint 0x01
device.bulk_transfer(0x01, [0x00, 0x01, 0x02], 3, 100);

// Read from endpoint 0x81
var response = device.bulk_transfer(0x81, [], 64, 100);

// Large bulk write (e.g. LCD image data)
device.bulk_transfer(0x02, imageData, 1024, 500);

---

device.control_transfer()

Transfer kontrol USB tingkat rendah. Digunakan untuk handshake autentikasi, protokol vendor-specific, dan kasus di mana metode HID tidak cukup. Ini adalah transfer kontrol, bukan transfer bulk.

Parameter	Tipe	Deskripsi	Contoh
RequestType	Hex	Bitmap tipe permintaan USB (arah, tipe, penerima)	0xA1
Request	Hex	Kode permintaan (spesifik perangkat)	0x01
Value	Hex	Field nilai	0x0100
Index	Int	Indeks antarmuka atau endpoint	0x00
DataArray	1D Array	Data yang dikirim (host-ke-perangkat), atau kosong	[]
Length	Int	Panjang respons yang diharapkan (perangkat-ke-host)	192
Timeout	Int	Milidetik sebelum menyerah	1000

Return	Tipe	Deskripsi
DataArray	1D Array	Byte yang diterima (transfer perangkat-ke-host)

Nilai RequestType umum:

Nilai	Arah	Tipe	Penerima	Kasus Penggunaan
0x21	Host → Perangkat	Class	Interface	HID SET_REPORT
0xA1	Perangkat → Host	Class	Interface	HID GET_REPORT
0x80	Perangkat → Host	Standard	Perangkat	Pembacaan deskriptor
0x00	Host → Perangkat	Standard	Perangkat	Perintah standar

// Read authentication token (device → host, class, interface)
var token = device.control_transfer(
    0xA1,    // Device-to-host, class, interface
    0x01,    // GET_REPORT
    0x0100,  // Report type (Feature) + report ID
    0x00,    // Interface 0
    [],      // No outbound data
    192,     // Expect 192 bytes back
    1000     // 1 second timeout
);

// Send a feature report (host → device)
device.control_transfer(0x21, 0x09, 0x0300, 0, [0x03, 0x08, 0x32], 0, 500);

---

Komunikasi Serial

Untuk perangkat serial/COM port, impor modul serial dan atur Type() plugin Anda ke "serial".

import { serial } from "@SignalRGB/serial";

export function Type() { return "serial"; }

Opsi Koneksi

serial.connect({
    baudRate: 115200,  // Default: 115200
    parity: "None",    // "None", "Even", "Odd", "Space", "Mark"
    dataBits: 8,       // 5, 6, 7, or 8
    stopBits: "One"    // "One", "OneAndHalf", "Two"
});

Metode Serial

Metode	Deskripsi	Return
serial.connect(options?)	Buka port serial	bool
serial.disconnect()	Tutup port serial	void
serial.isConnected()	Periksa status koneksi	bool
serial.write(data)	Kirim data	byte yang ditulis
serial.read(maxBytes?, timeoutMs?)	Baca byte yang tersedia (default: semua, timeout 1000ms)	array byte
serial.readAll()	Baca semua byte yang tersedia segera	array byte
serial.availablePorts()	Daftar port COM yang tersedia	array
serial.getPortName()	Nama port saat ini	string
serial.getBaudRate()	Baud rate saat ini	number
serial.getDeviceInfo()	Info port dengan VID, PID, dll.	object

import { serial } from "@SignalRGB/serial";

export function Type() { return "serial"; }

export function Initialize() {
    if (!serial.connect()) {
        device.log("Failed to connect to serial port");
        return;
    }
    device.log(`Connected on ${serial.getPortName()} at ${serial.getBaudRate()} baud`);
}

export function Render() {
    serial.write([0xFF, ...RGBData]);
}

export function Shutdown() {
    serial.disconnect();
}

---

Komunikasi Jaringan (TCP / UDP)

Untuk perangkat yang terhubung ke jaringan, impor modul TCP atau UDP dan atur Type() ke "network". Kedua modul menggunakan model callback berbasis event.

import { tcp } from "@SignalRGB/tcp";
import { udp } from "@SignalRGB/udp";

export function Type() { return "network"; }

TCP

import { tcp } from "@SignalRGB/tcp";

let socket;

export function Initialize() {
    socket = tcp.createSocket();

    socket.on("connected", () => {
        device.log("Connected");
        socket.send([0x01, 0x02, 0x03]);
    });

    socket.on("message", (data) => {
        device.log(`Received: ${data}`);
    });

    socket.on("error", (err) => {
        device.log(`Error: ${err}`);
    });

    socket.connect("192.168.1.100", 8080);
}

export function Render() {
    if (socket.state === socket.ConnectedState) {
        socket.send(RGBData);
    }
}

export function Shutdown() {
    socket.close();
}

Metode TCP:

Metode	Deskripsi
tcp.createSocket()	Buat socket TCP baru
socket.connect(address, port)	Hubungkan ke host
socket.send(data)	Kirim string atau array byte
socket.bind(port)	Ikat ke port lokal
socket.close()	Tutup socket
socket.on(event, callback)	Daftarkan handler event

Event TCP: "connected", "disconnected", "message", "error"

---

UDP

import { udp } from "@SignalRGB/udp";

let socket;

export function Initialize() {
    socket = udp.createSocket();

    socket.on("message", (data) => {
        device.log(`Received: ${data}`);
    });

    socket.connect("192.168.1.100", 21324);
}

export function Render() {
    socket.send(RGBData);
}

export function Shutdown() {
    socket.close();
}

Metode UDP:

Metode	Deskripsi
udp.createSocket()	Buat socket UDP baru
socket.connect(address, port)	Tetapkan tujuan pengiriman default
socket.send(data)	Kirim ke alamat yang terhubung
socket.write(data, address, port)	Kirim ke alamat tertentu tanpa memanggil connect() terlebih dahulu
socket.bind(port)	Ikat ke port lokal untuk menerima
socket.close()	Tutup socket
socket.on(event, callback)	Daftarkan handler event

Event UDP: "connected", "disconnected", "message", "error"

---

DTLS (UDP Terenkripsi)

Untuk perangkat yang memerlukan komunikasi terenkripsi (misalnya Philips Hue), gunakan fitur dtls. Ini menyediakan UDP terenkripsi DTLS menggunakan Pre-Shared Key (PSK).

export function Initialize() {
    device.addFeature("dtls");

    dtls.onConnectionEstablished(() => { device.log("DTLS connected"); });
    dtls.onConnectionClosed(() => { device.log("DTLS closed"); });
    dtls.onConnectionError(() => { device.log("DTLS error"); });

    dtls.createConnection("192.168.1.50", 2100, authIdentity, authKey);
}

export function Render() {
    if (dtls.hasEncryptedConnection()) {
        dtls.send(RGBData);
    }
}

export function Shutdown() {
    dtls.CloseConnection();
}

Metode DTLS:

Metode	Deskripsi
dtls.createConnection(host, port, identity, key)	Buka koneksi terenkripsi menggunakan PSK
dtls.send(data, endianness?)	Kirim data terenkripsi (0 = little-endian, 1 = big-endian)
dtls.hasEncryptedConnection()	Mengembalikan true jika koneksi sudah terjalin
dtls.CloseConnection()	Tutup koneksi
dtls.onConnectionEstablished(cb)	Callback saat koneksi berhasil
dtls.onConnectionClosed(cb)	Callback saat koneksi ditutup
dtls.onConnectionError(cb)	Callback saat error