ChromeOS Compatible - Keyboard Specification v1.0

Version: 1.0.1
Last Updated: 2024-02-01

Legend

Product Verb Development Action
"MUST" Mandatory product requirement
"SHOULD" Optional recommendation
"MAY" Nice to have

Overview

This specification document describes the criteria that a ChromeOS Compatible Keyboard meets.

This specification covers an external keyboard that is not a part of the device's main chassis. The keyboard may be connected wirelessly or via wire to a ChromeOS device.

The keyboard may be sold separately as an accessory or bundled with a ChromeOS device.

Glossary

  • Special keys: Tab, Enter, Backspace, Space, 英数, かな, かな<=>英数, Fn, Page Up, Page Down, Home, End, Delete, Escape, Lock, Language Switch.
  • Modifier keys: Launcher, Shift, Control, Alt, Alt Gr, Fn.
  • Character keys: Keys that represent written language or mathematical operations, which includes letters, punctuation, symbols, and diacritic characters.
  • Function keys: Numbered Fn keys, such as F1, F2, ....
  • Navigation keys: Up, Down, Left, Right.
  • Six-pack: In extended layout, the two rows of three keys sitting above Navigation keys.
  • Dongle: A small port adapter that provides communication with an accessory in a format not supported natively by the ChromeOS device. A dongle often contains an RF receiver.
  • RF: Radio Frequency. The most common form of wireless communication.
  • Modal keys: Caps Lock, Num Lock, Scroll Lock; Keys that change the behavior of the keyboard and continue to have effect after they are released.

Type

  • If the keyboard connects to the ChromeOS device via a wired connection, then it SHOULD connect to the ChromeOS device using USB.
  • If the keyboard uses a wireless connection, then it SHOULD connect to the ChromeOS device using Bluetooth or a 2.4 GHz USB adapter (dongle).

Security

Firmware Updater

It's important to ensure peripherals can be patched in case vulnerabilities are discovered in the future. Otherwise, peripherals with known vulnerabilities will be blocked from connecting with ChromeOS.

  • A Bluetooth wireless keyboard SHOULD support firmware updatability.
  • A 2.4 GHz dongle keyboard SHOULD support firmware updatability.
  • The keyboard SHOULD support firmware updates via fwupd.
    • Note: This will allow updates to be seamless to the user during a standard ChromeOS update (typically every 4 weeks).

Connectivity

  • The wireless keyboard SHOULD support connecting with the ChromeOS device using one or both of:
    • Bluetooth
    • 2.4 GHz Wireless dongle

2.4 GHz Wireless Dongle

A keyboard that comes with a 2.4 GHz wireless receiver (dongle) automatically pairs with (and only with) that receiver. User action (either on the device or via an app) is required to pair the keyboard with another receiver or pair a new keyboard with an existing receiver. The following requirements detail this functionality.

  • Where a 2.4 GHz wireless keyboard is packaged together with a receiver, the receiver MUST support connecting to the ChromeOS device via USB-A or USB-C.
  • If a 2.4 GHz wireless keyboard is packaged together with a receiver, then the keyboard MUST auto-pair with the receiver packaged with the keyboard.
  • A 2.4 GHz wireless Keyboard that is packaged together with a receiver MUST auto-pair only with the receiver packaged with the keyboard.
  • The 2.4 GHz keyboard MAY allow the user to pair the keyboard with another receiver.
  • The receiver MAY allow the user to pair another 2.4 GHz keyboard with the receiver.
  • The keyboard MAY rely on an app for user-initiated pairing with other receivers.
  • The receiver MAY rely on an app for user-initiated pairing with other keyboards.
  • If an app is required to alter keyboard/receiver pairing, then the app SHOULD run on ChromeOS.
  • If a pairing app is used, the pairing app SHOULD be a ChromeOS native app.
    • Note: Chrome Extensions are often used to support configuration of hardware and accessories.
  • The device MAY rely on a progressive web app (PWA) using WebUSB or WebHID for customization.
  • If a pairing app is used, the pairing app MAY be a web app using WebUSB or WebHID.
  • If pairing is implemented via an extension, then the extension MUST ONLY have access to USB ports.
    • Note: Content scripts are explicitly disallowed.

Bluetooth

  • If a wireless keyboard supports Bluetooth, the wireless keyboard MUST comply with requirements in ChromeOS Compatible Bluetooth Requirements. Specifically, the following sections:
    • Generic Bluetooth Requirements
    • Bluetooth Input Device Requirements

Connectors

