Instruction file imported from FREAKonXBOX/zmk-config-Proscanner (.github/instructions/.instructions.md). Copyright stays with the author.

ZMK Keyboard Configuration - TOTEM

This repository contains the ZMK firmware configuration for a custom TOTEM keyboard with Seeeduino Xiao BLE controllers.

Repository Purpose

This is a ZMK keyboard firmware configuration repository for the GEIGEIGEIST TOTEM keyboard. ZMK is an open-source keyboard firmware based on the Zephyr RTOS. This repository contains:

• Keyboard layout definitions (keymaps)
• Configuration files for keyboard behavior
• Build specifications for different keyboard variants
• Board-specific settings

Key Files and Structure

build.yaml

Defines the build matrix for the firmware. Contains:

• Board configurations (seeeduino_xiao_ble)
• Shield definitions (totem_left, totem_right, totem_dongle, settings_reset)
• ZMK Studio configuration options
• Build arguments and snippets

Important: When modifying build.yaml, ensure YAML syntax is correct and shield names match existing definitions.

config/

Contains the main configuration files:

• totem.keymap: The keyboard layout definition

  • Uses devicetree syntax (.dtsi format)
  • Defines layers (Base, Cir, Dia, Square, Tri)
  • Contains behavior configurations (mod-tap, layer-tap, homerow mods)
  • Defines combos (key combinations for special functions)
  • Uses ZMK keycodes from <dt-bindings/zmk/keys.h>

• totem.conf: Board configuration settings

  • Bluetooth settings (CONFIG_BT_*)
  • Battery reporting configuration
  • Status advertisement settings
  • Split keyboard configuration
  • Debugging options (commented out by default)

• info.json: Keyboard layout metadata

  • Physical key positions with coordinates and rotations
  • Used by keymap editors and visualization tools
  • Should match the physical keyboard layout

• west.yml: Zephyr West manifest (if present)

  • Defines ZMK firmware version and dependencies

boards/

Contains board-specific configurations and device tree overlays.

.github/workflows/build.yml

GitHub Actions workflow that builds the firmware using the official ZMK build action (zmkfirmware/zmk/.github/workflows/build-user-config.yml@v0.3).

Build Process

The firmware is automatically built by GitHub Actions on:

• Push to any branch
• Pull requests
• Manual workflow dispatch

Build steps:

1. GitHub Actions triggers on code changes
2. Calls the official ZMK build workflow from zmkfirmware/zmk repository
3. Builds firmware for each configuration in build.yaml
4. Generates .uf2 firmware files as artifacts
5. Artifacts can be downloaded and flashed to the keyboard

No local build setup is required - all builds happen in GitHub Actions.

Making Changes

Modifying Keymaps

When changing key assignments in config/totem.keymap:

1. Use valid ZMK keycodes (see ZMK Keycodes documentation)
2. Maintain the devicetree syntax structure
3. Test behavior configurations (hold-tap timing, etc.)
4. Keep layer definitions consistent
5. Document complex combos or custom behaviors

Modifying Configuration

When changing config/totem.conf:

1. Use valid Kconfig options with CONFIG_ prefix
2. Bluetooth settings affect power consumption and connectivity
3. Battery reporting options affect battery level display
4. Debugging options should remain commented out for production builds
5. Follow ZMK configuration documentation

Adding New Shields or Boards

When modifying build.yaml:

1. Maintain YAML list syntax with proper indentation
2. Ensure shield names match definitions in zmk-config or ZMK core
3. Include necessary cmake-args for special features (like ZMK Studio)
4. Consider build time - each entry adds to CI/CD duration

Testing and Validation

Validation Checklist

• YAML files are valid (build.yaml)
• Devicetree syntax is correct (totem.keymap)
• Configuration options are valid ZMK Kconfig options (totem.conf)
• GitHub Actions build completes successfully
• Generated .uf2 files are present in build artifacts
• No syntax errors in keymap or configuration files

How to Test

1. Syntax validation: Check GitHub Actions build status after pushing changes
2. Firmware testing: Download .uf2 artifacts and flash to keyboard hardware
3. Functional testing: Test all keys, layers, and combos on physical keyboard

Common Tasks

Add a new key combo

1. Edit config/totem.keymap
2. Add combo definition in the combos section
3. Specify bindings (what happens) and key-positions (which keys)
4. Follow existing combo format

Change Bluetooth settings

1. Edit config/totem.conf
2. Modify CONFIG_BT_* or CONFIG_ZMK_BLE_* options
3. Consider power consumption impact
4. Test connectivity after flashing

Enable debugging

1. Edit config/totem.conf
2. Uncomment debugging CONFIG options
3. Build and flash firmware
4. Connect via serial to view logs
5. Remember to disable debugging for production

Best Practices

1. Make minimal changes: ZMK configurations are precise - small changes have big effects
2. Test incrementally: Change one thing at a time and test
3. Preserve working configurations: Don't modify working code unnecessarily
4. Follow ZMK conventions: Use standard ZMK keycodes and behaviors
5. Document complex behaviors: Add comments for non-obvious configurations
6. Check build status: Always ensure GitHub Actions builds pass
7. Consider power consumption: Bluetooth and LED settings affect battery life
8. Keep info.json synchronized: If physical layout changes, update info.json

Important Notes

• This is a split keyboard configuration with left, right, and dongle variants
• The keyboard uses Seeeduino Xiao BLE boards
• ZMK Studio is enabled for the left side (for runtime configuration)
• Build artifacts are .uf2 files that can be flashed via USB mass storage
• The keyboard layout is based on the GEIGEIGEIST TOTEM design

Resources

• ZMK Documentation
• ZMK Keycodes
• ZMK Behaviors
• ZMK Configuration
• TOTEM Keyboard
• Devicetree Specification

Workflow Tips for Copilot

When assigned tasks:

• Review the specific file being modified and understand its purpose
• Check existing patterns and follow them
• Validate syntax after changes (especially devicetree and YAML)
• Keep changes minimal and focused
• Test via GitHub Actions build
• Provide clear commit messages explaining what was changed and why
• For keymap changes, consider ergonomics and user experience
• For config changes, consider power consumption and performance trade-offs