Guía de implementación de retroiluminación de teclado

En este documento se detalla la implementación del protocolo para integrar el control de retroiluminación de los dispositivos de teclado que se conectan a un host de Windows 11 compatible. Esto no incluye instrucciones sobre restricciones mecánicas, restricciones eléctricas o selección de componentes para el hardware del dispositivo de teclado.

En esta guía solo se tratan las luces traseras globales sencillas del teclado, donde se aplica un solo nivel de brillo a todo el teclado. En el caso de los teclados con iluminación RGB con zona o por tecla, consulte Iluminación dinámica en su lugar.

La compatibilidad con la integración con retroiluminación de teclado está disponible en Windows 11, versión 25H2, compilación 26200.7922 o posterior.

Implementación del protocolo de retroiluminación de teclado

Se necesita una buena comprensión del protocolo HID para poder comprender la información que se presenta aquí. Consulte los siguientes recursos para obtener información sobre el protocolo HID:

Guía de retroiluminación de teclado

Colección HID requerida

La funcionalidad relacionada con la retroiluminación del teclado debe incluirse en una colección de retroiluminación del teclado del consumidor HID (Página 0xC, Uso 0x7).

Botones de entrada

En la tabla siguiente se definen los botones de entrada admitidos por el host para los controles de retroiluminación de teclado. Estos botones no deben aplicar directamente los ajustes de brillo en el dispositivo, sino que deben delegar las operaciones de control de brillo al sistema anfitrión. En muchos casos, el sistema responderá rápidamente a un botón de entrada con un informe de ajuste de nivel, opcionalmente ajustado según el algoritmo de brillo del sistema. El dispositivo no debe aplicar ningún cambio de brillo temporal mientras espera esa respuesta.

Los botones de entrada se aplican por dispositivo y no se aplican a ningún dispositivo además del que emite el informe.

Si el dispositivo está conectado a un host que no admite el control de retroiluminación del teclado, indicado por la ausencia de un informe de salida de nivel establecido en el inicio o momento de conexión, el dispositivo puede volver al control directo de brillo local para sus botones de entrada.

Usos opcionales
Nombre de informe Descripción Página ID
Incremento de brillo Solicita al host que aumente la luminosidad de la retroiluminación en un paso lógico. El host determina el tamaño del paso, que puede variar en función del intervalo lógico y del algoritmo de brillo activo. Se recomienda encarecidamente que los dispositivos que admitan el incremento de brillo también admitan el decremento de brillo. 0x0C 0x0079
Decremento de brillo Solicita al host que disminuya el brillo de la retroiluminación en un paso lógico. El host determina el tamaño del paso, que puede variar en función del intervalo lógico y del algoritmo de brillo activo. Se recomienda encarecidamente que los dispositivos que admitan el decremento de brillo también admitan el incremento de brillo. 0x0C 0x007A
Control de Encendido/Apagado (OOC) Solicita al host que active o desactive la luz de retroceso del teclado. Si activa la luz trasera, el host determinará un valor de brillo distinto de cero adecuado para enviar al dispositivo. La desactivación de la retroiluminación implica una solicitud para que el host establezca la retroiluminación en cero brillo. 0x0C 0x007C
Automático Solicita al host que habilite o deshabilite el ajuste automático de brillo. 0x0C 0x007F
Establecer mínimo Pide al host que establezca la retroiluminación del teclado en su nivel de brillo lógico mínimo distinto de cero (normalmente 1 nit). Esto representa el brillo mínimo admitido por el dispositivo sin desactivar completamente la luz trasera. 0x0C 0x007D
Establecer máximo Solicita al host que establezca la retroiluminación del teclado en su nivel máximo de brillo lógico. 0x0C 0x007E
Siguiente nivel Solicita al host que establezca el brillo de la luz de fondo del teclado en la siguiente sugerencia de nivel más brillante, con desbordamiento a la sugerencia de nivel más bajo si el nivel de brillo actual cumple o supera la sugerencia de nivel más alta. Si no se implementa el informe de características de sugerencias de nivel, se omite este botón. 0x0C 0x0515
Nivel anterior Solicita al anfitrión que establezca el brillo de la retroiluminación del teclado en el siguiente nivel sugerido más tenue, con desbordamiento inferior al nivel sugerido más alto si el nivel de brillo actual alcanza o está por debajo del nivel sugerido más bajo. Si no se implementa el informe de características de sugerencias de nivel, se omite este botón. 0x0C 0x0516

