v3

CHANGELOG.md

@@ -0,0 +1,116 @@
+# Changelog
+Here's all notable changes and commits to both the configuration repo and the base ZMK that the config repo builds against. 
+
+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)
+
+### 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)
+
+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)
+
+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)
+
+
+14/2/2023 - Disable ZMK logging by default to improve power consumption [#101](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/101)
+
+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)
+
+21/11/2022 - Rewrite README to take into account new makefile structure [#57](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/57)
+
+18/11/2022 - Add SELinux support to the makefile build sequence [#58](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/58)
+
+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)
+
+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)
+
+26/10/2022 - Add support for building through podman as opposed to docker [#10](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/10)
+
+23/10/2022 - Update GitHub actions to avoid deprecated actions [#33](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/33)
+
+23/10/2022 - Add a makefile to reuse the docker image every time [#29](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/29)
+
+20/10/2022 - Update settings reset file to fully erase peripheral data from the central
+
+12/10/2022 - Fix local docker build after V2.0 update [#25](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/25)
+
+11/10/2022 - Set manufacturer information over BLE [#28](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/28)
+
+9/10/2022 - Cleanup of keymap [#24](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/)
+
+7/10/2022 - Add USB VID, PID and Manufacturer information to config files
+
+26/9/2022 - Revise local building script to avoid errors after V2.0 update
+
+### 17/9/2022 - V2.0 - Changes to support Zephyr 3 (adv360-z3)
+
+9/8/2022 - Remove extraneous keys from the GUI [#5](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/5)
+
+13/6/2022 - Change default keymap, add default macros
+
+23/5/2022 - Add local building with Docker, Add a README [#4](https://github.com/KinesisCorporation/Adv360-Pro-ZMK/pull/4)
+
+6/5/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
+
+## Base ZMK
+
+There have beeen 3 branches of ZMK used for the 360 Pro so far. 
+
+| 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-z3.2
+
+31/7/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
+
+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)
+
+30/5/2023 - Disable BLE battery reporting due to unreliability
+
+30/5/2023 - Various fixes to allow compilation on zephyr 3.2
+
+29/5/2023 - Merge latest upstream ZMK (Commit b276a3b)
+
+### adv360-z3
+
+27/3/2023 - Fix power on behaviour for RGB lighting
+
+24/2/2023 - Fix indication leds for BLE profile 5
+
+12/1/2023 - Merge latest upstream ZMK (Commit a82a0ec)
+
+12/1/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)
+
+25/11/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
+
+19/10/2022 - Merge latest upstream ZMK (Commit c9eb631)
+
+19/10/2022 - Fix initial power on lighting
+
+2/10/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 
+
+12/9/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)
+
+
+### adv360-beta
+This repository has been deprecated for a year and as such will not be documented, it is advisable to upgrade to V3.0 as this has more features and improved reliability

README.md

@@ -2,7 +2,11 @@
 
 ## Modifying the keymap
 
-There is a GUI for editing the keymap. It is available at https://kinesiscorporation.github.io/Adv360-Pro-GUI
+[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.
+
+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)
 
 ## Building the Firmware with GitHub Actions
 
@@ -38,13 +42,13 @@ There is a GUI for editing the keymap. It is available at https://kinesiscorpora
 
 ### Cleanup
 
-The built docker container and compiled firmware files can be deleted with `make clean`.
+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
 
 Follow the programming instruction on page 8 of the [Quick Start Guide](https://kinesis-ergo.com/wp-content/uploads/Advantage360-Professional-QSG-v8-25-22.pdf) to flash the firmware.
 
-### briefly
+### Overview
 
 1. Extract the firmwares from the downloaded archive.
 1. Connect the left side keyboard to USB.
@@ -60,6 +64,21 @@ Follow the programming instruction on page 8 of the [Quick Start Guide](https://
 
 > Note: There are also physical reset buttons on both keyboards which can be used to enter and exit the bootloader mode. Their location is described in section 2.7 on page 9 in the [User Manual](https://kinesis-ergo.com/wp-content/uploads/Advantage360-ZMK-KB360-PRO-Users-Manual-v3-10-23.pdf) and use is described in section 5.9 on page 14. 
 
+### Upgrading from V2 to V3
+
+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.
+
+## 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)
+
+## 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.
+
+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.
+
 ## Other support
 
 Further support resources can be found on Kinesis.com:

UPGRADE.md

@@ -0,0 +1,62 @@
+# Advantage 360 Pro ZMK upgrade guide
+
+The last V2.0 update and the new V3.0 branch have introduced changes into the keymap files that causes merge conflicts for people updating with custom keymaps. This guide covers what changed, why it changed and how to fix it.
+
+## What changed and why
+
+To resolve issues some users were encountering with out of matrix keypresses, as well as to streamline the keymap for all future updates, several keys that are unused were removed from the keymap and [matrix transform](https://zmk.dev/docs/config/kscan#matrix-transform). Formatting was also standardised to fall in line with ZMK formatting conventions. As a result the board definition for the Advantage 360 Pro as it stands to get merged into ZMK main [here](https://github.com/zmkfirmware/zmk/pull/1454) matches the one in this repository to the greatest extent possible. 
+These changes result in a merge conflict when two diverging git branches try to get added together in the updating procedure.
+This sort of breaking change shouldn't happen again in the future.
+
+## How to solve the merge conflict
+
+In order to solve the merge conflict all that has to be done is for the conflicting key behaviours to be manually removed from two files.
+- adv360.keymap
+
+![The highlighted &none behaviours that need removing](/assets/keymap.jpg)
+- keymap.json
+
+![The highlighted &none behaviours that need removing](/assets/json.jpg)
+
+These highlighted keys must be removed from each layer in both files. Be careful to preserve a comma in between every key behaviour in the keymap.json and at least one space between every behaviour in adv360.keymap or firmware builds will fail. The quotes need correctly preserving on the behaviours in keymap.json. Each behaviour needs to be wrapped in quotes. Whitespace within the quotes is ignored.
+If you try to update your fork using the GitHub web interface you will see an error saying "This branch has merge conflicts and cannot be merged automatically" and you will be prompted to open a pull request instead. Solving the merge conflict this way is more challenging than doing it on GitHub desktop.
+
+### Github Desktop 
+
+This assumes you already have [GitHub desktop](https://desktop.github.com/) downloaded, installed and you have logged in using the GitHub credentials for your account. Whilst it would be helpful to have an alternative text editor such as VSCode installed this task can be completed with notepad 
+1. Clone your repository
+
+        Navigate in the menu to File->Clone repository. Your fork of the Adv360-Pro-ZMK repository should be visible in the menu of repositories to choose from. Click the blue "Clone" button
+2. Open the folder
+
+    Open the folder by using the "Show in your file manager" option and navigate to the "config" folder
+3. Edit keymap.json
+
+    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
+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*"
+
+    ![The commit dialog of GitHub Desktop](/assets/commit.jpg)
+
+6. Merge
+
+    Navigate to Branch->Merge into current branch and select "upstream/V2.0" or "upstream/V3.0". You will see a warning that there will be two conflicted files. Click "Create a merge commit".
+
+    ![The merge dialog showing a warning of conflicts](/assets/merge.jpg)
+
+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. 
+    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)
+8. Push
+
+    Once the merge is complete you should be able to click the "push origin" button in the top bar. At this point your changes should be uploaded to GitHub servers and the build should start
+9. Test your firmware
+
+    When the build succeeds download the uf2 files and flash them as normal. Test the keymap, if keys are shifted one way or the other it's likely you deleted too many or not enough behaviours. 

assets/key-positions.md

@@ -0,0 +1,26 @@
+# Advantage 360 Pro key positions
+## Image
+![The key positions on the Advantage 360](key-positions.png)
+
+## Code
+```
+#define KEYS_L   0  1  2  3  4  5  6 \
+                14 15 16 17 18 19 20 \
+                28 29 30 31 32 33 34 \
+                46 47 48 49 50 51    \
+                60 61 62 63 64
+
+#define THUMBS_LEFT     35 36 \
+                           52 \
+                     65 66 67 \
+
+#define KEYS_R   7  8  9 10 11 12 13 \
+                21 22 23 24 25 26 27 \
+                39 40 41 42 43 44 45 \
+                   54 55 56 57 58 59 \
+                      71 72 73 74 75
+
+#define THUMBS_RIGHT 37 38    \
+                     53       \
+                     68 69 70 \
+                     ```

config/boards/arm/adv360/Kconfig

@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: MIT
 
 config BOARD_ENABLE_DCDC
-	bool "Enable DCDC mode"
-	select SOC_DCDC_NRF52X
-	default y
-	depends on BOARD_ADV360_LEFT || BOARD_ADV360_RIGHT
+    bool "Enable DCDC mode"
+    select SOC_DCDC_NRF52X
+    default y
+    depends on BOARD_ADV360_LEFT || BOARD_ADV360_RIGHT

config/boards/arm/adv360/Kconfig.board

@@ -1,12 +1,12 @@
 #
-# Copyright (c) 2021 Polarity Works
+# Copyright (c) 2022 The ZMK Contributors
 # SPDX-License-Identifier: MIT
 #
 
 config BOARD_ADV360_LEFT
-	bool "adv360_left"
-	depends on SOC_NRF52840_QIAA
+    bool "adv360_left"
+    depends on SOC_NRF52840_QIAA
 
 config BOARD_ADV360_RIGHT
-	bool "adv360_right"
-	depends on SOC_NRF52840_QIAA
+    bool "adv360_right"
+    depends on SOC_NRF52840_QIAA

config/boards/arm/adv360/Kconfig.defconfig

@@ -1,59 +1,61 @@
 #
-# Copyright (c) 2021 Polarity Works
+# Copyright (c) 2022 The ZMK Contributors
 # SPDX-License-Identifier: MIT
 #
 
 if BOARD_ADV360_LEFT
 
-	config ZMK_KEYBOARD_NAME
-	default "Adv360 Pro"
+    config ZMK_KEYBOARD_NAME
+    default "Adv360 Pro"
 
+    config ZMK_SPLIT_ROLE_CENTRAL
+    default y
 endif # BOARD_ADV360_LEFT
 
 if BOARD_ADV360_RIGHT
 
-	config ZMK_KEYBOARD_NAME
-	default "Adv360 Pro rt"
+    config ZMK_KEYBOARD_NAME
+    default "Adv360 Pro rt"
 
 endif # BOARD_ADV360_RIGHT
 
 
 if BOARD_ADV360_LEFT || BOARD_ADV360_RIGHT
 
 config BOARD
-	default "adv360"
+    default "adv360"
 
 config ZMK_SPLIT
-	default y
+    default y
 
 config SPI
     bool
     default y
 
 config BT_CTLR
-	default BT
+    default BT
 
 config ZMK_BLE
-	default y
+    default y
 
 config ZMK_USB
-	default y
+    default y
 
 if USB
 
 config USB_NRFX
-	default y
+    default y
 
 config USB_DEVICE_STACK
-	default y
+    default y
 
 endif # USB
 
 config ZMK_BATTERY_VOLTAGE_DIVIDER
-	default y
+    default y
 
 config SPI
-	default y
+    default y