Komunikasi Lanjutan

Halaman ini merangkumi kaedah komunikasi USB lanjutan, antaramuka bersiri, dan soket rangkaian. Untuk operasi baca dan tulis asas, lihat Penulisan dan Pembacaan.

Jenis Pemindahan USB

Memahami perbezaan antara jenis pemindahan USB membantu Anda memilih kaedah yang betul dan menyahpepijat ralat yang tidak dijangka.

Jenis	Kaedah	Saiz Biasa	Kes Penggunaan
Interrupt	device.write() / device.read()	3–64 bait	Data RGB, arahan kecil, input papan kekunci/tetikus
Bulk	device.write() / device.read()	64–1025 bait	Imej LCD, kemas kini firmware, blok konfigurasi besar
Control	device.send_report() / device.get_report() / device.control_transfer()	32–192 bait	Pengesahan, laporan ciri HID, konfigurasi peranti

Fungsi device.write() dan device.read() yang sama digunakan untuk pemindahan Interrupt dan Bulk — pemacu USB menentukan jenisnya berdasarkan endpoint dan saiz paket.

---

Kaedah Laporan HID

device.input_report()

Menghantar pemindahan kawalan HID GET_INPUT_REPORT. Serupa dengan device.get_report(), tetapi secara eksplisit meminta laporan Input dan bukannya laporan Ciri. Gunakan ini apabila get_report() mengembalikan data yang salah kerana peranti memisahkan jenis laporan Input dan Ciri.

Parameter	Jenis	Keterangan	Contoh
DataArray	1D Array	Data permintaan laporan	[0x01]
Length	Int	Saiz laporan yang dijangkakan dalam bait	64

Pulangan	Jenis	Keterangan
DataArray	1D Array	Bait yang diterima dari peranti

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

---

Kaedah USB Mentah

device.bulk_transfer()

Melaksanakan pemindahan Bulk atau Interrupt terus ke endpoint USB tertentu. Tidak seperti device.write() dan device.read() yang menggunakan endpoint yang dipilih oleh device.set_endpoint(), ini membolehkan Anda menangani mana-mana endpoint melalui alamatnya.

• Alamat endpoint yang berakhir dengan 0x80 atau lebih tinggi adalah IN (Peranti → Hos, Baca).
• Alamat endpoint di bawah 0x80 adalah OUT (Hos → Peranti, Tulis).

Parameter	Jenis	Keterangan	Contoh
Endpoint	Hex	Alamat endpoint USB	0x81
DataArray	1D Array	Data untuk dihantar (OUT) atau array kosong (IN)	[0x01, 0x02]
Length	Int	Saiz pemindahan dalam bait	64
Timeout	Int	Milisaat sehingga tamat masa	100

Pulangan	Jenis	Keterangan
DataArray	1D Array	Bait yang diterima (pemindahan IN), atau kosong

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

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

// Bulk write besar (contoh: data imej LCD)
device.bulk_transfer(0x02, imageData, 1024, 500);

---

device.control_transfer()

Pemindahan kawalan USB peringkat rendah. Digunakan untuk jabat tangan pengesahan, protokol khusus pengilang, dan kes-kes di mana kaedah HID tidak mencukupi. Ini adalah pemindahan kawalan, bukan pemindahan bulk.

Parameter	Jenis	Keterangan	Contoh
RequestType	Hex	Bitmap jenis permintaan USB (arah, jenis, penerima)	0xA1
Request	Hex	Kod permintaan (khusus peranti)	0x01
Value	Hex	Medan nilai	0x0100
Index	Int	Indeks antaramuka atau endpoint	0x00
DataArray	1D Array	Data untuk dihantar (Hos→Peranti), atau kosong	[]
Length	Int	Panjang tindak balas yang dijangkakan (Peranti→Hos)	192
Timeout	Int	Milisaat sehingga tamat masa	1000

Pulangan	Jenis	Keterangan
DataArray	1D Array	Bait yang diterima (pemindahan Peranti→Hos)

Nilai RequestType biasa:

Nilai	Arah	Jenis	Penerima	Kes Penggunaan
0x21	Hos → Peranti	Class	Interface	HID SET_REPORT
0xA1	Peranti → Hos	Class	Interface	HID GET_REPORT
0x80	Peranti → Hos	Standard	Peranti	Pembacaan penerangan
0x00	Hos → Peranti	Standard	Peranti	Arahan standard

