Avanceret kommunikation

Denne side behandler avancerede USB-kommunikationsmetoder, serielle grænseflader og netværks-sockets. For grundlæggende læse- og skriveoperationer, se Skrivninger og læsninger.

USB-overførselstyper

Forståelse af forskellen mellem USB-overførselstyper hjælper dig med at vælge den rigtige metode og debugge uventede fejl.

Type	Metode	Typisk størrelse	Brugstilfælde
Interrupt	device.write() / device.read()	3–64 bytes	RGB-data, små kommandoer, tastatur-/museinput
Bulk	device.write() / device.read()	64–1025 bytes	LCD-billeder, firmware-opdateringer, store konfigurationsblokke
Control	device.send_report() / device.get_report() / device.control_transfer()	32–192 bytes	Autentificering, HID-feature-reports, enhedskonfiguration

De samme funktioner device.write() og device.read() bruges til interrupt- og bulk-transfers — USB-driveren bestemmer typen baseret på endepunktet og pakkestørrelsen.

---

HID-rapport-metoder

device.input_report()

Sender en HID-GET_INPUT_REPORT-control-transfer. Ligner device.get_report(), men anmoder eksplicit om en input-rapport i stedet for en feature-rapport. Brug dette, når get_report() returnerer forkerte data, fordi enheden adskiller sine input- og feature-rapport-typer.

Parameter	Type	Beskrivelse	Eksempel
DataArray	1D-Array	Rapport-anmodningsdata	[0x01]
Length	Int	Forventet rapport-størrelse i bytes	64

Returnering	Type	Beskrivelse
DataArray	1D-Array	Bytes modtaget fra enheden

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

---

Raw-USB-metoder

device.bulk_transfer()

Udfører en direkte bulk- eller interrupt-transfer til et bestemt USB-endepunkt. I modsætning til device.write() og device.read(), der bruger det endepunkt valgt af device.set_endpoint(), kan du med dette adressere ethvert endepunkt via dets adresse.

• Endepunktadresser der slutter på 0x80 eller højere er IN (enhed → host, læsning).
• Endepunktadresser under 0x80 er OUT (host → enhed, skrivning).

Parameter	Type	Beskrivelse	Eksempel
Endpoint	Hex	USB-endepunktadresse	0x81
DataArray	1D-Array	Data der skal sendes (OUT) eller tomt array (IN)	[0x01, 0x02]
Length	Int	Overførselsstørrelse i bytes	64
Timeout	Int	Millisekunder til afbrydelse	100

Returnering	Type	Beskrivelse
DataArray	1D-Array	Modtagne bytes (IN-transfers), eller tomt

// Skriv til endepunkt 0x01
device.bulk_transfer(0x01, [0x00, 0x01, 0x02], 3, 100);

// Læs fra endepunkt 0x81
var response = device.bulk_transfer(0x81, [], 64, 100);

// Stor bulk-skrivning (f.eks. LCD-billeddata)
device.bulk_transfer(0x02, imageData, 1024, 500);

---

device.control_transfer()

Low-level USB-control-transfer. Bruges til autentificerings-handshakes, producentspecifikke protokoller og tilfælde, hvor HID-metoder ikke er tilstrækkelige. Dette er en control-transfer, ikke en bulk-transfer.

Parameter	Type	Beskrivelse	Eksempel
RequestType	Hex	USB-request-type-bitmap (retning, type, modtager)	0xA1
Request	Hex	Request-kode (enhedsspecifik)	0x01
Value	Hex	Value-felt	0x0100
Index	Int	Interface- eller endepunkt-indeks	0x00
DataArray	1D-Array	Data der skal sendes (host→enhed), eller tomt	[]
Length	Int	Forventet svarlængde (enhed→host)	192
Timeout	Int	Millisekunder til afbrydelse	1000

Returnering	Type	Beskrivelse
DataArray	1D-Array	Modtagne bytes (enhed→host-transfers)

Hyppige RequestType-værdier:

Værdi	Retning	Type	Modtager	Brugstilfælde
0x21	Host → Enhed	Class	Interface	HID SET_REPORT
0xA1	Enhed → Host	Class	Interface	HID GET_REPORT
0x80	Enhed → Host	Standard	Enhed	Deskriptor-læsninger
0x00	Host → Enhed	Standard	Enhed	Standardkommandoer

