darkkirb/qmk_firmware
1
0
Fork 0
forked from mirrors/qmk_firmware
Code Issues Pull requests Projects Releases Packages Wiki Activity

Breaking changes develop merge to master, 2021Q3 edition. (#14196)

Browse source
This commit is contained in:
Nick Brassel 2021-08-29 08:20:25 +10:00
commit f061ca4974
5158 changed files with 46919 additions and 30674 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
.github/workflows/format.yaml vendored
View file

@ -31,12 +31,12 @@ jobs:
output: ' '
fileOutput: ' '
- name: Run qmk cformat and qmk pyformat
- name: Run qmk format-c and qmk format-python
shell: 'bash {0}'
run: |
qmk cformat --core-only -n $(< ~/files.txt)
cformat_exit=$?
qmk pyformat -n
pyformat_exit=$?
qmk format-c --core-only -n $(< ~/files.txt)
format_c_exit=$?
qmk format-python -n
format_python_exit=$?
exit $((cformat_exit + pyformat_exit))
exit $((format_c_exit + format_python_exit))

1
.gitignore vendored
View file

@ -20,7 +20,6 @@
api_data/v1
doxygen/
quantum/version.h
!quantum/tools/eeprom_reset.hex
*.bin
*.eep
*.hex

27
Makefile
View file

@ -557,29 +557,14 @@ git-submodule:
git submodule sync --recursive
git submodule update --init --recursive --progress
# Generate the version.h file
ifdef SKIP_GIT
VERSION_H_FLAGS := --skip-git
endif
ifdef SKIP_VERSION
VERSION_H_FLAGS := --skip-all
SKIP_GIT := yes
endif
# Generate the version.h file
ifndef SKIP_GIT
GIT_VERSION := $(shell git describe --abbrev=6 --dirty --always --tags 2>/dev/null || date +"%Y-%m-%d-%H:%M:%S")
CHIBIOS_VERSION := $(shell cd lib/chibios && git describe --abbrev=6 --dirty --always --tags 2>/dev/null || date +"%Y-%m-%d-%H:%M:%S")
CHIBIOS_CONTRIB_VERSION := $(shell cd lib/chibios-contrib && git describe --abbrev=6 --dirty --always --tags 2>/dev/null || date +"%Y-%m-%d-%H:%M:%S")
else
GIT_VERSION := NA
CHIBIOS_VERSION := NA
CHIBIOS_CONTRIB_VERSION := NA
endif
ifndef SKIP_VERSION
BUILD_DATE := $(shell date +"%Y-%m-%d-%H:%M:%S")
else
BUILD_DATE := 2020-01-01-00:00:00
endif
$(shell echo '#define QMK_VERSION "$(GIT_VERSION)"' > $(ROOT_DIR)/quantum/version.h)
$(shell echo '#define QMK_BUILDDATE "$(BUILD_DATE)"' >> $(ROOT_DIR)/quantum/version.h)
$(shell echo '#define CHIBIOS_VERSION "$(CHIBIOS_VERSION)"' >> $(ROOT_DIR)/quantum/version.h)
$(shell echo '#define CHIBIOS_CONTRIB_VERSION "$(CHIBIOS_CONTRIB_VERSION)"' >> $(ROOT_DIR)/quantum/version.h)
$(shell $(QMK_BIN) generate-version-h $(VERSION_H_FLAGS) -q -o quantum/version.h)
include $(ROOT_DIR)/testlist.mk

2
Vagrantfile vendored
View file

@ -6,7 +6,7 @@ Vagrant.configure(2) do |config|
config.vm.define "qmk_firmware"
# VMware/Virtualbox ( and also Hyperv/Parallels) 64 bit
config.vm.box = "generic/debian9"
config.vm.box = "generic/debian10"
config.vm.synced_folder '.', '/vagrant'

6
bootloader.mk
View file

@ -26,6 +26,7 @@
# atmel-dfu Atmel factory DFU
# lufa-dfu LUFA DFU
# qmk-dfu QMK DFU (LUFA + blinkenlight)
# qmk-hid QMK HID (LUFA + blinkenlight)
# bootloadHID HIDBootFlash compatible (ATmega32A)
# USBasp USBaspLoader (ATmega328P)
# ARM:
@ -67,6 +68,11 @@ ifeq ($(strip $(BOOTLOADER)), qmk-dfu)
BOOTLOADER_SIZE = 8192
endif
endif
ifeq ($(strip $(BOOTLOADER)), qmk-hid)
OPT_DEFS += -DBOOTLOADER_QMK_HID
OPT_DEFS += -DBOOTLOADER_HID
BOOTLOADER_SIZE = 4096
endif
ifeq ($(strip $(BOOTLOADER)), halfkay)
OPT_DEFS += -DBOOTLOADER_HALFKAY
ifeq ($(strip $(MCU)), atmega32u4)

14
build_json.mk
View file

@ -1,31 +1,17 @@
# Look for a json keymap file
ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_5)/keymap.json)","")
KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
KEYMAP_JSON := $(MAIN_KEYMAP_PATH_5)/keymap.json
KEYMAP_PATH := $(MAIN_KEYMAP_PATH_5)
else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_4)/keymap.json)","")
KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
KEYMAP_JSON := $(MAIN_KEYMAP_PATH_4)/keymap.json
KEYMAP_PATH := $(MAIN_KEYMAP_PATH_4)
else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_3)/keymap.json)","")
KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
KEYMAP_JSON := $(MAIN_KEYMAP_PATH_3)/keymap.json
KEYMAP_PATH := $(MAIN_KEYMAP_PATH_3)
else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_2)/keymap.json)","")
KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
KEYMAP_JSON := $(MAIN_KEYMAP_PATH_2)/keymap.json
KEYMAP_PATH := $(MAIN_KEYMAP_PATH_2)
else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_1)/keymap.json)","")
KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
KEYMAP_JSON := $(MAIN_KEYMAP_PATH_1)/keymap.json
KEYMAP_PATH := $(MAIN_KEYMAP_PATH_1)
endif
# Load the keymap-level rules.mk if exists
ifneq ("$(wildcard $(KEYMAP_PATH))", "")
-include $(KEYMAP_PATH)/rules.mk
endif
# Generate the keymap.c
$(KEYBOARD_OUTPUT)/src/keymap.c: $(KEYMAP_JSON)
$(QMK_BIN) json2c --quiet --output $(KEYMAP_C) $(KEYMAP_JSON)

56
build_keyboard.mk
View file

@ -23,6 +23,15 @@ KEYBOARD_OUTPUT := $(BUILD_DIR)/obj_$(KEYBOARD_FILESAFE)
# Force expansion
TARGET := $(TARGET)
ifneq ($(FORCE_LAYOUT),)
TARGET := $(TARGET)_$(FORCE_LAYOUT)
endif
# Object files and generated keymap directory
# To put object files in current directory, use a dot (.), do NOT make
# this an empty or blank macro!
KEYMAP_OUTPUT := $(BUILD_DIR)/obj_$(TARGET)
# For split boards we need to set a master half.
MASTER ?= left
ifdef master
@ -100,7 +109,7 @@ MAIN_KEYMAP_PATH_4 := $(KEYBOARD_PATH_4)/keymaps/$(KEYMAP)
MAIN_KEYMAP_PATH_5 := $(KEYBOARD_PATH_5)/keymaps/$(KEYMAP)
# Pull in rules from info.json
INFO_RULES_MK = $(shell $(QMK_BIN) generate-rules-mk --quiet --escape --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/rules.mk)
INFO_RULES_MK = $(shell $(QMK_BIN) generate-rules-mk --quiet --escape --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/info_rules.mk)
include $(INFO_RULES_MK)
# Check for keymap.json first, so we can regenerate keymap.c
@ -137,16 +146,35 @@ ifeq ("$(wildcard $(KEYMAP_PATH))", "")
endif
endif
# Have we found a keymap.json?
ifneq ("$(wildcard $(KEYMAP_JSON))", "")
KEYMAP_C := $(KEYMAP_OUTPUT)/src/keymap.c
KEYMAP_H := $(KEYMAP_OUTPUT)/src/config.h
# Load the keymap-level rules.mk if exists
-include $(KEYMAP_PATH)/rules.mk
# Load any rules.mk content from keymap.json
INFO_RULES_MK = $(shell $(QMK_BIN) generate-rules-mk --quiet --escape --keyboard $(KEYBOARD) --keymap $(KEYMAP) --output $(KEYMAP_OUTPUT)/src/rules.mk)
include $(INFO_RULES_MK)
# Add rules to generate the keymap files - indentation here is important
$(KEYMAP_OUTPUT)/src/keymap.c: $(KEYMAP_JSON)
$(QMK_BIN) json2c --quiet --output $(KEYMAP_C) $(KEYMAP_JSON)
$(KEYMAP_OUTPUT)/src/config.h: $(KEYMAP_JSON)
$(QMK_BIN) generate-config-h --quiet --keyboard $(KEYBOARD) --keymap $(KEYMAP) --output $(KEYMAP_H)
generated-files: $(KEYMAP_OUTPUT)/src/config.h $(KEYMAP_OUTPUT)/src/keymap.c
endif
ifeq ($(strip $(CTPC)), yes)
CONVERT_TO_PROTON_C=yes
endif
ifeq ($(strip $(CONVERT_TO_PROTON_C)), yes)
include platforms/chibios/QMK_PROTON_C/convert_to_proton_c.mk
endif
ifneq ($(FORCE_LAYOUT),)
TARGET := $(TARGET)_$(FORCE_LAYOUT)
include platforms/chibios/boards/QMK_PROTON_C/convert_to_proton_c.mk
endif
include quantum/mcu_selection.mk
@ -232,6 +260,7 @@ ifdef MCU_FAMILY
PLATFORM=CHIBIOS
PLATFORM_KEY=chibios
FIRMWARE_FORMAT?=bin
OPT_DEFS += -DMCU_$(MCU_FAMILY)
else ifdef ARM_ATSAM
PLATFORM=ARM_ATSAM
PLATFORM_KEY=arm_atsam
@ -327,19 +356,19 @@ endif
# Disable features that a keyboard doesn't support
-include disable_features.mk
# Object files directory
# To put object files in current directory, use a dot (.), do NOT make
# this an empty or blank macro!
KEYMAP_OUTPUT := $(BUILD_DIR)/obj_$(TARGET)
ifneq ("$(wildcard $(KEYMAP_PATH)/config.h)","")
CONFIG_H += $(KEYMAP_PATH)/config.h
endif
ifneq ("$(KEYMAP_H)","")
CONFIG_H += $(KEYMAP_H)
endif
# project specific files
SRC += $(KEYBOARD_SRC) \
SRC += \
$(KEYBOARD_SRC) \
$(KEYMAP_C) \
$(QUANTUM_SRC)
$(QUANTUM_SRC) \
$(QUANTUM_DIR)/main.c \
# Optimize size but this may cause error "relocation truncated to fit"
#EXTRALDFLAGS = -Wl,--relax
@ -374,6 +403,7 @@ ifneq ($(strip $(PROTOCOL)),)
else
include $(TMK_PATH)/protocol/$(PLATFORM_KEY).mk
endif
-include $(TOP_DIR)/platforms/$(PLATFORM_KEY)/flash.mk
# TODO: remove this bodge?
PROJECT_DEFS := $(OPT_DEFS)

4
build_layout.mk
View file

@ -7,7 +7,6 @@ define SEARCH_LAYOUTS_REPO
LAYOUT_KEYMAP_C := $$(LAYOUT_KEYMAP_PATH)/keymap.c
ifneq ("$$(wildcard $$(LAYOUT_KEYMAP_JSON))","")
-include $$(LAYOUT_KEYMAP_PATH)/rules.mk
KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
KEYMAP_JSON := $$(LAYOUT_KEYMAP_JSON)
KEYMAP_PATH := $$(LAYOUT_KEYMAP_PATH)
else ifneq ("$$(wildcard $$(LAYOUT_KEYMAP_C))","")
@ -31,6 +30,3 @@ ifneq ($(FORCE_LAYOUT),)
endif
$(foreach LAYOUT,$(LAYOUTS),$(eval $(call SEARCH_LAYOUTS)))
# Use rule from build_json.mk, but update prerequisite in case KEYMAP_JSON was updated
$(KEYBOARD_OUTPUT)/src/keymap.c: $(KEYMAP_JSON)

4
build_test.mk
View file

@ -53,8 +53,10 @@ endif
include common_features.mk
include $(TMK_PATH)/common.mk
include $(QUANTUM_PATH)/debounce/tests/rules.mk
include $(QUANTUM_PATH)/sequencer/tests/rules.mk
include $(QUANTUM_PATH)/serial_link/tests/rules.mk
include $(TMK_PATH)/common/test/rules.mk
ifneq ($(filter $(FULL_TESTS),$(TEST)),)
include build_full_test.mk
endif
@ -62,7 +64,7 @@ endif
$(TEST)_SRC += \
tests/test_common/main.c \
$(LIB_PATH)/printf/printf.c \
$(COMMON_DIR)/printf.c
$(QUANTUM_PATH)/logging/print.c
$(TEST_OBJ)/$(TEST)_SRC := $($(TEST)_SRC)
$(TEST_OBJ)/$(TEST)_INC := $($(TEST)_INC) $(VPATH) $(GTEST_INC)

3
common.mk
View file

@ -12,6 +12,9 @@ QUANTUM_PATH = $(QUANTUM_DIR)
DRIVER_DIR = drivers
DRIVER_PATH = $(DRIVER_DIR)
PLATFORM_DIR = platforms
PLATFORM_PATH = $(PLATFORM_DIR)
BUILD_DIR := .build
COMMON_VPATH := $(TOP_DIR)

153
common_features.mk
View file

@ -20,8 +20,23 @@ QUANTUM_SRC += \
$(QUANTUM_DIR)/send_string.c \
$(QUANTUM_DIR)/bitwise.c \
$(QUANTUM_DIR)/led.c \
$(QUANTUM_DIR)/action.c \
$(QUANTUM_DIR)/action_layer.c \
$(QUANTUM_DIR)/action_macro.c \
$(QUANTUM_DIR)/action_tapping.c \
$(QUANTUM_DIR)/action_util.c \
$(QUANTUM_DIR)/eeconfig.c \
$(QUANTUM_DIR)/keyboard.c \
$(QUANTUM_DIR)/keymap_common.c \
$(QUANTUM_DIR)/keycode_config.c
$(QUANTUM_DIR)/keycode_config.c \
$(QUANTUM_DIR)/logging/debug.c \
$(QUANTUM_DIR)/logging/sendchar.c \
VPATH += $(QUANTUM_DIR)/logging
# Fall back to lib/printf if there is no platform provided print
ifeq ("$(wildcard $(TMK_PATH)/common/$(PLATFORM_KEY)/printf.mk)","")
include $(QUANTUM_PATH)/logging/print.mk
endif
ifeq ($(strip $(DEBUG_MATRIX_SCAN_RATE_ENABLE)), yes)
OPT_DEFS += -DDEBUG_MATRIX_SCAN_RATE
@ -102,13 +117,13 @@ endif
ifeq ($(strip $(MOUSEKEY_ENABLE)), yes)
OPT_DEFS += -DMOUSEKEY_ENABLE
OPT_DEFS += -DMOUSE_ENABLE
MOUSE_ENABLE := yes
SRC += $(QUANTUM_DIR)/mousekey.c
endif
ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
OPT_DEFS += -DPOINTING_DEVICE_ENABLE
OPT_DEFS += -DMOUSE_ENABLE
MOUSE_ENABLE := yes
SRC += $(QUANTUM_DIR)/pointing_device.c
endif
@ -170,6 +185,7 @@ else
else ifneq ($(filter $(MCU_SERIES),STM32L0xx STM32L1xx),)
OPT_DEFS += -DEEPROM_DRIVER
COMMON_VPATH += $(DRIVER_PATH)/eeprom
COMMON_VPATH += $(PLATFORM_PATH)/$(PLATFORM_KEY)/$(DRIVER_DIR)/eeprom
SRC += eeprom_driver.c eeprom_stm32_L0_L1.c
else
# This will effectively work the same as "transient" if not supported by the chip
@ -196,10 +212,11 @@ ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
ifeq ($(filter $(RGBLIGHT_DRIVER),$(VALID_RGBLIGHT_TYPES)),)
$(error RGBLIGHT_DRIVER="$(RGBLIGHT_DRIVER)" is not a valid RGB type)
else
POST_CONFIG_H += $(QUANTUM_DIR)/rgblight_post_config.h
COMMON_VPATH += $(QUANTUM_DIR)/rgblight
POST_CONFIG_H += $(QUANTUM_DIR)/rgblight/rgblight_post_config.h
OPT_DEFS += -DRGBLIGHT_ENABLE
SRC += $(QUANTUM_DIR)/color.c
SRC += $(QUANTUM_DIR)/rgblight.c
SRC += $(QUANTUM_DIR)/rgblight/rgblight.c
CIE1931_CURVE := yes
RGB_KEYCODES_ENABLE := yes
endif
@ -230,21 +247,25 @@ ifneq (,$(filter $(MCU), atmega16u2 atmega32u2 at90usb162))
# ATmegaxxU2 does not have hardware MUL instruction - lib8tion must be told to use software multiplication routines
OPT_DEFS += -DLIB8_ATTINY
endif
COMMON_VPATH += $(QUANTUM_DIR)/led_matrix
COMMON_VPATH += $(QUANTUM_DIR)/led_matrix/animations
COMMON_VPATH += $(QUANTUM_DIR)/led_matrix/animations/runners
SRC += $(QUANTUM_DIR)/process_keycode/process_backlight.c
SRC += $(QUANTUM_DIR)/led_matrix.c
SRC += $(QUANTUM_DIR)/led_matrix_drivers.c
SRC += $(QUANTUM_DIR)/led_matrix/led_matrix.c
SRC += $(QUANTUM_DIR)/led_matrix/led_matrix_drivers.c
SRC += $(LIB_PATH)/lib8tion/lib8tion.c
CIE1931_CURVE := yes
ifeq ($(strip $(LED_MATRIX_DRIVER)), IS31FL3731)
OPT_DEFS += -DIS31FL3731 -DSTM32_I2C -DHAL_USE_I2C=TRUE
COMMON_VPATH += $(DRIVER_PATH)/issi
COMMON_VPATH += $(DRIVER_PATH)/led/issi
SRC += is31fl3731-simple.c
QUANTUM_LIB_SRC += i2c_master.c
endif
endif
RGB_MATRIX_ENABLE ?= no
VALID_RGB_MATRIX_TYPES := IS31FL3731 IS31FL3733 IS31FL3737 IS31FL3741 WS2812 custom
VALID_RGB_MATRIX_TYPES := AW20216 IS31FL3731 IS31FL3733 IS31FL3737 IS31FL3741 WS2812 custom
ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
ifeq ($(filter $(RGB_MATRIX_DRIVER),$(VALID_RGB_MATRIX_TYPES)),)
@ -255,36 +276,47 @@ ifneq (,$(filter $(MCU), atmega16u2 atmega32u2 at90usb162))
# ATmegaxxU2 does not have hardware MUL instruction - lib8tion must be told to use software multiplication routines
OPT_DEFS += -DLIB8_ATTINY
endif
COMMON_VPATH += $(QUANTUM_DIR)/rgb_matrix
COMMON_VPATH += $(QUANTUM_DIR)/rgb_matrix/animations
COMMON_VPATH += $(QUANTUM_DIR)/rgb_matrix/animations/runners
SRC += $(QUANTUM_DIR)/color.c
SRC += $(QUANTUM_DIR)/rgb_matrix.c
SRC += $(QUANTUM_DIR)/rgb_matrix_drivers.c
SRC += $(QUANTUM_DIR)/rgb_matrix/rgb_matrix.c
SRC += $(QUANTUM_DIR)/rgb_matrix/rgb_matrix_drivers.c
SRC += $(LIB_PATH)/lib8tion/lib8tion.c
CIE1931_CURVE := yes
RGB_KEYCODES_ENABLE := yes
ifeq ($(strip $(RGB_MATRIX_DRIVER)), AW20216)
OPT_DEFS += -DAW20216 -DSTM32_SPI -DHAL_USE_SPI=TRUE
COMMON_VPATH += $(DRIVER_PATH)/led
SRC += aw20216.c
QUANTUM_LIB_SRC += spi_master.c
endif
ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3731)
OPT_DEFS += -DIS31FL3731 -DSTM32_I2C -DHAL_USE_I2C=TRUE
COMMON_VPATH += $(DRIVER_PATH)/issi
COMMON_VPATH += $(DRIVER_PATH)/led/issi
SRC += is31fl3731.c
QUANTUM_LIB_SRC += i2c_master.c
endif
ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3733)
OPT_DEFS += -DIS31FL3733 -DSTM32_I2C -DHAL_USE_I2C=TRUE
COMMON_VPATH += $(DRIVER_PATH)/issi
COMMON_VPATH += $(DRIVER_PATH)/led/issi
SRC += is31fl3733.c
QUANTUM_LIB_SRC += i2c_master.c
endif
ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3737)
OPT_DEFS += -DIS31FL3737 -DSTM32_I2C -DHAL_USE_I2C=TRUE
COMMON_VPATH += $(DRIVER_PATH)/issi
COMMON_VPATH += $(DRIVER_PATH)/led/issi
SRC += is31fl3737.c
QUANTUM_LIB_SRC += i2c_master.c
endif
ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3741)
OPT_DEFS += -DIS31FL3741 -DSTM32_I2C -DHAL_USE_I2C=TRUE
COMMON_VPATH += $(DRIVER_PATH)/issi
COMMON_VPATH += $(DRIVER_PATH)/led/issi
SRC += is31fl3741.c
QUANTUM_LIB_SRC += i2c_master.c
endif
@ -342,11 +374,6 @@ ifeq ($(strip $(LCD_ENABLE)), yes)
CIE1931_CURVE := yes
endif
# backward compat
ifeq ($(strip $(BACKLIGHT_CUSTOM_DRIVER)), yes)
BACKLIGHT_DRIVER := custom
endif
VALID_BACKLIGHT_TYPES := pwm timer software custom
BACKLIGHT_ENABLE ?= no
@ -406,7 +433,7 @@ ifeq ($(strip $(WS2812_DRIVER_REQUIRED)), yes)
endif
ifeq ($(strip $(APA102_DRIVER_REQUIRED)), yes)
COMMON_VPATH += $(DRIVER_PATH)/apa102
COMMON_VPATH += $(DRIVER_PATH)/led
SRC += apa102.c
endif
@ -462,18 +489,15 @@ ifeq ($(strip $(DIP_SWITCH_ENABLE)), yes)
SRC += $(QUANTUM_DIR)/dip_switch.c
endif
VALID_MAGIC_TYPES := yes full lite
VALID_MAGIC_TYPES := yes lite
BOOTMAGIC_ENABLE ?= no
ifneq ($(strip $(BOOTMAGIC_ENABLE)), no)
ifeq ($(filter $(BOOTMAGIC_ENABLE),$(VALID_MAGIC_TYPES)),)
$(error BOOTMAGIC_ENABLE="$(BOOTMAGIC_ENABLE)" is not a valid type of magic)
endif
ifneq ($(strip $(BOOTMAGIC_ENABLE)), full)
ifneq ($(strip $(BOOTMAGIC_ENABLE)), no)
OPT_DEFS += -DBOOTMAGIC_LITE
QUANTUM_SRC += $(QUANTUM_DIR)/bootmagic/bootmagic_lite.c
else
OPT_DEFS += -DBOOTMAGIC_ENABLE
QUANTUM_SRC += $(QUANTUM_DIR)/bootmagic/bootmagic_full.c
endif
endif
COMMON_VPATH += $(QUANTUM_DIR)/bootmagic
@ -494,42 +518,31 @@ ifneq ($(strip $(CUSTOM_MATRIX)), yes)
# if 'lite' then skip the actual matrix implementation
ifneq ($(strip $(CUSTOM_MATRIX)), lite)
# Include the standard or split matrix code if needed
ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
QUANTUM_SRC += $(QUANTUM_DIR)/split_common/matrix.c
else
QUANTUM_SRC += $(QUANTUM_DIR)/matrix.c
endif
QUANTUM_SRC += $(QUANTUM_DIR)/matrix.c
endif
endif
# Support for translating old names to new names:
ifeq ($(strip $(DEBOUNCE_TYPE)),sym_g)
DEBOUNCE_TYPE:=sym_defer_g
else ifeq ($(strip $(DEBOUNCE_TYPE)),eager_pk)
DEBOUNCE_TYPE:=sym_eager_pk
else ifeq ($(strip $(DEBOUNCE_TYPE)),sym_pk)
DEBOUNCE_TYPE:=sym_defer_pk
else ifeq ($(strip $(DEBOUNCE_TYPE)),eager_pr)
DEBOUNCE_TYPE:=sym_eager_pr
endif
DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce
# Debounce Modules. Set DEBOUNCE_TYPE=custom if including one manually.
DEBOUNCE_TYPE?= sym_defer_g
DEBOUNCE_TYPE ?= sym_defer_g
ifneq ($(strip $(DEBOUNCE_TYPE)), custom)
QUANTUM_SRC += $(DEBOUNCE_DIR)/$(strip $(DEBOUNCE_TYPE)).c
QUANTUM_SRC += $(QUANTUM_DIR)/debounce/$(strip $(DEBOUNCE_TYPE)).c
endif
ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
POST_CONFIG_H += $(QUANTUM_DIR)/split_common/post_config.h
OPT_DEFS += -DSPLIT_KEYBOARD
CRC_ENABLE := yes
# Include files used by all split keyboards
QUANTUM_SRC += $(QUANTUM_DIR)/split_common/split_util.c
# Determine which (if any) transport files are required
ifneq ($(strip $(SPLIT_TRANSPORT)), custom)
QUANTUM_LIB_SRC += $(QUANTUM_DIR)/split_common/transport.c
QUANTUM_SRC += $(QUANTUM_DIR)/split_common/transport.c \
$(QUANTUM_DIR)/split_common/transactions.c
OPT_DEFS += -DSPLIT_COMMON_TRANSACTIONS
# Functions added via QUANTUM_LIB_SRC are only included in the final binary if they're called.
# Unused functions are pruned away, which is why we can add multiple drivers here without bloat.
ifeq ($(PLATFORM),AVR)
@ -550,11 +563,17 @@ ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
COMMON_VPATH += $(QUANTUM_PATH)/split_common
endif
ifeq ($(strip $(CRC_ENABLE)), yes)
OPT_DEFS += -DCRC_ENABLE
SRC += crc.c
endif
HAPTIC_ENABLE ?= no
ifneq ($(strip $(HAPTIC_ENABLE)),no)
COMMON_VPATH += $(DRIVER_PATH)/haptic
SRC += haptic.c
OPT_DEFS += -DHAPTIC_ENABLE
SRC += $(QUANTUM_DIR)/haptic.c
SRC += $(QUANTUM_DIR)/process_keycode/process_haptic.c
endif
ifneq ($(filter DRV2605L, $(HAPTIC_ENABLE)), )
@ -569,15 +588,33 @@ ifneq ($(filter SOLENOID, $(HAPTIC_ENABLE)), )
endif
ifeq ($(strip $(HD44780_ENABLE)), yes)
SRC += drivers/avr/hd44780.c
SRC += platforms/avr/drivers/hd44780.c
OPT_DEFS += -DHD44780_ENABLE
endif
ifeq ($(strip $(OLED_DRIVER_ENABLE)), yes)
OPT_DEFS += -DOLED_DRIVER_ENABLE
COMMON_VPATH += $(DRIVER_PATH)/oled
QUANTUM_LIB_SRC += i2c_master.c
SRC += oled_driver.c
VALID_OLED_DRIVER_TYPES := SSD1306 custom
OLED_DRIVER ?= SSD1306
ifeq ($(strip $(OLED_ENABLE)), yes)
ifeq ($(filter $(OLED_DRIVER),$(VALID_OLED_DRIVER_TYPES)),)
$(error OLED_DRIVER="$(OLED_DRIVER)" is not a valid OLED driver)
else
OPT_DEFS += -DOLED_ENABLE
COMMON_VPATH += $(DRIVER_PATH)/oled
OPT_DEFS += -DOLED_DRIVER_$(strip $(shell echo $(OLED_DRIVER) | tr '[:lower:]' '[:upper:]'))
ifeq ($(strip $(OLED_DRIVER)), SSD1306)
SRC += ssd1306_sh1106.c
QUANTUM_LIB_SRC += i2c_master.c
endif
endif
endif
ifeq ($(strip $(ST7565_ENABLE)), yes)
OPT_DEFS += -DST7565_ENABLE
COMMON_VPATH += $(DRIVER_PATH)/oled # For glcdfont.h
COMMON_VPATH += $(DRIVER_PATH)/lcd
QUANTUM_LIB_SRC += spi_master.c
SRC += st7565.c
endif
include $(DRIVER_PATH)/qwiic/qwiic.mk
@ -632,6 +669,11 @@ ifeq ($(strip $(COMBO_ENABLE)), yes)
OPT_DEFS += -DCOMBO_ENABLE
endif
ifeq ($(strip $(KEY_OVERRIDE_ENABLE)), yes)
SRC += $(QUANTUM_DIR)/process_keycode/process_key_override.c
OPT_DEFS += -DKEY_OVERRIDE_ENABLE
endif
ifeq ($(strip $(TAP_DANCE_ENABLE)), yes)
SRC += $(QUANTUM_DIR)/process_keycode/process_tap_dance.c
OPT_DEFS += -DTAP_DANCE_ENABLE
@ -671,6 +713,11 @@ ifeq ($(strip $(JOYSTICK_ENABLE)), digital)
OPT_DEFS += -DDIGITAL_JOYSTICK_ENABLE
endif
DIGITIZER_ENABLE ?= no
ifneq ($(strip $(DIGITIZER_ENABLE)), no)
SRC += $(QUANTUM_DIR)/digitizer.c
endif
USBPD_ENABLE ?= no
VALID_USBPD_DRIVER_TYPES = custom vendor
USBPD_DRIVER ?= vendor

58
data/mappings/info_config.json
View file

@ -1,21 +1,48 @@
# This file maps keys between `config.h` and `info.json`. It is used by QMK
# This file maps keys between `config.h` and `info.json`. It is used by QMK
# to correctly and consistently map back and forth between the two systems.
{
# Format:
# <config.h key>: {"info_key": <info.json key>, ["value_type": <value_type>], ["to_json": <true/false>], ["to_c": <true/false>]}
# value_type: one of "array", "array.int", "int", "hex", "list", "mapping"
# value_type: one of "array", "array.int", "bool", "int", "hex", "list", "mapping"
# to_json: Default `true`. Set to `false` to exclude this mapping from info.json
# to_c: Default `true`. Set to `false` to exclude this mapping from config.h
# warn_duplicate: Default `true`. Set to `false` to turn off warning when a value exists in both places
"DEBOUNCE": {"info_key": "debounce", "value_type": "int"}
"AUDIO_VOICES": {"info_key": "audio.voices", "value_type": "bool"},
"BACKLIGHT_BREATHING": {"info_key": "backlight.breathing", "value_type": "bool"},
"BREATHING_PERIOD": {"info_key": "backlight.breathing_period", "value_type": "int"},
"BACKLIGHT_PIN": {"info_key": "backlight.pin"},
"COMBO_COUNT": {"info_key": "combo.count", "value_type": "int"},
"COMBO_TERM": {"info_key": "combo.term", "value_type": "int"},
"DEBOUNCE": {"info_key": "debounce", "value_type": "int"},
"DEVICE_VER": {"info_key": "usb.device_ver", "value_type": "hex"},
"DESCRIPTION": {"info_key": "keyboard_folder", "to_json": false},
"DIODE_DIRECTION": {"info_key": "diode_direction"},
"FORCE_NKRO": {"info_key": "usb.force_nkro", "value_type": "bool"},
"DYNAMIC_KEYMAP_EEPROM_MAX_ADDR": {"info_key": "dynamic_keymap.eeprom_max_addr", "value_type": "int"},
"DYNAMIC_KEYMAP_LAYER_COUNT": {"info_key": "dynamic_keymap.layer_count", "value_type": "int"},
"IGNORE_MOD_TAP_INTERRUPT": {"info_key": "tapping.ignore_mod_tap_interrupt", "value_type": "bool"},
"IGNORE_MOD_TAP_INTERRUPT_PER_KEY": {"info_key": "tapping.ignore_mod_tap_interrupt_per_key", "value_type": "bool"},
"LAYOUTS": {"info_key": "layout_aliases", "value_type": "mapping"},
"LEADER_PER_KEY_TIMING": {"info_key": "leader_key.timing", "value_type": "bool"},
"LEADER_KEY_STRICT_KEY_PROCESSING": {"info_key": "leader_key.strict_processing", "value_type": "bool"},
"LEADER_TIMEOUT": {"info_key": "leader_key.timeout", "value_type": "int"},
"LED_CAPS_LOCK_PIN": {"info_key": "indicators.caps_lock"},
"LED_NUM_LOCK_PIN": {"info_key": "indicators.num_lock"},
"LED_SCROLL_LOCK_PIN": {"info_key": "indicators.scroll_lock"},
"MANUFACTURER": {"info_key": "manufacturer"},
"MATRIX_HAS_GHOST": {"info_key": "matrix_pins.ghost", "value_type": "bool"},
"MATRIX_IO_DELAY": {"info_key": "matrix_pins.io_delay", "value_type": "int"},
"MOUSEKEY_DELAY": {"info_key": "mousekey.delay", "value_type": "int"},
"MOUSEKEY_INTERVAL": {"info_key": "mousekey.interval", "value_type": "int"},
"MOUSEKEY_MAX_SPEED": {"info_key": "mousekey.max_speed", "value_type": "int"},
"MOUSEKEY_TIME_TO_MAX": {"info_key": "mousekey.time_to_max", "value_type": "int"},
"MOUSEKEY_WHEEL_DELAY": {"info_key": "mousekey.wheel_delay", "value_type": "int"},
"ONESHOT_TIMEOUT": {"info_key": "oneshot.timeout", "value_type": "int"},
"ONESHOT_TAP_TOGGLE": {"info_key": "oneshot.tap_toggle", "value_type": "int"},
"PERMISSIVE_HOLD": {"info_key": "tapping.permissive_hold", "value_type": "bool"},
"PERMISSIVE_HOLD_PER_KEY": {"info_key": "tapping.permissive_hold_per_key", "value_type": "bool"},
"RETRO_TAPPING": {"info_key": "tapping.retro", "value_type": "bool"},
"RETRO_TAPPING_PER_KEY": {"info_key": "tapping.retro_per_key", "value_type": "bool"},
"RGB_DI_PIN": {"info_key": "rgblight.pin"},
"RGBLED_NUM": {"info_key": "rgblight.led_count", "value_type": "int"},
"RGBLED_SPLIT": {"info_key": "rgblight.split_count", "value_type": "array.int"},
@ -30,17 +57,40 @@
"RGBLIGHT_EFFECT_SNAKE": {"info_key": "rgblight.animations.snake", "value_type": "bool"},
"RGBLIGHT_EFFECT_STATIC_GRADIENT": {"info_key": "rgblight.animations.static_gradient", "value_type": "bool"},
"RGBLIGHT_EFFECT_TWINKLE": {"info_key": "rgblight.animations.twinkle"},
"RGBLIGHT_LAYER_BLINK": {"info_key": "rgblight.layers.blink", "value_type": "bool"},
"RGBLIGHT_LAYERS": {"info_key": "rgblight.layers.enabled", "value_type": "bool"},
"RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF": {"info_key": "rgblight.layers.override_rgb", "value_type": "bool"},
"RGBLIGHT_LIMIT_VAL": {"info_key": "rgblight.max_brightness", "value_type": "int"},
"RGBLIGHT_MAX_LAYERS": {"info_key": "rgblight.layers.max", "value_type": "int"},
"RGBLIGHT_HUE_STEP": {"info_key": "rgblight.hue_steps", "value_type": "int"},
"RGBLIGHT_SAT_STEP": {"info_key": "rgblight.saturation_steps", "value_type": "int"},
"RGBLIGHT_VAL_STEP": {"info_key": "rgblight.brightness_steps", "value_type": "int"},
"RGBLIGHT_SLEEP": {"info_key": "rgblight.sleep", "value_type": "bool"},
"RGBLIGHT_SPLIT": {"info_key": "rgblight.split", "value_type": "bool"},
"RGBW": {"info_key": "rgblight.rgbw", "value_type": "bool"},
"PRODUCT": {"info_key": "keyboard_folder", "to_json": false},
"PRODUCT_ID": {"info_key": "usb.pid", "value_type": "hex"},
"VENDOR_ID": {"info_key": "usb.vid", "value_type": "hex"},
"QMK_ESC_OUTPUT": {"info_key": "qmk_lufa_bootloader.esc_output"},
"QMK_ESC_INPUT": {"info_key": "qmk_lufa_bootloader.esc_input"},
"QMK_KEYS_PER_SCAN": {"info_key": "qmk.keys_per_scan", "value_type": "int"},
"QMK_LED": {"info_key": "qmk_lufa_bootloader.led"},
"QMK_SPEAKER": {"info_key": "qmk_lufa_bootloader.speaker"}
"QMK_SPEAKER": {"info_key": "qmk_lufa_bootloader.speaker"},
"SPLIT_MODS_ENABLE": {"info_key": "split.transport.sync_modifiers", "value_type": "bool"},
"SPLIT_TRANSPORT_MIRROR": {"info_key": "split.transport.sync_matrix_state", "value_type": "bool"},
"SPLIT_USB_DETECT": {"info_key": "split.usb_detect.enabled", "value_type": "bool"},
"SPLIT_USB_TIMEOUT": {"info_key": "split.usb_detect.timeout", "value_type": "int"},
"SPLIT_USB_TIMEOUT_POLL": {"info_key": "split.usb_detect.polling_interval", "value_type": "int"},
"SOFT_SERIAL_PIN": {"info_key": "split.soft_serial_pin"},
"SOFT_SERIAL_SPEED": {"info_key": "split.soft_serial_speed"},
"TAP_CODE_DELAY": {"info_key": "qmk.tap_keycode_delay", "value_type": "int"},
"TAP_HOLD_CAPS_DELAY": {"info_key": "qmk.tap_capslock_delay", "value_type": "int"},
"TAPPING_FORCE_HOLD": {"info_key": "tapping.force_hold", "value_type": "bool"},
"TAPPING_FORCE_HOLD_PER_KEY": {"info_key": "tapping.force_hold_per_key", "value_type": "bool"},
"TAPPING_TERM": {"info_key": "tapping.term", "value_type": "int"},
"TAPPING_TERM_PER_KEY": {"info_key": "tapping.term_per_key", "value_type": "bool"},
"TAPPING_TOGGLE": {"info_key": "tapping.toggle", "value_type": "int"},
"USB_MAX_POWER_CONSUMPTION": {"info_key": "usb.max_power", "value_type": "int"},
"USB_POLLING_INTERVAL_MS": {"info_key": "usb.polling_interval", "value_type": "int"},
"USB_SUSPEND_WAKEUP_DELAY": {"info_key": "usb.suspend_wakeup_delay", "value_type": "int"},
}

14
data/mappings/info_rules.json
View file

@ -1,15 +1,25 @@
# This file maps keys between `rules.mk` and `info.json`. It is used by QMK
# This file maps keys between `rules.mk` and `info.json`. It is used by QMK
# to correctly and consistently map back and forth between the two systems.
{
# Format:
# <rules.mk key>: {"info_key": <info.json key>, ["value_type": <value_type>], ["to_json": <true/false>], ["to_c": <true/false>]}
# value_type: one of "array", "array.int", "int", "list", "hex", "mapping"
# value_type: one of "array", "array.int", "bool", "int", "list", "hex", "mapping"
# to_json: Default `true`. Set to `false` to exclude this mapping from info.json
# to_c: Default `true`. Set to `false` to exclude this mapping from rules.mk
# warn_duplicate: Default `true`. Set to `false` to turn off warning when a value exists in both places
"BOARD": {"info_key": "board"},
"BOOTLOADER": {"info_key": "bootloader", "warn_duplicate": false},
"BLUETOOTH": {"info_key": "bluetooth.driver"},
"FIRMWARE_FORMAT": {"info_key": "build.firmware_format"},
"KEYBOARD_SHARED_EP": {"info_key": "usb.shared_endpoint.keyboard", "value_type": "bool"},
"MOUSE_SHARED_EP": {"info_key": "usb.shared_endpoint.mouse", "value_type": "bool"},
"LAYOUTS": {"info_key": "community_layouts", "value_type": "list"},
"LED_MATRIX_DRIVER": {"info_key": "led_matrix.driver"},
"LTO_ENABLE": {"info_key": "build.lto", "value_type": "bool"},
"MCU": {"info_key": "processor", "warn_duplicate": false},
"MOUSEKEY_ENABLE": {"info_key": "mouse_key.enabled", "value_type": "bool"},
"NO_USB_STARTUP_CHECK": {"info_key": "usb.no_startup_check", "value_type": "bool"},
"SPLIT_KEYBOARD": {"info_key": "split.enabled", "value_type": "bool"},
"SPLIT_TRANSPORT": {"info_key": "split.transport.protocol", "value_type": "str", "to_c": false},
"WAIT_FOR_USB": {"info_key": "usb.wait_for", "value_type": "bool"}
}

118
data/mappings/keyboard_aliases.json
View file

@ -11,6 +11,9 @@
'2_milk': {
target: 'spaceman/2_milk'
},
'aeboards/constellation': {
target: 'aeboards/constellation/rev1'
},
'aeboards/ext65': {
target: 'aeboards/ext65/rev1'
},
@ -38,9 +41,36 @@
'atom47/rev3': {
target: 'maartenwut/atom47/rev3'
},
bakeneko65: {
target: 'bakeneko65/rev2'
},
bear_face: {
target: 'bear_face/v1'
},
bm16a: {
target: 'kprepublic/bm16a'
},
bm16s: {
target: 'kprepublic/bm16s'
},
bm40hsrgb: {
target: 'kprepublic/bm40hsrgb'
},
bm43a: {
target: 'kprepublic/bm43a'
},
bm60poker: {
target: 'kprepublic/bm60poker'
},
bm60rgb: {
target: 'kprepublic/bm60rgb'
},
bm60rgb_iso: {
target: 'kprepublic/bm60rgb_iso'
},
bm68rgb: {
target: 'kprepublic/bm68rgb'
},
'bpiphany/pegasushoof': {
target: 'bpiphany/pegasushoof/2013'
},
@ -56,15 +86,27 @@
canoe: {
target: 'percent/canoe'
},
'clawsome/gamebuddy': {
target: 'clawsome/gamebuddy/v1_0'
},
'cmm_studio/saka68': {
target: 'cmm_studio/saka68/solder'
},
'cospad': {
target: 'kprepublic/cospad'
},
'crkbd/rev1/legacy': {
target: 'crkbd/rev1'
},
'crkbd/rev1/common': {
target: 'crkbd/rev1'
},
'custommk/genesis': {
target: 'custommk/genesis/rev1'
},
'daisy': {
target: 'ktec/daisy'
},
'doro67/multi': {
layouts: {
LAYOUT_ansi: 'LAYOUT_65_ansi_blocker'
@ -83,6 +125,9 @@
drakon: {
target: 'jagdpietr/drakon'
},
'durgod/k320': {
target: 'durgod/k3x0/k320'
},
'dztech/dz60rgb': {
target: 'dztech/dz60rgb/v1'
},
@ -95,9 +140,15 @@
'dztech/dz65rgb': {
target: 'dztech/dz65rgb/v1'
},
'dztech/volcano660': {
target: 'ilumkb/volcano660'
},
eek: {
target: 'eek/silk_down'
},
'ergodone': {
target: 'ktec/ergodone'
},
ergoinu: {
target: 'dm9records/ergoinu'
},
@ -107,9 +158,15 @@
gh60: {
target: 'gh60/revc'
},
'gmmk/pro': {
target: 'gmmk/pro/ansi'
},
'handwired/ferris': {
target: 'ferris/0_1'
},
'handwired/p1800fl': {
target: 'team0110/p1800fl'
},
'helix/pico/sc/back': {
target: 'helix/pico/sc'
},
@ -158,6 +215,15 @@
LAYOUT: 'LAYOUT_all'
}
},
'jj40': {
target: 'kprepublic/jj40'
},
'jj4x4': {
target: 'kprepublic/jj4x4'
},
'jj50': {
target: 'kprepublic/jj50'
},
jones: {
target: 'jones/v03_1'
},
@ -182,6 +248,12 @@
kudox: {
target: 'kudox/rev1'
},
'kyria': {
target: 'splitkb/kyria'
},
'lazydesigners/the60': {
target: 'lazydesigners/the60/rev1'
},
'lfkeyboards/lfk78': {
target: 'lfkeyboards/lfk78/revj'
},
@ -251,6 +323,9 @@
'maartenwut/wonderland': {
target: 'evyd13/wonderland'
},
'matrix/m12og': {
target: 'matrix/m12og/rev1'
},
'mechlovin/hannah910': {
target: 'mechlovin/hannah910/rev1'
},
@ -266,6 +341,9 @@
'mechlovin/hannah60rgb': {
target: 'mechlovin/hannah60rgb/rev1'
},
'mechlovin/hannah65/mechlovin9': {
target: 'mechlovin/mechlovin9/rev1'
},
'melgeek/z70ultra': {
target: 'melgeek/z70ultra/rev1'
},
@ -304,6 +382,9 @@
'pancake/promicro': {
target: 'spaceman/pancake/promicro'
},
'peiorisboards/ixora': {
target: 'coarse/ixora'
},
'percent/canoe': {
layouts: {
LAYOUT_iso: 'LAYOUT_65_iso_blocker'
@ -366,6 +447,9 @@
'ramonimbao/herringbone': {
target: 'ramonimbao/herringbone/v1'
},
'ramonimbao/mona': {
target: 'ramonimbao/mona/v1'
},
'rgbkb/pan': {
target: 'rgbkb/pan/rev1/32a'
},
@ -387,6 +471,9 @@
speedo: {
target: 'cozykeys/speedo/v2'
},
'staryu': {
target: 'ktec/staryu'
},
stoutgat: {
target: 'tkw/stoutgat/v1'
},
@ -405,10 +492,14 @@
'tkw/stoutgat/v2': {
target: 'tkw/stoutgat/v2/f411'
},
'tokyo60': {
target: 'tokyokeyboard/tokyo60'
},
underscore33: {
target: 'underscore33/rev1'
},
vinta: {
target: 'coarse/vinta',
layouts: {
LAYOUT_67_ansi: 'LAYOUT_65_ansi_blocker'
}
@ -422,6 +513,33 @@
'whale/sk': {
target: 'whale/sk/v3'
},
'xd002': {
target: 'xiudi/xd002'
},
'xd004': {
target: 'xiudi/xd004'
},
'xd60': {
target: 'xiudi/xd60'
},
'xd68': {
target: 'xiudi/xd68'
},
'xd75': {
target: 'xiudi/xd75'
},
'xd84': {
target: 'xiudi/xd84'
},
'xd84pro': {
target: 'xiudi/xd84pro'
},
'xd87': {
target: 'xiudi/xd87'
},
'xd96': {
target: 'xiudi/xd96'
},
'xelus/dawn60': {
target: 'xelus/dawn60/rev1'
},

44
data/schemas/api_keyboard.jsonschema
View file

@ -1,34 +1,22 @@
{
"$id": "qmk.api.keyboard.v1",
"allOf": [
{ "$ref": "qmk.keyboard.v1" },
{"$ref": "qmk.keyboard.v1"},
{
"$id": "qmk.api.keyboard.v1",
"keymaps": {
"type": "string"
},
"parse_errors": {
"type": "array",
"items": {
"type": "string"
}
},
"parse_warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"processor_type": {
"type": "string"
},
"protocol": {
"type": "string"
},
"keyboard_folder": {
"type": "string"
},
"platform": {
"type": "string"
"properties": {
"keymaps": {
"type": "object",
"properties": {
"url": {"type": "string"}
}
},
"parse_errors": {"$ref": "qmk.definitions.v1#/string_array"},
"parse_warnings": {"$ref": "qmk.definitions.v1#/string_array"},
"processor_type": {"type": "string"},
"protocol": {"type": "string"},
"keyboard_folder": {"type": "string"},
"platform": {"type": "string"}
}
}
]

107
data/schemas/definitions.jsonschema Normal file
View file

@ -0,0 +1,107 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "qmk.definitions.v1",
"title": "Common definitions used across QMK's jsonschemas.",
"type": "object",
"boolean_array": {
"type": "object",
"additionalProperties": {"type": "boolean"}
},
"filename": {
"type": "string",
"minLength": 1,
"pattern": "^[0-9a-z_]*$"
},
"hex_number_2d": {
"type": "string",
"pattern": "^0x[0-9A-F]{2}$"
},
"hex_number_4d": {
"type": "string",
"pattern": "^0x[0-9A-F]{4}$"
},
"text_identifier": {
"type": "string",
"minLength": 1,
"maxLength": 250
},
"layout_macro": {
"oneOf": [
{
"type": "string",
"enum": ["LAYOUT", "LAYOUT_planck_1x2uC"]
},
{
"type": "string",
"pattern": "^LAYOUT_[0-9a-z_]*$"
}
]
},
"key_unit": {
"type": "number",
"min": 0.25
},
"mcu_pin_array": {
"type": "array",
"items": {"$ref": "#/mcu_pin"}
},
"mcu_pin": {
"oneOf": [
{
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
{
"type": "string",
"pattern": "^LINE_PIN\\d{1,2}$"
},
{
"type": "number",
"multipleOf": 1
},
{
"type": "null"
}
]
},
"signed_decimal": {
"type": "number"
},
"signed_int": {
"type": "number",
"multipleOf": 1
}
"signed_int_8": {
"type": "number",
"min": -127,
"max": 127,
"multipleOf": 1
}
"string_array": {
"type": "array",
"items": {
"type": "string"
}
},
"string_object": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"unsigned_decimal": {
"type": "number",
"min": 0
},
"unsigned_int": {
"type": "number",
"min": 0,
"multipleOf": 1
}
"unsigned_int_8": {
"type": "number",
"min": 0,
"max": 255,
"multipleOf": 1
}
}

457
data/schemas/keyboard.jsonschema
View file

@ -1,31 +1,53 @@
{
"$schema": "http://json-schema.org/schema#",
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "qmk.keyboard.v1",
"title": "Keyboard Information",
"type": "object",
"properties": {
"keyboard_name": {
"type": "string",
"minLength": 2,
"maxLength": 250
},
"maintainer": {
"type": "string",
"minLength": 2,
"maxLength": 250
},
"manufacturer": {
"type": "string",
"minLength": 2,
"maxLength": 250
},
"keyboard_name": {"$ref": "qmk.definitions.v1#/text_identifier"},
"maintainer": {"$ref": "qmk.definitions.v1#/text_identifier"},
"manufacturer": {"$ref": "qmk.definitions.v1#/text_identifier"},
"url": {
"type": "string",
"format": "uri"
},
"processor": {
"type": "string",
"enum": ["cortex-m0", "cortex-m0plus", "cortex-m3", "cortex-m4", "MKL26Z64", "MK20DX128", "MK20DX256", "MK66F18", "STM32F042", "STM32F072", "STM32F103", "STM32F303", "STM32F401", "STM32F411", "STM32F446", "STM32G431", "STM32G474", "STM32L433", "STM32L443", "atmega16u2", "atmega32u2", "atmega16u4", "atmega32u4", "at90usb162", "at90usb646", "at90usb647", "at90usb1286", "at90usb1287", "atmega32a", "atmega328p", "atmega328", "attiny85", "unknown"]
"enum": ["cortex-m0", "cortex-m0plus", "cortex-m3", "cortex-m4", "MKL26Z64", "MK20DX128", "MK20DX256", "MK66F18", "STM32F042", "STM32F072", "STM32F103", "STM32F303", "STM32F401", "STM32F407", "STM32F411", "STM32F446", "STM32G431", "STM32G474", "STM32L412", "STM32L422", "STM32L433", "STM32L443", "atmega16u2", "atmega32u2", "atmega16u4", "atmega32u4", "at90usb162", "at90usb646", "at90usb647", "at90usb1286", "at90usb1287", "atmega32a", "atmega328p", "atmega328", "attiny85", "unknown"]
},
"audio": {
"type": "object",
"additionalProperties": false,
"properties": {
"pins": {"$ref": "qmk.definitions.v1#/mcu_pin_array"},
"voices": {"type": "boolean"}
}
},
"backlight": {
"type": "object",
"additionalProperties": false,
"properties": {
"breathing": {"type": "boolean"},
"breathing_period": {"$ref": "qmk.definitions.v1#/unsigned_int_8"},
"levels": {
"type": "number",
"min": 1,
"max": 31,
"multipleOf": 1
},
"pin": {"$ref": "qmk.definitions.v1#/mcu_pin"}
}
},
"bluetooth": {
"type": "object",
"additionalProperties": false,
"properties": {
"driver": {
"type": "string",
"enum": ["AdafruitBLE", "RN42"]
},
"lto": {"type": "boolean"},
}
},
"board": {
"type": "string",
@ -34,68 +56,55 @@
},
"bootloader": {
"type": "string",
"enum": ["atmel-dfu", "bootloadHID", "caterina", "halfkay", "kiibohd", "lufa-dfu", "lufa-ms", "micronucleus", "qmk-dfu", "stm32-dfu", "stm32duino", "unknown", "USBasp", "tinyuf2"]
"enum": ["atmel-dfu", "bootloadHID", "caterina", "halfkay", "kiibohd", "lufa-dfu", "lufa-ms", "micronucleus", "qmk-dfu", "qmk-hid", "stm32-dfu", "stm32duino", "unknown", "USBasp", "tinyuf2"],
},
"bootloader_instructions": {
"type": "string",
"description": "Instructions for putting the keyboard into a mode that allows for firmware flashing."
},
"build": {
"type": "object",
"additionalProperties": false,
"properties": {
"debounce_type": {
"type": "string",
"enum": ["custom", "eager_pk", "eager_pr", "sym_defer_pk", "sym_eager_pk"]
},
"firmware_format": {
"type": "string",
"enum": ["bin", "hex", "uf2"]
},
"lto": {"type": "boolean"},
}
},
"diode_direction": {
"type": "string",
"enum": ["COL2ROW", "ROW2COL"]
},
"debounce": {
"type": "number",
"min": 0,
"multipleOf": 1
},
"height": {
"type": "number",
"min": 0.25
},
"width": {
"type": "number",
"min": 0.25
"debounce": {"$ref": "qmk.definitions.v1#/unsigned_int"},
"combo": {
"type": "object",
"properties": {
"count": {"$ref": "qmk.definitions.v1#/unsigned_int"},
"term": {"$ref": "qmk.definitions.v1#/unsigned_int"}
}
},
"community_layouts": {
"type": "array",
"items": {
"type": "string",
"minLength": 2,
"pattern": "^[0-9a-z_]*$"
}
},
"features": {
"type": "object",
"additionalProperties": {"type": "boolean"}
"items": {"$ref": "qmk.definitions.v1#/filename"}
},
"features": {"$ref": "qmk.definitions.v1#/boolean_array"},
"indicators": {
"type": "object",
"properties": {
"caps_lock": {
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
"num_lock": {
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
"scroll_lock": {
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
}
"caps_lock": {"$ref": "qmk.definitions.v1#/mcu_pin"},
"num_lock": {"$ref": "qmk.definitions.v1#/mcu_pin"},
"scroll_lock": {"$ref": "qmk.definitions.v1#/mcu_pin"}
}
},
"layout_aliases": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "string",
"enum": ["LAYOUT", "LAYOUT_planck_1x2uC"]
},
{
"type": "string",
"pattern": "^LAYOUT_[0-9a-z_]*$"
}
]
}
"additionalProperties": {"$ref": "qmk.definitions.v1#/layout_macro"}
},
"layouts": {
"type": "object",
@ -109,11 +118,7 @@
"c_macro": {
"type": "boolean"
},
"key_count": {
"type": "number",
"min": 0,
"multipleOf": 1
},
"key_count": {"$ref": "qmk.definitions.v1#/key_unit"},
"layout": {
"type": "array",
"items": {
@ -131,101 +136,61 @@
"multipleOf": 1
}
},
"h": {
"type": "number",
"min": 0.25
},
"r": {
"type": "number",
"min": 0
},
"rx": {
"type": "number",
"min": 0
},
"ry": {
"type": "number",
"min": 0
},
"w": {
"type": "number",
"min": 0.25
},
"x": {
"type": "number",
"min": 0
},
"y": {
"type": "number",
"min": 0
}
"key_count": {"$ref": "qmk.definitions.v1#/key_unit"},
"r": {"$ref": "qmk.definitions.v1#/unsigned_decimal"},
"rx": {"$ref": "qmk.definitions.v1#/unsigned_decimal"},
"ry": {"$ref": "qmk.definitions.v1#/unsigned_decimal"},
"h": {"$ref": "qmk.definitions.v1#/key_unit"},
"w": {"$ref": "qmk.definitions.v1#/key_unit"},
"x": {"$ref": "qmk.definitions.v1#/key_unit"},
"y": {"$ref": "qmk.definitions.v1#/key_unit"}
}
}
}
}
}
},
"leader_key": {
"type": "object",
"properties": {
"timing": {"type": "boolean"},
"strict_processing": {"type": "boolean"},
"timeout": {"$ref": "qmk.definitions.v1#/unsigned_int"}
}
},
"matrix_pins": {
"type": "object",
"additionalProperties": false,
"properties": {
"custom": {"type": "boolean"},
"custom_lite": {"type": "boolean"},
"ghost": {"type": "boolean"},
"io_delay": {"$ref": "qmk.definitions.v1#/unsigned_int"},
"direct": {
"type": "array",
"items": {
"type": "array",
"items": {
"oneOf": [
{
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
{
"type": "number",
"multipleOf": 1
},
{
"type": "null"
}
]
}
}
"items": {"$ref": "qmk.definitions.v1#/mcu_pin_array"}
},
"cols": {
"type": "array",
"items": {
"oneOf": [
{
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
{
"type": "number",
"multipleOf": 1
},
{
"type": "null"
}
]
}
},
"rows": {
"type": "array",
"items": {
"oneOf": [
{
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
{
"type": "number",
"multipleOf": 1
},
{
"type": "null"
}
]
}
}
"cols": {"$ref": "qmk.definitions.v1#/mcu_pin_array"},
"rows": {"$ref": "qmk.definitions.v1#/mcu_pin_array"},
"unused": {"$ref": "qmk.definitions.v1#/mcu_pin_array"}
}
},
"mouse_key": {
"type": "object",
"properties": {
"enabled": {"type": "boolean"},
"delay": {"$ref": "qmk.definitions.v1#/unsigned_int_8"}
"interval": {"$ref": "qmk.definitions.v1#/unsigned_int_8"}
"max_speed": {"$ref": "qmk.definitions.v1#/unsigned_int_8"}
"time_to_max": {"$ref": "qmk.definitions.v1#/unsigned_int_8"}
"wheel_delay": {"$ref": "qmk.definitions.v1#/unsigned_int_8"}
}
},
"oneshot": {
"type": "object",
"properties": {
"tap_toggle": {"$ref": "qmk.definitions.v1#/unsigned_int"},
"timeout": {"$ref": "qmk.definitions.v1#/unsigned_int"}
}
},
"rgblight": {
@ -238,88 +203,160 @@
"type": "boolean"
}
},
"brightness_steps": {
"type": "number",
"min": 0,
"multipleOf": 1
},
"hue_steps": {
"type": "number",
"min": 0,
"multipleOf": 1
},
"led_count": {
"type": "number",
"min": 0,
"multipleOf": 1
},
"max_brightness": {
"type": "number",
"min": 0,
"max": 255,
"multipleOf": 1
},
"pin": {
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
"saturation_steps": {
"type": "number",
"min": 0,
"multipleOf": 1
"brightness_steps": {"$ref": "qmk.definitions.v1#/unsigned_int"},
"hue_steps": {"$ref": "qmk.definitions.v1#/unsigned_int"},
"layers": {
"type": "object",
"additionalProperties": false,
"properties": {
"blink": {"type": "boolean"},
"enabled": {"type": "boolean"},
"max": {
"type": "number",
"min": 1,
"max": 32,
"multipleOf": 1
},
"override_rgb": {"type": "boolean"}
}
},
"led_count": {"$ref": "qmk.definitions.v1#/unsigned_int"},
"max_brightness": {"$ref": "qmk.definitions.v1#/unsigned_int_8"},
"pin": {"$ref": "qmk.definitions.v1#/mcu_pin"},
"rgbw": {"type": "boolean"},
"saturation_steps": {"$ref": "qmk.definitions.v1#/unsigned_int"},
"sleep": {"type": "boolean"},
"split": {"type": "boolean"},
"split_count": {
"type": "array",
"minLength": 2,
"maxLength": 2,
"items": {
"type": "number",
"min": 0,
"multipleOf": 1
"items": {"$ref": "qmk.definitions.v1#/unsigned_int"}
}
}
},
"split": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": {"type": "boolean"},
"matrix_grid": {
"type": "array",
"items": {"$ref": "qmk.definitions.v1#/mcu_pin"}
},
"matrix_pins": {
"type": "object",
"additionalProperties": false,
"properties": {
"right": {
"type": "object",
"additionalProperties": false,
"properties": {
"direct": {
"type": "array",
"items": {"$ref": "qmk.definitions.v1#/mcu_pin_array"}
},
"cols": {"$ref": "qmk.definitions.v1#/mcu_pin_array"},
"rows": {"$ref": "qmk.definitions.v1#/mcu_pin_array"},
"unused": {"$ref": "qmk.definitions.v1#/mcu_pin_array"}
}
}
}
},
"main": {
"type": "string",
"enum": ["eeprom", "left", "matrix_grid", "pin", "right"]
},
"soft_serial_pin": {"$ref": "qmk.definitions.v1#/mcu_pin"},
"soft_serial_speed": {
"type": "number",
"min": 0,
"max": 5,
"multipleOf": 1
},
"transport": {
"type": "object",
"additionalProperties": false,
"properties": {
"protocol": {
"type": "string",
"enum": ["custom", "i2c", "serial", "serial_usart"]
},
"sync_matrix_state": {"type": "boolean"},
"sync_modifiers": {"type": "boolean"}
}
},
"usb_detect": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": {"type": "boolean"},
"polling_interval": {"$ref": "qmk.definitions.v1#/unsigned_int"},
"timeout": {"$ref": "qmk.definitions.v1#/unsigned_int"}
}
}
}
},
"tags": {
"type": "array",
"items": {"type": "string"}
},
"tapping": {
"type": "object",
"properties": {
"force_hold": {"type": "boolean"},
"force_hold_per_key": {"type": "boolean"},
"ignore_mod_tap_interrupt": {"type": "boolean"},
"ignore_mod_tap_interrupt_per_key": {"type": "boolean"},
"permissive_hold": {"type": "boolean"},
"permissive_hold_per_key": {"type": "boolean"},
"retro": {"type": "boolean"},
"retro_per_key": {"type": "boolean"},
"term": {"$ref": "qmk.definitions.v1#/unsigned_int"},
"term_per_key": {"type": "boolean"},
"toggle": {"$ref": "qmk.definitions.v1#/unsigned_int"},
}
},
"usb": {
"type": "object",
"additionalProperties": false,
"properties": {
"device_ver": {
"type": "string",
"pattern": "^[0-9A-F]x[0-9A-F][0-9A-F][0-9A-F][0-9A-F]"
"device_ver": {"$ref": "qmk.definitions.v1#/hex_number_4d"},
"force_nkro": {"type": "boolean"},
"pid": {"$ref": "qmk.definitions.v1#/hex_number_4d"},
"vid": {"$ref": "qmk.definitions.v1#/hex_number_4d"},
"max_power": {"$ref": "qmk.definitions.v1#/unsigned_int_8"},
"no_startup_check": {"type": "boolean"},
"polling_interval": {"$ref": "qmk.definitions.v1#/unsigned_int_8"},
"shared_endpoint": {
"type": "object",
"additionalProperties": false,
"properties": {
"keyboard": {"type": "boolean"},
"mouse": {"type": "boolean"}
}
},
"pid": {
"type": "string",
"pattern": "^[0-9A-F]x[0-9A-F][0-9A-F][0-9A-F][0-9A-F]"
},
"vid": {
"type": "string",
"pattern": "^[0-9A-F]x[0-9A-F][0-9A-F][0-9A-F][0-9A-F]"
}
"suspend_wakeup_delay": {"$ref": "qmk.definitions.v1#/unsigned_int_8"},
"wait_for": {"type": "boolean"},
}
},
"qmk": {
"type": "object",
"additionalProperties": false,
"properties": {
"keys_per_scan": {"$ref": "qmk.definitions.v1#/unsigned_int_8"},
"tap_keycode_delay": {"$ref": "qmk.definitions.v1#/unsigned_int_8"},
"tap_capslock_delay": {"$ref": "qmk.definitions.v1#/unsigned_int_8"},
}
},
"qmk_lufa_bootloader": {
"type": "object",
"additionalProperties": false,
"properties": {
"esc_output": {
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
"esc_input": {
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
"led": {
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
"speaker": {
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
}
"esc_output": {"$ref": "qmk.definitions.v1#/mcu_pin"},
"esc_input": {"$ref": "qmk.definitions.v1#/mcu_pin"},
"led": {"$ref": "qmk.definitions.v1#/mcu_pin"},
"speaker": {"$ref": "qmk.definitions.v1#/mcu_pin"}
}
}
}

24
data/schemas/keymap.jsonschema Normal file
View file

@ -0,0 +1,24 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "qmk.keymap.v1",
"title": "Keymap Information",
"type": "object",
"properties": {
"author": {"type": "string"},
"keyboard": {"$ref": "qmk.definitions.v1#/text_identifier"},
"keymap": {"$ref": "qmk.definitions.v1#/text_identifier"},
"layout": {"$ref": "qmk.definitions.v1#/layout_macro"},
"layers": {
"type": "array",
"items": {
"type": "array",
"items": {"type": "string"}
}
},
"config": {"$ref": "qmk.keyboard.v1"},
"notes": {
"type": "string",
"description": "asdf"
}
}
}

0
quantum/template/avr/config.h → data/templates/avr/config.h
View file

0
quantum/template/avr/readme.md → data/templates/avr/readme.md
View file

2
quantum/template/avr/rules.mk → data/templates/avr/rules.mk
View file

@ -7,7 +7,7 @@ BOOTLOADER = atmel-dfu
# Build Options
# change yes to no to disable
#
BOOTMAGIC_ENABLE = lite # Virtual DIP switch configuration
BOOTMAGIC_ENABLE = yes # Enable Bootmagic Lite
MOUSEKEY_ENABLE = yes # Mouse keys
EXTRAKEY_ENABLE = yes # Audio control and System control
CONSOLE_ENABLE = no # Console for debug

0
quantum/template/base/info.json → data/templates/base/info.json
View file

0
quantum/template/base/keyboard.c → data/templates/base/keyboard.c
View file

0
quantum/template/base/keyboard.h → data/templates/base/keyboard.h
View file

0
quantum/template/base/keymaps/default/keymap.c → data/templates/base/keymaps/default/keymap.c
View file

0
quantum/template/base/keymaps/default/readme.md → data/templates/base/keymaps/default/readme.md
View file

0
quantum/template/ps2avrgb/config.h → data/templates/ps2avrgb/config.h
View file

0
quantum/template/ps2avrgb/readme.md → data/templates/ps2avrgb/readme.md
View file

2
quantum/template/ps2avrgb/rules.mk → data/templates/ps2avrgb/rules.mk
View file

@ -7,7 +7,7 @@ BOOTLOADER = bootloadHID
# Build Options
# change yes to no to disable
#
BOOTMAGIC_ENABLE = lite # Virtual DIP switch configuration
BOOTMAGIC_ENABLE = yes # Enable Bootmagic Lite
MOUSEKEY_ENABLE = yes # Mouse keys
EXTRAKEY_ENABLE = yes # Audio control and System control
CONSOLE_ENABLE = no # Console for debug

557
docs/ChangeLog/20210828.md Normal file
View file

@ -0,0 +1,557 @@
# QMK Breaking Changes - 2021 August 28 Changelog
## Notable Features :id=notable-features
### Combo processing improvements ([#8591](https://github.com/qmk/qmk_firmware/pull/8591)) :id=combo-processing-improvements
Combo processing has been reordered with respect to keypress handling, allowing for much better compatibility with mod taps.
It is also now possible to define combos that have keys overlapping with other combos, triggering only one. For example, a combo of `A`, `B` can coexist with a longer combo of `A`, `B`, `C` -- previous functionality would trigger both combos if all three keys were pressed.
### Key Overrides ([#11422](https://github.com/qmk/qmk_firmware/pull/11422)) :id=key-overrides
QMK now has a new feature: [key overrides](https://docs.qmk.fm/#/feature_key_overrides). This feature allows for overriding the output of key combinations involving modifiers. As an example, pressing <kbd>Shift+2</kbd> normally results in an <kbd>@</kbd> on US-ANSI keyboard layouts -- the new key overrides allow for adding similar functionality, but for any <kbd>modifier + key</kbd> press.
To illustrate, it's now possible to use the key overrides feature to translate <kbd>Shift + Backspace</kbd> into <kbd>Delete</kbd> -- an often-requested example of where this functionality comes in handy.
There's far more to describe that what lives in this changelog, so head over to the [key overrides documentation](https://docs.qmk.fm/#/feature_key_overrides) for more examples and info.
### Digitizer support ([#12851](https://github.com/qmk/qmk_firmware/pull/12851))
QMK gained the ability to pretend to be a digitizer device -- much like a tablet device. A mouse uses delta-coordinates -- move up, move right -- but a digitizer works with absolute coordinates -- top left, bottom right.
## Changes Requiring User Action :id=changes-requiring-user-action
### Updated Keyboard Codebases :id=updated-keyboard-codebases
The following keyboards have had their source moved within QMK:
Old Keyboard Name | New Keyboard Name
------------------------------|---------------------------------------------------------
aeboards/constellation | aeboards/constellation/rev1, aeboards/constellation/rev2
bakeneko65 | bakeneko65/rev2, bakeneko65/rev3
bm16a | kprepublic/bm16a
bm16s | kprepublic/bm16s
bm40hsrgb | kprepublic/bm40hsrgb
bm43a | kprepublic/bm43a
bm60poker | kprepublic/bm60poker
bm60rgb | kprepublic/bm60rgb
bm60rgb_iso | kprepublic/bm60rgb_iso
bm68rgb | kprepublic/bm68rgb
clawsome/gamebuddy | clawsome/gamebuddy/v1_0, clawsome/gamebuddy/v1_m
cospad | kprepublic/cospad
custommk/genesis | custommk/genesis/rev1, custommk/genesis/rev2
daisy | ktec/daisy
durgod/k320 | durgod/k3x0/k320
dztech/volcano660 | ilumkb/volcano660
ergodone | ktec/ergodone
gmmk/pro | gmmk/pro/ansi, gmmk/pro/iso
handwired/p1800fl | team0110/p1800fl
jj40 | kprepublic/jj40
jj4x4 | kprepublic/jj4x4
jj50 | kprepublic/jj50
kyria | splitkb/kyria
lazydesigners/the60 | lazydesigners/the60/rev1, lazydesigners/the60/rev2
matrix/m12og | matrix/m12og/rev1, matrix/m12og/rev2
mechlovin/hannah65/mechlovin9 | mechlovin/mechlovin9/rev1, mechlovin/mechlovin9/rev2
peiorisboards/ixora | coarse/ixora
ramonimbao/mona | ramonimbao/mona/v1, ramonimbao/mona/v1_1
staryu | ktec/staryu
tokyo60 | tokyokeyboard/tokyo60
vinta | coarse/vinta
xd002 | xiudi/xd002
xd004 | xiudi/xd004
xd60 | xiudi/xd60
xd68 | xiudi/xd68
xd75 | xiudi/xd75
xd84 | xiudi/xd84
xd84pro | xiudi/xd84pro
xd87 | xiudi/xd87
xd96 | xiudi/xd96
### Bootmagic Full Removal ([#13846](https://github.com/qmk/qmk_firmware/pull/13846)) :id=bootmagic-full-removal
As noted during last breaking changes cycle, QMK has decided to deprecate the full Bootmagic feature and leave Bootmagic Lite as the only remaining option.
This pull request changes the behavior of `BOOTMAGIC_ENABLE` such that specifying `full` results in an error, allowing only `no`, `yes`, or `lite`.
Next cycle, `lite` will be removed, so `yes` and `no` should be used in to minimise disruption.
#### Bootmagic Full Deprecation Schedule
This is the current roadmap for the behavior of `BOOTMAGIC_ENABLE`:
- (done) From 2021 May 29, setting `BOOTMAGIC_ENABLE = yes` will enable Bootmagic Lite instead of full Bootmagic.
- (now) From 2021 Aug 28, `BOOTMAGIC_ENABLE` must be either `yes`, `lite`, or `no` – setting `BOOTMAGIC_ENABLE = full` will cause compilation to fail.
- (next) From 2021 Nov 27, `BOOTMAGIC_ENABLE` must be either `yes` or `no` – setting `BOOTMAGIC_ENABLE = lite` will cause compilation to fail.
### DIP switch callbacks are now boolean ([#13399](https://github.com/qmk/qmk_firmware/pull/13399)) :id=dip-switch-boolean
To match the encoder change last breaking changes cycle, DIP switch callbacks now return `bool`, too.
Example code before change:
```c
void dip_switch_update_kb(uint8_t index, bool active) {
dip_switch_update_user(index, active);
}
void dip_switch_update_user(uint8_t index, bool active) {
switch (index) {
case 0:
if(active) { audio_on(); } else { audio_off(); }
break;
}
}
void dip_switch_update_mask_kb(uint32_t state) {
dip_switch_update_mask_user(state);
}
void dip_switch_update_mask_user(uint32_t state) {
if (state & (1UL<<0) && state & (1UL<<1)) {
layer_on(_ADJUST); // C on esc
} else {
layer_off(_ADJUST);
}
}
```
Example code after change:
```c
bool dip_switch_update_kb(uint8_t index, bool active) {
if !(dip_switch_update_user(index, active)) { return false; }
return true;
}
bool dip_switch_update_user(uint8_t index, bool active) {
switch (index) {
case 0:
if(active) { audio_on(); } else { audio_off(); }
break;
}
return true; // Returning true allows keyboard code to execute, false will tell the keyboard code "I've already handled it".
}
bool dip_switch_update_mask_kb(uint32_t state) {
if (!dip_switch_update_mask_user(state)) { return false; }
return true;
}
bool dip_switch_update_mask_user(uint32_t state) {
if (state & (1UL<<0) && state & (1UL<<1)) {
layer_on(_ADJUST); // C on esc
} else {
layer_off(_ADJUST);
}
return true; // Returning true allows keyboard code to execute, false will tell the keyboard code "I've already handled it".
}
```
## Notable core changes :id=notable-core
### Split transport improvements :id=split-transport-improvements
Split keyboards gained a significant amount of improvements during this breaking changes cycle, specifically:
* Extensible split data sync ([#11930](https://github.com/qmk/qmk_firmware/pull/11930)) -- rewritten data sharing between sides, allowing for data transfer only when required, as well as enabling keyboards and keymaps to define their own shared data.
* Full-duplex ARM USART split ([#13081](https://github.com/qmk/qmk_firmware/pull/13081)) -- adds to the previous half-duplex driver and now allows for full-duplex support on ARM.
* Make solo half of split keyboards (more) usable. ([#13523](https://github.com/qmk/qmk_firmware/pull/13523)) -- allows the slave to be disconnected, enabling one-handed use.
* Switch split_common to CRC subsystem ([#13418](https://github.com/qmk/qmk_firmware/pull/13418))
!> If you're updating your split keyboard, you will need to flash both sides of the split with the your firmware.
### Teensy 4.x support ([#13056](https://github.com/qmk/qmk_firmware/pull/13056), [#13076](https://github.com/qmk/qmk_firmware/pull/13076), [#13077](https://github.com/qmk/qmk_firmware/pull/13077)) :id=teensy-4-x-support
Updated ChibiOS and ChibiOS-Contrib, which brought in support for Teensy 4.x dev boards, running NXP i.MX1062.
### Data Driven Improvements ([#13366](https://github.com/qmk/qmk_firmware/pull/13366))
QMK's pursuit of data-driven keyboards has progressed, allowing substantially more configurable options to be specified in `info.json`.
#### Tags
Tags will let you categorize your keyboard, and will be used in the future to allow browsing and sorting through keyboards in QMK. Tags are free-form text identifiers that identify attributes about your keyboard. To add tags you simply add a `tags` key to your `info.json`:
"tags": ["tkl", "backlight", "encoder"]
#### Dot Notation
With this release we are moving towards using JSON dot notation in more places. For example, when using `qmk info -f text`:
```
$ qmk info -f text -kb clueboard/card
bootloader: atmel-dfu
debounce: 20
diode_direction: ROW2COL
features.audio: True
features.backlight: True
features.bluetooth: False
features.bootmagic: False
features.command: True
features.console: True
features.extrakey: True
features.lto: True
features.midi: False
features.mousekey: True
features.nkro: False
features.rgblight: True
features.unicode: False
height: 8
keyboard_folder: clueboard/card
keyboard_name: Cluecard
layout_aliases.LAYOUT: LAYOUT_all
layouts: LAYOUT_all
maintainer: skullydazed
manufacturer: Clueboard
matrix_pins.cols: F1, F6, F7
matrix_pins.rows: B4, F0, F4, F5
platform: unknown
processor: atmega32u4
processor_type: avr
protocol: LUFA
rgblight.brightness_steps: 17
rgblight.hue_steps: 10
rgblight.led_count: 4
rgblight.pin: E6
rgblight.saturation_steps: 17
split.transport.protocol: serial
usb.device_ver: 0x0001
usb.pid: 0x2330
usb.vid: 0xC1ED
width: 10
```
#### New configuration keys
We've added dozens of new keys to `info.json` so that you can configure more than ever without writing a single line of code. A quick overview of the new items you can configure:
* `audio.pins`, `audio.voices`
* `backlight.breathing`, `backlight.breathing_period`, `backlight.levels`, `backlight.pin`,
* `bluetooth.driver`, `bluetooth.lto`
* `bootloader_instructions`
* `build.debounce_type`, `build.firmware_format`, `build.lto`
* `combo.count`, `combo.term`
* `leader_key.timing`, `leader_key.strict_processing`, `leader_key.timeout`
* `matrix.custom`, `matrix.custom_lite`, `matrix.ghost`, `matrix.io_delay`
* `mouse_key.enabled`, `mouse_key.delay`, `mouse_key.interval`, `mouse_key.max_speed`, `mouse_key.time_to_max`, `mouse_key.wheel_delay`
* `oneshot.tap_toggle`, `oneshot.timeout`
* `rgblight.layers.blink`, `rgblight.layers.enabled`, `rgblight.layers.max`, `rgblight.layers.override_rgb`, `rgblight.rgbw`
* `split.enabled`, `split.matrix_grid`, `split.matrix_pins`, `split.main`, `split.soft_serial_pin`, `split.soft_serial_speed`, `split.transport.protocol`, `split.transport.sync_matrix_state`, `split.transport.sync_modifiers`, `split.usb_detect`
* `tapping.force_hold`, `tapping.force_hold_per_key`, `tapping.ignore_mod_tap_interrupt`, `tapping.ignore_mod_tap_interrupt_per_key`, `tapping.permissive_hold`, `tapping.permissive_hold_per_key`, `tapping.retro`, `tapping.retro_per_key`, `tapping.term`, `tapping.term_per_key`, `tapping.toggle`
* `usb.force_nkro`, `usb.max_power`, `usb.no_startup_check`, `usb.polling_interval`, `usb.shared_endpoint.keyboard`, `usb.shared_endpoint.mouse`, `usb.suspend_wakeup_delay`, `usb.wait_for`
* `qmk.keys_per_scan`, `qmk.tap_keycode_delay`, `qmk.tap_capslock_delay`
### Codebase restructure and cleanup :id=codebase-restructure
QMK was originally based on TMK, and has grown in size considerably since its first inception. To keep moving things forward, restructure of some of the core areas of the code is needed to support new concepts and new hardware, and progress is happening along those lines:
* Move RGBLight code into its own folder ([#13312](https://github.com/qmk/qmk_firmware/pull/13312))
* Migrate platform independent code from tmk_core -> quantum ([#13673](https://github.com/qmk/qmk_firmware/pull/13673))
* matrix_scan_x -> x_task ([#13748](https://github.com/qmk/qmk_firmware/pull/13748))
* Move some led drivers to common folder ([#13749](https://github.com/qmk/qmk_firmware/pull/13749))
* Move chibios board files to allow tmk_core platform migration ([#13777](https://github.com/qmk/qmk_firmware/pull/13777))
* Begin to carve out platform/protocol API - Single main loop ([#13843](https://github.com/qmk/qmk_firmware/pull/13843))
* Relocate platform specific drivers ([#13894](https://github.com/qmk/qmk_firmware/pull/13894))
* Move all the flash logic from tmk_core ([#13927](https://github.com/qmk/qmk_firmware/pull/13927))
* Move USB Host Shield and Arduino core to `lib/` ([#13973](https://github.com/qmk/qmk_firmware/pull/13973))
* Unify behaviour of wait on AVR ([#14025](https://github.com/qmk/qmk_firmware/pull/14025))
* Move nix folder alongside vagrant ([#14132](https://github.com/qmk/qmk_firmware/pull/14132))
* Align some quantum sub-directories ([#14134](https://github.com/qmk/qmk_firmware/pull/14134))
---
## Full changelist
Core:
* Arm ps2 mouse interrupt ([#6490](https://github.com/qmk/qmk_firmware/pull/6490))
* Process combos earlier & overlapping combos ([#8591](https://github.com/qmk/qmk_firmware/pull/8591))
* Swap buttons on PS2 Mouse/Trackball ([#9205](https://github.com/qmk/qmk_firmware/pull/9205))
* Add HOLD_ON_OTHER_KEY_PRESS option for dual-role keys ([#9404](https://github.com/qmk/qmk_firmware/pull/9404))
* add yaml_build_options target ([#10533](https://github.com/qmk/qmk_firmware/pull/10533))
* Warn when building a board that uses arm_atsam ([#10904](https://github.com/qmk/qmk_firmware/pull/10904))
* Key Overrides ([#11422](https://github.com/qmk/qmk_firmware/pull/11422))
* Refactor `quantum/command.{c,h}` for code size & {read,maintain}ability ([#11842](https://github.com/qmk/qmk_firmware/pull/11842))
* Extensible split data sync ([#11930](https://github.com/qmk/qmk_firmware/pull/11930))
* Move print/debug files to quantum ([#12069](https://github.com/qmk/qmk_firmware/pull/12069))
* Unconditionally call led_init_ports ([#12116](https://github.com/qmk/qmk_firmware/pull/12116))
* Support using a timer for wait_us() on ChibiOS-based boards ([#12211](https://github.com/qmk/qmk_firmware/pull/12211))
* Add support for NO_PIN to all matrix types ([#12238](https://github.com/qmk/qmk_firmware/pull/12238))
* Avoid 8-bit timer overflows in debounce algorithms ([#12240](https://github.com/qmk/qmk_firmware/pull/12240))
* Add Per Key exclusions for Haptic Feedback ([#12386](https://github.com/qmk/qmk_firmware/pull/12386))
* Steno combinedkeys ([#12538](https://github.com/qmk/qmk_firmware/pull/12538))
* eeprom_stm32: implement high density wear leveling ([#12567](https://github.com/qmk/qmk_firmware/pull/12567))
* eeprom_i2c driver: added EXTERNAL_EEPROM_WP_PIN configuration option. ([#12617](https://github.com/qmk/qmk_firmware/pull/12617))
* Add CRC8 calculation subsystem to quantum ([#12641](https://github.com/qmk/qmk_firmware/pull/12641))
* Limit saturation for RGB_MATRIX_JELLYBEAN_RAINDROPS ([#12669](https://github.com/qmk/qmk_firmware/pull/12669))
* Add asym_eager_defer_pk debounce type ([#12689](https://github.com/qmk/qmk_firmware/pull/12689))
* Include lib8tion.c into RGB/LED matrix build list ([#12699](https://github.com/qmk/qmk_firmware/pull/12699))
* Add readPort() and some API to 'tmk_core/common/*/gpio.h' ([#12754](https://github.com/qmk/qmk_firmware/pull/12754))
* add wait_cpuclock() macro for AVR and CPU_CLOCK macro ([#12755](https://github.com/qmk/qmk_firmware/pull/12755))
* Trigger a wakeup after USB Reset on ChibiOS. ([#12831](https://github.com/qmk/qmk_firmware/pull/12831))
* Add sync_timer support over serial_link (i.e. Ergodox Infinity) ([#12845](https://github.com/qmk/qmk_firmware/pull/12845))
* Digitizer HID interface : absolute coordinates for mouse cursor ([#12851](https://github.com/qmk/qmk_firmware/pull/12851))
* Add config.h and rules.mk support for data driven keymaps ([#12859](https://github.com/qmk/qmk_firmware/pull/12859))
* Add alternate ldscript for STM32duino (F103xB) ([#12914](https://github.com/qmk/qmk_firmware/pull/12914))
* `keymap_extras`: Remove deprecated defines ([#12949](https://github.com/qmk/qmk_firmware/pull/12949))
* Retain brightness with lighting layers ([#13025](https://github.com/qmk/qmk_firmware/pull/13025))
* Move optical sensor code to drivers folder ([#13044](https://github.com/qmk/qmk_firmware/pull/13044))
* Change the prototype of matrix_output_unselect_delay() ([#13045](https://github.com/qmk/qmk_firmware/pull/13045))
* Add weak refs on reading rows/cols. ([#13062](https://github.com/qmk/qmk_firmware/pull/13062))
* Use single memcmp to determine if matrix changed. ([#13064](https://github.com/qmk/qmk_firmware/pull/13064))
* Improve layer mask handling ([#13065](https://github.com/qmk/qmk_firmware/pull/13065))
* mousekey: expose current report to users ([#13069](https://github.com/qmk/qmk_firmware/pull/13069))
* ChibiOS SVN mirror script. ([#13070](https://github.com/qmk/qmk_firmware/pull/13070))
* Added right vs left specific pin assignments for dip switch ([#13074](https://github.com/qmk/qmk_firmware/pull/13074))
* make RESET key work with Teensy 4.x ([#13076](https://github.com/qmk/qmk_firmware/pull/13076))
* wire up flash make target for Teensy 4.x ([#13077](https://github.com/qmk/qmk_firmware/pull/13077))
* bump USB spec version in device descriptor to 2.0 ([#13078](https://github.com/qmk/qmk_firmware/pull/13078))
* Unite half-duplex and full-duplex serial drivers ([#13081](https://github.com/qmk/qmk_firmware/pull/13081))
* Add ST7565 LCD driver ([#13089](https://github.com/qmk/qmk_firmware/pull/13089))
* `spi_master` Kinetis support ([#13098](https://github.com/qmk/qmk_firmware/pull/13098))
* GMMK Pro RGB Support ([#13147](https://github.com/qmk/qmk_firmware/pull/13147))
* Remove dfu-util arguments from mcu_selection ([#13150](https://github.com/qmk/qmk_firmware/pull/13150))
* Add subcommand to generate version.h ([#13151](https://github.com/qmk/qmk_firmware/pull/13151))
* Add oled_invert ([#13172](https://github.com/qmk/qmk_firmware/pull/13172))
* ST7565 invert ([#13237](https://github.com/qmk/qmk_firmware/pull/13237))
* RGB Matrix eeprom write limiting ([#13238](https://github.com/qmk/qmk_firmware/pull/13238))
* Temporary disable of CRC ([#13252](https://github.com/qmk/qmk_firmware/pull/13252))
* Move LED/RGB Matrix code into their own directories ([#13257](https://github.com/qmk/qmk_firmware/pull/13257))
* Skip EEPROM writes once done. ([#13293](https://github.com/qmk/qmk_firmware/pull/13293))
* Remove rgblight stubs ([#13302](https://github.com/qmk/qmk_firmware/pull/13302))
* Allow settable SPI divisor for AW20216 driver, set default to 4 ([#13309](https://github.com/qmk/qmk_firmware/pull/13309))
* Move RGBLight code into its own folder ([#13312](https://github.com/qmk/qmk_firmware/pull/13312))
* Unify matrix for split common and regular matrix ([#13330](https://github.com/qmk/qmk_firmware/pull/13330))
* Relocate RGB/HSV color defs to a more fitting place ([#13377](https://github.com/qmk/qmk_firmware/pull/13377))
* Adds support for STM32L412xB, STM32L422xB. ([#13383](https://github.com/qmk/qmk_firmware/pull/13383))
* Convert Dip Switch callbacks to boolean functions ([#13399](https://github.com/qmk/qmk_firmware/pull/13399))
* Use string literals for `SERIAL_NUMBER` ([#13403](https://github.com/qmk/qmk_firmware/pull/13403))
* Switch split_common to CRC subsystem ([#13418](https://github.com/qmk/qmk_firmware/pull/13418))
* Improve 'show_build_options' target ([#13425](https://github.com/qmk/qmk_firmware/pull/13425))
* AW20216 use register increment for framebuffer flushes ([#13430](https://github.com/qmk/qmk_firmware/pull/13430))
* Allow invert of SPLIT_HAND_PIN logic ([#13433](https://github.com/qmk/qmk_firmware/pull/13433))
* chibios: bootloader: use integer pointers as volatile ([#13450](https://github.com/qmk/qmk_firmware/pull/13450))
* Refactor OLED to allow easy addition of other types ([#13454](https://github.com/qmk/qmk_firmware/pull/13454))
* Dual RGB Matrix IS31FL3737 driver support to address #13442 ([#13457](https://github.com/qmk/qmk_firmware/pull/13457))
* Enable g_is31_leds PROGMEM for RGB Matrix IS31FL3737 driver ([#13480](https://github.com/qmk/qmk_firmware/pull/13480))
* Switch Ergodox Infinity over to split_common ([#13481](https://github.com/qmk/qmk_firmware/pull/13481))
* Make solo half of split keyboards (more) usable. ([#13523](https://github.com/qmk/qmk_firmware/pull/13523))
* Enable sync of OLED/ST7565 display on/off state on Splits ([#13542](https://github.com/qmk/qmk_firmware/pull/13542))
* Revert "Add rgblight to RGB Matrix VPATH" ([#13559](https://github.com/qmk/qmk_firmware/pull/13559))
* Move `SENDSTRING_BELL` code to `send_string.h` ([#13566](https://github.com/qmk/qmk_firmware/pull/13566))
* Migrate platform independent code from tmk_core -> quantum ([#13673](https://github.com/qmk/qmk_firmware/pull/13673))
* Avoid LTO conficts on arm_atsam ([#13676](https://github.com/qmk/qmk_firmware/pull/13676))
* Allow for removal of hysteresis on 4x encoders ([#13698](https://github.com/qmk/qmk_firmware/pull/13698))
* Port new_keyboard.sh to CLI ([#13706](https://github.com/qmk/qmk_firmware/pull/13706))
* Align AW20216 driver ([#13712](https://github.com/qmk/qmk_firmware/pull/13712))
* Haptic: driver-> feature ([#13713](https://github.com/qmk/qmk_firmware/pull/13713))
* Add support for STM32F407x MCUs. ([#13718](https://github.com/qmk/qmk_firmware/pull/13718))
* Remove legacy BACKLIGHT_CUSTOM_DRIVER option ([#13731](https://github.com/qmk/qmk_firmware/pull/13731))
* Minor tidy up of key overrides ([#13747](https://github.com/qmk/qmk_firmware/pull/13747))
* matrix_scan_x -> x_task ([#13748](https://github.com/qmk/qmk_firmware/pull/13748))
* Move some led drivers to common folder ([#13749](https://github.com/qmk/qmk_firmware/pull/13749))
* Allow for higher USB Polling rate on ATSAM boards ([#13755](https://github.com/qmk/qmk_firmware/pull/13755))
* Rgb matrix/enable modes explicitly ([#13758](https://github.com/qmk/qmk_firmware/pull/13758))
* Move chibios board files to allow tmk_core platform migration ([#13777](https://github.com/qmk/qmk_firmware/pull/13777))
* __flash? ([#13799](https://github.com/qmk/qmk_firmware/pull/13799))
* `--parallel` improvements ([#13800](https://github.com/qmk/qmk_firmware/pull/13800))
* Speed up pimoroni trackball driver ([#13823](https://github.com/qmk/qmk_firmware/pull/13823))
* Add a toggle key for GUI On/Off in Magic feature ([#13830](https://github.com/qmk/qmk_firmware/pull/13830))
* Begin to carve out platform/protocol API - Single main loop ([#13843](https://github.com/qmk/qmk_firmware/pull/13843))
* Remove Full Bootmagic ([#13846](https://github.com/qmk/qmk_firmware/pull/13846))
* Remove backwards compatibility of debounce names ([#13877](https://github.com/qmk/qmk_firmware/pull/13877))
* Relocate platform specific drivers ([#13894](https://github.com/qmk/qmk_firmware/pull/13894))
* Remove ONEHAND_ENABLE ([#13920](https://github.com/qmk/qmk_firmware/pull/13920))
* Move all the flash logic from tmk_core ([#13927](https://github.com/qmk/qmk_firmware/pull/13927))
* adding uf2 flash support for blackpill 401 ([#13968](https://github.com/qmk/qmk_firmware/pull/13968))
* Unify behaviour of wait on AVR ([#14025](https://github.com/qmk/qmk_firmware/pull/14025))
* Add qmk-hid bootloader detection support to `qmk console` ([#14038](https://github.com/qmk/qmk_firmware/pull/14038))
* Align DIP_SWITCH_PINS_RIGHT implementation with encoders ([#14079](https://github.com/qmk/qmk_firmware/pull/14079))
* Tidy up quantum.c now some of tmk_core has been merged ([#14083](https://github.com/qmk/qmk_firmware/pull/14083))
* Improve pmw3360 sensor and make it more hardware agnostic ([#14097](https://github.com/qmk/qmk_firmware/pull/14097))
* Move nix folder alongside vagrant ([#14132](https://github.com/qmk/qmk_firmware/pull/14132))
* Align some quantum sub-directories ([#14134](https://github.com/qmk/qmk_firmware/pull/14134))
* Revert 14083 && 14144 ([#14150](https://github.com/qmk/qmk_firmware/pull/14150))
CLI:
* allow LINE_PINxx for Teensy 4.x pins ([#13247](https://github.com/qmk/qmk_firmware/pull/13247))
* Remove the redundant pin name validation ([#13251](https://github.com/qmk/qmk_firmware/pull/13251))
* Move all our CLI file formatters to the format dir ([#13296](https://github.com/qmk/qmk_firmware/pull/13296))
* Refactor doctor.py into a directory ([#13298](https://github.com/qmk/qmk_firmware/pull/13298))
* Add git and venv info to doctor's output ([#13405](https://github.com/qmk/qmk_firmware/pull/13405))
* Matrix consistency check ([#13470](https://github.com/qmk/qmk_firmware/pull/13470))
* Remove references to info.json `width` and `height` in CLI ([#13728](https://github.com/qmk/qmk_firmware/pull/13728))
* Make `qmk doctor` more lenient about system config ([#13804](https://github.com/qmk/qmk_firmware/pull/13804))
* Defer the expensive search for layout macros until info.json has been processed ([#14007](https://github.com/qmk/qmk_firmware/pull/14007))
Submodule updates:
* Update ChibiOS, ChibiOS-Contrib. ([#13056](https://github.com/qmk/qmk_firmware/pull/13056))
* Update LUFA (18-07-2021) and add QMK-HID Bootloader support ([#13588](https://github.com/qmk/qmk_firmware/pull/13588))
* Update LUFA Submodule (2021-07-30) ([#13819](https://github.com/qmk/qmk_firmware/pull/13819))
* Bump gtest ([#13885](https://github.com/qmk/qmk_firmware/pull/13885))
* Update ChibiOS-Contrib, mirroring script. ([#13896](https://github.com/qmk/qmk_firmware/pull/13896))
* Move USB Host Shield and Arduino core to `lib/` ([#13973](https://github.com/qmk/qmk_firmware/pull/13973))
Keyboards:
* Migrate keyboards using uGFX to LED_MATRIX ([#9657](https://github.com/qmk/qmk_firmware/pull/9657))
* Remove MIDI Configuration boilerplate ([#11151](https://github.com/qmk/qmk_firmware/pull/11151))
* manyboard macro ([#11896](https://github.com/qmk/qmk_firmware/pull/11896))
* Moved tokyo60/ into tokyokeyboard/tokyo60/. ([#12023](https://github.com/qmk/qmk_firmware/pull/12023))
* Organize KPrepublic, K.T.E.C, xiudi boards into directories ([#12159](https://github.com/qmk/qmk_firmware/pull/12159))
* Add Durgod Taurus K310 keyboard ([#12314](https://github.com/qmk/qmk_firmware/pull/12314))
* add support for m65 and simple 5x13 ortholinear ([#12315](https://github.com/qmk/qmk_firmware/pull/12315))
* Relocalize and Update p1800fl ([#12425](https://github.com/qmk/qmk_firmware/pull/12425))
* GameBuddy v1.M ([#12637](https://github.com/qmk/qmk_firmware/pull/12637))
* Add mechlovin9 rev2 PCB ([#12767](https://github.com/qmk/qmk_firmware/pull/12767))
* Add RGB matrix support for Kyria ([#12789](https://github.com/qmk/qmk_firmware/pull/12789))
* RGB Matrix working for Sofle RGB ([#12861](https://github.com/qmk/qmk_firmware/pull/12861))
* Add Durgod Hades, Galaxy and Venus Keyboards ([#12893](https://github.com/qmk/qmk_firmware/pull/12893))
* kint36: set correct EEPROM size ([#12946](https://github.com/qmk/qmk_firmware/pull/12946))
* Updated encoder_update_user on my keymap to follow the new signature on quantum ([#13152](https://github.com/qmk/qmk_firmware/pull/13152))
* Add Creator Pro by SergioPoverony ([#13154](https://github.com/qmk/qmk_firmware/pull/13154))
* Use the new ST7565 driver on Ergodox Infinity ([#13165](https://github.com/qmk/qmk_firmware/pull/13165))
* Refactor atom47 and add rev4 and rev5 ([#13201](https://github.com/qmk/qmk_firmware/pull/13201))
* Add Bakeneko65 V3 and revision folders ([#13228](https://github.com/qmk/qmk_firmware/pull/13228))
* Keyboards/RGBKB/Mün ([#13239](https://github.com/qmk/qmk_firmware/pull/13239))
* Optimize our jsonschema by using refs ([#13271](https://github.com/qmk/qmk_firmware/pull/13271))
* Handwired/Stream_Cheap/2x4: Add via support ([#13297](https://github.com/qmk/qmk_firmware/pull/13297))
* ez_maker/directpins for easy one-offs in qmk_configurator ([#13321](https://github.com/qmk/qmk_firmware/pull/13321))
* add kinT kinesis keyboard controller (kint41 variant) ([#13333](https://github.com/qmk/qmk_firmware/pull/13333))
* Error log cleanup ([#13349](https://github.com/qmk/qmk_firmware/pull/13349))
* Drashna's split updates ([#13350](https://github.com/qmk/qmk_firmware/pull/13350))
* Migrate SHIFT_ESC and RGB `fn_actions` to Grave Escape and RGB keycodes ([#13360](https://github.com/qmk/qmk_firmware/pull/13360))
* Add a lot more data to info.json ([#13366](https://github.com/qmk/qmk_firmware/pull/13366))
* Remove `API_SYSEX_ENABLE`s from rules.mk ([#13389](https://github.com/qmk/qmk_firmware/pull/13389))
* gmmk/pro/mike1808 keymap ([#13398](https://github.com/qmk/qmk_firmware/pull/13398))
* Remove deprecated callbacks for encoders and dip switches ([#13404](https://github.com/qmk/qmk_firmware/pull/13404))
* first pass: matrix consistency improvements ([#13471](https://github.com/qmk/qmk_firmware/pull/13471))
* Migrate more `fn_actions` stuff ([#13502](https://github.com/qmk/qmk_firmware/pull/13502))
* add simple gmmk pro macos keymap with rgb ([#13504](https://github.com/qmk/qmk_firmware/pull/13504))
* move volcano660 to ilumkb folder ([#13550](https://github.com/qmk/qmk_firmware/pull/13550))
* Valor Rev 2 ([#13551](https://github.com/qmk/qmk_firmware/pull/13551))
* Split GMMK Pro PCBs into separate revisions ([#13570](https://github.com/qmk/qmk_firmware/pull/13570))
* Remove the vision_division keyboard ([#13571](https://github.com/qmk/qmk_firmware/pull/13571))
* Develop - Change uint32_t to layer_state_t ([#13596](https://github.com/qmk/qmk_firmware/pull/13596))
* Develop - DC01 left ([#13597](https://github.com/qmk/qmk_firmware/pull/13597))
* Created "paddlegame" keymap ([#13629](https://github.com/qmk/qmk_firmware/pull/13629))
* Add timer_avr to includes for broken builds ([#13641](https://github.com/qmk/qmk_firmware/pull/13641))
* Disable console by default on all Keebio boards ([#13649](https://github.com/qmk/qmk_firmware/pull/13649))
* Enable LTO by default on BastardKB Scylla ([#13664](https://github.com/qmk/qmk_firmware/pull/13664))
* Reduce compile size for dz60rgb v2.1 ([#13680](https://github.com/qmk/qmk_firmware/pull/13680))
* Clean up remaining RGB_DISABLE_WHEN_USB_SUSPENDED defines ([#13689](https://github.com/qmk/qmk_firmware/pull/13689))
* Remove some legacy files ([#13715](https://github.com/qmk/qmk_firmware/pull/13715))
* [Keyboard Update] Change to L422 ([#13717](https://github.com/qmk/qmk_firmware/pull/13717))
* Update kyria make path example ([#13720](https://github.com/qmk/qmk_firmware/pull/13720))
* Drashna's Defaults cleanup ([#13722](https://github.com/qmk/qmk_firmware/pull/13722))
* Reduce firmware size in prep for #12670 ([#13724](https://github.com/qmk/qmk_firmware/pull/13724))
* Tidy up rgbkb/mun ([#13801](https://github.com/qmk/qmk_firmware/pull/13801))
* Make default keymap for GMMK Pro reflect stock ([#13850](https://github.com/qmk/qmk_firmware/pull/13850))
* Rework as per 9824 ([#13898](https://github.com/qmk/qmk_firmware/pull/13898))
* Remove console from keebio via keyboards ([#13901](https://github.com/qmk/qmk_firmware/pull/13901))
* Drashna split transport improvement ([#13905](https://github.com/qmk/qmk_firmware/pull/13905))
* Copy GMMK Pro screw specs to ISO readme ([#13908](https://github.com/qmk/qmk_firmware/pull/13908))
* Clean up remaining RGB_DISABLE_WHEN_USB_SUSPENDED defines Part 2 ([#13912](https://github.com/qmk/qmk_firmware/pull/13912))
* Add andrebrait layout for GMMK Pro ([#13932](https://github.com/qmk/qmk_firmware/pull/13932))
* Updated RGB Matrix suspend define part 3 ([#13954](https://github.com/qmk/qmk_firmware/pull/13954))
* Improve andrebrait keymap ([#13985](https://github.com/qmk/qmk_firmware/pull/13985))
* Drashna's Improve OLEDs and custom Split code ([#14063](https://github.com/qmk/qmk_firmware/pull/14063))
* Kyria default reformat ([#14080](https://github.com/qmk/qmk_firmware/pull/14080))
* Feature rich keymap for GMMK Pro (ANSI) ([#14120](https://github.com/qmk/qmk_firmware/pull/14120))
Keyboard fixes:
* Fix LED mapping for GMMK Pro ([#13189](https://github.com/qmk/qmk_firmware/pull/13189))
* Fix up SplitKB keyboards ([#13511](https://github.com/qmk/qmk_firmware/pull/13511))
* Keyboards/sol rev2 fix ([#13533](https://github.com/qmk/qmk_firmware/pull/13533))
* Fix MATRIX_COLS for aeboards/constellation/rev2 ([#13633](https://github.com/qmk/qmk_firmware/pull/13633))
* Fix errors with matrix_output_unselect_delay function calls ([#13645](https://github.com/qmk/qmk_firmware/pull/13645))
* Fix default keymap for 0xCB 1337 keyboard ([#13646](https://github.com/qmk/qmk_firmware/pull/13646))
* Fix Matrix Row number for ggkeyboards/genisis ([#13647](https://github.com/qmk/qmk_firmware/pull/13647))
* Fix matrix issues with Promethium ([#13648](https://github.com/qmk/qmk_firmware/pull/13648))
* Fix dc01/left so that it doesn't throw a warning ([#13653](https://github.com/qmk/qmk_firmware/pull/13653))
* Remove broken, unmaintained converter/ibm_5291 ([#13658](https://github.com/qmk/qmk_firmware/pull/13658))
* Quick hack to fix Astro65 board ([#13665](https://github.com/qmk/qmk_firmware/pull/13665))
* Fix symmetric70_proto build break on develop branch ([#13667](https://github.com/qmk/qmk_firmware/pull/13667))
* Fix matrix delay on Drop boards ([#13671](https://github.com/qmk/qmk_firmware/pull/13671))
* Fix split matrix for sekigon grs 70ec ([#13672](https://github.com/qmk/qmk_firmware/pull/13672))
* Fix type on pandora via keymap ([#13681](https://github.com/qmk/qmk_firmware/pull/13681))
* Fix & clean up tronguylabs/m122_3270 ([#13684](https://github.com/qmk/qmk_firmware/pull/13684))
* Fix up xd002 rgb keymaps ([#13685](https://github.com/qmk/qmk_firmware/pull/13685))
* Dactyl Manuform cleanup ([#13686](https://github.com/qmk/qmk_firmware/pull/13686))
* Fix Q1 change dip switch to bool ([#13687](https://github.com/qmk/qmk_firmware/pull/13687))
* Fix compile size for the Merge UM70 via keymap ([#13690](https://github.com/qmk/qmk_firmware/pull/13690))
* Fix compile size for the Lets Split Sockets via keymap ([#13691](https://github.com/qmk/qmk_firmware/pull/13691))
* Fix Compile size on ungodly Launch Pad ([#13692](https://github.com/qmk/qmk_firmware/pull/13692))
* dirty fix ([#13695](https://github.com/qmk/qmk_firmware/pull/13695))
* Fix compile size for the Vitamins Included via keymap ([#13696](https://github.com/qmk/qmk_firmware/pull/13696))
* Fix typo in Dactyl Manuform ([#13740](https://github.com/qmk/qmk_firmware/pull/13740))
* Fix compile issues due to LED changes ([#13821](https://github.com/qmk/qmk_firmware/pull/13821))
* Fix SRC include for matrix/m20add issi driver ([#13826](https://github.com/qmk/qmk_firmware/pull/13826))
* fix develop branch move file ([#13832](https://github.com/qmk/qmk_firmware/pull/13832))
* Fix knops keymaps ([#13872](https://github.com/qmk/qmk_firmware/pull/13872))
* Switch Draculad to using WPM char hack ([#13886](https://github.com/qmk/qmk_firmware/pull/13886))
* Fix up builds after #8591 ([#13900](https://github.com/qmk/qmk_firmware/pull/13900))
* Fix matrix_output_unselect_delay for handwired/xealousbrown ([#13913](https://github.com/qmk/qmk_firmware/pull/13913))
* Fixup rgb matrix config for KBD67 mkII boards ([#13931](https://github.com/qmk/qmk_firmware/pull/13931))
* Fix compliation for ferris 0.2 bling ([#13937](https://github.com/qmk/qmk_firmware/pull/13937))
* Fix some additional bootmagic settings ([#13979](https://github.com/qmk/qmk_firmware/pull/13979))
* Fix default keymap for GMMK Pro Iso ([#13980](https://github.com/qmk/qmk_firmware/pull/13980))
* Fixup Ungodly Launch Pad config ([#13992](https://github.com/qmk/qmk_firmware/pull/13992))
* Fix errors that have cropped up in develop ([#14005](https://github.com/qmk/qmk_firmware/pull/14005))
* Fix wait_us overflow in matrix for dactyl based boards ([#14039](https://github.com/qmk/qmk_firmware/pull/14039))
* Fixup Neson Design N6 ISSI includes ([#14045](https://github.com/qmk/qmk_firmware/pull/14045))
* Fixup `massdrop/alt`, `cest73/tkm`. ([#14048](https://github.com/qmk/qmk_firmware/pull/14048))
* fix helix:fraanrosi compile error caused by #13677. ([#14061](https://github.com/qmk/qmk_firmware/pull/14061))
* Fix compile issues for Tractyl Manuform ([#14105](https://github.com/qmk/qmk_firmware/pull/14105))
* Disable Console on Keebio Quefrency ([#14108](https://github.com/qmk/qmk_firmware/pull/14108))
* Fixed GMMK Pro -> stickandgum keymap readme.md ([#14123](https://github.com/qmk/qmk_firmware/pull/14123))
* Drashna keymap fixups ([#14140](https://github.com/qmk/qmk_firmware/pull/14140))
* fix ([#14142](https://github.com/qmk/qmk_firmware/pull/14142))
* Fix merge artifacts ([#14146](https://github.com/qmk/qmk_firmware/pull/14146))
* Update readme files ([#14172](https://github.com/qmk/qmk_firmware/pull/14172))
Others:
* Add examples to RGB Matrix Indicators docs ([#12797](https://github.com/qmk/qmk_firmware/pull/12797))
Bugs:
* Fix Indicator LED issues ([#12097](https://github.com/qmk/qmk_firmware/pull/12097))
* Fixing incorrect keymap build when switching between multiple keymap.jsons ([#12632](https://github.com/qmk/qmk_firmware/pull/12632))
* Fix LED Hit Counter for LED/RGB Matrix ([#12674](https://github.com/qmk/qmk_firmware/pull/12674))
* ChibiOS fix O3 and LTO breakage of extra keys and joystick ([#12819](https://github.com/qmk/qmk_firmware/pull/12819))
* Remove the #10088 hotfix for Teensy 3.1-like Input:Club keyboards ([#12870](https://github.com/qmk/qmk_firmware/pull/12870))
* Fix firmware size check with avr-libc 1:2.0.0+Atmel3.6.2-1.1 (Debian bullseye) ([#12951](https://github.com/qmk/qmk_firmware/pull/12951))
* Fix RGB/LED Suspend defines ([#13146](https://github.com/qmk/qmk_firmware/pull/13146))
* Fix overrun in st7565_write_raw when not at (0, 0) ([#13209](https://github.com/qmk/qmk_firmware/pull/13209))
* Upgrades Vagrant box to Debian 10 to fix Docker build error on Debian 9. ([#13236](https://github.com/qmk/qmk_firmware/pull/13236))
* Fix issues with VIA EEPROM init and bring in line with eeconfig functionality ([#13243](https://github.com/qmk/qmk_firmware/pull/13243))
* Fix CRC for AVR and enable again. ([#13253](https://github.com/qmk/qmk_firmware/pull/13253))
* Fix linker error when rgblight and RGB Matrix are both enabled ([#13304](https://github.com/qmk/qmk_firmware/pull/13304))
* Fix building layouts from JSON ([#13310](https://github.com/qmk/qmk_firmware/pull/13310))
* Add rgblight to RGB Matrix VPATH ([#13371](https://github.com/qmk/qmk_firmware/pull/13371))
* Fix two out of bounds accesses from #13330. ([#13525](https://github.com/qmk/qmk_firmware/pull/13525))
* Fixes for clang not being able to run unit tests ([#13546](https://github.com/qmk/qmk_firmware/pull/13546))
* Fixup Audio startup and add to documents ([#13606](https://github.com/qmk/qmk_firmware/pull/13606))
* CLI/Docs: Fix the format commands' name ([#13668](https://github.com/qmk/qmk_firmware/pull/13668))
* Disables rgblight twinkle by default. ([#13677](https://github.com/qmk/qmk_firmware/pull/13677))
* Fix typo in dip switch example ([#13688](https://github.com/qmk/qmk_firmware/pull/13688))
* docs/cli_commands: fix typo ([#13697](https://github.com/qmk/qmk_firmware/pull/13697))
* Include gpio.h in solenoid driver for GPIO Control functions ([#13716](https://github.com/qmk/qmk_firmware/pull/13716))
* Fix pimoroni trackball read address ([#13810](https://github.com/qmk/qmk_firmware/pull/13810))
* Fix Key Override includes ([#13831](https://github.com/qmk/qmk_firmware/pull/13831))
* Fix alignment of USB out report buffer 2 -> 4 ([#13838](https://github.com/qmk/qmk_firmware/pull/13838))
* Fix compilation issue. ([#13926](https://github.com/qmk/qmk_firmware/pull/13926))
* Fix `combo_disable` ([#13988](https://github.com/qmk/qmk_firmware/pull/13988))
* Fix pmw3360 code to only output debug info if mouse debugging is enabled ([#13993](https://github.com/qmk/qmk_firmware/pull/13993))
* Fix ifdefs for OLED split sync code ([#14017](https://github.com/qmk/qmk_firmware/pull/14017))
* Various fixes from reorg of files ([#14051](https://github.com/qmk/qmk_firmware/pull/14051))
* Fixup atsam builds. ([#14052](https://github.com/qmk/qmk_firmware/pull/14052))
* Fix RGB/LED Matrix Suspend code ([#14084](https://github.com/qmk/qmk_firmware/pull/14084))
* Fix issues with recent keymap.json changes ([#14089](https://github.com/qmk/qmk_firmware/pull/14089))
* Fix LED Matrix suspend code ([#14090](https://github.com/qmk/qmk_firmware/pull/14090))
* Fix up compilation issues. ([#14095](https://github.com/qmk/qmk_firmware/pull/14095))
* Fix copypasta issue with pmw3360 sensor config ([#14106](https://github.com/qmk/qmk_firmware/pull/14106))
* Fix typo ([#14118](https://github.com/qmk/qmk_firmware/pull/14118))
* Fix bootloadHID comments breaking :flash ([#14133](https://github.com/qmk/qmk_firmware/pull/14133))
* Fix Mouse Shared EP functionality ([#14136](https://github.com/qmk/qmk_firmware/pull/14136))
* Short term bodge for firmware size bloat ([#14144](https://github.com/qmk/qmk_firmware/pull/14144))
* Move to correct location ([#14171](https://github.com/qmk/qmk_firmware/pull/14171))

7
docs/_summary.md
View file

@ -36,6 +36,7 @@
* Guides
* [Customizing Functionality](custom_quantum_functions.md)
* [Driver Installation with Zadig](driver_installation_zadig.md)
* [Easy Maker for One Offs](easy_maker.md)
* [Keymap Overview](keymap.md)
* Development Environments
* [Docker Guide](getting_started_docker.md)
@ -61,6 +62,7 @@
* [Language-Specific Keycodes](reference_keymap_extras.md)
* [Modifier Keys](feature_advanced_keycodes.md)
* [Quantum Keycodes](quantum_keycodes.md)
* [Magic Keycodes](keycodes_magic.md)
* Advanced Keycodes
* [Command](feature_command.md)
@ -78,6 +80,7 @@
* [Combos](feature_combo.md)
* [Debounce API](feature_debounce_type.md)
* [Key Lock](feature_key_lock.md)
* [Key Overrides](feature_key_overrides.md)
* [Layers](feature_layers.md)
* [One Shot Keys](one_shot_keys.md)
* [Pointing Device](feature_pointing_device.md)
@ -94,6 +97,7 @@
* Hardware Features
* Displays
* [HD44780 LCD Controller](feature_hd44780.md)
* [ST7565 LCD Driver](feature_st7565.md)
* [OLED Driver](feature_oled_driver.md)
* Lighting
* [Backlight](feature_backlight.md)
@ -102,8 +106,9 @@
* [RGB Matrix](feature_rgb_matrix.md)
* [Audio](feature_audio.md)
* [Bluetooth](feature_bluetooth.md)
* [Bootmagic](feature_bootmagic.md)
* [Bootmagic Lite](feature_bootmagic.md)
* [Custom Matrix](custom_matrix.md)
* [Digitizer](feature_digitizer.md)
* [DIP Switch](feature_dip_switch.md)
* [Encoders](feature_encoders.md)
* [Haptic Feedback](feature_haptic_feedback.md)

17
docs/breaking_changes.md
View file

@ -6,6 +6,7 @@ The breaking change period is when we will merge PR's that change QMK in dangero
## What has been included in past Breaking Changes?
* [2021 Aug 28](ChangeLog/20210828.md)
* [2021 May 29](ChangeLog/20210529.md)
* [2021 Feb 27](ChangeLog/20210227.md)
* [2020 Nov 28](ChangeLog/20201128.md)
@ -20,12 +21,12 @@ The next Breaking Change is scheduled for August 28, 2021.
### Important Dates
* [x] 2021 May 29 - `develop` is created. Each push to `master` is subsequently merged to `develop`
* [ ] 2021 Jul 31 - `develop` closed to new PR's.
* [ ] 2021 Jul 31 - Call for testers.
* [ ] 2021 Aug 26 - `master` is locked, no PR's merged.
* [ ] 2021 Aug 28 - Merge `develop` to `master`.
* [ ] 2021 Aug 28 - `master` is unlocked. PR's can be merged again.
* [x] 2021 Aug 29 - `develop` is created. Each push to `master` is subsequently merged to `develop`
* [ ] 2021 Oct 31 - `develop` closed to new PR's.
* [ ] 2021 Oct 31 - Call for testers.
* [ ] 2021 Nov 26 - `master` is locked, no PR's merged.
* [ ] 2021 Nov 28 - Merge `develop` to `master`.
* [ ] 2021 Nov 28 - `master` is unlocked. PR's can be merged again.
## What changes will be included?
@ -99,3 +100,7 @@ This happens immediately after the previous `develop` branch is merged.
* [ ] `git pull --ff-only`
* [ ] `git merge --no-ff develop`
* [ ] `git push upstream master`
## Post-merge operations
* (Optional) [update ChibiOS + ChibiOS-Contrib on `develop`](chibios_upgrade_instructions.md)

1
docs/breaking_changes_history.md
View file

@ -2,6 +2,7 @@
This page links to all previous changelogs from the QMK Breaking Changes process.
* [2021 Aug 28](ChangeLog/20210828.md) - version 0.14.0
* [2021 May 29](ChangeLog/20210529.md) - version 0.13.0
* [2021 Feb 27](ChangeLog/20210227.md) - version 0.12.0
* [2020 Nov 28](ChangeLog/20201128.md) - version 0.11.0

56
docs/chibios_upgrade_instructions.md Normal file
View file

@ -0,0 +1,56 @@
# ChibiOS Upgrade Procedure
ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a branch tied to the ChibiOS version in use and should not be mixed with different versions.
## Getting ChibiOS
* `svn` Initialisation:
* Only needed to be done once
* You might need to separately install `git-svn` package in your OS's package manager
* `git svn init --stdlayout --prefix='svn/' http://svn.osdn.net/svnroot/chibios/`
* `git remote add qmk git@github.com:qmk/ChibiOS.git`
* Updating:
* `git svn fetch`
* First time around this will take several hours
* Subsequent updates will be incremental only
* Tagging example (work out which version first!):
* `git tag -a ver20.3.3 -m ver20.3.3 svn/tags/ver20.3.3`
* `git push qmk ver20.3.3`
* `git tag -a breaking_YYYY_qN -m breaking_YYYY_qN svn/tags/ver20.3.3`
* `git push qmk breaking_YYYY_qN`
## Getting ChibiOS-Contrib
* `git` Initialisation:
* `git clone git@github.com:qmk/ChibiOS-Contrib`
* `git remote add upstream https://github.com/ChibiOS/ChibiOS-Contrib`
* `git checkout -b chibios-20.3.x upstream/chibios-20.3.x`
* Updating:
* `git fetch --all --tags --prune`
* `git checkout chibios-20.3.x`
* `git pull --ff-only`
* `git push origin chibios-20.3.x`
* `git tag -a breaking_YYYY_qN -m breaking_YYYY_qN chibios-20.3.x`
* `git push origin breaking_YYYY_qN`
## Updating submodules
* Update the submodules
* `cd $QMK_FIRMWARE`
* `git checkout develop`
* `git pull --ff-only`
* `git checkout -b chibios-version-bump`
* `cd lib/chibios`
* `git fetch --all --tags --prune`
* `git checkout breaking_YYYY_qN`
* `cd ../chibios-contrib`
* `git fetch --all --tags --prune`
* `git checkout breaking_YYYY_qN`
* Build everything
* `cd $QMK_FIRMWARE`
* `qmk multibuild -j4`
* Make sure there are no errors
* Push to the repo
* `git commit -am 'Update ChibiOS to XXXXXXXXX'`
* `git push --set-upstream origin chibios-version-bump`
* Make a PR to qmk_firmware with the new branch

50
docs/cli_commands.md
View file

@ -17,7 +17,7 @@ qmk compile [-c] <configuratorExport.json>
**Usage for Keymaps**:
```
qmk compile [-c] [-e <var>=<value>] -kb <keyboard_name> -km <keymap_name>
qmk compile [-c] [-e <var>=<value>] [-j <num_jobs>] -kb <keyboard_name> -km <keymap_name>
```
**Usage in Keyboard Directory**:
@ -73,6 +73,17 @@ $ qmk compile -kb dz60
...
```
**Parallel Compilation**:
It is possible to speed up compilation by adding the `-j`/`--parallel` flag.
```
qmk compile -j <num_jobs> -kb <keyboard_name>
```
The `num_jobs` argument determines the maximum number of jobs that can be used. Setting it to zero will enable parallel compilation without limiting the maximum number of jobs.
```
qmk compile -j 0 -kb <keyboard_name>
```
## `qmk flash`
This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default. To specify a different bootloader, use `-bl <bootloader>`. Visit the [Flashing Firmware](flashing.md) guide for more details of the available bootloaders.
@ -82,13 +93,13 @@ This command is directory aware. It will automatically fill in KEYBOARD and/or K
**Usage for Configurator Exports**:
```
qmk flash [-bl <bootloader>] [-c] [-e <var>=<value>] <configuratorExport.json>
qmk flash [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>] <configuratorExport.json>
```
**Usage for Keymaps**:
```
qmk flash -kb <keyboard_name> -km <keymap_name> [-bl <bootloader>] [-c] [-e <var>=<value>]
qmk flash -kb <keyboard_name> -km <keymap_name> [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>]
```
**Listing the Bootloaders**
@ -109,7 +120,7 @@ qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
## `qmk console`
This command lets you connect to keyboard consoles to get debugging messages. It only works if your keyboard firmware has been compiled with `CONSOLE_ENABLED=yes`.
This command lets you connect to keyboard consoles to get debugging messages. It only works if your keyboard firmware has been compiled with `CONSOLE_ENABLE=yes`.
**Usage**:
@ -280,12 +291,12 @@ qmk list-keymaps -kb planck/ez
This command creates a new keyboard based on available templates.
This command will prompt for input to guide you though the generation process.
Any arguments that are not provided will prompt for input. If `-u` is not passed and `user.name` is set in .gitconfig, it will be used as the default username in the prompt.
**Usage**:
```
qmk new-keyboard
qmk new-keyboard [-kb KEYBOARD] [-t {avr,ps2avrgb}] -u USERNAME
```
## `qmk new-keymap`
@ -314,7 +325,18 @@ qmk clean [-a]
# Developer Commands
## `qmk cformat`
## `qmk format-text`
This command formats text files to have proper line endings.
Every text file in the repository needs to have Unix (LF) line ending.
If you are working on **Windows**, you must ensure that line endings are corrected in order to get your PRs merged.
```
qmk format-text
```
## `qmk format-c`
This command formats C code using clang-format.
@ -325,25 +347,25 @@ Run it with `-a` to format all core code, or pass filenames on the command line
**Usage for specified files**:
```
qmk cformat [file1] [file2] [...] [fileN]
qmk format-c [file1] [file2] [...] [fileN]
```
**Usage for all core files**:
```
qmk cformat -a
qmk format-c -a
```
**Usage for only changed files against origin/master**:
```
qmk cformat
qmk format-c
```
**Usage for only changed files against branch_name**:
```
qmk cformat -b branch_name
qmk format-c -b branch_name
```
## `qmk docs`
@ -369,7 +391,7 @@ qmk generate-docs
## `qmk generate-rgb-breathe-table`
This command generates a lookup table (LUT) header file for the [RGB Lighting](feature_rgblight.md) feature's breathing animation. Place this file in your keyboard or keymap directory as `rgblight_breathe_table.h` to override the default LUT in `quantum/`.
This command generates a lookup table (LUT) header file for the [RGB Lighting](feature_rgblight.md) feature's breathing animation. Place this file in your keyboard or keymap directory as `rgblight_breathe_table.h` to override the default LUT in `quantum/rgblight/`.
**Usage**:
@ -399,14 +421,14 @@ $ qmk kle2json -f kle.txt -f
Ψ Wrote out to info.json
```
## `qmk pyformat`
## `qmk format-python`
This command formats python code in `qmk_firmware`.
**Usage**:
```
qmk pyformat
qmk format-python
```
## `qmk pytest`

4
docs/cli_development.md
View file

@ -188,7 +188,7 @@ cli.log.info('Reading from %s and writing to %s', cli.args.filename, cli.args.ou
# Testing, and Linting, and Formatting (oh my!)
We use nose2, flake8, and yapf to test, lint, and format code. You can use the `pytest` and `pyformat` subcommands to run these tests:
We use nose2, flake8, and yapf to test, lint, and format code. You can use the `pytest` and `format-py` subcommands to run these tests:
### Testing and Linting
@ -196,7 +196,7 @@ We use nose2, flake8, and yapf to test, lint, and format code. You can use the `
### Formatting
qmk pyformat
qmk format-py
## Formatting Details

3
docs/compatible_microcontrollers.md
View file

@ -27,10 +27,13 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s
* [STM32F103](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html)
* [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html)
* [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html)
* [STM32F407](https://www.st.com/en/microcontrollers-microprocessors/stm32f407-417.html)
* [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html)
* [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html)
* [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html)
* [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html)
* [STM32L412](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html)
* [STM32L422](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html)
* [STM32L433](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html)
* [STM32L443](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html)

53
docs/config_options.md
View file

@ -51,8 +51,10 @@ This is a C header file that is one of the first things included, and will persi
* the number of columns in your keyboard's matrix
* `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }`
* pins of the rows, from top to bottom
* may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information.
* `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }`
* pins of the columns, from left to right
* may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information.
* `#define MATRIX_IO_DELAY 30`
* the delay in microseconds when between changing matrix pin state and reading values
* `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }`
@ -186,13 +188,27 @@ If you define these options you will enable the associated feature, which may in
few ms of delay from this. But if you're doing chording on something with 3-4ms
scan times? You probably want this.
* `#define COMBO_COUNT 2`
* Set this to the number of combos that you're using in the [Combo](feature_combo.md) feature.
* Set this to the number of combos that you're using in the [Combo](feature_combo.md) feature. Or leave it undefined and programmatically set the count.
* `#define COMBO_TERM 200`
* how long for the Combo keys to be detected. Defaults to `TAPPING_TERM` if not defined.
* `#define COMBO_MUST_HOLD_MODS`
* Flag for enabling extending timeout on Combos containing modifers
* `#define COMBO_MOD_TERM 200`
* Allows for extending COMBO_TERM for mod keys while mid-combo.
* `#define COMBO_MUST_HOLD_PER_COMBO`
* Flag to enable per-combo COMBO_TERM extension and `get_combo_must_hold()` function
* `#define COMBO_TERM_PER_COMBO`
* Flag to enable per-combo COMBO_TERM extension and `get_combo_term()` function
* `#define COMBO_STRICT_TIMER`
* Only start the combo timer on the first key press instead of on all key presses.
* `#define COMBO_NO_TIMER`
* Disable the combo timer completely for relaxed combos.
* `#define TAP_CODE_DELAY 100`
* Sets the delay between `register_code` and `unregister_code`, if you're having issues with it registering properly (common on VUSB boards). The value is in milliseconds.
* `#define TAP_HOLD_CAPS_DELAY 80`
* Sets the delay for Tap Hold keys (`LT`, `MT`) when using `KC_CAPSLOCK` keycode, as this has some special handling on MacOS. The value is in milliseconds, and defaults to 80 ms if not defined. For macOS, you may want to set this to 200 or higher.
* `#define KEY_OVERRIDE_REPEAT_DELAY 500`
* Sets the key repeat interval for [key overrides](feature_key_overrides.md).
## RGB Light Configuration
@ -272,7 +288,7 @@ There are a few different ways to set handedness for split keyboards (listed in
### Other Options
* `#define USE_I2C`
* For using I2C instead of Serial (defaults to serial)
* For using I2C instead of Serial (default is serial; serial transport is supported on ARM -- I2C is AVR-only)
* `#define SOFT_SERIAL_PIN D0`
* When using serial, define this. `D0` or `D1`,`D2`,`D3`,`E6`.
@ -280,6 +296,7 @@ There are a few different ways to set handedness for split keyboards (listed in
* `#define MATRIX_ROW_PINS_RIGHT { <row pins> }`
* `#define MATRIX_COL_PINS_RIGHT { <col pins> }`
* If you want to specify a different pinout for the right half than the left half, you can define `MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT`. Currently, the size of `MATRIX_ROW_PINS` must be the same as `MATRIX_ROW_PINS_RIGHT` and likewise for the definition of columns.
* may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information.
* `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
* If you want to specify a different direct pinout for the right half than the left half, you can define `DIRECT_PINS_RIGHT`. Currently, the size of `DIRECT_PINS` must be the same as `DIRECT_PINS_RIGHT`.
@ -300,7 +317,7 @@ There are a few different ways to set handedness for split keyboards (listed in
* `#define SPLIT_USB_DETECT`
* Detect (with timeout) USB connection when delegating master/slave
* Default behavior for ARM
* Required for AVR Teensy
* Required for AVR Teensy (without hardware mods)
* `#define SPLIT_USB_TIMEOUT 2000`
* Maximum timeout when detecting master/slave when using `SPLIT_USB_DETECT`
@ -308,6 +325,34 @@ There are a few different ways to set handedness for split keyboards (listed in
* `#define SPLIT_USB_TIMEOUT_POLL 10`
* Poll frequency when detecting master/slave when using `SPLIT_USB_DETECT`
* `#define FORCED_SYNC_THROTTLE_MS 100`
* Deadline for synchronizing data from master to slave when using the QMK-provided split transport.
* `#define SPLIT_TRANSPORT_MIRROR`
* Mirrors the master-side matrix on the slave when using the QMK-provided split transport.
* `#define SPLIT_LAYER_STATE_ENABLE`
* Ensures the current layer state is available on the slave when using the QMK-provided split transport.
* `#define SPLIT_LED_STATE_ENABLE`
* Ensures the current host indicator state (caps/num/scroll) is available on the slave when using the QMK-provided split transport.
* `#define SPLIT_MODS_ENABLE`
* Ensures the current modifier state (normal, weak, and oneshot) is available on the slave when using the QMK-provided split transport.
* `#define SPLIT_WPM_ENABLE`
* Ensures the current WPM is available on the slave when using the QMK-provided split transport.
* `#define SPLIT_OLED_ENABLE`
* Syncs the on/off state of the OLED between the halves.
* `#define SPLIT_ST7565_ENABLE`
* Syncs the on/off state of the ST7565 screen between the halves.
* `#define SPLIT_TRANSACTION_IDS_KB .....`
* `#define SPLIT_TRANSACTION_IDS_USER .....`
* Allows for custom data sync with the slave when using the QMK-provided split transport. See [custom data sync between sides](feature_split_keyboard.md#custom-data-sync) for more information.
# The `rules.mk` File
This is a [make](https://www.gnu.org/software/make/manual/make.html) file that is included by the top-level `Makefile`. It is used to set some information about the MCU that we will be compiling for as well as enabling and disabling certain features.
@ -375,6 +420,8 @@ Use these to enable or disable building certain features. The more you have enab
* USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
* `AUDIO_ENABLE`
* Enable the audio subsystem.
* `KEY_OVERRIDE_ENABLE`
* Enable the key override feature
* `RGBLIGHT_ENABLE`
* Enable keyboard underlight functionality
* `LEADER_ENABLE`

10
docs/custom_quantum_functions.md
View file

@ -144,6 +144,14 @@ This is useful for setting up stuff that you may need elsewhere, but isn't hardw
* Keyboard/Revision: `void matrix_init_kb(void)`
* Keymap: `void matrix_init_user(void)`
### Low-level Matrix Overrides Function Documentation :id=low-level-matrix-overrides
* GPIO pin initialisation: `void matrix_init_pins(void)`
* This needs to perform the low-level initialisation of all row and column pins. By default this will initialise the input/output state of each of the GPIO pins listed in `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`, based on whether or not the keyboard is set up for `ROW2COL`, `COL2ROW`, or `DIRECT_PINS`. Should the keyboard designer override this function, no initialisation of pin state will occur within QMK itself, instead deferring to the keyboard's override.
* `COL2ROW`-based row reads: `void matrix_read_rows_on_col(matrix_row_t current_matrix[], uint8_t current_col)`
* `ROW2COL`-based column reads: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)`
* `DIRECT_PINS`-based reads: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)`
* These three functions need to perform the low-level retrieval of matrix state of relevant input pins, based on the matrix type. Only one of the functions should be implemented, if needed. By default this will iterate through `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`, configuring the inputs and outputs based on whether or not the keyboard is set up for `ROW2COL`, `COL2ROW`, or `DIRECT_PINS`. Should the keyboard designer override this function, no manipulation of matrix GPIO pin state will occur within QMK itself, instead deferring to the keyboard's override.
## Keyboard Post Initialization code
@ -374,7 +382,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
}
}
```
And lastly, you want to add the `eeconfig_init_user` function, so that when the EEPROM is reset, you can specify default values, and even custom actions. To force an EEPROM reset, use the `EEP_RST` keycode or [Bootmagic](feature_bootmagic.md) functionallity. For example, if you want to set rgb layer indication by default, and save the default valued.
And lastly, you want to add the `eeconfig_init_user` function, so that when the EEPROM is reset, you can specify default values, and even custom actions. To force an EEPROM reset, use the `EEP_RST` keycode or [Bootmagic Lite](feature_bootmagic.md) functionallity. For example, if you want to set rgb layer indication by default, and save the default valued.
```c
void eeconfig_init_user(void) { // EEPROM is getting reset!

8
docs/de/cli.md
View file

@ -88,14 +88,14 @@ qmk compile <configuratorExport.json>
qmk compile -kb <keyboard_name> -km <keymap_name>
```
## `qmk cformat`
## `qmk format-c`
Dieser Befehl formatiert C-Code im clang-Format. Benutze ihn ohne Argumente, um den core-Code zu formatieren, oder benutze Namen von Dateien in der CLI, um den Befehl auf bestimmte Dateien anzuwenden.
**Anwendung**:
```
qmk cformat [file1] [file2] [...] [fileN]
qmk format-c [file1] [file2] [...] [fileN]
```
## `qmk config`
@ -148,14 +148,14 @@ Dieser Befehl erstellt eine neue Keymap basierend auf einer existierenden Standa
qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
```
## `qmk pyformat`
## `qmk format-py`
Dieser Befehl formatiert Python-Code in `qmk_firmware`.
**Anwendung**:
```
qmk pyformat
qmk format-py
```
## `qmk pytest`

5
docs/driver_installation_zadig.md
View file

@ -8,8 +8,8 @@ We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have
## Installation
Put your keyboard into bootloader mode, either by hitting the `RESET` keycode (which may be on a different layer), or by pressing the reset switch that's usually located on the underside of the board. If your keyboard has neither, try holding Escape or Space+`B` as you plug it in (see the [Bootmagic](feature_bootmagic.md) docs for more details). Some boards use [Command](feature_command.md) instead of Bootmagic; in this case, you can enter bootloader mode by hitting Left Shift+Right Shift+`B` or Left Shift+Right Shift+Escape at any point while the keyboard is plugged in.
Some keyboards may have specific instructions for entering the bootloader. For example, the [Bootmagic Lite](feature_bootmagic.md#bootmagic-lite) key (default: Escape) might be on a different key, e.g. Left Control; or the magic combination for Command (default: Left Shift+Right Shift) might require you to hold something else, e.g. Left Control+Right Control. Refer to the board's README file if you are unsure.
Put your keyboard into bootloader mode, either by hitting the `RESET` keycode (which may be on a different layer), or by pressing the reset switch that's usually located on the underside of the board. If your keyboard has neither, try holding Escape or Space+`B` as you plug it in (see the [Bootmagic Lite](feature_bootmagic.md) docs for more details). Some boards use [Command](feature_command.md) instead of Bootmagic; in this case, you can enter bootloader mode by hitting Left Shift+Right Shift+`B` or Left Shift+Right Shift+Escape at any point while the keyboard is plugged in.
Some keyboards may have specific instructions for entering the bootloader. For example, the [Bootmagic Lite](feature_bootmagic.md) key (default: Escape) might be on a different key, e.g. Left Control; or the magic combination for Command (default: Left Shift+Right Shift) might require you to hold something else, e.g. Left Control+Right Control. Refer to the board's README file if you are unsure.
To put a device in bootloader mode with USBaspLoader, tap the `RESET` button while holding down the `BOOT` button.
Alternatively, hold `BOOT` while inserting the USB cable.
@ -95,3 +95,4 @@ The device name here is the name that appears in Zadig, and may not be what the
|`stm32-dfu` |STM32 BOOTLOADER |`0483:DF11` |WinUSB |
|`kiibohd` |Kiibohd DFU Bootloader |`1C11:B007` |WinUSB |
|`stm32duino` |Maple 003 |`1EAF:0003` |WinUSB |
|`qmk-hid` |(keyboard name) Bootloader |`03EB:2067` |HidUsb |

31
docs/easy_maker.md Normal file
View file

@ -0,0 +1,31 @@
# Easy Maker - Build One-Off Projects In Configurator
Have you ever needed an easy way to program a controller, such as a Proton C or Teensy 2.0, for a one-off project you're building? QMK has you covered with the Easy Maker. Now you can create a firmware in minutes using QMK Configurator.
There are different styles of Easy Maker available depending on your needs:
* [Direct Pin](https://config.qmk.fm/#/?filter=ez_maker/direct) - Connect a single switch to a single pin
* Direct Pin + Backlight (Coming Soon) - Like Direct Pin but dedicates a single pin to [Backlight](feature_backlight.md) control
* Direct Pin + Numlock (Coming Soon) - Like Direct Pin but dedicates a single pin to the Numlock LED
* Direct Pin + Capslock (Coming Soon) - Like Direct Pin but dedicates a single pin to the Numlock LED
* Direct Pin + Encoder (Coming Soon) - Like Direct Pin but uses 2 pins to add a single rotary encoder
## Quickstart
The easiest way to get started is with the Direct Pin boards. This will assign a single key to each pin and you can short that pin to ground to activate it. Select your MCU from the Keyboard dropdown here:
* <https://config.qmk.fm/#/?filter=ez_maker/direct>
For more details see the [Direct Pin](#direct-pin) section.
# Direct Pin
As its name implies Direct Pin works by connecting one switch per pin. The other side of the switch should be connected to ground (VSS or GND.) You don't need any other components, your MCU has internal pull-up resistors so that the switch sensing can work.
Here is a schematic showing how we connect a single button to pin A3 on a ProMicro:
![Schematic diagram showing a ProMicro with a wire coming out of A3, connecting to the left side of a switch. Another wire comes out of the right side of the switch to connect to the Ground Plane.](https://i.imgur.com/JcDhZll.png)
Once you have wired your switches you can assign keycodes to each pin and build a firmware by selecting the MCU you are using from the Keyboard dropdown. Use this link to show only Easy Maker Direct Pin:
* <https://config.qmk.fm/#/?filter=ez_maker/direct>

3
docs/eeprom_driver.md
View file

@ -31,6 +31,9 @@ Currently QMK supports 24xx-series chips over I2C. As such, requires a working i
`#define EXTERNAL_EEPROM_PAGE_SIZE` | Page size of the EEPROM in bytes, as specified in the datasheet | 32
`#define EXTERNAL_EEPROM_ADDRESS_SIZE` | The number of bytes to transmit for the memory location within the EEPROM | 2
`#define EXTERNAL_EEPROM_WRITE_TIME` | Write cycle time of the EEPROM, as specified in the datasheet | 5
`#define EXTERNAL_EEPROM_WP_PIN` | If defined the WP pin will be toggled appropriately when writing to the EEPROM. | _none_
Some I2C EEPROM manufacturers explicitly recommend against hardcoding the WP pin to ground. This is in order to protect the eeprom memory content during power-up/power-down/brown-out conditions at low voltage where the eeprom is still operational, but the i2c master output might be unpredictable. If a WP pin is configured, then having an external pull-up on the WP pin is recommended.
Default values and extended descriptions can be found in `drivers/eeprom/eeprom_i2c.h`.

34
docs/es/hardware_avr.md
View file

@ -6,26 +6,28 @@ Si aún no lo has hecho, debes leer las [Pautas de teclados](hardware_keyboard_g
## Añadir tu Teclado AVR a QMK
QMK tiene varias características para simplificar el trabajo con teclados AVR. Para la mayoría de los teclados no tienes que escribir ni una sola línea de código. Para empezar, ejecuta el archivo `util/new_keyboard.sh`:
QMK tiene varias características para simplificar el trabajo con teclados AVR. Para la mayoría de los teclados no tienes que escribir ni una sola línea de código. Para empezar, ejecuta `qmk new-keyboard`:
```
$ ./util/new_keyboard.sh
Generating a new QMK keyboard directory
$ qmk new-keyboard
Ψ Generating a new QMK keyboard directory
Keyboard Name: mycoolkb
Keyboard Type [avr]:
Your Name [John Smith]:
Keyboard Name: mycoolkeeb
Keyboard Type:
1. avr
2. ps2avrgb
Please enter your choice: [1]
Your Name: [John Smith]
Ψ Copying base template files...
Ψ Copying avr template files...
Ψ Renaming keyboard.[ch] to mycoolkeeb.[ch]...
Ψ Replacing %YEAR% with 2021...
Ψ Replacing %KEYBOARD% with mycoolkeeb...
Ψ Replacing %YOUR_NAME% with John Smith...
Copying base template files... done
Copying avr template files... done
Renaming keyboard files... done
Replacing %KEYBOARD% with mycoolkb... done
Replacing %YOUR_NAME% with John Smith... done
Created a new keyboard called mycoolkb.
To start working on things, cd into keyboards/mycoolkb,
or open the directory in your favourite text editor.
Ψ Created a new keyboard called mycoolkeeb.
Ψ To start working on things, `cd` into keyboards/mycoolkeeb,
Ψ or open the directory in your preferred text editor.
```
Esto creará todos los archivos necesarios para tu nuevo teclado, y rellenará la configuración con valores predeterminados. Ahora sólo tienes que personalizarlo para tu teclado.

2
docs/faq_keymap.md
View file

@ -31,7 +31,7 @@ QMK has two features, Bootmagic and Command, which allow you to change the behav
As a quick fix try holding down `Space`+`Backspace` while you plug in your keyboard. This will reset the stored settings on your keyboard, returning those keys to normal operation. If that doesn't work look here:
* [Bootmagic](feature_bootmagic.md)
* [Bootmagic Lite](feature_bootmagic.md)
* [Command](feature_command.md)
## The Menu Key Isn't Working

26
docs/feature_audio.md
View file

@ -167,6 +167,32 @@ The available keycodes for audio are:
!> These keycodes turn all of the audio functionality on and off. Turning it off means that audio feedback, audio clicky, music mode, etc. are disabled, completely.
## Audio Config
| Settings | Default | Description |
|---------------------------------|----------------------|-------------------------------------------------------------------------------|
|`AUDIO_PIN` | *Not defined* |Configures the pin that the speaker is connected to. |
|`AUDIO_PIN_ALT` | *Not defined* |Configures the pin for a second speaker or second pin connected to one speaker.|
|`AUDIO_PIN_ALT_AS_NEGATIVE` | *Not defined* |Enables support for one speaker connected to two pins. |
|`AUDIO_INIT_DELAY` | *Not defined* |Enables delay during startup song to accomidate for USB startup issues. |
|`AUDIO_ENABLE_TONE_MULTIPLEXING` | *Not defined* |Enables time splicing/multiplexing to create multiple tones simutaneously. |
|`STARTUP_SONG` | `STARTUP_SOUND` |Plays when the keyboard starts up (audio.c) |
|`GOODBYE_SONG` | `GOODBYE_SOUND` |Plays when you press the RESET key (quantum.c) |
|`AG_NORM_SONG` | `AG_NORM_SOUND` |Plays when you press AG_NORM (process_magic.c) |
|`AG_SWAP_SONG` | `AG_SWAP_SOUND` |Plays when you press AG_SWAP (process_magic.c) |
|`CG_NORM_SONG` | `AG_NORM_SOUND` |Plays when you press CG_NORM (process_magic.c) |
|`CG_SWAP_SONG` | `AG_SWAP_SOUND` |Plays when you press CG_SWAP (process_magic.c) |
|`MUSIC_ON_SONG` | `MUSIC_ON_SOUND` |Plays when music mode is activated (process_music.c) |
|`MUSIC_OFF_SONG` | `MUSIC_OFF_SOUND` |Plays when music mode is deactivated (process_music.c) |
|`MIDI_ON_SONG` | `MUSIC_ON_SOUND` |Plays when midi mode is activated (process_music.c) |
|`MIDI_OFF_SONG` | `MUSIC_OFF_SOUND` |Plays when midi mode is deactivated (process_music.c) |
|`CHROMATIC_SONG` | `CHROMATIC_SOUND` |Plays when the chromatic music mode is selected (process_music.c) |
|`GUITAR_SONG` | `GUITAR_SOUND` |Plays when the guitar music mode is selected (process_music.c) |
|`VIOLIN_SONG` | `VIOLIN_SOUND` |Plays when the violin music mode is selected (process_music.c) |
|`MAJOR_SONG` | `MAJOR_SOUND` |Plays when the major music mode is selected (process_music.c) |
|`DEFAULT_LAYER_SONGS` | *Not defined* |Plays song when switched default layers with [`set_single_persistent_default_layer(layer)`](ref_functions.md#setting-the-persistent-default-layer)(quantum.c) |
|`SENDSTRING_BELL` | *Not defined* |Plays chime when the "enter" ("\a") character is sent (send_string.c) |
## Tempo
the 'speed' at which SONGs are played is dictated by the set Tempo, which is measured in beats-per-minute. Note lengths are defined relative to that.
The initial/default tempo is set to 120 bpm, but can be configured by setting `TEMPO_DEFAULT` in `config.c`.

141
docs/feature_bootmagic.md
View file

@ -1,136 +1,15 @@
# Bootmagic
There are three separate but related features that allow you to change the behavior of your keyboard without reflashing. While each of them have similar functionality, it is accessed in different ways depending on how your keyboard is configured.
**Bootmagic** is a system for configuring your keyboard while it initializes. To trigger a Bootmagic command, hold down the Bootmagic key and one or more command keys.
**Bootmagic Keycodes** are prefixed with `MAGIC_`, and allow you to access the Bootmagic functionality *after* your keyboard has initialized. To use the keycodes, assign them to your keymap as you would any other keycode.
**Command**, formerly known as **Magic**, is another feature that allows you to control different aspects of your keyboard. While it shares some functionality with Bootmagic, it also allows you to do things that Bootmagic does not, such as printing version information to the console. For more information, see [Command](feature_command.md).
On some keyboards Bootmagic is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk` with:
```make
BOOTMAGIC_ENABLE = full
```
?> You may see `yes` being used in place of `full`, and this is okay. However, `yes` is deprecated, and ideally `full` (or `lite`) should be used instead.
Additionally, you can use [Bootmagic Lite](#bootmagic-lite) (a scaled down, very basic version of Bootmagic) by adding the following to your `rules.mk` file:
```make
BOOTMAGIC_ENABLE = lite
```
## Hotkeys
Hold down the Bootmagic key (Space by default) and the desired hotkey while plugging in your keyboard. For example, holding Space+`B` should cause it to enter the bootloader.
|Hotkey |Description |
|------------------|---------------------------------------------|
|Escape |Ignore Bootmagic configuration in EEPROM |
|`B` |Enter the bootloader |
|`D` |Toggle debugging over serial |
|`X` |Toggle key matrix debugging |
|`K` |Toggle keyboard debugging |
|`M` |Toggle mouse debugging |
|`L` |Set "Left Hand" for EE_HANDS handedness |
|`R` |Set "Right Hand" for EE_HANDS handedness |
|Backspace |Clear the EEPROM |
|Caps Lock |Toggle treating Caps Lock as Left Control |
|Left Control |Toggle swapping Caps Lock and Left Control |
|Left Alt |Toggle swapping Left Alt and Left GUI |
|Right Alt |Toggle swapping Right Alt and Right GUI |
|Left GUI |Toggle the GUI keys (useful when gaming) |
|<code>&#96;</code>|Toggle swapping <code>&#96;</code> and Escape|
|`\` |Toggle swapping `\` and Backspace |
|`N` |Toggle N-Key Rollover (NKRO) |
|`0` |Make layer 0 the default layer |
|`1` |Make layer 1 the default layer |
|`2` |Make layer 2 the default layer |
|`3` |Make layer 3 the default layer |
|`4` |Make layer 4 the default layer |
|`5` |Make layer 5 the default layer |
|`6` |Make layer 6 the default layer |
|`7` |Make layer 7 the default layer |
## Keycodes :id=keycodes
|Key |Aliases |Description |
|----------------------------------|---------|--------------------------------------------------------------------------|
|`MAGIC_SWAP_CONTROL_CAPSLOCK` |`CL_SWAP`|Swap Caps Lock and Left Control |
|`MAGIC_UNSWAP_CONTROL_CAPSLOCK` |`CL_NORM`|Unswap Caps Lock and Left Control |
|`MAGIC_CAPSLOCK_TO_CONTROL` |`CL_CTRL`|Treat Caps Lock as Control |
|`MAGIC_UNCAPSLOCK_TO_CONTROL` |`CL_CAPS`|Stop treating Caps Lock as Control |
|`MAGIC_SWAP_LCTL_LGUI` |`LCG_SWP`|Swap Left Control and GUI |
|`MAGIC_UNSWAP_LCTL_LGUI` |`LCG_NRM`|Unswap Left Control and GUI |
|`MAGIC_SWAP_RCTL_RGUI` |`RCG_SWP`|Swap Right Control and GUI |
|`MAGIC_UNSWAP_RCTL_RGUI` |`RCG_NRM`|Unswap Right Control and GUI |
|`MAGIC_SWAP_CTL_GUI` |`CG_SWAP`|Swap Control and GUI on both sides |
|`MAGIC_UNSWAP_CTL_GUI` |`CG_NORM`|Unswap Control and GUI on both sides |
|`MAGIC_TOGGLE_CTL_GUI` |`CG_TOGG`|Toggle Control and GUI swap on both sides |
|`MAGIC_SWAP_LALT_LGUI` |`LAG_SWP`|Swap Left Alt and GUI |
|`MAGIC_UNSWAP_LALT_LGUI` |`LAG_NRM`|Unswap Left Alt and GUI |
|`MAGIC_SWAP_RALT_RGUI` |`RAG_SWP`|Swap Right Alt and GUI |
|`MAGIC_UNSWAP_RALT_RGUI` |`RAG_NRM`|Unswap Right Alt and GUI |
|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides |
|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Alt and GUI on both sides |
|`MAGIC_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Alt and GUI swap on both sides |
|`MAGIC_NO_GUI` |`GUI_OFF`|Disable the GUI keys |
|`MAGIC_UNNO_GUI` |`GUI_ON` |Enable the GUI keys |
|`MAGIC_SWAP_GRAVE_ESC` |`GE_SWAP`|Swap <code>&#96;</code> and Escape |
|`MAGIC_UNSWAP_GRAVE_ESC` |`GE_NORM`|Unswap <code>&#96;</code> and Escape |
|`MAGIC_SWAP_BACKSLASH_BACKSPACE` |`BS_SWAP`|Swap `\` and Backspace |
|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|`BS_NORM`|Unswap `\` and Backspace |
|`MAGIC_HOST_NKRO` |`NK_ON` |Enable N-key rollover |
|`MAGIC_UNHOST_NKRO` |`NK_OFF` |Disable N-key rollover |
|`MAGIC_TOGGLE_NKRO` |`NK_TOGG`|Toggle N-key rollover |
|`MAGIC_EE_HANDS_LEFT` |`EH_LEFT`|Set the master half of a split keyboard as the left hand (for `EE_HANDS`) |
|`MAGIC_EE_HANDS_RIGHT` |`EH_RGHT`|Set the master half of a split keyboard as the right hand (for `EE_HANDS`)|
## Configuration
If you would like to change the hotkey assignments for Bootmagic, `#define` these in your `config.h` at either the keyboard or keymap level.
|Define |Default |Description |
|----------------------------------------|-------------|---------------------------------------------------|
|`BOOTMAGIC_KEY_SALT` |`KC_SPACE` |The Bootmagic key |
|`BOOTMAGIC_KEY_SKIP` |`KC_ESC` |Ignore Bootmagic configuration in EEPROM |
|`BOOTMAGIC_KEY_EEPROM_CLEAR` |`KC_BSPACE` |Clear the EEPROM configuration |
|`BOOTMAGIC_KEY_BOOTLOADER` |`KC_B` |Enter the bootloader |
|`BOOTMAGIC_KEY_DEBUG_ENABLE` |`KC_D` |Toggle debugging over serial |
|`BOOTMAGIC_KEY_DEBUG_MATRIX` |`KC_X` |Toggle matrix debugging |
|`BOOTMAGIC_KEY_DEBUG_KEYBOARD` |`KC_K` |Toggle keyboard debugging |
|`BOOTMAGIC_KEY_DEBUG_MOUSE` |`KC_M` |Toggle mouse debugging |
|`BOOTMAGIC_KEY_EE_HANDS_LEFT` |`KC_L` |Set "Left Hand" for EE_HANDS handedness |
|`BOOTMAGIC_KEY_EE_HANDS_RIGHT` |`KC_R` |Set "Right Hand" for EE_HANDS handedness |
|`BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK` |`KC_LCTRL` |Swap Left Control and Caps Lock |
|`BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL` |`KC_CAPSLOCK`|Toggle treating Caps Lock as Left Control |
|`BOOTMAGIC_KEY_SWAP_LALT_LGUI` |`KC_LALT` |Toggle swapping Left Alt and Left GUI (for macOS) |
|`BOOTMAGIC_KEY_SWAP_RALT_RGUI` |`KC_RALT` |Toggle swapping Right Alt and Right GUI (for macOS)|
|`BOOTMAGIC_KEY_NO_GUI` |`KC_LGUI` |Toggle the GUI keys (useful when gaming) |
|`BOOTMAGIC_KEY_SWAP_GRAVE_ESC` |`KC_GRAVE` |Toggle swapping <code>&#96;</code> and Escape |
|`BOOTMAGIC_KEY_SWAP_BACKSLASH_BACKSPACE`|`KC_BSLASH` |Toggle swapping `\` and Backspace |
|`BOOTMAGIC_HOST_NKRO` |`KC_N` |Toggle N-Key Rollover (NKRO) |
|`BOOTMAGIC_KEY_DEFAULT_LAYER_0` |`KC_0` |Make layer 0 the default layer |
|`BOOTMAGIC_KEY_DEFAULT_LAYER_1` |`KC_1` |Make layer 1 the default layer |
|`BOOTMAGIC_KEY_DEFAULT_LAYER_2` |`KC_2` |Make layer 2 the default layer |
|`BOOTMAGIC_KEY_DEFAULT_LAYER_3` |`KC_3` |Make layer 3 the default layer |
|`BOOTMAGIC_KEY_DEFAULT_LAYER_4` |`KC_4` |Make layer 4 the default layer |
|`BOOTMAGIC_KEY_DEFAULT_LAYER_5` |`KC_5` |Make layer 5 the default layer |
|`BOOTMAGIC_KEY_DEFAULT_LAYER_6` |`KC_6` |Make layer 6 the default layer |
|`BOOTMAGIC_KEY_DEFAULT_LAYER_7` |`KC_7` |Make layer 7 the default layer |
# Bootmagic Lite :id=bootmagic-lite
In addition to the full blown Bootmagic feature, is the Bootmagic Lite feature that only handles jumping into the bootloader. This is great for boards that don't have a physical reset button but you need a way to jump into the bootloader, and don't want to deal with the headache that Bootmagic can cause.
The Bootmagic Lite feature that only handles jumping into the bootloader. This is great for boards that don't have a physical reset button, giving you a way to jump into the bootloader
To enable this version of Bootmagic, you need to enable it in your `rules.mk` with:
On some keyboards Bootmagic Lite is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk` with:
```make
BOOTMAGIC_ENABLE = lite
BOOTMAGIC_ENABLE = yes
```
?> You may see `lite` being used in place of `yes`.
Additionally, you may want to specify which key to use. This is especially useful for keyboards that have unusual matrices. To do so, you need to specify the row and column of the key that you want to use. Add these entries to your `config.h` file:
```c
@ -142,7 +21,7 @@ By default, these are set to 0 and 0, which is usually the "ESC" key on a majori
And to trigger the bootloader, you hold this key down when plugging the keyboard in. Just the single key.
!> Using bootmagic lite will **always reset** the EEPROM, so you will lose any settings that have been saved.
!> Using Bootmagic Lite will **always reset** the EEPROM, so you will lose any settings that have been saved.
## Split Keyboards
@ -174,4 +53,10 @@ void bootmagic_lite(void) {
}
```
You can additional feature here. For instance, resetting the eeprom or requiring additional keys to be pressed to trigger bootmagic. Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware.
You can additional feature here. For instance, resetting the EEPROM or requiring additional keys to be pressed to trigger Bootmagic Lite. Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware.
## Addenda
To manipulate settings that were formerly configured through the now-deprecated full Bootmagic feature, see [Magic Keycodes](keycodes_magic.md).
The Command feature, formerly known as Magic, also allows you to control different aspects of your keyboard. While it shares some functionality with Magic Keycodes, it also allows you to do things that Magic Keycodes cannot, such as printing version information to the console. For more information, see [Command](feature_command.md).

292
docs/feature_combo.md
View file

@ -1,24 +1,39 @@
# Combos
The Combo feature is a chording type solution for adding custom actions. It lets you hit multiple keys at once and produce a different effect. For instance, hitting `A` and `S` within the tapping term would hit `ESC` instead, or have it perform even more complex tasks.
The Combo feature is a chording type solution for adding custom actions. It lets you hit multiple keys at once and produce a different effect. For instance, hitting `A` and `S` within the combo term would hit `ESC` instead, or have it perform even more complex tasks.
To enable this feature, you need to add `COMBO_ENABLE = yes` to your `rules.mk`.
Additionally, in your `config.h`, you'll need to specify the number of combos that you'll be using, by adding `#define COMBO_COUNT 1` (replacing 1 with the number that you're using).
<!-- At this time, this is necessary -->
Additionally, in your `config.h`, you'll need to specify the number of combos that you'll be using, by adding `#define COMBO_COUNT 1` (replacing 1 with the number that you're using). It is also possible to not define this and instead set the variable `COMBO_LEN` yourself. There's a trick where we don't need to think about this variable at all. More on this later.
Also, by default, the tapping term for the Combos is set to the same value as `TAPPING_TERM` (200 by default on most boards). But you can specify a different value by defining it in your `config.h`. For instance: `#define COMBO_TERM 300` would set the time out period for combos to 300ms.
Then, your `keymap.c` file, you'll need to define a sequence of keys, terminated with `COMBO_END`, and a structure to list the combination of keys, and it's resulting action.
Then, in your `keymap.c` file, you'll need to define a sequence of keys, terminated with `COMBO_END`, and a structure to list the combination of keys, and its resulting action.
```c
const uint16_t PROGMEM test_combo[] = {KC_A, KC_B, COMBO_END};
combo_t key_combos[COMBO_COUNT] = {COMBO(test_combo, KC_ESC)};
const uint16_t PROGMEM test_combo1[] = {KC_A, KC_B, COMBO_END};
const uint16_t PROGMEM test_combo2[] = {KC_C, KC_D, COMBO_END};
combo_t key_combos[COMBO_COUNT] = {
COMBO(test_combo1, KC_ESC),
COMBO(test_combo2, LCTL(KC_Z)), // keycodes with modifiers are possible too!
};
```
This will send "Escape" if you hit the A and B keys.
This will send "Escape" if you hit the A and B keys, and Ctrl+Z when you hit the C and D keys.
!> This method only supports [basic keycodes](keycodes_basic.md). See the examples for more control.
As of [PR#8591](https://github.com/qmk/qmk_firmware/pull/8591/), it is possible to fire combos from ModTap keys and LayerTap keys. So in the above example you could have keys `LSFT_T(KC_A)` and `LT(_LAYER, KC_B)` and it would work. So Home Row Mods and Home Row Combos at same time is now a thing!
It is also now possible to overlap combos. Before, with the example below both combos would activate when all three keys were pressed. Now only the three key combo will activate.
```c
const uint16_t PROGMEM test_combo1[] = {LSFT_T(KC_A), LT(_LAYER, KC_B), COMBO_END};
const uint16_t PROGMEM test_combo2[] = {LSFT_T(KC_A), LT(_LAYER, KC_B), KC_C, COMBO_END};
combo_t key_combos[COMBO_COUNT] = {
COMBO(test_combo1, KC_ESC)
COMBO(test_combo2, KC_TAB)
};
```
Executing more complex keycodes like ModTaps and LayerTaps is now also possible.
## Examples
@ -27,63 +42,68 @@ If you want to add a list, then you'd use something like this:
```c
enum combos {
AB_ESC,
JK_TAB
JK_TAB,
QW_SFT,
SD_LAYER,
};
const uint16_t PROGMEM ab_combo[] = {KC_A, KC_B, COMBO_END};
const uint16_t PROGMEM jk_combo[] = {KC_J, KC_K, COMBO_END};
const uint16_t PROGMEM qw_combo[] = {KC_Q, KC_W, COMBO_END};
const uint16_t PROGMEM sd_combo[] = {KC_S, KC_D, COMBO_END};
combo_t key_combos[COMBO_COUNT] = {
[AB_ESC] = COMBO(ab_combo, KC_ESC),
[JK_TAB] = COMBO(jk_combo, KC_TAB)
[JK_TAB] = COMBO(jk_combo, KC_TAB),
[QW_SFT] = COMBO(qw_combo, KC_LSFT)
[SD_LAYER] = COMBO(layer_combo, MO(_LAYER)),
};
```
For a more complicated implementation, you can use the `process_combo_event` function to add custom handling.
Additionally, this example shows how you can leave `COMBO_COUNT` undefined.
```c
enum combo_events {
ZC_COPY,
XV_PASTE
EM_EMAIL,
BSPC_LSFT_CLEAR,
COMBO_LENGTH
};
uint16_t COMBO_LEN = COMBO_LENGTH; // remove the COMBO_COUNT define and use this instead!
const uint16_t PROGMEM copy_combo[] = {KC_Z, KC_C, COMBO_END};
const uint16_t PROGMEM paste_combo[] = {KC_X, KC_V, COMBO_END};
const uint16_t PROGMEM email_combo[] = {KC_E, KC_M, COMBO_END};
const uint16_t PROGMEM clear_line_combo[] = {KC_BSPC, KC_LSFT, COMBO_END};
combo_t key_combos[COMBO_COUNT] = {
[ZC_COPY] = COMBO_ACTION(copy_combo),
[XV_PASTE] = COMBO_ACTION(paste_combo),
combo_t key_combos[] = {
[EM_EMAIL] = COMBO_ACTION(email_combo),
[BSPC_LSFT_CLEAR] = COMBO_ACTION(clear_line_combo),
};
/* COMBO_ACTION(x) is same as COMBO(x, KC_NO) */
void process_combo_event(uint16_t combo_index, bool pressed) {
switch(combo_index) {
case ZC_COPY:
case EM_EMAIL:
if (pressed) {
tap_code16(LCTL(KC_C));
SEND_STRING("john.doe@example.com");
}
break;
case XV_PASTE:
case BSPC_LSFT_CLEAR:
if (pressed) {
tap_code16(LCTL(KC_V));
tap_code16(KC_END);
tap_code16(S(KC_HOME));
tap_code16(KC_BSPC);
}
break;
}
}
```
This will send Ctrl+C if you hit Z and C, and Ctrl+V if you hit X and V. But you could change this to do stuff like change layers, play sounds, or change settings.
This will send "john.doe@example.com" if you chord E and M together, and clear the current line with Backspace and Left-Shift. You could change this to do stuff like play sounds or change settings.
## Additional Configuration
It is worth noting that `COMBO_ACTION`s are not needed anymore. As of [PR#8591](https://github.com/qmk/qmk_firmware/pull/8591/), it is possible to run your own custom keycodes from combos. Just define the custom keycode, program its functionality in `process_record_user`, and define a combo with `COMBO(<key_array>, <your_custom_keycode>)`.
If you're using long combos, or even longer combos, you may run into issues with this, as the structure may not be large enough to accommodate what you're doing.
In this case, you can add either `#define EXTRA_LONG_COMBOS` or `#define EXTRA_EXTRA_LONG_COMBOS` in your `config.h` file.
You may also be able to enable action keys by defining `COMBO_ALLOW_ACTION_KEYS`.
## Keycodes
You can enable, disable and toggle the Combo feature on the fly. This is useful if you need to disable them temporarily, such as for a game.
## Keycodes
You can enable, disable and toggle the Combo feature on the fly. This is useful if you need to disable them temporarily, such as for a game. The following keycodes are available for use in your `keymap.c`
|Keycode |Description |
|----------|---------------------------------|
@ -91,6 +111,187 @@ You can enable, disable and toggle the Combo feature on the fly. This is useful
|`CMB_OFF` |Turns off Combo feature |
|`CMB_TOG` |Toggles Combo feature on and off |
# Advanced Configuration
These configuration settings can be set in your `config.h` file.
## Combo Term
By default, the timeout for the Combos to be recognized is set to 50ms. This can be changed if accidental combo misfires are happening or if you're having difficulties pressing keys at the same time. For instance, `#define COMBO_TERM 40` would set the timeout period for combos to 40ms.
## Buffer and state sizes
If you're using long combos, or you have a lot of overlapping combos, you may run into issues with this, as the buffers may not be large enough to accommodate what you're doing. In this case, you can configure the sizes of the buffers used. Be aware, larger combo sizes and larger buffers will increase memory usage!
To configure the amount of keys a combo can be composed of, change the following:
| Keys | Define to be set |
|------|-----------------------------------|
| 6 | `#define EXTRA_SHORT_COMBOS` |
| 8 | QMK Default |
| 16 | `#define EXTRA_LONG_COMBOS` |
| 32 | `#define EXTRA_EXTRA_LONG_COMBOS` |
Defining `EXTRA_SHORT_COMBOS` combines a combo's internal state into just one byte. This can, in some cases, save some memory. If it doesn't, no point using it. If you do, you also have to make sure you don't define combos with more than 6 keys.
Processing combos has two buffers, one for the key presses, another for the combos being activated. Use the following options to configure the sizes of these buffers:
| Define | Default |
|-------------------------------------|------------------------------------------------------|
| `#define COMBO_KEY_BUFFER_LENGTH 8` | 8 (the key amount `(EXTRA_)EXTRA_LONG_COMBOS` gives) |
| `#define COMBO_BUFFER_LENGTH 4` | 4 |
## Modifier Combos
If a combo resolves to a Modifier, the window for processing the combo can be extended independently from normal combos. By default, this is disabled but can be enabled with `#define COMBO_MUST_HOLD_MODS`, and the time window can be configured with `#define COMBO_HOLD_TERM 150` (default: `TAPPING_TERM`). With `COMBO_MUST_HOLD_MODS`, you cannot tap the combo any more which makes the combo less prone to misfires.
## Per Combo Timing, Holding and Tapping
For each combo, it is possible to configure the time window it has to pressed in, if it needs to be held down, or if it needs to be tapped.
For example, tap-only combos are useful if any (or all) of the underlying keys is a Mod-Tap or a Layer-Tap key. When you tap the combo, you get the combo result. When you press the combo and hold it down, the combo doesn't actually activate. Instead the keys are processed separately as if the combo wasn't even there.
In order to use these features, the following configuration options and functions need to be defined. Coming up with useful timings and configuration is left as an exercise for the reader.
| Config Flag | Function | Description |
|-----------------------------|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
| `COMBO_TERM_PER_COMBO` | uint16_t get_combo_term(uint16_t index, combo_t \*combo) | Optional per-combo timeout window. (default: `COMBO_TERM`) |
| `COMBO_MUST_HOLD_PER_COMBO` | bool get_combo_must_hold(uint16_t index, combo_t \*combo) | Controls if a given combo should fire immediately on tap or if it needs to be held. (default: `false`) |
| `COMBO_MUST_TAP_PER_COMBO` | bool get_combo_must_tap(uint16_t index, combo_t \*combo) | Controls if a given combo should fire only if tapped within `COMBO_HOLD_TERM`. (default: `false`) |
Examples:
```c
uint16_t get_combo_term(uint16_t index, combo_t *combo) {
// decide by combo->keycode
switch (combo->keycode) {
case KC_X:
return 50;
}
// or with combo index, i.e. its name from enum.
switch (index) {
case COMBO_NAME_HERE:
return 9001;
}
// And if you're feeling adventurous, you can even decide by the keys in the chord,
// i.e. the exact array of keys you defined for the combo.
// This can be useful if your combos have a common key and you want to apply the
// same combo term for all of them.
if (combo->keys[0] == KC_ENTER) { // if first key in the array is KC_ENTER
return 150;
}
return COMBO_TERM;
}
bool get_combo_must_hold(uint16_t index, combo_t *combo) {
// Same as above, decide by keycode, the combo index, or by the keys in the chord.
if (KEYCODE_IS_MOD(combo->keycode) ||
(combo->keycode >= QK_MOMENTARY && combo->keycode <= QK_MOMENTARY_MAX) // MO(kc) keycodes
) {
return true;
}
switch (index) {
case COMBO_NAME_HERE:
return true;
}
return false;
}
bool get_combo_must_tap(uint16_t index, combo_t *combo) {
// If you want all combos to be tap-only, just uncomment the next line
// return true
// If you want *all* combos, that have Mod-Tap/Layer-Tap/Momentary keys in its chord, to be tap-only, this is for you:
uint16_t key;
uint8_t idx = 0;
while ((key = pgm_read_word(&combo->keys[idx])) != COMBO_END) {
switch (key) {
case QK_MOD_TAP...QK_MOD_TAP_MAX:
case QK_LAYER_TAP...QK_LAYER_TAP_MAX:
case QK_MOMENTARY...QK_MOMENTARY_MAX:
return true;
}
idx += 1;
}
return false;
}
```
## Variable Length Combos
If you leave `COMBO_COUNT` undefined in `config.h`, it allows you to programmatically declare the size of the Combo data structure and avoid updating `COMBO_COUNT`. Instead a variable called `COMBO_LEN` has to be set. It can be set with something similar to the following in `keymap.c`: `uint16_t COMBO_LEN = sizeof(key_combos) / sizeof(key_combos[0]);` or by adding `COMBO_LENGTH` as the *last* entry in the combo enum and then `uint16_t COMBO_LEN = COMBO_LENGTH;` as such:
```c
enum myCombos {
...,
COMBO_LENGTH
};
uint16_t COMBO_LEN = COMBO_LENGTH;
```
Regardless of the method used to declare `COMBO_LEN`, this also requires to convert the `combo_t key_combos[COMBO_COUNT] = {...};` line to `combo_t key_combos[] = {...};`.
## Combo timer
Normally, the timer is started on the first key press and then reset on every subsequent key press within the `COMBO_TERM`.
Inputting combos is relaxed like this, but also slightly more prone to accidental misfires.
The next two options alter the behaviour of the timer.
### `#define COMBO_STRICT_TIMER`
With `COMBO_STRICT_TIMER`, the timer is started only on the first key press.
Inputting combos is now less relaxed; you need to make sure the full chord is pressed within the `COMBO_TERM`.
Misfires are less common but if you type multiple combos fast, there is a
chance that the latter ones might not activate properly.
### `#define COMBO_NO_TIMER`
By defining `COMBO_NO_TIMER`, the timer is disabled completely and combos are activated on the first key release.
This also disables the "must hold" functionalities as they just wouldn't work at all.
## Customizable key releases
By defining `COMBO_PROCESS_KEY_RELEASE` and implementing the function `bool process_combo_key_release(uint16_t combo_index, combo_t *combo, uint8_t key_index, uint16_t keycode)`, you can run your custom code on each key release after a combo was activated. For example you could change the RGB colors, activate haptics, or alter the modifiers.
You can also release a combo early by returning `true` from the function.
Here's an example where a combo resolves to two modifiers, and on key releases the modifiers are unregistered one by one, depending on which key was released.
```c
enum combos {
AB_MODS,
COMBO_LENGTH
};
uint16_t COMBO_LEN = COMBO_LENGTH;
const uint16_t PROGMEM ab_combo[] = {KC_A, KC_B, COMBO_END};
combo_t key_combos[] = {
[AB_MODS] = COMBO(ab_combo, LCTL(KC_LSFT)),
};
bool process_combo_key_release(uint16_t combo_index, combo_t *combo, uint8_t key_index, uint16_t keycode) {
switch (combo_index) {
case AB_MODS:
switch(keycode) {
case KC_A:
unregister_mods(MOD_MASK_CTRL);
break;
case KC_B:
unregister_mods(MOD_MASK_SHIFT);
break;
}
return false; // do not release combo
}
return false;
}
```
## Layer independent combos
If you, for example, use multiple base layers for different key layouts, one for QWERTY, and another one for Colemak, you might want your combos to work from the same key positions on all layers. Defining the same combos again for another layout is redundant and takes more memory. The solution is to just check the keycodes from one layer.
With `#define COMBO_ONLY_FROM_LAYER _LAYER_A` the combos' keys are always checked from layer `_LAYER_A` even though the active layer would be `_LAYER_B`.
## User callbacks
In addition to the keycodes, there are a few functions that you can use to set the status, or check it:
@ -101,3 +302,28 @@ In addition to the keycodes, there are a few functions that you can use to set t
| `combo_disable()` | Disables the combo feature, and clears the combo buffer |
| `combo_toggle()` | Toggles the state of the combo feature |
| `is_combo_enabled()` | Returns the status of the combo feature state (true or false) |
# Dictionary Management
Having 3 places to update when adding new combos or altering old ones does become cumbersome when you have a lot of combos. We can alleviate this with some magic! ... If you consider C macros magic.
First, you need to add `VPATH += keyboards/gboards` to your `rules.mk`. Next, include the file `g/keymap_combo.h` in your `keymap.c`.
!> This functionality uses the same `process_combo_event` function as `COMBO_ACTION` macros do, so you cannot use the function yourself in your keymap. Instead, you have to define the `case`s of the `switch` statement by themselves within `inject.h`, which `g/keymap_combo.h` will then include into the function.
Then, write your combos in `combos.def` file in the following manner:
```c
// name result chord keys
COMB(AB_ESC, KC_ESC, KC_A, KC_B)
COMB(JK_TAB, KC_TAB, KC_J, KC_K)
COMB(JKL_SPC, KC_SPC, KC_J, KC_K, KC_L)
COMB(BSSL_CLR, KC_NO, KC_BSPC, KC_LSFT) // using KC_NO as the resulting keycode is the same as COMBO_ACTION before.
COMB(QW_UNDO, C(KC_Z), KC_Q, KC_W)
SUBS(TH_THE, "the", KC_T, KC_H) // SUBS uses SEND_STRING to output the given string.
...
```
Now, you can update only one place to add or alter combos. You don't even need to remember to update the `COMBO_COUNT` or the `COMBO_LEN` variables at all. Everything is taken care of. Magic!
For small to huge ready made dictionaries of combos, you can check out http://combos.gboards.ca/.

2
docs/feature_command.md
View file

@ -1,6 +1,6 @@
# Command
Command, formerly known as Magic, is a way to change your keyboard's behavior without having to flash or unplug it to use [Bootmagic](feature_bootmagic.md). There is a lot of overlap between this functionality and the [Bootmagic Keycodes](feature_bootmagic.md#keycodes). Wherever possible we encourage you to use that feature instead of Command.
Command, formerly known as Magic, is a way to change your keyboard's behavior without having to flash or unplug it to use [Bootmagic Lite](feature_bootmagic.md). There is a lot of overlap between this functionality and the [Magic Keycodes](keycodes_magic.md). Wherever possible we encourage you to use that feature instead of Command.
On some keyboards Command is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk`:

21
docs/feature_debounce_type.md
View file

@ -92,15 +92,6 @@ susceptible to noise, you must choose a debounce method that will also mitigate
## Debounce algorithms supported by QMK
QMK supports multiple debounce algorithms through its debounce API.
The logic for which debounce method called is below. It checks various defines that you have set in ```rules.mk```
```
DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce
DEBOUNCE_TYPE?= sym_defer_g
ifneq ($(strip $(DEBOUNCE_TYPE)), custom)
QUANTUM_SRC += $(DEBOUNCE_DIR)/$(strip $(DEBOUNCE_TYPE)).c
endif
```
### Debounce selection
@ -121,16 +112,16 @@ DEBOUNCE_TYPE = <name of algorithm>
Where name of algorithm is one of:
* ```sym_defer_g``` - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occurred, all input changes are pushed.
* This is the current default algorithm. This is the highest performance algorithm with lowest memory usage, and it's also noise-resistant.
* ```sym_eager_pr``` - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row.
* ```sym_eager_pr``` - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row.
For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be
appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use.
* ```sym_eager_pk``` - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key
* ```sym_defer_pk``` - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key status change is pushed.
* ```asym_eager_defer_pk``` - debouncing per key. On a key-down state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key. On a key-up state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key-up status change is pushed.
### A couple algorithms that could be implemented in the future:
* ```sym_defer_pr```
* ```sym_eager_g```
* ```asym_eager_defer_pk```
### Use your own debouncing code
You have the option to implement you own debouncing algorithm. To do this:
@ -140,11 +131,3 @@ You have the option to implement you own debouncing algorithm. To do this:
* Debouncing occurs after every raw matrix scan.
* Use num_rows rather than MATRIX_ROWS, so that split keyboards are supported correctly.
* If the algorithm might be applicable to other keyboards, please consider adding it to ```quantum/debounce```
### Old names
The following old names for existing algorithms will continue to be supported, however it is recommended to use the new names instead.
* sym_g - old name for sym_defer_g
* eager_pk - old name for sym_eager_pk
* sym_pk - old name for sym_defer_pk
* eager_pr - old name for sym_eager_pr

35
docs/feature_digitizer.md Normal file
View file

@ -0,0 +1,35 @@
## Digitizer
The digitizer HID interface allows setting the mouse cursor position at absolute coordinates, unlike the Pointing Device feature that applies relative displacements.
To enable the digitizer interface, add the following line to your rules.mk:
```makefile
DIGITIZER_ENABLE = yes
```
In order to change the mouse cursor position from your keymap.c file, include the digitizer header :
```c
#include "digitizer.h"
```
This gives you access to the `digitizer` structure which members allow you to change the cursor position.
The coordinates are normalized, meaning there value must be set between 0 and 1. For the `x` coordinate, the value `0` is the leftmost position, whereas the value `1` is the rightmost position.
For the `y` coordinate, `0` is at the top and `1` at the bottom.
Here is an example setting the cursor in the middle of the screen:
```c
digitizer_t digitizer;
digitizer.x = 0.5;
digitizer.y = 0.5;
digitizer.tipswitch = 0;
digitizer.inrange = 1;
digitizer_set_report(digitizer);
```
The `tipswitch` member triggers what equates to a click when set to `1`. The `inrange` member is required for the change in coordinates to be taken. It can then be set to `0` in a new report to signal the end of the digitizer interaction, but it is not strictly required.
Once all members are set to the desired value, the `status` member needs its bitmask `DZ_UPDATED` to be set so the report is sent during the next main loop iteration.

19
docs/feature_dip_switch.md
View file

@ -9,6 +9,8 @@ and this to your `config.h`:
```c
// Connects each switch in the dip switch to the GPIO pin of the MCU
#define DIP_SWITCH_PINS { B14, A15, A10, B9 }
// For split keyboards, you can separately define the right side pins
#define DIP_SWITCH_PINS_RIGHT { ... }
```
or
@ -23,8 +25,9 @@ or
The callback functions can be inserted into your `<keyboard>.c`:
```c
void dip_switch_update_kb(uint8_t index, bool active) {
dip_switch_update_user(index, active);
bool dip_switch_update_kb(uint8_t index, bool active) {
if (!dip_switch_update_user(index, active)) { return false; }
return true;
}
```
@ -32,7 +35,7 @@ void dip_switch_update_kb(uint8_t index, bool active) {
or `keymap.c`:
```c
void dip_switch_update_user(uint8_t index, bool active) {
bool dip_switch_update_user(uint8_t index, bool active) {
switch (index) {
case 0:
if(active) { audio_on(); } else { audio_off(); }
@ -57,6 +60,7 @@ void dip_switch_update_user(uint8_t index, bool active) {
}
break;
}
return true;
}
```
@ -64,8 +68,9 @@ Additionally, we support bit mask functions which allow for more complex handlin
```c
void dip_switch_update_mask_kb(uint32_t state) {
dip_switch_update_mask_user(state);
bool dip_switch_update_mask_kb(uint32_t state) {
if (!dip_switch_update_mask_user(state)) { return false; }
return true;
}
```
@ -73,7 +78,7 @@ void dip_switch_update_mask_kb(uint32_t state) {
or `keymap.c`:
```c
void dip_switch_update_mask_user(uint32_t state) {
bool dip_switch_update_mask_user(uint32_t state) {
if (state & (1UL<<0) && state & (1UL<<1)) {
layer_on(_ADJUST); // C on esc
} else {
@ -89,10 +94,10 @@ void dip_switch_update_mask_user(uint32_t state) {
} else {
layer_off(_TEST_B);
}
return true;
}
```
## Hardware
### Connects each switch in the dip switch to the GPIO pin of the MCU

6
docs/feature_encoders.md
View file

@ -38,6 +38,12 @@ It can also be defined per-encoder, by instead defining:
#define ENCODER_RESOLUTIONS { 4, 2 }
```
For 4× encoders you also can assign default position if encoder skips pulses when it changes direction. For example, if your encoder send high level on both pins by default, define this:
```c
#define ENCODER_DEFAULT_POS 0x3
```
## Split Keyboards
If you are using different pinouts for the encoders on each half of a split keyboard, you can define the pinout (and optionally, resolutions) for the right half like this:

26
docs/feature_haptic_feedback.md
View file

@ -162,4 +162,28 @@ This will set what sequence HPT_RST will set as the active mode. If not defined,
### DRV2605L Continuous Haptic Mode
This mode sets continuous haptic feedback with the option to increase or decrease strength.
This mode sets continuous haptic feedback with the option to increase or decrease strength.
## Haptic Key Exclusion
The Haptic Exclusion is implemented as `__attribute__((weak)) bool get_haptic_enabled_key(uint16_t keycode, keyrecord_t *record)` in haptic.c. This allows a re-definition at the required level with the specific requirement / exclusion.
### NO_HAPTIC_MOD
With the entry of `#define NO_HAPTIC_MOD` in config.h, modifiers from Left Control to Right GUI will not trigger a feedback. This also includes modifiers in a Mod Tap configuration.
### NO_HAPTIC_FN
With the entry of `#define NO_HAPTIC_FN` in config.h, layer keys will not rigger a feedback.
### NO_HAPTIC_ALPHA
With the entry of `#define NO_HAPTIC_ALPHA` in config.h, none of the alpha keys (A ... Z) will trigger a feedback.
### NO_HAPTIC_PUNCTUATION
With the entry of `#define NO_HAPTIC_PUNCTUATION` in config.h, none of the following keys will trigger a feedback: Enter, ESC, Backspace, Space, Minus, Equal, Left Bracket, Right Bracket, Backslash, Non-US Hash, Semicolon, Quote, Grave, Comma, Slash, Dot, Non-US Backslash.
### NO_HAPTIC_LOCKKEYS
With the entry of `#define NO_HAPTIC_LOCKKEYS` in config.h, none of the following keys will trigger a feedback: Caps Lock, Scroll Lock, Num Lock.
### NO_HAPTIC_NAV
With the entry of `#define NO_HAPTIC_NAV` in config.h, none of the following keys will trigger a feedback: Print Screen, Pause, Insert, Delete, Page Down, Page Up, Left Arrow, Up Arrow, Right Arrow, Down Arrow, End, Home.
### NO_HAPTIC_NUMERIC
With the entry of `#define NO_HAPTIC_NUMERIC` in config.h, none of the following keys between 0 and 9 (KC_1 ... KC_0) will trigger a feedback.

229
docs/feature_key_overrides.md Normal file
View file

@ -0,0 +1,229 @@
# Key Overrides
Key overrides allow you to override modifier-key combinations to send a different modifier-key combination or perform completely custom actions. Don't want `shift` + `1` to type `!` on your computer? Use a key override to make your keyboard type something different when you press `shift` + `1`. The general behavior is like this: If `modifiers w` + `key x` are pressed, replace these keys with `modifiers y` + `key z` in the keyboard report.
You can use key overrides in a similar way to momentary layer/fn keys to activate custom keycodes/shortcuts, with a number of benefits: You completely keep the original use of the modifier keys, while being able to save space by removing fn keys from your keyboard. You can also easily configure _combinations of modifiers_ to trigger different actions than individual modifiers, and much more. The possibilities are quite vast and this documentation contains a few examples for inspiration throughout.
##### A few more examples to get started: You could use key overrides to...
- Send `brightness up/down` when pressing `ctrl` + `volume up/down`.
- Send `delete` when pressing `shift` + `backspace`.
- Create custom shortcuts or change existing ones: E.g. Send `ctrl`+`shift`+`z` when `ctrl`+`y` is pressed.
- Run custom code when `ctrl` + `alt` + `esc` is pressed.
## Setup
To enable this feature, you need to add `KEY_OVERRIDE_ENABLE = yes` to your `rules.mk`.
Then, in your `keymap.c` file, you'll need to define the array `key_overrides`, which defines all key overrides to be used. Each override is a value of type `key_override_t`. The array `key_overrides` is `NULL`-terminated and contains pointers to `key_override_t` values (`const key_override_t **`).
## Creating Key Overrides
The `key_override_t` struct has many options that allow you to precisely tune your overrides. The full reference is shown below. Instead of manually creating a `key_override_t` value, it is recommended to use these dedicated initializers:
#### `ko_make_basic(modifiers, key, replacement)`
Returns a `key_override_t`, which sends `replacement` (can be a key-modifer combination), when `key` and `modifiers` are all pressed down. This override still activates if any additional modifiers not specified in `modifiers` are also pressed down. See `ko_make_with_layers_and_negmods` to customize this behavior.
#### `ko_make_with_layers(modifiers, key, replacement, layers)`
Additionally takes a bitmask `layers` that defines on which layers the override is used.
#### `ko_make_with_layers_and_negmods(modifiers, key, replacement, layers, negative_mods)`
Additionally takes a bitmask `negative_mods` that defines which modifiers may not be pressed for this override to activate.
#### `ko_make_with_layers_negmods_and_options(modifiers, key, replacement, layers, negative_mods, options)`
Additionally takes a bitmask `options` that specifies additional options. See `ko_option_t` for available options.
For more customization possibilities, you may directly create a `key_override_t`, which allows you to customize even more behavior. Read further below for details and examples.
## Simple Example
This shows how the mentioned example of sending `delete` when `shift` + `backspace` are pressed is realized:
```c
const key_override_t delete_key_override = ko_make_basic(MOD_MASK_SHIFT, KC_BSPACE, KC_DELETE);
// This globally defines all key overrides to be used
const key_override_t **key_overrides = (const key_override_t *[]){
&delete_key_override,
NULL // Null terminate the array of overrides!
};
```
## Intermediate Difficulty Examples
### Media Controls & Screen Brightness
In this example a single key is configured to control media, volume and screen brightness by using key overrides.
- The key is set to send `play/pause` in the keymap.
The following key overrides will be configured:
- `Ctrl` + `play/pause` will send `next track`.
- `Ctrl` + `Shift` + `play/pause` will send `previous track`.
- `Alt` + `play/pause` will send `volume up`.
- `Alt` + `Shift` + `play/pause` will send `volume down`.
- `Ctrl` + `Alt` + `play/pause` will send `brightness up`.
- `Ctrl` + `Alt` + `Shift` + `play/pause` will send `brightness down`.
```c
const key_override_t next_track_override =
ko_make_with_layers_negmods_and_options(
MOD_MASK_CTRL, // Trigger modifiers: ctrl
KC_MPLY, // Trigger key: play/pause
KC_MNXT, // Replacement key
~0, // Activate on all layers
MOD_MASK_SA, // Do not activate when shift or alt are pressed
ko_option_no_reregister_trigger); // Specifies that the play key is not registered again after lifting ctrl
const key_override_t prev_track_override = ko_make_with_layers_negmods_and_options(MOD_MASK_CS, KC_MPLY,
KC_MPRV, ~0, MOD_MASK_ALT, ko_option_no_reregister_trigger);
const key_override_t vol_up_override = ko_make_with_layers_negmods_and_options(MOD_MASK_ALT, KC_MPLY,
KC_VOLU, ~0, MOD_MASK_CS, ko_option_no_reregister_trigger);
const key_override_t vol_down_override = ko_make_with_layers_negmods_and_options(MOD_MASK_SA, KC_MPLY,
KC_VOLD, ~0, MOD_MASK_CTRL, ko_option_no_reregister_trigger);
const key_override_t brightness_up_override = ko_make_with_layers_negmods_and_options(MOD_MASK_CA, KC_MPLY,
KC_BRIU, ~0, MOD_MASK_SHIFT, ko_option_no_reregister_trigger);
const key_override_t brightness_down_override = ko_make_basic(MOD_MASK_CSA, KC_MPLY, KC_BRID);
// This globally defines all key overrides to be used
const key_override_t **key_overrides = (const key_override_t *[]){
&next_track_override,
&prev_track_override,
&vol_up_override,
&vol_down_override,
&brightness_up_override,
&brightness_down_override,
NULL
};
```
### Flexible macOS-friendly Grave Escape
The [Grave Escape feature](https://docs.qmk.fm/using-qmk/advanced-keycodes/feature_grave_esc) is limited in its configurability and has [bugs when used on macOS](https://docs.qmk.fm/using-qmk/advanced-keycodes/feature_grave_esc#caveats). Key overrides can be used to achieve a similar functionality as Grave Escape, but with more customization and without bugs on macOS.
```c
// Shift + esc = ~
const key_override_t tilde_esc_override = ko_make_basic(MOD_MASK_SHIFT, KC_ESC, S(KC_GRAVE));
// GUI + esc = `
const key_override_t grave_esc_override = ko_make_basic(MOD_MASK_GUI, KC_ESC, KC_GRAVE);
const key_override_t **key_overrides = (const key_override_t *[]){
&tilde_esc_override,
&grave_esc_override,
NULL
};
```
In addition to not encountering unexpected bugs on macOS, you can also change the behavior as you wish. Instead setting `GUI` + `ESC` = `` ` `` you may change it to an arbitrary other modifier, for example `Ctrl` + `ESC` = `` ` ``.
## Advanced Examples
### Modifiers as Layer Keys
Do you really need a dedicated key to toggle your fn layer? With key overrides, perhaps not. This example shows how you can configure to use `rGUI` + `rAlt` (right GUI and right alt) to access a momentary layer like an fn layer. With this you completely eliminate the need to use a dedicated layer key. Of course the choice of modifier keys can be changed as needed, `rGUI` + `rAlt` is just an example here.
```c
// This is called when the override activates and deactivates. Enable the fn layer on activation and disable on deactivation
bool momentary_layer(bool key_down, void *layer) {
if (key_down) {
layer_on((uint8_t)(uintptr_t)layer);
} else {
layer_off((uint8_t)(uintptr_t)layer);
}
return false;
}
const key_override_t fn_override = {.trigger_mods = MOD_BIT(KC_RGUI) | MOD_BIT(KC_RCTL), //
.layers = ~(1 << LAYER_FN), //
.suppressed_mods = MOD_BIT(KC_RGUI) | MOD_BIT(KC_RCTL), //
.options = ko_option_no_unregister_on_other_key_down, //
.negative_mod_mask = (uint8_t) ~(MOD_BIT(KC_RGUI) | MOD_BIT(KC_RCTL)), //
.custom_action = momentary_layer, //
.context = (void *)LAYER_FN, //
.trigger = KC_NO, //
.replacement = KC_NO, //
.enabled = NULL};
```
## Keycodes
You can enable, disable and toggle all key overrides on the fly.
|Keycode |Description |Function Equivalent|
|----------|---------------------------------|--------|
|`KEY_OVERRIDE_ON` |Turns on Key Override feature | `key_override_on(void)`|
|`KEY_OVERRIDE_OFF` |Turns off Key Override feature |`key_override_off(void)`|
|`KEY_OVERRIDE_TOGGLE` |Toggles Key Override feature on and off |`key_override_toggle(void)`|
## Reference for `key_override_t`
Advanced users may need more customization than what is offered by the simple `ko_make` initializers. For this, directly create a `key_override_t` value and set all members. Below is a reference for all members of `key_override_t`.
| Member | Description |
|--------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `uint16_t trigger` | The non-modifier keycode that triggers the override. This keycode, and the necessary modifiers (`trigger_mods`) must be pressed to activate this override. Set this to the keycode of the key that should activate the override. Set to `KC_NO` to require only the necessary modifiers to be pressed and no non-modifier. |
| `uint8_t trigger_mods` | Which mods need to be down for activation. If both sides of a modifier are set (e.g. left ctrl and right ctrl) then only one is required to be pressed (e.g. left ctrl suffices). Use the `MOD_MASK_XXX` and `MOD_BIT()` macros for this. |
| `layer_state_t layers` | This is a BITMASK (!), defining which layers this override applies to. To use this override on layer i set the ith bit `(1 << i)`. |
| `uint8_t negative_mod_mask` | Which modifiers cannot be down. It must hold that `(active_modifiers & negative_mod_mask) == 0`, otherwise the key override will not be activated. An active override will be deactivated once this is no longer true. |
| `uint8_t suppressed_mods` | Modifiers to 'suppress' while the override is active. To suppress a modifier means that even though the modifier key is held down, the host OS sees the modifier as not pressed. Can be used to suppress the trigger modifiers, as a trivial example. |
| `uint16_t replacement` | The complex keycode to send as replacement when this override is triggered. This can be a simple keycode, a key-modifier combination (e.g. `C(KC_A)`), or `KC_NO` (to register no replacement keycode). Use in combination with suppressed_mods to get the correct modifiers to be sent. |
| `ko_option_t options` | Options controlling the behavior of the override, such as what actions are allowed to activate the override. |
| `bool (*custom_action)(bool activated, void *context)` | If not NULL, this function will be called right before the replacement key is registered, along with the provided context and a flag indicating whether the override was activated or deactivated. This function allows you to run some custom actions for specific key overrides. If you return `false`, the replacement key is not registered/unregistered as it would normally. Return `true` to register and unregister the override normally. |
| `void *context` | A context that will be passed to the custom action function. |
| `bool *enabled` | If this points to false this override will not be used. Set to NULL to always have this override enabled. |
### Reference for `ko_option_t`
Bitfield with various options controlling the behavior of a key override.
| Value | Description |
|------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `ko_option_activation_trigger_down` | Allow activating when the trigger key is pressed down. |
| `ko_option_activation_required_mod_down` | Allow activating when a necessary modifier is pressed down. |
| `ko_option_activation_negative_mod_up` | Allow activating when a negative modifier is released. |
| `ko_option_one_mod` | If set, any of the modifiers in `trigger_mods` will be enough to activate the override (logical OR of modifiers). If not set, all the modifiers in `trigger_mods` have to be pressed (logical AND of modifiers). |
| `ko_option_no_unregister_on_other_key_down` | If set, the override will not deactivate when another key is pressed down. Use only if you really know you need this. |
| `ko_option_no_reregister_trigger` | If set, the trigger key will never be registered again after the override is deactivated. |
| `ko_options_default` | The default options used by the `ko_make_xxx` functions |
## For Advanced Users: Inner Workings
This section explains how a key override works in detail, explaining where each member of `key_override_t` comes into play. Understanding this is essential to be able to take full advantage of all the options offered by key overrides.
#### Activation
When the necessary keys are pressed (`trigger_mods` + `trigger`), the override is 'activated' and the replacement key is registered in the keyboard report (`replacement`), while the `trigger` key is removed from the keyboard report. The trigger modifiers may also be removed from the keyboard report upon activation of an override (`suppressed_mods`). The override will not activate if any of the `negative_modifiers` are pressed.
Overrides can activate in three different cases:
1. The trigger key is pressed down and necessary modifiers are already down.
2. A necessary modifier is pressed down, while the trigger key and other necessary modifiers are already down.
3. A negative modifier is released, while all necessary modifiers and the trigger key are already down.
Use the `option` member to customize which of these events are allowed to activate your overrides (default: all three).
In any case, a key override can only activate if the `trigger` key is the _last_ non-modifier key that was pressed down. This emulates the behavior of how standard OSes (macOS, Windows, Linux) handle normal key input (to understand: Hold down `a`, then also hold down `b`, then hold down `shift`; `B` will be typed but not `A`).
#### Deactivation
An override is 'deactivated' when one of the trigger keys (`trigger_mods`, `trigger`) is lifted, another non-modifier key is pressed down, or one of the `negative_modifiers` is pressed down. When an override deactivates, the `replacement` key is removed from the keyboard report, while the `suppressed_mods` that are still held down are re-added to the keyboard report. By default, the `trigger` key is re-added to the keyboard report if it is still held down and no other non-modifier key has been pressed since. This again emulates the behavior of how standard OSes handle normal key input (To understand: hold down `a`, then also hold down `b`, then also `shift`, then release `b`; `A` will not be typed even though you are holding the `a` and `shift` keys). Use the `option` field `ko_option_no_reregister_trigger` to prevent re-registering the trigger key in all cases.
#### Key Repeat Delay
A third way in which standard OS-handling of modifier-key input is emulated in key overrides is with a ['key repeat delay'](https://www.dummies.com/computers/pcs/set-your-keyboards-repeat-delay-and-repeat-rate/). To explain what this is, let's look at how normal keyboard input is handled by mainstream OSes again: If you hold down `a`, followed by `shift`, you will see the letter `a` is first typed, then for a short moment nothing is typed and then repeating `A`s are typed. Take note that, although shift is pressed down just after `a` is pressed, it takes a moment until `A` is typed. This is caused by the aforementioned key repeat delay, and it is a feature that prevents unwanted repeated characters from being typed.
This applies equally to releasing a modifier: When you hold `shift`, then press `a`, the letter `A` is typed. Now if you release `shift` first, followed by `a` shortly after, you will not see the letter `a` being typed, even though for a short moment of time you were just holding down the key `a`. This is because no modified characters are typed until the key repeat delay has passed.
This exact behavior is implemented in key overrides as well: If a key override for `shift` + `a` = `b` exists, and `a` is pressed and held, followed by `shift`, you will not immediately see the letter `b` being typed. Instead, this event is deferred for a short moment, until the key repeat delay has passed, measured from the moment when the trigger key (`a`) was pressed down.
The duration of the key repeat delay is controlled with the `KEY_OVERRIDE_REPEAT_DELAY` macro. Define this value in your `config.h` file to change it. It is 500ms by default.
## Difference to Combos
Note that key overrides are very different from [combos](https://docs.qmk.fm/#/feature_combo). Combos require that you press down several keys almost _at the same time_ and can work with any combination of non-modifier keys. Key overrides work like keyboard shortcuts (e.g. `ctrl` + `z`): They take combinations of _multiple_ modifiers and _one_ non-modifier key to then perform some custom action. Key overrides are implemented with much care to behave just like normal keyboard shortcuts would in regards to the order of pressed keys, timing, and interacton with other pressed keys. There are a number of optional settings that can be used to really fine-tune the behavior of each key override as well. Using key overrides also does not delay key input for regular key presses, which inherently happens in combos and may be undesirable.

73
docs/feature_led_matrix.md
View file

@ -52,7 +52,7 @@ Here is an example using 2 drivers.
Define these arrays listing all the LEDs in your `<keyboard>.c`:
```c
const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
const is31_led __flash g_is31_leds[DRIVER_LED_TOTAL] = {
/* Refer to IS31 manual for these locations
* driver
* | LED address
@ -63,7 +63,7 @@ const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
}
```
Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731-simple.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` ).
Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/led/issi/is31fl3731-simple.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` ).
---
@ -164,26 +164,26 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con
|Define |Description |
|-------------------------------------------------------|-----------------------------------------------|
|`#define DISABLE_LED_MATRIX_ALPHAS_MODS` |Disables `LED_MATRIX_ALPHAS_MODS` |
|`#define DISABLE_LED_MATRIX_BREATHING` |Disables `LED_MATRIX_BREATHING` |
|`#define DISABLE_LED_MATRIX_BAND` |Disables `LED_MATRIX_BAND` |
|`#define DISABLE_LED_MATRIX_BAND_PINWHEEL` |Disables `LED_MATRIX_BAND_PINWHEEL` |
|`#define DISABLE_LED_MATRIX_BAND_SPIRAL` |Disables `LED_MATRIX_BAND_SPIRAL` |
|`#define DISABLE_LED_MATRIX_CYCLE_LEFT_RIGHT` |Disables `LED_MATRIX_CYCLE_LEFT_RIGHT` |
|`#define DISABLE_LED_MATRIX_CYCLE_UP_DOWN` |Disables `LED_MATRIX_CYCLE_UP_DOWN` |
|`#define DISABLE_LED_MATRIX_CYCLE_OUT_IN` |Disables `LED_MATRIX_CYCLE_OUT_IN` |
|`#define DISABLE_LED_MATRIX_DUAL_BEACON` |Disables `LED_MATRIX_DUAL_BEACON` |
|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_SIMPLE` |Disables `LED_MATRIX_SOLID_REACTIVE_SIMPLE` |
|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_WIDE` |Disables `LED_MATRIX_SOLID_REACTIVE_WIDE` |
|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_MULTIWIDE` |Disables `LED_MATRIX_SOLID_REACTIVE_MULTIWIDE` |
|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_CROSS` |Disables `LED_MATRIX_SOLID_REACTIVE_CROSS` |
|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_MULTICROSS` |Disables `LED_MATRIX_SOLID_REACTIVE_MULTICROSS`|
|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_NEXUS` |Disables `LED_MATRIX_SOLID_REACTIVE_NEXUS` |
|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_MULTINEXUS` |Disables `LED_MATRIX_SOLID_REACTIVE_MULTINEXUS`|
|`#define DISABLE_LED_MATRIX_SOLID_SPLASH` |Disables `LED_MATRIX_SOLID_SPLASH` |
|`#define DISABLE_LED_MATRIX_SOLID_MULTISPLASH` |Disables `LED_MATRIX_SOLID_MULTISPLASH` |
|`#define DISABLE_LED_MATRIX_WAVE_LEFT_RIGHT` |Disables `LED_MATRIX_WAVE_LEFT_RIGHT` |
|`#define DISABLE_LED_MATRIX_WAVE_UP_DOWN` |Disables `LED_MATRIX_WAVE_UP_DOWN` |
|`#define ENABLE_LED_MATRIX_ALPHAS_MODS` |Enables `LED_MATRIX_ALPHAS_MODS` |
|`#define ENABLE_LED_MATRIX_BREATHING` |Enables `LED_MATRIX_BREATHING` |
|`#define ENABLE_LED_MATRIX_BAND` |Enables `LED_MATRIX_BAND` |
|`#define ENABLE_LED_MATRIX_BAND_PINWHEEL` |Enables `LED_MATRIX_BAND_PINWHEEL` |
|`#define ENABLE_LED_MATRIX_BAND_SPIRAL` |Enables `LED_MATRIX_BAND_SPIRAL` |
|`#define ENABLE_LED_MATRIX_CYCLE_LEFT_RIGHT` |Enables `LED_MATRIX_CYCLE_LEFT_RIGHT` |
|`#define ENABLE_LED_MATRIX_CYCLE_UP_DOWN` |Enables `LED_MATRIX_CYCLE_UP_DOWN` |
|`#define ENABLE_LED_MATRIX_CYCLE_OUT_IN` |Enables `LED_MATRIX_CYCLE_OUT_IN` |
|`#define ENABLE_LED_MATRIX_DUAL_BEACON` |Enables `LED_MATRIX_DUAL_BEACON` |
|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_SIMPLE` |Enables `LED_MATRIX_SOLID_REACTIVE_SIMPLE` |
|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_WIDE` |Enables `LED_MATRIX_SOLID_REACTIVE_WIDE` |
|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_MULTIWIDE` |Enables `LED_MATRIX_SOLID_REACTIVE_MULTIWIDE` |
|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_CROSS` |Enables `LED_MATRIX_SOLID_REACTIVE_CROSS` |
|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_MULTICROSS` |Enables `LED_MATRIX_SOLID_REACTIVE_MULTICROSS`|
|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_NEXUS` |Enables `LED_MATRIX_SOLID_REACTIVE_NEXUS` |
|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_MULTINEXUS` |Enables `LED_MATRIX_SOLID_REACTIVE_MULTINEXUS`|
|`#define ENABLE_LED_MATRIX_SOLID_SPLASH` |Enables `LED_MATRIX_SOLID_SPLASH` |
|`#define ENABLE_LED_MATRIX_SOLID_MULTISPLASH` |Enables `LED_MATRIX_SOLID_MULTISPLASH` |
|`#define ENABLE_LED_MATRIX_WAVE_LEFT_RIGHT` |Enables `LED_MATRIX_WAVE_LEFT_RIGHT` |
|`#define ENABLE_LED_MATRIX_WAVE_UP_DOWN` |Enables `LED_MATRIX_WAVE_UP_DOWN` |
## Custom LED Matrix Effects :id=custom-led-matrix-effects
@ -262,7 +262,7 @@ For inspiration and examples, check out the built-in effects under `quantum/led_
#define LED_MATRIX_FRAMEBUFFER_EFFECTS // enable framebuffer effects
#define LED_DISABLE_TIMEOUT 0 // number of milliseconds to wait until led automatically turns off
#define LED_DISABLE_AFTER_TIMEOUT 0 // OBSOLETE: number of ticks to wait until disabling effects
#define LED_DISABLE_WHEN_USB_SUSPENDED false // turn off effects when suspended
#define LED_DISABLE_WHEN_USB_SUSPENDED // turn off effects when suspended
#define LED_MATRIX_LED_PROCESS_LIMIT (DRIVER_LED_TOTAL + 4) / 5 // limits the number of LEDs to process in an animation per task run (increases keyboard responsiveness)
#define LED_MATRIX_LED_FLUSH_LIMIT 16 // limits in milliseconds how frequently an animation will update the LEDs. 16 (16ms) is equivalent to limiting to 60fps (increases keyboard responsiveness)
#define LED_MATRIX_MAXIMUM_BRIGHTNESS 255 // limits maximum brightness of LEDs
@ -350,30 +350,3 @@ void led_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) {
LED_MATRIX_INDICATOR_SET_VALUE(index, value);
}
```
## Suspended State :id=suspended-state
To use the suspend feature, make sure that `#define LED_DISABLE_WHEN_USB_SUSPENDED true` is added to the `config.h` file.
Additionally add this to your `<keyboard>.c`:
```c
void suspend_power_down_kb(void) {
led_matrix_set_suspend_state(true);
suspend_power_down_user();
}
void suspend_wakeup_init_kb(void) {
led_matrix_set_suspend_state(false);
suspend_wakeup_init_user();
}
```
or add this to your `keymap.c`:
```c
void suspend_power_down_user(void) {
led_matrix_set_suspend_state(true);
}
void suspend_wakeup_init_user(void) {
led_matrix_set_suspend_state(false);
}
```

20
docs/feature_oled_driver.md
View file

@ -21,13 +21,23 @@ Hardware configurations using Arm-based microcontrollers or different sizes of O
To enable the OLED feature, there are three steps. First, when compiling your keyboard, you'll need to add the following to your `rules.mk`:
```make
OLED_DRIVER_ENABLE = yes
OLED_ENABLE = yes
```
## OLED type
|OLED Driver |Supported Device |
|-------------------|---------------------------|
|SSD1306 (default) |For both SSD1306 and SH1106|
e.g.
```make
OLED_DRIVER = SSD1306
```
Then in your `keymap.c` file, implement the OLED task call. This example assumes your keymap has three layers named `_QWERTY`, `_FN` and `_ADJ`:
```c
#ifdef OLED_DRIVER_ENABLE
#ifdef OLED_ENABLE
void oled_task_user(void) {
// Host Keyboard Layer Status
oled_write_P(PSTR("Layer: "), false);
@ -114,7 +124,7 @@ static void fade_display(void) {
In split keyboards, it is very common to have two OLED displays that each render different content and are oriented or flipped differently. You can do this by switching which content to render by using the return value from `is_keyboard_master()` or `is_keyboard_left()` found in `split_util.h`, e.g:
```c
#ifdef OLED_DRIVER_ENABLE
#ifdef OLED_ENABLE
oled_rotation_t oled_init_user(oled_rotation_t rotation) {
if (!is_keyboard_master()) {
return OLED_ROTATION_180; // flips the display 180 degrees if offhand
@ -346,6 +356,10 @@ bool oled_scroll_left(void);
// Returns true if the screen was not scrolling or stops scrolling
bool oled_scroll_off(void);
// Inverts the display
// Returns true if the screen was or is inverted
bool oled_invert(bool invert);
// Returns the maximum number of characters that will fit on a line
uint8_t oled_max_chars(void);

38
docs/feature_ps2_mouse.md
View file

@ -50,7 +50,7 @@ In your keyboard config.h:
#endif
```
## Interrupt Version :id=interrupt-version
### Interrupt Version (AVR/ATMega32u4) :id=interrupt-version-avr
The following example uses D2 for clock and D5 for data. You can use any INT or PCINT pin for clock, and any pin for data.
@ -88,7 +88,31 @@ In your keyboard config.h:
#endif
```
## USART Version :id=usart-version
### Interrupt Version (ARM chibios) :id=interrupt-version-chibios
Pretty much any two pins can be used for the (software) interrupt variant on ARM cores. The example below uses A8 for clock, and A9 for data.
In rules.mk:
```
PS2_MOUSE_ENABLE = yes
PS2_USE_INT = yes
```
In your keyboard config.h:
```c
#define PS2_CLOCK A8
#define PS2_DATA A9
```
And in the chibios specifig halconf.h:
```c
#define PAL_USE_CALLBACKS TRUE
```
### USART Version :id=usart-version
To use USART on the ATMega32u4, you have to use PD5 for clock and PD2 for data. If one of those are unavailable, you need to use interrupt version.
@ -246,6 +270,16 @@ Fine control over the scrolling is supported with the following defines:
#define PS2_MOUSE_SCROLL_DIVISOR_V 2
```
### Invert Mouse buttons :id=invert-buttons
To invert the left & right buttons you can put:
```c
#define PS2_MOUSE_INVERT_BUTTONS
```
into config.h.
### Invert Mouse and Scroll Axes :id=invert-mouse-and-scroll-axes
To invert the X and Y axes you can put:

275
docs/feature_rgb_matrix.md
View file

@ -52,7 +52,7 @@ Here is an example using 2 drivers.
Define these arrays listing all the LEDs in your `<keyboard>.c`:
```c
const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
const is31_led __flash g_is31_leds[DRIVER_LED_TOTAL] = {
/* Refer to IS31 manual for these locations
* driver
* | R location
@ -64,7 +64,7 @@ const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
}
```
Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3`).
Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/led/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3`).
---
### IS31FL3733 :id=is31fl3733
@ -122,7 +122,7 @@ Currently only 4 drivers are supported, but it would be trivial to support all 8
Define these arrays listing all the LEDs in your `<keyboard>.c`:
```c
const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
const is31_led __flash g_is31_leds[DRIVER_LED_TOTAL] = {
/* Refer to IS31 manual for these locations
* driver
* | R location
@ -134,7 +134,7 @@ const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
}
```
Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3733.pdf) and the header file `drivers/issi/is31fl3733.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` for now).
Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3733.pdf) and the header file `drivers/led/issi/is31fl3733.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` for now).
---
### IS31FL3737 :id=is31fl3737
@ -145,9 +145,22 @@ There is basic support for addressable RGB matrix lighting with the I2C IS31FL37
RGB_MATRIX_ENABLE = yes
RGB_MATRIX_DRIVER = IS31FL3737
```
You can use between 1 and 2 IS31FL3737 IC's. Do not specify `DRIVER_ADDR_2` define for second IC if not present on your keyboard.
Configure the hardware via your `config.h`:
| Variable | Description | Default |
|----------|-------------|---------|
| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 |
| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 |
| `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | |
| `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | |
| `DRIVER_ADDR_1` | (Required) Address for the first RGB driver | |
| `DRIVER_ADDR_2` | (Optional) Address for the second RGB driver | |
Here is an example using 2 drivers.
```c
// This is a 7-bit address, that gets left-shifted and bit 0
// set to 0 for write, 1 for read (as per I2C protocol)
@ -159,19 +172,21 @@ Configure the hardware via your `config.h`:
// ADDR represents A3:A0 of the 7-bit address.
// The result is: 0b101(ADDR)
#define DRIVER_ADDR_1 0b1010000
#define DRIVER_ADDR_2 0b1010000 // this is here for compliancy reasons.
#define DRIVER_ADDR_2 0b1010001
#define DRIVER_COUNT 2
#define DRIVER_1_LED_TOTAL 64
#define DRIVER_LED_TOTAL DRIVER_1_LED_TOTAL
#define DRIVER_1_LED_TOTAL 30
#define DRIVER_2_LED_TOTAL 36
#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)
```
!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`.
Currently only a single drivers is supported, but it would be trivial to support all 4 combinations. For now define `DRIVER_ADDR_2` as `DRIVER_ADDR_1`
Currently only 2 drivers are supported, but it would be trivial to support all 4 combinations.
Define these arrays listing all the LEDs in your `<keyboard>.c`:
```c
const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
const is31_led __flash g_is31_leds[DRIVER_LED_TOTAL] = {
/* Refer to IS31 manual for these locations
* driver
* | R location
@ -183,7 +198,7 @@ const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
}
```
Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3737.pdf) and the header file `drivers/issi/is31fl3737.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0` right now).
Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3737.pdf) and the header file `drivers/led/issi/is31fl3737.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0`, `1` for now).
---
@ -227,6 +242,75 @@ Configure the hardware via your `config.h`:
#define DRIVER_LED_TOTAL 70
```
---
### AW20216 :id=aw20216
There is basic support for addressable RGB matrix lighting with the SPI AW20216 RGB controller. To enable it, add this to your `rules.mk`:
```makefile
RGB_MATRIX_ENABLE = yes
RGB_MATRIX_DRIVER = AW20216
```
You can use up to 2 AW20216 IC's. Do not specify `DRIVER_<N>_xxx` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`:
| Variable | Description | Default |
|----------|-------------|---------|
| `DRIVER_1_CS` | (Required) MCU pin connected to first RGB driver chip select line | B13 |
| `DRIVER_2_CS` | (Optional) MCU pin connected to second RGB driver chip select line | |
| `DRIVER_1_EN` | (Required) MCU pin connected to first RGB driver hardware enable line | C13 |
| `DRIVER_2_EN` | (Optional) MCU pin connected to second RGB driver hardware enable line | |
| `DRIVER_1_LED_TOTAL` | (Required) How many RGB lights are connected to first RGB driver | |
| `DRIVER_2_LED_TOTAL` | (Optional) How many RGB lights are connected to second RGB driver | |
| `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | |
| `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | |
| `AW_SCALING_MAX` | (Optional) LED current scaling value (0-255, higher values mean LED is brighter at full PWM) | 150 |
| `AW_GLOBAL_CURRENT_MAX` | (Optional) Driver global current limit (0-255, higher values means the driver may consume more power) | 150 |
| `AW_SPI_DIVISOR` | (Optional) Clock divisor for SPI communication (powers of 2, smaller numbers means faster communication, should not be less than 4) | 4 |
Here is an example using 2 drivers.
```c
#define DRIVER_1_CS B13
#define DRIVER_2_CS B14
// Hardware enable lines may be connected to the same pin
#define DRIVER_1_EN C13
#define DRIVER_2_EN C13
#define DRIVER_COUNT 2
#define DRIVER_1_LED_TOTAL 66
#define DRIVER_2_LED_TOTAL 32
#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)
```
!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`.
Define these arrays listing all the LEDs in your `<keyboard>.c`:
```c
const aw_led __flash g_aw_leds[DRIVER_LED_TOTAL] = {
/* Each AW20216 channel is controlled by a register at some offset between 0x00
* and 0xD7 inclusive.
* See drivers/awinic/aw20216.h for the mapping between register offsets and
* driver pin locations.
* driver
* | R location
* | | G location
* | | | B location
* | | | | */
{ 0, CS1_SW1, CS2_SW1, CS3_SW1 },
{ 0, CS4_SW1, CS5_SW1, CS6_SW1 },
{ 0, CS7_SW1, CS8_SW1, CS9_SW1 },
{ 0, CS10_SW1, CS11_SW1, CS12_SW1 },
{ 0, CS13_SW1, CS14_SW1, CS15_SW1 },
...
{ 1, CS1_SW1, CS2_SW1, CS3_SW1 },
{ 1, CS13_SW1, CS14_SW1, CS15_SW1 },
{ 1, CS16_SW1, CS17_SW1, CS18_SW1 },
{ 1, CS4_SW2, CS5_SW2, CS6_SW2 },
...
};
```
---
## Common Configuration :id=common-configuration
@ -364,46 +448,46 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con
|Define |Description |
|-------------------------------------------------------|-----------------------------------------------|
|`#define DISABLE_RGB_MATRIX_ALPHAS_MODS` |Disables `RGB_MATRIX_ALPHAS_MODS` |
|`#define DISABLE_RGB_MATRIX_GRADIENT_UP_DOWN` |Disables `RGB_MATRIX_GRADIENT_UP_DOWN` |
|`#define DISABLE_RGB_MATRIX_GRADIENT_LEFT_RIGHT` |Disables `MATRIX_GRADIENT_LEFT_RIGHT` |
|`#define DISABLE_RGB_MATRIX_BREATHING` |Disables `RGB_MATRIX_BREATHING` |
|`#define DISABLE_RGB_MATRIX_BAND_SAT` |Disables `RGB_MATRIX_BAND_SAT` |
|`#define DISABLE_RGB_MATRIX_BAND_VAL` |Disables `RGB_MATRIX_BAND_VAL` |
|`#define DISABLE_RGB_MATRIX_BAND_PINWHEEL_SAT` |Disables `RGB_MATRIX_BAND_PINWHEEL_SAT` |
|`#define DISABLE_RGB_MATRIX_BAND_PINWHEEL_VAL` |Disables `RGB_MATRIX_BAND_PINWHEEL_VAL` |
|`#define DISABLE_RGB_MATRIX_BAND_SPIRAL_SAT` |Disables `RGB_MATRIX_BAND_SPIRAL_SAT` |
|`#define DISABLE_RGB_MATRIX_BAND_SPIRAL_VAL` |Disables `RGB_MATRIX_BAND_SPIRAL_VAL` |
|`#define DISABLE_RGB_MATRIX_CYCLE_ALL` |Disables `RGB_MATRIX_CYCLE_ALL` |
|`#define DISABLE_RGB_MATRIX_CYCLE_LEFT_RIGHT` |Disables `RGB_MATRIX_CYCLE_LEFT_RIGHT` |
|`#define DISABLE_RGB_MATRIX_CYCLE_UP_DOWN` |Disables `RGB_MATRIX_CYCLE_UP_DOWN` |
|`#define DISABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON` |Disables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON` |
|`#define DISABLE_RGB_MATRIX_CYCLE_OUT_IN` |Disables `RGB_MATRIX_CYCLE_OUT_IN` |
|`#define DISABLE_RGB_MATRIX_CYCLE_OUT_IN_DUAL` |Disables `RGB_MATRIX_CYCLE_OUT_IN_DUAL` |
|`#define DISABLE_RGB_MATRIX_CYCLE_PINWHEEL` |Disables `RGB_MATRIX_CYCLE_PINWHEEL` |
|`#define DISABLE_RGB_MATRIX_CYCLE_SPIRAL` |Disables `RGB_MATRIX_CYCLE_SPIRAL` |
|`#define DISABLE_RGB_MATRIX_DUAL_BEACON` |Disables `RGB_MATRIX_DUAL_BEACON` |
|`#define DISABLE_RGB_MATRIX_RAINBOW_BEACON` |Disables `RGB_MATRIX_RAINBOW_BEACON` |
|`#define DISABLE_RGB_MATRIX_RAINBOW_PINWHEELS` |Disables `RGB_MATRIX_RAINBOW_PINWHEELS` |
|`#define DISABLE_RGB_MATRIX_RAINDROPS` |Disables `RGB_MATRIX_RAINDROPS` |
|`#define DISABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS` |Disables `RGB_MATRIX_JELLYBEAN_RAINDROPS` |
|`#define DISABLE_RGB_MATRIX_HUE_BREATHING` |Disables `RGB_MATRIX_HUE_BREATHING` |
|`#define DISABLE_RGB_MATRIX_HUE_PENDULUM` |Disables `RGB_MATRIX_HUE_PENDULUM` |
|`#define DISABLE_RGB_MATRIX_HUE_WAVE ` |Disables `RGB_MATRIX_HUE_WAVE ` |
|`#define DISABLE_RGB_MATRIX_TYPING_HEATMAP` |Disables `RGB_MATRIX_TYPING_HEATMAP` |
|`#define DISABLE_RGB_MATRIX_DIGITAL_RAIN` |Disables `RGB_MATRIX_DIGITAL_RAIN` |
|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_SIMPLE` |Disables `RGB_MATRIX_SOLID_REACTIVE_SIMPLE` |
|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE` |Disables `RGB_MATRIX_SOLID_REACTIVE` |
|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_WIDE` |Disables `RGB_MATRIX_SOLID_REACTIVE_WIDE` |
|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` |
|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_CROSS` |Disables `RGB_MATRIX_SOLID_REACTIVE_CROSS` |
|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTICROSS` |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTICROSS`|
|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_NEXUS` |Disables `RGB_MATRIX_SOLID_REACTIVE_NEXUS` |
|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS` |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS`|
|`#define DISABLE_RGB_MATRIX_SPLASH` |Disables `RGB_MATRIX_SPLASH` |
|`#define DISABLE_RGB_MATRIX_MULTISPLASH` |Disables `RGB_MATRIX_MULTISPLASH` |
|`#define DISABLE_RGB_MATRIX_SOLID_SPLASH` |Disables `RGB_MATRIX_SOLID_SPLASH` |
|`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH` |Disables `RGB_MATRIX_SOLID_MULTISPLASH` |
|`#define ENABLE_RGB_MATRIX_ALPHAS_MODS` |Enables `RGB_MATRIX_ALPHAS_MODS` |
|`#define ENABLE_RGB_MATRIX_GRADIENT_UP_DOWN` |Enables `RGB_MATRIX_GRADIENT_UP_DOWN` |
|`#define ENABLE_RGB_MATRIX_GRADIENT_LEFT_RIGHT` |Enables `MATRIX_GRADIENT_LEFT_RIGHT` |
|`#define ENABLE_RGB_MATRIX_BREATHING` |Enables `RGB_MATRIX_BREATHING` |
|`#define ENABLE_RGB_MATRIX_BAND_SAT` |Enables `RGB_MATRIX_BAND_SAT` |
|`#define ENABLE_RGB_MATRIX_BAND_VAL` |Enables `RGB_MATRIX_BAND_VAL` |
|`#define ENABLE_RGB_MATRIX_BAND_PINWHEEL_SAT` |Enables `RGB_MATRIX_BAND_PINWHEEL_SAT` |
|`#define ENABLE_RGB_MATRIX_BAND_PINWHEEL_VAL` |Enables `RGB_MATRIX_BAND_PINWHEEL_VAL` |
|`#define ENABLE_RGB_MATRIX_BAND_SPIRAL_SAT` |Enables `RGB_MATRIX_BAND_SPIRAL_SAT` |
|`#define ENABLE_RGB_MATRIX_BAND_SPIRAL_VAL` |Enables `RGB_MATRIX_BAND_SPIRAL_VAL` |
|`#define ENABLE_RGB_MATRIX_CYCLE_ALL` |Enables `RGB_MATRIX_CYCLE_ALL` |
|`#define ENABLE_RGB_MATRIX_CYCLE_LEFT_RIGHT` |Enables `RGB_MATRIX_CYCLE_LEFT_RIGHT` |
|`#define ENABLE_RGB_MATRIX_CYCLE_UP_DOWN` |Enables `RGB_MATRIX_CYCLE_UP_DOWN` |
|`#define ENABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON` |Enables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON` |
|`#define ENABLE_RGB_MATRIX_CYCLE_OUT_IN` |Enables `RGB_MATRIX_CYCLE_OUT_IN` |
|`#define ENABLE_RGB_MATRIX_CYCLE_OUT_IN_DUAL` |Enables `RGB_MATRIX_CYCLE_OUT_IN_DUAL` |
|`#define ENABLE_RGB_MATRIX_CYCLE_PINWHEEL` |Enables `RGB_MATRIX_CYCLE_PINWHEEL` |
|`#define ENABLE_RGB_MATRIX_CYCLE_SPIRAL` |Enables `RGB_MATRIX_CYCLE_SPIRAL` |
|`#define ENABLE_RGB_MATRIX_DUAL_BEACON` |Enables `RGB_MATRIX_DUAL_BEACON` |
|`#define ENABLE_RGB_MATRIX_RAINBOW_BEACON` |Enables `RGB_MATRIX_RAINBOW_BEACON` |
|`#define ENABLE_RGB_MATRIX_RAINBOW_PINWHEELS` |Enables `RGB_MATRIX_RAINBOW_PINWHEELS` |
|`#define ENABLE_RGB_MATRIX_RAINDROPS` |Enables `RGB_MATRIX_RAINDROPS` |
|`#define ENABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS` |Enables `RGB_MATRIX_JELLYBEAN_RAINDROPS` |
|`#define ENABLE_RGB_MATRIX_HUE_BREATHING` |Enables `RGB_MATRIX_HUE_BREATHING` |
|`#define ENABLE_RGB_MATRIX_HUE_PENDULUM` |Enables `RGB_MATRIX_HUE_PENDULUM` |
|`#define ENABLE_RGB_MATRIX_HUE_WAVE ` |Enables `RGB_MATRIX_HUE_WAVE ` |
|`#define ENABLE_RGB_MATRIX_TYPING_HEATMAP` |Enables `RGB_MATRIX_TYPING_HEATMAP` |
|`#define ENABLE_RGB_MATRIX_DIGITAL_RAIN` |Enables `RGB_MATRIX_DIGITAL_RAIN` |
|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_SIMPLE` |Enables `RGB_MATRIX_SOLID_REACTIVE_SIMPLE` |
|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE` |Enables `RGB_MATRIX_SOLID_REACTIVE` |
|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_WIDE` |Enables `RGB_MATRIX_SOLID_REACTIVE_WIDE` |
|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` |Enables `RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` |
|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_CROSS` |Enables `RGB_MATRIX_SOLID_REACTIVE_CROSS` |
|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_MULTICROSS` |Enables `RGB_MATRIX_SOLID_REACTIVE_MULTICROSS`|
|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_NEXUS` |Enables `RGB_MATRIX_SOLID_REACTIVE_NEXUS` |
|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS` |Enables `RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS`|
|`#define ENABLE_RGB_MATRIX_SPLASH` |Enables `RGB_MATRIX_SPLASH` |
|`#define ENABLE_RGB_MATRIX_MULTISPLASH` |Enables `RGB_MATRIX_MULTISPLASH` |
|`#define ENABLE_RGB_MATRIX_SOLID_SPLASH` |Enables `RGB_MATRIX_SOLID_SPLASH` |
|`#define ENABLE_RGB_MATRIX_SOLID_MULTISPLASH` |Enables `RGB_MATRIX_SOLID_MULTISPLASH` |
### RGB Matrix Effect Typing Heatmap :id=rgb-matrix-effect-typing-heatmap
@ -485,28 +569,29 @@ For inspiration and examples, check out the built-in effects under `quantum/rgb_
These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions.
|RGB |HSV |
|-------------------|-------------------|
|`RGB_WHITE` |`HSV_WHITE` |
|`RGB_RED` |`HSV_RED` |
|`RGB_CORAL` |`HSV_CORAL` |
|`RGB_ORANGE` |`HSV_ORANGE` |
|`RGB_GOLDENROD` |`HSV_GOLDENROD` |
|`RGB_GOLD` |`HSV_GOLD` |
|`RGB_YELLOW` |`HSV_YELLOW` |
|`RGB_CHARTREUSE` |`HSV_CHARTREUSE` |
|`RGB_GREEN` |`HSV_GREEN` |
|`RGB_SPRINGGREEN` |`HSV_SPRINGGREEN` |
|`RGB_TURQUOISE` |`HSV_TURQUOISE` |
|`RGB_TEAL` |`HSV_TEAL` |
|`RGB_CYAN` |`HSV_CYAN` |
|`RGB_AZURE` |`HSV_AZURE` |
|`RGB_BLUE` |`HSV_BLUE` |
|`RGB_PURPLE` |`HSV_PURPLE` |
|`RGB_MAGENTA` |`HSV_MAGENTA` |
|`RGB_PINK` |`HSV_PINK` |
|RGB |HSV |
|---------------------|---------------------|
|`RGB_AZURE` |`HSV_AZURE` |
|`RGB_BLACK`/`RGB_OFF`|`HSV_BLACK`/`HSV_OFF`|
|`RGB_BLUE` |`HSV_BLUE` |
|`RGB_CHARTREUSE` |`HSV_CHARTREUSE` |
|`RGB_CORAL` |`HSV_CORAL` |
|`RGB_CYAN` |`HSV_CYAN` |
|`RGB_GOLD` |`HSV_GOLD` |
|`RGB_GOLDENROD` |`HSV_GOLDENROD` |
|`RGB_GREEN` |`HSV_GREEN` |
|`RGB_MAGENTA` |`HSV_MAGENTA` |
|`RGB_ORANGE` |`HSV_ORANGE` |
|`RGB_PINK` |`HSV_PINK` |
|`RGB_PURPLE` |`HSV_PURPLE` |
|`RGB_RED` |`HSV_RED` |
|`RGB_SPRINGGREEN` |`HSV_SPRINGGREEN` |
|`RGB_TEAL` |`HSV_TEAL` |
|`RGB_TURQUOISE` |`HSV_TURQUOISE` |
|`RGB_WHITE` |`HSV_WHITE` |
|`RGB_YELLOW` |`HSV_YELLOW` |
These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list!
These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/color.h). Feel free to add to this list!
## Additional `config.h` Options :id=additional-configh-options
@ -657,29 +742,41 @@ void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) {
}
```
### Suspended state :id=suspended-state
To use the suspend feature, make sure that `#define RGB_DISABLE_WHEN_USB_SUSPENDED true` is added to the `config.h` file.
#### Examples :id=indicator-examples
Additionally add this to your `<keyboard>.c`:
This example sets the modifiers to be a specific color based on the layer state. You can use a switch case here, instead, if you would like. This uses HSV and then converts to RGB, because this allows the brightness to be limited (important when using the WS2812 driver).
```c
void suspend_power_down_kb(void) {
rgb_matrix_set_suspend_state(true);
suspend_power_down_user();
}
void suspend_wakeup_init_kb(void) {
rgb_matrix_set_suspend_state(false);
suspend_wakeup_init_user();
void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) {
HSV hsv = {0, 255, 255};
if (layer_state_is(layer_state, 2)) {
hsv = {130, 255, 255};
} else {
hsv = {30, 255, 255};
}
if (hsv.v > rgb_matrix_get_val()) {
hsv.v = rgb_matrix_get_val();
}
RGB rgb = hsv_to_rgb(hsv);
for (uint8_t i = led_min; i <= led_max; i++) {
if (HAS_FLAGS(g_led_config.flags[i], 0x01)) { // 0x01 == LED_FLAG_MODIFIER
rgb_matrix_set_color(i, rgb.r, rgb.g, rgb.b);
}
}
}
```
or add this to your `keymap.c`:
If you want to indicate a Host LED status (caps lock, num lock, etc), you can use something like this to light up the caps lock key:
```c
void suspend_power_down_user(void) {
rgb_matrix_set_suspend_state(true);
}
void suspend_wakeup_init_user(void) {
rgb_matrix_set_suspend_state(false);
void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) {
if (host_keyboard_led_state().caps_lock) {
RGB_MATRIX_INDICATOR_SET_COLOR(5, 255, 255, 255); // assuming caps lock is at led #5
} else {
RGB_MATRIX_INDICATOR_SET_COLOR(5, 0, 0, 0);
}
}
```

51
docs/feature_rgblight.md
View file

@ -119,7 +119,7 @@ if `RGBLIGHT_EFFECT_xxxx` or `RGBLIGHT_ANIMATIONS` is defined, you also have a n
Check out [this video](https://youtube.com/watch?v=VKrpPAHlisY) for a demonstration.
Note: For versions older than 0.6.117, The mode numbers were written directly. In `quantum/rgblight.h` there is a contrast table between the old mode number and the current symbol.
Note: For versions older than 0.6.117, The mode numbers were written directly. In `quantum/rgblight/rgblight.h` there is a contrast table between the old mode number and the current symbol.
### Effect and Animation Toggles
@ -326,9 +326,13 @@ would turn the layer 0 (or 1) on and off again three times when `DEBUG` is press
Normally lighting layers are not shown when RGB Lighting is disabled (e.g. with `RGB_TOG` keycode). If you would like lighting layers to work even when the RGB Lighting is otherwise off, add `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF` to your `config.h`.
### Retain brightness
Usually lighting layers apply their configured brightness once activated. If you would like lighting layers to retain the currently used brightness (as returned by `rgblight_get_val()`), add `#define RGBLIGHT_LAYERS_RETAIN_VAL` to your `config.h`.
## Functions
If you need to change your RGB lighting in code, for example in a macro to change the color whenever you switch layers, QMK provides a set of functions to assist you. See [`rgblight.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight.h) for the full list, but the most commonly used functions include:
If you need to change your RGB lighting in code, for example in a macro to change the color whenever you switch layers, QMK provides a set of functions to assist you. See [`rgblight.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight/rgblight.h) for the full list, but the most commonly used functions include:
### Utility Functions
|Function |Description |
@ -449,26 +453,27 @@ rgblight_sethsv_at(HSV_GREEN, 2); // led 2
These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions.
|RGB |HSV |
|-------------------|-------------------|
|`RGB_WHITE` |`HSV_WHITE` |
|`RGB_RED` |`HSV_RED` |
|`RGB_CORAL` |`HSV_CORAL` |
|`RGB_ORANGE` |`HSV_ORANGE` |
|`RGB_GOLDENROD` |`HSV_GOLDENROD` |
|`RGB_GOLD` |`HSV_GOLD` |
|`RGB_YELLOW` |`HSV_YELLOW` |
|`RGB_CHARTREUSE` |`HSV_CHARTREUSE` |
|`RGB_GREEN` |`HSV_GREEN` |
|`RGB_SPRINGGREEN` |`HSV_SPRINGGREEN` |
|`RGB_TURQUOISE` |`HSV_TURQUOISE` |
|`RGB_TEAL` |`HSV_TEAL` |
|`RGB_CYAN` |`HSV_CYAN` |
|`RGB_AZURE` |`HSV_AZURE` |
|`RGB_BLUE` |`HSV_BLUE` |
|`RGB_PURPLE` |`HSV_PURPLE` |
|`RGB_MAGENTA` |`HSV_MAGENTA` |
|`RGB_PINK` |`HSV_PINK` |
|RGB |HSV |
|---------------------|---------------------|
|`RGB_AZURE` |`HSV_AZURE` |
|`RGB_BLACK`/`RGB_OFF`|`HSV_BLACK`/`HSV_OFF`|
|`RGB_BLUE` |`HSV_BLUE` |
|`RGB_CHARTREUSE` |`HSV_CHARTREUSE` |
|`RGB_CORAL` |`HSV_CORAL` |
|`RGB_CYAN` |`HSV_CYAN` |
|`RGB_GOLD` |`HSV_GOLD` |
|`RGB_GOLDENROD` |`HSV_GOLDENROD` |
|`RGB_GREEN` |`HSV_GREEN` |
|`RGB_MAGENTA` |`HSV_MAGENTA` |
|`RGB_ORANGE` |`HSV_ORANGE` |
|`RGB_PINK` |`HSV_PINK` |
|`RGB_PURPLE` |`HSV_PURPLE` |
|`RGB_RED` |`HSV_RED` |
|`RGB_SPRINGGREEN` |`HSV_SPRINGGREEN` |
|`RGB_TEAL` |`HSV_TEAL` |
|`RGB_TURQUOISE` |`HSV_TURQUOISE` |
|`RGB_WHITE` |`HSV_WHITE` |
|`RGB_YELLOW` |`HSV_YELLOW` |
```c
rgblight_setrgb(RGB_ORANGE);
@ -477,7 +482,7 @@ rgblight_setrgb_at(RGB_GOLD, 3);
rgblight_sethsv_range(HSV_WHITE, 0, 6);
```
These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list!
These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/color.h). Feel free to add to this list!
## Changing the order of the LEDs

150
docs/feature_split_keyboard.md
View file

@ -8,8 +8,7 @@ QMK Firmware has a generic implementation that is usable by any board, as well a
For this, we will mostly be talking about the generic implementation used by the Let's Split and other keyboards.
!> ARM is not yet fully supported for Split Keyboards and has many limitations. Progress is being made, but we have not yet reached 100% feature parity.
!> ARM split supports most QMK subsystems when using the 'serial' and 'serial_usart' drivers. I2C slave is currently unsupported.
## Compatibility Overview
@ -90,7 +89,13 @@ You can configure the firmware to read a pin on the controller to determine hand
#define SPLIT_HAND_PIN B7
```
This will read the specified pin. If it's high, then the controller assumes it is the left hand, and if it's low, it's assumed to be the right side.
This will read the specified pin. By default, if it's high, then the controller assumes it is the left hand, and if it's low, it's assumed to be the right side.
This behaviour can be flipped by adding this to you `config.h` file:
```c
#define SPLIT_HAND_PIN_LOW_IS_LEFT
```
#### Handedness by Matrix Pin
@ -169,7 +174,7 @@ Because not every split keyboard is identical, there are a number of additional
#define USE_I2C
```
This enables I<sup>2</sup>C support for split keyboards. This isn't strictly for communication, but can be used for OLED or other I<sup>2</sup>C-based devices.
This configures the use of I<sup>2</sup>C support for split keyboard transport (AVR only).
```c
#define SOFT_SERIAL_PIN D0
@ -193,20 +198,143 @@ If you're having issues with serial communication, you can change this value, as
* **`5`**: about 20kbps
```c
#define SPLIT_MODS_ENABLE
#define FORCED_SYNC_THROTTLE_MS 100
```
This enables transmitting modifier state (normal, weak and oneshot) to the non
primary side of the split keyboard. This adds a few bytes of data to the split
communication protocol and may impact the matrix scan speed when enabled.
The purpose of this feature is to support cosmetic use of modifer state (e.g.
displaying status on an OLED screen).
This sets the maximum number of milliseconds before forcing a synchronization of data from master to slave. Under normal circumstances this sync occurs whenever the data _changes_, for safety a data transfer occurs after this number of milliseconds if no change has been detected since the last sync.
```c
#define SPLIT_MAX_CONNECTION_ERRORS 10
```
This sets the maximum number of failed communication attempts (one per scan cycle) from the master part before it assumes that no slave part is connected. This makes it possible to use a master part without the slave part connected.
Set to 0 to disable the disconnection check altogether.
```c
#define SPLIT_CONNECTION_CHECK_TIMEOUT 500
```
How long (in milliseconds) the master part should block all connection attempts to the slave after the communication has been flagged as disconnected (see `SPLIT_MAX_CONNECTION_ERRORS` above).
One communication attempt will be allowed everytime this amount of time has passed since the last attempt. If that attempt succeeds, the communication is seen as working again.
Set to 0 to disable this throttling of communications while disconnected. This can save you a couple of bytes of firmware size.
```c
#define SPLIT_TRANSPORT_MIRROR
```
This mirrors the master side matrix to the slave side for features that react or require knowledge of master side key presses on the slave side. This adds a few bytes of data to the split communication protocol and may impact the matrix scan speed when enabled. The purpose of this feature is to support cosmetic use of key events (e.g. RGB reacting to Keypresses).
This mirrors the master side matrix to the slave side for features that react or require knowledge of master side key presses on the slave side. The purpose of this feature is to support cosmetic use of key events (e.g. RGB reacting to keypresses). This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled.
```c
#define SPLIT_LAYER_STATE_ENABLE
```
This enables syncing of the layer state between both halves of the split keyboard. The main purpose of this feature is to enable support for use of things like OLED display of the currently active layer. This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled.
```c
#define SPLIT_LED_STATE_ENABLE
```
This enables syncing of the Host LED status (caps lock, num lock, etc) between both halves of the split keyboard. The main purpose of this feature is to enable support for use of things like OLED display of the Host LED status. This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled.
```c
#define SPLIT_MODS_ENABLE
```
This enables transmitting modifier state (normal, weak and oneshot) to the non primary side of the split keyboard. The purpose of this feature is to support cosmetic use of modifer state (e.g. displaying status on an OLED screen). This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled.
```c
#define SPLIT_WPM_ENABLE
```
This enables transmitting the current WPM to the slave side of the split keyboard. The purpose of this feature is to support cosmetic use of WPM (e.g. displaying the current value on an OLED screen). This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled.
```c
#define SPLIT_OLED_ENABLE
```
This enables transmitting the current OLED on/off status to the slave side of the split keyboard. The purpose of this feature is to support state (on/off state only) syncing. This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled.
```c
#define SPLIT_ST7565_ENABLE
```
This enables transmitting the current ST7565 on/off status to the slave side of the split keyboard. The purpose of this feature is to support state (on/off state only) syncing. This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled.
### Custom data sync between sides :id=custom-data-sync
QMK's split transport allows for arbitrary data transactions at both the keyboard and user levels. This is modelled on a remote procedure call, with the master invoking a function on the slave side, with the ability to send data from master to slave, process it slave side, and send data back from slave to master.
To leverage this, a keyboard or user/keymap can define a comma-separated list of _transaction IDs_:
```c
// for keyboard-level data sync:
#define SPLIT_TRANSACTION_IDS_KB KEYBOARD_SYNC_A, KEYBOARD_SYNC_B
// or, for user:
#define SPLIT_TRANSACTION_IDS_USER USER_SYNC_A, USER_SYNC_B, USER_SYNC_C
```
These _transaction IDs_ then need a slave-side handler function to be registered with the split transport, for example:
```c
typedef struct _master_to_slave_t {
int m2s_data;
} master_to_slave_t;
typedef struct _slave_to_master_t {
int s2m_data;
} slave_to_master_t;
void user_sync_a_slave_handler(uint8_t in_buflen, const void* in_data, uint8_t out_buflen, void* out_data) {
const master_to_slave_t *m2s = (const master_to_slave_t*)in_data;
slave_to_master_t *s2m = (slave_to_master_t*)out_data;
s2m->s2m_data = m2s->m2s_data + 5; // whatever comes in, add 5 so it can be sent back
}
void keyboard_post_init_user(void) {
transaction_register_rpc(USER_SYNC_A, user_sync_a_slave_handler);
}
```
The master side can then invoke the slave-side handler - for normal keyboard functionality to be minimally affected, any keyboard- or user-level code attempting to sync data should be throttled:
```c
void housekeeping_task_user(void) {
if (is_keyboard_master()) {
// Interact with slave every 500ms
static uint32_t last_sync = 0;
if (timer_elapsed32(last_sync) > 500) {
master_to_slave_t m2s = {6};
slave_to_master_t s2m = {0};
if(transaction_rpc_exec(USER_SYNC_A, sizeof(m2s), &m2s, sizeof(s2m), &s2m)) {
last_sync = timer_read32();
dprintf("Slave value: %d\n", s2m.s2m_data); // this will now be 11, as the slave adds 5
} else {
dprint("Slave sync failed!\n");
}
}
}
}
```
!> It is recommended that any data sync between halves happens during the master side's _housekeeping task_. This ensures timely retries should failures occur.
If only one-way data transfer is needed, helper methods are provided:
```c
bool transaction_rpc_exec(int8_t transaction_id, uint8_t initiator2target_buffer_size, const void *initiator2target_buffer, uint8_t target2initiator_buffer_size, void *target2initiator_buffer);
bool transaction_rpc_send(int8_t transaction_id, uint8_t initiator2target_buffer_size, const void *initiator2target_buffer);
bool transaction_rpc_recv(int8_t transaction_id, uint8_t target2initiator_buffer_size, void *target2initiator_buffer);
```
By default, the inbound and outbound data is limited to a maximum of 32 bytes each. The sizes can be altered if required:
```c
// Master to slave:
#define RPC_M2S_BUFFER_SIZE 48
// Slave to master:
#define RPC_S2M_BUFFER_SIZE 48
```
### Hardware Configuration Options

274
docs/feature_st7565.md Normal file
View file

@ -0,0 +1,274 @@
# ST7565 LCD Driver
## Supported Hardware
LCD modules using ST7565 driver IC, communicating over SPI.
|Module |IC |Size |Notes |
|------------------------------|-------|------|----------------------------------------------------------|
|Newhaven Display NHD-C12832A1Z|ST7565R|128x32|Used by Ergodox Infinity; primary consumer of this feature|
|Zolentech ZLE12864B |ST7565P|128x64|Requires contrast adjustment |
## Usage
To enable the feature, there are three steps. First, when compiling your keyboard, you'll need to add the following to your `rules.mk`:
```make
ST7565_ENABLE = yes
```
Then in your `keymap.c` file, implement the ST7565 task call. This example assumes your keymap has three layers named `_QWERTY`, `_FN` and `_ADJ`:
```c
#ifdef ST7565_ENABLE
void st7565_task_user(void) {
// Host Keyboard Layer Status
st7565_write_P(PSTR("Layer: "), false);
switch (get_highest_layer(layer_state)) {
case _QWERTY:
st7565_write_P(PSTR("Default\n"), false);
break;
case _FN:
st7565_write_P(PSTR("FN\n"), false);
break;
case _ADJ:
st7565_write_P(PSTR("ADJ\n"), false);
break;
default:
// Or use the write_ln shortcut over adding '\n' to the end of your string
st7565_write_ln_P(PSTR("Undefined"), false);
}
// Host Keyboard LED Status
led_t led_state = host_keyboard_led_state();
st7565_write_P(led_state.num_lock ? PSTR("NUM ") : PSTR(" "), false);
st7565_write_P(led_state.caps_lock ? PSTR("CAP ") : PSTR(" "), false);
st7565_write_P(led_state.scroll_lock ? PSTR("SCR ") : PSTR(" "), false);
}
#endif
```
## Logo Example
In the default font, certain ranges of characters are reserved for a QMK logo. To render this logo to the screen, use the following code example:
```c
static void render_logo(void) {
static const char PROGMEM qmk_logo[] = {
0x80, 0x81, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89, 0x8A, 0x8B, 0x8C, 0x8D, 0x8E, 0x8F, 0x90, 0x91, 0x92, 0x93, 0x94,
0xA0, 0xA1, 0xA2, 0xA3, 0xA4, 0xA5, 0xA6, 0xA7, 0xA8, 0xA9, 0xAA, 0xAB, 0xAC, 0xAD, 0xAE, 0xAF, 0xB0, 0xB1, 0xB2, 0xB3, 0xB4,
0xC0, 0xC1, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, 0xC8, 0xC9, 0xCA, 0xCB, 0xCC, 0xCD, 0xCE, 0xCF, 0xD0, 0xD1, 0xD2, 0xD3, 0xD4, 0x00
};
st7565_write_P(qmk_logo, false);
}
```
## Buffer Read Example
For some purposes, you may need to read the current state of the display buffer. The `st7565_read_raw` function can be used to safely read bytes from the buffer.
In this example, calling `fade_display` in the `st7565_task_user` function will slowly fade away whatever is on the screen by turning random pixels off over time.
```c
//Setup some mask which can be or'd with bytes to turn off pixels
const uint8_t single_bit_masks[8] = {127, 191, 223, 239, 247, 251, 253, 254};
static void fade_display(void) {
//Define the reader structure
display_buffer_reader_t reader;
uint8_t buff_char;
if (random() % 30 == 0) {
srand(timer_read());
// Fetch a pointer for the buffer byte at index 0. The return structure
// will have the pointer and the number of bytes remaining from this
// index position if we want to perform a sequential read by
// incrementing the buffer pointer
reader = st7565_read_raw(0);
//Loop over the remaining buffer and erase pixels as we go
for (uint16_t i = 0; i < reader.remaining_element_count; i++) {
//Get the actual byte in the buffer by dereferencing the pointer
buff_char = *reader.current_element;
if (buff_char != 0) {
st7565_write_raw_byte(buff_char & single_bit_masks[rand() % 8], i);
}
//increment the pointer to fetch a new byte during the next loop
reader.current_element++;
}
}
}
```
## Other Examples
In split keyboards, it is very common to have two displays that each render different content and are oriented or flipped differently. You can do this by switching which content to render by using the return value from `is_keyboard_master()` or `is_keyboard_left()` found in `split_util.h`, e.g:
```c
#ifdef ST7565_ENABLE
display_rotation_t st7565_init_user(display_rotation_t rotation) {
if (!is_keyboard_master()) {
return DISPLAY_ROTATION_180; // flips the display 180 degrees if offhand
}
return rotation;
}
void st7565_task_user(void) {
if (is_keyboard_master()) {
render_status(); // Renders the current keyboard state (layer, lock, caps, scroll, etc)
} else {
render_logo(); // Renders a static logo
}
}
#endif
```
## Basic Configuration
|Define |Default |Description |
|------------------------|--------------|-----------------------------------------------------------------------------------------------------|
|`ST7565_A0_PIN` |*Not defined* |(Required) The GPIO connected to the display's A0 (data/command) pin |
|`ST7565_RST_PIN` |*Not defined* |(Required) The GPIO connected to the display's reset pin |
|`ST7565_SS_PIN` |*Not defined* |(Required) The GPIO connected to the display's slave select pin |
|`ST7565_SPI_CLK_DIVISOR`|`4` |The SPI clock divisor to use |
|`ST7565_FONT_H` |`"glcdfont.c"`|The font code file to use for custom fonts |
|`ST7565_FONT_START` |`0` |The starting character index for custom fonts |
|`ST7565_FONT_END` |`223` |The ending character index for custom fonts |
|`ST7565_FONT_WIDTH` |`6` |The font width |
|`ST7565_FONT_HEIGHT` |`8` |The font height (untested) |
|`ST7565_TIMEOUT` |`60000` |Turns off the screen after 60000ms of keyboard inactivity. Helps reduce burn-in. Set to 0 to disable.|
|`ST7565_COLUMN_OFFSET` |`0` |Shift output to the right this many pixels. |
|`ST7565_CONTRAST` |`32` |The default contrast level of the display, from 0 to 255. |
|`ST7565_UPDATE_INTERVAL`|`0` |Set the time interval for updating the display in ms. This will improve the matrix scan rate. |
## Custom sized displays
The default display size for this feature is 128x32 and all necessary defines are precalculated with that in mind.
|Define |Default |Description |
|-----------------------|----------|-----------------------------------------------------------------------------------------------------------|
|`ST7565_DISPLAY_WIDTH` |`128` |The width of the display. |
|`ST7565_DISPLAY_HEIGHT`|`32` |The height of the display. |
|`ST7565_MATRIX_SIZE` |`512` |The local buffer size to allocate.<br>`(ST7565_DISPLAY_HEIGHT / 8 * ST7565_DISPLAY_WIDTH)`. |
|`ST7565_BLOCK_TYPE` |`uint16_t`|The unsigned integer type to use for dirty rendering. |
|`ST7565_BLOCK_COUNT` |`16` |The number of blocks the display is divided into for dirty rendering.<br>`(sizeof(ST7565_BLOCK_TYPE) * 8)`.|
|`ST7565_BLOCK_SIZE` |`32` |The size of each block for dirty rendering<br>`(ST7565_MATRIX_SIZE / ST7565_BLOCK_COUNT)`. |
## API
```c
// Rotation enum values are flags
typedef enum {
DISPLAY_ROTATION_0,
DISPLAY_ROTATION_180
} display_rotation_t;
// Initialize the display, rotating the rendered output based on the define passed in.
// Returns true if the was initialized successfully
bool st7565_init(display_rotation_t rotation);
// Called at the start of st7565_init, weak function overridable by the user
// rotation - the value passed into st7565_init
// Return new display_rotation_t if you want to override default rotation
display_rotation_t st7565_init_user(display_rotation_t rotation);
// Clears the display buffer, resets cursor position to 0, and sets the buffer to dirty for rendering
void st7565_clear(void);
// Renders the dirty chunks of the buffer to display
void st7565_render(void);
// Moves cursor to character position indicated by column and line, wraps if out of bounds
// Max column denoted by 'st7565_max_chars()' and max lines by 'st7565_max_lines()' functions
void st7565_set_cursor(uint8_t col, uint8_t line);
// Advances the cursor to the next page, writing ' ' if true
// Wraps to the begining when out of bounds
void st7565_advance_page(bool clearPageRemainder);
// Moves the cursor forward 1 character length
// Advance page if there is not enough room for the next character
// Wraps to the begining when out of bounds
void st7565_advance_char(void);
// Writes a single character to the buffer at current cursor position
// Advances the cursor while writing, inverts the pixels if true
// Main handler that writes character data to the display buffer
void st7565_write_char(const char data, bool invert);
// Writes a string to the buffer at current cursor position
// Advances the cursor while writing, inverts the pixels if true
void st7565_write(const char *data, bool invert);
// Writes a string to the buffer at current cursor position
// Advances the cursor while writing, inverts the pixels if true
// Advances the cursor to the next page, wiring ' ' to the remainder of the current page
void st7565_write_ln(const char *data, bool invert);
// Pans the buffer to the right (or left by passing true) by moving contents of the buffer
// Useful for moving the screen in preparation for new drawing
void st7565_pan(bool left);
// Returns a pointer to the requested start index in the buffer plus remaining
// buffer length as struct
display_buffer_reader_t st7565_read_raw(uint16_t start_index);
// Writes a string to the buffer at current cursor position
void st7565_write_raw(const char *data, uint16_t size);
// Writes a single byte into the buffer at the specified index
void st7565_write_raw_byte(const char data, uint16_t index);
// Sets a specific pixel on or off
// Coordinates start at top-left and go right and down for positive x and y
void st7565_write_pixel(uint8_t x, uint8_t y, bool on);
// Writes a PROGMEM string to the buffer at current cursor position
// Advances the cursor while writing, inverts the pixels if true
// Remapped to call 'void st7565_write(const char *data, bool invert);' on ARM
void st7565_write_P(const char *data, bool invert);
// Writes a PROGMEM string to the buffer at current cursor position
// Advances the cursor while writing, inverts the pixels if true
// Advances the cursor to the next page, wiring ' ' to the remainder of the current page
// Remapped to call 'void st7565_write_ln(const char *data, bool invert);' on ARM
void st7565_write_ln_P(const char *data, bool invert);
// Writes a PROGMEM string to the buffer at current cursor position
void st7565_write_raw_P(const char *data, uint16_t size);
// Can be used to manually turn on the screen if it is off
// Returns true if the screen was on or turns on
bool st7565_on(void);
// Called when st7565_on() turns on the screen, weak function overridable by the user
// Not called if the screen is already on
void st7565_on_user(void);
// Can be used to manually turn off the screen if it is on
// Returns true if the screen was off or turns off
bool st7565_off(void);
// Called when st7565_off() turns off the screen, weak function overridable by the user
// Not called if the screen is already off
void st7565_off_user(void);
// Returns true if the screen is currently on, false if it is
// not
bool st7565_is_on(void);
// Basically it's st7565_render, but with timeout management and st7565_task_user calling!
void st7565_task(void);
// Called at the start of st7565_task, weak function overridable by the user
void st7565_task_user(void);
// Inverts the display
// Returns true if the screen was or is inverted
bool st7565_invert(bool invert);
// Returns the maximum number of characters that will fit on a line
uint8_t st7565_max_chars(void);
// Returns the maximum number of lines that will fit on the display
uint8_t st7565_max_lines(void);
```

15
docs/feature_stenography.md
View file

@ -128,3 +128,18 @@ As defined in `keymap_steno.h`.
|`STN_RES1`||(GeminiPR only)|
|`STN_RES2`||(GeminiPR only)|
|`STN_PWR`||(GeminiPR only)|
If you do not want to hit two keys with one finger combined keycodes can be used. These are also defined in `keymap_steno.h`, and causes both keys to be reported as pressed or released. To use these keycodes define `STENO_COMBINEDMAP` in your `config.h` file
|Combined key | Key1 | Key 2 |
|---------------|--------|----------|
|STN_S3 | STN_S1 | STN_S2 |
|STN_TKL | STN_TL | STN_KL |
|STN_PWL | STN_PL | STN_WL |
|STN_HRL | STN_HL | STN_RL |
|STN_FRR | STN_FR | STN_RR |
|STN_PBR | STN_PR | STN_BR |
|STN_LGR | STN_LR | STN_GR |
|STN_TSR | STN_TR | STN_SR |
|STN_DZR | STN_DR | STN_ZR |
|STN_AO | STN_A | STN_O |
|STN_EU | STN_E | STN_U |

2
docs/feature_tap_dance.md
View file

@ -50,7 +50,7 @@ The main entry point is `process_tap_dance()`, called from `process_record_quant
This means that you have `TAPPING_TERM` time to tap the key again; you do not have to input all the taps within a single `TAPPING_TERM` timeframe. This allows for longer tap counts, with minimal impact on responsiveness.
Our next stop is `matrix_scan_tap_dance()`. This handles the timeout of tap-dance keys.
Our next stop is `tap_dance_task()`. This handles the timeout of tap-dance keys.
For the sake of flexibility, tap-dance actions can be either a pair of keycodes, or a user function. The latter allows one to handle higher tap counts, or do extra things, like blink the LEDs, fiddle with the backlighting, and so on. This is accomplished by using an union, and some clever macros.

50
docs/flashing.md
View file

@ -48,7 +48,7 @@ QMK maintains [a fork of the LUFA DFU bootloader](https://github.com/qmk/lufa/tr
//#define QMK_LED E6
//#define QMK_SPEAKER C6
```
Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md#bootmagic-lite), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader.
Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader.
The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string.
@ -171,6 +171,52 @@ Flashing sequence:
3. Flash a .hex file
4. Reset the device into application mode (may be done automatically)
### QMK HID
QMK maintains [a fork of the LUFA HID bootloader](https://github.com/qmk/lufa/tree/master/Bootloaders/HID), which uses a USB HID Endpoint for flashing in the way that the PJRC's Teensy Loader flasher and HalfKay bootloader work. Additionally, it performs a simple matrix scan for exiting the bootloader and returning to the application, as well as flashing an LED/making a ticking noise with a speaker when things are happening.
To ensure compatibility with the QMK HID bootloader, make sure this block is present in your `rules.mk`:
```make
# Bootloader selection
BOOTLOADER = qmk-hid
```
To enable the additional features, add the following defines to your `config.h`:
```c
#define QMK_ESC_OUTPUT F1 // COL pin if COL2ROW
#define QMK_ESC_INPUT D5 // ROW pin if COL2ROW
// Optional:
//#define QMK_LED E6
//#define QMK_SPEAKER C6
```
Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader.
The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string.
To generate this bootloader, use the `bootloader` target, eg. `make planck/rev4:default:bootloader`. To generate a production-ready .hex file (combining QMK and the bootloader), use the `production` target, eg. `make planck/rev4:default:production`.
Compatible flashers:
* TBD
* Currently, you need to either use the [Python script](https://github.com/qmk/lufa/tree/master/Bootloaders/HID/HostLoaderApp_python), or compile [`hid_bootloader_cli`](https://github.com/qmk/lufa/tree/master/Bootloaders/HID/HostLoaderApp), from the LUFA repo. Homebrew may (will) have support for this directly (via `brew install qmk/qmk/hid_bootloader_cli`).
Flashing sequence:
1. Enter the bootloader using any of the following methods:
* Press the `RESET` keycode
* Press the `RESET` button on the PCB if available
* short RST to GND quickly
2. Wait for the OS to detect the device
3. Flash a .hex file
4. Reset the device into application mode (may be done automatically)
### `make` Targets
* `:qmk-hid`: Checks every 5 seconds until a DFU device is available, and then flashes the firmware.
## STM32/APM32 DFU
All STM32 and APM32 MCUs, except for F103 (see the [STM32duino section](#stm32duino)) come preloaded with a factory bootloader that cannot be modified nor deleted.
@ -252,7 +298,7 @@ Flashing sequence:
## tinyuf2
Keyboards may opt into supporting the tinyuf2 bootloader. This is currently only supported on the F411 blackpill.
Keyboards may opt into supporting the tinyuf2 bootloader. This is currently only supported on the F401/F411 blackpill.
The `rules.mk` setting for this bootloader is `tinyuf2`, and can be specified at the keymap or user level.

8
docs/fr-fr/cli.md
View file

@ -85,14 +85,14 @@ qmk compile <configuratorExport.json>
qmk compile -kb <keyboard_name> -km <keymap_name>
```
## `qmk cformat`
## `qmk format-c`
Cette commande formatte le code C en utilisant clang-format. Lancez-la sans arguments pour formatter tout le code core, ou passez les noms de fichiers à la ligne de commande pour la lancer sur des fichiers spécifiques.
**Utilisation**:
```
qmk cformat [file1] [file2] [...] [fileN]
qmk format-c [file1] [file2] [...] [fileN]
```
## `qmk config`
@ -125,14 +125,14 @@ Cette commande crée une nouvelle keymap basée sur une keymap par défaut d'un
qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
```
## `qmk pyformat`
## `qmk format-py`
Cette commande formate le code python dans `qmk_firmware`.
**Utilisation**:
```
qmk pyformat
qmk format-py
```
## `qmk pytest`

34
docs/hardware_avr.md
View file

@ -6,26 +6,28 @@ If you have not yet you should read the [Keyboard Guidelines](hardware_keyboard_
## Adding Your AVR Keyboard to QMK
QMK has a number of features to simplify working with AVR keyboards. For most keyboards you don't have to write a single line of code. To get started, run the `util/new_keyboard.sh` script:
QMK has a number of features to simplify working with AVR keyboards. For most keyboards you don't have to write a single line of code. To get started, run `qmk new-keyboard`:
```
$ ./util/new_keyboard.sh
Generating a new QMK keyboard directory
$ qmk new-keyboard
Ψ Generating a new QMK keyboard directory
Keyboard Name: mycoolkb
Keyboard Type [avr]:
Your Name [John Smith]:
Keyboard Name: mycoolkeeb
Keyboard Type:
1. avr
2. ps2avrgb
Please enter your choice: [1]
Your Name: [John Smith]
Ψ Copying base template files...
Ψ Copying avr template files...
Ψ Renaming keyboard.[ch] to mycoolkeeb.[ch]...
Ψ Replacing %YEAR% with 2021...
Ψ Replacing %KEYBOARD% with mycoolkeeb...
Ψ Replacing %YOUR_NAME% with John Smith...
Copying base template files... done
Copying avr template files... done
Renaming keyboard files... done
Replacing %KEYBOARD% with mycoolkb... done
Replacing %YOUR_NAME% with John Smith... done
Created a new keyboard called mycoolkb.
To start working on things, cd into keyboards/mycoolkb,
or open the directory in your favourite text editor.
Ψ Created a new keyboard called mycoolkeeb.
Ψ To start working on things, `cd` into keyboards/mycoolkeeb,
Ψ or open the directory in your preferred text editor.
```
This will create all the files needed to support your new keyboard, and populate the settings with default values. Now you just need to customize it for your keyboard.

4
docs/hardware_keyboard_guidelines.md
View file

@ -189,9 +189,9 @@ Hardware files (such as plates, cases, pcb) can be contributed to the [qmk.fm re
Given the amount of functionality that QMK exposes it's very easy to confuse new users. When putting together the default firmware for your keyboard we recommend limiting your enabled features and options to the minimal set needed to support your hardware. Recommendations for specific features follow.
### Bootmagic and Command
### Magic Keycodes and Command
[Bootmagic](feature_bootmagic.md) and [Command](feature_command.md) are two related features that allow a user to control their keyboard in non-obvious ways. We recommend you think long and hard about if you're going to enable either feature, and how you will expose this functionality. Keep in mind that users who want this functionality can enable it in their personal keymaps without affecting all the novice users who may be using your keyboard as their first programmable board.
[Magic Keycodes](keycodes_magic.md) and [Command](feature_command.md) are two related features that allow a user to control their keyboard in non-obvious ways. We recommend you think long and hard about if you're going to enable either feature, and how you will expose this functionality. Keep in mind that users who want this functionality can enable it in their personal keymaps without affecting all the novice users who may be using your keyboard as their first programmable board.
By far the most common problem new users encounter is accidentally triggering Bootmagic while they're plugging in their keyboard. They're holding the keyboard by the bottom, unknowingly pressing in alt and spacebar, and then they find that these keys have been swapped on them. We recommend leaving this feature disabled by default, but if you do turn it on consider setting `BOOTMAGIC_KEY_SALT` to a key that is hard to press while plugging your keyboard in.

14
docs/ja/cli_commands.md
View file

@ -211,7 +211,7 @@ qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
# 開発者用コマンド
## `qmk cformat`
## `qmk format-c`
このコマンドは clang-format を使って C コードを整形します。
@ -222,25 +222,25 @@ qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
**指定したファイルに対する使い方**:
```
qmk cformat [file1] [file2] [...] [fileN]
qmk format-c [file1] [file2] [...] [fileN]
```
**全てのコアファイルに対する使い方**:
```
qmk cformat -a
qmk format-c -a
```
**origin/master で変更されたファイルのみに対する使い方**:
```
qmk cformat
qmk format-c
```
**branch_name で変更されたファイルのみに対する使い方**:
```
qmk cformat -b branch_name
qmk format-c -b branch_name
```
## `qmk docs`
@ -275,14 +275,14 @@ $ qmk kle2json -f kle.txt -f
Ψ Wrote out to info.json
```
## `qmk pyformat`
## `qmk format-py`
このコマンドは `qmk_firmware` 内の python コードを整形します。
**使用法**:
```
qmk pyformat
qmk format-py
```
## `qmk pytest`

4
docs/ja/cli_development.md
View file

@ -192,7 +192,7 @@ cli.log.info('Reading from %s and writing to %s', cli.args.filename, cli.args.ou
# テスト、リントおよびフォーマット
nose2、flake8 および yapf を使ってコードをテスト、リントおよびフォーマットします。これらのテストを実行するために `pytest` と `pyformat` サブコマンドを使うことができます。
nose2、flake8 および yapf を使ってコードをテスト、リントおよびフォーマットします。これらのテストを実行するために `pytest` と `format-py` サブコマンドを使うことができます。
### テストとリント
@ -200,7 +200,7 @@ nose2、flake8 および yapf を使ってコードをテスト、リントお
### フォーマット
qmk pyformat
qmk format-py
## フォーマットの詳細

3
docs/ja/compatible_microcontrollers.md
View file

@ -32,10 +32,13 @@ QMK は十分な容量のフラッシュメモリを備えた USB 対応 AVR ま
* [STM32F103](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html)
* [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html)
* [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html)
* [STM32F407](https://www.st.com/en/microcontrollers-microprocessors/stm32f407-417.html)
* [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html)
* [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html)
* [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html)
* [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html)
* [STM32L412](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html)
* [STM32L422](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html)
* [STM32L433](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html)
* [STM32L443](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html)

2
docs/ja/feature_bootmagic.md
View file

@ -16,7 +16,7 @@
一部のキーボードでは、ブートマジックはデフォルトで無効になっています。その場合、`rules.mk` 内で以下のように明示的に有効にする必要があります:
```make
BOOTMAGIC_ENABLE = full
BOOTMAGIC_ENABLE = yes
```
?> `full` の代わりに `yes` が使われていることがあるかもしれませんが、これは問題ありません。ただし、`yes` は非推奨で、理想的には `full` (あるいは`lite`) が使われるべきです。

17
docs/ja/feature_debounce_type.md
View file

@ -88,15 +88,6 @@ voltage +----------------------
## QMK でサポートされるデバウンスアルゴリズム
QMK はデバウンス API を介して複数のデバウンスアルゴリズムをサポートします。
どのデバウンスメソッドが呼ばれるかのロジックは下記のとおりです。```rules.mk``` で設定された様々な定義をチェックします。
```
DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce
DEBOUNCE_TYPE?= sym_defer_g
ifneq ($(strip $(DEBOUNCE_TYPE)), custom)
QUANTUM_SRC += $(DEBOUNCE_DIR)/$(strip $(DEBOUNCE_TYPE)).c
endif
```
### デバウンスの選択
@ -135,11 +126,3 @@ DEBOUNCE_TYPE = <アルゴリズムの名前>
* デバウンスは、全てのマトリクススキャンの後で発生します。
* MATRIX_ROWS ではなく num_rows を使って、分割キーボードが正しくサポートされるようにします。
* アルゴリズムが他のキーボードにも適用できる可能性がある場合、```quantum/debounce``` に追加することを検討してください。
### 古い名前
次の既存のアルゴリズムの古い名前は引き続きサポートされますが、代わりに新しい名前を使うことを推奨します。
* sym_g - sym_defer_g の古い名前
* eager_pk - sym_eager_pk の古い名前
* sym_pk - sym_defer_pk の古い名前
* eager_pr - sym_eager_pr の古い名前

18
docs/ja/feature_dip_switch.md
View file

@ -14,6 +14,8 @@ DIP スイッチは、以下を `rules.mk` に追加することでサポート
```c
// Connects each switch in the dip switch to the GPIO pin of the MCU
#define DIP_SWITCH_PINS { B14, A15, A10, B9 }
// For split keyboards, you can separately define the right side pins
#define DIP_SWITCH_PINS_RIGHT { ... }
```
あるいは
@ -28,8 +30,9 @@ DIP スイッチは、以下を `rules.mk` に追加することでサポート
コールバック関数を `<keyboard>.c` に記述することができます:
```c
void dip_switch_update_kb(uint8_t index, bool active) {
dip_switch_update_user(index, active);
bool dip_switch_update_kb(uint8_t index, bool active) {
if !(dip_switch_update_user(index, active)) { return false; }
return true;
}
```
@ -37,7 +40,7 @@ void dip_switch_update_kb(uint8_t index, bool active) {
あるいは `keymap.c` に記述することもできます:
```c
void dip_switch_update_user(uint8_t index, bool active) {
bool dip_switch_update_user(uint8_t index, bool active) {
switch (index) {
case 0:
if(active) { audio_on(); } else { audio_off(); }
@ -62,6 +65,7 @@ void dip_switch_update_user(uint8_t index, bool active) {
}
break;
}
return true;
}
```
@ -69,8 +73,9 @@ void dip_switch_update_user(uint8_t index, bool active) {
```c
void dip_switch_update_mask_kb(uint32_t state) {
dip_switch_update_mask_user(state);
bool dip_switch_update_mask_kb(uint32_t state) {
if (!dip_switch_update_mask_user(state)) { return false; }
return true;
}
```
@ -78,7 +83,7 @@ void dip_switch_update_mask_kb(uint32_t state) {
あるいは `keymap.c` に記述することもできます:
```c
void dip_switch_update_mask_user(uint32_t state) {
bool dip_switch_update_mask_user(uint32_t state) {
if (state & (1UL<<0) && state & (1UL<<1)) {
layer_on(_ADJUST); // C on esc
} else {
@ -94,6 +99,7 @@ void dip_switch_update_mask_user(uint32_t state) {
} else {
layer_off(_TEST_B);
}
return true;
}
```

10
docs/ja/feature_encoders.md
View file

@ -51,15 +51,18 @@ ENCODER_ENABLE = yes
コールバック関数を `<keyboard>.c` に記述することができます:
```c
void encoder_update_kb(uint8_t index, bool clockwise) {
encoder_update_user(index, clockwise);
bool encoder_update_kb(uint8_t index, bool clockwise) {
if (!encoder_update_user(index, clockwise)) {
return false;
}
}
```
あるいは `keymap.c` に記述することもできます:
```c
void encoder_update_user(uint8_t index, bool clockwise) {
bool encoder_update_user(uint8_t index, bool clockwise) {
if (index == 0) { /* First encoder */
if (clockwise) {
tap_code(KC_PGDN);
@ -73,6 +76,7 @@ void encoder_update_user(uint8_t index, bool clockwise) {
tap_code(KC_UP);
}
}
return true;
}
```

4
docs/ja/feature_led_matrix.md
View file

@ -52,7 +52,7 @@ I2C IS31FL3731 RGB コントローラを使ったアドレス指定可能な LED
`<keyboard>.c` に全ての LED を列挙する配列を定義します:
const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
const is31_led __flash g_is31_leds[DRIVER_LED_TOTAL] = {
/* これらの位置については IS31 マニュアルを参照してください
* driver
* | LED address
@ -61,7 +61,7 @@ I2C IS31FL3731 RGB コントローラを使ったアドレス指定可能な LED
....
}
ここで、`Cx_y` は[データシート](https://www.issi.com/WW/pdf/31FL3731.pdf)およびヘッダファイル `drivers/issi/is31fl3731-simple.h` で定義されるマトリックス内の LED の位置です。`driver` は `config.h` で定義したドライバのインデックス(`0`、`1`、`2`、`3`のいずれか)です。
ここで、`Cx_y` は[データシート](https://www.issi.com/WW/pdf/31FL3731.pdf)およびヘッダファイル `drivers/led/issi/is31fl3731-simple.h` で定義されるマトリックス内の LED の位置です。`driver` は `config.h` で定義したドライバのインデックス(`0`、`1`、`2`、`3`のいずれか)です。
## キーコード

2
docs/ja/feature_tap_dance.md
View file

@ -59,7 +59,7 @@
このことは、あなたは再びキーをタップするまでの時間として `TAPPING_TERM` の時間を持っていることを意味します。そのため、あなたは1つの `TAPPING_TERM` の時間内に全てのタップを行う必要はありません。これにより、キーの反応への影響を最小限に抑えながら、より長いタップ回数を可能にします。
次は `matrix_scan_tap_dance()` です。この関数はタップダンスキーのタイムアウトを制御します。
次は `tap_dance_task()` です。この関数はタップダンスキーのタイムアウトを制御します。
柔軟性のために、タップダンスは、キーコードの組み合わせにも、ユーザー関数にもなることができます。後者は、より高度なタップ回数の制御や、LED を点滅させたり、バックライトをいじったり、等々の制御を可能にします。これは、1つの共用体と、いくつかの賢いマクロによって成し遂げられています。

34
docs/ja/hardware_avr.md
View file

@ -12,26 +12,28 @@
## AVR を使用したキーボードを QMK に追加する
QMK には AVR を使ったキーボードでの作業を簡略化するための機能が多数あります。大体のキーボードでは1行もコードを書く必要がありません。まずはじめに、`util/new_keyboard.sh` スクリプトを実行します。
QMK には AVR を使ったキーボードでの作業を簡略化するための機能が多数あります。大体のキーボードでは1行もコードを書く必要がありません。まずはじめに、`qmk new-keyboard` を実行します。
```
$ ./util/new_keyboard.sh
Generating a new QMK keyboard directory
$ qmk new-keyboard
Ψ Generating a new QMK keyboard directory
Keyboard Name: mycoolkb
Keyboard Type [avr]:
Your Name [John Smith]:
Keyboard Name: mycoolkeeb
Keyboard Type:
1. avr
2. ps2avrgb
Please enter your choice: [1]
Your Name: [John Smith]
Ψ Copying base template files...
Ψ Copying avr template files...
Ψ Renaming keyboard.[ch] to mycoolkeeb.[ch]...
Ψ Replacing %YEAR% with 2021...
Ψ Replacing %KEYBOARD% with mycoolkeeb...
Ψ Replacing %YOUR_NAME% with John Smith...
Copying base template files... done
Copying avr template files... done
Renaming keyboard files... done
Replacing %KEYBOARD% with mycoolkb... done
Replacing %YOUR_NAME% with John Smith... done
Created a new keyboard called mycoolkb.
To start working on things, cd into keyboards/mycoolkb,
or open the directory in your favourite text editor.
Ψ Created a new keyboard called mycoolkeeb.
Ψ To start working on things, `cd` into keyboards/mycoolkeeb,
Ψ or open the directory in your preferred text editor.
```
これにより、新しいキーボードをサポートするために必要なすべてのファイルが作成され、デフォルト値で設定が入力されます。あとはあなたのキーボード用にカスタマイズするだけです。

2
docs/ja/reference_configurator_support.md
View file

@ -104,8 +104,6 @@ JSON ファイルをビルドする最も簡単な方法は、[Keyboard Layout E
"tags": {
"form_factor": "numpad"
},
"width": 4,
"height": 5,
"layouts": {
"LAYOUT": {
"layout": [

4
docs/ja/reference_info_json.md
View file

@ -20,10 +20,6 @@
* キーボードの製品ページ、[QMK.fm/keyboards](https://qmk.fm/keyboards) のページ、あるいはキーボードに関する情報を説明する他のページの URL。
* `maintainer`
* メンテナの GitHub のユーザ名、あるいはコミュニティが管理するキーボードの場合は `qmk`
* `width`
* キー単位でのキーボードの幅
* `height`
* キー単位でのキーボードの高さ
* `layouts`
* 物理的なレイアウト表現。詳細は以下のセクションを見てください。

72
docs/keycodes.md
View file

@ -257,42 +257,6 @@ See also: [Backlighting](feature_backlight.md)
|`BL_DEC` |Decrease the backlight level |
|`BL_BRTG`|Toggle backlight breathing |
## Bootmagic :id=bootmagic
See also: [Bootmagic](feature_bootmagic.md)
|Key |Aliases |Description |
|----------------------------------|---------|--------------------------------------------------------------------------|
|`MAGIC_SWAP_CONTROL_CAPSLOCK` |`CL_SWAP`|Swap Caps Lock and Left Control |
|`MAGIC_UNSWAP_CONTROL_CAPSLOCK` |`CL_NORM`|Unswap Caps Lock and Left Control |
|`MAGIC_CAPSLOCK_TO_CONTROL` |`CL_CTRL`|Treat Caps Lock as Control |
|`MAGIC_UNCAPSLOCK_TO_CONTROL` |`CL_CAPS`|Stop treating Caps Lock as Control |
|`MAGIC_SWAP_LCTL_LGUI` |`LCG_SWP`|Swap Left Control and GUI |
|`MAGIC_UNSWAP_LCTL_LGUI` |`LCG_NRM`|Unswap Left Control and GUI |
|`MAGIC_SWAP_RCTL_RGUI` |`RCG_SWP`|Swap Right Control and GUI |
|`MAGIC_UNSWAP_RCTL_RGUI` |`RCG_NRM`|Unswap Right Control and GUI |
|`MAGIC_SWAP_CTL_GUI` |`CG_SWAP`|Swap Control and GUI on both sides |
|`MAGIC_UNSWAP_CTL_GUI` |`CG_NORM`|Unswap Control and GUI on both sides |
|`MAGIC_TOGGLE_CTL_GUI` |`CG_TOGG`|Toggle Control and GUI swap on both sides |
|`MAGIC_SWAP_LALT_LGUI` |`LAG_SWP`|Swap Left Alt and GUI |
|`MAGIC_UNSWAP_LALT_LGUI` |`LAG_NRM`|Unswap Left Alt and GUI |
|`MAGIC_SWAP_RALT_RGUI` |`RAG_SWP`|Swap Right Alt and GUI |
|`MAGIC_UNSWAP_RALT_RGUI` |`RAG_NRM`|Unswap Right Alt and GUI |
|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides |
|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Alt and GUI on both sides |
|`MAGIC_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Alt and GUI swap on both sides |
|`MAGIC_NO_GUI` |`GUI_OFF`|Disable the GUI keys |
|`MAGIC_UNNO_GUI` |`GUI_ON` |Enable the GUI keys |
|`MAGIC_SWAP_GRAVE_ESC` |`GE_SWAP`|Swap <code>&#96;</code> and Escape |
|`MAGIC_UNSWAP_GRAVE_ESC` |`GE_NORM`|Unswap <code>&#96;</code> and Escape |
|`MAGIC_SWAP_BACKSLASH_BACKSPACE` |`BS_SWAP`|Swap `\` and Backspace |
|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|`BS_NORM`|Unswap `\` and Backspace |
|`MAGIC_HOST_NKRO` |`NK_ON` |Enable N-key rollover |
|`MAGIC_UNHOST_NKRO` |`NK_OFF` |Disable N-key rollover |
|`MAGIC_TOGGLE_NKRO` |`NK_TOGG`|Toggle N-key rollover |
|`MAGIC_EE_HANDS_LEFT` |`EH_LEFT`|Set the master half of a split keyboard as the left hand (for `EE_HANDS`) |
|`MAGIC_EE_HANDS_RIGHT` |`EH_RGHT`|Set the master half of a split keyboard as the right hand (for `EE_HANDS`)|
## Bluetooth :id=bluetooth
See also: [Bluetooth](feature_bluetooth.md)
@ -354,6 +318,42 @@ See also: [Leader Key](feature_leader_key.md)
|---------|------------------------|
|`KC_LEAD`|Begins a leader sequence|
## Magic Keycodes :id=magic-keycodes
See also: [Magic Keycodes](keycodes_magic.md)
|Key |Aliases |Description |
|----------------------------------|---------|--------------------------------------------------------------------------|
|`MAGIC_SWAP_CONTROL_CAPSLOCK` |`CL_SWAP`|Swap Caps Lock and Left Control |
|`MAGIC_UNSWAP_CONTROL_CAPSLOCK` |`CL_NORM`|Unswap Caps Lock and Left Control |
|`MAGIC_CAPSLOCK_TO_CONTROL` |`CL_CTRL`|Treat Caps Lock as Control |
|`MAGIC_UNCAPSLOCK_TO_CONTROL` |`CL_CAPS`|Stop treating Caps Lock as Control |
|`MAGIC_SWAP_LCTL_LGUI` |`LCG_SWP`|Swap Left Control and GUI |
|`MAGIC_UNSWAP_LCTL_LGUI` |`LCG_NRM`|Unswap Left Control and GUI |
|`MAGIC_SWAP_RCTL_RGUI` |`RCG_SWP`|Swap Right Control and GUI |
|`MAGIC_UNSWAP_RCTL_RGUI` |`RCG_NRM`|Unswap Right Control and GUI |
|`MAGIC_SWAP_CTL_GUI` |`CG_SWAP`|Swap Control and GUI on both sides |
|`MAGIC_UNSWAP_CTL_GUI` |`CG_NORM`|Unswap Control and GUI on both sides |
|`MAGIC_TOGGLE_CTL_GUI` |`CG_TOGG`|Toggle Control and GUI swap on both sides |
|`MAGIC_SWAP_LALT_LGUI` |`LAG_SWP`|Swap Left Alt and GUI |
|`MAGIC_UNSWAP_LALT_LGUI` |`LAG_NRM`|Unswap Left Alt and GUI |
|`MAGIC_SWAP_RALT_RGUI` |`RAG_SWP`|Swap Right Alt and GUI |
|`MAGIC_UNSWAP_RALT_RGUI` |`RAG_NRM`|Unswap Right Alt and GUI |
|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides |
|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Alt and GUI on both sides |
|`MAGIC_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Alt and GUI swap on both sides |
|`MAGIC_NO_GUI` |`GUI_OFF`|Disable the GUI keys |
|`MAGIC_UNNO_GUI` |`GUI_ON` |Enable the GUI keys |
|`MAGIC_SWAP_GRAVE_ESC` |`GE_SWAP`|Swap <code>&#96;</code> and Escape |
|`MAGIC_UNSWAP_GRAVE_ESC` |`GE_NORM`|Unswap <code>&#96;</code> and Escape |
|`MAGIC_SWAP_BACKSLASH_BACKSPACE` |`BS_SWAP`|Swap `\` and Backspace |
|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|`BS_NORM`|Unswap `\` and Backspace |
|`MAGIC_HOST_NKRO` |`NK_ON` |Enable N-key rollover |
|`MAGIC_UNHOST_NKRO` |`NK_OFF` |Disable N-key rollover |
|`MAGIC_TOGGLE_NKRO` |`NK_TOGG`|Toggle N-key rollover |
|`MAGIC_EE_HANDS_LEFT` |`EH_LEFT`|Set the master half of a split keyboard as the left hand (for `EE_HANDS`) |
|`MAGIC_EE_HANDS_RIGHT` |`EH_RGHT`|Set the master half of a split keyboard as the right hand (for `EE_HANDS`)|
## MIDI :id=midi
See also: [MIDI](feature_midi.md)

36
docs/keycodes_magic.md Normal file
View file

@ -0,0 +1,36 @@
# Magic Keycodes :id=magic-keycodes
**Magic Keycodes** are prefixed with `MAGIC_`, and allow you to access the functionality of the deprecated Bootmagic feature *after* your keyboard has initialized. To use the keycodes, assign them to your keymap as you would any other keycode.
|Key |Aliases |Description |
|----------------------------------|---------|--------------------------------------------------------------------------|
|`MAGIC_SWAP_CONTROL_CAPSLOCK` |`CL_SWAP`|Swap Caps Lock and Left Control |
|`MAGIC_UNSWAP_CONTROL_CAPSLOCK` |`CL_NORM`|Unswap Caps Lock and Left Control |
|`MAGIC_CAPSLOCK_TO_CONTROL` |`CL_CTRL`|Treat Caps Lock as Control |
|`MAGIC_UNCAPSLOCK_TO_CONTROL` |`CL_CAPS`|Stop treating Caps Lock as Control |
|`MAGIC_SWAP_LCTL_LGUI` |`LCG_SWP`|Swap Left Control and GUI |
|`MAGIC_UNSWAP_LCTL_LGUI` |`LCG_NRM`|Unswap Left Control and GUI |
|`MAGIC_SWAP_RCTL_RGUI` |`RCG_SWP`|Swap Right Control and GUI |
|`MAGIC_UNSWAP_RCTL_RGUI` |`RCG_NRM`|Unswap Right Control and GUI |
|`MAGIC_SWAP_CTL_GUI` |`CG_SWAP`|Swap Control and GUI on both sides |
|`MAGIC_UNSWAP_CTL_GUI` |`CG_NORM`|Unswap Control and GUI on both sides |
|`MAGIC_TOGGLE_CTL_GUI` |`CG_TOGG`|Toggle Control and GUI swap on both sides |
|`MAGIC_SWAP_LALT_LGUI` |`LAG_SWP`|Swap Left Alt and GUI |
|`MAGIC_UNSWAP_LALT_LGUI` |`LAG_NRM`|Unswap Left Alt and GUI |
|`MAGIC_SWAP_RALT_RGUI` |`RAG_SWP`|Swap Right Alt and GUI |
|`MAGIC_UNSWAP_RALT_RGUI` |`RAG_NRM`|Unswap Right Alt and GUI |
|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides |
|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Alt and GUI on both sides |
|`MAGIC_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Alt and GUI swap on both sides |
|`MAGIC_NO_GUI` |`GUI_OFF`|Disable the GUI keys |
|`MAGIC_UNNO_GUI` |`GUI_ON` |Enable the GUI keys |
|`MAGIC_TOGGLE_GUI` |`GUI_TOG`|Toggles the status of the GUI keys |
|`MAGIC_SWAP_GRAVE_ESC` |`GE_SWAP`|Swap <code>&#96;</code> and Escape |
|`MAGIC_UNSWAP_GRAVE_ESC` |`GE_NORM`|Unswap <code>&#96;</code> and Escape |
|`MAGIC_SWAP_BACKSLASH_BACKSPACE` |`BS_SWAP`|Swap `\` and Backspace |
|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|`BS_NORM`|Unswap `\` and Backspace |
|`MAGIC_HOST_NKRO` |`NK_ON` |Enable N-key rollover |
|`MAGIC_UNHOST_NKRO` |`NK_OFF` |Disable N-key rollover |
|`MAGIC_TOGGLE_NKRO` |`NK_TOGG`|Toggle N-key rollover |
|`MAGIC_EE_HANDS_LEFT` |`EH_LEFT`|Set the master half of a split keyboard as the left hand (for `EE_HANDS`) |
|`MAGIC_EE_HANDS_RIGHT` |`EH_RGHT`|Set the master half of a split keyboard as the right hand (for `EE_HANDS`)|

2
docs/ref_functions.md
View file

@ -93,7 +93,7 @@ And to do so, add `reset_keyboard()` to your function or macro, and this will re
## Wiping the EEPROM (Persistent Storage)
If you're having issues with Audio, RGB Underglow, backlighting or keys acting weird, then you can reset the EEPROM (persistent setting storage). To force an EEPROM reset, use the [`EEP_RST` keycode](quantum_keycodes.md) or [Bootmagic](feature_bootmagic.md) functionality. If neither of those are an option, then you can use a custom macro to do so.
If you're having issues with Audio, RGB Underglow, backlighting or keys acting weird, then you can reset the EEPROM (persistent setting storage). To force an EEPROM reset, use the [`EEP_RST` keycode](quantum_keycodes.md) or [Bootmagic Lite](feature_bootmagic.md) functionality. If neither of those are an option, then you can use a custom macro to do so.
To wipe the EEPROM, run `eeconfig_init()` from your function or macro to reset most of the settings to default.

2
docs/reference_configurator_support.md
View file

@ -99,8 +99,6 @@ Use the `keyboard_name` object to set the name of the keyboard. For instruction
"tags": {
"form_factor": "numpad"
},
"width": 4,
"height": 5,
"layouts": {
"LAYOUT": {
"layout": [

4
docs/reference_info_json.md
View file

@ -15,10 +15,6 @@ The `info.json` file is a JSON formatted dictionary with the following keys avai
* A URL to the keyboard's product page, [QMK.fm/keyboards](https://qmk.fm/keyboards) page, or other page describing information about the keyboard.
* `maintainer`
* GitHub username of the maintainer, or `qmk` for community maintained boards
* `width`
* Width of the board in Key Units
* `height`
* Height of the board in Key Units
* `debounce`
* How many milliseconds (ms) to wait for debounce to happen. (Default: 5)
* `diode_direction`

19
docs/serial_driver.md
View file

@ -63,7 +63,7 @@ Configure the hardware via your config.h:
// 5: about 19200 baud
#define SERIAL_USART_DRIVER SD1 // USART driver of TX pin. default: SD1
#define SERIAL_USART_TX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7
#define SERIAL_USART_TIMEOUT 100 // USART driver timeout. default 100
#define SERIAL_USART_TIMEOUT 20 // USART driver timeout. default 20
```
You must also enable the ChibiOS `SERIAL` feature:
@ -73,7 +73,7 @@ You must also enable the ChibiOS `SERIAL` feature:
Do note that the configuration required is for the `SERIAL` peripheral, not the `UART` peripheral.
### USART Full-duplex
Targeting STM32 boards where communication is offloaded to a USART hardware device. The advantage over bitbang is that this provides fast and accurate timings. USART Full-Duplex requires two conductors **without** pull-up resistors instead of one conductor with a pull-up resistor unlike the Half-duplex driver, but it is more efficent as it uses DMA transfers, which can result in even faster transmission speeds.
Targeting STM32 boards where communication is offloaded to a USART hardware device. The advantage over bitbang is that this provides fast and accurate timings. USART Full-Duplex requires two conductors **without** pull-up resistors instead of one conductor with a pull-up resistor unlike the Half-duplex driver. Due to its internal design it is more efficent, which can result in even faster transmission speeds.
#### Pin configuration
@ -86,12 +86,13 @@ Please note that `TX` of the master half has to be connected with the `RX` pin o
To use the driver, add this to your rules.mk:
```make
SERIAL_DRIVER = usart_duplex
SERIAL_DRIVER = usart
```
Next configure the hardware via your config.h:
```c
#define SERIAL_USART_FULL_DUPLEX // Enable full duplex operation mode.
#define SERIAL_USART_TX_PIN B6 // USART TX pin
#define SERIAL_USART_RX_PIN B7 // USART RX pin
//#define USART1_REMAP // Remap USART TX and RX pins on STM32F103 MCUs, see table below.
@ -104,17 +105,17 @@ Next configure the hardware via your config.h:
// 3: 57600 baud
// 4: 38400 baud
// 5: 19200 baud
#define SERIAL_USART_DRIVER UARTD1 // USART driver of TX and RX pin. default: UARTD1
#define SERIAL_USART_DRIVER SD1 // USART driver of TX and RX pin. default: SD1
#define SERIAL_USART_TX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7
#define SERIAL_USART_RX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7
#define SERIAL_USART_TIMEOUT 100 // USART driver timeout. default 100
#define SERIAL_USART_TIMEOUT 20 // USART driver timeout. default 20
```
You must also enable the ChibiOS `UART` with blocking api feature:
* In your board's halconf.h: `#define HAL_USE_UART TRUE` and `#define UART_USE_WAIT TRUE`
* In your board's mcuconf.h: `#define STM32_UART_USE_USARTn TRUE` (where 'n' matches the peripheral number of your selected USART on the MCU)
You must also enable the ChibiOS `SERIAL` feature:
* In your board's halconf.h: `#define HAL_USE_SERIAL TRUE`
* In your board's mcuconf.h: `#define STM32_SERIAL_USE_USARTn TRUE` (where 'n' matches the peripheral number of your selected USART on the MCU)
Do note that the configuration required is for the `UART` peripheral, not the `SERIAL` peripheral.
Do note that the configuration required is for the `SERIAL` peripheral, not the `UART` peripheral.
#### Pins for USART Peripherals with Alternate Functions for selected STM32 MCUs

3
docs/syllabus.md
View file

@ -40,6 +40,7 @@ These topics start to dig into some of the features that QMK supports. You don't
* [Tap Dance](feature_tap_dance.md)
* [Combos](feature_combo.md)
* [Userspace](feature_userspace.md)
* [Key Overrides](feature_key_overrides.md)
# Advanced Topics
@ -53,7 +54,7 @@ Everything below here requires a lot of foundational knowledge. Besides being ab
* **Advanced Features**
* [Unicode](feature_unicode.md)
* [API](api_overview.md)
* [Bootmagic](feature_bootmagic.md)
* [Bootmagic Lite](feature_bootmagic.md)
* **Hardware**
* [How Keyboards Work](how_keyboards_work.md)
* [How A Keyboard Matrix Works](how_a_matrix_works.md)

108
docs/tap_hold.md
View file

@ -36,29 +36,49 @@ uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) {
}
```
## Tap-Or-Hold Decision Modes
## Permissive Hold
The code which decides between the tap and hold actions of dual-role keys supports three different modes, in increasing order of preference for the hold action:
As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new `config.h` option:
1. The default mode selects the hold action only if the dual-role key is held down longer than the tapping term. In this mode pressing other keys while the dual-role key is held down does not influence the tap-or-hold decision.
2. The “permissive hold” mode, in addition to the default behavior, immediately selects the hold action when another key is tapped (pressed and then released) while the dual-role key is held down, even if this happens earlier than the tapping term. If another key is just pressed, but then the dual-role key is released before that other key (and earlier than the tapping term), this mode will still select the tap action.
3. The “hold on other key press” mode, in addition to the default behavior, immediately selects the hold action when another key is pressed while the dual-role key is held down, even if this happens earlier than the tapping term.
Note that until the tap-or-hold decision completes (which happens when either the dual-role key is released, or the tapping term has expired, or the extra condition for the selected decision mode is satisfied), key events are delayed and not transmitted to the host immediately. The default mode gives the most delay (if the dual-role key is held down, this mode always waits for the whole tapping term), and the other modes may give less delay when other keys are pressed, because the hold action may be selected earlier.
### Permissive Hold
The “permissive hold” mode can be enabled for all dual-role keys by adding the corresponding option to `config.h`:
```c
#define PERMISSIVE_HOLD
```
This makes tap and hold keys (like Mod Tap) work better for fast typists, or for high `TAPPING_TERM` settings.
This makes tap and hold keys (like Layer Tap) work better for fast typists, or for high `TAPPING_TERM` settings.
If you press a Mod Tap key, tap another key (press and release) and then release the Mod Tap key, all within the tapping term, it will output the tapping function for both keys.
If you press a dual-role key, tap another key (press and release) and then release the dual-role key, all within the tapping term, by default the dual-role key will perform its tap action. If the `PERMISSIVE_HOLD` option is enabled, the dual-role key will perform its hold action instead.
For Instance:
An example of a sequence which is affected by the “permissive hold” mode:
- `SFT_T(KC_A)` Down
- `KC_X` Down
- `KC_X` Up
- `SFT_T(KC_A)` Up
- `LT(2, KC_A)` Down
- `KC_L` Down (the `L` key is also mapped to `KC_RGHT` on layer 2)
- `KC_L` Up
- `LT(2, KC_A)` Up
Normally, if you do all this within the `TAPPING_TERM` (default: 200ms) this will be registered as `ax` by the firmware and host system. With permissive hold enabled, this modifies how this is handled by considering the Mod Tap keys as a Mod if another key is tapped, and would registered as `X` (`SHIFT`+`x`).
Normally, if you do all this within the `TAPPING_TERM` (default: 200ms), this will be registered as `al` by the firmware and host system. With the `PERMISSIVE_HOLD` option enabled, the Layer Tap key is considered as a layer switch if another key is tapped, and the above sequence would be registered as `KC_RGHT` (the mapping of `L` on layer 2).
?> If you have `Ignore Mod Tap Interrupt` enabled, as well, this will modify how both work. The regular key has the modifier added if the first key is released first or if both keys are held longer than the `TAPPING_TERM`.
However, this slightly different sequence will not be affected by the “permissive hold” mode:
- `LT(2, KC_A)` Down
- `KC_L` Down (the `L` key is also mapped to `KC_RGHT` on layer 2)
- `LT(2, KC_A)` Up
- `KC_L` Up
In the sequence above the dual-role key is released before the other key is released, and if that happens within the tapping term, the “permissive hold” mode will still choose the tap action for the dual-role key, and the sequence will be registered as `al` by the host.
?> The `PERMISSIVE_HOLD` option also affects Mod Tap keys, but this may not be noticeable if you do not also enable the `IGNORE_MOD_TAP_INTERRUPT` option for those keys, because the default handler for Mod Tap keys also considers both the “nested press” and “rolling press” sequences like shown above as a modifier hold, not the tap action. If you do not enable `IGNORE_MOD_TAP_INTERRUPT`, the effect of `PERMISSIVE_HOLD` on Mod Tap keys would be limited to reducing the delay before the key events are made visible to the host.
For more granular control of this feature, you can add the following to your `config.h`:
@ -72,13 +92,60 @@ You can then add the following function to your keymap:
bool get_permissive_hold(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case LT(1, KC_BSPC):
// Immediately select the hold action when another key is tapped.
return true;
default:
// Do not select the hold action when another key is tapped.
return false;
}
}
```
### Hold On Other Key Press
The “hold on other key press” mode can be enabled for all dual-role keys by adding the corresponding option to `config.h`:
```c
#define HOLD_ON_OTHER_KEY_PRESS
```
This mode makes tap and hold keys (like Layer Tap) work better for fast typists, or for high `TAPPING_TERM` settings. Compared to the “permissive hold” mode, this mode selects the hold action in more cases.
If you press a dual-role key, press another key, and then release the dual-role key, all within the tapping term, by default the dual-role key will perform its tap action. If the `HOLD_ON_OTHER_KEY_PRESS` option is enabled, the dual-role key will perform its hold action instead.
An example of a sequence which is affected by the “hold on other key press” mode, but not by the “permissive hold” mode:
- `LT(2, KC_A)` Down
- `KC_L` Down (the `L` key is also mapped to `KC_RGHT` on layer 2)
- `LT(2, KC_A)` Up
- `KC_L` Up
Normally, if you do all this within the `TAPPING_TERM` (default: 200ms), this will be registered as `al` by the firmware and host system. With the `HOLD_ON_OTHER_KEY_PRESS` option enabled, the Layer Tap key is considered as a layer switch if another key is pressed, and the above sequence would be registered as `KC_RGHT` (the mapping of `L` on layer 2).
?> The `HOLD_ON_OTHER_KEY_PRESS` option also affects Mod Tap keys, but this may not be noticeable if you do not also enable the `IGNORE_MOD_TAP_INTERRUPT` option for those keys, because the default handler for Mod Tap keys also considers the “rolling press” sequence like shown above as a modifier hold, not the tap action. If you do not enable `IGNORE_MOD_TAP_INTERRUPT`, the effect of `HOLD_ON_OTHER_KEY_PRESS` on Mod Tap keys would be limited to reducing the delay before the key events are made visible to the host.
For more granular control of this feature, you can add the following to your `config.h`:
```c
#define HOLD_ON_OTHER_KEY_PRESS_PER_KEY
```
You can then add the following function to your keymap:
```c
bool get_hold_on_other_key_press(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case LT(1, KC_BSPC):
// Immediately select the hold action when another key is pressed.
return true;
default:
// Do not select the hold action when another key is pressed.
return false;
}
}
```
## Ignore Mod Tap Interrupt
To enable this setting, add this to your `config.h`:
@ -87,23 +154,22 @@ To enable this setting, add this to your `config.h`:
#define IGNORE_MOD_TAP_INTERRUPT
```
Similar to Permissive Hold, this alters how the firmware processes inputs for fast typists. If you press a Mod Tap key, press another key, release the Mod Tap key, and then release the normal key, it would normally output the Mod plus the normal key, even if pressed within the `TAPPING_TERM`. This may not be desirable for rolling combo keys, or for fast typists who have a Mod Tap on a frequently used key (`RCTL_T(KC_QUOT)`, for example).
?> This option affects only the Mod Tap keys; it does not affect other dual-role keys such as Layer Tap.
Setting `Ignore Mod Tap Interrupt` requires holding both keys for the `TAPPING_TERM` to trigger the hold function (the mod).
By default the tap-or-hold decision for Mod Tap keys strongly prefers the hold action. If you press a Mod Tap key, then press another key while still holding the Mod Tap key down, the Mod Tap press will be handled as a modifier hold even if the Mod Tap key is then released within the tapping term, and irrespective of the order in which those keys are released. Using options such as `PERMISSIVE_HOLD` or `HOLD_ON_OTHER_KEY_PRESS` will not affect the functionality of Mod Tap keys in a major way (these options would still affect the delay until the common code for dual-role keys finishes its tap-or-hold decision, but then the special code for Mod Tap keys will override the result of that decision and choose the hold action if another key was pressed). In fact, by default the tap-or-hold decision for Mod Tap keys is done in the same way as if the `HOLD_ON_OTHER_KEY_PRESS` option was enabled, but without the decreased delay provided by `HOLD_ON_OTHER_KEY_PRESS`.
For Instance:
If the `IGNORE_MOD_TAP_INTERRUPT` option is enabled, Mod Tap keys are no longer treated as a special case, and their behavior will match the behavior of other dual-role keys such as Layer Tap. Then the behavior of Mod Tap keys can be further tuned using other options such as `PERMISSIVE_HOLD` or `HOLD_ON_OTHER_KEY_PRESS`.
An example of a sequence which will be affected by the `IGNORE_MOD_TAP_INTERRUPT` option (assuming that options like `PERMISSIVE_HOLD` or `HOLD_ON_OTHER_KEY_PRESS` are not enabled):
- `SFT_T(KC_A)` Down
- `KC_X` Down
- `SFT_T(KC_A)` Up
- `KC_X` Up
Normally, this would send a capital `X` (`SHIFT`+`x`), or, Mod + key. With `Ignore Mod Tap Interrupt` enabled, holding both keys are required for the `TAPPING_TERM` to register the hold action. A quick tap will output `ax` in this case, while a hold on both will still output capital `X` (`SHIFT`+`x`).
Normally, this would send a capital `X` (`SHIFT`+`x`), even if the sequence is performed faster than the `TAPPING_TERM`. However, if the `IGNORE_MOD_TAP_INTERRUPT` option is enabled, the `SFT_T(KC_A)` key must be held longer than the `TAPPING_TERM` to register the hold action. A quick tap will output `ax` in this case, while a hold will still output a capital `X` (`SHIFT`+`x`).
?> __Note__: This only concerns modifiers and not layer switching keys.
?> If you have `Permissive Hold` enabled, as well, this will modify how both work. The regular key has the modifier added if the first key is released first or if both keys are held longer than the `TAPPING_TERM`.
However, if the `HOLD_ON_OTHER_KEY_PRESS` option is enabled in addition to `IGNORE_MOD_TAP_INTERRUPT`, the above sequence will again send a capital `X` (`SHIFT`+`x`) even if performed faster that the `TAPPING_TERM`. The difference from the default configuration is that by default the host will receive the key events only after the `SFT_T(KC_A)` key is released, but with the `HOLD_ON_OTHER_KEY_PRESS` option the host will start receiving key events when the `KC_X` key is pressed.
For more granular control of this feature, you can add the following to your `config.h`:
@ -117,8 +183,12 @@ You can then add the following function to your keymap:
bool get_ignore_mod_tap_interrupt(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case SFT_T(KC_SPC):
// Do not force the mod-tap key press to be handled as a modifier
// if any other key was pressed while the mod-tap key is held down.
return true;
default:
// Force the mod-tap key press to be handled as a modifier if any
// other key was pressed while the mod-tap key is held down.
return false;
}
}

1
docs/understanding_qmk.md
View file

@ -146,6 +146,7 @@ The `process_record()` function itself is deceptively simple, but hidden within
* [`bool process_audio(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_audio.c#L19)
* [`bool process_steno(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_steno.c#L160)
* [`bool process_music(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_music.c#L114)
* [`bool process_key_override(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/5a1b857dea45a17698f6baa7dd1b7a7ea907fb0a/quantum/process_keycode/process_key_override.c#L397)
* [`bool process_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_tap_dance.c#L141)
* [`bool process_unicode_common(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_unicode_common.c#L169)
calls one of:

6
docs/zh-cn/custom_quantum_functions.md
View file

@ -297,7 +297,7 @@ void suspend_wakeup_init_user(void) {
本例使用了Planck键盘示范了如何设置 [RGB背光灯](feature_rgblight.md)使之与层对应
```c
uint32_t layer_state_set_user(uint32_t state) {
layer_state_t layer_state_set_user(layer_state_t state) {
switch (biton32(state)) {
case _RAISE:
rgblight_setrgb (0x00, 0x00, 0xFF);
@ -321,7 +321,7 @@ uint32_t layer_state_set_user(uint32_t state) {
### `layer_state_set_*` 函数文档
* 键盘/修订: `uint32_t layer_state_set_kb(uint32_t state)`
* 布局: `uint32_t layer_state_set_user(uint32_t state)`
* 布局: `layer_state_t layer_state_set_user(layer_state_t state)`
该`状态`是活动层的bitmask, 详见[布局概述](keymap.md#布局的层状态)
@ -377,7 +377,7 @@ void keyboard_post_init_user(void) {
以上函数会在读EEPROM配置后立即使用该设置来设置默认层RGB颜色。"raw"的值是从你上面基于"union"创建的结构体中转换来的。
```c
uint32_t layer_state_set_user(uint32_t state) {
layer_state_t layer_state_set_user(layer_state_t state) {
switch (biton32(state)) {
case _RAISE:
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); }

1
doxygen-todo
View file

@ -21,7 +21,6 @@ quantum/tools
quantum/visualizer
quantum/visualizer/resources
drivers
drivers/avr
drivers/ugfx
drivers/ugfx/gdisp
drivers/ugfx/gdisp/is31fl3731c

62
drivers/avr/serial.h
View file

@ -1,62 +0,0 @@
#pragma once
#include <stdbool.h>
// /////////////////////////////////////////////////////////////////
// Need Soft Serial defines in config.h
// /////////////////////////////////////////////////////////////////
// ex.
// #define SOFT_SERIAL_PIN ?? // ?? = D0,D1,D2,D3,E6
// OPTIONAL: #define SELECT_SOFT_SERIAL_SPEED ? // ? = 1,2,3,4,5
// // 1: about 137kbps (default)
// // 2: about 75kbps
// // 3: about 39kbps
// // 4: about 26kbps
// // 5: about 20kbps
//
// //// USE simple API (using signle-type transaction function)
// /* nothing */
// //// USE flexible API (using multi-type transaction function)
// #define SERIAL_USE_MULTI_TRANSACTION
//
// /////////////////////////////////////////////////////////////////
// Soft Serial Transaction Descriptor
typedef struct _SSTD_t {
uint8_t *status;
uint8_t initiator2target_buffer_size;
uint8_t *initiator2target_buffer;
uint8_t target2initiator_buffer_size;
uint8_t *target2initiator_buffer;
} SSTD_t;
#define TID_LIMIT(table) (sizeof(table) / sizeof(SSTD_t))
// initiator is transaction start side
void soft_serial_initiator_init(SSTD_t *sstd_table, int sstd_table_size);
// target is interrupt accept side
void soft_serial_target_init(SSTD_t *sstd_table, int sstd_table_size);
// initiator resullt
#define TRANSACTION_END 0
#define TRANSACTION_NO_RESPONSE 0x1
#define TRANSACTION_DATA_ERROR 0x2
#define TRANSACTION_TYPE_ERROR 0x4
#ifndef SERIAL_USE_MULTI_TRANSACTION
int soft_serial_transaction(void);
#else
int soft_serial_transaction(int sstd_index);
#endif
// target status
// *SSTD_t.status has
// initiator:
// TRANSACTION_END
// or TRANSACTION_NO_RESPONSE
// or TRANSACTION_DATA_ERROR
// target:
// TRANSACTION_DATA_ERROR
// or TRANSACTION_ACCEPTED
#define TRANSACTION_ACCEPTED 0x8
#ifdef SERIAL_USE_MULTI_TRANSACTION
int soft_serial_get_and_clean_status(int sstd_index);
#endif

62
drivers/chibios/serial.h
View file

@ -1,62 +0,0 @@
#pragma once
#include <stdbool.h>
// /////////////////////////////////////////////////////////////////
// Need Soft Serial defines in config.h
// /////////////////////////////////////////////////////////////////
// ex.
// #define SOFT_SERIAL_PIN ?? // ?? = D0,D1,D2,D3,E6
// OPTIONAL: #define SELECT_SOFT_SERIAL_SPEED ? // ? = 1,2,3,4,5
// // 1: about 137kbps (default)
// // 2: about 75kbps
// // 3: about 39kbps
// // 4: about 26kbps
// // 5: about 20kbps
//
// //// USE simple API (using signle-type transaction function)
// /* nothing */
// //// USE flexible API (using multi-type transaction function)
// #define SERIAL_USE_MULTI_TRANSACTION
//
// /////////////////////////////////////////////////////////////////
// Soft Serial Transaction Descriptor
typedef struct _SSTD_t {
uint8_t *status;
uint8_t initiator2target_buffer_size;
uint8_t *initiator2target_buffer;
uint8_t target2initiator_buffer_size;
uint8_t *target2initiator_buffer;
} SSTD_t;
#define TID_LIMIT(table) (sizeof(table) / sizeof(SSTD_t))
// initiator is transaction start side
void soft_serial_initiator_init(SSTD_t *sstd_table, int sstd_table_size);
// target is interrupt accept side
void soft_serial_target_init(SSTD_t *sstd_table, int sstd_table_size);
// initiator result
#define TRANSACTION_END 0
#define TRANSACTION_NO_RESPONSE 0x1
#define TRANSACTION_DATA_ERROR 0x2
#define TRANSACTION_TYPE_ERROR 0x4
#ifndef SERIAL_USE_MULTI_TRANSACTION
int soft_serial_transaction(void);
#else
int soft_serial_transaction(int sstd_index);
#endif
// target status
// *SSTD_t.status has
// initiator:
// TRANSACTION_END
// or TRANSACTION_NO_RESPONSE
// or TRANSACTION_DATA_ERROR
// target:
// TRANSACTION_DATA_ERROR
// or TRANSACTION_ACCEPTED
#define TRANSACTION_ACCEPTED 0x8
#ifdef SERIAL_USE_MULTI_TRANSACTION
int soft_serial_get_and_clean_status(int sstd_index);
#endif

208
drivers/chibios/serial_usart.c
View file

@ -1,208 +0,0 @@
/* Copyright 2021 QMK
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#include "serial_usart.h"
#ifndef USE_GPIOV1
// The default PAL alternate modes are used to signal that the pins are used for USART
# ifndef SERIAL_USART_TX_PAL_MODE
# define SERIAL_USART_TX_PAL_MODE 7
# endif
#endif
#ifndef SERIAL_USART_DRIVER
# define SERIAL_USART_DRIVER SD1
#endif
#ifdef SOFT_SERIAL_PIN
# define SERIAL_USART_TX_PIN SOFT_SERIAL_PIN
#endif
static inline msg_t sdWriteHalfDuplex(SerialDriver* driver, uint8_t* data, uint8_t size) {
msg_t ret = sdWrite(driver, data, size);
// Half duplex requires us to read back the data we just wrote - just throw it away
uint8_t dump[size];
sdRead(driver, dump, size);
return ret;
}
#undef sdWrite
#define sdWrite sdWriteHalfDuplex
static inline msg_t sdWriteTimeoutHalfDuplex(SerialDriver* driver, uint8_t* data, uint8_t size, uint32_t timeout) {
msg_t ret = sdWriteTimeout(driver, data, size, timeout);
// Half duplex requires us to read back the data we just wrote - just throw it away
uint8_t dump[size];
sdReadTimeout(driver, dump, size, timeout);
return ret;
}
#undef sdWriteTimeout
#define sdWriteTimeout sdWriteTimeoutHalfDuplex
static inline void sdClear(SerialDriver* driver) {
while (sdGetTimeout(driver, TIME_IMMEDIATE) != MSG_TIMEOUT) {
// Do nothing with the data
}
}
static SerialConfig sdcfg = {
(SERIAL_USART_SPEED), // speed - mandatory
(SERIAL_USART_CR1), // CR1
(SERIAL_USART_CR2), // CR2
(SERIAL_USART_CR3) // CR3
};
void handle_soft_serial_slave(void);
/*
* This thread runs on the slave and responds to transactions initiated
* by the master
*/
static THD_WORKING_AREA(waSlaveThread, 2048);
static THD_FUNCTION(SlaveThread, arg) {
(void)arg;
chRegSetThreadName("slave_transport");
while (true) {
handle_soft_serial_slave();
}
}
__attribute__((weak)) void usart_init(void) {
#if defined(USE_GPIOV1)
palSetLineMode(SERIAL_USART_TX_PIN, PAL_MODE_STM32_ALTERNATE_OPENDRAIN);
#else
palSetLineMode(SERIAL_USART_TX_PIN, PAL_MODE_ALTERNATE(SERIAL_USART_TX_PAL_MODE) | PAL_STM32_OTYPE_OPENDRAIN);
#endif
#if defined(USART_REMAP)
USART_REMAP;
#endif
}
void usart_master_init(void) {
usart_init();
sdcfg.cr3 |= USART_CR3_HDSEL;
sdStart(&SERIAL_USART_DRIVER, &sdcfg);
}
void usart_slave_init(void) {
usart_init();
sdcfg.cr3 |= USART_CR3_HDSEL;
sdStart(&SERIAL_USART_DRIVER, &sdcfg);
// Start transport thread
chThdCreateStatic(waSlaveThread, sizeof(waSlaveThread), HIGHPRIO, SlaveThread, NULL);
}
static SSTD_t* Transaction_table = NULL;
static uint8_t Transaction_table_size = 0;
void soft_serial_initiator_init(SSTD_t* sstd_table, int sstd_table_size) {
Transaction_table = sstd_table;
Transaction_table_size = (uint8_t)sstd_table_size;
usart_master_init();
}
void soft_serial_target_init(SSTD_t* sstd_table, int sstd_table_size) {
Transaction_table = sstd_table;
Transaction_table_size = (uint8_t)sstd_table_size;
usart_slave_init();
}
void handle_soft_serial_slave(void) {
uint8_t sstd_index = sdGet(&SERIAL_USART_DRIVER); // first chunk is always transaction id
SSTD_t* trans = &Transaction_table[sstd_index];
// Always write back the sstd_index as part of a basic handshake
sstd_index ^= HANDSHAKE_MAGIC;
sdWrite(&SERIAL_USART_DRIVER, &sstd_index, sizeof(sstd_index));
if (trans->initiator2target_buffer_size) {
sdRead(&SERIAL_USART_DRIVER, trans->initiator2target_buffer, trans->initiator2target_buffer_size);
}
if (trans->target2initiator_buffer_size) {
sdWrite(&SERIAL_USART_DRIVER, trans->target2initiator_buffer, trans->target2initiator_buffer_size);
}
if (trans->status) {
*trans->status = TRANSACTION_ACCEPTED;
}
}
/////////
// start transaction by initiator
//
// int soft_serial_transaction(int sstd_index)
//
// Returns:
// TRANSACTION_END
// TRANSACTION_NO_RESPONSE
// TRANSACTION_DATA_ERROR
#ifndef SERIAL_USE_MULTI_TRANSACTION
int soft_serial_transaction(void) {
uint8_t sstd_index = 0;
#else
int soft_serial_transaction(int index) {
uint8_t sstd_index = index;
#endif
if (sstd_index > Transaction_table_size) return TRANSACTION_TYPE_ERROR;
SSTD_t* trans = &Transaction_table[sstd_index];
msg_t res = 0;
sdClear(&SERIAL_USART_DRIVER);
// First chunk is always transaction id
sdWriteTimeout(&SERIAL_USART_DRIVER, &sstd_index, sizeof(sstd_index), TIME_MS2I(SERIAL_USART_TIMEOUT));
uint8_t sstd_index_shake = 0xFF;
// Which we always read back first so that we can error out correctly
// - due to the half duplex limitations on return codes, we always have to read *something*
// - without the read, write only transactions *always* succeed, even during the boot process where the slave is not ready
res = sdReadTimeout(&SERIAL_USART_DRIVER, &sstd_index_shake, sizeof(sstd_index_shake), TIME_MS2I(SERIAL_USART_TIMEOUT));
if (res < 0 || (sstd_index_shake != (sstd_index ^ HANDSHAKE_MAGIC))) {
dprintf("serial::usart_shake NO_RESPONSE\n");
return TRANSACTION_NO_RESPONSE;
}
if (trans->initiator2target_buffer_size) {
res = sdWriteTimeout(&SERIAL_USART_DRIVER, trans->initiator2target_buffer, trans->initiator2target_buffer_size, TIME_MS2I(SERIAL_USART_TIMEOUT));
if (res < 0) {
dprintf("serial::usart_transmit NO_RESPONSE\n");
return TRANSACTION_NO_RESPONSE;
}
}
if (trans->target2initiator_buffer_size) {
res = sdReadTimeout(&SERIAL_USART_DRIVER, trans->target2initiator_buffer, trans->target2initiator_buffer_size, TIME_MS2I(SERIAL_USART_TIMEOUT));
if (res < 0) {
dprintf("serial::usart_receive NO_RESPONSE\n");
return TRANSACTION_NO_RESPONSE;
}
}
return TRANSACTION_END;
}

261
drivers/chibios/serial_usart_duplex.c
View file

@ -1,261 +0,0 @@
/* Copyright 2021 QMK
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#include "serial_usart.h"
#include <stdatomic.h>
#if !defined(USE_GPIOV1)
// The default PAL alternate modes are used to signal that the pins are used for USART
# if !defined(SERIAL_USART_TX_PAL_MODE)
# define SERIAL_USART_TX_PAL_MODE 7
# endif
# if !defined(SERIAL_USART_RX_PAL_MODE)
# define SERIAL_USART_RX_PAL_MODE 7
# endif
#endif
#if !defined(SERIAL_USART_DRIVER)
# define SERIAL_USART_DRIVER UARTD1
#endif
#if !defined(SERIAL_USART_TX_PIN)
# define SERIAL_USART_TX_PIN A9
#endif
#if !defined(SERIAL_USART_RX_PIN)
# define SERIAL_USART_RX_PIN A10
#endif
#define SIGNAL_HANDSHAKE_RECEIVED 0x1
void handle_transactions_slave(uint8_t sstd_index);
static void receive_transaction_handshake(UARTDriver* uartp, uint16_t received_handshake);
/*
* UART driver configuration structure. We use the blocking DMA enabled API and
* the rxchar callback to receive handshake tokens but only on the slave halve.
*/
// clang-format off
static UARTConfig uart_config = {
.txend1_cb = NULL,
.txend2_cb = NULL,
.rxend_cb = NULL,
.rxchar_cb = NULL,
.rxerr_cb = NULL,
.timeout_cb = NULL,
.speed = (SERIAL_USART_SPEED),
.cr1 = (SERIAL_USART_CR1),
.cr2 = (SERIAL_USART_CR2),
.cr3 = (SERIAL_USART_CR3)
};
// clang-format on
static SSTD_t* Transaction_table = NULL;
static uint8_t Transaction_table_size = 0;
static atomic_uint_least8_t handshake = 0xFF;
static thread_reference_t tp_target = NULL;
/*
* This callback is invoked when a character is received but the application
* was not ready to receive it, the character is passed as parameter.
* Receive transaction table index from initiator, which doubles as basic handshake token. */
static void receive_transaction_handshake(UARTDriver* uartp, uint16_t received_handshake) {
/* Check if received handshake is not a valid transaction id.
* Please note that we can still catch a seemingly valid handshake
* i.e. a byte from a ongoing transfer which is in the allowed range.
* So this check mainly prevents any obviously wrong handshakes and
* subsequent wakeups of the receiving thread, which is a costly operation. */
if (received_handshake > Transaction_table_size) {
return;
}
handshake = (uint8_t)received_handshake;
chSysLockFromISR();
/* Wakeup receiving thread to start a transaction. */
chEvtSignalI(tp_target, (eventmask_t)SIGNAL_HANDSHAKE_RECEIVED);
chSysUnlockFromISR();
}
__attribute__((weak)) void usart_init(void) {
#if defined(USE_GPIOV1)
palSetLineMode(SERIAL_USART_TX_PIN, PAL_MODE_STM32_ALTERNATE_PUSHPULL);
palSetLineMode(SERIAL_USART_RX_PIN, PAL_MODE_INPUT);
#else
palSetLineMode(SERIAL_USART_TX_PIN, PAL_MODE_ALTERNATE(SERIAL_USART_TX_PAL_MODE) | PAL_STM32_OTYPE_PUSHPULL | PAL_STM32_OSPEED_HIGHEST);
palSetLineMode(SERIAL_USART_RX_PIN, PAL_MODE_ALTERNATE(SERIAL_USART_RX_PAL_MODE) | PAL_STM32_OTYPE_PUSHPULL | PAL_STM32_OSPEED_HIGHEST);
#endif
}
/*
* This thread runs on the slave half and reacts to transactions initiated from the master.
*/
static THD_WORKING_AREA(waSlaveThread, 1024);
static THD_FUNCTION(SlaveThread, arg) {
(void)arg;
chRegSetThreadName("slave_usart_tx_rx");
while (true) {
/* We sleep as long as there is no handshake waiting for us. */
chEvtWaitAny((eventmask_t)SIGNAL_HANDSHAKE_RECEIVED);
handle_transactions_slave(handshake);
}
}
void soft_serial_target_init(SSTD_t* const sstd_table, int sstd_table_size) {
Transaction_table = sstd_table;
Transaction_table_size = (uint8_t)sstd_table_size;
usart_init();
#if defined(USART_REMAP)
USART_REMAP;
#endif
tp_target = chThdCreateStatic(waSlaveThread, sizeof(waSlaveThread), HIGHPRIO, SlaveThread, NULL);
// Start receiving handshake tokens on slave halve
uart_config.rxchar_cb = receive_transaction_handshake;
uartStart(&SERIAL_USART_DRIVER, &uart_config);
}
/**
* @brief React to transactions started by the master.
* This version uses duplex send and receive usart pheriphals and DMA backed transfers.
*/
void inline handle_transactions_slave(uint8_t sstd_index) {
size_t buffer_size = 0;
msg_t msg = 0;
SSTD_t* trans = &Transaction_table[sstd_index];
/* Send back the handshake which is XORed as a simple checksum,
to signal that the slave is ready to receive possible transaction buffers */
sstd_index ^= HANDSHAKE_MAGIC;
buffer_size = (size_t)sizeof(sstd_index);
msg = uartSendTimeout(&SERIAL_USART_DRIVER, &buffer_size, &sstd_index, TIME_MS2I(SERIAL_USART_TIMEOUT));
if (msg != MSG_OK) {
if (trans->status) {
*trans->status = TRANSACTION_NO_RESPONSE;
}
return;
}
/* Receive transaction buffer from the master. If this transaction requires it.*/
buffer_size = (size_t)trans->initiator2target_buffer_size;
if (buffer_size) {
msg = uartReceiveTimeout(&SERIAL_USART_DRIVER, &buffer_size, trans->initiator2target_buffer, TIME_MS2I(SERIAL_USART_TIMEOUT));
if (msg != MSG_OK) {
if (trans->status) {
*trans->status = TRANSACTION_NO_RESPONSE;
}
return;
}
}
/* Send transaction buffer to the master. If this transaction requires it. */
buffer_size = (size_t)trans->target2initiator_buffer_size;
if (buffer_size) {
msg = uartSendFullTimeout(&SERIAL_USART_DRIVER, &buffer_size, trans->target2initiator_buffer, TIME_MS2I(SERIAL_USART_TIMEOUT));
if (msg != MSG_OK) {
if (trans->status) {
*trans->status = TRANSACTION_NO_RESPONSE;
}
return;
}
}
if (trans->status) {
*trans->status = TRANSACTION_ACCEPTED;
}
}
void soft_serial_initiator_init(SSTD_t* const sstd_table, int sstd_table_size) {
Transaction_table = sstd_table;
Transaction_table_size = (uint8_t)sstd_table_size;
usart_init();
#if defined(SERIAL_USART_PIN_SWAP)
uart_config.cr2 |= USART_CR2_SWAP; // master has swapped TX/RX pins
#endif
#if defined(USART_REMAP)
USART_REMAP;
#endif
uartStart(&SERIAL_USART_DRIVER, &uart_config);
}
/**
* @brief Start transaction from the master to the slave.
* This version uses duplex send and receive usart pheriphals and DMA backed transfers.
*
* @param index Transaction Table index of the transaction to start.
* @return int TRANSACTION_NO_RESPONSE in case of Timeout.
* TRANSACTION_TYPE_ERROR in case of invalid transaction index.
* TRANSACTION_END in case of success.
*/
#if !defined(SERIAL_USE_MULTI_TRANSACTION)
int soft_serial_transaction(void) {
uint8_t sstd_index = 0;
#else
int soft_serial_transaction(int index) {
uint8_t sstd_index = index;
#endif
if (sstd_index > Transaction_table_size) {
return TRANSACTION_TYPE_ERROR;
}
SSTD_t* const trans = &Transaction_table[sstd_index];
msg_t msg = 0;
size_t buffer_size = (size_t)sizeof(sstd_index);
/* Send transaction table index to the slave, which doubles as basic handshake token. */
uartSendFullTimeout(&SERIAL_USART_DRIVER, &buffer_size, &sstd_index, TIME_MS2I(SERIAL_USART_TIMEOUT));
uint8_t sstd_index_shake = 0xFF;
buffer_size = (size_t)sizeof(sstd_index_shake);
/* Receive the handshake token from the slave. The token was XORed by the slave as a simple checksum.
If the tokens match, the master will start to send and receive possible transaction buffers. */
msg = uartReceiveTimeout(&SERIAL_USART_DRIVER, &buffer_size, &sstd_index_shake, TIME_MS2I(SERIAL_USART_TIMEOUT));
if (msg != MSG_OK || (sstd_index_shake != (sstd_index ^ HANDSHAKE_MAGIC))) {
dprintln("USART: Handshake Failed");
return TRANSACTION_NO_RESPONSE;
}
/* Send transaction buffer to the slave. If this transaction requires it. */
buffer_size = (size_t)trans->initiator2target_buffer_size;
if (buffer_size) {
msg = uartSendFullTimeout(&SERIAL_USART_DRIVER, &buffer_size, trans->initiator2target_buffer, TIME_MS2I(SERIAL_USART_TIMEOUT));
if (msg != MSG_OK) {
dprintln("USART: Send Failed");
return TRANSACTION_NO_RESPONSE;
}
}
/* Receive transaction buffer from the slave. If this transaction requires it. */
buffer_size = (size_t)trans->target2initiator_buffer_size;
if (buffer_size) {
msg = uartReceiveTimeout(&SERIAL_USART_DRIVER, &buffer_size, trans->target2initiator_buffer, TIME_MS2I(SERIAL_USART_TIMEOUT));
if (msg != MSG_OK) {
dprintln("USART: Receive Failed");
return TRANSACTION_NO_RESPONSE;
}
}
return TRANSACTION_END;
}

23
drivers/eeprom/eeprom_i2c.c
View file

@ -16,6 +16,9 @@
#include <stdint.h>
#include <string.h>
#if defined(EXTERNAL_EEPROM_WP_PIN)
# include "gpio.h"
#endif
/*
Note that the implementations of eeprom_XXXX_YYYY on AVR are normally
@ -50,7 +53,14 @@ static inline void fill_target_address(uint8_t *buffer, const void *addr) {
}
}
void eeprom_driver_init(void) { i2c_init(); }
void eeprom_driver_init(void) {
i2c_init();
#if defined(EXTERNAL_EEPROM_WP_PIN)
/* We are setting the WP pin to high in a way that requires at least two bit-flips to change back to 0 */
writePin(EXTERNAL_EEPROM_WP_PIN, 1);
setPinInputHigh(EXTERNAL_EEPROM_WP_PIN);
#endif
}
void eeprom_driver_erase(void) {
#if defined(CONSOLE_ENABLE) && defined(DEBUG_EEPROM_OUTPUT)
@ -89,6 +99,11 @@ void eeprom_write_block(const void *buf, void *addr, size_t len) {
uint8_t * read_buf = (uint8_t *)buf;
uintptr_t target_addr = (uintptr_t)addr;
#if defined(EXTERNAL_EEPROM_WP_PIN)
setPinOutput(EXTERNAL_EEPROM_WP_PIN);
writePin(EXTERNAL_EEPROM_WP_PIN, 0);
#endif
while (len > 0) {
uintptr_t page_offset = target_addr % EXTERNAL_EEPROM_PAGE_SIZE;
int write_length = EXTERNAL_EEPROM_PAGE_SIZE - page_offset;
@ -116,4 +131,10 @@ void eeprom_write_block(const void *buf, void *addr, size_t len) {
target_addr += write_length;
len -= write_length;
}
#if defined(EXTERNAL_EEPROM_WP_PIN)
/* We are setting the WP pin to high in a way that requires at least two bit-flips to change back to 0 */
writePin(EXTERNAL_EEPROM_WP_PIN, 1);
setPinInputHigh(EXTERNAL_EEPROM_WP_PIN);
#endif
}

7
drivers/eeprom/eeprom_spi.c
View file

@ -31,6 +31,8 @@
*/
#include "wait.h"
#include "debug.h"
#include "timer.h"
#include "spi_master.h"
#include "eeprom.h"
#include "eeprom_spi.h"
@ -50,11 +52,6 @@
# define EXTERNAL_EEPROM_SPI_TIMEOUT 100
#endif
#if defined(CONSOLE_ENABLE) && defined(DEBUG_EEPROM_OUTPUT)
# include "timer.h"
# include "debug.h"
#endif // CONSOLE_ENABLE
static bool spi_eeprom_start(void) { return spi_start(EXTERNAL_EEPROM_SPI_SLAVE_SELECT_PIN, EXTERNAL_EEPROM_SPI_LSBFIRST, EXTERNAL_EEPROM_SPI_MODE, EXTERNAL_EEPROM_SPI_CLOCK_DIVISOR); }
static spi_status_t spi_eeprom_wait_while_busy(int timeout) {

1
drivers/haptic/solenoid.c
View file

@ -18,6 +18,7 @@
#include "timer.h"
#include "solenoid.h"
#include "haptic.h"
#include "gpio.h"
bool solenoid_on = false;
bool solenoid_buzzing = false;

496
drivers/lcd/st7565.c Normal file
View file

@ -0,0 +1,496 @@
/*
Copyright 2021
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#include "st7565.h"
#include <string.h>
#include "keyboard.h"
#include "progmem.h"
#include "timer.h"
#include "wait.h"
#include ST7565_FONT_H
// Fundamental Commands
#define CONTRAST 0x81
#define DISPLAY_ALL_ON 0xA5
#define DISPLAY_ALL_ON_RESUME 0xA4
#define NORMAL_DISPLAY 0xA6
#define INVERT_DISPLAY 0xA7
#define DISPLAY_ON 0xAF
#define DISPLAY_OFF 0xAE
#define NOP 0xE3
// Addressing Setting Commands
#define PAM_SETCOLUMN_LSB 0x00
#define PAM_SETCOLUMN_MSB 0x10
#define PAM_PAGE_ADDR 0xB0 // 0xb0 -- 0xb7
// Hardware Configuration Commands
#define DISPLAY_START_LINE 0x40
#define SEGMENT_REMAP 0xA0
#define SEGMENT_REMAP_INV 0xA1
#define COM_SCAN_INC 0xC0
#define COM_SCAN_DEC 0xC8
#define LCD_BIAS_7 0xA3
#define LCD_BIAS_9 0xA2
#define RESISTOR_RATIO 0x20
#define POWER_CONTROL 0x28
// Misc defines
#ifndef ST7565_BLOCK_COUNT
# define ST7565_BLOCK_COUNT (sizeof(ST7565_BLOCK_TYPE) * 8)
#endif
#ifndef ST7565_BLOCK_SIZE
# define ST7565_BLOCK_SIZE (ST7565_MATRIX_SIZE / ST7565_BLOCK_COUNT)
#endif
#define ST7565_ALL_BLOCKS_MASK (((((ST7565_BLOCK_TYPE)1 << (ST7565_BLOCK_COUNT - 1)) - 1) << 1) | 1)
#define HAS_FLAGS(bits, flags) ((bits & flags) == flags)
// Display buffer's is the same as the display memory layout
// this is so we don't end up with rounding errors with
// parts of the display unusable or don't get cleared correctly
// and also allows for drawing & inverting
uint8_t st7565_buffer[ST7565_MATRIX_SIZE];
uint8_t * st7565_cursor;
ST7565_BLOCK_TYPE st7565_dirty = 0;
bool st7565_initialized = false;
bool st7565_active = false;
bool st7565_inverted = false;
display_rotation_t st7565_rotation = DISPLAY_ROTATION_0;
#if ST7565_TIMEOUT > 0
uint32_t st7565_timeout;
#endif
#if ST7565_UPDATE_INTERVAL > 0
uint16_t st7565_update_timeout;
#endif
// Flips the rendering bits for a character at the current cursor position
static void InvertCharacter(uint8_t *cursor) {
const uint8_t *end = cursor + ST7565_FONT_WIDTH;
while (cursor < end) {
*cursor = ~(*cursor);
cursor++;
}
}
bool st7565_init(display_rotation_t rotation) {
setPinOutput(ST7565_A0_PIN);
writePinHigh(ST7565_A0_PIN);
setPinOutput(ST7565_RST_PIN);
writePinHigh(ST7565_RST_PIN);
st7565_rotation = st7565_init_user(rotation);
spi_init();
spi_start(ST7565_SS_PIN, false, 0, ST7565_SPI_CLK_DIVISOR);
st7565_reset();
st7565_send_cmd(LCD_BIAS_7);
if (!HAS_FLAGS(st7565_rotation, DISPLAY_ROTATION_180)) {
st7565_send_cmd(SEGMENT_REMAP);
st7565_send_cmd(COM_SCAN_DEC);
} else {
st7565_send_cmd(SEGMENT_REMAP_INV);
st7565_send_cmd(COM_SCAN_INC);
}
st7565_send_cmd(DISPLAY_START_LINE | 0x00);
st7565_send_cmd(CONTRAST);
st7565_send_cmd(ST7565_CONTRAST);
st7565_send_cmd(RESISTOR_RATIO | 0x01);
st7565_send_cmd(POWER_CONTROL | 0x04);
wait_ms(50);
st7565_send_cmd(POWER_CONTROL | 0x06);
wait_ms(50);
st7565_send_cmd(POWER_CONTROL | 0x07);
wait_ms(10);
st7565_send_cmd(DISPLAY_ON);
st7565_send_cmd(DISPLAY_ALL_ON_RESUME);
st7565_send_cmd(NORMAL_DISPLAY);
spi_stop();
#if ST7565_TIMEOUT > 0
st7565_timeout = timer_read32() + ST7565_TIMEOUT;
#endif
st7565_clear();
st7565_initialized = true;
st7565_active = true;
return true;
}
__attribute__((weak)) display_rotation_t st7565_init_user(display_rotation_t rotation) { return rotation; }
void st7565_clear(void) {
memset(st7565_buffer, 0, sizeof(st7565_buffer));
st7565_cursor = &st7565_buffer[0];
st7565_dirty = ST7565_ALL_BLOCKS_MASK;
}
uint8_t crot(uint8_t a, int8_t n) {
const uint8_t mask = 0x7;
n &= mask;
return a << n | a >> (-n & mask);
}
void st7565_render(void) {
if (!st7565_initialized) {
return;
}
// Do we have work to do?
st7565_dirty &= ST7565_ALL_BLOCKS_MASK;
if (!st7565_dirty) {
return;
}
// Find first dirty block
uint8_t update_start = 0;
while (!(st7565_dirty & ((ST7565_BLOCK_TYPE)1 << update_start))) {
++update_start;
}
// Calculate commands to set memory addressing bounds.
uint8_t start_page = ST7565_BLOCK_SIZE * update_start / ST7565_DISPLAY_WIDTH;
uint8_t start_column = ST7565_BLOCK_SIZE * update_start % ST7565_DISPLAY_WIDTH;
// IC has 132 segment drivers, for panels with less width we need to offset the starting column
if (HAS_FLAGS(st7565_rotation, DISPLAY_ROTATION_180)) {
start_column += (132 - ST7565_DISPLAY_WIDTH);
}
spi_start(ST7565_SS_PIN, false, 0, ST7565_SPI_CLK_DIVISOR);
st7565_send_cmd(PAM_PAGE_ADDR | start_page);
st7565_send_cmd(PAM_SETCOLUMN_LSB | ((ST7565_COLUMN_OFFSET + start_column) & 0x0f));
st7565_send_cmd(PAM_SETCOLUMN_MSB | ((ST7565_COLUMN_OFFSET + start_column) >> 4 & 0x0f));
st7565_send_data(&st7565_buffer[ST7565_BLOCK_SIZE * update_start], ST7565_BLOCK_SIZE);
// Turn on display if it is off
st7565_on();
// Clear dirty flag
st7565_dirty &= ~((ST7565_BLOCK_TYPE)1 << update_start);
}
void st7565_set_cursor(uint8_t col, uint8_t line) {
uint16_t index = line * ST7565_DISPLAY_WIDTH + col * ST7565_FONT_WIDTH;
// Out of bounds?
if (index >= ST7565_MATRIX_SIZE) {
index = 0;
}
st7565_cursor = &st7565_buffer[index];
}
void st7565_advance_page(bool clearPageRemainder) {
uint16_t index = st7565_cursor - &st7565_buffer[0];
uint8_t remaining = ST7565_DISPLAY_WIDTH - (index % ST7565_DISPLAY_WIDTH);
if (clearPageRemainder) {
// Remaining Char count
remaining = remaining / ST7565_FONT_WIDTH;
// Write empty character until next line
while (remaining--) st7565_write_char(' ', false);
} else {
// Next page index out of bounds?
if (index + remaining >= ST7565_MATRIX_SIZE) {
index = 0;
remaining = 0;
}
st7565_cursor = &st7565_buffer[index + remaining];
}
}
void st7565_advance_char(void) {
uint16_t nextIndex = st7565_cursor - &st7565_buffer[0] + ST7565_FONT_WIDTH;
uint8_t remainingSpace = ST7565_DISPLAY_WIDTH - (nextIndex % ST7565_DISPLAY_WIDTH);
// Do we have enough space on the current line for the next character
if (remainingSpace < ST7565_FONT_WIDTH) {
nextIndex += remainingSpace;
}
// Did we go out of bounds
if (nextIndex >= ST7565_MATRIX_SIZE) {
nextIndex = 0;
}
// Update cursor position
st7565_cursor = &st7565_buffer[nextIndex];
}
// Main handler that writes character data to the display buffer
void st7565_write_char(const char data, bool invert) {
// Advance to the next line if newline
if (data == '\n') {
// Old source wrote ' ' until end of line...
st7565_advance_page(true);
return;
}
if (data == '\r') {
st7565_advance_page(false);
return;
}
// copy the current render buffer to check for dirty after
static uint8_t st7565_temp_buffer[ST7565_FONT_WIDTH];
memcpy(&st7565_temp_buffer, st7565_cursor, ST7565_FONT_WIDTH);
_Static_assert(sizeof(font) >= ((ST7565_FONT_END + 1 - ST7565_FONT_START) * ST7565_FONT_WIDTH), "ST7565_FONT_END references outside array");
// set the reder buffer data
uint8_t cast_data = (uint8_t)data; // font based on unsigned type for index
if (cast_data < ST7565_FONT_START || cast_data > ST7565_FONT_END) {
memset(st7565_cursor, 0x00, ST7565_FONT_WIDTH);
} else {
const uint8_t *glyph = &font[(cast_data - ST7565_FONT_START) * ST7565_FONT_WIDTH];
memcpy_P(st7565_cursor, glyph, ST7565_FONT_WIDTH);
}
// Invert if needed
if (invert) {
InvertCharacter(st7565_cursor);
}
// Dirty check
if (memcmp(&st7565_temp_buffer, st7565_cursor, ST7565_FONT_WIDTH)) {
uint16_t index = st7565_cursor - &st7565_buffer[0];
st7565_dirty |= ((ST7565_BLOCK_TYPE)1 << (index / ST7565_BLOCK_SIZE));
// Edgecase check if the written data spans the 2 chunks
st7565_dirty |= ((ST7565_BLOCK_TYPE)1 << ((index + ST7565_FONT_WIDTH - 1) / ST7565_BLOCK_SIZE));
}
// Finally move to the next char
st7565_advance_char();
}
void st7565_write(const char *data, bool invert) {
const char *end = data + strlen(data);
while (data < end) {
st7565_write_char(*data, invert);
data++;
}
}
void st7565_write_ln(const char *data, bool invert) {
st7565_write(data, invert);
st7565_advance_page(true);
}
void st7565_pan(bool left) {
uint16_t i = 0;
for (uint16_t y = 0; y < ST7565_DISPLAY_HEIGHT / 8; y++) {
if (left) {
for (uint16_t x = 0; x < ST7565_DISPLAY_WIDTH - 1; x++) {
i = y * ST7565_DISPLAY_WIDTH + x;
st7565_buffer[i] = st7565_buffer[i + 1];
}
} else {
for (uint16_t x = ST7565_DISPLAY_WIDTH - 1; x > 0; x--) {
i = y * ST7565_DISPLAY_WIDTH + x;
st7565_buffer[i] = st7565_buffer[i - 1];
}
}
}
st7565_dirty = ST7565_ALL_BLOCKS_MASK;
}
display_buffer_reader_t st7565_read_raw(uint16_t start_index) {
if (start_index > ST7565_MATRIX_SIZE) start_index = ST7565_MATRIX_SIZE;
display_buffer_reader_t ret_reader;
ret_reader.current_element = &st7565_buffer[start_index];
ret_reader.remaining_element_count = ST7565_MATRIX_SIZE - start_index;
return ret_reader;
}
void st7565_write_raw_byte(const char data, uint16_t index) {
if (index > ST7565_MATRIX_SIZE) index = ST7565_MATRIX_SIZE;
if (st7565_buffer[index] == data) return;
st7565_buffer[index] = data;
st7565_dirty |= ((ST7565_BLOCK_TYPE)1 << (index / ST7565_BLOCK_SIZE));
}
void st7565_write_raw(const char *data, uint16_t size) {
uint16_t cursor_start_index = st7565_cursor - &st7565_buffer[0];
if ((size + cursor_start_index) > ST7565_MATRIX_SIZE) size = ST7565_MATRIX_SIZE - cursor_start_index;
for (uint16_t i = cursor_start_index; i < cursor_start_index + size; i++) {
uint8_t c = *data++;
if (st7565_buffer[i] == c) continue;
st7565_buffer[i] = c;
st7565_dirty |= ((ST7565_BLOCK_TYPE)1 << (i / ST7565_BLOCK_SIZE));
}
}
void st7565_write_pixel(uint8_t x, uint8_t y, bool on) {
if (x >= ST7565_DISPLAY_WIDTH) {
return;
}
uint16_t index = x + (y / 8) * ST7565_DISPLAY_WIDTH;
if (index >= ST7565_MATRIX_SIZE) {
return;
}
uint8_t data = st7565_buffer[index];
if (on) {
data |= (1 << (y % 8));
} else {
data &= ~(1 << (y % 8));
}
if (st7565_buffer[index] != data) {
st7565_buffer[index] = data;
st7565_dirty |= ((ST7565_BLOCK_TYPE)1 << (index / ST7565_BLOCK_SIZE));
}
}
#if defined(__AVR__)
void st7565_write_P(const char *data, bool invert) {
uint8_t c = pgm_read_byte(data);
while (c != 0) {
st7565_write_char(c, invert);
c = pgm_read_byte(++data);
}
}
void st7565_write_ln_P(const char *data, bool invert) {
st7565_write_P(data, invert);
st7565_advance_page(true);
}
void st7565_write_raw_P(const char *data, uint16_t size) {
uint16_t cursor_start_index = st7565_cursor - &st7565_buffer[0];
if ((size + cursor_start_index) > ST7565_MATRIX_SIZE) size = ST7565_MATRIX_SIZE - cursor_start_index;
for (uint16_t i = cursor_start_index; i < cursor_start_index + size; i++) {
uint8_t c = pgm_read_byte(data++);
if (st7565_buffer[i] == c) continue;
st7565_buffer[i] = c;
st7565_dirty |= ((ST7565_BLOCK_TYPE)1 << (i / ST7565_BLOCK_SIZE));
}
}
#endif // defined(__AVR__)
bool st7565_on(void) {
if (!st7565_initialized) {
return st7565_active;
}
#if ST7565_TIMEOUT > 0
st7565_timeout = timer_read32() + ST7565_TIMEOUT;
#endif
if (!st7565_active) {
spi_start(ST7565_SS_PIN, false, 0, ST7565_SPI_CLK_DIVISOR);
st7565_send_cmd(DISPLAY_ON);
spi_stop();
st7565_active = true;
st7565_on_user();
}
return st7565_active;
}
__attribute__((weak)) void st7565_on_user(void) {}
bool st7565_off(void) {
if (!st7565_initialized) {
return !st7565_active;
}
if (st7565_active) {
spi_start(ST7565_SS_PIN, false, 0, ST7565_SPI_CLK_DIVISOR);
st7565_send_cmd(DISPLAY_OFF);
spi_stop();
st7565_active = false;
st7565_off_user();
}
return !st7565_active;
}
__attribute__((weak)) void st7565_off_user(void) {}
bool st7565_is_on(void) { return st7565_active; }
bool st7565_invert(bool invert) {
if (!st7565_initialized) {
return st7565_inverted;
}
if (invert != st7565_inverted) {
spi_start(ST7565_SS_PIN, false, 0, ST7565_SPI_CLK_DIVISOR);
st7565_send_cmd(invert ? INVERT_DISPLAY : NORMAL_DISPLAY);
spi_stop();
st7565_inverted = invert;
}
return st7565_inverted;
}
uint8_t st7565_max_chars(void) { return ST7565_DISPLAY_WIDTH / ST7565_FONT_WIDTH; }
uint8_t st7565_max_lines(void) { return ST7565_DISPLAY_HEIGHT / ST7565_FONT_HEIGHT; }
void st7565_task(void) {
if (!st7565_initialized) {
return;
}
#if ST7565_UPDATE_INTERVAL > 0
if (timer_elapsed(st7565_update_timeout) >= ST7565_UPDATE_INTERVAL) {
st7565_update_timeout = timer_read();
st7565_set_cursor(0, 0);
st7565_task_user();
}
#else
st7565_set_cursor(0, 0);
st7565_task_user();
#endif
// Smart render system, no need to check for dirty
st7565_render();
// Display timeout check
#if ST7565_TIMEOUT > 0
if (st7565_active && timer_expired32(timer_read32(), st7565_timeout)) {
st7565_off();
}
#endif
}
__attribute__((weak)) void st7565_task_user(void) {}
void st7565_reset(void) {
writePinLow(ST7565_RST_PIN);
wait_ms(20);
writePinHigh(ST7565_RST_PIN);
wait_ms(20);
}
spi_status_t st7565_send_cmd(uint8_t cmd) {
writePinLow(ST7565_A0_PIN);
return spi_write(cmd);
}
spi_status_t st7565_send_data(uint8_t *data, uint16_t length) {
writePinHigh(ST7565_A0_PIN);
return spi_transmit(data, length);
}

219
drivers/lcd/st7565.h Normal file
View file

@ -0,0 +1,219 @@
/*
Copyright 2021
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#pragma once
#include <stdint.h>
#include <stdbool.h>
#include "spi_master.h"
#ifndef ST7565_DISPLAY_WIDTH
# define ST7565_DISPLAY_WIDTH 128
#endif
#ifndef ST7565_DISPLAY_HEIGHT
# define ST7565_DISPLAY_HEIGHT 32
#endif
#ifndef ST7565_MATRIX_SIZE
# define ST7565_MATRIX_SIZE (ST7565_DISPLAY_HEIGHT / 8 * ST7565_DISPLAY_WIDTH) // 1024 (compile time mathed)
#endif
#ifndef ST7565_BLOCK_TYPE
# define ST7565_BLOCK_TYPE uint16_t
#endif
#ifndef ST7565_BLOCK_COUNT
# define ST7565_BLOCK_COUNT (sizeof(ST7565_BLOCK_TYPE) * 8) // 32 (compile time mathed)
#endif
#ifndef ST7565_BLOCK_SIZE
# define ST7565_BLOCK_SIZE (ST7565_MATRIX_SIZE / ST7565_BLOCK_COUNT) // 32 (compile time mathed)
#endif
// the column address corresponding to the first column in the display hardware
#if !defined(ST7565_COLUMN_OFFSET)
# define ST7565_COLUMN_OFFSET 0
#endif
// spi clock divisor
#if !defined(ST7565_SPI_CLK_DIVISOR)
# define ST7565_SPI_CLK_DIVISOR 4
#endif
// Custom font file to use
#if !defined(ST7565_FONT_H)
# define ST7565_FONT_H "glcdfont.c"
#endif
// unsigned char value of the first character in the font file
#if !defined(ST7565_FONT_START)
# define ST7565_FONT_START 0
#endif
// unsigned char value of the last character in the font file
#if !defined(ST7565_FONT_END)
# define ST7565_FONT_END 223
#endif
// Font render width
#if !defined(ST7565_FONT_WIDTH)
# define ST7565_FONT_WIDTH 6
#endif
// Font render height
#if !defined(ST7565_FONT_HEIGHT)
# define ST7565_FONT_HEIGHT 8
#endif
// Default contrast level
#if !defined(ST7565_CONTRAST)
# define ST7565_CONTRAST 32
#endif
#if !defined(ST7565_TIMEOUT)
# if defined(ST7565_DISABLE_TIMEOUT)
# define ST7565_TIMEOUT 0
# else
# define ST7565_TIMEOUT 60000
# endif
#endif
#if !defined(ST7565_UPDATE_INTERVAL) && defined(SPLIT_KEYBOARD)
# define ST7565_UPDATE_INTERVAL 50
#endif
typedef struct __attribute__((__packed__)) {
uint8_t *current_element;
uint16_t remaining_element_count;
} display_buffer_reader_t;
// Rotation enum values are flags
typedef enum { DISPLAY_ROTATION_0, DISPLAY_ROTATION_180 } display_rotation_t;
// Initialize the display, rotating the rendered output based on the define passed in.
// Returns true if the display was initialized successfully
bool st7565_init(display_rotation_t rotation);
// Called at the start of st7565_init, weak function overridable by the user
// rotation - the value passed into st7565_init
// Return new display_rotation_t if you want to override default rotation
display_rotation_t st7565_init_user(display_rotation_t rotation);
// Clears the display buffer, resets cursor position to 0, and sets the buffer to dirty for rendering
void st7565_clear(void);
// Renders the dirty chunks of the buffer to display
void st7565_render(void);
// Moves cursor to character position indicated by column and line, wraps if out of bounds
// Max column denoted by 'st7565_max_chars()' and max lines by 'st7565_max_lines()' functions
void st7565_set_cursor(uint8_t col, uint8_t line);
// Advances the cursor to the next page, writing ' ' if true
// Wraps to the begining when out of bounds
void st7565_advance_page(bool clearPageRemainder);
// Moves the cursor forward 1 character length
// Advance page if there is not enough room for the next character
// Wraps to the begining when out of bounds
void st7565_advance_char(void);
// Writes a single character to the buffer at current cursor position
// Advances the cursor while writing, inverts the pixels if true
// Main handler that writes character data to the display buffer
void st7565_write_char(const char data, bool invert);
// Writes a string to the buffer at current cursor position
// Advances the cursor while writing, inverts the pixels if true
void st7565_write(const char *data, bool invert);
// Writes a string to the buffer at current cursor position
// Advances the cursor while writing, inverts the pixels if true
// Advances the cursor to the next page, wiring ' ' to the remainder of the current page
void st7565_write_ln(const char *data, bool invert);
// Pans the buffer to the right (or left by passing true) by moving contents of the buffer
// Useful for moving the screen in preparation for new drawing
void st7565_pan(bool left);
// Returns a pointer to the requested start index in the buffer plus remaining
// buffer length as struct
display_buffer_reader_t st7565_read_raw(uint16_t start_index);
// Writes a string to the buffer at current cursor position
void st7565_write_raw(const char *data, uint16_t size);
// Writes a single byte into the buffer at the specified index
void st7565_write_raw_byte(const char data, uint16_t index);
// Sets a specific pixel on or off
// Coordinates start at top-left and go right and down for positive x and y
void st7565_write_pixel(uint8_t x, uint8_t y, bool on);
#if defined(__AVR__)
// Writes a PROGMEM string to the buffer at current cursor position
// Advances the cursor while writing, inverts the pixels if true
// Remapped to call 'void st7565_write(const char *data, bool invert);' on ARM
void st7565_write_P(const char *data, bool invert);
// Writes a PROGMEM string to the buffer at current cursor position
// Advances the cursor while writing, inverts the pixels if true
// Advances the cursor to the next page, wiring ' ' to the remainder of the current page
// Remapped to call 'void st7565_write_ln(const char *data, bool invert);' on ARM
void st7565_write_ln_P(const char *data, bool invert);
// Writes a PROGMEM string to the buffer at current cursor position
void st7565_write_raw_P(const char *data, uint16_t size);
#else
# define st7565_write_P(data, invert) st7565_write(data, invert)
# define st7565_write_ln_P(data, invert) st7565_write_ln(data, invert)
# define st7565_write_raw_P(data, size) st7565_write_raw(data, size)
#endif // defined(__AVR__)
// Can be used to manually turn on the screen if it is off
// Returns true if the screen was on or turns on
bool st7565_on(void);
// Called when st7565_on() turns on the screen, weak function overridable by the user
// Not called if the screen is already on
void st7565_on_user(void);
// Can be used to manually turn off the screen if it is on
// Returns true if the screen was off or turns off
bool st7565_off(void);
// Called when st7565_off() turns off the screen, weak function overridable by the user
// Not called if the screen is already off
void st7565_off_user(void);
// Returns true if the screen is currently on, false if it is
// not
bool st7565_is_on(void);
// Basically it's st7565_render, but with timeout management and st7565_task_user calling!
void st7565_task(void);
// Called at the start of st7565_task, weak function overridable by the user
void st7565_task_user(void);
// Inverts the display
// Returns true if the screen was or is inverted
bool st7565_invert(bool invert);
// Returns the maximum number of characters that will fit on a line
uint8_t st7565_max_chars(void);
// Returns the maximum number of lines that will fit on the display
uint8_t st7565_max_lines(void);
void st7565_reset(void);
spi_status_t st7565_send_cmd(uint8_t cmd);
spi_status_t st7565_send_data(uint8_t *data, uint16_t length);

Some files were not shown because too many files have changed in this diff Show more