shagi
/
qmk_firmare
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
qmk_firmare/keyboards/fingerpunch/FIRMWARE.md

8.0 KiB
Raw Permalink Blame History

Firmware

QMK repo: https://github.com/qmk/qmk_firmware
fingerpunch repo: https://github.com/sadekbaroudi/qmk_firmware

Branches

  • master (or vial in the vial repo) - stable, synced with qmk master (or vial), but adds the fingerpunch keyboards ( keyboards/fingerpunch/ directory )
  • develop_fingerpunch - relatively stable, synced with qmk master, but contains new fingerpunch specific changes only, no changes to qmk itself...
  • develop_qmk - synced with qmk develop, contains all the latest qmk changes only, along with the fingerpunch folder ( keyboards/fingerpunch/ directory )

branch management

Default firmware

Github Actions

The default firmware for all boards is built automatically for every keyboard with every commit. This is supported for both QMK and Vial.

You can access them by clicking any commit here: https://github.com/sadekbaroudi/qmk_firmware/actions
https://github.com/sadekbaroudi/vial-qmk/actions

You can download the zip file and install the appropriate hex or uf2 to test out your keyboard:

github-actions-01 github-actions-02 github-actions-03

Vial support

Vial is supported for most of the fingerpunch keyboards, and you can download the vial firmware as described here:
Github Actions

Building firmware

There are a couple of methods to build firmware. The traditional method and the fingerpunch build script.

To build your own firmware, the recommendation is to use the fingerpunch firmware builder, since it accounts for all the possible fingerpunch features.

fingerpunch build script

The script is available in the git repo:
/bin/fp_build.sh

In other words, you run it from the qmk root directory as follows:

$ bin/fp_build.sh -h

Usage: bin/fp_build.sh -k <keyboard> -m <keymap> -c <convert_to controller> -r -h

 -l list valid keyboards (optional, overrides all other options)
 -k keyboard directory (optional, default is all fingerpunch keyboards)
 -m keymap (optional, defaults to the 'default' keymap)
 -c add CONVERT_TO parameter for a controller (eg -c stemcell)
 -i (interactive mode, take feature selection user input to generate build command)
 -r (run the build command(s), defaults to outputting the build string)
 -h (show this dialog)

The interactive mode will help you configure based on your keyboard setup. For example:

$ bin/fp_build.sh -k ffkb/byomcu/v3 -m default -i -c stemcell -r
Running for keyboards/fingerpunch/ffkb/byomcu/v3
make fingerpunch/ffkb/byomcu/v3:default
Do you have a cirque? (yes/no): n
Do you have a trackball? (yes/no): y
No RGB, RGB light, RGB matrix? (0-2): 2
No rotary encoders, EC11, or EVQ? (0-2): 1

make fingerpunch/ffkb/byomcu/v3:default CIRQUE_ENABLE=no FP_TRACKBALL_ENABLE=yes RGB_MATRIX_ENABLE=yes FP_EC11=yes CONVERT_TO=stemcell
fp_build.sh: Running QMK Build....

Traditional QMK method

In the same way that you build any other keyboard, you can do the same for fingerpunch boards. The thing to consider is that there are options for each keyboard that you should be aware of.

For your keyboard, review the fp_build.json to see the possible options. For example:
/keyboards/fingerpunch/ffkb/byomcu/v3

Example command:
make fingerpunch/ffkb/byomcu/v3:default CIRQUE_ENABLE=no FP_TRACKBALL_ENABLE=yes RGB_MATRIX_ENABLE=yes FP_EC11=yes CONVERT_TO=stemcell

Anything that is in all caps can be set as a build option followed by =yes

For example, this is from keyboards/fingerpunch/ffkb/byomcu/v3/fp_build.json fp-build-json

STeMCell or other controllers

For other controllers, you can use the CONVERT_TO build parameter: https://github.com/qmk/qmk_firmware/blob/master/docs/feature_converters.md

So, for example, for the STeMCell, you can add -c stemcell if using the fingerpunch build script, or you can add CONVERT_TO=stemcell at the end of your build string if using the Traditional QMK build script

