Beginner-friendly example code for each type of feature supported

[idesignstuff]

As one who is fairly new to custom/diy/mechanical keebs, and less than a beginner at python, some example code in the docs for the core features would be much appreciated.

Namely:

• [x] assigning simple and combo keycodes
• [x] layer do's and don'ts
• [ ] RGB control
• [x] macros

I'm excited & grateful to have found KMK, and hopeful that some maintainers will pick it back up.

[kdb424]

It's still in active development, and by no means abandoned. We require additional help, especially as there is little time for myself or klardotsh to commit code directly, but many members are actively pushing code, and getting merged into mainline. RGB control should be handled completely in the RGB docs here https://github.com/KMKfw/kmk_firmware/blob/master/docs/rgb.md and what you call "macros" should be covered here. https://github.com/KMKfw/kmk_firmware/blob/master/docs/sequences.md

[idesignstuff]

Thanks! It's really encouraging that you are actively working on kmk. I'm grateful for your effort!

What I meant with my issue was that, while RGB may be completely described, how to call things isn't spelled out for beginners, even in the 'getting started' section.

Thanks for the links! I'll read them and see how far I get.

Christian

On Tue, Feb 22, 2022, 6:03 PM Kyle Brown @.***> wrote:

It's still in active development, and by no means abandoned. We require additional help, especially as there is little time for myself or klardotsh to commit code directly, but many members are actively pushing code, and getting merged into mainline. RGB control should be handled completely in the RGB docs here https://github.com/KMKfw/kmk_firmware/blob/master/docs/rgb.md and what you call "macros" should be covered here. https://github.com/KMKfw/kmk_firmware/blob/master/docs/sequences.md

— Reply to this email directly, view it on GitHub https://github.com/KMKfw/kmk_firmware/issues/336#issuecomment-1048326350, or unsubscribe https://github.com/notifications/unsubscribe-auth/AEAGGGPKE3TR2Y2G27UBUVLU4QP3VANCNFSM5PCXSRVQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

You are receiving this because you authored the thread.Message ID: @.***>

[Tonasz]

What do you mean by "completely described but things isn't spelled out for beginners"? I'm genuinely curious, because RGB has one of the best doc among other undocumented stuff - it has:

• code snippet adding extension in Enabling the extension section
• keycodes and configuration variables listed
• public interface functions described for advanced modding and fiddling
• Troubleshooting section with most common issues

If you're looking for "complete examples" there is whole folder of configuration which can be copied to board and run right away - https://github.com/KMKfw/kmk_firmware/tree/master/boards - maybe it's not featured enough?

[idesignstuff]

Tonasz, wow!

Thanks for the tip about the running configs in the boards folder!

I'm a beginner at writing code & custom keebs. Since I started with a handwired custom board, it never occurred to me to look there. I assumed the boards folder would be only matrix and pin configs.

And, yes the RGB section of the docs really spells out the features and functions available, but NOT how to roll those into other commands (for instance: press a layer switch key = switch layers AND change color of the RGB).

Christian

On Thu, Feb 24, 2022, 12:09 AM Tonasz @.***> wrote:

What do you mean by "completely described but things isn't spelled out for beginners"? I'm genuinely curious, because RGB has one of the best doc among other undocumented stuff - it has:

• code snippet adding extension in Enabling the extension section
• keycodes and configuration variables listed
• public interface functions described for advanced modding and fiddling
• Troubleshooting section with most common issues

If you're looking for "complete examples" there is whole folder of configuration which can be copied to board and run right away - https://github.com/KMKfw/kmk_firmware/tree/master/boards - maybe it's not featured enough?

— Reply to this email directly, view it on GitHub https://github.com/KMKfw/kmk_firmware/issues/336#issuecomment-1049526100, or unsubscribe https://github.com/notifications/unsubscribe-auth/AEAGGGMXMIQ5H2O3VDJJN2TU4XDQ3ANCNFSM5PCXSRVQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

You are receiving this because you authored the thread.Message ID: @.***>

[idesignstuff]

So, I've had a few sessions to try some of this stuff out. It appears [from the docs](https://github.com/KMKfw/kmk_firmware/blob/master/docs/sequences.md#:~:text=triggering%20side%20effects%20(think%20lighting%2C) that sequences are intended to do macros.

I want a keypress to:

• toggle to a different layer
• change the neopixel colors/mode/whatever
• print to serial so I have feedback while I'm tweaking

So I made this:

