Bootloader reset docs ambiguity around split keyboards locality

[davidgamero]

These two quotes were very confusing to reconcile until I read the open issues:

behaviors/reset#split-keyboards

The peripheral side of the keyboard has to be paired and connected to the central side in order to be able to activate these behaviors, even if it is possible to trigger the behavior using only keys on that side. This is because the key bindings are processed on the central side which would then instruct the peripheral side to reset.

features/combos#advanced-usage

Invoking a source-specific behavior such as one of the reset behaviors using a combo will always trigger it on the central side of the keyboard, regardless of the side that the keys corresponding to key-positions are on.

I now see that this comes from the 'locality' from https://github.com/zmkfirmware/zmk/pull/547 and will likely change when https://github.com/zmkfirmware/zmk/issues/1494 is complete and the combos will no longer only trigger on the central side.

Hoping someone who understands this more deeply could clarify the order of operations here, and I'm happy to make a PR to update the docs

Regardless, it could also be very helpful to add additional information for split keyboards saying when it is actually necessary to re-flash both sides vs just the central one (I didn't realize I didn't have to flash both sides for keymap-only updates and had been doing it for days before a friend told me)

[caksoylar]

Can you elaborate a little more on why the two statements together confuse you? I can't spot an issue but I can't see it with fresh eyes, like you do.

Regardless, it could also be very helpful to add additional information for split keyboards saying when it is actually necessary to re-flash both sides vs just the central one (I didn't realize I didn't have to flash both sides for keymap-only updates and had been doing it for days before a friend told me)

That would be good to put somewhere indeed, I proposed #948 which mentions it but I never got around to writing something of the sort.

[davidgamero]

Sure!

The tricky part comes from interpreting these parts:

... which would then instruct the peripheral side to reset.

^ this states that using a key binding to reset the peripheral side requires the central side to be on into order to process the reset command, implying that the peripheral side can be reset as long as the central side is connected.

Invoking a source-specific behavior such as one of the reset behaviors using a combo will always trigger it on the central side of the keyboard, regardless of the side that the keys corresponding to key-positions are on.

This bit says that the central side will always reset if the command comes from a combo, even if that combo comes from the peripheral side, which goes against the "local" concept above. The tricky part is that I had read about combos first, then the reset behavior and totally missed the caveat about reset locality.

Lmk if that doesn't make sense and I can rephrase

[caksoylar]

I think I get your point. Do you mean that it is not very clear in the combos doc that this is an exception to the rule (of how source-specific behaviors, like reset work)?

I am not sure if you could count that as an exception, since combos by their nature involve multiple key positions. For instance it is not clear which side you would reset when you trigger a combo with key positions on both halves of the keyboard. However this could be changed in the future so that if all key positions are on the same half then you could trigger on that half, falling back to the triggering on the central if not, like the current behavior.

(The problem in #1494 is that behaviors invoked from mod-morphs or tap dances also act this way, even though they involve a single key position [unless they are themselves triggered from a combo].)

[davidgamero]

Ah yup that's exactly it. Your explanation totally makes sense idk why I thought it would somehow know that all the keys on a combo were on one side and send that side the reset.

My thought process went something like:

• i want to add a reset button
• searches "reset" on zmk docs
• reads section about split kb
• i already use combos and decide to use a combo on the peripheral side to reset it
• discover through trial and error only the central side resets
• later find out that was fine all along because i only have to flash the central side for keymap updates

Maybe it's too verbose, but a link about reset combos in the reset behavior section for split keyboards would be the earliest step to avoid this.

I recognize i probably should have read the combos page more clearly, but now it's hard to tell since Ive been rereading these a lot haha

[caksoylar]

Maybe it's too verbose, but a link about reset combos in the reset behavior section for split keyboards would be the earliest step to avoid this.

I guess a warning about combos could be useful. Since there aren't any other source-specific behaviors at the moment it wouldn't lead to too much duplication across pages, which is what we'd ideally like to avoid.