Establecer informe de salida de nivel

El host enviará este informe para establecer o cambiar el nivel de brillo de la retroiluminación en el dispositivo. El dispositivo puede detectar un host que tenga retroiluminación de teclado habilitada al recibir este informe durante el inicio del sistema o al conectarse al host.

El informe de salida de Establecer nivel debe definir un intervalo lógico de valores de nivel de brillo en una escala lineal, con la unidad HID declarada como nits. El host usa este intervalo lógico para determinar los posibles niveles de brillo admitidos por el dispositivo; no requiere que el dispositivo se calibra para emitir valores de luminancia exactos. Todos los demás comandos de retroiluminación de teclado y operaciones de host harán referencia a este intervalo lógico.

Si el mínimo lógico es igual o mayor que el máximo lógico, el dispositivo se considera no conforme y no se habilitará para el control de retroiluminación por el anfitrión.

Un valor Set Level de 0 indica al dispositivo que desactive la luz trasera. Se recomienda encarecidamente que el dispositivo use un mínimo lógico de 0 (sin brillo) para este informe.

Usos obligatorios
Nombre de informe Descripción Página ID
Establecer nivel Indica al dispositivo que establezca el brillo de la retroiluminación del teclado al valor lógico de nits especificado. 0x0C 0x007B

Informe de función para sugerencias del nivel de retroiluminación del teclado

Este informe es opcional. El dispositivo puede optar por admitir una serie de al menos dos valores preestablecidos de brillo que desea recorrer cuando el usuario presiona los botones Nivel siguiente o Nivel anterior. El host consultará estos valores preestablecidos en el inicio del sistema o cuando el dispositivo se conecte o vuelva a conectarse al host. Los valores preestablecidos deben estar dentro del intervalo lógico especificado en el informe de salida Set Level. Un valor de sugerencia de 0 es válido e indica el estado de la retroiluminación apagada como un ajuste preestablecido.

El informe de la función de sugerencias de nivel se omite si el dispositivo no implementa ni el botón de entrada de Siguiente Nivel ni el de Nivel Anterior.

Usos opcionales
Nombre de informe Descripción Página ID
Sugerencia de nivel de retroiluminación de teclado Indica un valor preestablecido de nivel de brillo sugerido que se debe tener en cuenta cuando el host controla los botones de entrada Nivel siguiente o Nivel anterior. 0x07 0x0517

Informe de ajuste de nivel de retroiluminación de teclado

Este informe es opcional. El dispositivo puede optar por implementar este informe para indicar al sistema host un nivel de brillo inicial sugerido al inicio o en el momento de la conexión, por ejemplo, si el usuario ajustó la retroiluminación antes del arranque del sistema o de conectar el dispositivo. El host consultará este informe en el inicio del sistema o cuando el dispositivo se conecte o vuelva a conectarse al host, opcionalmente seleccionando invalidar este nivel sugerido con su propio valor. Un valor sugerido de 0 es válido e indica que la luz trasera estaba desactivada. Si el valor sugerido está fuera del intervalo lógico del informe de salida Establecer nivel, se omite el informe. Un valor sugerido que no se corresponde con ninguna entrada en la función de sugerencias de nivel es válido, siempre que se encuentre dentro del intervalo lógico.

El intervalo lógico de este informe debe estar dentro del intervalo lógico del informe de salida de "Set Level".

