Geavanceerde communicatie

Deze pagina behandelt geavanceerde USB-communicatiemethoden, seriële poorten en netwerksockets. Voor basislees- en schrijfbewerkingen, zie Schrijven en lezen.

USB-overdrachtstypen

Het begrijpen van het verschil tussen USB-overdrachtstypen helpt u de juiste methode te kiezen en onverwachte fouten te debuggen.

Type	Methode	Typische grootte	Gebruiksscenario
Interrupt	device.write() / device.read()	3–64 bytes	RGB-gegevens, kleine opdrachten, toetsenbord/muis-invoer
Bulk	device.write() / device.read()	64–1025 bytes	LCD-afbeeldingen, firmware-updates, grote configuratieblokken
Control	device.send_report() / device.get_report() / device.control_transfer()	32–192 bytes	Authenticatie, HID-functierapporten, apparaatconfiguratie

Dezelfde device.write()- en device.read()-functies worden gebruikt voor zowel interrupt- als bulk-overdrachten — het USB-stuurprogramma bepaalt het type op basis van het eindpunt en de pakketgrootte.

---

HID-rapportmethoden

device.input_report()

Verzendt een HID GET_INPUT_REPORT-beheersoverdracht. Vergelijkbaar met device.get_report() maar vraagt specifiek een Input-rapport in plaats van een Feature-rapport. Gebruik dit wanneer get_report() onjuiste gegevens retourneert omdat het apparaat zijn Input- en Feature-rapporttypen scheidt.

Parameter	Type	Beschrijving	Voorbeeld
DataArray	1D-array	Rapportaanvraaggegevens	[0x01]
Length	Int	Verwachte rapportgrootte in bytes	64

Retour	Type	Beschrijving
DataArray	1D-array	Bytes ontvangen van het apparaat

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

---

Ruwe USB-methoden

device.bulk_transfer()

Voert een directe bulk- of interrupt-overdracht uit naar een specifiek USB-eindpunt. In tegenstelling tot device.write() en device.read() die het eindpunt gebruiken dat is geselecteerd door device.set_endpoint(), kunt u hiermee elk eindpunt targeten op adres.

• Eindpuntadressen eindigend op 0x80 of hoger zijn IN (apparaat → host, lezen).
• Eindpuntadressen onder 0x80 zijn OUT (host → apparaat, schrijven).

Parameter	Type	Beschrijving	Voorbeeld
Endpoint	Hex	USB-eindpuntadres	0x81
DataArray	1D-array	Te verzenden gegevens (OUT), of lege array (IN)	[0x01, 0x02]
Length	Int	Overdrachtsgrootte in bytes	64
Timeout	Int	Milliseconden voordat opgegeven wordt	100

Retour	Type	Beschrijving
DataArray	1D-array	Ontvangen bytes (IN-overdrachten), of leeg

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

Laagniveau USB-beheersoverdracht. Gebruikt voor authenticatie-handshakes, leveranciersspecifieke protocollen en gevallen waarin HID-methoden niet voldoende zijn. Dit is een beheersoverdracht, geen bulk-overdracht.

Parameter	Type	Beschrijving	Voorbeeld
RequestType	Hex	USB-aanvraagtype bitmap (richting, type, ontvanger)	0xA1
Request	Hex	Aanvraagcode (apparaatspecifiek)	0x01
Value	Hex	Waardeveld	0x0100
Index	Int	Interface- of eindpuntindex	0x00
DataArray	1D-array	Te verzenden gegevens (host-naar-apparaat), of leeg	[]
Length	Int	Verwachte responslengte (apparaat-naar-host)	192
Timeout	Int	Milliseconden voordat opgegeven wordt	1000

Retour	Type	Beschrijving
DataArray	1D-array	Ontvangen bytes (apparaat-naar-host overdrachten)

Veelgebruikte RequestType-waarden:

Waarde	Richting	Type	Ontvanger	Gebruiksscenario
0x21	Host → Apparaat	Klasse	Interface	HID SET_REPORT
0xA1	Apparaat → Host	Klasse	Interface	HID GET_REPORT
0x80	Apparaat → Host	Standaard	Apparaat	Descriptor-leesbewerkingen
0x00	Host → Apparaat	Standaard	Apparaat	Standaardopdrachten

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

---

Seriële communicatie

Voor seriële/COM-poortapparaten importeert u de seriële module en stelt u het Type() van uw plugin in op "serial".

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

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

Verbindingsopties

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

Seriële methoden

Methode	Beschrijving	Retourneert
serial.connect(options?)	Open de seriële poort	bool
serial.disconnect()	Sluit de seriële poort	void
serial.isConnected()	Controleer verbindingsstatus	bool
serial.write(data)	Gegevens verzenden	geschreven bytes
serial.read(maxBytes?, timeoutMs?)	Beschikbare bytes lezen (standaard: alles, 1000ms timeout)	byte-array
serial.readAll()	Alle beschikbare bytes onmiddellijk lezen	byte-array
serial.availablePorts()	Beschikbare COM-poorten weergeven	array
serial.getPortName()	Huidige poortnaam	string
serial.getBaudRate()	Huidige baudrate	getal
serial.getDeviceInfo()	Poortinfo met VID, PID, enz.	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();
}

---

Netwerkcommunicatie (TCP / UDP)

Voor netwerk-verbonden apparaten importeert u de TCP- of UDP-module en stelt u Type() in op "network". Beide modules gebruiken een event-gebaseerd callback-model.

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

TCP-methoden:

Methode	Beschrijving
tcp.createSocket()	Maak een nieuwe TCP-socket aan
socket.connect(address, port)	Verbinding maken met een host
socket.send(data)	Tekenreeks of byte-array verzenden
socket.bind(port)	Binden aan een lokale poort
socket.close()	Socket sluiten
socket.on(event, callback)	Een event-handler registreren

TCP-events: "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();
}

UDP-methoden:

Methode	Beschrijving
udp.createSocket()	Maak een nieuwe UDP-socket aan
socket.connect(address, port)	Standaard verzendbestemming instellen
socket.send(data)	Verzenden naar verbonden adres
socket.write(data, address, port)	Verzenden naar een specifiek adres zonder eerst connect() aan te roepen
socket.bind(port)	Binden aan een lokale poort voor ontvangst
socket.close()	Socket sluiten
socket.on(event, callback)	Een event-handler registreren

UDP-events: "connected", "disconnected", "message", "error"

---

DTLS (Versleutelde UDP)

Voor apparaten waarvoor versleutelde communicatie vereist is (bijv. Philips Hue), gebruikt u de dtls-functie. Het biedt DTLS-versleutelde UDP met behulp van een 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();
}

DTLS-methoden:

Methode	Beschrijving
dtls.createConnection(host, port, identity, key)	Open een versleutelde verbinding met een PSK
dtls.send(data, endianness?)	Versleutelde gegevens verzenden (0 = little-endian, 1 = big-endian)
dtls.hasEncryptedConnection()	Retourneert true als de verbinding tot stand is gebracht
dtls.CloseConnection()	Verbinding sluiten
dtls.onConnectionEstablished(cb)	Callback wanneer verbinding slaagt
dtls.onConnectionClosed(cb)	Callback wanneer verbinding sluit
dtls.onConnectionError(cb)	Callback bij fout