04.05.2024

So today we're going to be taking a look. at zmk firmware and how to actually. create a board from scratch I'm not. going to dive deep into all the features. of zmk because well it does a ton of. stuff you could look at the. documentation if you want to figure that. out but hopefully by the end of this. video you'll be able to create a board. set up your Matrix and start wiring it. up either handwired or PCB because it. pretty much is the same no matter what. that said I do have a video separate for. the actual Hardware that I'll link in. the top right so you can actually go. check that out if you haven't seen that. already but what's really cool about zmk. is that potentially you could do. everything on an iPad because it. leverages GitHub actions meaning you. pretty much push your code up to the. repo and it does everything else for you.

There it compiles it and then gives you. a firmware file so what we're going to. do is we're going to just hop into the. computer or just break this down step by. step and hopefully by the end you can. build a keyboard so the first we have to. do is create a repository where all our. code will be compiled and stored you can. do this by going to GitHub and then just. typing in a new repository name and if. you don't know how to get there you. basically just click the plus to click. new repository but we're going to name. this zmkconfig. and then Dash tube test tube test. replace it with whatever your board name. is but this is the overall naming. convention for zmk zmkconfig and then. Dash whatever your board is called so. we're going to do is Click create. repository and that's all we need in. here now we can jump into a terminal now.

All we have to do to get this code ready. to push up to GitHub is inside of this. terminal we're going to just paste this. command which is copy from the zmk. documentation but this will basically. run an executable that will give us a. little bit of a CLI to work with so what. we're going to do here is we're going to. just pick the two percent milk keyboard. This is basically just telling which. keyboard you want to select and then. this is the more important part here. because this is determining which MCU. you're using most of you if not all of. you will be using a nice Nano because. these are Wireless boards so we're going. to just pretty much click the six option. for the dice Nano V2. and then now we want to copy in the. stock key map just in case you want to. customize that you don't always have to. do this but I always do it just to have.

Some of the reference so just click yes. and then now you enter in your GitHub. username and then you have the GitHub. repo name which is what we just created. and now this part here is important to. pay attention to if I come over to. GitHub you'll see that I am actually. using a SSH key in order to authenticate. most of you probably will be using. default authentication unless you are in. the code world and have the proper. authentication set up so I'm just going. to copy this here and I'll paste that in. here and press enter and then now I'm. just going to click yes to continue and. this will do everything it needs to do. to set up this keyboard all I'm going to. do now and this is an important step to. not miss is I'm going to do CD into that. new folder we made zmkconfig tube test. hit enter and now we're into the working.

Directory and we can actually start. doing stuff with this code dot to open. the actual current working directory. inside of vs code I'm going to trust the. authors because I'm the author of it and. then we can see here that this is the. default structure for the actual project. we have the config folder and then we. have the build.yaml so we're going to. first jump into build yaml and we're. going to name this what we want our. board to be called I'm going to be. calling this just tube test so we'll. just name that and we can save this file. and then we can delete these two files. here the two percent milk.conf and the. two percent milk.keymap now we're going. to create four files instead of the. config folder but first we're going to. hop back over to a terminal to actually. make the directory now we're back in the.

Terminal and I just have a command. copied here but it's basically make. directory Dash p for path and we're. going to create config boards Shields. board name obviously board name we're. going to want to replace with tube test. or whatever board you are creating so. the first file that we're going to. create is kconfig.shield and basically. inside of this file you're just defining. what this keyboard actually is so you're. going to type in Shield underscore. whatever your keyboard is and I'll. uppercase here and then underneath here. you're going to just replace this with. whatever your keyboard name is you could. name this tube test if you wanted to do. a camel case but I'm just going to do. tube test for this example and as a side. note this actually will match whatever. you put in here so if you do do it this.

Way which I will do here and then I. change this to tube test the should. match because this is basically how zmk. is referencing your board but that's all. that belongs in this file we're going to. jump onto the next one now the next file. is. kconfig.defconfig and all this file does. is it pretty much handles configurations. for your board all we're going to be. doing is just naming the board in here. but there's other stuff you can do. according to documentation but if we. take a look here you can see if Shield. tube test and remember tube test is. whatever your board will be called you. want to replace that but we can also see. that this matches what we just created. inside a kconfig of config Shield tube. test so that's basically defining where. your keyboard exists now in here all. we're doing is we're running config zmk.

Keyboard name or setting it to tube test. this part here you can replace whatever. you want it's just important to note. that this can only be 16 characters or. less I believe it's a Bluetooth. limitation that if you go over that. stuff won't work right I've never tested. it so I don't actually know what happens. but just keep it 16 characters lesson. you should be fine now this next file is. called tube test.overlay and it's. important to keep in mind that this name. here should actually match what is. inside of our kconfig.com Shield right. here so this should match that and then. you're pretty much good to go there now. inside of this file is where we're going. to be storing either the Matrix or the. direct pin wiring definition so this. basically defines how your keyboard. connects to the controller we're going.

To be starting here with the actual. matrix definition because that's. probably what most people will be using. for this but then later in the video. we'll touch on the actual direct pin. wiring so we're just going to break this. file down line by line because I think. it's the simplest way to do this so the. include for the Matrix transform is. basically importing the macro for this. default transform which we'll talk about. in a few moments here. but what's important in this file is the. default K scan this is where the bulk of. the work is done inside of this file and. all this is doing is it's very simple. actually is you'll pretty much have this. for every single board this will be the. same pretty much regardless of what. board you're doing but this part down. here is where you're defining which pins. to use on your actual controller so you.

