Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/manna-harbour/xmk

Use programmable keyboard firmware with any keyboard.
https://github.com/manna-harbour/xmk
keyboard keyboard-firmware kmk kmk-firmware kmonad qmk zmk
Last synced: 2 months ago
JSON representation
Use programmable keyboard firmware with any keyboard.
Host: GitHub
URL: https://github.com/manna-harbour/xmk
Owner: manna-harbour
Created: 2022-09-04T06:32:20.000Z (over 2 years ago)
Default Branch: main
Last Pushed: 2023-03-08T11:48:23.000Z (almost 2 years ago)
Last Synced: 2024-07-30T20:08:28.257Z (6 months ago)
Topics: keyboard, keyboard-firmware, kmk, kmk-firmware, kmonad, qmk, zmk
Language: Python
Homepage:
Size: 120 KB
Stars: 143
Watchers: 4
Forks: 11
Open Issues: 2
Metadata Files:
- Readme: readme.org
- Funding: .github/FUNDING.yml
Awesome Lists containing this project

README

        # Copyright 2023 Manna Harbour

# https://github.com/manna-harbour/xmk

# M-x org-make-toc to update TOC

# https://github.com/alphapapa/org-make-toc

# M-x org-babel-mark-block M-x mermaid-compile-region to preview diagram

# https://github.com/abrochard/mermaid-mode

