Communication avancée

Cette page couvre les méthodes de communication USB avancées, les ports série et les sockets réseau. Pour les lectures et écritures de base, voir Écritures et lectures.

Types de transfert USB

Comprendre la différence entre les types de transfert USB vous aidera à choisir la bonne méthode et à déboguer les erreurs inattendues.

Type	Méthode	Taille typique	Cas d’usage
Interrupt	`device.write()` / `device.read()`	3–64 octets	Données RGB, petites commandes, entrée clavier/souris
Bulk	`device.write()` / `device.read()`	64–1025 octets	Images LCD, mises à jour firmware, grands blocs de configuration
Control	`device.send_report()` / `device.get_report()` / `device.control_transfer()`	32–192 octets	Authentification, rapports HID feature, configuration appareil

Les mêmes fonctions device.write() et device.read() sont utilisées pour les transferts interrupt et bulk — le pilote USB détermine le type d’après le point d’accès et la taille du paquet.

Méthodes de rapport HID

device.input_report()

Envoie un transfert de contrôle HID GET_INPUT_REPORT. Similaire à device.get_report() mais demande spécifiquement un rapport Input plutôt qu’un rapport Feature. Utilisez ceci quand get_report() retourne des données incorrectes parce que l’appareil sépare ses types de rapports Input et Feature.

Paramètre	Type	Description	Exemple
DataArray	Tableau 1D	Données de demande de rapport	[0x01]
Length	Int	Taille de rapport attendue en octets	64

Retour	Type	Description
DataArray	Tableau 1D	Octets reçus depuis l’appareil

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

Méthodes USB brutes

device.bulk_transfer()

Effectue un transfert bulk ou interrupt direct vers un point d’accès USB spécifique. Contrairement à device.write() et device.read() qui utilisent le point d’accès sélectionné par device.set_endpoint(), ceci vous permet de cibler n’importe quel point d’accès par son adresse.

Les adresses de point d’accès se terminant par 0x80 ou plus sont IN (appareil → hôte, lecture).
Les adresses de point d’accès inférieures à 0x80 sont OUT (hôte → appareil, écriture).

Paramètre	Type	Description	Exemple
Endpoint	Hex	Adresse du point d’accès USB	0x81
DataArray	Tableau 1D	Données à envoyer (OUT), ou tableau vide (IN)	[0x01, 0x02]
Length	Int	Taille du transfert en octets	64
Timeout	Int	Millisecondes avant abandon	100

Retour	Type	Description
DataArray	Tableau 1D	Octets reçus (transferts IN), ou vide

// Écrire vers le point d'accès 0x01
device.bulk_transfer(0x01, [0x00, 0x01, 0x02], 3, 100);

// Lire depuis le point d'accès 0x81
var response = device.bulk_transfer(0x81, [], 64, 100);

// Grande écriture bulk (ex. données d'image LCD)
device.bulk_transfer(0x02, imageData, 1024, 500);

device.control_transfer()

Transfert de contrôle USB de bas niveau. Utilisé pour les handshakes d’authentification, les protocoles spécifiques aux fabricants et les cas où les méthodes HID sont insuffisantes. C’est un transfert de contrôle, pas un transfert bulk.

Paramètre	Type	Description	Exemple
RequestType	Hex	Bitmap du type de requête USB (direction, type, destinataire)	0xA1
Request	Hex	Code de requête (spécifique à l’appareil)	0x01
Value	Hex	Champ valeur	0x0100
Index	Int	Index d’interface ou de point d’accès	0x00
DataArray	Tableau 1D	Données à envoyer (hôte→appareil), ou vide	[]
Length	Int	Longueur de réponse attendue (appareil→hôte)	192
Timeout	Int	Millisecondes avant abandon	1000

Retour	Type	Description
DataArray	Tableau 1D	Octets reçus (transferts appareil→hôte)

Valeurs RequestType courantes :

Valeur	Direction	Type	Destinataire	Cas d’usage
`0x21`	Hôte → Appareil	Class	Interface	HID SET_REPORT
`0xA1`	Appareil → Hôte	Class	Interface	HID GET_REPORT
`0x80`	Appareil → Hôte	Standard	Appareil	Lecture de descripteurs
`0x00`	Hôte → Appareil	Standard	Appareil	Commandes standard

