Zaawansowana komunikacja

Ta strona omawia zaawansowane metody komunikacji USB, porty szeregowe i gniazda sieciowe. W przypadku podstawowych operacji odczytu i zapisu zobacz Zapisy i odczyty.

Typy przesyłu USB

Zrozumienie różnicy między typami przesyłu USB pomaga wybrać właściwą metodę i debugować nieoczekiwane błędy.

Typ	Metoda	Typowy rozmiar	Przypadek użycia
Interrupt	device.write() / device.read()	3–64 bajty	Dane RGB, małe polecenia, wejście klawiatury/myszy
Bulk	device.write() / device.read()	64–1025 bajtów	Obrazy LCD, aktualizacje oprogramowania układowego, duże bloki konfiguracji
Control	device.send_report() / device.get_report() / device.control_transfer()	32–192 bajty	Uwierzytelnianie, raporty funkcji HID, konfiguracja urządzenia

Te same funkcje device.write() i device.read() są używane zarówno do przesyłu interrupt, jak i bulk — sterownik USB określa typ na podstawie punktu końcowego i rozmiaru pakietu.

---

Metody raportu HID

device.input_report()

Wysyła przesył sterujący HID GET_INPUT_REPORT. Podobny do device.get_report(), ale konkretnie żąda raportu Input zamiast Feature. Użyj tego, gdy get_report() zwraca nieprawidłowe dane, ponieważ urządzenie oddziela typy raportów Input i Feature.

Parametr	Typ	Opis	Przykład
DataArray	Tablica 1D	Dane żądania raportu	[0x01]
Length	Int	Oczekiwany rozmiar raportu w bajtach	64

Zwrot	Typ	Opis
DataArray	Tablica 1D	Bajty odebrane od urządzenia

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

---

Metody Raw USB

device.bulk_transfer()

Wykonuje bezpośredni przesył bulk lub interrupt do konkretnego punktu końcowego USB. W przeciwieństwie do device.write() i device.read(), które używają punktu końcowego wybranego przez device.set_endpoint(), pozwala to na celowanie dowolnego punktu końcowego według adresu.

• Adresy punktów końcowych kończące się na 0x80 lub wyżej to IN (urządzenie → host, odczyt).
• Adresy punktów końcowych poniżej 0x80 to OUT (host → urządzenie, zapis).

Parametr	Typ	Opis	Przykład
Endpoint	Hex	Adres punktu końcowego USB	0x81
DataArray	Tablica 1D	Dane do wysłania (OUT), lub pusta tablica (IN)	[0x01, 0x02]
Length	Int	Rozmiar przesyłu w bajtach	64
Timeout	Int	Milisekundy przed rezygnacją	100

Zwrot	Typ	Opis
DataArray	Tablica 1D	Odebrane bajty (przesyły IN) lub puste

// 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()

Niskopoziomowy przesył sterujący USB. Używany do uścisków dłoni uwierzytelniania, protokołów specyficznych dla dostawcy i przypadków, gdy metody HID nie wystarczają. Jest to przesył sterujący, nie bulk.

Parametr	Typ	Opis	Przykład
RequestType	Hex	Bitmapa typu żądania USB (kierunek, typ, odbiorca)	0xA1
Request	Hex	Kod żądania (specyficzny dla urządzenia)	0x01
Value	Hex	Pole wartości	0x0100
Index	Int	Indeks interfejsu lub punktu końcowego	0x00
DataArray	Tablica 1D	Dane do wysłania (host-do-urządzenia) lub puste	[]
Length	Int	Oczekiwana długość odpowiedzi (urządzenie-do-hosta)	192
Timeout	Int	Milisekundy przed rezygnacją	1000

Zwrot	Typ	Opis
DataArray	Tablica 1D	Odebrane bajty (przesyły urządzenie-do-hosta)

Często używane wartości RequestType:

Wartość	Kierunek	Typ	Odbiorca	Przypadek użycia
0x21	Host → Urządzenie	Klasa	Interfejs	HID SET_REPORT
0xA1	Urządzenie → Host	Klasa	Interfejs	HID GET_REPORT
0x80	Urządzenie → Host	Standard	Urządzenie	Odczyty deskryptora
0x00	Host → Urządzenie	Standard	Urządzenie	Standardowe polecenia

// 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);

---

Komunikacja szeregowa

W przypadku urządzeń szeregowych/COM importujesz moduł serial i ustawiasz Type() swojej wtyczki na "serial".

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

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

Opcje połączenia

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"
});

Metody szeregowe

Metoda	Opis	Zwraca
serial.connect(options?)	Otwórz port szeregowy	bool
serial.disconnect()	Zamknij port szeregowy	void
serial.isConnected()	Sprawdź status połączenia	bool
serial.write(data)	Wyślij dane	zapisane bajty
serial.read(maxBytes?, timeoutMs?)	Odczytaj dostępne bajty (domyślnie: wszystko, timeout 1000ms)	tablica bajtów
serial.readAll()	Natychmiast odczytaj wszystkie dostępne bajty	tablica bajtów
serial.availablePorts()	Wylistuj dostępne porty COM	tablica
serial.getPortName()	Bieżąca nazwa portu	string
serial.getBaudRate()	Bieżąca prędkość transmisji	liczba
serial.getDeviceInfo()	Informacje o porcie z VID, PID itp.	obiekt

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();
}

---

Komunikacja sieciowa (TCP / UDP)

W przypadku urządzeń połączonych sieciowo importujesz moduł TCP lub UDP i ustawiasz Type() na "network". Oba moduły używają modelu callbacków opartego na zdarzeniach.

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();
}

Metody TCP:

Metoda	Opis
tcp.createSocket()	Utwórz nowe gniazdo TCP
socket.connect(address, port)	Połącz z hostem
socket.send(data)	Wyślij string lub tablicę bajtów
socket.bind(port)	Powiąż z lokalnym portem
socket.close()	Zamknij gniazdo
socket.on(event, callback)	Zarejestruj procedurę obsługi zdarzeń

Zdarzenia 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();
}

Metody UDP:

Metoda	Opis
udp.createSocket()	Utwórz nowe gniazdo UDP
socket.connect(address, port)	Ustaw domyślne miejsce docelowe wysyłania
socket.send(data)	Wyślij do połączonego adresu
socket.write(data, address, port)	Wyślij do konkretnego adresu bez wcześniejszego wywołania connect()
socket.bind(port)	Powiąż z lokalnym portem do odbioru
socket.close()	Zamknij gniazdo
socket.on(event, callback)	Zarejestruj procedurę obsługi zdarzeń

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

---

DTLS (Zaszyfrowany UDP)

W przypadku urządzeń wymagających zaszyfrowanej komunikacji (np. Philips Hue) użyj funkcji dtls. Zapewnia zaszyfrowany UDP DTLS przy użyciu klucza wstępnie udostępnionego (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();
}

Metody DTLS:

Metoda	Opis
dtls.createConnection(host, port, identity, key)	Otwórz zaszyfrowane połączenie z PSK
dtls.send(data, endianness?)	Wyślij zaszyfrowane dane (0 = little-endian, 1 = big-endian)
dtls.hasEncryptedConnection()	Zwraca true jeśli połączenie zostało nawiązane
dtls.CloseConnection()	Zamknij połączenie
dtls.onConnectionEstablished(cb)	Callback gdy połączenie się powiedzie
dtls.onConnectionClosed(cb)	Callback gdy połączenie się zamknie
dtls.onConnectionError(cb)	Callback przy błędzie