Forking plugin repositories

Programming
1

I have looked at the code of a few plugins, and I want to fork one make a few changes.

But I don’t know arduino (or git honestly) well enough to know where to start. All I know is ‘make flash’ from the Model01-Firmware folder (or upload in the IDE when that fails).

Can you point to some docs or give simple instructions on how to change a plugin to my forked version.

I just forked: https://github.com/lldata/Kaleidoscope-OneShot

Do I need to check out my fork in some special directory for it to be picked up (and prefered over the one in my libraries folder?

Thanks!

2

The way I handle working with forks is I just make a branch on the repo in the libraries directory then set the upstream to be my forked repository.

Something like:

$ cd Arduino-Boards/library/Kaleidoscope-$whatever
$ git remote add myupstream git://github.com:myusername/Kaleidoscope-$whatever
$ git checkout -b adding-some-feature
$ git branch --set-upstream-to myupstream/adding-some-feature
2 Likes
3

Ever so slightly easier than that, if the branch you want to check out already exists in the fork repository:

$ cd Arduino-Boards/libraries/Kaleidoscope-${PLUGIN}/
$ git remote add ${REMOTE} ${FORK_URL}
$ git checkout -t ${REMOTE}/${BRANCH}
  • $REMOTE can be any name you want other than “origin”
  • $FORK_URL can be copied from GitHub’ “Clone or Download” button
  • $BRANCH is the name of the existing branch in the fork that you want

This will work as long as you don’t already have a branch with that name in your local repository. For example, if you want the master branch of the fork, it will fail because you already have a master branch (from the origin remote). In that case, you should use:

$ git checkout -t ${REMOTE}/${BRANCH} -b ${NEW_BRANCH_NAME}
1 Like
4

There’s one more thing you can do, that should also work. In your Model01-Firmware directory, clone the plugin repository fork that you want:

$ cd Model01-Firmware/
$ git clone https://github.com/<user>/<plugin>

If you need to, check out a branch from the fork:

$ cd <plugin>
$ git checkout <branch>

…then build the firmware:

$ cd ..  # i.e. Model01-Firmware/
$ make   # or `make flash`

The copy of the library in your sketch (Model01-Firmware/Kaleidoscope-<plugin_name>) will override the one in Arduino-Boards/libraries/. I don’t know for sure if it overrides libraries installed via the Arduino app’s package manager, though.

2 Likes
5

Thanks a lot! I’ll try it out.

6

Dunno where to ask this, since it is a mixture of problems…

I tried cloning @jdlien jdlien/Kaleidoscope-LEDEffect-FunctionalColor into my Model01-Firmware folder as described by @merlin above.

I had to change #include <Kaleidoscope-LEDEffect-FunctionalColor.h>
to #include "Kaleidoscope-LEDEffect-FunctionalColor.h" but after that it compiles (with a bunch of warnings) with make flash on my Mac.

But make flash stopped working a while ago. It can’t find the serial port.
So I use Arduino to upload to the keyboard. Annoying, but it works. Or worked…

The Arduino IDE can’t compile my layout. So now I have two broken tools. One that can compile, but not upload. And one that can’t upload, because it can’t compile. :’(

Sorry about all the n00b questions. :blush:

7

Next you’ll probably ask which error messages I get, so here goes:
make flash:

Press ENTER when ready…

Couldn’t autodetect the keyboard’s serial port.
If you see this message and your keyboard is connected to your computer,
it probably means that our serial port detection logic is buggy or incomplete.

Arduino IDE:

Arduino: 1.8.5 (Mac OS X), Board: “Keyboardio Model 01”

/Users/lasse/Documents/Arduino/Model01-Firmware/Model01-Firmware.ino:77:52: fatal error: Kaleidoscope-LEDEffect-FunctionalColor.h: No such file or directory
#include “Kaleidoscope-LEDEffect-FunctionalColor.h”
^
compilation terminated.
Multiple libraries were found for “HID.h”
Used: /Users/lasse/Documents/Arduino/hardware/keyboardio/avr/libraries/HID
Not used: /Applications/Arduino.app/Contents/Java/hardware/arduino/avr/libraries/HID
exit status 1
Error compiling for board Keyboardio Model 01.

This report would have more information with
“Show verbose output during compilation”
option enabled in File → Preferences.

8

Have you updated to the latest (GitHub) version of Kaleidoscope? A couple of weeks ago, there was a change to the serial port detection code for macOS: https://github.com/keyboardio/Kaleidoscope/pull/282

9

Hi @lasse, are you sure that you’ve got the plugin in the right directory? I found it quite difficult to dig up the right directory as there are some situations, depending on how you install everything, where you might have a couple different library directories.

At any rate, it’s cool that you’re interested in FunctionalColor, which is very new. What modifications did you want to make to it? I’m interested in discovering how people want to use it and making it better, so I’m open to having a discussion about making some changes to accommodate your needs.

If you make changes that you think would be generally useful, feel free to make a pull request and I’ll check it out!

10

Thanks for all the help and patience @merlin. I think my environment is a bit messed up. I get warnings that I have libraries installed in two different locations. I’ll see if I can fix it or scratch it and start over.

@jdlien I just want something a bit more visible when I change to the function layer. It is not really that important. My initial idea is to color the arrow and mouse keys blue. It looks like your plugin is a perfect match for that use case :slight_smile: But I’ll make sure to return if I have any feedback. Thank you for putting in the effort!

1 Like
11

Yeah, it sounds like FunctionalColors should work well as is for that. One thing you can’t really do yet is to color individual keys… but that could be added. It’s just tedious work and I’m a bit worried it’d take a lot more memory… But I could have a variable for every single key and make things like arrow keys groups and stuff, if say, you wanted all arrow keys blue but the up arrow a different color.

12

That’s what I did. I had to purge the libraries installed via the Arduino IDE, because (If I recall correctly) they always were searched before the ones from checked out from GitHub.