// Læs autentificerings-token (enhed → host, Class, Interface)
var token = device.control_transfer(
    0xA1,    // enhed→host, Class, Interface
    0x01,    // GET_REPORT
    0x0100,  // Rapport-type (Feature) + rapport-ID
    0x00,    // Interface 0
    [],      // Ingen udgående data
    192,     // Forvent 192 bytes tilbage
    1000     // 1 sekund timeout
);

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

---

Seriel kommunikation

Til serielle/COM-port-enheder importeres Serial-modulet og pluginets Type() sættes til "serial".

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

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

Forbindelsesindstillinger

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

Serielle metoder

Metode	Beskrivelse	Returnering
serial.connect(options?)	Åbn seriel port	bool
serial.disconnect()	Luk seriel port	void
serial.isConnected()	Kontrollér forbindelsesstatus	bool
serial.write(data)	Send data	Sendte bytes
serial.read(maxBytes?, timeoutMs?)	Læs tilgængelige bytes (standard: alle, 1000 ms timeout)	Byte-array
serial.readAll()	Læs alle tilgængelige bytes straks	Byte-array
serial.availablePorts()	List tilgængelige COM-porte	Array
serial.getPortName()	Aktuelt portnavn	string
serial.getBaudRate()	Aktuel baudrate	number
serial.getDeviceInfo()	Port-info med VID, PID osv.	object

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

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

export function Initialize() {
    if (!serial.connect()) {
        device.log("Forbindelse til seriel port mislykkedes");
        return;
    }
    device.log(`Forbundet på ${serial.getPortName()} med ${serial.getBaudRate()} baud`);
}

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

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

---

Netværkskommunikation (TCP / UDP)

Til netværksaktiverede enheder importeres TCP- eller UDP-modulet og Type() sættes til "network". Begge moduler bruger en hændelsesbaseret 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("Forbundet");
        socket.send([0x01, 0x02, 0x03]);
    });

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

    socket.on("error", (err) => {
        device.log(`Fejl: ${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-metoder:

Metode	Beskrivelse
tcp.createSocket()	Opret ny TCP-socket
socket.connect(address, port)	Opret forbindelse til en host
socket.send(data)	Send streng eller byte-array
socket.bind(port)	Bind til lokal port
socket.close()	Luk socket
socket.on(event, callback)	Registrér event-handler

TCP-hændelser: "connected", "disconnected", "message", "error"

---

UDP

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

let socket;

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

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

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

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

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

UDP-metoder:

Metode	Beskrivelse
udp.createSocket()	Opret ny UDP-socket
socket.connect(address, port)	Angiv standard sendemål
socket.send(data)	Send til forbundet adresse
socket.write(data, address, port)	Send til bestemt adresse uden forudgående connect()-kald
socket.bind(port)	Bind til lokal port til modtagelse
socket.close()	Luk socket
socket.on(event, callback)	Registrér event-handler

UDP-hændelser: "connected", "disconnected", "message", "error"

---

DTLS (Krypteret UDP)

Til enheder der kræver krypteret kommunikation (f.eks. Philips Hue), bruges dtls-feature’et. Det tilbyder DTLS-krypteret UDP med en Pre-Shared Key (PSK).

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

    dtls.onConnectionEstablished(() => { device.log("DTLS forbundet"); });
    dtls.onConnectionClosed(() => { device.log("DTLS lukket"); });
    dtls.onConnectionError(() => { device.log("DTLS fejl"); });

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

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

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

DTLS-metoder:

Metode	Beskrivelse
dtls.createConnection(host, port, identity, key)	Åbn krypteret forbindelse med PSK
dtls.send(data, endianness?)	Send krypterede data (0 = Little-Endian, 1 = Big-Endian)
dtls.hasEncryptedConnection()	Returnerer true hvis forbindelsen er etableret
dtls.CloseConnection()	Luk forbindelsen
dtls.onConnectionEstablished(cb)	Callback når forbindelsen er oprettet
dtls.onConnectionClosed(cb)	Callback når forbindelsen lukkes
dtls.onConnectionError(cb)	Callback ved fejl