Guide d’implémentation du rétro-éclairage clavier

Ce document détaille l’implémentation du protocole permettant d’intégrer le contrôle de rétro-éclairage des périphériques clavier qui se connectent à un hôte compatible Windows 11. Cela n’inclut pas d’aide sur les contraintes mécaniques, les contraintes électriques ou la sélection des composants pour le matériel de l’appareil clavier.

Ce guide couvre uniquement les rétrolights globaux simples, où un seul niveau de luminosité s’applique à l’ensemble du clavier. Pour les claviers avec éclairage RVB par zone ou par touche, reportez-vous à l’éclairage dynamique à la place.

La prise en charge de l'intégration du rétroéclairage du clavier est disponible dans Windows 11, version 25H2, build 26200.7922 ou version ultérieure.

Implémentation du protocole backlight clavier

Une bonne compréhension du protocole HID est nécessaire pour pouvoir comprendre les informations présentées ici. Pour plus d’informations sur le protocole HID, consultez les ressources suivantes :

• Définition de classe d’appareil pour les appareils d’interface humaine (HID)
• Tables d’utilisation HID

Conseils sur le rétro-éclairage du clavier

Collection HID requise

Les fonctionnalités liées au rétroéclairage du clavier doivent être incluses dans une collection HID Consumer Keyboard Backlight (Page 0xC, Utilisation 0x7).

Boutons d’entrée

Le tableau suivant définit les touches d'entrée prises en charge par l’hôte pour les contrôles de rétroéclairage du clavier. Ces boutons ne doivent pas appliquer directement les mises à jour de luminosité sur l’appareil, mais doivent au lieu de différer les opérations de contrôle de luminosité à l’hôte. Dans de nombreux cas, l'hôte réagit rapidement à un bouton d'entrée avec un rapport de niveau défini, éventuellement ajusté en fonction de l'algorithme de luminosité de l'hôte. L’appareil ne doit appliquer aucune modification de luminosité temporaire en attendant cette réponse.

Les boutons d’entrée sont appliqués par appareil et ne s’appliquent à aucun appareil en plus de celui qui émet le rapport.

Si l’appareil est connecté à un hôte qui ne prend pas en charge le contrôle du rétroéclairage du clavier, indiqué par l’absence d'un rapport de sortie Set Level au démarrage ou au moment de la connexion, l’appareil peut revenir au contrôle de luminosité local direct pour ses boutons d’entrée.

Utilisations facultatives

Nom de l’état	Description	Page	ID
Incrément de luminosité	Demande à l’hôte d’augmenter la luminosité du rétro-éclairage par une étape logique. L’hôte détermine la taille d’étape, qui peut varier en fonction de la plage logique et de l’algorithme de luminosité active. Il est fortement recommandé que les appareils prenant en charge Brightness Increment prennent également en charge la décrémentation de luminosité.	0x0C	0x0079
Diminution de luminosité	Demande à l’hôte de réduire la luminosité du rétro-éclairage par une étape logique. L’hôte détermine la taille d’étape, qui peut varier en fonction de la plage logique et de l’algorithme de luminosité active. Il est fortement recommandé que les appareils prenant en charge la décrémentation de luminosité doivent également prendre en charge l’incrément de luminosité.	0x0C	0x007A
Contrôle activé/désactivé (OOC)	Demande à l’hôte d’activer ou désactiver le rétro-éclairage du clavier. Si vous activez le rétro-éclairage, l’hôte détermine une valeur de luminosité différente de zéro appropriée à envoyer à l’appareil. La désactivation de l’éclairage arrière implique une demande pour que l’hôte définisse la lumière arrière sur une luminosité nulle.	0x0C	0x007C
Automatique	Demande à l’hôte d’activer ou de désactiver l’ajustement automatique de la luminosité.	0x0C	0x007F
Définir le minimum	Demande à l’hôte de définir le rétro-éclairage du clavier sur son niveau de luminosité logique minimal non nul (généralement 1 nit). Cela représente la luminosité minimale prise en charge par l’appareil sans désactiver entièrement la lumière arrière.	0x0C	0x007D
Définir le nombre maximal	Demande à l’hôte de définir le rétro-éclairage du clavier sur son niveau de luminosité maximal logique.	0x0C	0x007E
Niveau suivant	Demande à l’hôte de régler la luminosité du rétroéclairage du clavier sur le niveau de luminosité suivant le plus élevé, avec retour au niveau le plus bas si le niveau de luminosité actuel atteint ou dépasse le niveau le plus élevé. Si le rapport de fonctionnalité Suggestions de niveau n’est pas implémenté, ce bouton est ignoré.	0x0C	0x0515
Niveau précédent	Demande à l’hôte de définir la luminosité du rétroéclairage du clavier sur le niveau de luminosité inférieur suivant, avec une réinitialisation au niveau le plus élevé si le niveau de luminosité actuel est inférieur ou égal à la suggestion de niveau le plus bas. Si la fonctionnalité de rapport des suggestions de niveau n’est pas implémentée, ce bouton est ignoré.	0x0C	0x0516

