mkbd65/vial-qmk
Watch
1
0
Fork
You've already forked vial-qmk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge branch 'master' of https://github.com/qmk/qmk_firmware

Browse source
This commit is contained in:
Alex Ong 2019-01-04 19:39:14 +11:00
commit 47c91fc7f7
3911 changed files with 238889 additions and 26831 deletions
Download patch file Download diff file Expand all files Collapse all files

5
.github/ISSUE_TEMPLATE/blank.md vendored Normal file
View file

@ -0,0 +1,5 @@
---
name: Blank issue
about: If you're 100% sure that you don't need one of the other issue templates, use this one instead.
---

31
.github/ISSUE_TEMPLATE/bug_report.md vendored Normal file
View file

@ -0,0 +1,31 @@
---
name: Bug report
about: Create a report to help us improve the QMK Firmware
---
<!-- Provide a general summary of the bug in the Title above -->
<!-- This template is entirely option and can be removed, but is here to help both you and us. -->
<!-- This text and anything on lines wrapped like this one will not show up in the final text. This text is to help us and you. -->
**Describe the bug**
<!-- A clear and concise description of what the bug is. -->
**System Information**
- Keyboard:
- Revision (if applicable):
- Operating System:
- avr-gcc version:
<!-- Run `avr-gcc --version` to find out -->
- arm gcc version:
<!-- Run `arm-none-eabi-gcc --version` to find out -->
- QMK Firmware version:
<!-- You can run `git describe --abbrev=0 --tags` to find this out -->
- Any keyboard related software installed?
- [ ] Auto Hot Key
- [ ] Karabiner
- [ ] Other
**Additional context**
<!-- Add any other context about the problem here. -->

19
.github/ISSUE_TEMPLATE/feature_request.md vendored Normal file
View file

@ -0,0 +1,19 @@
---
name: Feature request
about: Suggest a new feature or changes to existing features
---
<!--- Provide a general summary of the changes you want in the Title above -->
<!-- This template is entirely option and can be removed, but is here to help both you and us. -->
<!-- This text and anything on lines wrapped like this one will not show up in the final text. This text is to help us and you. -->
## Feature Request Type
- [ ] Core Functionality
- [ ] Add-on hardware support (e.g. audio, RGB, OLED screen, etc.)
- [ ] Alteration (enhancement/optimization) of existing Feature(s)
- [ ] New behavior
## Description
<!-- A few sentences describing what it is that you'd like to see. Additional information (such as links to spec sheets, licensing info, other related issues or PR's, etc) would be helpful. -->

9
.github/ISSUE_TEMPLATE/other_issues.md vendored Normal file
View file

@ -0,0 +1,9 @@
---
name: Other issues
about: Anything else that doesn't fall into the above categories.
---
<!--- Provide a general summary of the changes you want in the Title above -->
<!-- This text and anything on lines wrapped like this one will not show up in the final text. This text is to help us and you. -->
<!-- Please check https://docs.qmk.fm/#/support for additional resources first. If that doesn't answer your question, check the bug report option, as that may be more appropriate. -->

32
.github/PULL_REQUEST_TEMPLATE.md vendored Normal file
View file

