Getting started compiling firmware - documentation duplicate?

Programming
1

I was getting confused trying to get the firmware to build, and I couldn’t find the instructions I used successfully the last time. I tracked down the source of my confusion: there are two/three related-but-different instructions for getting a build running locally. There’s the readme in

  1. https://github.com/keyboardio/Model01-Firmware which points to
  2. the wiki, or
  3. the forums, but actually
  4. https://github.com/keyboardio/Kaleidoscope is the instructions that actually worked for me, but I don’t think they’re linked to from any of the other places.

Is one of those the Best? It would be good to remove duplication – I’m willing to do PRs to remove duplicates in the docs, but I don’t know where to point to. @Jennigma this is your jam, right?

1 Like
2

What specifically in the Kaleidoscope docs worked for you? And what in the wiki didn’t work? If you were looking at the readme it points to the wiki in the first paragraph.

3

Sorry, I’ll clarify:
The wiki was fantastic for when I wanted to use the Arduino GUI and make small changes to existing layouts. Now I want to go all in and build from the command line; that’s where I’m finding confusing/duplicate documentation.

Following the instructions in the README here https://github.com/keyboardio/Kaleidoscope
and then cloning https://github.com/keyboardio/Model01-Firmware , I was able to make flash, which was my goal.

I think the difference there is that the Kaleidoscope repo readme specifies making a top-level kaleidoscope directory.

The relationship between the different repos, and where they have to be on disk is what I am finding confusing here. Possibly extra confused by a compilation error that might be transient or it might be my setup.

4

ah, cool. Yes, there is a “setting up a dev environment” set of documentation in the works, but last I checked they were not yet ready for prime time. I’ve been mostly absent for a couple weeks with some family stuff, so I’m not sure what the status of those is. :slight_smile: I expect things to settle down so I can give Keyboardio a reasonable time slice in the next week or so.

5

I’ve also been working on some documentation that would be helpful with this, but it also stalled out last week while I started writing plugins…

2 Likes
6

I created a stub overview page with what I know so far at Create new page · keyboardio/Kaleidoscope Wiki · GitHub . There are quite a few TODOs in that doc that point to exactly where I lack the necessary info. Respond to this thread and I’ll update the wiki, or feel free to edit the wiki directly.
Specific quesitons:

If you are using the Arduino GUI’s boards manager, stop. How?

You will also have a link from HOME/kaleidoscope/Arduino-Boards to $HOME/Documents/Arduino/hardware/keyboardio/avr Why?

Clone the Model01-Firmware somewhere Where?

Clone the Model01=Sketch somewhere Where?

7

@merlin @Jennigma feel free to overwrite my stub page :slight_smile:

8

I believe you can go into the boards manager and click “uninstall” on the keyboardio hardware definitions.

The important thing is that Arduino looks for hardware definitions in two places: One is their boards manager directory. The other is inside the ‘sketchbook’ directory. On OSX, that’s Documents/Arduino/. On linux, that’s just Arduino/

The path inside that is ~hardcoded to hardware/keyboardio/avr

Most people don’t like to have git checkouts over there, preferring instead to keep them encapsulated inside ~/git/ or something.

This is outdated. ‘Model01-Firmware’ is now included inside Arduino-Boards inside libraries/Model01-Firmware

Hm? This doesn’t feel right. Model01-Firmware is the sketch :slight_smile:

9

Yes, but if you’re going to be making your own changes, it’s better to have an independent clone of Model01-Firmware someplace else, because if you update the Arduino-Boards repository’s submodules, you don’t want the default firmware to check out something other than your own sketch.

@Benji: if you do have a separate firmware sketch (doesn’t have to be a clone of Model01-Firmware, but that’s the easiest way to do it), you can put it anywhere. You can even add third-party plugins as submodules of your own sketch, like this:

git submodule add <plugin-name> <repository-url>

Do that in the sketch directory (e.g. Model01-Firmware/), and the build system will find those plugin libraries.

10