Wired Keyboards

  • A wired keyboard SHOULD support one of the following USB transports:
    • On-keyboard USB-C receptacle
    • Captive cable with USB-A plug
    • Captive cable with USB-C plug
  • If the wired keyboard supports on-device USB-C receptacle, the USB-C receptacle MUST comply with Section 4.5.1.3.2 Sink Configuration Channel Functional Model.
  • If the wired keyboard supports on-device USB-C receptacle, the USB-C receptacle MUST comply with Figure 4-9 Sink Functional Model for CC1 and CC2.
  • If the wired keyboard supports captive cable with USB-A plug, the product bundle SHOULD include a compliant USB Type-C to USB 3.1 Standard-A Receptacle Adapter (USB Type-C Specification Section 3.6.1).
  • If the wired keyboard supports captive cable with USB-C plug, the USB-C plug MUST comply with USB Type-C Specification Section 4.5.2 CC Functional and Behavioral Requirements.
    • Note: specifically the rules around direct connect device or device with captive cable (These devices shall apply and sense CC voltage levels on pin A5 only).
  • If the wired keyboard supports captive cable with USB-C plug, the keyboard MUST omit a passive USB Type-C Receptacle to USB-A adapter.
    • Rationale: USB Type-C Receptacle to USB-A adapters are forbidden by the USB Type-C Specification Section 2.2.
  • If the product bundle includes a USB cable, the cable SHOULD be USB-IF certified.

Key Behavior

N-key Rollover

  • If the keyboard is expected to be paired with gaming-friendly devices, then it SHOULD support N-key rollover (NKRO).
    • Note: A keyboard that supports NKRO can report any number of keys being pressed at the same time.
  • If the keyboard does not support NKRO, then it SHOULD support six-key rollover (6KRO) or better.
    • Note: A keyboard that supports 6KRO can report up to 6 keys being pressed at the same time.
  • If the keyboard supports less than 6KRO, then it SHOULD have anti-ghosting or other reliable mechanisms to prevent erroneous key presses being registered.

HID Codes

  • The keyboard MUST send a HID report descriptor when queried, as required by the Device Class Definition for HID v1.11.
  • All keys MUST send meaningful action HID codes, mapped to a KEY_ or BTN_ code by the linux kernel.
    • Note: Some legacy external ChromeOS Device keyboards send F1, F2, etc. which do not match the glyph on the key— these are not compliant.

Function Keys

  • Keys MAY have a secondary behavior as Function keys.
  • If the keyboards have keys with a secondary behavior as Function Keys, the keyboard MUST have a Fn key.
  • If a key with secondary behavior as a Function Key is chorded with a Fn key, the keyboard MUST send a Function Key HID code.
  • The keyboard MAY dedicated Function keys.

Glyph Artwork Guidelines

Function keys

  • Primary action glyphs SHOULD appear more visually prominent (larger, brighter, or heavier in weight) than secondary function glyphs.

The Navigation keys are Up, Down, Left, and Right.

  • If the keyboard has Navigation keys, the Navigation keys SHOULD have arrow glyphs printed on the key caps.
  • If the keyboard has a Left key and a Back key, then the Left key glyph SHOULD be visually distinct from the Back key glyph.
  • If the keyboard has a Right key and a Forward key, then the Right key glyph SHOULD be visually distinct from the Forward key glyph.

Battery and Power

  • If the keyboard contains a battery, then the keyboard firmware SHOULD report battery level via HID.
  • If the keyboard contains batteries, then the keyboard MAY include one or more of: power-related keys, a power indicator, and power switch.
  • If the keyboard contains a rechargeable battery, then the keyboard SHOULD support recharging via USB.
  • If the device is bundled with a USB-C charger, then the charger MAY be USB-IF certified for power delivery.

Software

Vendor and Product IDs

  • The vendor ID reported by the keyboard over all protocols MUST belong to the manufacturer.
  • The vendor/product ID combinations(s) reported by the keyboard MUST be unique from other keyboard models.
  • If multiple variants exist of the same keyboard model, they SHOULD all share the same HID descriptor.
  • If variants of the same keyboard model have different HID descriptors, each variation of HID descriptor MUST map to a unique product ID.

Kernel

  • If a custom kernel driver is used, it MUST be checked into upstream Linux
  • If a custom kernel driver is used, it MUST be backported to Chromium OS kernels 4.14 and above.
  • When a keyboard is switched off or disconnected, the kernel MUST remove the keyboard from the collection of input devices.

Revision History

Date Version Notes
2024-02-01 1.0.1 Republication on a new platform
2023-05-18 1.0 Initial Partner Site Publication