Définir le rapport de sortie de niveau

L’hôte envoie ce rapport pour définir ou modifier le niveau de luminosité du rétro-éclairage sur l’appareil. L’appareil peut détecter un hôte avec rétro-éclairage clavier en recevant ce rapport au démarrage du système ou lors de la connexion à l’hôte.

Le rapport de sortie Set Level doit définir une plage logique de valeurs de niveau de luminosité sur une échelle linéaire, avec son unité HID indiquée en nits. L’hôte utilise cette plage logique pour déterminer les niveaux de luminosité possibles pris en charge par l’appareil ; il ne nécessite pas que l’appareil soit étalonné pour émettre des valeurs de luminance exactes. Toutes les autres commandes de rétroéclairage du clavier et les opérations de l'hôte se réfèrent à cette plage logique.

Si le minimum logique est égal ou supérieur à la valeur maximale logique, l’appareil est considéré comme non conforme et n’est pas ouvert pour le contrôle de rétro-éclairage par l’hôte.

Une valeur de niveau défini de 0 indique à l’appareil de désactiver le feu arrière. Il est fortement recommandé que l’appareil utilise un minimum logique de 0 (aucune luminosité) pour ce rapport.

Utilisations obligatoires

Nom de l’état	Description	Page	ID
Définir le niveau	Indique à l’appareil de définir la luminosité du rétro-éclairage du clavier sur la valeur de nits logique spécifiée.	0x0C	0x007B

Rapport des niveaux de rétro-éclairage clavier suggérés

Ce rapport est facultatif. L’appareil peut choisir de prendre en charge une série d’au moins deux présélections de luminosité qu’il souhaite parcourir lorsque l’utilisateur appuie sur les boutons Niveau suivant ou Niveau précédent. L’hôte interroge ces présélections au démarrage du système ou lorsque l’appareil se connecte ou se reconnecte à l’hôte. Les présélections doivent se trouver dans l'intervalle logique spécifié dans le rapport de sortie du niveau défini. Une valeur de suggestion de 0 est valide et indique l’état de rétro-éclairage sous forme de présélection.

Le rapport de fonctionnalité des Suggestions de niveau est ignoré si l’appareil n’implémente ni le bouton d’entrée du niveau suivant ni celui du niveau précédent.

Utilisations facultatives

Nom de l’état	Description	Page	ID
Suggestion de niveau du rétroéclairage du clavier	Indique une présélection de niveau de luminosité suggérée qui doit être prise en compte lorsque l’hôte gère les boutons d’entrée niveau suivant ou niveau précédent.	0x07	0x0517

Rapport de fonctionnalité de réglage du niveau de rétroéclairage du clavier

Ce rapport est facultatif. L’appareil peut choisir d’implémenter ce rapport pour signaler à l’hôte un niveau de luminosité initial suggéré au démarrage ou au moment de la connexion, par exemple si le rétro-éclairage a été ajusté par l’utilisateur avant le démarrage système ou l’attachement de l’appareil. L’hôte interroge ce rapport au démarrage du système ou lorsque l’appareil se connecte ou se reconnecte à l’hôte, en choisissant éventuellement de remplacer ce niveau suggéré par sa propre valeur. Une valeur suggérée de 0 est valide et indique que le feu arrière a été désactivé. Si la valeur suggérée se trouve en dehors de la plage logique du rapport de sortie Set Level, le rapport est ignoré. Une valeur suggérée qui ne correspond à aucune entrée dans le rapport des fonctionnalités de Suggestions de niveau est valide, à condition qu’elle se trouve dans l'intervalle logique.

