Avancerad kommunikation

Den här sidan täcker avancerade USB-kommunikationsmetoder, seriella portar och nätverkssockets. För grundläggande läsningar och skrivningar, se sidan Skrivningar och läsningar.

USB-transfereringstyper

Att förstå skillnaden mellan USB-transfereringstyper hjälper dig att välja rätt metod och felsöka oväntade fel.

Typ	Metod	Typisk storlek	Användningsfall
Interrupt	device.write() / device.read()	3–64 byte	RGB-data, små kommandon, tangentbords-/musinmatning
Bulk	device.write() / device.read()	64–1025 byte	LCD-bilder, firmware-uppdateringar, stora konfigurationsblock
Control	device.send_report() / device.get_report() / device.control_transfer()	32–192 byte	Autentisering, HID-funktionsrapporter, enhetskonfiguration

Samma device.write() och device.read()-funktioner används för både interrupt- och bulk-transfereringar — USB-drivrutinen bestämmer typen från slutpunkten och paketstorlek.

---

HID-rapportmetoder

device.input_report()

Skickar en HID GET_INPUT_REPORT-kontrolltransferering. Liknar device.get_report() men begär specifikt en inmatningsrapport snarare än en funktionsrapport. Använd detta när get_report() returnerar fel data eftersom enheten skiljer på rapport-typer för inmatning och funktion.

Parameter	Typ	Beskrivning	Exempel
DataArray	1D Array	Rapportförfrågningsdata	[0x01]
Length	Int	Förväntad rapportstorlek (byte)	64

Returnerar	Typ	Beskrivning
DataArray	1D Array	Bytes mottagna från enheten

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

---

Raw USB-metoder

device.bulk_transfer()

Utför en direkt bulk- eller interrupt-transferering till en specifik USB-slutpunkt. Till skillnad från device.write() och device.read() som använder slutpunkten vald av device.set_endpoint(), låter det här dig rikta dig mot vilken slutpunkt som helst via adress.

• Slutpunkter med adresser som slutar på 0x80 eller högre är IN-riktning (enhet → värd, läsning).
• Slutpunktsadresser under 0x80 är OUT-riktning (värd → enhet, skrivning).

Parameter	Typ	Beskrivning	Exempel
Endpoint	Hex	USB-slutpunktens adress	0x81
DataArray	1D Array	Data att skicka (OUT) eller tom array (IN)	[0x01, 0x02]
Length	Int	Transfereringsstorlek (byte)	64
Timeout	Int	Millisekunder innan avbrott	100

Returnerar	Typ	Beskrivning
DataArray	1D Array	Mottagna bytes (IN-transfereringar) eller tom

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

// Läs från slutpunkt 0x81
var response = device.bulk_transfer(0x81, [], 64, 100);

// Stor bulk-skrivning (t.ex. LCD-bilddata)
device.bulk_transfer(0x02, imageData, 1024, 500);

---

device.control_transfer()

Lågnivå USB-kontrolltransferering. Används för autentiseringshandskakning, tillverkarspecifika protokoll och situationer där HID-metoder inte räcker. Det här är en kontrolltransferering, inte en bulk-transferering.

Parameter	Typ	Beskrivning	Exempel
RequestType	Hex	USB-förfrågningstyp-bitmask (riktning, typ, mottagare)	0xA1
Request	Hex	Förfrågningskod (enhetsspecifik)	0x01
Value	Hex	Värdefält	0x0100
Index	Int	Gränssnitts- eller slutpunktsindex	0x00
DataArray	1D Array	Data att skicka (värd till enhet) eller tom	[]
Length	Int	Förväntad svarslängd (enhet till värd)	192
Timeout	Int	Millisekunder innan avbrott	1000

Returnerar	Typ	Beskrivning
DataArray	1D Array	Mottagna bytes (enhet-till-värd-transfereringar)

Vanliga RequestType-värden:

Värde	Riktning	Typ	Mottagare	Användningsfall
0x21	Värd → Enhet	Klass	Gränssnitt	HID SET_REPORT
0xA1	Enhet → Värd	Klass	Gränssnitt	HID GET_REPORT
0x80	Enhet → Värd	Standard	Enhet	Deskriptorläsningar
0x00	Värd → Enhet	Standard	Enhet	Standardkommandon