Can see here we have row gpios and this. is each referring to Pro micro 15 Pro. micro 14 and pro micro 16. you're also. seeing this over here which I'm not. going to explain because I don't really. understand it but I will pop up a. screenshot from the actual creator of. zmk who kind of explains what that's. doing it's basically biasing the pin so. it knows when they're on or not but. that's really simple in here it's not. really that complicated you can see for. our columns we're using four five and. six and that's basically it we're. defining a three by three Matrix right. now but right now how we're defining it. this is saying a three by three one by. one grid meaning you can't have say. three keys on one row two on the next. and three on the bottom it's always. going to expect that in the actual key. map that is where the the default.

Transform comes in so the default. transform and it's important to keep in. mind I mentioned this a second ago you. need this include in order to get this. working but the default transform. basically says that we want the key at. zero zero zero one zero two it's. defining how your key map is going to. actually look so if we didn't have a key. say on the second row here we could. actually delete this and this is what. your keyboard would look like so this is. basically just telling zmk that hey I. only have two keys on the second row I. don't need you to scan for three keys. and it will know that based on this. transform the other thing important in. this here is also just defined in the. rows and columns just so it knows what. your Matrix size is you don't need that. in the default K scan but you do need it. in the default transform now the last.

Thing on this file is this chosen. property and this is basically just. defining which ones to use so we're. using the default K scan defined right. here and then we're using the default. transform to find right here now this is. actually kind of cool because you could. actually Define multiple default. transforms or multiple transforms. depending on if say you're using a. keyboard where it has an option to do a. 3 by I3 layout or maybe a 3x2 layout or. different layout so you could have. multiple default transforms to have. different layouts for your actual board. what I've now done is replace the code. instead of tube test.overlay with the. wiring for a direct wired board and what. you're going to notice in here is that. we no longer have a default transform. the reason to not have a default. transform inside of this file is because.

Well for a direct wired board the. keyboard knows where each key is because. it's sending it directly to a pin on it. so it's not scanning a matrix left to. right if a key is missing at say Row 2. position 3 it's not going to look for it. there because it's not scanning a matrix. it just says hey there's no key at this. pin so simple as that but inside of this. file it's pretty much the same as before. where we're just choosing the default. case scan we're setting up the. compatible label the same as before but. the important part here is input gpios. we're basically just saying use each pin. on the board and that's basically it in. here and then the key map is just going. to scan those pins and that's it so. direct pin is a lot simpler than the. Matrix definitions but it limits you in. the sense that you need to have enough.

Pins for every key on your board the. final file I want to talk about is. tubetest.keymap or whatever your board. is called Dot keymap and this file here. is basically just the key map for your. board it's not too complicated so I'm. not going to like dive into everything. in here but what I do want to talk about. is the Bluetooth layer because these are. Bluetooth boards and you obviously need. Bluetooth functions so all I have here. is a secondary layer and it's important. to note that if you do have a secondary. layer in zmk that it should be. accessible so I do have an mo1 here so I. could switch that layer if you don't do. this zmk will air out when it goes to. compile but all I have in my Bluetooth. layer is three different profiles I. believe you can have up to five inside. of zmk so you can be connected to five.

Devices at once and then just switch. between them with these profiles and. then I have the Bluetooth clear function. to clear which one of these profiles and. make them accessible from the computer. that I'm trying to connect to and then I. just have a bootloader mode so I can. easily put in a bootloader very simple. stuff in here probably pretty. selfexplanatory so I think what we can. do now is hop into a terminal and get. this compiling here we are back inside. of our terminal and all we're going to. do inside of here is run git adda to. add all files we're going to do git. commit with some type of message so. we'll just name this compile. and then we're going to run git push and. we're going to hop over to GitHub to see. the board actually compiling so here we. are back on GitHub now and all we're. going to do is go to the actions tab and.

This is where all your code will be. compiled you can see that I have quite a. few failed in here and basically I. forgot to save a file so if you do. encounter errors make sure you've saved. all your files but we're just going to. go to the latest one when I actually did. save my files and we're going to just. view this here and you'll be able to see. as this is compiling in real time this. is obviously already built but you'll be. able to see all your like code and stuff. as it compiles and everything it's doing. any errors that occur will also show up. in here it'll give you a notification. that the build actually failed but we're. interested if we go back to the summary. is we're interested in the artifacts. here and we're going to just download. the firmware which will download a zip. file we will open this up and you will.

See in here that we have a uf2 file all. you have to do to get this onto your. controller is you put it into bootloader. mode plug it in and then drop this file. on it it will auto eject and. everything's done in there what's really. cool about zmk which I think I mentioned. in the beginning of this video is that. you can probably do this all from an. iPad because nothing thing is relying on. a local install of anything it's all. done remotely on GitHub and everything's. just recognized as like a disk so. there's no like special loaders to. actually access these keyboards unless. there's something I'm missing with like. the actual nice Nano when you plug it in. maybe it needs something additional but. it should just be detected as a disk and. you'll be able to just do this all from. any device really but with that said.

hopefully this video was clear and got. you in a good enough starting point to. actually build a keyboard from scratch. with zmk if you do have any questions. make sure to ask them down below and. I'll do my best to answer those also of. course my Discord and the official zmk. Discord are great resources for that if. you did like this like the video. subscribe do those things of course and. with that said I think I cover what I. want to cover today and I'll see you. next time