From a3a8da28a86cbd00fe60343308f8430e9f3dd871 Mon Sep 17 00:00:00 2001 From: ReFil <31960031+ReFil@users.noreply.github.com> Date: Thu, 14 Sep 2023 14:25:58 +0100 Subject: [PATCH 1/2] Minor cleanup, change date format, add beta testing --- CHANGELOG.md | 102 ++++++++++++++++++++++++++------------------------- README.md | 34 ++++++++++++----- UPGRADE.md | 4 +- 3 files changed, 79 insertions(+), 61 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7cda150018..27f5cfc8f5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,112 +4,116 @@ Here's all notable changes and commits to both the configuration repo and the ba Many thanks to all those who have submitted issues and pull requests to make this firmware better! ## Config repo -28/7/2023 - Add a section in README explaining how to resolve connectivity issues after updating [#197](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/197) +10/2/2023 - Further documentation refinements, add section on beta testing, document BLE privacy [#241](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/241) -### 6/7/2023 - V3.0 - Major refactor to board definition to match the upstream PR and comply with ZMK pre-commit requirements, Final changes to key matrix in hope of avoiding any future git conflicts, switch to zephyr Pinctrl API, Update the settings-reset file, switch to the zephyr 3.2 branch of the base ZMK repo, add instructions to resolve the conflicts upon updating (adv360-z3.2) +9/7/2023 - Add a changelog to the documentation, document key positions for combos and improve misc other areas of documentation [#221](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/221) [#222](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/222) -7/4/2023 - README improvements, adding instructions on flashing, links to the GUI editor and formatting cleanup [#128](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/128) +7/28/2023 - Add a section in README explaining how to resolve connectivity issues after updating [#197](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/197) -4/3/2023 - Add extra keys into matrix that point to nowhere, fixes spurious keypress issues when using USB3.1 cables [#114](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/114) [#116](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/116) +### 7/6/2023 - V3.0 - Major refactor to board definition to match the upstream PR and comply with ZMK pre-commit requirements, Final changes to key matrix in hope of avoiding any future git conflicts, switch to zephyr Pinctrl API, Update the settings-reset file, switch to the zephyr 3.2 branch of the base ZMK repo, add instructions to resolve the conflicts upon updating (adv360-z3.2) +4/7/2023 - README improvements, adding instructions on flashing, links to the GUI editor and formatting cleanup [#128](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/128) -14/2/2023 - Disable ZMK logging by default to improve power consumption [#101](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/101) +3/4/2023 - Add extra keys into matrix that point to nowhere, fixes spurious keypress issues when using USB3.1 cables [#114](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/114) [#116](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/116) -25/1/2023 - Fix automatic OS detection to build properly when using the local builder on OS-X [#91](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/91) -16/1/2023 - Change formatting of keymap GUI files [#92](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/92) +2/14/2023 - Disable ZMK logging by default to improve power consumption [#101](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/101) -21/11/2022 - Rewrite README to take into account new makefile structure [#57](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/57) +1/25/2023 - Fix automatic OS detection to build properly when using the local builder on OS-X [#91](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/91) -18/11/2022 - Add SELinux support to the makefile build sequence [#58](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/58) +1/16/2023 - Change formatting of keymap GUI files [#92](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/92) -14/11/2022 - Makefile cleanup to delete docker images on clean and run more seamlessly [#42](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/42) +11/21/2022 - Rewrite README to take into account new makefile structure [#57](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/57) -30/10/2022 - Improve make clean so that it doesn't error when run without build firmware [#36](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/36) +11/18/2022 - Add SELinux support to the makefile build sequence [#58](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/58) -26/10/2022 - Add support for building through podman as opposed to docker [#10](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/10) +11/14/2022 - Makefile cleanup to delete docker images on clean and run more seamlessly [#42](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/42) -23/10/2022 - Update GitHub actions to avoid deprecated actions [#33](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/33) +10/30/2022 - Improve make clean so that it doesn't error when run without build firmware [#36](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/36) -23/10/2022 - Add a makefile to reuse the docker image every time [#29](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/29) +10/26/2022 - Add support for building through podman as opposed to docker [#10](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/10) -20/10/2022 - Update settings reset file to fully erase peripheral data from the central +10/23/2022 - Update GitHub actions to avoid deprecated actions [#33](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/33) -12/10/2022 - Fix local docker build after V2.0 update [#25](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/25) +10/23/2022 - Add a makefile to reuse the docker image every time [#29](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/29) -11/10/2022 - Set manufacturer information over BLE [#28](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/28) +10/20/2022 - Update settings reset file to fully erase peripheral data from the central -9/10/2022 - Cleanup of keymap [#24](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/) +10/12/2022 - Fix local docker build after V2.0 update [#25](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/25) -7/10/2022 - Add USB VID, PID and Manufacturer information to config files +10/11/2022 - Set manufacturer information over BLE [#28](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/28) -26/9/2022 - Revise local building script to avoid errors after V2.0 update +10/9/2022 - Cleanup of keymap [#24](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/) -### 17/9/2022 - V2.0 - Changes to support Zephyr 3 (adv360-z3) +10/7/2022 - Add USB VID, PID and Manufacturer information to config files -9/8/2022 - Remove extraneous keys from the GUI [#5](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/5) +9/26/2022 - Revise local building script to avoid errors after V2.0 update -13/6/2022 - Change default keymap, add default macros +### 9/17/2022 - V2.0 - Changes to support Zephyr 3 (adv360-z3) -23/5/2022 - Add local building with Docker, Add a README [#4](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/4) +8/9/2022 - Remove extraneous keys from the GUI [#5](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/5) -6/5/2022 - Change LFCLK accuracy for improved reliability [#2](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/2) +6/13/2022 - Change default keymap, add default macros + +5/23/2022 - Add local building with Docker, Add a README [#4](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/4) + +5/6/2022 - Change LFCLK accuracy for improved reliability [#2](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/2) ### 3/3/2022 - V1.0 - Initial config repo release [#1](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/1) (adv360-beta) -1/3/2022 - Initial publication of licence +3/1/2022 - Initial publication of licence ## Base ZMK -There have beeen 3 branches of ZMK used for the 360 Pro so far. +There have beeen 3 mainline branches of ZMK used for the 360 Pro so far. Beta branches are not changelogged as they are subject to frequent changes and tweaks. | Branch | Date From | Date To | Config Branch | | -------- | ------- |-------|-----| -| [adv360-beta](https://github.com/ReFil/zmk/tree/adv360-beta) | 1/3/2022 | 17/9/2022 | main (since deleted) | -| [adv360-z3](https://github.com/ReFil/zmk/tree/adv360-z3) | 17/9/2022 | 6/7/2023 | [V2.0](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/tree/V2.0) | -| [adv360-z3.2](https://github.com/ReFil/zmk/tree/adv360-z3.2) | 6/7/2023 | To date | [V3.0](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/tree/V3.0) | +| [adv360-beta](https://github.com/ReFil/zmk/tree/adv360-beta) | 3/1/2022 | 9/17/2022 | V1.0 (since deleted) | +| [adv360-z3](https://github.com/ReFil/zmk/tree/adv360-z3) | 9/17/2022 | 7/6/2023 | [V2.0](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/tree/V2.0) | +| [adv360-z3.2](https://github.com/ReFil/zmk/tree/adv360-z3.2) | 7/6/2023 | To date | [V3.0](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/tree/V3.0) | ### adv360-z3.2 -31/7/2023 - Fix broken CI builds [#6](https://github.com/ReFil/zmk/pull/6) +7/31/2023 - Fix broken CI builds [#6](https://github.com/ReFil/zmk/pull/6) -30/5/2023 - Update RGB indicators code to match latest changes from pull requests +5/30/2023 - Update RGB indicators code to match latest changes from pull requests -30/5/2023 - Merge latest HID indicators pull request alongside dependencies [#999](https://github.com/zmkfirmware/zmk/pull/999) [#1803](https://github.com/zmkfirmware/zmk/pull/1803) +5/30/2023 - Merge latest HID indicators pull request alongside dependencies [#999](https://github.com/zmkfirmware/zmk/pull/999) [#1803](https://github.com/zmkfirmware/zmk/pull/1803) -30/5/2023 - Disable BLE battery reporting due to unreliability +5/30/2023 - Disable BLE battery reporting due to unreliability -30/5/2023 - Various fixes to allow compilation on zephyr 3.2 +5/30/2023 - Various fixes to allow compilation on zephyr 3.2 -29/5/2023 - Merge latest upstream ZMK (Commit b276a3b) +5/29/2023 - Merge latest upstream ZMK (Commit b276a3b) ### adv360-z3 -27/3/2023 - Fix power on behaviour for RGB lighting +3/27/2023 - Fix power on behaviour for RGB lighting -24/2/2023 - Fix indication leds for BLE profile 5 +2/24/2023 - Fix indication leds for BLE profile 5 -12/1/2023 - Merge latest upstream ZMK (Commit a82a0ec) +1/12/2023 - Merge latest upstream ZMK (Commit a82a0ec) -12/1/2023 - Fix pre-commit formatting +1/12/2023 - Fix pre-commit formatting -12/1/2023 - Fix a compile time warning by defining struct in header [#4](https://github.com/ReFil/zmk/pull/4) +1/12/2023 - Fix a compile time warning by defining struct in header [#4](https://github.com/ReFil/zmk/pull/4) -25/11/2022 - Add extra BLE characteristic to fix HID light reporting on MacOS +11/25/2022 - Add extra BLE characteristic to fix HID light reporting on MacOS -19/10/2022 - Add BLE whitelist scanning to improve performance in environments with many BLE devices +10/19/2022 - Add BLE whitelist scanning to improve performance in environments with many BLE devices -19/10/2022 - Merge latest upstream ZMK (Commit c9eb631) +10/19/2022 - Merge latest upstream ZMK (Commit c9eb631) -19/10/2022 - Fix initial power on lighting +10/19/2022 - Fix initial power on lighting -2/10/2022 - Add ability to scale RGB and backlight brightness to improve battery life +10/2/2022 - Add ability to scale RGB and backlight brightness to improve battery life -13/9/2022 - Add custom lighting functionality on top of base ZMK +9/13/2022 - Add custom lighting functionality on top of base ZMK -12/9/2022 - Merge HID indicators pull request [#999](https://github.com/zmkfirmware/zmk/pull/999) atop of base ZMK +9/12/2022 - Merge HID indicators pull request [#999](https://github.com/zmkfirmware/zmk/pull/999) atop of base ZMK -11/9/2022 - Diverge from base ZMK (Commit 6124d25) +9/11/2022 - Diverge from base ZMK (Commit 6124d25) ### adv360-beta diff --git a/README.md b/README.md index c0c3885d01..a732332897 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ -# ADV360-PRO-ZMK +# Kinesis Advantage 360 Pro ZMK Config ## Modifying the keymap [The ZMK documentation](https://zmk.dev/docs) covers both basic and advanced functionality and has a table of OS compatibility for keycodes. Please note that the RGB Underglow, Backlight and Power Management sections are not relevant to the Advantage 360 Pro's custom ZMK fork. For more information see [this note](#note) -There is a GUI for editing the keymap. It is available at https://kinesiscorporation.github.io/Adv360-Pro-GUI. This repository is also compatible with certain other web based ZMK keymap editors. +There is a web based GUI available for editing the keymap. It is available at https://kinesiscorporation.github.io/Adv360-Pro-GUI. This repository is also compatible with certain other web based ZMK keymap editors however they may have keycodes or behaviours that are not implemented on the 360 Pro and could cause unusual behaviour or build failures. Furthermore changes made on other keymap editors may not be compatible if one goes back to using the Kinesis GUI. -Certain ZMK features require knowing the exact key positions in the matrix. They can be found in both image and text format [here](assets/key-positions.md) +Certain ZMK features (e.g. combos) require knowing the exact key positions in the matrix. They can be found in both image and text format [here](assets/key-positions.md) ## Building the Firmware with GitHub Actions @@ -26,13 +26,13 @@ Certain ZMK features require knowing the exact key positions in the matrix. They #### Software -* Either Podman or Docker is required, Podman is preferred if both are present. +* Either Podman or Docker is required, Podman is chosen if both are installed. * Make is also required #### Windows specific * If compiling on Windows use WSL2 and Docker [Docker Setup Guide](https://docs.docker.com/desktop/windows/wsl/). -* Install make using `sudo apt-get install make`. +* Install make using `sudo apt-get install make` inside the WSL2 instance. * The repository can be cloned directly into the WSL2 instance or accessed through the C: mount point WSL provides by default (`/mnt/c/path-to-repo`). ### Build firmware @@ -42,7 +42,7 @@ Certain ZMK features require knowing the exact key positions in the matrix. They ### Cleanup -The built docker container and compiled firmware files can be deleted with `make clean`. This might be necessary if you updated your fork from V2.0 to V3.0 and are encountering build failures +The built docker container and compiled firmware files can be deleted with `make clean`. This might be necessary if you updated your fork from V2.0 to V3.0 and are encountering build failures. ## Flashing firmware @@ -50,7 +50,7 @@ Follow the programming instruction on page 8 of the [Quick Start Guide](https:// ### Overview -1. Extract the firmwares from the downloaded archive. +1. Extract the firmwares from the archive downloaded from the GitHub build job (If using the cloud builder) or the firmware folder (If building locally). 1. Connect the left side keyboard to USB. 1. Press Mod+macro1 to put the left side into bootloader mode; it should attach to your computer as a USB drive. 1. Copy `left.uf2` to the USB drive and it will disconnect. @@ -69,15 +69,26 @@ Follow the programming instruction on page 8 of the [Quick Start Guide](https:// If you are upgrading from V2 to V3, and if the flashing didn't work as expected (i.e. if you are unable to pair the keyboard via Bluetooth), then consider [resetting](https://kinesis-ergo.com/support/kb360pro/#firmware-updates) both halves of the keyboard to its native state. Make sure to use the `settings-reset.uf2` file from the V3 branch of this repository. After doing this, proceed with the flashing instructions above. +## Bluetooth LE Privacy +By default this firmware ships with BT Privacy enabled (To read more about BT privacy see [this article](https://novelbits.io/how-to-protect-the-privacy-of-your-bluetooth-low-energy-device/)). This was done based off feedback from MacOS users as some Macs and all iOS devices use resolvable private addresses that they cycle between (the Apple documentation can be found [here](https://developer.apple.com/accessories/Accessory-Design-Guidelines.pdf#page=194)), and when the host cycled to a new address the Advantage 360 Pro would need re-pairing. It can cause issues with some operating systems and hardware setups. To disable BT Privacy change `CONFIG_BT_PRIVACY=y` to `CONFIG_BT_PRIVACY=n` in [adv360_left_defconfig](config/boards/arm/adv360/adv360_left_defconfig#L52). Disabling this might necessitate re-pairing to the host. + ## Changelog -The changelog for both the config repo and the underlying ZMK fork that the config repo builds against can be found [here](CHANGELOG.md) +The changelog for both the config repo and the underlying ZMK fork that the config repo builds against can be found [here](CHANGELOG.md). + +## Beta testing + +The Advantage 360 Pro is always getting updates and refinements. If you are willing to beta test you can follow [this guide from ZMK](https://zmk.dev/docs/features/beta-testing#testing-features) on how to change where your config repo points to. The `west.yml` file that is mentioned is located in config/. [This link](config/west.yml) can take you to the file. Typically you will only need to change the `revision: ` to match the beta branch. The current beta branch is [adv360-z3.2-beta](https://github.com/ReFil/zmk/tree/adv360-z3.2-beta) which is compatible with V3.0 config repositories however users must [disable BT privacy](#bluetooth-le-privacy). + +Feedback on beta branches should be submitted as a GitHub issue on the base ZMK repository as opposed to this config repository + +In the event of a major update the beta branch may not be compatible with the current mainline version of the config repository. If this is the case it will be detailed here along with instructions on how to update. ## Note -By default this config repository references [a customised version of ZMK](https://github.com/ReFil/zmk/tree/adv360-z3.2) with Advantage 360 Pro specific functionality and changes over [base ZMK](https://github.com/zmkfirmware/zmk). The Kinesis fork is regularly updated to bring the latest updates and changes from base ZMK however will not always be completely up to date. +By default this config repository references [a customised version of ZMK](https://github.com/ReFil/zmk/tree/adv360-z3.2) with Advantage 360 Pro specific functionality and changes over [base ZMK](https://github.com/zmkfirmware/zmk). The Kinesis fork is regularly updated to bring the latest updates and changes from base ZMK however will not always be completely up to date, some features such as new keycodes will not be immediately available on the 360 Pro after they are implemented in base ZMK. -Whilst the Advantage 360 Pro is compatible with base ZMK some of the more advanced features will not work, and Kinesis cannot provide customer service for usage of base ZMK. Likewise the ZMK community cannot provide support for either the Kinesis keymap editor, nor any usage of the Kinesis custom fork. +Whilst the Advantage 360 Pro is compatible with base ZMK (The pull request to merge it can be seen [here](https://github.com/zmkfirmware/zmk/pull/1454) if you want to see how to implement it) some of the more advanced features (the indicator RGB leds) will not work, and Kinesis cannot provide customer service for usage of base ZMK. Likewise the ZMK community cannot provide support for either the Kinesis keymap editor, nor any usage of the Kinesis custom fork. ## Other support @@ -85,3 +96,6 @@ Further support resources can be found on Kinesis.com: * https://kinesis-ergo.com/support/kb360pro/#firmware-updates * https://kinesis-ergo.com/support/kb360pro/#manuals + +In the event of a hardware issue it may be necessary to open a support ticket directly with Kinesis as opposed to a GitHub issue in this repository. +* https://kinesis-ergo.com/support/kb360pro/#ticket \ No newline at end of file diff --git a/UPGRADE.md b/UPGRADE.md index 10d5ddf1a2..e3e7cbbb14 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -35,7 +35,7 @@ This assumes you already have [GitHub desktop](https://desktop.github.com/) down Open keymap.json, and for each layer remove the 8 highlighted &none behaviours including the quotes wrapping them, and the commas 4. Edit adv 360.keymap - Open adv360.keymap and remove the 8 highlighted &none behaviours in each later + Open adv360.keymap and remove the 8 highlighted &none behaviours in each layer 5. Commit your changes Returning to GitHub desktop you should see the changes you made in the bar on the left. Type an appropriate commit summary and click "Commit to *branch name*" @@ -50,7 +50,7 @@ This assumes you already have [GitHub desktop](https://desktop.github.com/) down 7. Resolve Conflicts - The conflict resolution window has powerful options to soresolve the merge conflict, you will want to clik on the down arrow next to "Open in *your text editor*" and click use the modified file from *your branch name*. In the case of this example it is called V2.0-beta. Using the file from upstream/V2.0 or upstream/V3.0 will result in none of your keymap changes being preserved. + The conflict resolution window has powerful options to soresolve the merge conflict, you will want to click on the down arrow next to "Open in *your text editor*" and click use the modified file from *your branch name*. In the case of this example it is called V2.0-beta. Using the file from upstream/V2.0 or upstream/V3.0 will result in none of your keymap changes being preserved. Do this for both files then you will be able to click the "Continue Merge" option ![The merge dialog showing a warning of conflicts](/assets/conflict.jpg) From d0949952251729667cdd68924e5f6997a9ff1280 Mon Sep 17 00:00:00 2001 From: ReFil <31960031+ReFil@users.noreply.github.com> Date: Mon, 9 Oct 2023 10:16:21 +0100 Subject: [PATCH 2/2] Update CHANGELOG.md --- CHANGELOG.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 27f5cfc8f5..8145ff1db7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,9 @@ Here's all notable changes and commits to both the configuration repo and the ba Many thanks to all those who have submitted issues and pull requests to make this firmware better! ## Config repo -10/2/2023 - Further documentation refinements, add section on beta testing, document BLE privacy [#241](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/241) +10/9/2023 - Further documentation refinements, add section on beta testing, document BLE privacy [#241](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/241) + +10/9/2023 - Change build actions to fix warnings from shellcheck [#242](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/242) 9/7/2023 - Add a changelog to the documentation, document key positions for combos and improve misc other areas of documentation [#221](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/221) [#222](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/222)