// Läs autentiseringstoken (enhet → värd, klass, gränssnitt)
var token = device.control_transfer(
    0xA1,    // Enhet till värd, klass, gränssnitt
    0x01,    // GET_REPORT
    0x0100,  // Rapporttyp (funktion) + rapport-ID
    0x00,    // Gränssnitt 0
    [],      // Ingen utgående data
    192,     // 192 bytes förväntade
    1000     // 1 sekunders timeout
);

// Skicka funktionsrapport (värd → enhet)
device.control_transfer(0x21, 0x09, 0x0300, 0, [0x03, 0x08, 0x32], 0, 500);

---

Seriekommunikation

För seriella/COM-portentheter, importera seriemodulen och ange "serial" i pluginets Type()-funktion.

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

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

Anslutningsalternativ

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

Seriemetoder

Metod	Beskrivning	Returnerar
serial.connect(options?)	Öppna serieporten	bool
serial.disconnect()	Stäng serieporten	void
serial.isConnected()	Kontrollera anslutningsstatus	bool
serial.write(data)	Skicka data	skrivna bytes
serial.read(maxBytes?, timeoutMs?)	Läs tillgängliga bytes (standard: alla, 1000ms timeout)	byte-array
serial.readAll()	Läs alla tillgängliga bytes omedelbart	byte-array
serial.availablePorts()	Lista tillgängliga COM-portar	array
serial.getPortName()	Aktuellt portnamn	string
serial.getBaudRate()	Aktuell baudhastighet	number
serial.getDeviceInfo()	Portinfo med VID, PID osv.	objekt

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

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

export function Initialize() {
    if (!serial.connect()) {
        device.log("Kunde inte ansluta till serieporten");
        return;
    }
    device.log(`Ansluten på ${serial.getPortName()} vid ${serial.getBaudRate()} baud`);
}

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

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

---

Nätverkskommunikation (TCP / UDP)

För nätverksanslutna enheter, importera TCP- eller UDP-modulen och ange "network" i Type()-funktionen. Båda modulerna använder en händelsebaserad callback-modell.

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

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

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

Metod	Beskrivning
tcp.createSocket()	Skapa ny TCP-socket
socket.connect(address, port)	Anslut till en värd
socket.send(data)	Skicka sträng eller byte-array
socket.bind(port)	Bind till lokal port
socket.close()	Stäng socketen
socket.on(event, callback)	Registrera händelsehanterare

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

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

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

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

UDP-metoder:

Metod	Beskrivning
udp.createSocket()	Skapa ny UDP-socket
socket.connect(address, port)	Ange standardsändningsmål
socket.send(data)	Skicka till ansluten adress
socket.write(data, address, port)	Skicka till specifik adress utan att anropa connect() först
socket.bind(port)	Bind till lokal port för mottagning
socket.close()	Stäng socketen
socket.on(event, callback)	Registrera händelsehanterare

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

---

DTLS (krypterad UDP)

För enheter som kräver krypterad kommunikation (t.ex. Philips Hue), använd dtls-funktionen. Det ger DTLS-krypterad UDP med hjälp av en fördelad nyckel (PSK).

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

    dtls.onConnectionEstablished(() => { device.log("DTLS ansluten"); });
    dtls.onConnectionClosed(() => { device.log("DTLS stängd"); });
    dtls.onConnectionError(() => { device.log("DTLS-fel"); });

    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:

Metod	Beskrivning
dtls.createConnection(host, port, identity, key)	Öppna krypterad anslutning med PSK
dtls.send(data, endianness?)	Skicka krypterad data (0 = little-endian, 1 = big-endian)
dtls.hasEncryptedConnection()	Returnerar true om anslutning är upprättad
dtls.CloseConnection()	Stäng anslutningen
dtls.onConnectionEstablished(cb)	Callback när anslutning lyckades
dtls.onConnectionClosed(cb)	Callback när anslutning stängdes
dtls.onConnectionError(cb)	Callback vid fel