La plage logique de ce rapport doit se trouver dans la plage logique du rapport de sortie Set Level.

Utilisations facultatives

Nom de l’état	Description	Page	ID
Définir le niveau	Informe l’hôte du niveau de luminosité actuel du rétro-éclairage en tant que suggestion pour l’état initial de l’appareil dans ses algorithmes de luminosité.	0x0C	0x007B

Comportement du rétroéclairage du clavier

Grisage en mode Économiseur d’énergie

Windows prend en charge l'atténuation automatique du rétroéclairage du clavier lorsque le mode économie d'énergie est activé. Sur les appareils compatibles, cette fonctionnalité peut être activée dans Paramètres>System>Power &battery>Energy saver>Luminosité inférieure du clavier lors de l’utilisation de l’économiseur d’énergie ou au raccourci suivant : Power &battery.

Personnalisation

Cette fonctionnalité peut être configurée dans le Registre, comme indiqué dans le tableau ci-dessous. Par défaut, la fonctionnalité applique un multiplicateur de 70% à la luminosité du rétro-éclairage du clavier lorsque l’économiseur d’énergie est activé.

Clé du Registre	Name	Type	Unités
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Lighting\Backlight	Rétroéclairage économiseur d'énergie activé	REG_DWORD	Boolean (1 ou 0)
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Lighting\Backlight	Multiplicateur d'économie d'énergie du rétroéclairage	REG_DWORD	Pourcentage (0-100)

La fonctionnalité peut également être configurée à l’aide de Windows Installation sans assistance ou de l'approvisionnement en temps d'exécution.

Luminosité automatique du rétroéclairage du clavier

Dans les appareils tels que les ordinateurs portables qui contiennent à la fois un rétro-éclairage clavier et un capteur de lumière Ambient, Windows prend en charge l’ajustement automatique de la luminosité du rétro-éclairage du clavier. Cette fonctionnalité est également prise en charge pour les claviers externes lorsqu’ils sont attachés à des appareils avec des capteurs de lumière ambiante.

La luminosité automatique du clavier est distincte de la luminosité adaptative pour les affichages, mais son implémentation est conceptuellement similaire.

Sur les appareils compatibles, cette fonctionnalité peut être activée dans Paramètres>Bluetooth et appareils>Clavier>Rétroéclairage>Changer la luminosité du clavier automatiquement lorsque l’éclairage change ou au raccourci suivant : Clavier.

Courbe de réponse à la lumière ambiante compartimentée

Le rétroéclairage du clavier à luminosité automatique emprunte le concept d'une courbe de réponse à la lumière ambiante (ALR) compartimentée, comme décrit dans l'adaptabilité de la luminosité.

Les mappages de valeurs par défaut entre les niveaux de lux et les pourcentages de luminosité du rétroéclairage du clavier sont indiqués dans le tableau ci-dessous. Le pourcentage du compartiment fait référence à une proportion de la valeur maximale logique du rapport de sortie de Valeur définie et sera utilisé lorsque le niveau de lumière ambiante se trouve dans la plage du compartiment.

Tous les compartiments de la courbe ALR doivent être contigus ou se chevauchent : les écarts entre les compartiments ne sont pas autorisés. Chaque seau doit avoir une valeur de lux minimale strictement inférieure à sa valeur maximale. Si la lecture de la lumière ambiante tombe en dessous du lux minimal du compartiment le plus bas, le pourcentage de compartiment le plus bas est utilisé. S’il dépasse le nombre maximal de lux du compartiment le plus élevé, le pourcentage de compartiment le plus élevé est utilisé.

Seau	Min Lux	Max Lux	Pourcentage
1	0	6	35
2	5	14	52
3	12	32	70
4	30	45	88
5	40	100	100
6	95	110	88
7	105	160	70
8	155	205	52
9	200	300	0