`

macros

STD = simple_key_sequence( ( KC.DF(LYR_STD), # Set layer to Standard print('Stndard Layer'), #keyboard.pixels.set_hsv_fill(0, 100, 255) ) ) TMS = simple_key_sequence( ( KC.DF(LYR_TMS), # Set layer to Teams print('Teams Layer'), #keyboard.pixels.set_hsv_fill(0, 100, 255) ) ) PS = simple_key_sequence( ( KC.DF(LYR_PS), # Set layer to Teams print('Photochop Layer'), #keyboard.pixels.set_hsv_fill(0, 100, 255) ) ) WIN = simple_key_sequence( ( KC.DF(LYR_WIN), # Set layer to Teams print('Windows Layer'), #keyboard.pixels.set_hsv_fill(0, 100, 255) ) ) `

Then I want to call each one of these in a tapdance, like this:

LTOGL = KC.TD( STD, TMS,# KC.DF(LYR_TMS), PS,# KC.DF(LYR_PS), WIN,# KC.DF(LYR_WIN), )

It's not behaving like I expect, but that's not surprising, as I have no idea what I'm doing.

When I boot it up, the serial console says this:

` Code stopped by auto-reload. soft reboot

Auto-reload is on. Simply save files over USB to run them or enter REPL to disable. code.py output: Starting macropad Standard Layer Teams Layer Photochop Layer Windows Layer `

[kdb424]

I'd recommend checking out the matrix/discord chats. They are both bridged with a bot, so you are free to choose your client, and everyone is in one place. Debugging will be easier there as we can get more viability to your issues, and get faster responses.

[LukeDRussell]

I'm finding there are large gaps in assumed knowledge throughout the documentation. I spent hours to get a single KC.A sending from a Nice!Nano with 1 switch plugged in. I have qualifications in electronics and some skill with Python, I imagine it would take a lot longer for complete newbies.

I will have a go at a PR to improve the Getting Started Guide with some of my findings.

[idesignstuff]

We beginners would really appreciate that! I'm getting somewhere, but it's slow going.

Christian

On Sat, Mar 12, 2022, 6:18 PM Luke D Russell @.***> wrote:

I'm finding there are large gaps in assumed knowledge throughout the documentation. I spent hours to get a single KC.A sending from a Nice!Nano with 1 switch plugged in. I have qualifications in electronics and some skill with Python, I imagine it would take a lot longer for complete newbies.

I will have a go at a PR to improve the Getting Started Guide with some of my findings.

— Reply to this email directly, view it on GitHub https://github.com/KMKfw/kmk_firmware/issues/336#issuecomment-1065990432, or unsubscribe https://github.com/notifications/unsubscribe-auth/AEAGGGO6KFR7C2FDL5WUY4TU7UX3ZANCNFSM5PCXSRVQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

You are receiving this because you authored the thread.Message ID: @.***>

[HBBisenieks]

FWIW, #350 and #341 have addressed some of this. @idesignstuff want to check those tasks off?

[idesignstuff]

@HBBisenieks Thanks for pointing those out. I've checked off the ones that I think were updated. Looks like RGB docs still show outdated info re: [anything].pixels.[anything]

I'd fix it myself if I understood it well enough to.

[Tonasz]

As I was told on matrix, keyboard.pixels.smth is the left over from times when modules where not yet implemented and RGB was not an extension, so it was accessible as from keyboard object. To properly solve that, we need to first solve issue #360.

For now, we could maybe advice using the object handler of RGB, what I mean is below example (but probably too long for docs):

rgb_ext = RGB(
    pixel_pin=keyboard.rgb_pixel_pin,
    num_pixels=10,
)
keyboard.extensions.append(rgb_ext)

def foo_test(key, keyboard, *args):
    print('Lorem ipsum')
    rgb_ext.set_rgb_fill((0, 255, 0))

FOO = KC.Q.clone().after_press_handler(foo_test)

[idesignstuff]

but probably too long for docs

Disagree. If it's actually solving a problem (helping the user understand how to use the tool) then it isn't too long for docs.

IMHO

[HBBisenieks]

I'm with @idesignstuff on this; while docs shouldn't be overly-wordy (lol @ past me on that), their whole purpose is to elucidate features for newbies.

[HBBisenieks]

@idesignstuff btw, mind taking a peek at #362? i took a stab at documentation-documentation, but it could probably stand to be fleshed out

[kdb424]

I believe that docs can be both wordy, and short and concise. It's a matter of making both available. The concise direct ones, and maybe at the bottom or linked, the long version for those that need more. You don't want to get in the way of people that know what they are doing, but also don't want to leave out those that don't.

[HBBisenieks]

I like that; writing in a TL;DR type section at the bottom of docs and/or a fully-commented working firmware example similar to what was suggested for the layer docs

next time I have some documentation-time on my hands, I'll probably start writing something like that up, maybe starting with sequences.md since I know my way around that one decently-well and it's one of the places that I think a lot of folks will be looking for example code

[LukeDRussell]

I'm not quite done with re-drafting the Getting Started to be more suitable for complete newbies. I've redone the first few headings though, so you can get an idea. You can see my progress here on my fork. Let us know @idesignstuff if this level of explanation would be more helpful for you to get started.

@HBBisenieks I was hoping the ToC could be a basic TLDR for those that already have some of the requisite skills and knowledge.

@kdb424 I've made an opinionated recommendation to use "Mu" as editor, could you let me know your thoughts on that point? If your not comfortable I can change it to be less recommendation, more endorsement.

[kdb424]

@LukeDRussell I have no opinion as I use picocom on Mac/Linux and don't know anything about Windows. If that's what you think is best on that side, and it's Adafruit supported (it is), then I guess it's good.

[idesignstuff]

Luke, that's a great cleanup, with a beginner audience in mind. As for Mu, I think it's a fine editor for circuitpython, but rather than saying "adafruit endorsers this, and we echo that" I think you could just say "adafruit recommends Mu."

FWIW, I've been using:

https://urfdvw.github.io/CircuitPython-online-IDE/

And it just works in a chrome browser with no installation at all.

Thank you for taking the effort and time to write to us with the readme.md!

Christian

On Wed, Mar 16, 2022, 9:32 PM Kyle Brown @.***> wrote:

@LukeDRussell https://github.com/LukeDRussell I have no opinion as I use picocom on Mac/Linux and don't know anything about Windows. If that's what you think is best on that side, and it's Adafruit supported (it is), then I guess it's good.

— Reply to this email directly, view it on GitHub https://github.com/KMKfw/kmk_firmware/issues/336#issuecomment-1069914640, or unsubscribe https://github.com/notifications/unsubscribe-auth/AEAGGGM24GHYV2IORU7QIVDVAKKUJANCNFSM5PCXSRVQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

You are receiving this because you were mentioned.Message ID: @.***>

[midicdj1000]

HI, I would very much like to see a dual scanner setup working. I am using a pico to use old retro computer keyboards via USB for emulators and some have keys that are not on the matrix. One example is the Atari XL and XE, they have 4 keys are are shorted to ground so just have 4 basic inputs. I looked at the dual scanner and can see it's supported, but as I am still learning all of this I was not sure how to use it.

[ahemberger]

Hi @idesignstuff, did you happen to get your desired code working?:

- toggle to a different layer
- change the neopixel colors/mode/whatever
- print to serial so I have feedback while I'm tweaking

? I'm trying to figure out how to do the same. So far I've been told to read the code to try to learn this, but the lack of comments and docs make this a little hard.

I see mention of the various plugs one can hook into the matrix scan of the keyboard (e.g. after_matrix_scan(), after_hid_send()), but can't find any code showing examples of how to detect a keypress and react to it meaningfully in these functions.

[idesignstuff]

I managed to get it to change all the LED colors on command, and play some canned animations, but not the desired state, where I could change individual colors based on a key input to show modes.

I decided to table it and hope the docs matured a bit before I tried again.

Then I built a keebio quefrency and it does all the things this macropad was doing, using qmk/via for config.

Christian

On Tue, Sep 20, 2022, 7:49 PM Allen Hemberger @.***> wrote:

Hi @idesignstuff https://github.com/idesignstuff, did you happen to get your desired code working?:

• toggle to a different layer
• change the neopixel colors/mode/whatever
• print to serial so I have feedback while I'm tweaking

? I'm trying to figure out how to do the same. So far I've been told to read the code to try to learn this, but the lack of comments and docs make this a little hard.

I see mention of the various plugs one can hook into the matrix scan of the keyboard (e.g. after_matrix_scan(), after_hid_send()), but can't find any code showing examples of how to detect a keypress and react to it meaningfully in these functions.

— Reply to this email directly, view it on GitHub https://github.com/KMKfw/kmk_firmware/issues/336#issuecomment-1253061464, or unsubscribe https://github.com/notifications/unsubscribe-auth/AEAGGGNPVN35XON2JEKR6WTV7JLQBANCNFSM5PCXSRVQ . You are receiving this because you were mentioned.Message ID: @.***>

[idesignstuff]

I'm not following closely anymore, so it seems unfair to hold this open.