Usos opcionales
Nombre de informe Descripción Página ID
Establecer nivel Informa al host del nivel de brillo de la luz trasera actual como sugerencia para el estado inicial del dispositivo en sus algoritmos de brillo. 0x0C 0x007B

Comportamiento del host respecto a la retroiluminación del teclado

Atenuación en modo de ahorro de energía

Windows admite la atenuación de la retroiluminación del teclado automáticamente cuando se habilita el modo de ahorro de energía. En dispositivos compatibles, esta característica se puede alternar en Configuración>Sistema>Energía y batería>Reducir el brillo del teclado al usar el ahorro de energía> o en el siguiente acceso directo: Energía y batería.

Customization

Esta característica se puede configurar en el Registro como se describe en la tabla siguiente. De forma predeterminada, la función aplica un multiplicador del 70% al brillo de la retroiluminación del teclado cuando se habilita el modo ahorro de energía.

Clave del Registro Nombre Tipo Unidades
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Lighting\Backlight RetroiluminaciónConAhorroDeEnergíaActivado REG_DWORD Boolean (1 o 0)
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Lighting\Backlight MultiplicadorDeAhorroDeEnergíaDeRetroiluminación REG_DWORD Porcentaje (0-100)

La característica también se puede configurar mediante Windows Unattended Setup o aprovisionamiento en tiempo de ejecución.

Retroiluminación de teclado con brillo automático

En dispositivos como los portátiles que disponen de retroiluminación del teclado y un sensor de luz ambiental, Windows admite el ajuste automático de la intensidad de la retroiluminación del teclado. Esta característica también se admite para teclados externos cuando están conectados a dispositivos con sensores de luz ambiente.

La función de brillo automático de la retroiluminación del teclado es distinta del brillo adaptable para las pantallas, pero conceptualmente similar en su implementación.

En dispositivos compatibles, esta característica puede activarse o desactivarse en Configuración>Bluetooth y dispositivos>Teclado>Retroiluminación del teclado>Cambiar el brillo del teclado automáticamente cuando cambia la iluminación o en el siguiente método abreviado Teclado.

Curva de respuesta de luz ambiente agrupada

La retroiluminación del teclado Autobrightness toma el concepto de una curva de respuesta de luz ambiente (ALR) en cubos, tal como se describe en Brillo adaptable.

Las asignaciones de valores predeterminados entre los niveles de lux y los porcentajes de brillo de la retroiluminación del teclado se muestran en la tabla siguiente. El porcentaje del cubo hace referencia a una proporción del valor máximo lógico del informe de salida Establecer valor y se usará mientras el nivel de luz ambiente se encuentra dentro del intervalo del cubo.

Todos los cubos de la curva ALR deben ser contiguos o superpuestos; no se permiten espacios entre depósitos. Cada cubo debe tener un valor de lux mínimo estrictamente menor que su valor de lux máximo. Si la lectura de luz ambiental cae por debajo del lux mínimo del depósito más bajo, se usa el porcentaje del depósito más bajo. Si supera el lux máximo del contenedor más alto, se utiliza el porcentaje del contenedor más alto.

Cubo Min Lux Max Lux Porcentaje
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

Cuando se conectan varios teclados retroiluminados, se usa la misma curva ALR para todos los teclados, con los porcentajes resultantes aplicados a cada dispositivo en función del intervalo de brillo lógico del dispositivo.

Customization

Los valores de habilitación de autobrillo y curva ALR se pueden configurar en el registro, como se describe en la tabla siguiente. También se pueden configurar mediante Instalación Desatendida de Windows o Aprovisionamiento en Tiempo de Ejecución.

