I have my config set up with the intent of using a dongle to connect to three peripherals: my totem split and my adept BLE. The GitHub actions, build succeeds, and the keyboard and dongle work exactly the way I want them to. The problem I’m having is that the track ball’s optical sensor does not seem to work at all, and the buttons, instead of clicking and such, our outputting letters that should be coming from the left half of the keyboard.
#Build succeeds but AdeptBLE not working as expected
1 messages · Page 1 of 1 (latest)
It looks like the only matrix-transform, physical-layout and keymap you have on the dongle are for the totem? You'd need to combine that with the adeptble's.
The peripheral is "dumb". It only sends row and column presses to the central. Since it's using its own matrix transform with no offset, it's sending stuff like
<dbg> zmk: kscan_matrix_read: Sending event at 0,0 state on
<dbg> zmk: zmk_physical_layouts_kscan_process_msgq: Row: 0, col: 0, position: 0, pressed: true
Your dongle sees "row 0, column 0", and matches that up to the only matrix-transform/physical-layout/keymap it's been built with.
You'll need to set the pointer up to work as a split peripheral, too: https://zmk.dev/docs/development/hardware-integration/pointing#input-device
Where do I start if I want to really understand the relationships of all the stuff that goes into making this all work? I've found the docs helpful when trying to do specific/focused tasks but not so much on understanding the big picture. Even the stuff I've successfully completed has been mostly just following rote instructions and parroting stuff I've seen in successful configs.
...That is a fantastic question which I don't really have an answer to.
What I know, I've pieced together almost entirely via troubleshooting.
I might start by going upstream.
You can create an exploratory project separate from ZMK, but using ZMK's Zephyr fork (...just so you aren't quite so blindsided by all the breaking changes). You should be able to re-use ZMK's zephyr folder with a bit of finagling, if you want.
Or just dive into the documentation.
good call on all that
I'd started looking at the Zephyr 3.5 docs but it's a lot and it will take time even just to figure out what bits are even relevant.
Someone on the Ploopy server showed me this site, and while obviously LLM stuff needs to be carefully digested and verified I think it has potential to be useful.
DeepWiki
This page provides a comprehensive introduction to the ZMK firmware, its architecture, and core components. It serves as a starting point for understanding how the different parts of ZMK work together
It basically takes an entire repo and creates alternate documentation of it. Like I said, there may be large or small flaws, but it does come at zmk from angles I haven't found cohesively addressed in the human generated docs.
Having to write #help message reminded me of this issue as well. I think we have bits and pieces of this kind of explanation in https://zmk.dev/docs/config/layout (which is linked from new shield guide, IIRC) but nowhere says explicitly that row/col-offset in the matrix transform is the mechanism used to "put together" keys from different parts of a split keyboard
See Configuration Overview for instructions on how to change these settings.
It would be nice to have a proper explainer for the full interaction between kscan -> matrix transform -> physical layout, with additional notes specifically for split keyboards
The deepwiki seems OK, but it conflates a lot of the internals (C APIs) with the config, and that's really not what we'd want to do for end users
Yeah that’s the impression I got. It wasn’t as useful as I hoped. I see there’s WIP of a Devicetree primer which is cool https://github.com/nmunnich/zmk/blob/devicetree-primer/docs/docs/development/devicetree.md
Indeed, that will be useful to understand the syntax and file structure. Should be merged very soon
Can I still take the approach of importing my Totem and AdeptBLE modules?
And if so, would it work to override the default AdeptBLE.overlay by putting a modified copy in zmk-config-bilderman-kawasaki/boards/shields/AdeptBLE?
I'll need to override the row offset somehow
I modified totem_dongle.overlay to include the trackball in the default transform starting on the next row down from the keyboard
Truthfully I don't have any splits, much less dongles, so I haven't worked through any of this myself.
If by "importing" you mean referencing in your config/west.yml, yes. If I understand this correctly you'll just be ignoring all their Not quite, you're right about kscans, matrix-transforms and physical-layouts—whatever's configured in their overlays will basically be like unused variables.row-offset I think. Hmm...
I've already got them referenced in west.yml, just not super certain where to override stuff like the overlays from the referenced modules
the only example I have to work off is this one, but it doesn't use external modules at all.
It's a bit madcap, but perhaps putting whatever offset in the keymap would work? 
Not the totem_dongle.keymap, which I'm pretty sure will be the one that gets used for everything. adeptble.keymap
hmm
I think that still gets applied as the final overlay even if the actual key mappings from it aren't used.
can you not override a .overlay?
With another .overlay, I take it.
You can try! But I think you'll run into this: https://github.com/zmkfirmware/zmk/issues/1382
Which is why I suggest the keymap.
Give it a build and look very closely at what files are included and in what order. (This is not a rhetorical or Socratic statement.)
You can pass an "unrelated" KEYMAP_FILE in via cmake-args, if that helps: https://github.com/zmkfirmware/zmk/issues/1931#issuecomment-2174153453
I'm back at this again, but with a new repo.
I decided to abandon for now the approach of trying to include my totem and adeptBLE modules and also to have the adeptBLE act as dongle.
The dongle function is working so the keyboard is totally usable but the trackball sensor is not working at all and the buttons are not referenced properly in such a way that the zmk build knows how to connect them to the desired behavior
I do still need to follow the build logs carefully to see if I learn anything