Lorsque plusieurs claviers rétrolittés sont attachés, la même courbe ALR est utilisée pour tous les claviers, avec les pourcentages résultants appliqués à chaque appareil en fonction de la plage de luminosité logique de cet appareil.

Personnalisation

Les paramètres d’activation de l’autobrightness et de la courbe ALR peuvent être configurés dans le Registre, comme indiqué dans le tableau ci-dessous. Ils peuvent également être configurés à l’aide de Configuration automatique de Windows ou du Provisionnement du runtime.

Clé du Registre	Name	Type	Unités
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Lighting\Backlight	ActiverSeuilRétroéclairageLuminositéAutomatique	REG_DWORD	Boolean (1 ou 0)
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Lighting\Backlight	BacklightAutobrightnessBucketMapping	REG_SZ	Chaîne composée d’un ou plusieurs triples délimités par des virgules sous la forme <minlux>:<maxlux>:<percentage>. Chaque triple représente un seau dans la courbe ALR. Si la courbe ALR personnalisée a des lacunes, a zéro entrée ou contient n’importe quel compartiment où minlux ≥ maxlux, la courbe ALR par défaut sera utilisée à la place.

Désactivation manuelle de la luminosité automatique

Si un bouton d’entrée est enfoncé en même temps que le rétroéclairage automatique du clavier est activé, une dérogation manuelle temporaire de l’algorithme d’autobrightness est initiée. La dérogation génère un compartiment unique et supplémentaire appliqué au-dessus de la courbe compartimentée, provenant de la lecture de lumière ambiante actuelle, avec des valeurs minimales et maximales générées à une distance donnée au-dessus ou en dessous de la lecture actuelle en fonction d’un pourcentage de cette lecture.

Les mappages de valeurs par défaut entre les compartiments lux et les constantes de plage de remplacement manuelles sont indiqués dans le tableau ci-dessous. Les entrées de la table de recherche doivent avoir des plages de lux contiguës qui ne se chevauchent pas.

Seau	Min Lux	Max Lux	Facteur de limite inférieure de dépassement	Limite supérieure du facteur de dépassement
1	0	20	1,00	1,00
2	20	40	0.70	0.60
3	40	150	0.60	0.60
4	150	600	0,50	0,50
5	600	1000	0.40	0.40
6	1000	4000	0.30	0.25
7	4000	10000	0.20	0.20
8	10000	30000	0.15	0.10
9	30000	100000	0.10	0.10

Pour obtenir un exemple de calcul de la plage de remplacement, envisagez d’appuyer sur un bouton d’entrée lorsque la dernière lecture de la lumière ambiante est de 120 lux. L’entrée dans la table de correspondance correspondante est le compartiment 3, car 120 lux se situe entre 40 et 150 lux. Le bucket sera créé avec un seuil inférieur de 60% de la lecture actuelle. Avec R=120 et A=0,6, le seuil inférieur est 120(1 - 0,6) = 48 lux. Le seuil supérieur est également de 60% au-dessus de la lecture actuelle. Là encore, avec R=120 et B=0,6, le seuil supérieur est 120(1 + 0,6) = 192 lux. Par conséquent, le remplacement manuel s’applique alors que le niveau de lumière ambiante reste dans la plage de [48, 192].

Une fois activé, le pourcentage de luminosité du seau de dérogation manuelle est utilisé jusqu’à ce que :

• la lecture de la lumière ambiante franchit les seuils de la plage de dérogation, à ce moment la dérogation est annulée, la plage de dérogation est ignorée et le contrôle de l’autobrightness reprend à l’aide de la courbe ALR segmentée, ou
• Une autre pression sur le bouton d'entrée est reçue de l'appareil, ce qui amène l'hôte à ajuster le pourcentage de luminosité et à recalculer la plage de remplacement manuel en fonction de la dernière mesure de la lumière ambiante.

Personnalisation

La table de recherche de remplacement manuelle peut être configurée dans le Registre, comme indiqué dans le tableau ci-dessous. Il peut également être configuré à l’aide de Configuration automatique de Windows ou du provisionnement en temps d'exécution.