* [[https://github.com/manna-harbour/xmk][𝑥MK]]

:PROPERTIES:

:TOC:      :include descendants :depth 1

:END:

[[docs/images/xmk-banner.jpg]]

*Use programmable keyboard firmware with any keyboard.*

:CONTENTS:

- [[#introduction][Introduction]]

- [[#operation][Operation]]

- [[#xmk][xmk]]

- [[#maps][Maps]]

- [[#firmware][Firmware]]

- [[#discussions-and-support][Discussions and Support]]

:END:

** Introduction

:PROPERTIES:

:TOC:      :include descendants :depth 1 :local depth

:END:

:CONTENTS:

- [[#uses][Uses]]

- [[#overview][Overview]]

- [[#background][Background]]

:END:

*** Uses

- Use QMK, ZMK, or KMK with any keyboard connected to a Linux host, including

  - non-programmable keyboards,

  - incompatible programmable keyboards,

  - QMK, ZMK, or KMK keyboards (using a keymap or layer without dual function keys),

  - BT or other wireless keyboards, and

  - built-in laptop keyboards.

- Record and play back timed keystrokes to

  - test keymap changes,

  - compare behaviour between QMK, ZMK, and KMK, or

  - debug firmware timing issues.

- For other uses see https://github.com/manna-harbour/xmk/discussions/2.

*** Overview

𝑥MK facilitates the use of programmable keyboard firmware with any keyboard.

With 𝑥MK, a keyboard, and an MCU board running programmable keyboard firmware, are connected to the host, and key events are diverted by ~xmk~ from the keyboard to the MCU board for processing by the firmware. 𝑥MK supports any keyboard, Linux hosts, and QMK, ZMK, or KMK keymaps, and requires an MCU board and the ~xmk~ application.

#+begin_src mermaid :file xmk-overview.svg

graph LR

    kbd([keyboard])-->xmk

    subgraph host

        xmk

        apps([applications])

    end

    xmk-->mcu

    mcu[MCU board]-->apps

#+end_src

With 𝑥MK Native, the firmware instead runs as a process on the host. 𝑥MK Native supports any keyboard, Linux hosts, and ZMK keymaps, and requires the ~xmk~ and ~usbip~ applications and no additional hardware.

#+begin_src mermaid :file xmk-native-overview.svg

graph LR

    kbd([keyboard])-->xmk

    subgraph host

        xmk-->firmware-->usbip-->apps([applications])

    end

#+end_src

*** Background

:PROPERTIES:

:TOC:      :include descendants :depth 1 :local depth

:END:

:CONTENTS:

- [[#non-programmable-keyboards][Non-Programmable Keyboards]]

- [[#programmable-keyboards][Programmable Keyboards]]

- [[#𝑥mk-and-related-projects][𝑥MK and Related Projects]]

:END:

**** Non-Programmable Keyboards

With non-programmable keyboards, keyswitches are scanned for state changes by an integrated controller, and keycode events are generated with a fixed relationship between key and keycode. Keycode events are transmitted from the controller to the host and are made available to applications on the host.

#+begin_src mermaid :file non-programmable-keyboard.svg

graph LR

    subgraph non-programmable keyboard

        ks([keyswitches])-->|state 
 changes|c[controller]

    end

    subgraph host

        apps([applications])

    end

    c-->|keycode 
 events|apps

#+end_src

**** Programmable Keyboards

[[https://qmk.fm/][QMK]], [[https://zmk.dev/][ZMK]], and [[https://github.com/KMKfw/kmk_firmware][KMK]] are firmware for compatible programmable keyboards, and support customisation functions such as remapping, layers, and dual functions keys. Typical programmable keyboards use an MCU board to run the firmware. The firmware scans the keyswitches for state changes in the same way as with a non-programmable keyboard. Keycode events are generated via a customisable keymap. Keycode events are transmitted from the keymap to the host and are made available to applications on the host.

#+begin_src mermaid :file programmable-keyboard.svg

graph LR

    subgraph programmable keyboard

        ks([keyswitches])

        subgraph MCU board

            km[keymap]

        end

        ks-->|state 
 changes|km

    end

    km-->|keycode 
 events|apps

    subgraph host

        apps([applications])

    end

#+end_src

**** 𝑥MK and Related Projects

:PROPERTIES:

:TOC:      :include descendants :depth 1 :local depth

:END:

𝑥MK and related projects facilitate the use of customisable keymaps with non-programmable keyboards.

:CONTENTS:

- [[#kmonad][KMonad]]

- [[#converter][Converter]]

- [[#modification][Modification]]

- [[#comparison-summary][Comparison Summary]]

- [[#miryoku][Miryoku]]

:END:

***** KMonad

With [[https://github.com/kmonad/kmonad][KMonad]], key events are diverted from the keyboard to the ~kmonad~ application on the host for processing by the KMonad keymap. KMonad supports any keyboard, multiple platforms, and KMonad keymaps, and requires the ~kmonad~ application and no additional hardware.

#+begin_src mermaid :file xmonad.svg

graph LR

    kbd([keyboard])-->kmonad

    subgraph host

        kmonad-->apps([applications])

    end

#+end_src

***** Converter

With a [[https://github.com/qmk/qmk_firmware/tree/master/keyboards/converter/usb_usb][QMK USB to USB keyboard protocol converter]], the converter is connected between keyboard and host, and key events are processed by the keymap. The converter supports USB keyboards, any host, and QMK keymaps, and requires the converter hardware and no additional software.

#+begin_src mermaid :file xmonad.svg

graph LR

    kbd([keyboard])-->km

    subgraph converter

        km[keymap]

    end

    subgraph host

        km-->apps([applications])

    end

#+end_src

***** Modification

With hardware modification, the non-programmable controller can be replaced with an MCU board running programmable firmware, converting the [[#non-programmable-keyboards][non-programmable keyboard]] into a [[#programmable-keyboards][programmable keyboard]]. Hardware modification supports modifiable keyboards, any host, and QMK, ZMK, or KMK keymaps, and requires the MCU board and no additional software.

***** Comparison Summary

|            | 𝑥MK           | 𝑥MK Native     | KMonad   | Converter | Modification  |

|------------+---------------+----------------+----------+-----------+---------------|

| *Keyboard* | any           | any            | any      | USB       | modifiable    |

| *OS*       | Linux         | Linux          | multiple | any       | any           |

| *Hardware* | MCU board     | none           | none     | converter | MCU board     |

| *Software* | ~xmk~         | ~xmk~, ~usbip~ | ~kmonad~ | none      | none          |

| *Keymap*   | QMK, ZMK, KMK | ZMK            | KMonad   | QMK       | QMK, ZMK, KMK |

***** Miryoku

𝑥MK can be used with any keymap. [[https://github.com/manna-harbour/miryoku_qmk/tree/miryoku/users/manna-harbour_miryoku#𝑥mk][Miryoku QMK]], [[https://github.com/manna-harbour/miryoku_zmk#𝑥mk][Miryoku ZMK]], and [[https://github.com/manna-harbour/miryoku_kmk#𝑥mk][Miryoku KMK]] include support for 𝑥MK. [[https://github.com/manna-harbour/miryoku_kmonad][Miryoku KMonad]] can be used as an alternative to Miryoku QMK, Miryoku ZMK, and Miryoku KMK with 𝑥MK.

** Operation

:PROPERTIES:

:TOC:      :include descendants :depth 1 :local depth

:END:

:CONTENTS:

- [[#𝑥mk-operation][𝑥MK Operation]]

- [[#𝑥mk-native-operation][𝑥MK Native Operation]]

- [[#record-and-playback-operation][Record and Playback Operation]]

:END:

*** 𝑥MK Operation

The required hardware components are any keyboard, an MCU board running QMK / ZMK / KMK firmware built with the [[#qmk][QMK converter / xmk keyboard]] / [[#xmk-shield][ZMK xmk shield]] / [[#kmk][KMK xmk keyboard]] and desired keymap, and a Linux host. The required software components are the [[#xmk][xmk]] python application, and a [[#maps][map]] of keyboard keycode to keymap key positions.

The keyboard is connected to the host via USB, BT, PS/2, etc. Keycode events from the keyboard are made available on the host as a keyboard evdev device.

~xmk~ reads the map, grabs the keyboard evdev device, reads the keyboard keycode events, converts keycodes to keymap key positions according to the map, and outputs key position event shell commands via stdout.

The MCU board is connected to the host via USB. The firmware includes a serial shell supporting keymap key position event shell commands. The shell is made available on the host as a tty device over USB CDC ACM (serial over USB).

Output from ~xmk~ is redirected to the tty device. The firmware shell interprets the shell commands and triggers the corresponding events in the keymap.

Keycode events from the keymap are sent to the host via USB HID, and are made available to the host as an MCU board firmware evdev device.

#+begin_src mermaid :file xmk.svg

graph TB

    kbd([keyboard])-->|keycode events via 
 USB, BT, PS/2, etc.|kd

    subgraph Linux host

        kd[keyboard 
 evdev device]-->|keycode events 
 via evdev|xmk

        mapfile[(map)]-->|keycode to keymap 
 position mapping 
 from file|xmk

        xmk-->|key position event shell commands 
 via stdout|tty[MCU board firmware tty device]

        md[MCU board firmware evdev device]-->|keycode events via evdev|a([applications])

    end

    tty-->|key position event shell commands 
 via USB CDC ACM|sh

    subgraph MCU board firmware

        sh[shell]-->|key position events|km[keymap]

    end

    km-->|keycode events via USB HID|md

#+end_src

*** 𝑥MK Native Operation

The required hardware components are any keyboard, and a Linux host. The required software components are the [[#xmk][xmk]] python application, a [[#maps][map]] of keyboard keycode to keymap key positions, ZMK firmware built with the [[#native_posix_64-board][𝑥MK native_posix_64 board]] and desired keymap, and a USB/IP client.

The keyboard is connected to the host via USB, BT, PS/2, etc. Keycode events from the keyboard are made available on the host as a keyboard evdev device.

~xmk~ reads the map, grabs the keyboard evdev device, reads the keyboard keycode events, converts keycodes to keymap key positions according to the map, and outputs key position event shell commands via stdout.

The firmware runs as a native process on the host. The firmware includes a serial shell supporting keymap key position event shell commands. The shell is made available on the host as a pty device.

Output from ~xmk~ is redirected to the pty device. The firmware shell interprets the shell commands and triggers the corresponding events in the keymap.

The firmware process includes a USB/IP server. Keycode events from the keymap are made available via the USB/IP server.

The USB/IP client connects to the USB/IP server, and receives keycode events via USB/IP. Keycode events are made available on the host as a USB/IP evdev device.

#+begin_src mermaid :file xmk-native.svg

graph TB

    kbd([keyboard])-->|keycode events via 
 USB, BT, PS/2, etc.|kd

    subgraph Linux host

        kd[keyboard 
 evdev device]-->|keycode events 
 via evdev|xmk

        mapfile[(map)]-->|keycode to keymap 
 position mapping 
 from file|xmk

        xmk-->|key position event shell commands 
 via stdout|pty[firmware process pty device]

        subgraph firmware process

            sh[shell]-->|key position events|km[keymap]-->|keycode events|us[USB/IP server]

        end

        pty-->|key position event shell commands 
 via pty|sh

        us-->|keycode events via USB/IP|uc[USB/IP client]-->|keycode events|ud[USB/IP client evdev device]

        ud-->|keycode events via evdev|a([applications])

    end

#+end_src

*** Record and Playback Operation

When recording, in addition to the normal [[#𝑥mk-operation][𝑥MK operation]] and [[#𝑥mk-native-operation][𝑥MK Native operation]], ~xmk~ saves key position events with timing to a file.

#+begin_src mermaid :file xmk-record.svg

graph TB

    kd[[keyboard evdev device]]-->|keycode events 
 via evdev|xmk

    mapfile[(map)]-->|keycode to keymap 
 position mapping 
 from file|xmk

    xmk-->|key position event shell commands 
 via stdout|tty[[firmware tty / pty device]]

    xmk-->|key position events 
 with timing 
 to file|rec[(recording)]

#+end_src

#+RESULTS:

[[file:xmk-record.svg]]

When playing back, the normal [[#𝑥mk-operation][𝑥MK operation]] and [[#𝑥mk-native-operation][𝑥MK Native operation]] is modified in that instead of reading the map and the keyboard evdev device, ~xmk~ reads key position events with timing from a file, and outputs key position event shell commands via stdout according to the timing.

#+begin_src mermaid :file xmk-playback.svg

graph TB

    rec[(recording)]-->|key position events with timing 
 from file|xmk

    xmk-->|key position event shell commands 
 via stdout|tty[[firmware tty / pty device]]

#+end_src

** xmk

:PROPERTIES:

:TOC:      :include descendants :depth 1 :local depth

:END:

~xmk~ is located at [[./src/xmk]].

:CONTENTS:

- [[#xmk-prerequisites][xmk Prerequisites]]

- [[#xmk-setup][xmk Setup]]

- [[#xmk-usage][xmk Usage]]

:END:

*** xmk Prerequisites

- https://github.com/gvalkov/python-evdev

*** xmk Setup

:PROPERTIES:

:TOC:      :include descendants :depth 1 :local depth

:END:

:CONTENTS:

- [[#add-account-to-input-group][Add Account to input Group]]

- [[#find-the-keyboard-device][Find the Keyboard Device]]

- [[#select-the-keyboard][Select the Keyboard]]

- [[#create-a-map][Create a Map]]

- [[#select-the-map][Select the Map]]

:END:

**** Add Account to input Group

Add your account to the ~input~ group.

#+BEGIN_SRC sh

sudo usermod -aG input `whoami`

#+END_SRC

Login again.

**** Find the Keyboard Device

Find the device for your keyboard under ~/dev/input~.

First look under ~/dev/input/by-id/~. It will usually end in ~event-kbd~.

#+BEGIN_SRC sh

ls /dev/input/by-id/*

#+END_SRC

Note the keyboard device in the output.

#+BEGIN_EXAMPLE

/dev/input/by-id/usb-SIGMACHIP_USB_Keyboard-event-kbd

#+END_EXAMPLE

If not listed, find the device with ~evtest~.

#+BEGIN_SRC sh

evtest

#+END_SRC

Note the keyboard device in the output.

#+BEGIN_EXAMPLE

/dev/input/event21:	SIGMACHIP USB Keyboard

#+END_EXAMPLE

**** Select the Keyboard

The ~-k~ option is used to select the keyboard. Give the path to the keyboard device from [[#find-the-keyboard-device][Find the Keyboard Device]].

#+BEGIN_SRC sh

./src/xmk -k /dev/input/by-id/usb-SIGMACHIP_USB_Keyboard-event-kbd -m ./src/maps/minidox/60_ansi -s > /dev/ttyACM0

#+END_SRC

#+BEGIN_SRC sh

./src/xmk -k /dev/input/event21 -m ./src/maps/minidox/60_ansi -s > /dev/ttyACM0

#+END_SRC

**** Create a Map

The ~-c~ option is used to create a map. Give the path to the map file to be created. Also [[#select-the-keyboard][select the keyboard]].

#+BEGIN_SRC sh

./src/xmk -k /dev/input/by-id/usb-SIGMACHIP_USB_Keyboard-event-kbd -c ./src/maps/minidox/60_ansi

#+END_SRC

Press each key to be used in the keymap in order of keymap key position. Press a key a second time to insert a line break. Press a third time to exit. Optionally edit the file to reformat whitespace or add comments with ~#~.

**** Select the Map

The ~-m~ option is used to select a map. Give the path to the map file. Use one of the included [[#maps][maps]], or first [[#create-a-map][create a map]].

#+BEGIN_SRC sh

./src/xmk -k /dev/input/by-id/usb-SIGMACHIP_USB_Keyboard-event-kbd -m ./src/maps/minidox/tap -s > /dev/ttyACM0

#+END_SRC

*** xmk Usage

:PROPERTIES:

:TOC:      :include descendants :depth 1 :local depth

:END:

:CONTENTS:

- [[#typing][Typing]]

- [[#record][Record]]

- [[#playback][Playback]]

:END:

**** Typing

The ~-s~ option is used to output firmware shell commands.

Redirect output to the tty or pty device from [[#converterxmk-setup][converter/xmk Setup]], [[#xmk-shield-setup][xmk Shield Setup]],  [[#native_posix_64-board-setup][native_posix_64 Board Setup]], or [[#kmk-xmk-setup][KMK xmk Setup]] as appropriate.

Also [[#select-the-keyboard][select the keyboard]] and [[#select-the-map][select the map]].

#+BEGIN_SRC sh

./src/xmk -k /dev/input/by-id/usb-SIGMACHIP_USB_Keyboard-event-kbd -m ./src/maps/minidox/60_ansi -s > /dev/ttyACM0

#+END_SRC

**** Record

The ~-r~ option is used to record keystrokes with timing. Give the path to the recording file to be created. Optionally redirect output as when [[#typing][typing]]. Also [[#select-the-keyboard][select the keyboard]] and [[#select-the-map][select the map]].

#+BEGIN_SRC sh

./src/xmk -k /dev/input/by-id/usb-SIGMACHIP_USB_Keyboard-event-kbd -m ./src/maps/minidox/60_ansi -r ./src/recordings/hello_world > /dev/ttyACM0

#+END_SRC

**** Playback

The ~-p~ option is used to read recorded keystrokes with timing and output firmware shell commands. Give the path to the recording file. Redirect output as when [[#typing][typing]].

#+BEGIN_SRC sh

./src/xmk -p ./src/recordings/hello_world > /dev/ttyACM0

#+END_SRC

** Maps

:PROPERTIES:

:TOC:      :include descendants :depth 1 :local depth

:END:

Map of keyboard keys to keymap key positions.

Sample maps are included under [[./src/maps]] by keymap layout.

:CONTENTS:

- [[#minidox][minidox]]

:END:

*** minidox

:PROPERTIES:

:TOC:      :include descendants :depth 1 :local depth

:END:

:CONTENTS:

- [[#60_ansi][60_ansi]]

- [[#60_ansi-noreverseangle][60_ansi-noreverseangle]]

- [[#kinesis_advantage][kinesis_advantage]]

- [[#tap][tap]]

:END:

**** 60_ansi

[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/mapping/miryoku-kle-mapping-60_ansi.png]]

**** 60_ansi-noreverseangle

[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/mapping/miryoku-kle-mapping-60_ansi-noreverseangle.png]]

**** kinesis_advantage

[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/mapping/miryoku-kle-mapping-kinesis_advantage.png]]

**** tap

Corresponds to the default [[https://github.com/manna-harbour/miryoku/tree/master/docs/reference#additional-features][Miryoku Tap layer]].

** Firmware

:PROPERTIES:

:TOC:      :include descendants :depth 1 :local depth

:END:

:CONTENTS:

- [[#qmk][QMK]]

- [[#zmk][ZMK]]

- [[#kmk][KMK]]

:END:

*** QMK

:PROPERTIES:

:TOC:      :include descendants :depth 1 :local depth

:END:

A bare QMK-compatible MCU board connected to the host over USB, running QMK built with the ~converter/xmk~ keyboard definition. USB HID is over USB. Communication from ~xmk~ to QMK is over USB CDC ACM UART.

:CONTENTS:

- [[#converterxmk-prerequisites][converter/xmk Prerequisites]]

- [[#converterxmk-setup][converter/xmk Setup]]

:END:

**** converter/xmk Prerequisites

- A [[https://github.com/qmk/qmk_firmware/blob/master/docs/compatible_microcontrollers.md][QMK-compatible]] MCU board.

**** converter/xmk Setup

The ~converter/xmk~ keyboard definition is a available at [[https://github.com/qmk/qmk_firmware/tree/master/keyboards/converter/xmk]].

Add your keymap. If it is not using one of the supported layouts, also edit ~info.json~ to add a new entry under ~layouts~, ensuring the ~matrix~ entries are in order and without gaps. If adding support for a community layout, also append to ~community_layouts~.

For local builds, build with keyboard ~converter/xmk~.

For workflow builds, fork this repo. Edit [[./.github/workflows/build-converter-xmk.yml]] to modify the values for ~repository~ and ~ref~ in the ~qmk~ step for the QMK fork containing your keymap. Run the ~Build converter/xmk~ workflow.

Connect the MCU board to USB, enter the bootloader (e.g. for [[https://learn.sparkfun.com/tutorials/pro-micro--fio-v3-hookup-guide/troubleshooting-and-faq#ts-reset][Pro-Micro]]), and flash the firmware.

Reconnect the MCU board and find the tty device.

#+BEGIN_SRC sh

sudo dmesg | grep tty

#+END_SRC

Note the tty device in the output.

#+BEGIN_EXAMPLE

cdc_acm 1-3.4.4:1.0: ttyACM0: USB ACM device

#+END_EXAMPLE

When using ~xmk~ for [[#typing][typing]], redirect output to the tty device from the previous step.

#+BEGIN_SRC sh

./src/xmk -k /dev/input/by-id/usb-SIGMACHIP_USB_Keyboard-event-kbd -m ./src/maps/minidox/60_ansi -s > /dev/ttyACM0

#+END_SRC

To enter the bootloader after flashing the firmware, ~xmk~ can be used to trigger a ~QK_BOOT~ keycode if present in the keymap, or enter the ~boot~ command in the ~converter/xmk~ shell e.g. ~echo "boot" > /dev/ttyACM0~.

*** ZMK

:PROPERTIES:

:TOC:      :include descendants :depth 1 :local depth

:END:

Two different methods of operation are supported.

:CONTENTS:

- [[#xmk-shield][xmk Shield]]

- [[#native_posix_64-board][native_posix_64 Board]]

:END:

**** xmk Shield

:PROPERTIES:

:TOC:      :include descendants :depth 1 :local depth

:END:

A bare ZMK-compatible MCU board connected to the host over USB, running ZMK built with the ~xmk~ shield definition.  USB HID is over USB. Communication from ~xmk~ to ZMK is over USB CDC ACM UART.

:CONTENTS:

- [[#xmk-shield-prerequisites][xmk Shield Prerequisites]]

- [[#xmk-shield-setup][xmk Shield Setup]]

:END:

***** xmk Shield Prerequisites

- A [[https://zmk.dev/docs/hardware][ZMK-compatible]] MCU board.

***** xmk Shield Setup

Edit [[./zmk-config/xmk.keymap]] to add your keymap. No transform is required.

For local builds, merge https://github.com/zmkfirmware/zmk/pull/1318, ~west update~, and build with shield ~xmk~ and the appropriate board for your MCU board, using the path to [[./zmk-config]] for [[https://zmk.dev/docs/development/build-flash#building-from-zmk-config-folder][ZMK_CONFIG]].

For workflow builds, fork this repo. Edit [[./zmk-config/xmk.yml]] to adjust the value for ~board~ for your MCU board. Run the ~Build xmk shield~ workflow.

Connect the MCU board to USB, enter the bootloader (e.g. for [[https://nicekeyboards.com/docs/nice-nano/getting-started#flashing-firmware-and-bootloaders][nice!nano]] or [[https://wiki.seeedstudio.com/Seeeduino-XIAO/#enter-bootloader-mode][Seeeduino XIAO]]), and flash the firmware.

Reconnect the MCU board and find the tty device.

#+BEGIN_SRC sh

sudo dmesg | grep tty

#+END_SRC

Note the tty device in the output.

#+BEGIN_EXAMPLE

cdc_acm 1-3.4.4:1.0: ttyACM0: USB ACM device

#+END_EXAMPLE

When using ~xmk~ for [[#typing][typing]], redirect output to the tty device from the previous step.

#+BEGIN_SRC sh

./src/xmk -k /dev/input/by-id/usb-SIGMACHIP_USB_Keyboard-event-kbd -m ./src/maps/minidox/60_ansi -s > /dev/ttyACM0

#+END_SRC

To enter the bootloader after flashing the firmware, ~xmk~ can be used to trigger a ~&bootloader~ binding if present in the keymap.

**** native_posix_64 Board

:PROPERTIES:

:TOC:      :include descendants :depth 1 :local depth

:END:

Note: https://github.com/zmkfirmware/zmk/issues/1444.

A Zephyr native posix application running on the host. USB HID is over USB/IP. Communication from ~xmk~ to ZMK is through a pty.

:CONTENTS:

- [[#native_posix_64-board-prerequisites][native_posix_64 Board Prerequisites]]

- [[#native_posix_64-board-setup][native_posix_64 Board Setup]]

:END:

***** native_posix_64 Board Prerequisites

- usbip

***** native_posix_64 Board Setup

Edit [[./zmk-config/native_posix_64.keymap]] to add your keymap. No transform is required.

For local builds, merge https://github.com/zmkfirmware/zmk/pull/1318, ~west update~, and build with board ~native_posix_64~, using the path to [[./zmk-config]] for [[https://zmk.dev/docs/development/build-flash#building-from-zmk-config-folder][ZMK_CONFIG]].

For workflow builds, fork this repo and run the ~Build native_posix_64 board~ workflow.

Load the usbip modules if necessary.

#+BEGIN_SRC sh

sudo modprobe vhci-hcd

#+END_SRC

Execute ~zmk.elf~.

#+BEGIN_SRC sh

zmk.elf

#+END_SRC

Note the pty device in the output.

#+BEGIN_EXAMPLE

UART_0 connected to pseudotty: /dev/pts/18

#+END_EXAMPLE

Find the busid of the usbip server.

#+BEGIN_SRC sh

usbip list -r localhost

#+END_SRC

Note the busid in the output.

#+BEGIN_EXAMPLE

Exportable USB devices

======================

 - localhost

        1-1: OpenMoko, Inc. : unknown product (1d50:615e)

           : /sys/devices/pci0000:00/0000:00:01.2/usb1/1-1

           : (Defined at Interface level) (00/00/00)

           :  0 - Human Interface Device / No Subclass / None (03/00/00)

#+END_EXAMPLE

Attach the usbip client using the busid from the previous step.

#+BEGIN_SRC sh

sudo usbip attach -r localhost -b 1-1

#+END_SRC

When using ~xmk~ for [[#typing][typing]], redirect output to the pty device from the earlier step.

#+BEGIN_SRC sh

./src/xmk -k /dev/input/by-id/usb-SIGMACHIP_USB_Keyboard-event-kbd -m ./src/maps/minidox/60_ansi -s > /dev/pts/18

#+END_SRC

*** KMK

:PROPERTIES:

:TOC:      :include descendants :depth 1 :local depth

:END:

A bare KMK-compatible MCU board connected to the host over USB, running KMK with the KMK ~xmk~ keyboard definition.

USB HID is over USB.

Communication from ~xmk~ to KMK is over USB CDC ACM UART.

:CONTENTS:

- [[#kmk-xmk-prerequisites][KMK xmk Prerequisites]]

- [[#kmk-xmk-setup][KMK xmk Setup]]

:END:

**** KMK xmk Prerequisites

- A KMK-compatible MCU board.

**** KMK xmk Setup

Merge https://github.com/manna-harbour/kmk_firmware/tree/xmk with KMK master.

Install KMK from the merged branch according to the KMK documentation.

Add your keymap to ~boards/xmk/main.py~.

Copy the contents of ~boards/xmk/~ to the root of the USB drive for your MCU board.

Reset or reconnect the MCU board and find the tty device.

#+BEGIN_SRC sh

sudo dmesg | grep tty

#+END_SRC

Note the second tty device in the output.

#+BEGIN_EXAMPLE

cdc_acm 1-1:1.0: ttyACM0: USB ACM device

cdc_acm 1-1:1.2: ttyACM1: USB ACM device

#+END_EXAMPLE

When using ~xmk~ for [[#typing][typing]], redirect output to the tty device from the previous step.

#+BEGIN_SRC sh

./src/xmk -k /dev/input/by-id/usb-SIGMACHIP_USB_Keyboard-event-kbd -m ./src/maps/minidox/60_ansi -s > /dev/ttyACM1

#+END_SRC

** Discussions and Support

- [[https://github.com/manna-harbour/xmk/discussions/1][𝑥MK Discussions and Support]]

* 

[[https://github.com/manna-harbour][https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/logos/manna-harbour-boa-32.png]]