I believe that if you have check out your own version, either from a different republic or a different branch of that repo, doing a submodule update will not clobber your work. That is a pretty standard part of my workflow

11

It won’t clobber your work, but if you keep the submodules in sync with Arduino-Boards, when you run git submodule --remote --init, it will check out whatever version of Model01-Firmware is registered in Arduino-Boards/.gitmodules, and whatever branch you had checked out with your own sketch will need to be checked out again before you build.

EDIT: to clarify, it will clobber your work, but only in the sense that after you update the submodules, you will have the “official” branch checked out, not your own (assuming you’re using git and checking in your own changes). If you have un-committed changes, those shouldn’t get overwritten, but I don’t recommend doing that.

12

I think it ought to be fairly common for people to make changes to their own sketch, and include third-party plugins, but to just use the latest Arduino-Boards and everything under it without changing anything there. That’s the use case I’m thinking of; someone who’s tracking their own changes in git, but doesn’t want to have to restore their branch every time there’s a change to any submodule in Arduino-Boards.

2 Likes
13

Hmm – would it be correct to add a step that says something like:

To modify the firmware and keep your own copy of it, fork theModel01-Firmware repo on github and check that out locally:

$ cd $HOME/kaleidoscope
$ git clone git@github.com:mygithubuname/Model01-Firmware.git mygithubuname-firmware
$ cd mygithubuname-firmware
$ make flash
edit edit edit edit
$ make flash

Modify your local copy to your heart’s content, and push your changes to github whenever you want.

14

You should only fork the repo if you want to publish (or publicly back up) your own copy. If you want to keep it private, and local to your own machine, just clone it.

15

Oh gosh, I always want a backup of my source code, all the time! I think these basic instructions should encourage that habit. My question was more, “is this a workable workflow that makes sense?”

I now know that it works, because, https://github.com/benshine/Model01-Firmware/blob/master/Model01-Firmware.ino#L10 works! I can finally retire my poor gist, which I only created because I couldn’t figure out how to get source control on a sketch I created from the arduino gui.

:grin::grin::grin::grin::grin: I can finally build and flash my sketch from the command line! Thanks eveybody!!!

2 Likes
16

It certainly does make sense; I’m just thinking that it’s not for everyone. There are people who don’t have (or want to have) a GitHub account, or who just store their stuff on some other server (e.g. GitLab), so I think that step should be left out of the instructions, or offered as an additional extra step, which can always be done after the fact.

You can clone the repo(s), make your own branch(es), make lots of changes, then create a GitHub account, fork whichever repositories you want, add those forks as remotes, and push changes to them — all in that order. So I think it’s best to give only the necessary steps first, since it’s not necessary to start over in order to start publishing (or backing up) your changes.

1 Like
17

Got it! I’ve modified the instructions to indicate this is optional: https://github.com/keyboardio/Kaleidoscope/wiki/Developer-Setup/_compare/433d66ca79407a1bff1b592f664b4b855ab7afc8...b9bce4062f33bf98717d963f923fac70aed59c87

18

I also see that you’ve got an extra copy of Kaleidoscope in your diagram; it’s included in Arduino-Boards, so you don’t need to have another copy at the same level as Model01-Firmware & Arduino-Boards.

1 Like
19

The way I’ve been thinking of it it is that while using version control is a good thing, making git usage a prerequisite for modifying your keyboard firmware sketch is…off-putting at best if you’re new to all of this.

That’s why, for simply modifying your own sketch, we push people toward using the Arduino Boards Manager and the automatic download and install. From there, they can open the Model01-Firmware sketch as an “Example” and Arduino will force them to save it locally.

I believe that to be the “correct” flow for a user who wants to create a custom sketch. If they want to mod the core, that’s when they should need to start touching git.

1 Like
20

Well, there are people who don’t want to mess with the core, but are more comfortable using the command line interface, rather than yet another unfamiliar GUI system. And for them, running git clone and git pull is much easier than getting the files some other way.

1 Like