Clé du Registre	Name	Type	Unités
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Lighting\Backlight	RétroéclairageLuminositéAutomatiqueDépassementManuelLut	REG_SZ	Chaîne composée d'un ou plusieurs 4-tuples délimités par des virgules au format <minlux>:<maxlux>:<lowerboundfactor>:<upperboundfactor>. Chaque 4-tuple représente une entrée dans la table de correspondance. Si la table de choix personnalisée a des lacunes, a zéro entrée, a des compartiments qui se chevauchent ou contient un compartiment où minlux ≥ maxlux, la table de recherche par défaut sera utilisée à la place.

Exemples de descripteurs de rapport HID

Exemple de descripteur de rétroéclairage du clavier

Le descripteur suivant prend en charge toutes les utilisations obligatoires et facultatives. Il déclare la prise en charge de huit touches d'entrée de clavier rétro-éclairé.

Toutes les plages logiques pour le rapport de fonctionnalité "Définir le Niveau" et les rapports de fonctionnalité "Suggestions de Niveau" doivent se trouver dans la plage logique du rapport de sortie obligatoire de Définir le Niveau.

0x05, 0x0C,                      // UsagePage(Consumer[0x000C])
0x09, 0x07,                      // UsageId(Keyboard Backlight[0x0007])
0xA1, 0x01,                      // Collection(Application)
0x85, 0x01,                      //     ReportId(1)
0x09, 0x79,                      //     UsageId(Keyboard Brightness Increment[0x0079])
0x09, 0x7A,                      //     UsageId(Keyboard Brightness Decrement[0x007A])
0x09, 0x7C,                      //     UsageId(Keyboard Backlight OOC[0x007C])
0x09, 0x7D,                      //     UsageId(Keyboard Backlight Set Minimum[0x007D])
0x09, 0x7E,                      //     UsageId(Keyboard Backlight Set Maximum[0x007E])
0x09, 0x7F,                      //     UsageId(Keyboard Backlight Auto[0x007F])
0x0A, 0x15, 0x05,                //     UsageId(Keyboard Brightness Next[0x0515])
0x0A, 0x16, 0x05,                //     UsageId(Keyboard Brightness Previous[0x0516])
0x15, 0x00,                      //     LogicalMinimum(0)
0x25, 0x01,                      //     LogicalMaximum(1)
0x95, 0x08,                      //     ReportCount(8)
0x75, 0x01,                      //     ReportSize(1)
0x81, 0x06,                      //     Input(Data, Variable, Relative, NoWrap, Linear, PreferredState, NoNullPosition, BitField)
0x0A, 0x17, 0x05,                //     UsageId(Keyboard Backlight Level Suggestion[0x0517])
0x67, 0xE1, 0x00, 0x00, 0x01,    //     Unit('nits', SiLinear, Centimeter:-2, Candela:1)
0x55, 0x04,                      //     UnitExponent(10,000)
0x26, 0xFF, 0x00,                //     LogicalMaximum(255)
0x95, 0x04,                      //     ReportCount(4)
0x75, 0x08,                      //     ReportSize(8)
0xB1, 0x03,                      //     Feature(Constant, Variable, Absolute, NoWrap, Linear, PreferredState, NoNullPosition, NonVolatile, BitField)
0x85, 0x02,                      //     ReportId(2)
0x09, 0x7B,                      //     UsageId(Keyboard Backlight Set Level[0x007B])
0x95, 0x01,                      //     ReportCount(1)
0xB1, 0x03,                      //     Feature(Constant, Variable, Absolute, NoWrap, Linear, PreferredState, NoNullPosition, NonVolatile, BitField)
0x85, 0x01,                      //     ReportId(1)
0x09, 0x7B,                      //     UsageId(Keyboard Backlight Set Level[0x007B])
0x91, 0x02,                      //     Output(Data, Variable, Absolute, NoWrap, Linear, PreferredState, NoNullPosition, NonVolatile, BitField)
0xC0,                            // EndCollection()

Le descripteur ci-dessus a été généré via le fichier Waratah suivant :