@ -0,0 +1,32 @@
<!--- Provide a general summary of your changes in the Title above -->
<!--- This template is entirely option and can be removed, but is here to help both you and us. -->
<!--- This text and anything on lines wrapped like this one will not show up in the final text. This text is to help us and you. -->
## Description
<!--- Describe your changes in detail -->
## Types of changes
<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
- [ ] Core
- [ ] Bugfix
- [ ] New Feature
- [ ] Enhancement/Optimization
- [ ] Keyboard (addition or update)
- [ ] Keymap/Layout/Userspace (addition or update)
- [ ] Documentation
## Issues Fixed or Closed by this PR
*
## Checklist:
<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
- [ ] My code follows the code style of this project.
- [ ] My change requires a change to the documentation.
- [ ] I have updated the documentation accordingly.
- [ ] I have read the **CONTRIBUTING** document. (https://docs.qmk.fm/#/contributing)
- [ ] I have added tests to cover my changes.
- [ ] I have tested the changes and verified that they work and don't break anything (as well as I can manage).

3
.travis.yml
View file

@ -19,6 +19,7 @@ install:
before_script:
- avr-gcc --version
script:
- git rev-parse --short HEAD
- make test:all AUTOGEN=false
- bash util/travis_build.sh
- bash util/travis_docs.sh
@ -33,7 +34,7 @@ addons:
- diffutils
- dos2unix
- doxygen
after_success:
after_success:
bash util/travis_compiled_push.sh
notifications:
webhooks:

41
Dockerfile
View file

@ -1,28 +1,29 @@
FROM debian:jessie
MAINTAINER Erik Dasque <erik@frenchguys.com>
FROM debian
RUN apt-get update && apt-get install --no-install-recommends -y build-essential \
RUN apt-get update && apt-get install --no-install-recommends -y \
avr-libc \
avrdude \
binutils-arm-none-eabi \
binutils-avr \
build-essential \
dfu-programmer \
dfu-util \
gcc \
gcc-arm-none-eabi \
gcc-avr \
git \
libnewlib-arm-none-eabi \
software-properties-common \
unzip \
wget \
zip \
gcc-avr \
binutils-avr \
avr-libc \
dfu-programmer \
dfu-util \
gcc-arm-none-eabi \
binutils-arm-none-eabi \
libnewlib-arm-none-eabi \
git \
software-properties-common \
avrdude \
&& rm -rf /var/lib/apt/lists/*
ENV keyboard=ergodox
ENV subproject=ez
ENV keymap=default
ENV KEYBOARD=ergodox_ez
ENV KEYMAP=default
VOLUME /qmk
WORKDIR /qmk
CMD make clean ; make keyboard=${keyboard} subproject=${subproject} keymap=${keymap}
VOLUME /qmk_firmware
WORKDIR /qmk_firmware
COPY . .
CMD make $KEYBOARD:$KEYMAP

2
Makefile
View file

@ -578,7 +578,7 @@ lib/%:
git-submodule:
git submodule sync --recursive
git submodule update --init --recursive
git submodule update --init --recursive --progress
ifdef SKIP_VERSION
SKIP_GIT := yes

2
Vagrantfile vendored
View file

@ -59,7 +59,7 @@ Vagrant.configure(2) do |config|
# add a # before ,args: and run 'vagrant up' to get a working
# non-updated box and then attempt to troubleshoot or open a Github issue
config.vm.provision "shell", run: "always", path: "./util/install_dependencies.sh", args: "-update"
config.vm.provision "shell", run: "always", path: "./util/qmk_install.sh", args: "-update"
config.vm.post_up_message = <<-EOT

117
build_keyboard.mk
View file

@ -1,3 +1,9 @@
# Determine what keyboard we are building and setup the build environment.
#
# We support folders up to 5 levels deep below `keyboards/`. This file is
# responsible for determining which folder is being used and doing the
# corresponding environment setup.
ifndef VERBOSE
.SILENT:
endif
@ -6,26 +12,15 @@ endif
include common.mk
# 5/4/3/2/1
KEYBOARD_FOLDER_PATH_1 := $(KEYBOARD)
KEYBOARD_FOLDER_PATH_2 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_1)))
KEYBOARD_FOLDER_PATH_3 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_2)))
KEYBOARD_FOLDER_PATH_4 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_3)))
KEYBOARD_FOLDER_PATH_5 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_4)))
KEYBOARD_FOLDER_1 := $(notdir $(KEYBOARD_FOLDER_PATH_1))
KEYBOARD_FOLDER_2 := $(notdir $(KEYBOARD_FOLDER_PATH_2))
KEYBOARD_FOLDER_3 := $(notdir $(KEYBOARD_FOLDER_PATH_3))
KEYBOARD_FOLDER_4 := $(notdir $(KEYBOARD_FOLDER_PATH_4))
KEYBOARD_FOLDER_5 := $(notdir $(KEYBOARD_FOLDER_PATH_5))
# Set the filename for the final firmware binary
KEYBOARD_FILESAFE := $(subst /,_,$(KEYBOARD))
TARGET ?= $(KEYBOARD_FILESAFE)_$(KEYMAP)
KEYBOARD_OUTPUT := $(BUILD_DIR)/obj_$(KEYBOARD_FILESAFE)
# Force expansion
TARGET := $(TARGET)
# For split boards we need to set a master half.
MASTER ?= left
ifdef master
MASTER = $(master)
@ -39,35 +34,62 @@ $(error MASTER does not have a valid value(left/right))
endif
endif
KEYBOARD_PATHS :=
ifdef SKIP_VERSION
OPT_DEFS += -DSKIP_VERSION
endif
# Determine which subfolders exist.
KEYBOARD_FOLDER_PATH_1 := $(KEYBOARD)
KEYBOARD_FOLDER_PATH_2 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_1)))
KEYBOARD_FOLDER_PATH_3 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_2)))
KEYBOARD_FOLDER_PATH_4 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_3)))
KEYBOARD_FOLDER_PATH_5 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_4)))
KEYBOARD_FOLDER_1 := $(notdir $(KEYBOARD_FOLDER_PATH_1))
KEYBOARD_FOLDER_2 := $(notdir $(KEYBOARD_FOLDER_PATH_2))
KEYBOARD_FOLDER_3 := $(notdir $(KEYBOARD_FOLDER_PATH_3))
KEYBOARD_FOLDER_4 := $(notdir $(KEYBOARD_FOLDER_PATH_4))
KEYBOARD_FOLDER_5 := $(notdir $(KEYBOARD_FOLDER_PATH_5))
KEYBOARD_PATHS :=
KEYBOARD_PATH_1 := keyboards/$(KEYBOARD_FOLDER_PATH_1)
KEYBOARD_PATH_2 := keyboards/$(KEYBOARD_FOLDER_PATH_2)
KEYBOARD_PATH_3 := keyboards/$(KEYBOARD_FOLDER_PATH_3)
KEYBOARD_PATH_4 := keyboards/$(KEYBOARD_FOLDER_PATH_4)
KEYBOARD_PATH_5 := keyboards/$(KEYBOARD_FOLDER_PATH_5)
ifneq ("$(wildcard $(KEYBOARD_PATH_5)/rules.mk)","")
ifneq ("$(wildcard $(KEYBOARD_PATH_5)/)","")
KEYBOARD_PATHS += $(KEYBOARD_PATH_5)
endif
ifneq ("$(wildcard $(KEYBOARD_PATH_4)/)","")
KEYBOARD_PATHS += $(KEYBOARD_PATH_4)
endif
ifneq ("$(wildcard $(KEYBOARD_PATH_3)/)","")
KEYBOARD_PATHS += $(KEYBOARD_PATH_3)
endif
ifneq ("$(wildcard $(KEYBOARD_PATH_2)/)","")
KEYBOARD_PATHS += $(KEYBOARD_PATH_2)
endif
ifneq ("$(wildcard $(KEYBOARD_PATH_1)/)","")
KEYBOARD_PATHS += $(KEYBOARD_PATH_1)
endif
# Pull in rules.mk files from all our subfolders
ifneq ("$(wildcard $(KEYBOARD_PATH_5)/rules.mk)","")
include $(KEYBOARD_PATH_5)/rules.mk
endif
ifneq ("$(wildcard $(KEYBOARD_PATH_4)/rules.mk)","")
KEYBOARD_PATHS += $(KEYBOARD_PATH_4)
include $(KEYBOARD_PATH_4)/rules.mk
endif
ifneq ("$(wildcard $(KEYBOARD_PATH_3)/rules.mk)","")
KEYBOARD_PATHS += $(KEYBOARD_PATH_3)
include $(KEYBOARD_PATH_3)/rules.mk
endif
ifneq ("$(wildcard $(KEYBOARD_PATH_2)/rules.mk)","")
KEYBOARD_PATHS += $(KEYBOARD_PATH_2)
include $(KEYBOARD_PATH_2)/rules.mk
endif
ifneq ("$(wildcard $(KEYBOARD_PATH_1)/rules.mk)","")
KEYBOARD_PATHS += $(KEYBOARD_PATH_1)
include $(KEYBOARD_PATH_1)/rules.mk
endif
# Find all the C source files to be compiled in subfolders.
KEYBOARD_SRC :=
KEYBOARD_C_1 := $(KEYBOARD_PATH_1)/$(KEYBOARD_FOLDER_1).c
@ -92,9 +114,38 @@ ifneq ("$(wildcard $(KEYBOARD_C_1))","")
KEYBOARD_SRC += $(KEYBOARD_C_1)
endif
OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE)
# Generate KEYBOARD_name_subname for all levels of the keyboard folder
KEYBOARD_FILESAFE_1 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_1)))
KEYBOARD_FILESAFE_2 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_2)))
KEYBOARD_FILESAFE_3 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_3)))
KEYBOARD_FILESAFE_4 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_4)))
KEYBOARD_FILESAFE_5 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_5)))
ifneq ("$(wildcard $(KEYBOARD_PATH_5)/)","")
OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_5)
endif
ifneq ("$(wildcard $(KEYBOARD_PATH_4)/)","")
OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_4)
endif
ifneq ("$(wildcard $(KEYBOARD_PATH_3)/)","")
OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_3)
endif
ifneq ("$(wildcard $(KEYBOARD_PATH_2)/)","")
OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_2)
endif
ifneq ("$(wildcard $(KEYBOARD_PATH_1)/)","")
OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_1)
endif
# Setup the define for QMK_KEYBOARD_H. This is used inside of keymaps so
# that the same keymap may be used on multiple keyboards.
#
# We grab the most top-level include file that we can. That file should
# use #ifdef statements to include all the neccesary subfolder includes,
# as described here:
#
# https://docs.qmk.fm/#/feature_layouts?id=tips-for-making-layouts-keyboard-agnostic
#
ifneq ("$(wildcard $(KEYBOARD_PATH_1)/$(KEYBOARD_FOLDER_1).h)","")
QMK_KEYBOARD_H = $(KEYBOARD_FOLDER_1).h
endif
@ -111,13 +162,18 @@ ifneq ("$(wildcard $(KEYBOARD_PATH_5)/$(KEYBOARD_FOLDER_5).h)","")
QMK_KEYBOARD_H = $(KEYBOARD_FOLDER_5).h
endif
# We can assume a ChibiOS target When MCU_FAMILY is defined , since it's not used for LUFA
# Determine and set parameters based on the keyboard's processor family.
# We can assume a ChibiOS target When MCU_FAMILY is defined since it's
# not used for LUFA
ifdef MCU_FAMILY
FIRMWARE_FORMAT=bin
FIRMWARE_FORMAT?=bin
PLATFORM=CHIBIOS
else ifdef ARM_ATSAM
PLATFORM=ARM_ATSAM
FIRMWARE_FORMAT=bin
else
PLATFORM=AVR
FIRMWARE_FORMAT=hex
FIRMWARE_FORMAT?=hex
endif
ifeq ($(PLATFORM),CHIBIOS)
@ -148,6 +204,7 @@ ifeq ($(PLATFORM),CHIBIOS)
endif
endif
# Find all of the config.h files and add them to our CONFIG_H define.
CONFIG_H :=
ifneq ("$(wildcard $(KEYBOARD_PATH_5)/config.h)","")
CONFIG_H += $(KEYBOARD_PATH_5)/config.h
@ -203,7 +260,7 @@ else
# this state should never be reached
endif
# User space stuff
# Userspace setup and definitions
ifeq ("$(USER_NAME)","")
USER_NAME := $(KEYMAP)
endif
@ -225,6 +282,7 @@ ifneq ("$(wildcard $(KEYMAP_PATH)/config.h)","")
endif
# # project specific files
SRC += $(patsubst %.c,%.clib,$(LIB_SRC))
SRC += $(KEYBOARD_SRC) \
$(KEYMAP_C) \
$(QUANTUM_SRC)
@ -243,6 +301,7 @@ include $(TMK_PATH)/protocol.mk
include $(TMK_PATH)/common.mk
include bootloader.mk
SRC += $(patsubst %.c,%.clib,$(QUANTUM_LIB_SRC))
SRC += $(TMK_COMMON_SRC)
OPT_DEFS += $(TMK_COMMON_DEFS)
EXTRALDFLAGS += $(TMK_COMMON_LDFLAGS)
@ -256,6 +315,11 @@ endif
include $(TMK_PATH)/avr.mk
endif
ifeq ($(PLATFORM),ARM_ATSAM)
include $(TMK_PATH)/arm_atsam.mk
include $(TMK_PATH)/protocol/arm_atsam.mk
endif
ifeq ($(PLATFORM),CHIBIOS)
include $(TMK_PATH)/protocol/chibios.mk
endif
@ -283,11 +347,6 @@ $(KEYBOARD_OUTPUT)_CONFIG := $(PROJECT_CONFIG)
# Default target.
all: build check-size
# Change the build target to build a HEX file or a library.
build: elf cpfirmware
#build: elf hex eep lss sym
#build: lib
include $(TMK_PATH)/rules.mk

1
common.mk
View file

@ -21,5 +21,4 @@ COMMON_VPATH += $(QUANTUM_PATH)/keymap_extras
COMMON_VPATH += $(QUANTUM_PATH)/audio
COMMON_VPATH += $(QUANTUM_PATH)/process_keycode
COMMON_VPATH += $(QUANTUM_PATH)/api
COMMON_VPATH += $(QUANTUM_PATH)/split_common
COMMON_VPATH += $(DRIVER_PATH)

80
common_features.mk
View file

@ -61,8 +61,8 @@ endif
ifeq ($(strip $(STENO_ENABLE)), yes)
OPT_DEFS += -DSTENO_ENABLE
VIRTSER_ENABLE := yes
SRC += $(QUANTUM_DIR)/process_keycode/process_steno.c
VIRTSER_ENABLE := yes
SRC += $(QUANTUM_DIR)/process_keycode/process_steno.c
endif
ifeq ($(strip $(VIRTSER_ENABLE)), yes)
@ -75,9 +75,9 @@ ifeq ($(strip $(FAUXCLICKY_ENABLE)), yes)
endif
ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
OPT_DEFS += -DPOINTING_DEVICE_ENABLE
OPT_DEFS += -DMOUSE_ENABLE
SRC += $(QUANTUM_DIR)/pointing_device.c
OPT_DEFS += -DPOINTING_DEVICE_ENABLE
OPT_DEFS += -DMOUSE_ENABLE
SRC += $(QUANTUM_DIR)/pointing_device.c
endif
ifeq ($(strip $(UCIS_ENABLE)), yes)
@ -110,19 +110,41 @@ ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
ifeq ($(strip $(RGBLIGHT_CUSTOM_DRIVER)), yes)
OPT_DEFS += -DRGBLIGHT_CUSTOM_DRIVER
else
SRC += ws2812.c
SRC += ws2812.c
endif
endif
ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
RGB_MATRIX_ENABLE ?= no
VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 custom
ifneq ($(strip $(RGB_MATRIX_ENABLE)), no)
ifeq ($(filter $(RGB_MATRIX_ENABLE),$(VALID_MATRIX_TYPES)),)
$(error RGB_MATRIX_ENABLE="$(RGB_MATRIX_ENABLE)" is not a valid matrix type)
endif
OPT_DEFS += -DRGB_MATRIX_ENABLE
SRC += is31fl3731.c
SRC += i2c_master.c
SRC += $(QUANTUM_DIR)/color.c
SRC += $(QUANTUM_DIR)/rgb_matrix.c
SRC += $(QUANTUM_DIR)/rgb_matrix_drivers.c
CIE1931_CURVE = yes
endif
ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
RGB_MATRIX_ENABLE = IS31FL3731
endif
ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3731)
OPT_DEFS += -DIS31FL3731
COMMON_VPATH += $(DRIVER_PATH)/issi
SRC += is31fl3731.c
SRC += i2c_master.c
endif
ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3733)
OPT_DEFS += -DIS31FL3733
COMMON_VPATH += $(DRIVER_PATH)/issi
SRC += is31fl3733.c
SRC += i2c_master.c
endif
ifeq ($(strip $(TAP_DANCE_ENABLE)), yes)
OPT_DEFS += -DTAP_DANCE_ENABLE
SRC += $(QUANTUM_DIR)/process_keycode/process_tap_dance.c
@ -169,7 +191,7 @@ ifeq ($(strip $(BACKLIGHT_ENABLE)), yes)
ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
CIE1931_CURVE = yes
endif
ifeq ($(strip $(BACKLIGHT_CUSTOM_DRIVER)), yes)
ifeq ($(strip $(BACKLIGHT_CUSTOM_DRIVER)), yes)
OPT_DEFS += -DBACKLIGHT_CUSTOM_DRIVER
endif
endif
@ -191,25 +213,48 @@ endif
ifeq ($(strip $(TERMINAL_ENABLE)), yes)
SRC += $(QUANTUM_DIR)/process_keycode/process_terminal.c
OPT_DEFS += -DTERMINAL_ENABLE
OPT_DEFS += -DUSER_PRINT
endif
ifeq ($(strip $(USB_HID_ENABLE)), yes)
include $(TMK_DIR)/protocol/usb_hid.mk
endif
ifeq ($(strip $(ENCODER_ENABLE)), yes)
SRC += $(QUANTUM_DIR)/encoder.c
OPT_DEFS += -DENCODER_ENABLE
endif
ifeq ($(strip $(HAPTIC_ENABLE)), DRV2605L)
COMMON_VPATH += $(DRIVER_PATH)/haptic
SRC += DRV2605L.c
SRC += i2c_master.c
OPT_DEFS += -DDRV2605L
endif
ifeq ($(strip $(HD44780_ENABLE)), yes)
SRC += drivers/avr/hd44780.c
OPT_DEFS += -DHD44780_ENABLE
OPT_DEFS += -DHD44780_ENABLE
endif
ifeq ($(strip $(DYNAMIC_KEYMAP_ENABLE)), yes)
OPT_DEFS += -DDYNAMIC_KEYMAP_ENABLE
SRC += $(QUANTUM_DIR)/dynamic_keymap.c
endif
ifeq ($(strip $(LEADER_ENABLE)), yes)
SRC += $(QUANTUM_DIR)/process_keycode/process_leader.c
OPT_DEFS += -DLEADER_ENABLE
endif
include $(DRIVER_PATH)/qwiic/qwiic.mk
QUANTUM_SRC:= \
$(QUANTUM_DIR)/quantum.c \
$(QUANTUM_DIR)/keymap_common.c \
$(QUANTUM_DIR)/keycode_config.c \
$(QUANTUM_DIR)/process_keycode/process_leader.c
$(QUANTUM_DIR)/keycode_config.c
ifndef CUSTOM_MATRIX
ifneq ($(strip $(CUSTOM_MATRIX)), yes)
ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
QUANTUM_SRC += $(QUANTUM_DIR)/split_common/matrix.c
else
@ -220,7 +265,8 @@ endif
ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
OPT_DEFS += -DSPLIT_KEYBOARD
QUANTUM_SRC += $(QUANTUM_DIR)/split_common/split_flags.c \
$(QUANTUM_DIR)/split_common/split_util.c \
$(QUANTUM_DIR)/split_common/i2c.c \
$(QUANTUM_DIR)/split_common/serial.c
$(QUANTUM_DIR)/split_common/split_util.c
QUANTUM_LIB_SRC += $(QUANTUM_DIR)/split_common/i2c.c
QUANTUM_LIB_SRC += $(QUANTUM_DIR)/split_common/serial.c
COMMON_VPATH += $(QUANTUM_PATH)/split_common
endif

4
docs/LANGS.md Normal file
View file

@ -0,0 +1,4 @@
# Languages
* [English](/)
* [Chinese](zh/)

78
docs/_sidebar.md
View file

@ -1,18 +1,16 @@
* [Getting Started](README.md)
* [QMK Introduction](getting_started_introduction.md)
* [Install Build Tools](getting_started_build_tools.md)
* Alternative: [Vagrant Guide](getting_started_vagrant.md)
* [Build/Compile Instructions](getting_started_make_guide.md)
* [Flashing Firmware](flashing.md)
* [Contributing to QMK](contributing.md)
* [How to Use Github](getting_started_github.md)
* [Getting Help](getting_started_getting_help.md)
* [Complete Newbs Guide](newbs.md)
* [Getting Started](newbs_getting_started.md)
* [Building Your First Firmware](newbs_building_firmware.md)
* [Flashing Firmware](newbs_flashing.md)
* [Testing and Debugging](newbs_testing_debugging.md)
* [Best Practices](newbs_best_practices.md)
* [Learning Resources](newbs_learn_more_resources.md)
* [QMK Basics](README.md)
* [QMK Introduction](getting_started_introduction.md)
* [Contributing to QMK](contributing.md)
* [How to Use Github](getting_started_github.md)
* [Getting Help](getting_started_getting_help.md)
* [FAQ](faq.md)
* [General FAQ](faq_general.md)
@ -20,26 +18,50 @@
* [Debugging/Troubleshooting QMK](faq_debug.md)
* [Keymap](faq_keymap.md)
* Detailed Guides
* [Install Build Tools](getting_started_build_tools.md)
* [Vagrant Guide](getting_started_vagrant.md)
* [Build/Compile Instructions](getting_started_make_guide.md)
* [Flashing Firmware](flashing.md)
* [Customizing Functionality](custom_quantum_functions.md)
* [Keymap Overview](keymap.md)
* [Hardware](hardware.md)
* [Keyboard Guidelines](hardware_keyboard_guidelines.md)
* [AVR Processors](hardware_avr.md)
* ARM Processors (TBD)
* [Drivers](hardware_drivers.md)
* Reference
* [Keyboard Guidelines](hardware_keyboard_guidelines.md)
* [Config Options](config_options.md)
* [Keycodes](keycodes.md)
* [Documentation Best Practices](documentation_best_practices.md)
* [Documentation Templates](documentation_templates.md)
* [Glossary](reference_glossary.md)
* [Unit Testing](unit_testing.md)
* [Useful Functions](ref_functions.md)
* [Configurator Support](reference_configurator_support.md)
* [Features](features.md)
* [Basic Keycodes](keycodes_basic.md)
* [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
* [Quantum Keycodes](quantum_keycodes.md)
* [Advanced Keycodes](feature_advanced_keycodes.md)
* [Audio](feature_audio.md)
* [Auto Shift](feature_auto_shift.md)
* [Backlight](feature_backlight.md)
* [Bluetooth](feature_bluetooth.md)
* [Bootmagic](feature_bootmagic.md)
* [Combos](feature_combo)
* [Command](feature_command.md)
* [Dynamic Macros](feature_dynamic_macros.md)
* [Encoders](feature_encoders.md)
* [Grave Escape](feature_grave_esc.md)
* [Key Lock](feature_key_lock.md)
* [Layouts](feature_layouts.md)
* [Leader Key](feature_leader_key.md)
* [Macros](feature_macros.md)
* [Mouse Keys](feature_mouse_keys.md)
* [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
* [Pointing Device](feature_pointing_device.md)
* [PS/2 Mouse](feature_ps2_mouse.md)
* [RGB Lighting](feature_rgblight.md)
@ -54,38 +76,11 @@
* [Unicode](feature_unicode.md)
* [Userspace](feature_userspace.md)
* [Keycodes](keycodes.md)
* [Basic](keycodes_basic.md)
* [Quantum](quantum_keycodes.md)
* [Audio](feature_audio.md#audio-keycodes)
* [Backlight](feature_backlight.md#backlight-keycodes)
* [Bluetooth](feature_bluetooth.md#bluetooth-keycodes)
* [Bootmagic](feature_bootmagic.md#bootmagic-keycodes)
* [Layer Switching](feature_advanced_keycodes.md#switching-and-toggling-layers)
* [Mod+Key](feature_advanced_keycodes.md#modifier-keys)
* [Mod Tap](feature_advanced_keycodes.md#mod-tap)
* [Mouse Keys](feature_mouse_keys.md#mapping-mouse-actions-to-keyboard-keys)
* [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
* [RGB Light](feature_rgblight.md#rgblight-keycodes)
* [RGB Matrix](feature_rgb_matrix.md#keycodes)
* [Shifted Keys](feature_advanced_keycodes.md#shifted-keycodes)
* [Stenography](feature_stenography.md#keycode-reference)
* [Swap Hands](feature_swap_hands.md#swap-keycodes)
* [Thermal Printer](feature_thermal_printer.md#thermal-printer-keycodes)
* [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
* Reference
* [Config Options](config_options.md)
* [Customizing Functionality](custom_quantum_functions.md)
* [Documentation Best Practices](documentation_best_practices.md)
* [Documentation Templates](documentation_templates.md)
* [Glossary](reference_glossary.md)
* [Keymap Overview](keymap.md)
* [Unit Testing](unit_testing.md)
* For Makers and Modders
* [Hand Wiring Guide](hand_wire.md)
* [ISP Flashing Guide](isp_flashing_guide.md)
* [ARM Debugging Guide](arm_debugging.md)
* [I2C Driver](i2c_driver.md)
* For a Deeper Understanding
* [How Keyboards Work](how_keyboards_work.md)
@ -93,6 +88,7 @@
* Other Topics
* [Using Eclipse with QMK](eclipse.md)
* [Support](support.md)
* QMK Internals (In Progress)
* [Defines](internals_defines.md)

78
docs/_summary.md
View file

@ -1,18 +1,16 @@
* [Getting Started](README.md)
* [QMK Introduction](getting_started_introduction.md)
* [Install Build Tools](getting_started_build_tools.md)
* Alternative: [Vagrant Guide](getting_started_vagrant.md)
* [Build/Compile Instructions](getting_started_make_guide.md)
* [Flashing Firmware](flashing.md)
* [Contributing to QMK](contributing.md)
* [How to Use Github](getting_started_github.md)
* [Getting Help](getting_started_getting_help.md)
* [Complete Newbs Guide](newbs.md)
* [Getting Started](newbs_getting_started.md)
* [Building Your First Firmware](newbs_building_firmware.md)
* [Flashing Firmware](newbs_flashing.md)
* [Testing and Debugging](newbs_testing_debugging.md)
* [Best Practices](newbs_best_practices.md)
* [Learning Resources](newbs_learn_more_resources.md)
* [QMK Basics](README.md)
* [QMK Introduction](getting_started_introduction.md)
* [Contributing to QMK](contributing.md)
* [How to Use Github](getting_started_github.md)
* [Getting Help](getting_started_getting_help.md)
* [FAQ](faq.md)
* [General FAQ](faq_general.md)
@ -20,26 +18,50 @@
* [Debugging/Troubleshooting QMK](faq_debug.md)
* [Keymap](faq_keymap.md)
* Detailed Guides
* [Install Build Tools](getting_started_build_tools.md)
* [Vagrant Guide](getting_started_vagrant.md)
* [Build/Compile Instructions](getting_started_make_guide.md)
* [Flashing Firmware](flashing.md)
* [Customizing Functionality](custom_quantum_functions.md)
* [Keymap Overview](keymap.md)
* [Hardware](hardware.md)
* [Keyboard Guidelines](hardware_keyboard_guidelines.md)
* [AVR Processors](hardware_avr.md)
* ARM Processors (TBD)
* [Drivers](hardware_drivers.md)
* Reference
* [Keyboard Guidelines](hardware_keyboard_guidelines.md)
* [Config Options](config_options.md)
* [Keycodes](keycodes.md)
* [Documentation Best Practices](documentation_best_practices.md)
* [Documentation Templates](documentation_templates.md)
* [Glossary](reference_glossary.md)
* [Unit Testing](unit_testing.md)
* [Useful Functions](ref_functions.md)
* [Configurator Support](reference_configurator_support.md)
* [Features](features.md)
* [Basic Keycodes](keycodes_basic.md)
* [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
* [Quantum Keycodes](quantum_keycodes.md)
* [Advanced Keycodes](feature_advanced_keycodes.md)
* [Audio](feature_audio.md)
* [Auto Shift](feature_auto_shift.md)
* [Backlight](feature_backlight.md)
* [Bluetooth](feature_bluetooth.md)
* [Bootmagic](feature_bootmagic.md)
* [Combos](feature_combo)
* [Command](feature_command.md)
* [Dynamic Macros](feature_dynamic_macros.md)
* [Encoders](feature_encoders.md)
* [Grave Escape](feature_grave_esc.md)
* [Key Lock](feature_key_lock.md)
* [Layouts](feature_layouts.md)
* [Leader Key](feature_leader_key.md)
* [Macros](feature_macros.md)
* [Mouse Keys](feature_mouse_keys.md)
* [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
* [Pointing Device](feature_pointing_device.md)
* [PS/2 Mouse](feature_ps2_mouse.md)
* [RGB Lighting](feature_rgblight.md)
@ -54,38 +76,11 @@
* [Unicode](feature_unicode.md)
* [Userspace](feature_userspace.md)
* [Keycodes](keycodes.md)
* [Basic](keycodes_basic.md)
* [Quantum](quantum_keycodes.md)
* [Audio](feature_audio.md#audio-keycodes)
* [Backlight](feature_backlight.md#backlight-keycodes)
* [Bluetooth](feature_bluetooth.md#bluetooth-keycodes)
* [Bootmagic](feature_bootmagic.md#bootmagic-keycodes)
* [Layer Switching](feature_advanced_keycodes.md#switching-and-toggling-layers)
* [Mod+Key](feature_advanced_keycodes.md#modifier-keys)
* [Mod Tap](feature_advanced_keycodes.md#mod-tap)
* [Mouse Keys](feature_mouse_keys.md#mapping-mouse-actions-to-keyboard-keys)
* [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
* [RGB Light](feature_rgblight.md#rgblight-keycodes)
* [RGB Matrix](feature_rgb_matrix.md#keycodes)
* [Shifted Keys](feature_advanced_keycodes.md#shifted-keycodes)
* [Stenography](feature_stenography.md#keycode-reference)
* [Swap Hands](feature_swap_hands.md#swap-keycodes)
* [Thermal Printer](feature_thermal_printer.md#thermal-printer-keycodes)
* [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
* Reference
* [Config Options](config_options.md)
* [Customizing Functionality](custom_quantum_functions.md)
* [Documentation Best Practices](documentation_best_practices.md)
* [Documentation Templates](documentation_templates.md)
* [Glossary](reference_glossary.md)
* [Keymap Overview](keymap.md)
* [Unit Testing](unit_testing.md)
* For Makers and Modders
* [Hand Wiring Guide](hand_wire.md)
* [ISP Flashing Guide](isp_flashing_guide.md)
* [ARM Debugging Guide](arm_debugging.md)
* [I2C Driver](i2c_driver.md)
* For a Deeper Understanding
* [How Keyboards Work](how_keyboards_work.md)
@ -93,6 +88,7 @@
* Other Topics
* [Using Eclipse with QMK](eclipse.md)
* [Support](support.md)
* QMK Internals (In Progress)
* [Defines](internals_defines.md)

87
docs/arm_debugging.md Normal file
View file

@ -0,0 +1,87 @@
# ARM Debugging usign Eclipse
This page describes how to setup debugging for ARM MCUs using an SWD adapter and open-source/free tools. In this guide we will install GNU MCU Eclipse IDE for C/C++ Developers and OpenOCD together with all the necessary dependencies.
This guide is catered towards advance users and assumes you can compile an ARM compatible keyboard on your machine using the MAKE flow.
## Installing the software
The main objective here is to get the MCU Eclipse IDE correcly installed on our machine. The necesarry instructions are derived from [this](https://gnu-mcu-eclipse.github.io/install/) install guide.
### The xPack Manager
This tool is a software package manager and it is used to help us get the necesarry depencencies.
XPM runs using Node.js so grab that form [here](https://nodejs.org/en/). After installation, open a terminal and type `npm -v`. A reply with the version number means that the instalation was successful.
XPM instalation instructions can be found [here](https://www.npmjs.com/package/xpm) and are OS specific. Entering `xpm --version` to your terminal should return the software version.
### The ARM Toolchain
Using XPM it is very easy to install the ARM toolchain. Enter the command `xpm install --global @gnu-mcu-eclipse/arm-none-eabi-gcc`.
### Windows build tools
If you are using windows you need to install this!
`xpm install --global @gnu-mcu-eclipse/windows-build-tools`
### Programer/Debugger Drivers
Now its the time to install your programer's drivers. This tutorial was made using an ST-Link v2 which you can get from almost anywhere.
If you have an ST-Link the drivers can be found [here](https://www.st.com/en/development-tools/stsw-link009.html) otherwise consult the manufuturer of your tool.
### OpenOCD
This dependency allows SWD access from GDB and it is essential for debugging. Run `xpm install --global @gnu-mcu-eclipse/openocd`.
### Java
Java is needed by Eclipse so please download it from [here](https://www.oracle.com/technetwork/java/javase/downloads/index.html).
### GNU MCU Eclipse IDE
Now its finally time to install the IDE. Use the Release page [here](https://github.com/gnu-mcu-eclipse/org.eclipse.epp.packages/releases/) to get the latest version.
## Configuring Eclipse
Open up the Eclipse IDE we just downloaded. To import our QMK directory select File -> Import -> C/C++ -> Existing code as Makefile Project. Select next and use Browse to select your QMK folder. In the tool-chain list select ARM Cross GCC and select Finish.
Now you can see the QMK folder on the left hand side. Right click it and select Properties. On the left hand side, expand MCU and select ARM Toolchain Paths. Press xPack and OK. Repeat for OpenOCD Path and if you are on windows for Build Tool Path. Select Apply and Close.
Now its time to install the necessary MCU packages. Go to Packs perspective by selecting Window -> Open Perspective -> Others -> Packs. Now select the yellow refresh symbol next to the Packs tab. This will take a long time as it is requesting the MCU definitions from various places. If some of the links fail you can probably select Ignore.
When this finishes you must find the MCU which we will be building/debugging for. In this example I will be using the STM32F3 series MCUs. On the left, select STMicroelectonics -> STM32F3 Series. On the middle window we can see the pack. Right click and select Install. Once that is done we can go back to the default perspective, Window -> Open Perspective -> Others -> C/C++.
We need to let eclipse know the device we intent to build QMK on. Right click on the QMK folder -> Properties -> C/C++ Build -> Settings. Select the Devices tab and under devices select the appropriate variant of your MCU. For my example it is STM32F303CC
While we are here let's setup the build command as well. Select C/C++ Build and then the Behavior tab. On the build command, replace `all` with your necessary make command. For example for a rev6 Planck with the default keymap this would be `planck/rev6:default`. Select Apply and Close.
## Building
If you have setup everything correctly pressing the hammer button should build the firmware for you and a .bin file should appear.
## Debugging
### Connecting the Debugger
ARM MCUs use the Single Wire Debug (SWD) protocol which comprises of the clock (SWCLK) signal and the data (SWDIO) signal. Connecting this two wires and ground should be enough to allow full manipulation of the MCU. Here we assume that the keyboard will be powered though USB. The RESET signal is not necessary as we can manually assert it using the reset button. For a more advance setup, the SWO signal can be used which pipes printf and scanf asynchronously to the host but for our setup we will ignore it.
NOTE: Make sure the SWCLK and SWDIO pins are not used in the matrix of your keyboard. If they are you can temporarily switch them for some other pins.
### Configuring the Debugger
Right click on your QMK folder, select Debug As -> Debug Configuration. Here double click on GDB OpenOCD Debugging. Select the debugger tab and enter the configuration necessary for your MCU. This might take some fiddling and googleing to find out. The default script for the STM32F3 is called stm32f3discovery.cfg. To let OpenOCD know, in the Config options enter `-f board/stm32f3discovery.cfg`.
NOTE: In my case this configuration script requires editing to disable the reset assertion. The locations of the scripts can be found in the actual executable field usually under the path `openocd/version/.content/scripts/board`. Here I edited `reset_config srst_only` to `reset_config none`.
Select Apply and Close.
### Running the Debugger.
Reset your keyboard.
Press the bug icon and if all goes well you should soon find yourself in the debug perspective. Here the program counter will pause at the beginning of the main function and way for you to press Play. Most of the features of all debuggers work on ARM MCUs but for exact details google is your friend!
Happy debugging!

10
docs/becoming_a_qmk_collaborator.md
View file

@ -1,7 +1,9 @@
A QMK collaborator is a keyboard maker/designer that is interested in helping QMK grow and fully support their keyboard(s), and encouraging their users/customers to submit features, ideas, and keymaps. We're always looking to add more keyboards and collaborators, but we ask that they fulfill these requirements:
# Becoming a QMK Collaborator
* **Have a PCB available for sale** - unfortunately there's just too much variation and complications with handwired keyboards.
* **Maintain the your keyboard's directory** - this may just require an initial setup to get your keyboard working, but it could also include accommodating changes made to QMK's core.
* **Approve and merge your keyboard's keymap pull requests** - we like to encourage users to contribute their keymaps for others to see and work from when creating their own.
A QMK collaborator is a keyboard maker or designer that is interested in helping QMK grow and fully support their keyboard(s), and encouraging their users and customers to submit features, ideas, and keymaps. We're always looking to add more keyboards and collaborators, but we ask that they fulfill these requirements:
* **Have a PCB available for sale.** Unfortunately there's just too much variation and complications with handwired keyboards.
* **Maintain your keyboard in QMK.** This may just require an initial setup to get your keyboard working, but it could also include accommodating changes made to QMK's core that might break or render any custom code redundant.
* **Approve and merge keymap pull requests for your keyboard.** We like to encourage users to contribute their keymaps for others to see and work from when creating their own.
If you feel you meet these requirements, shoot us an email at hello@qmk.fm with an introduction and some links to your keyboard!

109
docs/config_options.md
View file

@ -119,8 +119,8 @@ If you define these options you will enable the associated feature, which may in
* `#define FORCE_NKRO`
* NKRO by default requires to be turned on, this forces it on during keyboard startup regardless of EEPROM setting. NKRO can still be turned off but will be turned on again if the keyboard reboots.
* `#define PREVENT_STUCK_MODIFIERS`
* stores the layer a key press came from so the same layer is used when the key is released, regardless of which layers are enabled
* `#define STRICT_LAYER_RELEASE`
* force a key release to be evaluated using the current layer stack instead of remembering which layer it came from (used for advanced cases)
## Behaviors That Can Be Configured
@ -132,16 +132,22 @@ If you define these options you will enable the associated feature, which may in
* `#define TAPPING_TOGGLE 2`
* how many taps before triggering the toggle
* `#define PERMISSIVE_HOLD`
* makes tap and hold keys work better for fast typers who don't want tapping term set above 500
* makes tap and hold keys trigger the hold if another key is pressed before releasing, even if it hasn't hit the `TAPPING_TERM`
* See [Permissive Hold](feature_advanced_keycodes.md#permissive-hold) for details
* `#define IGNORE_MOD_TAP_INTERRUPT`
* makes it possible to do rolling combos (zx) with keys that convert to other keys on hold
* See [Mod tap interrupt](feature_advanced_keycodes.md#mod-tap-interrupt) for details
* makes it possible to do rolling combos (zx) with keys that convert to other keys on hold, by enforcing the `TAPPING_TERM` for both keys.
* See [Mod tap interrupt](feature_advanced_keycodes.md#ignore-mod-tap-interrupt) for details
* `#define TAPPING_FORCE_HOLD`
* makes it possible to use a dual role key as modifier shortly after having been tapped
* See [Hold after tap](feature_advanced_keycodes.md#hold-after-tap)
* See [Hold after tap](feature_advanced_keycodes.md#tapping-force-hold)
* Breaks any Tap Toggle functionality (`TT` or the One Shot Tap Toggle)
* `#define LEADER_TIMEOUT 300`
* how long before the leader key times out
* If you're having issues finishing the sequence before it times out, you may need to increase the timeout setting. Or you may want to enable the `LEADER_PER_KEY_TIMING` option, which resets the timeout after each key is tapped.
* `#define LEADER_PER_KEY_TIMING`
* sets the timer for leader key chords to run on each key press rather than overall
* `#define LEADER_KEY_STRICT_KEY_PROCESSING`
* Disables keycode filtering for Mod-Tap and Layer-Tap keycodes. Eg, if you enable this, you would need to specify `MT(MOD_CTL, KC_A)` if you want to use `KC_A`.
* `#define ONESHOT_TIMEOUT 300`
* how long before oneshot times out
* `#define ONESHOT_TAP_TOGGLE 2`
@ -155,6 +161,12 @@ If you define these options you will enable the associated feature, which may in
going to produce the 500 keystrokes a second needed to actually get more than a
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.
* `#define COMBO_TERM 200`
* how long for the Combo keys to be detected. Defaults to `TAPPING_TERM` if not defined.
* `#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.
## RGB Light Configuration
@ -185,12 +197,48 @@ If you define these options you will enable the associated feature, which may in
Split Keyboard specific options, make sure you have 'SPLIT_KEYBOARD = yes' in your rules.mk
* `#define SPLIT_HAND_PIN B7`
* For using high/low pin to determine handedness, low = right hand, high = left hand. Replace 'B7' with the pin you are using. This is optional and you can still use the EEHANDS method or MASTER_LEFT / MASTER_RIGHT defines like the stock Let's Split uses.
### Setting Handedness
One thing to remember, the side that the USB port is plugged into is always the master half. The side not plugged into USB is the slave.
There are a few different ways to set handedness for split keyboards (listed in order of precedence):
1. Set `SPLIT_HAND_PIN`: Reads a pin to determine handedness. If pin is high, it's the left side, if low, the half is determined to be the right side
2. Set `EE_HANDS` and flash `eeprom-lefthand.eep`/`eeprom-righthand.eep` to each half
3. Set `MASTER_RIGHT`: Half that is plugged into the USB port is determined to be the master and right half (inverse of the default)
4. Default: The side that is plugged into the USB port is the master half and is assumed to be the left half. The slave side is the right half
* `#define SPLIT_HAND_PIN B7`
* For using high/low pin to determine handedness, low = right hand, high = left hand. Replace `B7` with the pin you are using. This is optional, and if you leave `SPLIT_HAND_PIN` undefined, then you can still use the EE_HANDS method or MASTER_LEFT / MASTER_RIGHT defines like the stock Let's Split uses.
* `#define EE_HANDS` (only works if `SPLIT_HAND_PIN` is not defined)
* Reads the handedness value stored in the EEPROM after `eeprom-lefthand.eep`/`eeprom-righthand.eep` has been flashed to their respective halves.
* `#define MASTER_RIGHT`
* Master half is defined to be the right half.
### Other Options
* `#define USE_I2C`
* For using I2C instead of Serial (defaults to serial)
* `#define SOFT_SERIAL_PIN D0`
* When using serial, define this. `D0` or `D1`,`D2`,`D3`,`E6`.
* `#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.
* `#define SELECT_SOFT_SERIAL_SPEED <speed>` (default speed is 1)
* Sets the protocol speed when using serial communication
* Speeds:
* 0: about 189kbps (Experimental only)
* 1: about 137kbps (default)
* 2: about 75kbps
* 3: about 39kbps
* 4: about 26kbps
* 5: about 20kbps
# 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.
@ -199,6 +247,8 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
* `DEFAULT_FOLDER`
* Used to specify a default folder when a keyboard has more than one sub-folder.
* `FIRMWARE_FORMAT`
* Defines which format (bin, hex) is copied to the root `qmk_firmware` folder after building.
* `SRC`
* Used to add files to the compilation/linking list.
* `LAYOUTS`
@ -232,17 +282,56 @@ Use these to enable or disable building certain features. The more you have enab
* Console for debug(+400)
* `COMMAND_ENABLE`
* Commands for debug and configuration
* `COMBO_ENABLE`
* Key combo feature
* `NKRO_ENABLE`
* 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.
* `RGBLIGHT_ENABLE`
* Enable keyboard underlight functionality
* `LEADER_ENABLE`
* Enable leader key chording
* `MIDI_ENABLE`
* MIDI controls
* `UNICODE_ENABLE`
* Unicode
* `BLUETOOTH_ENABLE`
* Enable Bluetooth with the Adafruit EZ-Key HID
* Legacy option to Enable Bluetooth with the Adafruit EZ-Key HID. See BLUETOOTH
* `BLUETOOTH`
* Current options are AdafruitEzKey, AdafruitBLE, RN42
* `SPLIT_KEYBOARD`
* Enables split keyboard support (dual MCU like the let's split and bakingpy's boards) and includes all necessary files located at quantum/split_common
* `WAIT_FOR_USB`
* Forces the keyboard to wait for a USB connection to be established before it starts up
* `NO_USB_STARTUP_CHECK`
* Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master.
## USB Endpoint Limitations
In order to provide services over USB, QMK has to use USB endpoints.
These are a finite resource: each microcontroller has only a certain number.
This limits what features can be enabled together.
If the available endpoints are exceeded, a build error is thrown.
The following features can require separate endpoints:
* `MOUSEKEY_ENABLE`
* `EXTRAKEY_ENABLE`
* `CONSOLE_ENABLE`
* `NKRO_ENABLE`
* `MIDI_ENABLE`
* `RAW_ENABLE`
* `VIRTSER_ENABLE`
In order to improve utilisation of the endpoints, the HID features can be combined to use a single endpoint.
By default, `MOUSEKEY`, `EXTRAKEY`, and `NKRO` are combined into a single endpoint.
The base keyboard functionality can also be combined into the endpoint,
by setting `KEYBOARD_SHARED_EP = yes`.
This frees up one more endpoint,
but it can prevent the keyboard working in some BIOSes,
as they do not implement Boot Keyboard protocol switching.
Combining the mouse also breaks Boot Mouse compatibility.
The mouse can be uncombined by setting `MOUSE_SHARED_EP = no` if this functionality is required.

24
docs/contributing.md
View file

@ -57,19 +57,39 @@ Never made an open source contribution before? Wondering how contributions work
Most of our style is pretty easy to pick up on, but right now it's not entirely consistent. You should match the style of the code surrounding your change, but if that code is inconsistent or unclear use the following guidelines:
* We indent using two spaces (soft tabs)
* We use One True Brace Style
* We use a modified One True Brace Style
* Opening Brace: At the end of the same line as the statement that opens the block
* Closing Brace: Lined up with the first character of the statement that opens the block
* Else If: Place the closing brace at the beginning of the line and the next opening brace at the end of the same line.
* Optional Braces: Always include optional braces.
* Good: if (condition) { return false; }
* Bad: if (condition) return false;
* We use C style comments: `/* */`
* We encourage use of C style comments: `/* */`
* Think of them as a story describing the feature
* Use them liberally to explain why particular decisions were made.
* Do not write obvious comments
* If you not sure if a comment is obvious, go ahead and include it.
* In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns.
* We use `#pragma once` at the start of header files rather than old-style include guards (`#ifndef THIS_FILE_H`, `#define THIS_FILE_H`, ..., `#endif`)
Here is an example for easy reference:
```c
/* Enums for foo */
enum foo_state {
FOO_BAR,
FOO_BAZ,
};
/* Returns a value */
int foo(void) {
if (some_condition) {
return FOO_BAR;
} else {
return -1;
}
}
```
# General Guidelines

182
docs/custom_quantum_functions.md
View file

@ -27,7 +27,7 @@ The first step to creating your own custom keycode(s) is to enumerate them. This
Here is an example of enumerating 2 keycodes. After adding this block to your `keymap.c` you will be able to use `FOO` and `BAR` inside your keymap.
```
```c
enum my_keycodes {
FOO = SAFE_RANGE,
BAR
@ -44,7 +44,7 @@ These function are called every time a key is pressed or released.
This example does two things. It defines the behavior for a custom keycode called `FOO`, and it supplements our Enter key by playing a tone whenever it is pressed.
```
```c
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case FOO:
@ -75,16 +75,16 @@ The `keycode` argument is whatever is defined in your keymap, eg `MO(1)`, `KC_L`
The `record` argument contains information about the actual press:
```
```c
keyrecord_t record {
+-keyevent_t event {
| +-keypos_t key {
| | +-uint8_t col
| | +-uint8_t row
| | }
| +-bool pressed
| +-uint16_t time
| }
keyevent_t event {
keypos_t key {
uint8_t col
uint8_t row
}
bool pressed
uint16_t time
}
}
```
@ -100,7 +100,7 @@ This allows you to control the 5 LED's defined as part of the USB Keyboard spec.
### Example `led_set_user()` Implementation
```
```c
void led_set_user(uint8_t usb_led) {
if (usb_led & (1<<USB_LED_NUM_LOCK)) {
PORTB |= (1<<0);
@ -117,12 +117,12 @@ void led_set_user(uint8_t usb_led) {
} else {
PORTB &= ~(1<<2);
}
if (usb_led & (1<<USB_LED_COMPOSE_LOCK)) {
if (usb_led & (1<<USB_LED_COMPOSE)) {
PORTB |= (1<<3);
} else {
PORTB &= ~(1<<3);
}
if (usb_led & (1<<USB_LED_KANA_LOCK)) {
if (usb_led & (1<<USB_LED_KANA)) {
PORTB |= (1<<4);
} else {
PORTB &= ~(1<<4);
@ -138,14 +138,14 @@ void led_set_user(uint8_t usb_led) {
# Matrix Initialization Code
Before a keyboard can be used the hardware must be initialized. QMK handles initialization of the keyboard matrix itself, but if you have other hardware like LED's or i&#xb2;c controllers you will need to set up that hardware before it can be used.
Before a keyboard can be used the hardware must be initialized. QMK handles initialization of the keyboard matrix itself, but if you have other hardware like LED's or i&#xb2;c controllers you will need to set up that hardware before it can be used.
### Example `matrix_init_user()` Implementation
This example, at the keyboard level, sets up B1, B2, and B3 as LED pins.
```
```c
void matrix_init_user(void) {
// Call the keymap level matrix init.
@ -181,16 +181,16 @@ You should use this function if you need custom matrix scanning code. It can als
# Keyboard Idling/Wake Code
If the board supports it, it can be "idled", by stopping a number of functions. A good example of this is RGB lights or backlights. This can save on power consumption, or may be better behavior for your keyboard.
If the board supports it, it can be "idled", by stopping a number of functions. A good example of this is RGB lights or backlights. This can save on power consumption, or may be better behavior for your keyboard.
This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_init_*`, which are called when the system is board is idled and when it wakes up, respectively.
This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_init_*`, which are called when the system is board is idled and when it wakes up, respectively.
### Example suspend_power_down_user() and suspend_wakeup_init_user() Implementation
This example, at the keyboard level, sets up B1, B2, and B3 as LED pins.
```
```c
void suspend_power_down_user(void)
{
rgb_matrix_set_suspend_state(true);
@ -210,13 +210,13 @@ void suspend_wakeup_init_user(void)
# Layer Change Code
This runs code every time that the layers get changed. This can be useful for layer indication, or custom layer handling.
This runs code every time that the layers get changed. This can be useful for layer indication, or custom layer handling.
### Example `layer_state_set_*` Implementation
This example shows how to set the [RGB Underglow](feature_rgblight.md) lights based on the layer, using the Planck as an example
```
```c
uint32_t layer_state_set_user(uint32_t state) {
switch (biton32(state)) {
case _RAISE:
@ -244,3 +244,143 @@ uint32_t layer_state_set_user(uint32_t state) {
* Keymap: `uint32_t layer_state_set_user(uint32_t state)`
The `state` is the bitmask of the active layers, as explained in the [Keymap Overview](keymap.md#keymap-layer-status)
# Persistent Configuration (EEPROM)
This allows you to configure persistent settings for your keyboard. These settings are stored in the EEPROM of your controller, and are retained even after power loss. The settings can be read with `eeconfig_read_kb` and `eeconfig_read_user`, and can be written to using `eeconfig_update_kb` and `eeconfig_update_user`. This is useful for features that you want to be able to toggle (like toggling rgb layer indication). Additionally, you can use `eeconfig_init_kb` and `eeconfig_init_user` to set the default values for the EEPROM.
The complicated part here, is that there are a bunch of ways that you can store and access data via EEPROM, and there is no "correct" way to do this. However, you only have a DWORD (4 bytes) for each function.
Keep in mind that EEPROM has a limited number of writes. While this is very high, it's not the only thing writing to the EEPROM, and if you write too often, you can potentially drastically shorten the life of your MCU.
* If you don't understand the example, then you may want to avoid using this feature, as it is rather complicated.
### Example Implementation
This is an example of how to add settings, and read and write it. We're using the user keymap for the example here. This is a complex function, and has a lot going on. In fact, it uses a lot of the above functions to work!
In your keymap.c file, add this to the top:
```
typedef union {
uint32_t raw;
struct {
bool rgb_layer_change :1;
};
} user_config_t;
user_config_t user_config;
```
This sets up a 32 bit structure that we can store settings with in memory, and write to the EEPROM. Using this removes the need to define variables, since they're defined in this structure. Remember that `bool` (boolean) values use 1 bit, `uint8_t` uses 8 bits, `uint16_t` uses up 16 bits. You can mix and match, but changing the order can cause issues, as it will change the values that are read and written.
We're using `rgb_layer_change`, for the `layer_state_set_*` function, and use `matrix_init_user` and `process_record_user` to configure everything.
Now, using the `matrix_init_user` code above, you want to add `eeconfig_read_user()` to it, to populate the structure you've just created. And you can then immediately use this structure to control functionality in your keymap. And It should look like:
```
void matrix_init_user(void) {
// Call the keymap level matrix init.
// Read the user config from EEPROM
user_config.raw = eeconfig_read_user();
// Set default layer, if enabled
if (user_config.rgb_layer_change) {
rgblight_enable_noeeprom();
rgblight_sethsv_noeeprom_cyan();
rgblight_mode_noeeprom(1);
}
}
```
The above function will use the EEPROM config immediately after reading it, to set the default layer's RGB color. The "raw" value of it is converted in a usable structure based on the "union" that you created above.
```
uint32_t layer_state_set_user(uint32_t state) {
switch (biton32(state)) {
case _RAISE:
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); }
break;
case _LOWER:
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_red(); rgblight_mode_noeeprom(1); }
break;
case _PLOVER:
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_green(); rgblight_mode_noeeprom(1); }
break;
case _ADJUST:
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); }
break;
default: // for any other layers, or the default layer
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); }
break;
}
return state;
}
```
This will cause the RGB underglow to be changed ONLY if the value was enabled. Now to configure this value, create a new keycode for `process_record_user` called `RGB_LYR` and `EPRM`. Additionally, we want to make sure that if you use the normal RGB codes, that it turns off Using the example above, make it look this:
```
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case FOO:
if (record->event.pressed) {
// Do something when pressed
} else {
// Do something else when release
}
return false; // Skip all further processing of this key
case KC_ENTER:
// Play a tone when enter is pressed
if (record->event.pressed) {
PLAY_NOTE_ARRAY(tone_qwerty);
}
return true; // Let QMK send the enter press/release events
case EPRM:
if (record->event.pressed) {
eeconfig_init(); // resets the EEPROM to default
}
return false;
case RGB_LYR: // This allows me to use underglow as layer indication, or as normal
if (record->event.pressed) {
user_config.rgb_layer_change ^= 1; // Toggles the status
eeconfig_update_user(user_config.raw); // Writes the new status to EEPROM
if (user_config.rgb_layer_change) { // if layer state indication is enabled,
layer_state_set(layer_state); // then immediately update the layer color
}
}
return false; break;
case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // For any of the RGB codes (see quantum_keycodes.h, L400 for reference)
if (record->event.pressed) { //This disables layer indication, as it's assumed that if you're changing this ... you want that disabled
if (user_config.rgb_layer_change) { // only if this is enabled
user_config.rgb_layer_change = false; // disable it, and
eeconfig_update_user(user_config.raw); // write the setings to EEPROM
}
}
return true; break;
default:
return true; // Process all other keycodes normally
}
}
```
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. For example, if you want to set rgb layer indication by default, and save the default valued.
```
void eeconfig_init_user(void) { // EEPROM is getting reset!
user_config.rgb_layer_change = true; // We want this enabled by default
eeconfig_update_user(user_config.raw); // Write default value to EEPROM now
// use the non noeeprom versions, to write these values to EEPROM too
rgblight_enable(); // Enable RGB by default
rgblight_sethsv_cyan(); // Set it to CYAN by default
rgblight_mode(1); // set to solid by default
}
```
And you're done. The RGB layer indication will only work if you want it to. And it will be saved, even after unplugging the board. And if you use any of the RGB codes, it will disable the layer indication, so that it stays on the mode and color that you set it to.
### 'EECONFIG' Function Documentation
* Keyboard/Revision: `void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)` and `void eeconfig_update_kb(uint32_t val)`
* Keymap: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` and `void eeconfig_update_user(uint32_t val)`
The `val` is the value of the data that you want to write to EEPROM. And the `eeconfig_read_*` function return a 32 bit (DWORD) value from the EEPROM.

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