Creating a Human68k Utility to Map Keyboard Scancodes to Key Names
The X68000 keyboard presents an interesting problem for retrocomputing preservation because its Human68k environment translates physical key presses into several different forms. A controller value, a Human68k key code, an ASCII character and an application event may all describe the same press. A useful mapper must identify the correct layer, retain the original value and associate it with a stable key name. Learn more about ゲーミングキーボードのスイッチをリニアとタクタイルで比較しながら交換する実験メモ.
A Human68k scancode-to-key-name utility turns that hidden relationship into an observable diagnostic. It can identify a mystery key, verify a repaired keyboard, document differences between key layouts and help software authors understand the codes supplied by Human68k. The utility should report what it receives without changing the keyboard configuration, interfering with normal typing or assuming that every installation uses the same controller behaviour.
Define the value being mapped
The word “scancode” can describe a physical matrix position, a value encoded by the keyboard controller or a key code passed through Human68k and its BIOS layer. These are related, but they are not interchangeable. A matrix row and column may need to be combined before they resemble the integer recorded by the operating system, while an application character may already have modifier and keyboard-mode processing applied.
The first design decision is therefore to state exactly which value the utility will display. For a general-purpose diagnostic, preserve the complete integer returned by the selected input interface and label it as a Human68k or BIOS key code. If lower-level controller values are available, those can be captured separately. The name should describe the physical key, such as LEFT_SHIFT, F1, RETURN or BACKSPACE, rather than whichever character the current mode happens to produce.
Each captured event should include the numeric code in hexadecimal and decimal, a canonical key name and any separately decoded modifier flags. Unknown values must remain visible as UNKNOWN_0xNN; guessing a name from the expected keyboard arrangement can conceal the very mismatch the utility was built to find.
Trace the Human68k keyboard path
Begin with the documented Human68k or BIOS keyboard-input function. It is safer and usually sufficient because the operating system already handles the controller handshake, scan timing and keyboard state. A character-returning function may not expose the underlying scancode, however. In that case, a diagnostic resident or a carefully placed breakpoint in the keyboard handler can record the integer before it is translated into text.
Reading the keyboard controller directly is possible but should remain an advanced option. User programs can easily lose an interrupt, mistake a controller status bit for a key or disturb the system’s keyboard state. The capture routine should also establish whether the controller sends separate press and release values. Separate release reporting cannot be assumed across every keyboard revision, so the utility should learn this behaviour from the connected machine instead of building it into the decoder.
Current notes in the X68K diary provide a useful place for recording the exact Human68k version, board revision and input routine used during development. A reliable capture procedure starts with one known key, then covers every key, held keys, repeated presses and simultaneous modifier combinations. Saving the raw hexadecimal values before assigning names prevents an early assumption from becoming embedded in the program.
Construct the lookup data
The mapper’s core can be a fixed array of records containing the observed code, decoded flags, canonical name and optional aliases. Fixed-width integer types are preferable where the available compiler supports them; otherwise, use an explicitly sized unsigned type and verify that promotion to a signed integer cannot corrupt a high-bit value. Keep the original code as it appeared in the capture log, because Human68k implementations may place modifier information in the same byte as the key code.
Modifier keys deserve special treatment. Shift, Control, Alt and the Japanese conversion keys can be represented as separate flags, but their masks must follow the interface being decoded. Blindly removing a high byte can erase both a key identity and a modifier state. Store the combined value first, decode it with documented masks and retain enough information to reconstruct the original input.
These representations should never be conflated:
| Representation | What it identifies | Layout sensitivity | Diagnostic value |
|---|---|---|---|
| Matrix row and column | A physical switch position | Low | Shows the hardware connection clearly |
| Encoded controller value | What the keyboard controller transmitted | Usually low | Best for identifying a failed or unusual key |
| Human68k or BIOS key code | The operating system’s internal key identifier | Medium | Most practical for application diagnostics |
| Translated character | Text produced after keys and modifiers were processed | High | Useful for checking what software receives |
The completed mapping can then provide canonical English names, with aliases such as ESC for ESCAPE or ENTER for RETURN. A name should identify the key rather than a particular character: YEN remains YEN in every keyboard mode, while A remains A whether it ultimately produces a Latin letter or a converted character. Keeping this distinction makes logs much easier to compare.
Handle Japanese and Australian layouts
Human68k is closely associated with the Japanese JIS keyboard used by the X68000. Its special keys include kana and conversion controls, Japanese punctuation, function keys and keys that have no direct equivalent on a contemporary Australian PC board. The mapper should preserve those physical names even when the active mode converts a press into an ASCII character. Useful canonical labels include KANA, ZENKAKU_HANKAKU, YEN, XF1 and PRTSC.
Most full-size keyboards sold for Australian PCs use a US-English 104-key arrangement, although ISO 104-key versions are also available. Their backslash, punctuation and modifier positions differ from JIS, and an Australian replacement board may include Windows or application keys that never existed on the original X68000 keyboard. A key-map profile must therefore state the physical layout rather than silently treating every number row, backslash key or modifier as universal.
Australian surplus dealers and online marketplaces usually offer plentiful PC replacement boards but relatively few original X68000 keyboard assemblies. That makes adapted modern boards attractive to hobbyists, although their switch feel, rollover behaviour and controller protocol may differ substantially. A switch replacement experiment comparing linear and tactile gaming switches is a useful side reference for keyboard mechanics, but switch feel cannot reveal an X68000 scancode.
At retrocomputing gatherings in Sydney, Melbourne and Canberra, collectors may describe a keyboard that drops or duplicates characters as “crook”. A capture log can distinguish that informal diagnosis from several measurable causes: switch bounce, matrix conflicts, ghosting, mode confusion or an incorrect lookup entry. Australian mains electricity is 230 volts at 50 hertz, so bench testing should use a suitable surge-protected supply and keep the original hardware well ventilated.
Make the utility dependable on real hardware
A live display is the most useful default. It can show the most recent code in hexadecimal, its canonical name and the current modifier flags. A capture mode should append each event to a scrolling display, while a dump mode can output the complete mapping for later inspection. Names should remain printable ASCII even if the console supports Japanese text, because stable labels are more valuable than decorative localisation in a diagnostic tool.
Reliability depends on handling the awkward parts of an interactive utility. A blocked BIOS read may ignore a normal interrupt-based exit request, so the program needs a quit key that the input path will actually return. It should not clear the screen on every keystroke, overwrite unrelated memory or modify the Human68k keyboard configuration. A small static lookup array, fixed output buffers and explicit limits on captured events will keep memory use predictable on an original 16-bit environment.
Testing should progress from individual keys to the full keyboard. Verify uppercase and lowercase input, every modifier, mode changes, held keys, repeat events and two-key or three-key combinations. Rapid typing can expose rollover limitations that a slow key-by-key test misses. Any code that cannot be reproduced should remain in the unknown list until another physical test confirms its identity, rather than being filled in from a photograph of the keyboard.
Results should be saved in a plain-text format containing the hexadecimal code, modifier flags, canonical name and any alias. Include the Human68k version and test date because identical-looking keyboards can expose different controller behaviour. A compact exported file also makes it possible to compare a repaired machine with a known-good system without recompiling the utility.
Publish a reusable keyboard map
Complete documentation should identify the X68000 model, Human68k release, keyboard revision, selected input interface and keyboard-mode assumptions. It should also record any differences between the original board and an adapted replacement. These details allow another hobbyist to distinguish a genuinely new scancode from a utility that was tested under different conditions.
Expansion-board users can find related preservation context in the Nereid-X project, where hardware, firmware and diagnostic information belong together. A keyboard mapper does not need an expansion board to operate, but documenting whether one was present helps prevent an environmental variable from being mistaken for a keyboard-controller difference.
Start with a minimal version that captures one known key and prints one verified name, then extend it to the complete keyboard and modifier set. Publish the source, mapping data and a short test record in the project diary, and compare results with another X68000 wherever possible. A reproducible map gives the next collector a working diagnostic instead of another box of undocumented mystery codes.
Nereid-X Expansion Board
A personally-produced LAN+USB+Memory expansion board for Sharp X68000 series computers. Multiple production runs were offered, including a final batch and a later revival reproduction run.
Power Supply Repair
X68 power supply repair and modification services were offered by the site owner, with documentation shared through diary entries spanning 2001–2006.
Server & Networking
Notes on FreeBSD administration, ISP changes, server migration, and networking topics. The site itself ran on FreeBSD with the hns diary system and Namazu search integration.
Get in touch
X68K.NET connects Sharp X68000 enthusiasts through community links and shared projects. Reach out with questions about the Nereid project or X68 resources.