[[unit]]
name = 'meter'
centimeter = [100.0, 1.0]

[[unit]]
name = 'nits'
candela = [1.0, 1.0]
meter = [1.0, -2.0]

[[usagePage]]
name = 'Consumer'

    [[usagePage.usage]]
    id = 0x07
    name = 'Keyboard Backlight'
    types = ['CA']

    [[usagePage.usage]]
    id = 0x515
    name = 'Keyboard Brightness Next'
    types = ['OSC']

    [[usagePage.usage]]
    id = 0x516
    name = 'Keyboard Brightness Previous'
    types = ['OSC']

    [[usagePage.usage]]
    id = 0x517
    name = 'Keyboard Backlight Level Suggestion'
    types = ['SV']

[[applicationCollection]]
usage = ['Consumer', 'Keyboard Backlight']

    [[applicationCollection.inputReport]]

        [[applicationCollection.inputReport.variableItem]]
        usage = ['Consumer', 'Keyboard Brightness Increment']
        logicalValueRange = [0, 1]
        reportFlags = ['Relative', 'PreferredState']

        [[applicationCollection.inputReport.variableItem]]
        usage = ['Consumer', 'Keyboard Brightness Decrement']
        logicalValueRange = [0, 1]
        reportFlags = ['Relative', 'PreferredState']

        [[applicationCollection.inputReport.variableItem]]
        usage = ['Consumer', 'Keyboard Backlight OOC']
        logicalValueRange = [0, 1]
        reportFlags = ['Relative', 'PreferredState']

        [[applicationCollection.inputReport.variableItem]]
        usage = ['Consumer', 'Keyboard Backlight Set Minimum']
        logicalValueRange = [0, 1]
        reportFlags = ['Relative', 'PreferredState']

        [[applicationCollection.inputReport.variableItem]]
        usage = ['Consumer', 'Keyboard Backlight Set Maximum']
        logicalValueRange = [0, 1]
        reportFlags = ['Relative', 'PreferredState']

        [[applicationCollection.inputReport.variableItem]]
        usage = ['Consumer', 'Keyboard Backlight Auto']
        logicalValueRange = [0, 1]
        reportFlags = ['Relative', 'PreferredState']

        [[applicationCollection.inputReport.variableItem]]
        usage = ['Consumer', 'Keyboard Brightness Next']
        logicalValueRange = [0, 1]
        reportFlags = ['Relative', 'PreferredState']

        [[applicationCollection.inputReport.variableItem]]
        usage = ['Consumer', 'Keyboard Brightness Previous']
        logicalValueRange = [0, 1]
        reportFlags = ['Relative', 'PreferredState']

    # Keyboard provided brightness level suggestions for host.
    # Here, the device suggests 4 brightness levels, which the host is free to override as it sees fit.
    [[applicationCollection.featureReport]]

        [[applicationCollection.featureReport.variableItem]]
        usage = ['Consumer', 'Keyboard Backlight Level Suggestion']
        sizeInBits = 8
        logicalValueRange = 'maxUnsignedSizeRange'
        unit = 'nits'
        reportFlags = ['constant']
        count = 4

    # Keyboard reports its last used brightness level as a hint to the host during initialization.
    [[applicationCollection.featureReport]]

        [[applicationCollection.featureReport.variableItem]]
        usage = ['Consumer', 'Keyboard Backlight Set Level']
        sizeInBits = 8
        logicalValueRange = 'maxUnsignedSizeRange'
        unit = 'nits'
        reportFlags = ['constant']

    # Host control of the keyboard brightness level.
    # Device has been previously calibrated to understand what LED 'power level' corresponds to emitted nits.
    [[applicationCollection.outputReport]]

        [[applicationCollection.outputReport.variableItem]]
        usage = ['Consumer', 'Keyboard Backlight Set Level']
        sizeInBits = 8
        logicalValueRange = 'maxUnsignedSizeRange'
        unit = 'nits'

Rubriques connexes

• Microsoft-Windows-Devices-Lights-Configuration | informations de référence sur l’installation sans assistance Windows
• Éclairage dynamique
• Capteurs de lumière ambiante
• Luminosité adaptative