Clave del Registro Nombre Tipo Unidades
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Lighting\Backlight Habilitar retroiluminación con brillo automático segmentado REG_DWORD Boolean (1 o 0)
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Lighting\Backlight BacklightAutobrightnessBucketMapping REG_SZ Cadena que consta de uno o varios triples delimitados por comas con el formato <minlux>:<maxlux>:<percentage>. Cada triple representa un cubo en la curva ALR. Si la curva ALR personalizada tiene huecos, tiene cero entradas o contiene cualquier cubo donde minlux ≥ maxluxse usará la curva ALR predeterminada en su lugar.

Anulación manual de brillo automático

Si se presiona un botón de entrada mientras la retroiluminación automática del teclado está activada, se iniciará una sobrescritura manual temporal del algoritmo de brillo automático. La sobrescritura genera un único segmento adicional aplicado sobre la curva segmentada, que se origina en la lectura actual de luz ambiente, con valores mínimos y máximos de lux generados a una distancia determinada por encima o por debajo de la lectura actual, en función de un porcentaje de esa lectura.

Las asignaciones de valores por defecto entre cubos lux y constantes de rango de anulación manual se muestran en la tabla siguiente. Las entradas de la tabla de búsqueda deben tener intervalos lux contiguos y no superpuestos.

Cubo Min Lux Max Lux Factor de límite inferior de sobrescritura Factor de límite superior de anulación
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

Para un ejemplo de cálculo del rango de sobrescritura, considere a un usuario presionando un botón de entrada cuando la lectura de luz ambiental más reciente sea 120 lux. La entrada correspondiente de la tabla de búsqueda es la casilla 3, porque 120 lux se encuentra entre 40 y 150 lux. El cubo se creará utilizando un umbral inferior establecido en un 60% menos que la medición actual. Con R=120 y A=0,6, el umbral inferior es 120(1 - 0,6) = 48 lux. El umbral superior también es 60% por encima de la lectura actual. De nuevo, con R=120 y B=0,6, el umbral superior es 120(1 + 0,6) = 192 lux. Por lo tanto, la anulación manual se aplicará mientras el nivel de luz ambiental permanezca en el rango de [48, 192].

Una vez activado, se usa el porcentaje de brillo del contenedor de anulación manual hasta que:

  • La lectura de luz ambiente cruza los límites del conjunto de anulación, en cuyo punto se cancela la anulación, se descarta el rango de anulación, y el control de brillo automático se reanuda mediante la curva ALR segmentada, o bien
  • Se recibe otra pulsación de botón de entrada del dispositivo, que solicita al host que ajuste el nivel de brillo y recalcule el rango de anulación manual según la última lectura de luz ambiente.

Customization

La tabla de búsqueda de sobrescritura manual se puede configurar en el registro como se muestra en la tabla a continuación. También se puede configurar mediante Configuración no atendida de Windows o aprovisionamiento en tiempo real.

Clave del Registro Nombre Tipo Unidades
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Lighting\Backlight RetroiluminaciónAutobrilloAnulaciónManualLut REG_SZ Cadena que consta de una o varias tuplas de 4 elementos delimitadas por comas con el formato <minlux>:<maxlux>:<lowerboundfactor>:<upperboundfactor>. Cada tupla de 4 representa una entrada en la tabla de búsqueda. Si la tabla de búsqueda personalizada tiene huecos, tiene cero entradas, tiene cubos superpuestos o contiene cualquier cubo donde minlux ≥ maxlux, se usará la tabla de búsqueda predeterminada en su lugar.

Descriptores de informe HID de ejemplo

Descriptor de retroiluminación para teclado de muestra

El descriptor siguiente admite todos los usos obligatorios y opcionales. Declara la compatibilidad con ocho botones de entrada de retroiluminación de teclado.

Todos los intervalos lógicos del informe de función Establecer Nivel, así como los informes de función Sugerencias de Nivel, deben estar dentro del intervalo lógico del informe de salida obligatorio de Establecer Nivel.

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

El descriptor anterior se generó a través del siguiente archivo Waratah :

[[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'
  • Last updated on