Skip to content

Commit

Permalink
Add ZMK Studio support & switch to mouse move scroll feature
Browse files Browse the repository at this point in the history
* modify scale-divisor for regular and snipe, and decrease CPI to 1000

* change zmk firmware to pointers-with-input-processors

* add macros, optimize existing macros, expang macro queue limit

* update keymap

* initial commit for zmk studio integration

* change the chosen default to physical-layout

* move the physical layout dtsi to the correct shield directory

* update physical layouts file

* prevent copying the pysical layout dtsi for reset firmware

* configure dongle firmware to use matrix transform and bt/usb firmware to integrate ZMK studio with physical layout

* add &studio_unlock to keymap

* update key mapping names for SVG

* enabled PMW3610 smart algorithm

* update README
  • Loading branch information
280Zo authored Nov 7, 2024
1 parent fbb4d95 commit 14e11aa
Show file tree
Hide file tree
Showing 20 changed files with 1,285 additions and 813 deletions.
15 changes: 12 additions & 3 deletions .github/workflows/draw_keymaps.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -159,10 +159,19 @@ jobs:
"&VSplit": "VSPLIT",
"&caps_word": "CAPS WORD",
"&td_bore": "L_BASE L_EXTRA",
"&tdtb": "SCROLL TRACKBALL",
"&tdtb2": "SCROLL SNIPE",
"&tdmt": "L1/BS LCLICK",
"&tdbt": "L2/ESC RCLICK"
"&tdbt": "L2/ESC RCLICK",
"&td_layers": "L_BASE L_PHOTO L_GAME",
"&td_cursor": "SCRL SLOW",
"&shrug": "SHRUG",
"&lgtm": "LGTM",
"&gcm": "GIT COMMIT",
"&clip_hist": "CLIP HIST",
"&shit": "SHIT SUDO",
"&new_dir": "NEW DIR",
"&py_iter": "PYTHON LOOP",
"&js_iter": "JS LOOP",
"&studio_unlock": "ZMK Studio"
}
run: |
get_args() {
Expand Down
10 changes: 8 additions & 2 deletions .github/workflows/user_config_build.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -126,8 +126,13 @@ jobs:
cp -R "${{ inputs.config_path }}"/* "$base_config_path/"
echo "config files ready"
# Copy active keymap to the board directory & adjust for bt/dongle format
# Copy keymap & physical layouts
if [ "${{ env.shield }}" != "settings_reset" ]; then
# Copy physical layout file to shield directory
mv -v "$base_config_path/charybdis-layouts.dtsi" \
"${GITHUB_WORKSPACE}/boards/shields/charybdis-${{ env.format }}/"
# Copy active keymap to the board directory & adjust for bt/dongle format
cp -Rv "$GITHUB_WORKSPACE/${{ inputs.keymap_path }}/${{ env.keymap }}.keymap" \
"$base_config_path/charybdis.keymap"
echo "format: ${{ env.format }}"
Expand All @@ -137,7 +142,8 @@ jobs:
sed -i 's/device = <&vtrackball>;/device = <\&trackball>;/g' "$base_config_path/charybdis.keymap"
grep "device = <" "$base_config_path/charybdis.keymap"
;;
esac fi
esac
fi
fi
# Remove untargeted shields so they don't get auto picked up by the west build command
Expand Down
38 changes: 24 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,9 @@ This repository offers pre-configured ZMK firmware designed for Wireless Charybd
- Bluetooth and USB
- Dongle

Additionally, this repository also provides high level instructions and resources on how to customize and build the firmware to meet your specific needs.
Additionally, this repository automatically generates SVG images of all layers in the keymap, and adds it to the README. It also provides high level instructions and resources on how to customize and build the firmware to meet your specific needs.

Check out the [Charybdis Mini Wireless build guide](https://github.com/280Zo/charybdis-wireless-mini-3x6-build-guide?tab=readme-ov-file) if you haven't yet built your own Charybdis keyboard.

## Usage

Expand All @@ -28,7 +30,7 @@ There are a few things to note about how the pre-built firmware is configured:
- To add support for the PMW3610 low power trackball sensor, badjeff's [zmk-pmw3610-driver](https://github.com/badjeff/zmk-pmw3610-driver), [ZMK Input Behavior Listener](https://github.com/badjeff/zmk-input-behavior-listener?tab=readme-ov-file), and [ZMK Split Peripheral Input Relay](https://github.com/badjeff/zmk-split-peripheral-input-relay) modules are included in the firmware.
- eigatech's [zmk-configs](https://github.com/eigatech/zmk-config?tab=readme-ov-file) played a major role in getting badjeff's drivers and modules fully configured and are a great resource
- A separate branch builds the Bluetooth/USB firmware using [inorichi's driver](https://github.com/inorichi/zmk-pmw3610-driver?tab=readme-ov-file) as an alternative to badjeff's driver.
- [Petejohanson's individual work](https://github.com/petejohanson/zmk/blob/feat/pointers-move-scroll/docs/docs/behaviors/mouse-emulation.md) is also included in the build to allow mouse keys to function. This will be used until the main ZMK repo merges it.
- Pete Johanson (creator and lead of the ZMK firmware) developed a feature ([pointers-move-scroll](https://github.com/zmkfirmware/zmk/pull/2027)) that allows mouse keys to move and scroll. A successor feature ([pointers-with-input-processors](https://github.com/zmkfirmware/zmk/pull/2477)) was then developed that allows more flexibility. This feature is what will eventually be merged into the main ZMK branch, and it's what is used by this repo to build the firmware. Although it's not guranteed to be stable, it hasn't caused any noticible issues. That being said, if you'd prefer to use pointers-move-scroll which is in a stable state, you can update the west.yaml and adapt the config files accordingly.

## Flashing the Firmware

Expand All @@ -44,22 +46,20 @@ Follow the steps below to flash the firmware
- Repeat these steps for all devices.
- You should now be able to use your keyboard

Note - If the keyboard halves aren't connecting as expected, try pressing the reset button on both halves at the same time. If that doesn't work, follow the [ZMK Connection Issues](https://zmk.dev/docs/troubleshooting/connection-issues#acquiring-a-reset-uf2) documentation for more troubleshooting steps.
> [!NOTE]
> If the keyboard halves aren't connecting as expected, try pressing the reset button on both halves at the same time. If that doesn't work, follow the [ZMK Connection Issues](https://zmk.dev/docs/troubleshooting/connection-issues#acquiring-a-reset-uf2) documentation for more troubleshooting steps.
## Keymaps & Layers

Each layer has been heavily influenced by [Miryoku](https://github.com/manna-harbour/miryoku/) and [home row mods](https://precondition.github.io/home-row-mods) that use [bilateral combinations](https://sunaku.github.io/home-row-mods.html) to make typing as efficient and comfortable as possible, though some non-bilateral key options are also included for optional usage.
To reduce hand movement, extra attention has also been given to making sure cursor, scrolling, and mouse button operations are as seamless as possible.
The base layer uses [home row mods](https://precondition.github.io/home-row-mods) to make typing as efficient and comfortable as possible. To reduce hand movement, extra attention has also been given to making sure cursor, scrolling, and mouse button operations are as seamless as possible.

Review the layer maps below to see how each one functions. Then either modify the keymap to fit your needs, or start using these defaults to become more familiar with them.

Here are a few tips for a quick start:

- When moving the trackball, the mouse layer will be automatically activated. When the trackball movement stops, the previous layer is activated again.

- The bluetooth keys on the EXTRAS layer allow you to select which bluetooth pairing you want, BT-CLR clears the pairing on the selected profile.

- The most left thumb button has multiple functions
- The left most thumb button has multiple functions
- When held, the function of the trackball is changed from moving the cursor to scrolling.
- When double tapped, it will reduce the cursor speed for more precision, and activate the mouse layer.
- When single tapped it will activate the base layer.
Expand All @@ -68,9 +68,19 @@ Here are a few tips for a quick start:

## Modify Key Mappings

### Use a GUI
### ZMK Studio

[ZMK Studio](https://zmk.studio/) allows users to update functionality during runtime. It's currently in beta, but the physical layout and updated config files are included in the BT/USB firmware for testing. The dongle firmware does not have this integration at the moment.

To change the visual layout of the keys, the physical layout must be updated. This is the charybdis-layouts.dtsi file, which handles the actual physical positions of the keys. Though they may appear to be similar, this is different than the matrix transform file (charybdis.json) which handles the electrical matrix to keymap relationship.

To easily modify the physical layout, or convert a matrix transform file, [caksoylar](https://github.com/caksoylar/zmk-physical-layout-converter) has built the [ZMK physical layouts converter](https://zmk-physical-layout-converter.streamlit.app/).

For more details on how to use ZMK Studio, refer to the [ZMK documentation](https://zmk.dev/docs/features/studio).

### Keymap GUI

Using a GUI to generate the keymap file content is the easiest option when getting started. Head over to nickcoutsos' keymap editor and follow the steps below.
Using a GUI to generate the keymap file before building the firmware is another easy way to modify the key mappings. Head over to nickcoutsos' keymap editor and follow the steps below.

- Fork/Clone this repo
- Open a new tab to the [keymap editor](https://nickcoutsos.github.io/keymap-editor/)
Expand All @@ -81,7 +91,7 @@ Using a GUI to generate the keymap file content is the easiest option when getti
- Wait for the pipeline to run
- Download and flash the new firmware

### Edit Code Directly
### Edit Keymap Directly

To change a key layout choose a behavior you'd like to assign to a key, then choose a parameter code. This process is more clearly outlined on ZMK's [Keymaps & Behaviors](https://zmk.dev/docs/features/keymaps) page.

Expand Down Expand Up @@ -118,10 +128,10 @@ This repo uses the excellent work of caksoylar's [Keymap Drawer](https://keymap-

## Upcoming ZMK Features

ZMK is actively being developed and there are a few features that will be added to these builds as soon as they are released.
ZMK is actively being developed and there are a few features that will be added to these builds if/when they are approved.

- Mouse Pointer & Scrolling - [PR in review](https://github.com/zmkfirmware/zmk/pull/2027)
- Layer Locks - [Layer locks will hopefully get merged in](https://github.com/zmkfirmware/zmk/pull/1984)
- Layer Lock - [Open PR](https://github.com/zmkfirmware/zmk/pull/1984)
- Unicode Support - [Issue](https://github.com/zmkfirmware/zmk/issues/232)

## Credits

Expand Down
7 changes: 6 additions & 1 deletion boards/shields/charybdis-bt/charybdis.dtsi
Original file line number Diff line number Diff line change
@@ -1,9 +1,14 @@
#include <dt-bindings/zmk/matrix_transform.h>
#include "charybdis-layouts.dtsi"

/ {
// chosen {
// zmk,kscan = &kscan0;
// zmk,matrix_transform = &default_transform;
// };
chosen {
zmk,kscan = &kscan0;
zmk,matrix_transform = &default_transform;
zmk,physical-layout = &charybdis_physical_layout;
};

vbatt: vbatt {
Expand Down
7 changes: 7 additions & 0 deletions boards/shields/charybdis-bt/charybdis_left.conf
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
## ZMK Studio - Move this to config/charybdis.conf when dongle works with ZMK Studio
## https://zmk.dev/docs/features/studio
CONFIG_ZMK_STUDIO=y
## https://zmk.dev/docs/config/studio
CONFIG_ZMK_STUDIO_LOCKING=y
CONFIG_ZMK_STUDIO_LOCK_ON_DISCONNECT=y
CONFIG_ZMK_STUDIO_TRANSPORT_BLE_PREF_LATENCY=5
2 changes: 1 addition & 1 deletion boards/shields/charybdis-bt/charybdis_pmw3610.dtsi
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@
reg = <0>;
spi-max-frequency = <2000000>;
irq-gpios = <&gpio0 6 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>;
cpi = <1600>;
cpi = <1000>;
evt-type = <INPUT_EV_REL>;
x-input-code = <INPUT_REL_X>;
y-input-code = <INPUT_REL_Y>;
Expand Down
8 changes: 7 additions & 1 deletion boards/shields/charybdis-bt/charybdis_right.conf
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,10 @@ CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS=1
CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_FETCHING=y
CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_PROXY=y

CONFIG_ZMK_SLEEP=y
## ZMK Studio - Move this to config/charybdis.conf when dongle works with ZMK Studio
## https://zmk.dev/docs/features/studio
CONFIG_ZMK_STUDIO=y
## https://zmk.dev/docs/config/studio
CONFIG_ZMK_STUDIO_LOCKING=y
CONFIG_ZMK_STUDIO_LOCK_ON_DISCONNECT=y
CONFIG_ZMK_STUDIO_TRANSPORT_BLE_PREF_LATENCY=5
7 changes: 7 additions & 0 deletions boards/shields/charybdis-dongle/charybdis.dtsi
Original file line number Diff line number Diff line change
@@ -1,11 +1,18 @@
#include <dt-bindings/zmk/matrix_transform.h>
#include "charybdis-layouts.dtsi"

/ {
chosen {
zmk,kscan = &kscan0;
zmk,matrix_transform = &default_transform;
};

// ZMK Studio
// chosen {
// zmk,kscan = &kscan0;
// zmk,physical-layout = &charybdis_physical_layout;
// };

vbatt: vbatt {
compatible = "zmk,battery-nrf-vddh";
};
Expand Down
2 changes: 1 addition & 1 deletion boards/shields/charybdis-dongle/charybdis_dongle.conf
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS=2
CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_FETCHING=y
CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_PROXY=y

# CONFIG_ZMK_SLEEP=n ## Uncomment this if there are connectivity issues.
CONFIG_ZMK_SLEEP=n ## Uncomment this if there are connectivity issues

## Display Configuratoin
## https://zmk.dev/docs/config/displays
Expand Down
2 changes: 1 addition & 1 deletion boards/shields/charybdis-dongle/charybdis_pmw3610.dtsi
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@
reg = <0>;
spi-max-frequency = <2000000>;
irq-gpios = <&gpio0 6 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>;
cpi = <1600>;
cpi = <1000>;
evt-type = <INPUT_EV_REL>;
x-input-code = <INPUT_REL_X>;
y-input-code = <INPUT_REL_Y>;
Expand Down
2 changes: 2 additions & 0 deletions build.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ include:
keymap: qwerty
format: bt
artifact-name: charybdis_qwerty_right
snippet: studio-rpc-usb-uart

# Colemak DH BT
- board: nice_nano_v2
Expand All @@ -41,6 +42,7 @@ include:
keymap: colemak_dh
format: bt
artifact-name: charybdis_colemak_right
snippet: studio-rpc-usb-uart

# QWERTY Dongle
- board: nice_nano_v2
Expand Down
63 changes: 63 additions & 0 deletions config/charybdis-layouts.dtsi
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
#include <physical_layouts.dtsi>

/ {
charybdis_physical_layout: charybdis_physical_layout {
compatible = "zmk,physical-layout";
display-name = "Charybdis 3x6";

kscan = <&kscan0>;
transform = <&default_transform>;

keys
// Left Half - Main Keys
// w h x y rot rx ry
= <&key_physical_attrs 100 100 0 38 0 0 0>
, <&key_physical_attrs 100 100 100 38 0 0 0>
, <&key_physical_attrs 100 100 200 12 0 0 0>
, <&key_physical_attrs 100 100 300 0 0 0 0>
, <&key_physical_attrs 100 100 400 12 0 0 0>
, <&key_physical_attrs 100 100 500 12 0 0 0>
, <&key_physical_attrs 100 100 900 12 0 0 0>
, <&key_physical_attrs 100 100 1000 12 0 0 0>
, <&key_physical_attrs 100 100 1100 0 0 0 0>
, <&key_physical_attrs 100 100 1200 12 0 0 0>
, <&key_physical_attrs 100 100 1300 38 0 0 0>
, <&key_physical_attrs 100 100 1400 38 0 0 0>
, <&key_physical_attrs 100 100 0 138 0 0 0>
, <&key_physical_attrs 100 100 100 138 0 0 0>
, <&key_physical_attrs 100 100 200 112 0 0 0>
, <&key_physical_attrs 100 100 300 100 0 0 0>
, <&key_physical_attrs 100 100 400 112 0 0 0>
, <&key_physical_attrs 100 100 500 112 0 0 0>

// Right Half - Main Keys
// w h x y rot rx ry
, <&key_physical_attrs 100 100 900 112 0 0 0>
, <&key_physical_attrs 100 100 1000 112 0 0 0>
, <&key_physical_attrs 100 100 1100 100 0 0 0>
, <&key_physical_attrs 100 100 1200 112 0 0 0>
, <&key_physical_attrs 100 100 1300 138 0 0 0>
, <&key_physical_attrs 100 100 1400 138 0 0 0>
, <&key_physical_attrs 100 100 0 238 0 0 0>
, <&key_physical_attrs 100 100 100 238 0 0 0>
, <&key_physical_attrs 100 100 200 212 0 0 0>
, <&key_physical_attrs 100 100 300 200 0 0 0>
, <&key_physical_attrs 100 100 400 212 0 0 0>
, <&key_physical_attrs 100 100 500 212 0 0 0>
, <&key_physical_attrs 100 100 900 212 0 0 0>
, <&key_physical_attrs 100 100 1000 212 0 0 0>
, <&key_physical_attrs 100 100 1100 200 0 0 0>
, <&key_physical_attrs 100 100 1200 212 0 0 0>
, <&key_physical_attrs 100 100 1300 238 0 0 0>
, <&key_physical_attrs 100 100 1400 238 0 0 0>

// Thumb Clusters
// w h x y rot rx ry
, <&key_physical_attrs 100 100 348 314 0 0 0>
, <&key_physical_attrs 100 100 348 314 1500 398 790>
, <&key_physical_attrs 100 100 348 320 3000 398 790>
, <&key_physical_attrs 100 100 1052 320 (-3000) 1102 790>
, <&key_physical_attrs 100 100 1052 314 (-1500) 1102 790>
;
};
};
12 changes: 9 additions & 3 deletions config/charybdis.conf
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ CONFIG_ZMK_BLE_EXPERIMENTAL_FEATURES=y
## Power Management Config
## https://zmk.dev/docs/config/power
CONFIG_ZMK_SLEEP=y
CONFIG_ZMK_IDLE_TIMEOUT=30000
CONFIG_ZMK_IDLE_SLEEP_TIMEOUT=600000
# CONFIG_ZMK_IDLE_TIMEOUT=30000
# CONFIG_ZMK_IDLE_SLEEP_TIMEOUT=600000
CONFIG_ZMK_EXT_POWER=y
## https://docs.zephyrproject.org/2.7.5/reference/kconfig/CONFIG_PM_DEVICE.html
CONFIG_PM_DEVICE=y
Expand All @@ -26,4 +26,10 @@ CONFIG_ZMK_MOUSE=y
## Include input subsystem and drivers in the system config
## https://github.com/badjeff/zmk-pmw3610-driver
## https://github.com/badjeff/zmk-split-peripheral-input-relay
CONFIG_INPUT=y
CONFIG_INPUT=y

## https://zmk.dev/docs/keymaps/behaviors/macros#behavior-queue-limit
CONFIG_ZMK_BEHAVIORS_QUEUE_SIZE=512

## https://github.com/zmkfirmware/zmk/pull/2477
# CONFIG_ZMK_MOUSE_SMOOTH_SCROLLING=y
Loading

0 comments on commit 14e11aa

Please sign in to comment.