Loading files…
Choose to either use QMK (more resources and better for beginners) or mage firmware (more hackable and on the go configuration).
Follow the and setup your enviroment. Then, copy from this project's directory into your folder. . The rest of this guide is for the mage firmware. To configure with QMK continue reading their docs.
magev2qmkqmk/keyboards/Initialize the cmake project with cmake -B build. Then, build the firmware with cmake --build build. Put the microcontroller into bootloader mode by holding the boot button (Labeled 'B' on the xiao) then pressing the reset button (Labeled 'R' on the xiao). Use the install.sh script or mount the drive and copy build/mage_firmware.uf2 to the drive. The configuration must then be written. I recommend using the default at first then changing whatever you see fit.
All configuration is done with the configurator tool. There is a cli and tui interface.
Navigate into the configurator folder and run:
cmake -B build
cmake --build build
The configurator tool will then be in the build folder as 'mage_configurator'.
Some commands take arguments. For the description of the command required arguments are surrounded by [] and optional arguments are surrounded by <>. For example:
configurator command [required] <optional>
Additionally, many commands take an <index> argument. This tells the command which config to reference. There are 16 configs to choose from and they can be switch with the CONFIG0-CONFIGF keys.
configurator default
Uploads the default config (defined in configurator/serial.h). Does not save the config.
configurator save <index>
Saves the working config to the given index. If no index is provided saves to the current config index.
configurator change [state] [column] [row] [key]
Sets the provided state, column, row to the key. All arguments are case insensitive.
State can be "high", "normal", "low", "control" or numbers 0-3 respectively.
Column and row are index numbers. For example, the first column third row (default right arrow) would be referenced with "1 3".
Key is the name of the key that should be at the provided position. This can be the full name or a shortening. For example, The escape key can be "escape" or "ESC". A full list of names is available in the configurator/keycode.h file.
configurator
Opens the working config in the TUI. Each key is interactable and pressing the enter key allow them to take the name of a keycode as input. If the key name is invalid the input will be reverted to the old value and the box will turn red.
configurator restore <index>
Pulls from the provided index's config from flash into the working config. The working config will not be saved by this command and the config index is not changed.
configurator fetch
Fetchs the working config from the mage and prints it out.
configurator index <set-index>
If <set-index> is provided then pull the config at that index and set the current config index to it. Otherwise, prints the current config index.
configurator download [filename]
Saves the current working config as a file with the provided file name.
configurator upload [filename]
Uploads the config in the file with the provided file name to the mage.
configurator edit [filename]
Opens the provided file in the TUI and saves to the original file on exit.
Ensure the microcontroller's 5V, Ground, SDA and SCK pins are fully connected and not shorted. There is a normal connection with resistance between the 5V and ground pins but they should not be shorted. Also make sure the microcontroller is working. These 4 pins are the only needed pins on the microcontroller for the mage to work and if any of them are disconnected the entire keyboard will not work.
This usually means that one of the I/O expanders is not working. Make sure that the 5V, Ground, SDA, and SCK pin are fully connected to the pads on the board.
This usually means that the keys that aren't working are not connected to the I/O expander. Most often this is because the pin of the I/O expander for that key is not connected properly.
No comments yet. Be the first to ask about this board.