// Lire le jeton d'authentification (appareil → hôte, class, interface)
var token = device.control_transfer(
    0xA1,    // Appareil→hôte, class, interface
    0x01,    // GET_REPORT
    0x0100,  // Type de rapport (Feature) + ID de rapport
    0x00,    // Interface 0
    [],      // Pas de données sortantes
    192,     // Attendre 192 octets en retour
    1000     // Timeout 1 seconde
);

// Envoyer un rapport feature (hôte → appareil)
device.control_transfer(0x21, 0x09, 0x0300, 0, [0x03, 0x08, 0x32], 0, 500);

Communication série

Pour les appareils série/COM port, importez le module série et définissez Type() de votre plugin sur "serial".

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

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

Options de connexion

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

Méthodes série

Méthode	Description	Retourne
`serial.connect(options?)`	Ouvrir le port série	`bool`
`serial.disconnect()`	Fermer le port série	void
`serial.isConnected()`	Vérifier l’état de la connexion	`bool`
`serial.write(data)`	Envoyer des données	octets écrits
`serial.read(maxBytes?, timeoutMs?)`	Lire les octets disponibles (par défaut : tous, timeout 1000 ms)	tableau d’octets
`serial.readAll()`	Lire immédiatement tous les octets disponibles	tableau d’octets
`serial.availablePorts()`	Lister les ports COM disponibles	tableau
`serial.getPortName()`	Nom du port actuel	string
`serial.getBaudRate()`	Débit en bauds actuel	number
`serial.getDeviceInfo()`	Infos du port avec VID, PID, etc.	object

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

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

export function Initialize() {
    if (!serial.connect()) {
        device.log("Échec de connexion au port série");
        return;
    }
    device.log(`Connecté sur ${serial.getPortName()} à ${serial.getBaudRate()} bauds`);
}

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

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

Communication réseau (TCP / UDP)

Pour les appareils connectés en réseau, importez le module TCP ou UDP et définissez Type() sur "network". Les deux modules utilisent un modèle de callback basé sur les événements.

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

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

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

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

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

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

Méthodes TCP :

Méthode	Description
`tcp.createSocket()`	Créer un nouveau socket TCP
`socket.connect(address, port)`	Se connecter à un hôte
`socket.send(data)`	Envoyer une chaîne ou un tableau d’octets
`socket.bind(port)`	Lier à un port local
`socket.close()`	Fermer le socket
`socket.on(event, callback)`	Enregistrer un gestionnaire d’événement

Événements 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(`Reçu : ${data}`);
    });

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

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

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

Méthodes UDP :

Méthode	Description
`udp.createSocket()`	Créer un nouveau socket UDP
`socket.connect(address, port)`	Définir la destination d’envoi par défaut
`socket.send(data)`	Envoyer à l’adresse connectée
`socket.write(data, address, port)`	Envoyer à une adresse spécifique sans appeler `connect()` au préalable
`socket.bind(port)`	Lier à un port local pour la réception
`socket.close()`	Fermer le socket
`socket.on(event, callback)`	Enregistrer un gestionnaire d’événement

Événements UDP : "connected", "disconnected", "message", "error"

DTLS (UDP chiffré)

Pour les appareils qui nécessitent une communication chiffrée (ex. Philips Hue), utilisez la fonctionnalité dtls. Elle fournit un UDP chiffré DTLS avec une clé pré-partagée (PSK).

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

    dtls.onConnectionEstablished(() => { device.log("DTLS connecté"); });
    dtls.onConnectionClosed(() => { device.log("DTLS fermé"); });
    dtls.onConnectionError(() => { device.log("Erreur DTLS"); });

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

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

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

Méthodes DTLS :

Méthode	Description
`dtls.createConnection(host, port, identity, key)`	Ouvrir une connexion chiffrée avec une PSK
`dtls.send(data, endianness?)`	Envoyer des données chiffrées (`0` = little-endian, `1` = big-endian)
`dtls.hasEncryptedConnection()`	Retourne `true` si la connexion est établie
`dtls.CloseConnection()`	Fermer la connexion
`dtls.onConnectionEstablished(cb)`	Callback quand la connexion réussit
`dtls.onConnectionClosed(cb)`	Callback quand la connexion se ferme
`dtls.onConnectionError(cb)`	Callback en cas d’erreur