// Baca token pengesahan (Peranti → Hos, Class, Interface)
var token = device.control_transfer(
    0xA1,    // Peranti→Hos, Class, Interface
    0x01,    // GET_REPORT
    0x0100,  // Jenis laporan (Ciri) + ID laporan
    0x00,    // Interface 0
    [],      // Tiada data keluar
    192,     // Jangkakan 192 bait kembali
    1000     // Tamat masa 1 saat
);

// Hantar laporan ciri (Hos → Peranti)
device.control_transfer(0x21, 0x09, 0x0300, 0, [0x03, 0x08, 0x32], 0, 500);

---

Komunikasi Bersiri

Untuk peranti bersiri/COM port, import modul Serial dan tetapkan Type() plugin Anda kepada "serial".

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

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

Pilihan Sambungan

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

Kaedah Bersiri

Kaedah	Keterangan	Pulangan
serial.connect(options?)	Buka port bersiri	bool
serial.disconnect()	Tutup port bersiri	void
serial.isConnected()	Semak status sambungan	bool
serial.write(data)	Hantar data	Bait yang dihantar
serial.read(maxBytes?, timeoutMs?)	Baca bait yang tersedia (lalai: semua, tamat masa 1000 ms)	Array bait
serial.readAll()	Baca semua bait yang tersedia dengan serta-merta	Array bait
serial.availablePorts()	Senaraikan port COM yang tersedia	Array
serial.getPortName()	Nama port semasa	string
serial.getBaudRate()	Kadar baud semasa	number
serial.getDeviceInfo()	Maklumat port dengan VID, PID dll.	object

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

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

export function Initialize() {
    if (!serial.connect()) {
        device.log("Gagal menyambung ke port bersiri");
        return;
    }
    device.log(`Disambungkan pada ${serial.getPortName()} pada ${serial.getBaudRate()} baud`);
}

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

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

---

Komunikasi Rangkaian (TCP / UDP)

Untuk peranti berkemampuan rangkaian, import modul TCP atau UDP dan tetapkan Type() kepada "network". Kedua-dua modul menggunakan model callback berasaskan peristiwa.

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("Disambungkan");
        socket.send([0x01, 0x02, 0x03]);
    });

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

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

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

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

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

Kaedah TCP:

Kaedah	Keterangan
tcp.createSocket()	Cipta soket TCP baharu
socket.connect(address, port)	Sambung ke hos
socket.send(data)	Hantar string atau array bait
socket.bind(port)	Ikat ke port tempatan
socket.close()	Tutup soket
socket.on(event, callback)	Daftarkan pengendali peristiwa

Peristiwa 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(`Diterima: ${data}`);
    });

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

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

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

Kaedah UDP:

Kaedah	Keterangan
udp.createSocket()	Cipta soket UDP baharu
socket.connect(address, port)	Tetapkan destinasi penghantaran lalai
socket.send(data)	Hantar ke alamat yang disambungkan
socket.write(data, address, port)	Hantar ke alamat tertentu tanpa panggilan connect() terlebih dahulu
socket.bind(port)	Ikat ke port tempatan untuk menerima
socket.close()	Tutup soket
socket.on(event, callback)	Daftarkan pengendali peristiwa

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

---

DTLS (UDP Terenkripsi)

Untuk peranti yang memerlukan komunikasi terenkripsi (contohnya Philips Hue), gunakan ciri dtls. Ia menyediakan UDP terenkripsi DTLS dengan Kunci Pra-Dikongsi (PSK).

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

    dtls.onConnectionEstablished(() => { device.log("DTLS disambungkan"); });
    dtls.onConnectionClosed(() => { device.log("DTLS ditutup"); });
    dtls.onConnectionError(() => { device.log("Ralat DTLS"); });

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

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

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

Kaedah DTLS:

Kaedah	Keterangan
dtls.createConnection(host, port, identity, key)	Buka sambungan terenkripsi dengan PSK
dtls.send(data, endianness?)	Hantar data terenkripsi (0 = Little-Endian, 1 = Big-Endian)
dtls.hasEncryptedConnection()	Kembalikan true jika sambungan wujud
dtls.CloseConnection()	Tutup sambungan
dtls.onConnectionEstablished(cb)	Callback apabila sambungan berjaya
dtls.onConnectionClosed(cb)	Callback apabila sambungan ditutup
dtls.onConnectionError(cb)	Callback apabila berlaku ralat