tiny-pilot / tiny-pilot/tinypilot

Support a "force QWERTY" mode

Open
#1,171 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Python
Stars
3.5k
Forks
291
PR merge metrics
No merged PRs in 30d

Description

Problem

TinyPilot sends keyboard input by forwarding key events by sending the KeyboardEvent.code value for the input event. The the KeyboardEvent.code is agnostic to keyboard layout, as it represents the physical position of the key on the keyboard.

Sending the KeyboardEvent.code value means that the target computer gets to decide how to interpret the key depending on the layout of the target system. The behavior is equivalent to if your keyboard was directly plugged into the target system.

In some cases, TinyPilot's default behavior is not desirable. If a TinyPilot user has a keyboard with the NEO layout, but their target system has a QWERTY layout, the keys the user presses as they observe on their local keyboard won't match the keys that appear on the target system.

For example, on a NEO local system and a QWERTY target system:

  1. User pushes the button labeled h on their NEO keyboard
  2. TinyPilot receives JS keystroke with event.code='KeyU'
  3. TinyPilot translates KeyU to HID KEYCODE_U=0x18
  4. A 'u' character appears on the target system

If the user actually meant for the target system to receive the h keystroke, then TinyPilot's behavior is undesirable.

This scenario can happen when the target system is in an OS environment without keyboard layout options, so it assumes QWERTY.

Proposed solution

TinyPilot should offer a configuration option where the user can elect to "force QWERTY" where TinyPilot assumes that the target system is QWERTY and forces keystrokes to their QWERTY equivalent.

When "force QWERTY" mode is active, instead of looking at the KeyboardEvent.code property, we'd look at KeyboardEvent.key, which would represent the layout-aware character they pressed. We'd then translate that key into the equivalent HID code, assuming the target system is QWERTY.

For example, on a NEO local system and a QWERTY target system (with "force QWERTY" enabled):

  1. User pushes the button labeled h on their NEO keyboard
  2. TinyPilot receives JS keystroke with event.key='h'
  3. TinyPilot translates h to HID KEYCODE_H=0x0b
  4. An 'h' character appears on the target system

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the existing path from JavaScript KeyboardEvent.code through HID translation, then compare how KeyboardEvent.key would represent the same input. Identify where configuration is defined and how keyboard events are translated; done means an optional force-QWERTY setting produces the intended HID key while existing behavior remains unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, python
Domain
embedded-iot, frontend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.