Also note that stemcell uses tinyuf2, so you'll want to use the .uf2 file instead of the .bin or .hex file as you would with other controllers

One time build

If using the Vial repository, in the code snippet below...

  • Replace qmk_firmware.git with vial-qmk.git
  • Replace master with vial

Starting with no repository, here's an example of building stock ffkb firmware with rgbmatrix and ec11 encoders:

# Cloning the repo
git clone git@github.com:sadekbaroudi/qmk_firmware.git
cd qmk_firmware
git submodule update --init --recursive
# Running the firmware build
make fingerpunch/ffkb_byomcu/v3:default CIRQUE_ENABLE=no FP_TRACKBALL_ENABLE=yes RGB_MATRIX_ENABLE=yes FP_EC11=yes CONVERT_TO=stemcell

# Build firmware will be .build/fingerpunch_ffkb_byomcu_rgbmatrix_ec11_default.hex
# Copy the hex file and use QMK toolbox to load it
# If using a uf2, copy the uf2 file somewhere where you can drag and drop it to flash your STeMcell

Managing fingerpunch code in your repository

If using the Vial repository, in the code snippet below...

  • Replace qmk_firmware.git with vial-qmk.git
  • Replace master with vial

Now, you may ask yourself the question: "But how do I organize and manage my code in there?"

My recommendation is to add my repo as a remote repository to yours. So, instead of cloning my repo, add it to yours using "git remote"

Note that you can do the below multiple times for different keyboards by replacing the branch name ffkb with whatever you like. You will not need to repeat the "git remote add" command once you have run it the first time.

# Add the fingerpunch repo as a remote repository
git remote add fingerpunch git@github.com:sadekbaroudi/qmk_firmware.git
git fetch fingerpunch

# Checkout the master branch as a branch that tracks your keyboard. Let's use ffkb in this example
git checkout -b ffkb fingerpunch/master
git submodule update --init --recursive

# add your keymap, code, etc into keyboards/fingerpunch/ffkb_byomcu/v3/keymaps/{your_keymap_dir}

# commit your changes
git commit -a -m "Your commit message"

# push the branch to your repo
git push origin ffkb

# If you ever want to update from the latest fingerpunch master branch in the future
git fetch fingerpunch
git merge fingerpunch/master
git push origin ffkb

Contributing

By contributing to the fingerpunch repository, all changes will sync to Vial If you want to contribute to Vial specific code, please do the following in the code snippets below

  • Replace qmk_firmware.git with vial-qmk.git
  • Replace develop_fingerpunch with vial

Note that I will only accept fingerpunch changes (in the keyboards/fingerpunch/ directory), which go into the develop_fingerpunch branch. If there are changes outside of that, they should be pull requests into qmk directly.

If you'd like to contribute, you can do the following:

# ...in your qmk cloned repository
# If you haven't already, create a remote of the fingerpunch repo
git remote add fingerpunch git@github.com:sadekbaroudi/qmk_firmware.git
git fetch fingerpunch

# Checkout a feature branch based on develop_fingerpunch
git checkout -b features/fingerpunch/YOUR_FEATURE_BRANCH_NAME fingerpunch/develop_fingerpunch

# Make your changes

# Commit your changes
git commit -a -m "YOUR COMMIT MESSAGE"

# Push your changes to your fork
git push origin features/fingerpunch/YOUR_FEATURE_BRANCH_NAME

# Submit your pull request on github (see below)

Once you have your branch in your fork, you can go to the pull requests page for my repo:

https://github.com/sadekbaroudi/qmk_firmware/compare/sadekbaroudi:develop_fingerpunch...Keychron:qmk_firmware:audio_out

Or for Vial

https://github.com/sadekbaroudi/vial-qmk/compare/sadekbaroudi:vial

You'll need to change the head repository and branch to yours (circled in green below)

Please fill in a sensible description to explain what you are changing and why!

contributing-pr

Submit the pull request and notify me to review.