alvierahman90/qmk_firmware
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge branch 'master' into debounce_refactor

Browse Source 
# Conflicts:
#	tmk_core/common/keyboard.c
This commit is contained in:
Alex Ong 2019-01-04 19:43:45 +11:00
commit 2bb2977c13
3425 changed files with 216127 additions and 20390 deletions
Show Stats 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

36
build_keyboard.mk
View File

@ -34,6 +34,10 @@ $(error MASTER does not have a valid value(left/right))
endif
endif
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)))
@ -110,8 +114,28 @@ 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.
@ -144,6 +168,9 @@ endif
ifdef MCU_FAMILY
FIRMWARE_FORMAT?=bin
PLATFORM=CHIBIOS
else ifdef ARM_ATSAM
PLATFORM=ARM_ATSAM
FIRMWARE_FORMAT=bin
else
PLATFORM=AVR
FIRMWARE_FORMAT?=hex
@ -255,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)
@ -273,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)
@ -286,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

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)

60
common_features.mk
View File

@ -114,37 +114,35 @@ ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
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
OPT_DEFS += -DIS31FL3731
COMMON_VPATH += $(DRIVER_PATH)/issi
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 += -DRGB_MATRIX_ENABLE
OPT_DEFS += -DIS31FL3731
COMMON_VPATH += $(DRIVER_PATH)/issi
SRC += is31fl3731.c
SRC += i2c_master.c
SRC += $(QUANTUM_DIR)/color.c
SRC += $(QUANTUM_DIR)/rgb_matrix.c
CIE1931_CURVE = yes
endif
ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3733)
OPT_DEFS += -DRGB_MATRIX_ENABLE
OPT_DEFS += -DIS31FL3733
COMMON_VPATH += $(DRIVER_PATH)/issi
SRC += is31fl3733.c
SRC += i2c_master.c
SRC += $(QUANTUM_DIR)/color.c
SRC += $(QUANTUM_DIR)/rgb_matrix.c
CIE1931_CURVE = yes
endif
ifeq ($(strip $(TAP_DANCE_ENABLE)), yes)
@ -215,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
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
@ -244,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/)

10
docs/_sidebar.md
View File

@ -3,6 +3,8 @@
* [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)
@ -37,9 +39,11 @@
* [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)
@ -47,8 +51,10 @@
* [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)
@ -69,11 +75,12 @@
* [Thermal Printer](feature_thermal_printer.md)
* [Unicode](feature_unicode.md)
* [Userspace](feature_userspace.md)
* [US ANSI Shifted Keys](keycodes_us_ansi_shifted.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)
@ -81,6 +88,7 @@
* Other Topics
* [Using Eclipse with QMK](eclipse.md)
* [Support](support.md)
* QMK Internals (In Progress)
* [Defines](internals_defines.md)

10
docs/_summary.md
View File

@ -3,6 +3,8 @@
* [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)
@ -37,9 +39,11 @@
* [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)
@ -47,8 +51,10 @@
* [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)
@ -69,11 +75,12 @@
* [Thermal Printer](feature_thermal_printer.md)
* [Unicode](feature_unicode.md)
* [Userspace](feature_userspace.md)
* [US ANSI Shifted Keys](keycodes_us_ansi_shifted.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)
@ -81,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!

107
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.
@ -234,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.

2
docs/documentation_templates.md
View File

@ -36,7 +36,7 @@ Make example for this keyboard (after setting up your build environment):
make planck/rev4:default
See [build environment setup](https://docs.qmk.fm/build_environment_setup.html) then the [make instructions](https://docs.qmk.fm/make_instructions.html) for more information.
See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs).
```
There needs to be two spaces at the end of the `Keyboard Maintainer` and `Hardware Supported` lines for it to render correctly with Markdown.

14
docs/faq_build.md
View File

@ -17,7 +17,7 @@ or just:
Note that running `make` with `sudo` is generally *not* a good idea, and you should use one of the former methods, if possible.
## Linux `udev` Rules
### Linux `udev` Rules
On Linux, you'll need proper privileges to access the MCU. You can either use
`sudo` when flashing firmware, or place these files in `/etc/udev/rules.d/`.
@ -37,6 +37,14 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="066
SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
```
## Unknown Device for DFU Bootloader
If you're using Windows to flash your keyboard, and you are running into issues, check the Device Manager. If you see an "Unknown Device" when the keyboard is in "bootloader mode", then you may have a driver issue.
Re-running the installation script for MSYS2 may help (eg run `./util/qmk_install.sh` from MSYS2/WSL) or reinstalling the QMK Toolbox may fix the issue.
If that doesn't work, then you may need to grab the [Zadig Utility](https://zadig.akeo.ie/). Download this, find the device in question, and select the `WinUS(libusb-1.0)` option, and hit "Reinstall driver". Once you've done that, try flashing your board, again.
## WINAVR is Obsolete
It is no longer recommended and may cause some problem.
See [TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99).
@ -97,10 +105,12 @@ The solution is to remove and reinstall all affected modules.
```
brew rm avr-gcc
brew rm dfu-programmer
brew rm dfu-util
brew rm gcc-arm-none-eabi
brew rm avrdude
brew install avr-gcc
brew install dfu-programmer
brew install dfu-util
brew install gcc-arm-none-eabi
brew install avrdude
```
@ -116,5 +126,5 @@ For now, you need to rollback avr-gcc to 7 in brew.
```
brew uninstall --force avr-gcc
brew install avr-gcc@7
brew link avr-gcc@7
brew link --force avr-gcc@7
```

21
docs/faq_keymap.md
View File

@ -11,8 +11,8 @@ Keycodes are actually defined in [common/keycode.h](https://github.com/qmk/qmk_f
There are 3 standard keyboard layouts in use around the world- ANSI, ISO, and JIS. North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS. Regions not mentioned typically use either ANSI or ISO. The keycodes corresponding to these layouts are shown here:
<!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/070a530eedaed36a2d77f3f6fd455677 -->
![Keyboard Layout Image](https://i.imgur.com/gvlNUpQ.png)
<!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
![Keyboard Layout Image](https://i.imgur.com/5wsh5wM.png)
## Some Of My Keys Are Swapped Or Not Working
@ -211,20 +211,3 @@ here real_mods lost state for 'physical left shift'.
weak_mods is ORed with real_mods when keyboard report is sent.
https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57
## Timer Functionality
It's possible to start timers and read values for time-specific events - here's an example:
```c
static uint16_t key_timer;
key_timer = timer_read();
if (timer_elapsed(key_timer) < 100) {
// do something if less than 100ms have passed
} else {
// do something if 100ms or more have passed
}
```
It's best to declare the `static uint16_t key_timer;` at the top of the file, outside of any code blocks you're using it in.

206
docs/feature_advanced_keycodes.md
View File

@ -2,7 +2,7 @@
Your keymap can include keycodes that are more advanced than normal, for example keys that switch layers or send modifiers when held, but send regular keycodes when tapped. This page documents the functions that are available to you.
### Assigning Custom Names
## Assigning Custom Names
People often define custom names using `#define`. For example:
@ -13,18 +13,21 @@ People often define custom names using `#define`. For example:
This will allow you to use `FN_CAPS` and `ALT_TAB` in your `KEYMAP()`, keeping it more readable.
### Limits of These Aliases
## Caveats
Currently, the keycodes able to used with these functions are limited to the [Basic Keycodes](keycodes_basic.md), meaning you can't use keycodes like `KC_TILD`, or anything greater than 0xFF. For a full list of the keycodes able to be used see [Basic Keycodes](keycodes_basic.md).
Currently, `LT()` and `MT()` are limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. Modifiers specified as part of a Layer Tap or Mod Tap's keycode will be ignored.
Additionally, if at least one right-handed modifier is specified in a Mod Tap or Layer Tap, it will cause all modifiers specified to become right-handed, so it is not possible to mix and match the two.
# Switching and Toggling Layers
These functions allow you to activate layers in various ways. Note that layers are not generally independent layouts -- multiple layers can be activated at once, and it's typical for layers to use `KC_TRNS` to allow keypresses to pass through to lower layers. For a detailed explanation of layers, see [Keymap Overview](keymap.md#keymap-and-layers)
These functions allow you to activate layers in various ways. Note that layers are not generally independent layouts -- multiple layers can be activated at once, and it's typical for layers to use `KC_TRNS` to allow keypresses to pass through to lower layers. For a detailed explanation of layers, see [Keymap Overview](keymap.md#keymap-and-layers) When using momentary layer switching with MO(), LM(), TT(), or LT(), make sure to leave the key on the above layers transparent or it may not work as intended.
* `DF(layer)` - switches the default layer. The default layer is the always-active base layer that other layers stack on top of. See below for more about the default layer. This might be used to switch from QWERTY to Dvorak layout. (Note that this is a temporary switch that only persists until the keyboard loses power. To modify the default layer in a persistent way requires deeper customization, such as calling the `set_single_persistent_default_layer` function inside of [process_record_user](custom_quantum_functions.md#programming-the-behavior-of-any-keycode).)
* `MO(layer)` - momentarily activates *layer*. As soon as you let go of the key, the layer is deactivated.
* `LM(layer, mod)` - Momentarily activates *layer* (like `MO`), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers.
* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped.
* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped. Only supports layers 0-15.
* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys](#one-shot-keys) for details and additional functionality.
* `TG(layer)` - toggles *layer*, activating it if it's inactive and vice versa
* `TO(layer)` - activates *layer* and de-activates all other layers (except your default layer). This function is special, because instead of just adding/removing one layer to your active layer stack, it will completely replace your current active layers, uniquely allowing you to replace higher layers with a lower one. This is activated on keydown (as soon as the key is pressed).
* `TT(layer)` - Layer Tap-Toggle. If you hold the key down, *layer* is activated, and then is de-activated when you let go (like `MO`). If you repeatedly tap it, the layer will be toggled on or off (like `TG`). It needs 5 taps by default, but you can change this by defining `TAPPING_TOGGLE` -- for example, `#define TAPPING_TOGGLE 2` to toggle on just two taps.
@ -33,7 +36,7 @@ These functions allow you to activate layers in various ways. Note that layers a
Care must be taken when switching layers, it's possible to lock yourself into a layer with no way to deactivate that layer (without unplugging your keyboard.) We've created some guidelines to help users avoid the most common problems.
### Beginners
## Beginners
If you are just getting started with QMK you will want to keep everything simple. Follow these guidelines when setting up your layers:
@ -41,11 +44,11 @@ If you are just getting started with QMK you will want to keep everything simple
* Arrange your layers in a "tree" layout, with layer 0 as the root. Do not try to enter the same layer from more than one other layer.
* In a layer's keymap, only reference higher-numbered layers. Because layers are processed from the highest-numbered (topmost) active layer down, modifying the state of lower layers can be tricky and error-prone.
### Intermediate Users
## Intermediate Users
Sometimes you need more than one base layer. For example, if you want to switch between QWERTY and Dvorak, switch between layouts for different countries, or switch your layout for different videogames. Your base layers should always be the lowest numbered layers. When you have multiple base layers you should always treat them as mutually exclusive. When one base layer is on the others are off.
### Advanced Users
## Advanced Users
Once you have a good feel for how layers work and what you can do, you can get more creative. The rules listed in the beginner section will help you be successful by avoiding some of the tricker details but they can be constraining, especially for ultra-compact keyboard users. Understanding how layers work will allow you to use them in more advanced ways.
@ -55,57 +58,80 @@ Sometimes, you might want to switch between layers in a macro or as part of a ta
# Modifier Keys
These functions allow you to combine a mod with a keycode. When pressed the keydown for the mod will be sent first, and then *kc* will be sent. When released the keyup for *kc* will be sent and then the mod will be sent.
These allow you to combine a modifier with a keycode. When pressed, the keydown event for the modifier, then `kc` will be sent. On release, the keyup event for `kc`, then the modifier will be sent.
* `LSFT(kc)` or `S(kc)` - applies left Shift to *kc* (keycode)
* `RSFT(kc)` - applies right Shift to *kc*
* `LCTL(kc)` - applies left Control to *kc*
* `RCTL(kc)` - applies right Control to *kc*
* `LALT(kc)` - applies left Alt to *kc*
* `RALT(kc)` - applies right Alt to *kc*
* `LGUI(kc)` - applies left GUI (command/win) to *kc*
* `RGUI(kc)` - applies right GUI (command/win) to *kc*
* `HYPR(kc)` - applies Hyper (all modifiers) to *kc*
* `MEH(kc)` - applies Meh (all modifiers except Win/Cmd) to *kc*
* `LCAG(kc)` - applies CtrlAltGui to *kc*
|Key |Aliases |Description |
|----------|----------------------|----------------------------------------------------|
|`LCTL(kc)`| |Hold Left Control and press `kc` |
|`LSFT(kc)`|`S(kc)` |Hold Left Shift and press `kc` |
|`LALT(kc)`| |Hold Left Alt and press `kc` |
|`LGUI(kc)`|`LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc` |
|`RCTL(kc)`| |Hold Right Control and press `kc` |
|`RSFT(kc)`| |Hold Right Shift and press `kc` |
|`RALT(kc)`|`ALGR(kc)` |Hold Right Alt and press `kc` |
|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)`|Hold Right GUI and press `kc` |
|`HYPR(kc)`| |Hold Left Control, Shift, Alt and GUI and press `kc`|
|`MEH(kc)` | |Hold Left Control, Shift and Alt and press `kc` |
|`LCAG(kc)`| |Hold Left Control, Alt and GUI and press `kc` |
|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`|Hold Left Shift and GUI and press `kc` |
|`LCA(kc)` | |Hold Left Control and Alt and press `kc` |
You can also chain these, like this:
You can also chain them, for example `LCTL(LALT(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress.
LALT(LCTL(KC_DEL)) -- this makes a key that sends Alt, Control, and Delete in a single keypress.
# Mod-Tap
# Mod Tap
The Mod-Tap key `MT(mod, kc)` acts like a modifier when held, and a regular keycode when tapped. In other words, you can have a key that sends Escape when you tap it, but functions as a Control or Shift key when you hold it down.
`MT(mod, kc)` - is *mod* (modifier key - MOD_LCTL, MOD_LSFT) when held, and *kc* when tapped. In other words, you can have a key that sends Esc (or the letter O or whatever) when you tap it, but works as a Control key or a Shift key when you hold it down.
The modifiers this keycode and `OSM()` accept are prefixed with `MOD_`, not `KC_`:
These are the values you can use for the `mod` in `MT()` and `OSM()`:
|Modifier |Description |
|----------|----------------------------------------|
|`MOD_LCTL`|Left Control |
|`MOD_LSFT`|Left Shift |
|`MOD_LALT`|Left Alt |
|`MOD_LGUI`|Left GUI (Windows/Command/Meta key) |
|`MOD_RCTL`|Right Control |
|`MOD_RSFT`|Right Shift |
|`MOD_RALT`|Right Alt (AltGr) |
|`MOD_RGUI`|Right GUI (Windows/Command/Meta key) |
|`MOD_HYPR`|Hyper (Left Control, Shift, Alt and GUI)|
|`MOD_MEH` |Meh (Left Control, Shift, and Alt) |
* MOD_LCTL
* MOD_LSFT
* MOD_LALT
* MOD_LGUI
* MOD_RCTL
* MOD_RSFT
* MOD_RALT
* MOD_RGUI
* MOD_HYPR
* MOD_MEH
You can combine these by ORing them together like so:
These can also be combined like `MOD_LCTL | MOD_LSFT` e.g. `MT(MOD_LCTL | MOD_LSFT, KC_ESC)` which would activate Control and Shift when held, and send Escape when tapped.
```c
MT(MOD_LCTL | MOD_LSFT, KC_ESC)
```
We've added shortcuts to make common modifier/tap (mod-tap) mappings more compact:
This key would activate Left Control and Left Shift when held, and send Escape when tapped.
* `CTL_T(kc)` - is LCTL when held and *kc* when tapped
* `SFT_T(kc)` - is LSFT when held and *kc* when tapped
* `ALT_T(kc)` - is LALT when held and *kc* when tapped
* `ALGR_T(kc)` - is AltGr when held and *kc* when tapped
* `GUI_T(kc)` - is LGUI when held and *kc* when tapped
* `ALL_T(kc)` - is Hyper (all mods) when held and *kc* when tapped. To read more about what you can do with a Hyper key, see [this blog post by Brett Terpstra](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)
* `LCAG_T(kc)` - is CtrlAltGui when held and *kc* when tapped
* `MEH_T(kc)` - is like Hyper, but not as cool -- does not include the Cmd/Win key, so just sends Alt+Ctrl+Shift.
For convenience, QMK includes some Mod-Tap shortcuts to make common combinations more compact in your keymap:
?> Due to the way that keycodes are structured, any modifiers specified as part of `kc`, such as `LCTL()` or `KC_LPRN`, will only activate when held instead of tapped.
|Key |Aliases |Description |
|------------|---------------------------------------|-------------------------------------------------------|
|`LCTL_T(kc)`|`CTL_T(kc)` |Left Control when held, `kc` when tapped |
|`RCTL_T(kc)`| |Right Control when held, `kc` when tapped |
|`LSFT_T(kc)`|`SFT_T(kc)` |Left Shift when held, `kc` when tapped |
|`RSFT_T(kc)`| |Right Shift when held, `kc` when tapped |
|`LALT_T(kc)`|`ALT_T(kc)` |Left Alt when held, `kc` when tapped |
|`RALT_T(kc)`|`ALGR_T(kc)` |Right Alt when held, `kc` when tapped |
|`LGUI_T(kc)`|`LCMD_T(kc)`, `RWIN_T(kc)`, `GUI_T(kc)`|Left GUI when held, `kc` when tapped |
|`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)` |Right GUI when held, `kc` when tapped |
|`C_S_T(kc)` | |Left Control and Shift when held, `kc` when tapped |
|`MEH_T(kc)` | |Left Control, Shift and Alt when held, `kc` when tapped|
|`LCAG_T(kc)`| |Left Control, Alt and GUI when held, `kc` when tapped |
|`RCAG_T(kc)`| |Right Control, Alt and GUI when held, `kc` when tapped |
|`ALL_T(kc)` | |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)|
|`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)` |Left Shift and GUI when held, `kc` when tapped |
|`LCA_T(kc)` | |Left Control and Alt when held, `kc` when tapped |
?> Additionally, if there is at least one right-handed modifier, any other modifiers in a chain of functions will turn into their right-handed equivalents, so it is not possible to "mix and match" the two.
## Caveats
Unfortunately, these keycodes cannot be used in Mod-Taps or Layer-Taps, since any modifiers specified in the keycode are ignored.
Additionally, you may run into issues when using Remote Desktop Connection on Windows. Because these codes send shift very fast, Remote Desktop may miss the codes.
To fix this, open Remote Desktop Connection, click on "Show Options", open the the "Local Resources" tab. In the keyboard section, change the drop down to "On this Computer". This will fix the issue, and allow the characters to work correctly.
# One Shot Keys
@ -115,6 +141,8 @@ For example, if you define a key as `OSM(MOD_LSFT)`, you can type a capital A ch
One shot keys also work as normal modifiers. If you hold down a one shot key and type other keys, your one shot will be released immediately after you let go of the key.
Additionally, hitting keys five times in a short period will lock that key. This applies for both One Shot Modifiers and One Shot Layers, and is controlled by the `ONESHOT_TAP_TOGGLE` define.
You can control the behavior of one shot keys by defining these in `config.h`:
```c
@ -125,42 +153,78 @@ You can control the behavior of one shot keys by defining these in `config.h`:
* `OSM(mod)` - Momentarily hold down *mod*. You must use the `MOD_*` keycodes as shown in [Mod Tap](#mod-tap), not the `KC_*` codes.
* `OSL(layer)` - momentary switch to *layer*.
Sometimes, you want to activate a one-shot layer as part of a macro or tap dance routine. To do this, you need to call `set_oneshot_layer(LAYER, ONESHOT_START)` on key down, and `set_oneshot_layer(ONESHOT_PRESSED)` on key up. If you want to cancel the oneshot, call `reset_oneshot_layer()`. For more complicated actions, take a look at the oneshot implementation in [`process_record`](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action.c#L429).
Sometimes, you want to activate a one-shot key as part of a macro or tap dance routine.
If you're having issues with OSM translating over Remote Desktop Connection, this can be fixed by opening the settings, going to the "Local Resources" tap, and in the keyboard section, change the drop down to "On this Computer". This will fix the issue and allow OSM to function properly over Remote Desktop.
For one shot layers, you need to call `set_oneshot_layer(LAYER, ONESHOT_START)` on key down, and `set_oneshot_layer(ONESHOT_PRESSED)` on key up. If you want to cancel the oneshot, call `reset_oneshot_layer()`.
# Permissive Hold
For one shot mods, you need to call `set_oneshot_mods(MOD)` to set it, or `clear_oneshot_mods()` to cancel it.
!> If you're having issues with OSM translating over Remote Desktop Connection, this can be fixed by opening the settings, going to the "Local Resources" tap, and in the keyboard section, change the drop down to "On this Computer". This will fix the issue and allow OSM to function properly over Remote Desktop.
# Tap-Hold Configuration Options
While Tap-Hold options are fantastic, they are not without their issues. We have tried to configure them with reasonal defaults, but that may still cause issues for some people.
These options let you modify the behavior of the Tap-Hold keys.
## Permissive Hold
As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new `config.h` option:
```
```c
#define PERMISSIVE_HOLD
```
This makes it easier for fast typists to use dual-function keys. Without this, if you let go of a held key inside the tapping term, it won't register.
This makes tap and hold keys (like Mod Tap) work better for fast typist, or for high `TAPPING_TERM` settings.
Example: (Tapping Term = 200ms)
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.
- SHFT_T(KC_A) Down
- KC_X Down
- KC_X Up
- SHFT_T(KC_A) Up
For Instance:
With defaults, if above is typed within tapping term, this will emit `ax`. With permissive hold, if above is typed within tapping term, this will emit `X` (so, Shift+X).
- `SHFT_T(KC_A)` Down
- `KC_X` Down
- `KC_X` Up
- `SHFT_T(KC_A)` Up
# Mod tap interrupt
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`).
When a dual role key used for a modifier is quickly followed by another keys, it is interpreted as held even before the tapping term elapsed. This is a problem if a key is used for example inside a rolling combo because the second key will be pressed before the first key is released.
?> 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`.
For example, when trying to type the rolling combo "zx" and z being configured to send Ctrl when hold, z rapidly followed by x actually sends Ctrl-x. That's bad.
## Ignore Mod Tap Interrupt
You can disable this behavior by defining `IGNORE_MOD_TAP_INTERRUPT` in `config.h`.
To enable this setting, add this to your `config.h`:
Note that this only concerns modifiers and not layer switching keys.
```c
#define IGNORE_MOD_TAP_INTERRUPT
```
# Hold after tap
Similar to Permissive Hold, this alters how the firmware processes input for fast typist. 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 "tapping" function for both keys. This may not be desirable for rolling combo keys.
When the user holds a key after tap, this repeats the tapped key rather to hold a modifier key. This allows to use auto repeat for the tapped key. If you prefer to hold a modifier instead, define `TAPPING_FORCE_HOLD` in `config.h`.
Setting `Ignore Mod Tap Interrupt` requires holding both keys for the `TAPPING_TERM` to trigger the hold function (the mod).
For Instance:
- `SHFT_T(KC_A)` Down
- `KC_X` Down
- `SHFT_T(KC_A)` Up
- `KC_X` Up
Normally, this would send `X` (`SHIFT`+`x`). 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 `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`.
## Tapping Force Hold
To enable `tapping force hold`, add the following to your `config.h`:
```c
#define TAPPING_FORCE_HOLD
```
When the user holds a key after tap, this repeats the tapped key rather to hold a modifier key. This allows to use auto repeat for the tapped key.
Example:
@ -176,8 +240,14 @@ With `TAPPING_FORCE_HOLD`, the second press will be interpreted as a Shift, allo
!> `TAPPING_FORCE_HOLD` will break anything that uses tapping toggles (Such as the `TT` layer keycode, and the One Shot Tapping Toggle).
# Retro Tapping
## Retro Tapping
When you hold a dual function key, and haven't pressed anything when you release the key, normally nothing happens. However, if you enable this, if you release the key without pressing another key, it will send the original key, even if it is outside of the tapping term.
To enable `retro tapping`, add the following to your `config.h`:
For instance, if you're using `LT(2, KC_SPACE)`, if you hold the key, don't hit anything else and then release it, normally, nothing happens. But with `RETRO_TAPPING` defined in your `config.h`, it will send `KC_SPACE`.
```c
#define RETRO_TAPPING
```
Holding and releasing a dual function key without pressing another key will result in nothing happening. With retro tapping enabled, releasing the key without pressing another will send the original keycode even if it is outside the tapping term.
For instance, holding and releasing `LT(2, KC_SPACE)` without hitting another key will result in nothing happening. With this enabled, it will send `KC_SPACE` instead.

33
docs/feature_audio.md
View File

@ -61,10 +61,19 @@ It's advised that you wrap all audio features in `#ifdef AUDIO_ENABLE` / `#endif
The available keycodes for audio are:
* `AU_ON` - Turn audio mode on
* `AU_OFF` - Turn audio mode off
* `AU_TOG` - Toggle audio mode
* `AU_ON` - Turn Audio Feature on
* `AU_OFF` - Turn Audio Feature off
* `AU_TOG` - Toggle Audio Feature state
!> 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.
## ARM Audio Volume
For ARM devices, you can adjust the DAC sample values. If your board is too loud for you or your coworkers, you can set the max using `DAC_SAMPLE_MAX` in your `config.h`:
```c
#define DAC_SAMPLE_MAX 65535U
```
## Music Mode
@ -119,22 +128,22 @@ You can completely disable Music Mode as well. This is useful, if you're pressed
#define NO_MUSIC_MODE
## Faux Click
## Audio Click
This adds a click sound each time you hit a button, to simulate click sounds from the keyboard. And the sounds are slightly different for each keypress, so it doesn't sound like a single long note, if you type rapidly.
* `CK_TOGG` - Toggles the status (will play sound if enabled)
* `CK_RST` - Resets the frequency to the default state
* `CK_UP` - Increases the frequency of the clicks
* `CK_DOWN` - Decreases the frequency of the clicks
* `CK_ON` - Turns on Audio Click (plays sound)
* `CK_OFF` - Turns off Audio Click (doesn't play sound)
* `CK_RST` - Resets the frequency to the default state (plays sound at default frequency)
* `CK_UP` - Increases the frequency of the clicks (plays sound at new frequency)
* `CK_DOWN` - Decreases the frequency of the clicks (plays sound at new frequency)
The feature is disabled by default, to save space. To enable it, add this to your `config.h`:
#define AUDIO_CLICKY
Additionally, even when enabled, the feature is not enabled by default, so you would need to turn it on first. And since we don't use EEPROM to store the setting (yet), you can default this to on by adding this to your `config.h`:
#define AUDIO_CLICKY_ON
You can configure the default, min and max frequencies, the stepping and built in randomness by defining these values:
@ -144,14 +153,14 @@ You can configure the default, min and max frequencies, the stepping and built i
| `AUDIO_CLICKY_FREQ_MIN` | 65.0f | Sets the lowest frequency (under 60f are a bit buggy). |
| `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | Sets the the highest frequency. Too high may result in coworkers attacking you. |
| `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f| Sets the stepping of UP/DOWN key codes. |
| `AUDIO_CLICKY_FREQ_RANDOMNESS` | 0.05f | Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical. |
| `AUDIO_CLICKY_FREQ_RANDOMNESS` | 0.05f | Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical, and `1.0f` will make this sound much like the 90's computer screen scrolling/typing effect. |
## MIDI Functionality
This is still a WIP, but check out `quantum/keymap_midi.c` to see what's happening. Enable from the Makefile.
This is still a WIP, but check out `quantum/process_keycode/process_midi.c` to see what's happening. Enable from the Makefile.
## Audio Keycodes

19
docs/feature_backlight.md
View File

@ -54,14 +54,17 @@ In this handler, the value of an incrementing counter is mapped onto a precomput
## Backlight Functions
|Function |Description |
|----------|----------------------------------------------------------|
|`backlight_toggle()` |Turn the backlight on or off |
|`backlight_step()` |Cycle through backlight levels |
|`backlight_increase()` |Increase the backlight level |
|`backlight_decrease()` |Decrease the backlight level |
|`backlight_level(x)` |Sets the backlight level to specified level |
|`get_backlight_level()`|Toggle backlight breathing |
|Function |Description |
|----------|-----------------------------------------------------------|
|`backlight_toggle()` |Turn the backlight on or off |
|`backlight_enable()` |Turn the backlight on |
|`backlight_disable()` |Turn the backlight off |
|`backlight_step()` |Cycle through backlight levels |
|`backlight_increase()` |Increase the backlight level |
|`backlight_decrease()` |Decrease the backlight level |
|`backlight_level(x)` |Sets the backlight level to specified level |
|`get_backlight_level()` |Return the current backlight level |
|`is_backlight_enabled()`|Return whether the backlight is currently on |
### Backlight Breathing Functions

32
docs/feature_bluetooth.md
View File

@ -1,10 +1,40 @@
# Bluetooth
## Bluetooth Functionality
## Bluetooth Known Supported Hardware
Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1 Qmk has support for RN-42 HID Firmware and Bluefruit EZ Key the later of which is not produced anymore. For more recent BLE protocols currently only the Adafruit Bluefruit SPI friend is directly supported. BLE is needed to connect to iOS devices. Note iOS does not support Mouse Input.
|Board |Bluetooth Protocol |Connection Type |Rules.mk |Bluetooth Chip|
|----------------------------------------------------------------|----------------------------|----------------|---------------------------|--------------|
|[Adafruit EzKey HID]("https://www.adafruit.com/product/1535") |Bluetooth Classic | UART | BLUETOOTH = AdafruitEZKey | |
|Rover Networks RN-42 (Sparkfun Bluesmirf) |Bluetooth Classic | UART | BLUETOOTH = RN42 | RN-42 |
|[Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633)|Bluetooth Low Energy | SPI | BLUETOOTH = AdafruitBLE | nRF5182 |
Not Supported Yet but possible:
* [Bluefruit LE UART Friend](https://www.adafruit.com/product/2479). [Possible tmk implementation found in](https://github.com/tmk/tmk_keyboard/issues/514)
* HC-05 boards flashed with RN-42 firmware. They apparently both use the CSR BC417 Chip. Flashing it with RN-42 firmware gives it HID capability.
* [Sparkfun Bluetooth mate](https://www.sparkfun.com/products/14839)
* HM-13 based boards
### Adafruit BLE SPI Friend
Currently The only bluetooth chipset supported by QMK is the Adafruit Bluefruit SPI Friend. It's a Nordic nRF5182 based chip running Adafruit's custom firmware. Data is transmitted via Adafruit's SDEP over Hardware SPI. The [Feather 32u4 Bluefruit LE](https://www.adafruit.com/product/2829) is supported as it's an AVR mcu connected via SPI to the Nordic BLE chip with Adafruit firmware. If Building a custom board with the SPI friend it would be easiest to just use the pin selection that the 32u4 feather uses but you can change the pins in the config.h options with the following defines:
* #define AdafruitBleResetPin D4
* #define AdafruitBleCSPin B4
* #define AdafruitBleIRQPin E6
A Bluefruit UART friend can be converted to an SPI friend, however this [requires](https://github.com/qmk/qmk_firmware/issues/2274) some reflashing and soldering directly to the MDBT40 chip.
## Adafruit EZ-Key hid
This requires [some hardware changes](https://www.reddit.com/r/MechanicalKeyboards/comments/3psx0q/the_planck_keyboard_with_bluetooth_guide_and/?ref=search_posts), but can be enabled via the Makefile. The firmware will still output characters via USB, so be aware of this when charging via a computer. It would make sense to have a switch on the Bluefruit to turn it off at will.
<!-- FIXME: Document bluetooth support more completely. -->
## Bluetooth Rules.mk Options
Use only one of these
* BLUETOOTH_ENABLE = yes (Legacy Option)
* BLUETOOTH = RN42
* BLUETOOTH = AdafruitEZKey
* BLUETOOTH = AdafruitBLE
## Bluetooth Keycodes

53
docs/feature_bootmagic.md
View File

@ -11,7 +11,15 @@ There are three separate but related features that allow you to change the behav
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 = yes
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
@ -57,6 +65,7 @@ Hold down the Bootmagic key (Space by default) and the desired hotkey while plug
|`MAGIC_UNNO_GUI` | |Enable the GUI keys |
|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides (for macOS)|
|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Left Alt and Left GUI |
|`MAGIC_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Left Alt and GUI swap |
|`MAGIC_SWAP_BACKSLASH_BACKSPACE` | |Swap `\` and Backspace |
|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`| |Unswap `\` and Backspace |
|`MAGIC_SWAP_CONTROL_CAPSLOCK` | |Swap Left Control and Caps Lock |
@ -98,3 +107,45 @@ If you would like to change the hotkey assignments for Bootmagic, `#define` thes
|`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
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.
To enable this version of Bootmagic, you need to enable it in your `rules.mk` with:
```make
BOOTMAGIC_ENABLE = lite
```
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
#define BOOTMAGIC_LITE_ROW 0
#define BOOTMAGIC_LITE_COLUMN 1
```
By default, these are set to 0 and 0, which is usually the "ESC" key on a majority of keyboards.
And to trigger the bootloader, you hold this key down when plugging the keyboard in. Just the single key.
## Advanced Bootmagic Lite
The `bootmagic_lite` function is defined weakly, so that you can replace this in your code, if you need. A great example of this is the Zeal60 boards that have some additional handling needed.
To replace the function, all you need to do is add something like this to your code:
```c
void bootmagic_lite(void) {
matrix_scan();
wait_ms(DEBOUNCING_DELAY * 2);
matrix_scan();
if (matrix_get_row(BOOTMAGIC_LITE_ROW) & (1 << BOOTMAGIC_LITE_COLUMN)) {
// Jump to bootloader.
bootloader_jump();
}
}
```
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.

89
docs/feature_combo.md Normal file
View File

@ -0,0 +1,89 @@
# 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.
To enable this feature, yu 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 -->
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.
```c
const uint16_t PROGMEM test_combo[] = {KC_A, KC_B, COMBO_END};
combo_t key_combos[COMBO_COUNT] = {COMBO(test_combo, KC_ESC)};
```
This will send "Escape" if you hit the A and B keys.
!> This method only supports [basic keycodes](keycodes_basic.md). See the examples for more control.
!> You cannot reuse (share) keys in combos. Each key should only belong to a single combo.
## Examples
If you want to add a list, then you'd use something like this:
```c
enum combos {
AB_ESC,
JK_TAB
}
const uint16_t PROGMEM ab_combo[] = {KC_A, KC_B, COMBO_END};
const uint16_t PROGMEM jk_combo[] = {KC_J, KC_K, COMBO_END};
combo_t key_combos[COMBO_COUNT] = {
[AB_ESC] = COMBO(ab_combo, KC_ESC),
[JK_TAB] = COMBO(jk_combo, KC_TAB)
};
```
For a more complicated implementation, you can use the `process_combo_event` function to add custom handling.
```c
enum combo_events {
ZC_COPY,
XV_PASTE
};
const uint16_t PROGMEM copy_combo[] = {KC_Z, KC_C, COMBO_END};
const uint16_t PROGMEM paste_combo[] = {KC_X, KC_V, COMBO_END};
combo_t key_combos[COMBO_COUNT] = {
[ZC_COPY] = COMBO_ACTION(copy_combo),
[XV_PASTE] = COMBO_ACTION(paste_combo),
};
void process_combo_event(uint8_t combo_index, bool pressed) {
switch(combo_index) {
case ZC_COPY:
if (pressed) {
register_code(KC_LCTL);
register_code(KC_C);
unregister_code(KC_C);
unregister_code(KC_LCTL);
}
break;
case XV_PASTE:
if (pressed) {
register_code(KC_LCTL);
register_code(KC_V);
unregister_code(KC_V);
unregister_code(KC_LCTL);
}
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.
## Additional Configuration
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`.

48
docs/feature_encoders.md Normal file
View File

@ -0,0 +1,48 @@
# Encoders
Basic encoders are supported by adding this to your `rules.mk`:
ENCODER_ENABLE = yes
and this to your `config.h`:
#define NUMBER_OF_ENCODERS 1
#define ENCODERS_PAD_A { B12 }
#define ENCODERS_PAD_B { B13 }
Each PAD_A/B variable defines an array so multiple encoders can be defined, e.g.:
#define ENCODERS_PAD_A { encoder1a, encoder2a }
#define ENCODERS_PAD_B { encoder1b, encoder2b }
If your encoder's clockwise directions are incorrect, you can swap the A & B pad definitions.
Additionally, the resolution can be specified in the same file (the default & suggested is 4):
#define ENCODER_RESOLUTION 4
## Callbacks
The callback functions can be inserted into your `<keyboard>.c`:
void encoder_update_kb(uint8_t index, bool clockwise) {
encoder_update_user(index, clockwise);
}
or `keymap.c`:
void encoder_update_user(uint8_t index, bool clockwise) {
if (index == 0) {
if (clockwise) {
register_code(KC_PGDN);
unregister_code(KC_PGDN);
} else {
register_code(KC_PGUP);
unregister_code(KC_PGUP);
}
}
}
## Hardware
The A an B lines of the encoders should be wired directly to the MCU, and the C/common lines should be wired to ground.

6
docs/feature_layouts.md
View File

@ -53,6 +53,8 @@ but the `LAYOUT_<layout>` variable must be defined in `<folder>.h` as well.
## Tips for Making Layouts Keyboard-Agnostic
### Includes
Instead of using `#include "planck.h"`, you can use this line to include whatever `<keyboard>.h` (`<folder>.h` should not be included here) file that is being compiled:
#include QMK_KEYBOARD_H
@ -72,3 +74,7 @@ For example:
```
Note that the names are lowercase and match the folder/file names for the keyboard/revision exactly.
### Keymaps
In order to support both split and non-split keyboards with the same layout, you need to use the keyboard agnostic `LAYOUT_<layout name>` macro in your keymap. For instance, in order for a Let's Split and Planck to share the same layout file, you need to use `LAYOUT_ortho_4x12` instead of `LAYOUT_planck_grid` or just `{}` for a C array.

111
docs/feature_leader_key.md
View File

@ -5,10 +5,11 @@ If you've ever used Vim, you know what a Leader key is. If not, you're about to
That's what `KC_LEAD` does. Here's an example:
1. Pick a key on your keyboard you want to use as the Leader key. Assign it the keycode `KC_LEAD`. This key would be dedicated just for this -- it's a single action key, can't be used for anything else.
2. Include the line `#define LEADER_TIMEOUT 300` somewhere in your keymap.c file, probably near the top. The 300 there is 300ms -- that's how long you have for the sequence of keys following the leader. You can tweak this value for comfort, of course.
3. Within your `matrix_scan_user` function, do something like this:
2. Include the line `#define LEADER_TIMEOUT 300` in your `config.h`. This sets the timeout for the `KC_LEAD` key. Specifically, when you press the `KC_LEAD` key, you only have a certain amount of time to complete the Leader Key sequence. The `300` here sets that to 300ms, and you can increase this value to give you more time to hit the sequence. But any keys pressed during this timeout are intercepted and not sent, so you may want to keep this value low. .
* By default, this timeout is how long after pressing `KC_LEAD` to complete your entire sequence. This may be very low for some people. So you may want to increase this timeout. Optionally, you may want to enable the `LEADER_PER_KEY_TIMING` option, which resets the timeout after each key is tapped. This allows you to maintain a low value here, but still be able to use the longer sequences. To enable this option, add `#define LEADER_PER_KEY_TIMING` to your `config.h`.
3. Within your `matrix_scan_user` function, add something like this:
```
```c
LEADER_EXTERNS();
void matrix_scan_user(void) {
@ -39,3 +40,107 @@ void matrix_scan_user(void) {
As you can see, you have a few function. You can use `SEQ_ONE_KEY` for single-key sequences (Leader followed by just one key), and `SEQ_TWO_KEYS`, `SEQ_THREE_KEYS` up to `SEQ_FIVE_KEYS` for longer sequences.
Each of these accepts one or more keycodes as arguments. This is an important point: You can use keycodes from **any layer on your keyboard**. That layer would need to be active for the leader macro to fire, obviously.
## Adding Leader Key Support in the `rules.mk`
To add support for Leader Key you simply need to add a single line to your keymap's `rules.mk`:
```make
LEADER_ENABLE = yes
```
## Per Key Timing on Leader keys
Rather than relying on an incredibly high timeout for long leader key strings or those of us without 200wpm typing skills, we can enable per key timing to ensure that each key pressed provides us with more time to finish our stroke. This is incredibly helpful with leader key emulation of tap dance (read: multiple taps of the same key like C, C, C).
In order to enable this, place this in your `config.h`:
```c
#define LEADER_PER_KEY_TIMING
```
After this, it's recommended that you lower your `LEADER_TIMEOUT` to something less that 300ms.
```c
#define LEADER_TIMEOUT 250
```
Now, something like this won't seem impossible to do without a 1000MS leader key timeout:
```c
SEQ_THREE_KEYS(KC_C, KC_C, KC_C) {
SEND_STRING("Per key timing is great!!!");
}
```
## Strict Key Processing
By default, the Leader Key feature will filter the keycode out of [`Mod-Tap`](feature_advanced_keycodes.md#mod-tap) and [`Layer Tap`](feature_advanced_keycodes.md#switching-and-toggling-layers) functions when checking for the Leader sequences. That means if you're using `LT(3, KC_A)`, it will pick this up as `KC_A` for the sequence, rather than `LT(3, KC_A)`, giving a more expected behavior for newer users.
While, this may be fine for most, if you want to specify the whole keycode (eg, `LT(3, KC_A)` from the example above) in the sequence, you can enable this by added `#define LEADER_KEY_STRICT_KEY_PROCESSING` to your `config.h` file. This well then disable the filtering, and you'll need to specify the whole keycode.
## Customization
The Leader Key feature has some additional customization to how the Leader Key feature works. It has two functions that can be called at certain parts of the process. Namely `leader_start()` and `leader_end()`.
The `leader_start()` function is called when you tap the `KC_LEAD` key, and the `leader_end()` function is called when either the leader sequence is completed, or the leader timeout is hit.
You can add these functions to your code (`keymap.c` usually) to add feedback to the Leader sequences (such as beeping or playing music).
```c
void leader_start(void) {
// sequence started
}
void leader_end(void) {
// sequence ended (no success/failuer detection)
}
```
### Example
This example will play the Mario "One Up" sound when you hit `KC_LEAD` to start the Leader Sequence, and will play "All Star" if it completes successfully or "Rick Roll" you if it fails.
```c
bool did_leader_succeed;
#ifdef AUDIO_ENABLE
float leader_start[][2] = SONG(ONE_UP_SOUND );
float leader_succeed[][2] = SONG(ALL_STAR);
float leader_fail[][2] = SONG(RICK_ROLL);
#endif
LEADER_EXTERNS();
void matrix_scan_user(void) {
LEADER_DICTIONARY() {
did_leader_succeed = leading = false;
SEQ_ONE_KEY(KC_E) {
// Anything you can do in a macro.
SEND_STRING(SS_LCTRL(SS_LSFT("t")));
did_leader_succeed = true;
} else
SEQ_TWO_KEYS(KC_E, KC_D) {
SEND_STRING(SS_LGUI("r")"cmd"SS_TAP(KC_ENTER)SS_LCTRL("c"));
did_leader_succeed = true;
}
leader_end();
}
}
void leader_start(void) {
#ifdef AUDIO_ENABLE
PLAY_SONG(leader_start);
#endif
}
void leader_end(void) {
if (did_leader_succeed) {
#ifdef AUDIO_ENABLE
PLAY_SONG(leader_succeed);
#endif
} else {
#ifdef AUDIO_ENABLE
PLAY_SONG(leader_fail);
#endif
}
}
```

164
docs/feature_macros.md
View File

@ -12,24 +12,28 @@ Here is an example `keymap.c` for a two-key keyboard:
```c
enum custom_keycodes {
MY_CUSTOM_MACRO = SAFE_RANGE
QMKBEST = SAFE_RANGE,
};
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
if (record->event.pressed) {
switch(keycode) {
case MY_CUSTOM_MACRO:
SEND_STRING("QMK is the best thing ever!"); // this is our macro!
return false;
}
}
return true;
switch (keycode) {
case QMKBEST:
if (record->event.pressed) {
// when keycode QMKBEST is pressed
SEND_STRING("QMK is the best thing ever!");
} else {
// when keycode QMKBEST is released
}
break;
}
return true;
};
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = {
{MY_CUSTOM_MACRO, KC_ESC}
}
[0] = {
{QMKBEST, KC_ESC}
}
};
```
@ -37,7 +41,7 @@ What happens here is this:
We first define a new custom keycode in the range not occupied by any other keycodes.
Then we use the `process_record_user` function, which is called whenever a key is pressed or released, to check if our custom keycode has been activated.
If yes, we send the string `"QMK is the best thing ever!"` to the computer via the `SEND_STRING` macro (this is a C preprocessor macro, not to be confused with QMK macros).
We return `false` to indicate to the caller that the key press we just processed need not be processed any further.
We return `true` to indicate to the caller that the key press we just processed should continue to be processed as normal (as we didn't replace or alter the functionality).
Finally, we define the keymap so that the first button activates our macro and the second button is just an escape button.
You might want to add more than one macro.
@ -45,28 +49,42 @@ You can do that by adding another keycode and adding another case to the switch
```c
enum custom_keycodes {
MY_CUSTOM_MACRO = SAFE_RANGE,
MY_OTHER_MACRO
QMKBEST = SAFE_RANGE,
QMKURL,
MY_OTHER_MACRO
};
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
if (record->event.pressed) {
switch(keycode) {
case MY_CUSTOM_MACRO:
SEND_STRING("QMK is the best thing ever!");
return false;
case MY_OTHER_MACRO:
SEND_STRING(SS_LCTRL("ac")); // selects all and copies
return false;
}
}
return true;
switch (keycode) {
case QMKBEST:
if (record->event.pressed) {
// when keycode QMKBEST is pressed
SEND_STRING("QMK is the best thing ever!");
} else {
// when keycode QMKBEST is released
}
break;
case QMKURL:
if (record->event.pressed) {
// when keycode QMKURL is pressed
SEND_STRING("https://qmk.fm/" SS_TAP(X_ENTER));
} else {
// when keycode QMKURL is released
}
break;
case MY_OTHER_MACRO:
if (record->event.pressed) {
SEND_STRING(SS_LCTRL("ac")); // selects all and copies
}
break;
}
return true;
};
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = {
{MY_CUSTOM_MACRO, MY_OTHER_MACRO}
}
[0] = {
{MY_CUSTOM_MACRO, MY_OTHER_MACRO}
}
};
```
@ -136,21 +154,21 @@ By default QMK assumes you don't have any macros. To define your macros you crea
```c
const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
if (record->event.pressed) {
switch(id) {
case 0:
return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END);
case 1:
return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END);
}
}
return MACRO_NONE;
if (record->event.pressed) {
switch(id) {
case 0:
return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END);
case 1:
return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END);
}
}
return MACRO_NONE;
};
```
This defines two macros which will be run when the key they are assigned to is pressed. If instead you'd like them to run when the key is released you can change the if statement:
if (!record->event.pressed) {
if (!record->event.pressed) {
### Macro Commands
@ -169,21 +187,21 @@ Use the `M()` function within your `KEYMAP()` to call a macro. For example, here
```c
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = KEYMAP(
M(0), M(1)
),
[0] = KEYMAP(
M(0), M(1)
),
};
const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
if (record->event.pressed) {
switch(id) {
case 0:
return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END);
case 1:
return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END);
}
}
return MACRO_NONE;
if (record->event.pressed) {
switch(id) {
case 0:
return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END);
case 1:
return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END);
}
}
return MACRO_NONE;
};
```
@ -198,9 +216,9 @@ If you have a bunch of macros you want to refer to from your keymap while keepin
#define M_BYE M(1)
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = KEYMAP(
M_HI, M_BYE
),
[0] = KEYMAP(
M_HI, M_BYE
),
};
```
@ -213,11 +231,11 @@ There are some functions you may find useful in macro-writing. Keep in mind that
This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is
```c
if (record->event.pressed) {
// on keydown
} else {
// on keyup
}
if (record->event.pressed) {
// on keydown
} else {
// on keyup
}
```
### `register_code(<kc>);`
@ -228,6 +246,12 @@ This sends the `<kc>` keydown event to the computer. Some examples would be `KC_
Parallel to `register_code` function, this sends the `<kc>` keyup event to the computer. If you don't use this, the key will be held down until it's sent.
### `tap_code(<kc>);`
This will send `register_code(<kc>)` and then `unregister_code(<kc>)`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it).
If you're having issues with taps (un)registering, you can add a delay between the register and unregister events by setting `#define TAP_CODE_DELAY 100` in your `config.h` file. The value is in milliseconds.
### `clear_keyboard();`
This will clear all mods and keys currently pressed.
@ -246,16 +270,16 @@ This example defines a macro which sends `Ctrl-C` when pressed down, and `Ctrl-V
```c
const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
switch(id) {
case 0: {
if (record->event.pressed) {
return MACRO( D(LCTL), T(C), U(LCTL), END );
} else {
return MACRO( D(LCTL), T(V), U(LCTL), END );
}
break;
}
}
return MACRO_NONE;
switch(id) {
case 0: {
if (record->event.pressed) {
return MACRO( D(LCTL), T(C), U(LCTL), END );
} else {
return MACRO( D(LCTL), T(V), U(LCTL), END );
}
break;
}
}
return MACRO_NONE;
};
```

18
docs/feature_ps2_mouse.md
View File

@ -6,6 +6,24 @@ To hook up a Trackpoint, you need to obtain a Trackpoint module (i.e. harvest fr
There are three available modes for hooking up PS/2 devices: USART (best), interrupts (better) or busywait (not recommended).
### The Cirtuitry between Trackpoint and Controller
To get the things working, a 4.7K drag is needed between the two lines DATA and CLK and the line 5+.
```
DATA ----------+--------- PIN
|
4.7K
|
MODULE 5+ --------+--+--------- PWR CONTROLLER
|
4.7K
|
CLK ------+------------ PIN
```
### Busywait Version
Note: This is not recommended, you may encounter jerky movement or unsent inputs. Please use interrupt or USART version if possible.

25
docs/feature_rgb_matrix.md
View File

@ -140,6 +140,7 @@ These are the effects that are currently available:
RGB_MATRIX_RAINBOW_PINWHEELS,
RGB_MATRIX_RAINBOW_MOVING_CHEVRON,
RGB_MATRIX_JELLYBEAN_RAINDROPS,
RGB_MATRIX_DIGITAL_RAIN,
#ifdef RGB_MATRIX_KEYPRESSES
RGB_MATRIX_SOLID_REACTIVE,
RGB_MATRIX_SPLASH,
@ -149,6 +150,30 @@ These are the effects that are currently available:
#endif
RGB_MATRIX_EFFECT_MAX
};
You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `config.h`:
|Define |Description |
|---------------------------------------------------|--------------------------------------------|
|`#define DISABLE_RGB_MATRIX_ALPHAS_MODS` |Disables `RGB_MATRIX_ALPHAS_MODS` |
|`#define DISABLE_RGB_MATRIX_DUAL_BEACON` |Disables `RGB_MATRIX_DUAL_BEACON` |
|`#define DISABLE_RGB_MATRIX_GRADIENT_UP_DOWN` |Disables `RGB_MATRIX_GRADIENT_UP_DOWN` |
|`#define DISABLE_RGB_MATRIX_RAINDROPS` |Disables `RGB_MATRIX_RAINDROPS` |
|`#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_BEACON` |Disables `RGB_MATRIX_RAINBOW_BEACON` |
|`#define DISABLE_RGB_MATRIX_RAINBOW_PINWHEELS` |Disables `RGB_MATRIX_RAINBOW_PINWHEELS` |
|`#define DISABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON`|Disables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON`|
|`#define DISABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS` |Disables `RGB_MATRIX_JELLYBEAN_RAINDROPS` |
|`#define DISABLE_RGB_MATRIX_DIGITAL_RAIN` |Disables `RGB_MATRIX_DIGITAL_RAIN` |
|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE` |Disables `RGB_MATRIX_SOLID_REACTIVE` |
|`#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` |
## Custom layer effects

62
docs/feature_rgblight.md
View File

@ -63,8 +63,6 @@ Changing the **Value** sets the overall brightness.
|`RGB_MODE_GRADIENT`|`RGB_M_G` |Static gradient animation mode |
|`RGB_MODE_RGBTEST` |`RGB_M_T` |Red, Green, Blue test animation mode |
?> For backwards compatibility, `RGB_SMOD` is another alias of `RGB_MOD`.
## Configuration
Your RGB lighting can be configured by placing these `#define`s in your `config.h`:
@ -79,28 +77,41 @@ Your RGB lighting can be configured by placing these `#define`s in your `config.
## Animations
Not only can this lighting be whatever color you want, if `RGBLIGHT_ANIMATIONS` is defined, you also have a number of animation modes at your disposal:
|Mode |Description |
|-----|---------------------|
|1 |Solid color |
|2-5 |Solid color breathing|
|6-8 |Cycling rainbow |
|9-14 |Swirling rainbow |
|15-20|Snake |
|21-23|Knight |
|24 |Christmas |
|25-34|Static gradient |
|35 |RGB Test |
|36 |Alternating |
Not only can this lighting be whatever color you want,
if `RGBLIGHT_EFFECT_xxxx` or `RGBLIGHT_ANIMATIONS` is defined, you also have a number of animation modes at your disposal:
|Mode number symbol |Additional number |Description |
|-----------------------------|-------------------|---------------------------------------|
|`RGBLIGHT_MODE_STATIC_LIGHT` | *None* |Solid color (this mode is always enabled) |
|`RGBLIGHT_MODE_BREATHING` | 0,1,2,3 |Solid color breathing |
|`RGBLIGHT_MODE_RAINBOW_MOOD` | 0,1,2 |Cycling rainbow |
|`RGBLIGHT_MODE_RAINBOW_SWIRL`| 0,1,2,3,4,5 |Swirling rainbow |
|`RGBLIGHT_MODE_SNAKE` | 0,1,2,3,4,5 |Snake |
|`RGBLIGHT_MODE_KNIGHT` | 0,1,2 |Knight |
|`RGBLIGHT_MODE_CHRISTMAS` | *None* |Christmas |
|`RGBLIGHT_MODE_STATIC_GRADIENT`| 0,1,..,9 |Static gradient |
|`RGBLIGHT_MODE_RGB_TEST` | *None* |RGB Test |
|`RGBLIGHT_MODE_ALTERNATING` | *None* |Alternating |
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.
The following options can be used to tweak the various animations:
|Define |Default |Description |
|------------------------------------|-------------|-------------------------------------------------------------------------------------|
|`RGBLIGHT_ANIMATIONS` |*Not defined*|If defined, enables additional animation modes |
|`RGBLIGHT_EFFECT_BREATHING` |*Not defined*|If defined, enable breathing animation mode. |
|`RGBLIGHT_EFFECT_RAINBOW_MOOD` |*Not defined*|If defined, enable rainbow mood animation mode. |
|`RGBLIGHT_EFFECT_RAINBOW_SWIRL` |*Not defined*|If defined, enable rainbow swirl animation mode. |
|`RGBLIGHT_EFFECT_SNAKE` |*Not defined*|If defined, enable snake animation mode. |
|`RGBLIGHT_EFFECT_KNIGHT` |*Not defined*|If defined, enable knight animation mode. |
|`RGBLIGHT_EFFECT_CHRISTMAS` |*Not defined*|If defined, enable christmas animation mode. |
|`RGBLIGHT_EFFECT_STATIC_GRADIENT` |*Not defined*|If defined, enable static gradient mode. |
|`RGBLIGHT_EFFECT_RGB_TEST` |*Not defined*|If defined, enable RGB test animation mode. |
|`RGBLIGHT_EFFECT_ALTERNATING` |*Not defined*|If defined, enable alternating animation mode. |
|`RGBLIGHT_ANIMATIONS` |*Not defined*|If defined, enables all additional animation modes |
|`RGBLIGHT_EFFECT_BREATHE_CENTER` |`1.85` |Used to calculate the curve for the breathing animation. Valid values are 1.0 to 2.7 |
|`RGBLIGHT_EFFECT_BREATHE_MAX` |`255` |The maximum brightness for the breathing mode. Valid values are 1 to 255 |
|`RGBLIGHT_EFFECT_SNAKE_LENGTH` |`4` |The number of LEDs to light up for the "Snake" animation |
@ -109,6 +120,7 @@ The following options can be used to tweak the various animations:
|`RGBLIGHT_EFFECT_KNIGHT_LED_NUM` |`RGBLED_NUM` |The number of LEDs to have the "Knight" animation travel |
|`RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL`|`1000` |How long to wait between light changes for the "Christmas" animation, in milliseconds|
|`RGBLIGHT_EFFECT_CHRISTMAS_STEP` |`2` |The number of LEDs to group the red/green colors by for the "Christmas" animation |
|`RGBLIGHT_RAINBOW_SWIRL_RANGE` |`360` |Range adjustment for the rainbow swirl effect to get different swirls |
You can also modify the speeds that the different modes animate at:
@ -149,6 +161,24 @@ If you need to change your RGB lighting in code, for example in a macro to chang
|`rgblight_sethsv(h, s, v)` |Set all LEDs to the given HSV value where `h` is between 0 and 360 and `s`/`v` are between 0 and 255 |
|`rgblight_sethsv_noeeprom(h, s, v)`|Set all LEDs to the given HSV value where `h` is between 0 and 360 and `s`/`v` are between 0 and 255 (not written to EEPROM) |
|`rgblight_sethsv_at(h, s, v, led)` |Set a single LED to the given HSV value, where `h` is between 0 and 360, `s`/`v` are between 0 and 255, and `led` is between 0 and `RGBLED_NUM` (not written to EEPROM)|
|`rgblight_toggle()` |Toggle all LEDs between on and off |
|`rgblight_toggle_noeeprom()` |Toggle all LEDs between on and off (not written to EEPROM) |
|`rgblight_step()` |Change the mode to the next RGB animation in the list of enabled RGB animations |
|`rgblight_step_noeeprom()` |Change the mode to the next RGB animation in the list of enabled RGB animations (not written to EEPROM) |
|`rgblight_step_reverse()` |Change the mode to the previous RGB animation in the list of enabled RGB animations |
|`rgblight_step_reverse_noeeprom()` |Change the mode to the previous RGB animation in the list of enabled RGB animations (not written to EEPROM) |
|`rgblight_increase_hue()` |Increase the hue for all LEDs. This wraps around at maximum hue |
|`rgblight_increase_hue_noeeprom()` |Increase the hue for all LEDs. This wraps around at maximum hue (not written to EEPROM) |
|`rgblight_decrease_hue()` |Decrease the hue for all LEDs. This wraps around at minimum hue |
|`rgblight_decrease_hue_noeeprom()` |Decrease the hue for all LEDs. This wraps around at minimum hue (not written to EEPROM) |
|`rgblight_increase_sat()` |Increase the saturation for all LEDs. This wraps around at maximum saturation |
|`rgblight_increase_sat_noeeprom()` |Increase the saturation for all LEDs. This wraps around at maximum saturation (not written to EEPROM) |
|`rgblight_decrease_sat()` |Decrease the saturation for all LEDs. This wraps around at minimum saturation |
|`rgblight_decrease_sat_noeeprom()` |Decrease the saturation for all LEDs. This wraps around at minimum saturation (not written to EEPROM) |
|`rgblight_increase_val()` |Increase the value for all LEDs. This wraps around at maximum value |
|`rgblight_increase_val_noeeprom()` |Increase the value for all LEDs. This wraps around at maximum value (not written to EEPROM) |
|`rgblight_decrease_val()` |Decrease the value for all LEDs. This wraps around at minimum value |
|`rgblight_decrease_val_noeeprom()` |Decrease the value for all LEDs. This wraps around at minimum value (not written to EEPROM) |
Additionally, [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h) defines several predefined shortcuts for various colors. Feel free to add to this list!

38
docs/feature_tap_dance.md
View File

@ -26,6 +26,8 @@ This array specifies what actions shall be taken when a tap-dance key is in acti
The first option is enough for a lot of cases, that just want dual roles. For example, `ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT)` will result in `Space` being sent on single-tap, `Enter` otherwise.
!> Keep in mind that only [basic keycodes](keycodes_basic.md) are supported here. Custom keycodes are not supported.
And that's the bulk of it!
And now, on to the explanation of how it works!
@ -183,29 +185,11 @@ Below is a specific example:
## Setup
You will need a few things that can be used for 'Quad Function Tap-Dance'. The suggested setup is to create a user directory for yourself. This directory will contain rules.mk `<your_name>.c` and `<your_name>.h`. This directory should be called `<your_name>`, and located in the top level `users` directory. There should already be a few examples to look at there.
You will need a few things that can be used for 'Quad Function Tap-Dance'.
### In `/qmk_firmware/users/<your_name>/rules.mk`
Put the following:
```c
TAP_DANCE_ENABLE = yes
SRC += your_name.c
```
Pretty simple. It is a nice way to keep some rules common on all your keymaps.
### In `/qmk_firmware/users/<your_name>/<your_name>.h`
You will need a few things in this file:
You'll need to add these to the top of your `keymap.c` file, before your keymap.
```c
#pragma once
#include "quantum.h"
#include "process_keycode/process_tap_dance.h"
typedef struct {
bool is_press_action;
int state;
@ -232,18 +216,12 @@ int cur_dance (qk_tap_dance_state_t *state);
//for the x tap dance. Put it here so it can be used in any keymap
void x_finished (qk_tap_dance_state_t *state, void *user_data);
void x_reset (qk_tap_dance_state_t *state, void *user_data);
```
### In `/qmk_firmware/users/<your_name>/<your_name>.c`
And then in your user's `.c` file you implement the functions above:
Now, at the bottom of your `keymap.c` file, you'll need to add the following:
```c
#include "<your_name>.h"
#include "quantum.h"
#include "action.h"
#include "process_keycode/process_tap_dance.h"
/* Return an integer that corresponds to what kind of tap dance should be executed.
*
* How to figure out tap dance state: interrupted and pressed.
@ -333,4 +311,6 @@ qk_tap_dance_action_t tap_dance_actions[] = {
};
```
And then simply use `TD(X_CTL)` anywhere in your keymap after including `<your_name>.h`.
And then simply use `TD(X_CTL)` anywhere in your keymap.
If you want to implement this in your userspace, then you may want to check out how [DanielGGordon](https://github.com/qmk/qmk_firmware/tree/master/users/gordon) has implemented this in their userspace.

177
docs/feature_unicode.md
View File

@ -1,43 +1,172 @@
# Unicode Support
There are three Unicode keymap definition method available in QMK:
There are three Unicode keymap definition methods available in QMK:
## UNICODE_ENABLE
Supports Unicode input up to 0xFFFF. The keycode function is `UC(n)` in
keymap file, where *n* is a 4 digit hexadecimal.
Supports Unicode up to `0xFFFF`. The keycode function is `UC(n)` in the keymap file, where _n_ is a 4 digit hexadecimal number.
## UNICODEMAP_ENABLE
Supports Unicode up to 0xFFFFFFFF. You need to maintain a separate mapping
table `const uint32_t PROGMEM unicode_map[] = {...}` in your keymap file.
The keycode function is `X(n)` where *n* is the array index of the mapping
table.
Supports Unicode up to `0x10FFFF` (all possible code points). You need to maintain a separate mapping table `const uint32_t PROGMEM unicode_map[] = {...}` in your keymap file. The keycode function is `X(n)`, where _n_ is an array index into the mapping table.
And you may want to have an enum to make reference easier. So you'd want to add something like this to your keymap:
```c
enum unicode_names {
BANG,
IRONY,
SNEK,
};
const uint32_t PROGMEM unicode_map[] = {
[BANG] = 0x203D, // ‽
[IRONY] = 0x2E2E, // ⸮
[SNEK] = 0x1F40D, // 🐍
};
```
Make sure that the order for both matches.
## UCIS_ENABLE
TBD
Supports Unicode up to `0x10FFFF` (all possible code points). As with `UNICODEMAP`, you may want to maintain a mapping table in your keymap file. However, there are no built-in keycodes for this feature — you will have to add a keycode or function that calls `qk_ucis_start()`. Once it's been called, you can type the mnemonic for your character, then hit Space or Enter to complete it or Esc to cancel. If the mnemonic matches an entry in your table, the typed text will automatically be erased and the corresponding Unicode sequence inserted.
Unicode input in QMK works by inputing a sequence of characters to the OS,
sort of like macro. Unfortunately, each OS has different ideas on how Unicode is inputted.
For instance, you would need to have a table like this in your keymap:
This is the current list of Unicode input method in QMK:
```c
const qk_ucis_symbol_t ucis_symbol_table[] = UCIS_TABLE
(
UCIS_SYM("poop", 0x1f4a9),
UCIS_SYM("rofl", 0x1f923),
UCIS_SYM("kiss", 0x1f619)
);
```
* UC_OSX: MacOS Unicode Hex Input support. Works only up to 0xFFFF. Disabled by default. To enable: go to System Preferences -> Keyboard -> Input Sources, and enable Unicode Hex.
* UC_OSX_RALT: Same as UC_OSX, but sends the Right Alt key for unicode input
* UC_LNX: Unicode input method under Linux. Works up to 0xFFFFF. Should work almost anywhere on ibus enabled distros. Without ibus, this works under GTK apps, but rarely anywhere else.
* UC_WIN: (not recommended) Windows built-in Unicode input. To enable: create registry key under `HKEY_CURRENT_USER\Control Panel\Input Method\EnableHexNumpad` of type `REG_SZ` called `EnableHexNumpad`, set its value to 1, and reboot. This method is not recommended because of reliability and compatibility issue, use WinCompose method below instead.
* UC_WINC: Windows Unicode input using WinCompose. Requires [WinCompose](https://github.com/samhocevar/wincompose). Works reliably under many (all?) variations of Windows.
You run the function, and then type "rofl" and hit enter, it should backspace remove "rofl" and input the `0x1f923` unicode.
# Additional Language Support
### Customization
There are several functions that you can add to your keymap to customize the functionality of this feature.
* `void qk_ucis_start_user(void)` - This runs when you run the "start" function, and can be used to provide feedback. By default, it types out a keyboard emoji.
* `void qk_ucis_success(uint8_t symbol_index)` - This runs when the unicode input has matched something, and has completed. Default doesn't do anything.
* `void qk_ucis_symbol_fallback (void)` - This runs if the input text doesn't match anything. The default function falls back to trying that input as a unicode code.
You can find the default implementations of these functions in [`process_ucis.c`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_ucis.c).
## Input Modes
Unicode input in QMK works by inputting a sequence of characters to the OS, sort of like a macro. Unfortunately, the way this is done differs for each platform. Specifically, each platform requires a different combination of keys to trigger Unicode input. Therefore, a corresponding input mode has to be set in QMK.
The following input modes are available:
* **`UC_OSX`**: Mac OS X built-in Unicode hex input. Supports code points up to `0xFFFF` (`0x10FFFF` with `UNICODEMAP`).
To enable, go to _System Preferences > Keyboard > Input Sources_, add _Unicode Hex Input_ to the list (it's under _Other_), then activate it from the input dropdown in the Menu Bar.
By default, this mode uses the left Option key (`KC_LALT`), but this can be changed by defining [`UNICODE_OSX_KEY`](#input-key-configuration) with another keycode.
* **`UC_LNX`**: Linux built-in IBus Unicode input. Supports all possible code points (`0x10FFFF`).
Enabled by default and works almost anywhere on IBus-enabled distros. Without IBus, this mode works under GTK apps, but rarely anywhere else.
* **`UC_WIN`**: _(not recommended)_ Windows built-in hex numpad Unicode input. Supports code points up to `0xFFFF`.
To enable, create a registry key under `HKEY_CURRENT_USER\Control Panel\Input Method\EnableHexNumpad` of type `REG_SZ` called `EnableHexNumpad` and set its value to `1`. This can be done from the Command Prompt by running `reg add "HKCU\Control Panel\Input Method" -v EnableHexNumpad -t REG_SZ -d 1` with administrator privileges. Afterwards, reboot.
This mode is not recommended because of reliability and compatibility issues; use the `UC_WINC` mode instead.
* **`UC_BSD`**: _(non implemented)_ Unicode input under BSD. Not implemented at this time. If you're a BSD user and want to help add support for it, please [open an issue on GitHub](https://github.com/qmk/qmk_firmware/issues).
* **`UC_WINC`**: Windows Unicode input using [WinCompose](https://github.com/samhocevar/wincompose). As of v0.8.2, supports code points up to `0xFFFFF`.
To enable, install the [latest release](https://github.com/samhocevar/wincompose/releases/latest). Once installed, WinCompose will automatically run on startup. Works reliably under all version of Windows supported by the app.
By default, this mode uses the right Alt key (`KC_RALT`), but this can be changed in the WinCompose settings and by defining [`UNICODE_WINC_KEY`](#input-key-configuration) with another keycode.
### Switching Input Modes
There are two ways to set the input mode for Unicode: by keycode or by function. Keep in mind that both methods write to persistent storage (EEPROM), and are loaded each time the keyboard starts. So once you've set it the first time, you don't need to set it again unless you want to change it, or you've reset the EEPROM settings.
You can switch the input mode at any time by using one of the following keycodes. The easiest way is to add the ones you use to your keymap.
|Keycode |Alias |Input mode |Description |
|-----------------------|---------|-------------|-----------------------------------------|
|`UNICODE_MODE_FORWARD` |`UC_MOD` | |Cycles forwards through the available modes. [(Disabled by default)](#input-method-cycling)|
|`UNICODE_MODE_REVERSE` |`UC_RMOD`| |Cycles forwards through the available modes. [(Disabled by default)](#input-method-cycling)|
|`UNICODE_MODE_OSX` |`UC_M_OS`|`UC_OSX` |Switch to Mac OS X input. |
|`UNICODE_MODE_LNX` |`UC_M_LN`|`UC_LNX` |Switch to Linux input. |
|`UNICODE_MODE_WIN` |`UC_M_WI`|`UC_WIN` |Switch to Windows input. |
|`UNICODE_MODE_BSD` |`UC_M_BS`|`UC_BSD` |Switch to BSD input (not implemented). |
|`UNICODE_MODE_WINC` |`UC_M_WC`|`UC_WINC` |Switch to Windows input using WinCompose.|
You can also switch the input mode by calling `set_unicode_input_mode(x)` in your code, where _x_ is one of the above input mode constants (e.g. `UC_LNX`). Since the function only needs to be called once, it's recommended that you do it in `eeconfig_init_user` (or a similar function). For example:
```c
void eeconfig_init_user(void) {
set_unicode_input_mode(UC_LNX);
}
```
### Audio Feedback
If you have the [Audio feature](feature_audio.md) enabled on the board, you can set melodies to be played when you press the above keys. That way you can have some audio feedback when switching input modes.
For instance, you can add these definitions to your `config.h` file:
```c
#define UNICODE_SONG_OSX COIN_SOUND
#define UNICODE_SONG_LNX UNICODE_LINUX
#define UNICODE_SONG_BSD MARIO_GAMEOVER
#define UNICODE_SONG_WIN UNICODE_WINDOWS
#define UNICODE_SONG_WINC UNICODE_WINDOWS
```
### Additional Customization
Because Unicode is such a large and variable feature, there are a number of options that you can customize to work better on your system.
#### Start and Finish input functions
The functions for starting and finishing Unicode input on your platform can be overridden locally. Possible uses include customizing input mode behavior if you don't use the default keys, or adding extra visual/audio feedback to Unicode input.
* `void unicode_input_start(void)` – This sends the initial sequence that tells your platform to enter Unicode input mode. For example, it presses Ctrl+Shift+U on Linux and holds the Option key on Mac.
* `void unicode_input_finish(void)` – This is called to exit Unicode input mode, for example by pressing Space or releasing the Option key.
You can find the default implementations of these functions in [`process_unicode_common.c`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_unicode_common.c).
#### Input Key Configuration
Additionally, you can customize the keys used to trigger the unicode input for macOS and WinCompose by adding defines to your `config.h`
```c
#define UNICODE_OSX_KEY KC_LALT
#define UNICODE_WINC_KEY KC_RALT
```
#### Input Method Cycling
Also, you can choose which input methods are availble for cycling through. By default, this is disabled. But if you want to enabled it, then limiting it to just those modes makes sense. Note that `UNICODE_SELECTED_MODES` define is comma delimited.
```c
#define UNICODE_SELECTED_MODES UC_OSX, UC_LNX, UC_WIN, UC_BSD, UC_WINC
```
## `send_unicode_hex_string`
To type multiple characters for things like (ノಠ痊ಠ)ノ彡┻━┻, you can use `send_unicode_hex_string()` much like `SEND_STRING()` except you would use hex values separate by spaces.
For example, the table flip seen above would be `send_unicode_hex_string("0028 30CE 0CA0 75CA 0CA0 0029 30CE 5F61 253B 2501 253B")`
There are many ways to get a hex code, but an easy one is [this site](https://r12a.github.io/app-conversion/). Just make sure to convert to hexadecimal, and that is your string.
## Additional Language Support
In `quantum/keymap_extras/`, you'll see various language files - these work the same way as the alternative layout ones do. Most are defined by their two letter country/language code followed by an underscore and a 4-letter abbreviation of its name. `FR_UGRV` which will result in a `ù` when using a software-implemented AZERTY layout. It's currently difficult to send such characters in just the firmware.
# International Characters on Windows
## International Characters on Windows
[AutoHotkey](https://autohotkey.com) allows Windows users to create custom hotkeys among others.
### AutoHotkey allows Windows users to create custom hotkeys among others.
The method does not require Unicode support in the keyboard itself but depends instead of AutoHotkey running in the background.
The method does not require Unicode support in the keyboard itself but depends instead of [AutoHotkey](https://autohotkey.com) running in the background.
First you need to select a modifier combination that is not in use by any of your programs.
CtrlAltWin is not used very widely and should therefore be perfect for this.
@ -52,3 +181,11 @@ In the default script of AutoHotkey you can define custom hotkeys.
The hotkeys above are for the combination CtrlAltGui and CtrlAltGuiShift plus the letter a.
AutoHotkey inserts the Text right of `Send, ` when this combination is pressed.
### US International
If you enable the US International layout on the system, it will use punctuation to accent the characters.
For instance, typing "`a" will result in à.
You can find details on how to enable this [here](https://support.microsoft.com/en-us/help/17424/windows-change-keyboard-layout).

190
docs/feature_userspace.md
View File

@ -5,15 +5,12 @@ If you use more than one keyboard with a similar keymap, you might see the benef
* `/users/<name>/` (added to the path automatically)
* `readme.md` (optional, recommended)
* `rules.mk` (included automatically)
* `config.h` (included automatically)
* `<name>.h` (optional)
* `<name>.c` (optional)
* `config.h` (optional)
* `cool_rgb_stuff.c` (optional)
* `cool_rgb_stuff.h` (optional)
`<name>.c` will need to be added to the SRC in `rules.mk` like this:
SRC += <name>.c
Additional files may be added in the same way - it's recommended you have one named `<name>`.c/.h though.
All this only happens when you build a keymap named `<name>`, like this:
@ -23,82 +20,179 @@ For example,
make planck:jack
Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`.
Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`.
!> This `name` can be [overridden](#override-default-userspace), if needed.
## `Rules.mk`
The `rules.mk` is one of the two files that gets processed automatically. This is how you add additional source files (such as `<name>.c`) will be added when compiling.
It's highly recommended that you use `<name>.c` as the default source file to be added. And to add it, you need to add it the SRC in `rules.mk` like this:
SRC += <name>.c
Additional files may be added in the same way - it's recommended you have one named `<name>`.c/.h to start off with, though.
The `/users/<name>/rules.mk` file will be included in the build _after_ the `rules.mk` from your keymap. This allows you to have features in your userspace `rules.mk` that depend on individual QMK features that may or may not be available on a specific keyboard.
For example, if you have RGB control features shared between all your keyboards that support RGB lighting, you can add support for that if the RGBLIGHT feature is enabled:
```make
ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
# Include my fancy rgb functions source here
SRC += cool_rgb_stuff.c
endif
```
Alternatively, you can `define RGB_ENABLE` in your keymap's `rules.mk` and then check for the variable in your userspace's `rules.mk` like this:
```make
ifdef RGB_ENABLE
# Include my fancy rgb functions source here
SRC += cool_rgb_stuff.c
endif
```
### Override default userspace
By default the userspace used will be the same as the keymap name. In some situations this isn't desirable. For instance, if you use the [layout](feature_layouts.md) feature you can't use the same name for different keymaps (e.g. ANSI and ISO). You can name your layouts `mylayout-ansi` and `mylayout-iso` and add the following line to your layout's `rules.mk`:
```
USER_NAME := mylayout
```
This is also useful if you have multiple different keyboards with different features physically present on the board (such as one with RGB Lights, and one with Audio, or different number of LEDs, or connected to a different PIN on the controller).
## Configuration Options (`config.h`)
Additionally, `config.h` here will be processed like the same file in your keymap folder. This is handled separately from the `<name>.h` file.
The reason for this, is that `<name>.h` won't be added in time to add settings (such as `#define TAPPING_TERM 100`), and including the `<name.h>` file in any `config.h` files will result in compile issues.
So you should use the `config.h` for QMK settings, and the `<name>.h` file for user or keymap specific settings.
!>You should use the `config.h` for [configuration options](config_options.md), and the `<name>.h` file for user or keymap specific settings (such as the enum for layer or keycodes)
`/users/<name>/rules.mk` will be included in the build _after_ the `rules.mk` from your keymap. This allows you to have features in your userspace `rules.mk` that depend on individual QMK features that may or may not be available on a specific keyboard. For example, if you have RGB control features shared between all your keyboards that support RGB lighting, you can `define RGB_ENABLE` in your keymap `rules.mk` and then check for the variable in your userspace `rules.mk` like this:
```make
ifdef RGB_ENABLE
# Include my fancy rgb functions source here
endif
```
Because of this, any time you turn on QMK features in your `users/<name>/rules.mk`, you should conditionally enable them only if the flag isn't already defined, like this:
```make
ifndef TAP_DANCE_ENABLE
TAP_DANCE_ENABLE = yes
endif
```
This will ensure that you can explicitly turn off features for an individual keymap.
## Readme
## Readme (`readme.md`)
Please include authorship (your name, github username, email), and optionally [a license that's GPL compatible](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses).
## `Config.h`
You can use this as a template:
```
Copyright <year> <name> <email> @<github_username>
If you do add a `config,h` file, you want to make sure that it only gets processed once. So you may want to start off with something like this:
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.
```c
#ifndef USERSPACE_CONFIG_H
#define USERSPACE_CONFIG_H
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.
// Put normal config.h settings here:
#endif // !USERSPACE_CONFIG_H
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
```
You can use any option hre that you could use in your keymap's `config.h` file. You can find a list of vales [here](config_options.md).
You'd want to replace the year, name, email and github username with your info.
## Example
Additionally, this is a good place to document your code, if you wish to share it with others.
For a brief example, checkout `/users/_example/` , or for a more detailed examples check out [`template.h`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.h) and [`template.c`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.c) in `/users/drashna/` .
# Examples
### Consolidated Macros
For a brief example, checkout [`/users/_example/`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna).
For a more complicated example, checkout [`/users/drashna/`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna)'s userspace.
If you wanted to consolidate macros and other functions into your userspace for all of your keymaps, you can do that. The issue is that you then cannot call any function defined in your userspace, or it gets complicated. To better handle this, you can call the functions here and create new functions to use in individual keymaps.
## Customized Functions
QMK has a bunch of [functions](custom_quantum_functions.md) that have [`_quantum`, `_kb`, and `_user` versions](custom_quantum_functions.md#a-word-on-core-vs-keyboards-vs-keymap) that you can use. You will pretty much always want to use the user version of these functions. But the problem is that if you use them in your userspace, then you don't have a version that you can use in your keymap.
However, you can actually add support for keymap version, so that you can use it in both your userspace and your keymap!
For instance, lets looks at the `layer_state_set_user` function. Lets enable the [Tri Layer State](ref_functions.md#olkb-tri-layers) functionalitly to all of our boards, and then still have your `keymap.c` still able to use this functionality.
In your `<name.c>` file, you'd want to add this:
```c
__attribute__ ((weak))
uint32_t layer_state_set_keymap (uint32_t state) {
return state;
}
uint32_t layer_state_set_user (uint32_t state) {
state = update_tri_layer_state(state, 2, 3, 5);
return layer_state_set_keymap (state);
}
```
The `__attribute__ ((weak))` part tells the compiler that this is a placeholder function that can then be replaced by a version in your `keymap.c`. That way, you don't need to add it to your `keymap.c`, but if you do, you won't get any conflicts because the function is the same name.
The `_keymap` part here doesn't matter, it just needs to be something other than `_quantum`, `_kb`, or `_user`, since those are already in use. So you could use `layer_state_set_mine`, `layer_state_set_fn`, or anything else.
You can see a list of this and other common functions in [`template.c`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.c) in [`users/drashna`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna).
## Custom Features
Since the Userspace feature can support a staggering number of boards, you may have boards that you want to enable certain functionality for, but not for others. And you can actually create "features" that you can enable or disable in your own userspace.
For instance, if you wanted to have a bunch of macros available, but only on certain boards (to save space), you could "hide" them being a `#ifdef MACROS_ENABLED`, and then enable it per board. To do this, add this to your rules.mk
```make
ifeq ($(strip $(MACROS_ENABLED)), yes)
OPT_DEFS += -DMACROS_ENABLED
endif
```
The `OPT_DEFS` setting causes `MACROS_ENABLED` to be defined for your keyboards (note the `-D` in front of the name), and you could use `#ifdef MACROS_ENABLED` to check the status in your c/h files, and handle that code based on that.
Then you add `MACROS_ENABLED = yes` to the `rules.mk` for you keymap to enable this feature and the code in your userspace.
And in your `process_record_user` function, you'd do something like this:
```c
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
#ifdef MACROS_ENABLED
case MACRO1:
if (!record->event.pressed) {
SEND_STRING("This is macro 1!");
}
break;
case MACRO2:
if (!record->event.pressed) {
SEND_STRING("This is macro 2!");
}
break;
#endif
}
return true;
}
```
## Consolidated Macros
If you wanted to consolidate macros and other functions into your userspace for all of your keymaps, you can do that. This builds upon the [Customized Functions](#customized-functions) example above. This lets you maintain a bunch of macros that are shared between the different keyboards, and allow for keyboard specific macros, too.
First, you'd want to go through all of your `keymap.c` files and replace `process_record_user` with `process_record_keymap` instead. This way, you can still use keyboard specific codes on those boards, and use your custom "global" keycodes as well. You'll also want to replace `SAFE_RANGE` with `NEW_SAFE_RANGE` so that you wont have any overlapping keycodes
Then add `#include <name.h>` to all of your keymap.c files. This allows you to use these new keycodes without having to redefine them in each keymap.
Once you've done that, you'll want to set the keycode definitions that you need to the `<name>.h` file. For instance:
```
#ifndef USERSPACE
#define USERSPACE
```c
#pragma once
#include "quantum.h"
#include "action.h"
#include "version.h"
// Define all of
enum custom_keycodes {
KC_MAKE = SAFE_RANGE,
NEW_SAFE_RANGE //use "NEW_SAFE_RANGE" for keymap specific codes
};
#endif
```
Now you want to create the `<name>.c` file, and add this content to it:
```
```c
#include "<name>.h"
#include "quantum.h"
#include "action.h"
#include "version.h"
__attribute__ ((weak))
bool process_record_keymap(uint16_t keycode, keyrecord_t *record) {
@ -126,14 +220,8 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
}
```
This will add a new `KC_MAKE` keycode that can be used in any of your keymaps. And this keycode will output `make <keyboard>:<keymap">`, making frequent compiling easier. And this will work with any keyboard and any keymap as it will output the current boards info, so that you don't have to type this out every time.
This will add a new `KC_MAKE` keycode that can be used in any of your keymaps. And this keycode will output `make <keyboard>:<keymap>`, making frequent compiling easier. And this will work with any keyboard and any keymap as it will output the current boards info, so that you don't have to type this out every time.
Additionally, this should flash the newly compiled firmware automatically, using the correct utility, based on the bootloader settings (or default to just generating the HEX file). However, it should be noted that this may not work on all systems. AVRDUDE doesn't work on WSL, namely (and will dump the HEX in the ".build" folder instead).
## Override default userspace
By default the userspace used will be the same as the keymap name. In some situations this isn't desirable. For instance, if you use the [layout](feature_layouts.md) feature you can't use the same name for different keymaps (e.g. ANSI and ISO). You can name your layouts `mylayout-ansi` and `mylayout-iso` and add the following line to your layout's `rules.mk`:
```
USER_NAME := mylayout
```

4
docs/features.md
View File

@ -8,13 +8,17 @@ QMK has a staggering number of features for building your keyboard. It can take
* [Auto Shift](feature_auto_shift.md) - Tap for the normal key, hold slightly longer for its shifted state.
* [Backlight](feature_backlight.md) - LED lighting support for your keyboard.
* [Bootmagic](feature_bootmagic.md) - Adjust the behavior of your keyboard using hotkeys.
* [Combos](feature_combo.md) - Custom actions for multiple key holds.
* [Command](feature_command.md) - Runtime version of bootmagic (Formerly known as "Magic").
* [Dynamic Macros](feature_dynamic_macros.md) - Record and playback macros from the keyboard itself.
* [Grave Escape](feature_grave_esc.md) - Lets you use a single key for Esc and Grave.
* [HD44780 LCD Display](feature_hd44780.md) - Support for LCD character displays using the HD44780 standard.
* [Key Lock](feature_key_lock.md) - Lock a key in the "down" state.
* [Layouts](feature_layouts.md) - Use one keymap with any keyboard that supports your layout.
* [Leader Key](feature_leader_key.md) - Tap the leader key followed by a sequence to trigger custom behavior.
* [Macros](feature_macros.md) - Send multiple key presses when pressing only one physical key.
* [Mouse keys](feature_mouse_keys.md) - Control your mouse pointer from your keyboard.
* [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys) - Sticky Keys, lets hit a key rather than holding it.
* [Pointing Device](feature_pointing_device.md) - Framework for connecting your custom pointing device to your keyboard.
* [PS2 Mouse](feature_ps2_mouse.md) - Driver for connecting a PS/2 mouse directly to your keyboard.
* [RGB Light](feature_rgblight.md) - RGB lighting for your keyboard.

39
docs/flashing.md
View File

@ -2,7 +2,7 @@
There are quite a few different types of bootloaders that keyboards use, and just about all of the use a different flashing method. Luckily, projects like the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) aim to be compatible with all the different types without having to think about it much, but this article will describe the different types of bootloaders, and available methods for flashing them.
If you have a bootloader selected with the `BOOTLOADER` variable in your `rules.mk`, QMK will automatically calculate if your .hex file is the right size to be flashed to the device, and output the total size it bytes (along with the max). To run this process manually, compile with the target `check-size`, eg `make planck/rev4:default:check-size`.
If you have a bootloader selected with the `BOOTLOADER` variable in your `rules.mk`, QMK will automatically calculate if your .hex file is the right size to be flashed to the device, and output the total size in bytes (along with the max). To run this process manually, compile with the target `check-size`, eg `make planck/rev4:default:check-size`.
## DFU
@ -71,13 +71,19 @@ Flashing sequence:
1. Press the `RESET` keycode, or short RST to GND quickly (you only have 7 seconds to flash once it enters)
2. Wait for the OS to detect the device
4. Flash a .hex file
5. Wait for the device to reset automatically
3. Flash a .hex file
4. Wait for the device to reset automatically
or
make <keyboard>:<keymap>:avrdude
or if you want to flash multiple boards, use the following command
make <keyboard>:<keymap>:avrdude-loop
When you're done flashing boards, you'll need to hit Ctrl + C or whatever the correct keystroke is for your operating system to break the loop.
## Halfkay
Halfkay is a super-slim protocol developed by PJRC that uses HID, and come on all Teensys (namely the 2.0).
@ -100,5 +106,28 @@ Flashing sequence:
1. Press the `RESET` keycode, or short RST to GND quickly (you only have 7 seconds to flash once it enters)
2. Wait for the OS to detect the device
4. Flash a .hex file
5. Reset the device into application mode (may be done automatically)
3. Flash a .hex file
4. Reset the device into application mode (may be done automatically)
## STM32
All STM32 chips come preloaded with a factory bootloader that cannot be modified nor deleted. Some STM32 chips have bootloaders that do not come with USB programming (e.g. STM32F103) but the process is still the same.
At the moment, no `BOOTLOADER` variable is needed on `rules.mk` for STM32.
Compatible flashers:
* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
* [dfu-util](https://github.com/Stefan-Schmidt/dfu-util) / `:dfu-util` (recommended command line)
Flashing sequence:
1. Enter the bootloader using any of the following methods:
* Tap the `RESET` keycode (may not work on STM32F042 devices)
* If a reset circuit is present, tap the RESET button
* Otherwise, you need to bridge BOOT0 to VCC (via BOOT0 button or bridge), short RESET to GND (via RESET button or bridge), and then let go of the BOOT0 bridge
2. Wait for the OS to detect the device
3. Flash a .bin file
* You will receive a warning about the DFU signature; Just ignore it
4. Reset the device into application mode (may be done automatically)
* If you are building from command line (e.g. `make planck/rev6:default:dfu-util`), make sure that `:leave` is passed to the `DFU_ARGS` variable inside your `rules.mk` (e.g. `DFU_ARGS = -d 0483:df11 -a 0 -s 0x08000000:leave`) so that your device resets after flashing

35
docs/getting_started_build_tools.md
View File

@ -8,7 +8,7 @@ Note: If it is your first time here, Check out the "Complete Newbs guide" instea
## Linux
To ensure you are always up to date, you can just run `sudo util/install_dependencies.sh`. That should always install all the dependencies needed. **This will run `apt-get upgrade`.**
To ensure you are always up to date, you can just run `sudo util/qmk_install.sh`. That should always install all the dependencies needed. **This will run `apt-get upgrade`.**
You can also install things manually, but this documentation might not be always up to date with all requirements.
@ -57,11 +57,13 @@ If you're using [homebrew,](http://brew.sh/) you can use the following commands:
brew tap PX4/homebrew-px4
brew update
brew install avr-gcc@7
brew link --force avr-gcc@7
brew install dfu-programmer
brew install dfu-util
brew install gcc-arm-none-eabi
brew install avrdude
This is the recommended method. If you don't have homebrew, [install it!](http://brew.sh/) It's very much worth it for anyone who works in the command line. Note that the `make` and `make install` portion during the homebrew installation of avr-libc can take over 20 minutes and exhibit high CPU usage.
This is the recommended method. If you don't have homebrew, [install it!](http://brew.sh/) It's very much worth it for anyone who works in the command line. Note that the `make` and `make install` portion during the homebrew installation of `avr-gcc@7` can take over 20 minutes and exhibit high CPU usage.
## Windows with msys2 (recommended)
@ -69,9 +71,9 @@ The best environment to use, for Windows Vista through any later version (tested
* Install msys2 by downloading it and following the instructions here: http://www.msys2.org
* Open the ``MSYS2 MingGW 64-bit`` shortcut
* Navigate to your qmk checkout. For example, if it's in the root of your c drive:
* Navigate to your QMK repository. For example, if it's in the root of your c drive:
* `$ cd /c/qmk_firmware`
* Run `util/msys2_install.sh` and follow the prompts
* Run `util/qmk_install.sh` and follow the prompts
## Windows 10 (deprecated)
These are the old instructions for Windows 10. We recommend you use [MSYS2 as outlined above](#windows-with-msys2-recommended).
@ -121,24 +123,27 @@ If you have trouble and want to ask for help, it is useful to generate a *Win_Ch
## Docker
If this is a bit complex for you, Docker might be the turn-key solution you need. After installing [Docker](https://www.docker.com/products/docker), run the following command at the root of the QMK folder to build a keyboard/keymap:
If this is a bit complex for you, Docker might be the turn-key solution you need. After installing [Docker CE](https://docs.docker.com/install/#supported-platforms), run the following command from the `qmk_firmware` directory to build a keyboard/keymap:
```bash
# You'll run this every time you want to build a keymap
# modify the keymap and keyboard assignment to compile what you want
# defaults are ergodox/default
util/docker_build.sh keyboard:keymap
# For example: util/docker_build.sh ergodox_ez:steno
```
This will compile the targeted keyboard/keymap and leave the resulting `.hex` or `.bin` file in the QMK directory for you to flash. If `:keymap` is omitted, the `default` keymap is used. Note that the parameter format is the same as when building with `make`.
docker run -e keymap=gwen -e keyboard=ergodox_ez --rm -v $('pwd'):/qmk:rw edasque/qmk_firmware
You can also start the script without any parameters, in which case it will ask you to input the build parameters one by one, which you may find easier to use:
```bash
util/docker_build.sh
# Reads parameters as input (leave blank for defaults)
```
On Windows Docker seems to have issues with the VOLUME tag in Dockerfile, and `$('pwd')` won't print a Windows compliant path; use full path instead, like this:
There is also support for building _and_ flashing the keyboard straight from Docker by specifying the `target` as well:
```bash
docker run -e keymap=default -e keyboard=ergodox_ez --rm -v D:/Users/Sacapuces/Documents/Repositories/qmk:/qmk:rw edasque/qmk_firmware
util/docker_build.sh keyboard:keymap:target
# For example: util/docker_build.sh planck/rev6:default:dfu-util
```
If you're on Linux, this should work out of the box. On Windows and macOS, it requires [Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/) to be running. This is tedious to set up, so it's not recommended; use QMK Toolbox instead.
This will compile the targeted keyboard/keymap and leave it in your QMK directory for you to flash.
!> Docker for Windows requires [Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v) to be enabled. This means that it cannot work on versions of Windows which don't have Hyper-V, such as Windows 7, Windows 8 and **Windows 10 Home**.
## Vagrant
If you have any problems building the firmware, you can try using a tool called Vagrant. It will set up a virtual computer with a known configuration that's ready-to-go for firmware building. OLKB does NOT host the files for this virtual computer. Details on how to set up Vagrant are in the [vagrant guide](getting_started_vagrant.md).

2
docs/getting_started_github.md
View File

@ -8,7 +8,7 @@ Start on the [QMK Github page](https://github.com/qmk/qmk_firmware), and you'll
![Fork on Github](http://i.imgur.com/8Toomz4.jpg)
If you're apart of an organization, you'll need to choose which account to fork it to. In most circumstances, you'll want to fork it to your personal account. Once your fork is completed (sometimes this takes a little while), click the "Clone or Download" button:
If you're a part of an organization, you'll need to choose which account to fork it to. In most circumstances, you'll want to fork it to your personal account. Once your fork is completed (sometimes this takes a little while), click the "Clone or Download" button:
![Download from Github](http://i.imgur.com/N1NYcSz.jpg)

46
docs/hardware_avr.md
View File

@ -8,7 +8,7 @@ If you have not yet you should read the [Keyboard Guidelines](hardware_keyboard_
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_project.sh` script:
```
```bash
$ util/new_project.sh my_awesome_keyboard
######################################################
# /keyboards/my_awesome_keyboard project created. To start
@ -30,7 +30,7 @@ This is where all the custom logic for your keyboard goes. Many keyboards do not
This is the file you define your [Layout Macro(s)](feature_layouts.md) in. At minimum you should have a `#define LAYOUT` for your keyboard that looks something like this:
```
```c
#define LAYOUT( \
k00, k01, k02, \
k10, k11 \
@ -57,7 +57,7 @@ At the top of the `config.h` you'll find USB related settings. These control how
Do change the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` lines to accurately reflect your keyboard.
```
```c
#define VENDOR_ID 0xFEED
#define PRODUCT_ID 0x6060
#define DEVICE_VER 0x0001
@ -66,20 +66,20 @@ Do change the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` lines to accurately r
#define DESCRIPTION A custom keyboard
```
?> Note: On Windows and macOS the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` fields will be displayed in the list of USB devices. On Linux these values will not be visible in `lsusb`, since Linux takes that information from the list published by the USB-IF.
?> Note: On Windows and macOS the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` fields will be displayed in the list of USB devices. ?> On Linux these values will not be visible in lsusb by default, since Linux takes the information from the list maintained by [USB ID Repository](http://www.linux-usb.org/usb-ids.html) by default. lsusb will show the information reported by the device when executed with -v option. It is also present in kernel logs after plugging in the device.
### Keyboard Matrix Configuration
The next section of the `config.h` file deals with your keyboard's matrix. The first thing you should set is the matrix's size. This is usually, but not always, the same number of rows and columns as the physical key arrangement.
```
```c
#define MATRIX_ROWS 2
#define MATRIX_COLS 3
```
Once you've defined the size of your matrix you need to define which pins on your MCU are connected to rows and columns. To do so simply specify the names of those pins:
```
```c
#define MATRIX_ROW_PINS { D0, D5 }
#define MATRIX_COL_PINS { F1, F0, B0 }
#define UNUSED_PINS
@ -89,7 +89,7 @@ The number of `MATRIX_ROW_PINS` entries must be the same as the number you assig
Finally, you can specify the direction your diodes point. This can be `COL2ROW`, `ROW2COL`, or `CUSTOM_MATRIX`.
```
```c
#define DIODE_DIRECTION COL2ROW
```
@ -97,16 +97,14 @@ Finally, you can specify the direction your diodes point. This can be `COL2ROW`,
By default QMK supports backlighting on pins `B5`, `B6`, and `B7`. If you are using one of those you can simply enable it here. For more details see the [Backlight Documentation](feature_backlight.md).
```
```c
#define BACKLIGHT_PIN B7
#define BACKLIGHT_LEVELS 3
#define BACKLIGHT_BREATHING
#define BREATHING_PERIOD 6
```
{% hint style='info' %}
You can use backlighting on any pin you like, but you will have to do more work to support that. See the [Backlight Documentation](feature_backlight.md) for more details.
{% endhint %}
?> You can use backlighting on any pin you like, but you will have to do more work to support that. See the [Backlight Documentation](feature_backlight.md) for more details.
### Other Configuration Options
@ -120,7 +118,7 @@ You use the `rules.mk` file to tell QMK what files to build and what features to
These options tell the build system what CPU to build for. Be very careful if you change any of these settings, you can render your keyboard inoperable.
```
```make
MCU = atmega32u4
F_CPU = 16000000
ARCH = AVR8
@ -128,26 +126,26 @@ F_USB = $(F_CPU)
OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT
```
### Bootloader Size
### Bootloaders
The bootloader is a special section of your MCU that allows you to upgrade the code stored on the MCU. Think of it like a Rescue Partition for your keyboard. If you are using a teensy 2.0, or a device like the Ergodox EZ that uses the teensy bootloader you should set this to `512`. Most other bootloaders should be set to `4096`, but `1024` and `2048` are other possible values you may encounter.
The bootloader is a special section of your MCU that allows you to upgrade the code stored on the MCU. Think of it like a Rescue Partition for your keyboard.
#### Teensy 2.0 Bootloader Example
#### Teensy Bootloader Example
```
OPT_DEFS += -DBOOTLOADER_SIZE=512
```
#### Teensy 2.0++ Bootloader Example
```
OPT_DEFS += -DBOOTLOADER_SIZE=1024
```make
BOOTLOADER = halfkay
```
#### Atmel DFU Loader Example
```make
BOOTLOADER = atmel-dfu
```
OPT_DEFS += -DBOOTLOADER_SIZE=4096
#### Pro Micro Bootloader Example
```make
BOOTLOADER = caterina
```
### Build Options

14
docs/how_keyboards_work.md
View File

@ -27,17 +27,17 @@ This usually happens with a periodic scan of key presses. This speed often is li
## 2. What the Firmware Sends
The [HID specification](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) tells what a keyboard can actually send through USB to have a chance to be properly recognised. This includes a pre-defined list of scancodes which are simple numbers from `0x00` to `0xE7`. The firmware assigns a scancode to each key of the keyboard.
The [HID specification](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf) tells what a keyboard can actually send through USB to have a chance to be properly recognised. This includes a pre-defined list of scancodes which are simple numbers from `0x00` to `0xE7`. The firmware assigns a scancode to each key of the keyboard.
The firmware does not send actually letters or characters, but only scancodes.
Thus, by modifying the firmware, you only can modify what scancode is sent over
The firmware does not send actual letters or characters, but only scancodes.
Thus, by modifying the firmware, you can only modify what scancode is sent over
USB for a given key.
## 3. What the Operating System Does
Once the keycode reaches the operating system, a piece of software has to have
it match an actual character thanks to a keyboard layout. For example, if your
layout is set to QWERTY, a sample of the matching table is as follow:
layout is set to QWERTY, a sample of the matching table is as follows:
| keycode | character |
|---------|-----------|
@ -55,11 +55,11 @@ As the layout is generally fixed (unless you create your own), the firmware can
## List of Characters You Can Send
Putting aside shortcuts, having a limited set of keycodes mapped to a limited layout means that **the list of characters you can assign to a given key only is the ones present in the layout**.
Putting aside shortcuts, having a limited set of keycodes mapped to a limited layout means that **the list of characters you can assign to a given key are only the ones present in the layout**.
For example, this means that if you have a QWERTY US layout, and you want to assign 1 key to produce `€` (euro currency symbol), you are unable to do so, because the QWERTY US layout does not have such mapping. You could fix that by using a QWERTY UK layout, or a QWERTY US International.
For example, this means that if you have a QWERTY US layout, and you want to assign one key to produce `€` (euro currency symbol), you are unable to do so, because the QWERTY US layout does not have such mapping. You could fix that by using a QWERTY UK layout, or a QWERTY US International.
You may wonder why a keyboard layout containing all of Unicode is not devised then? The limited number of keycode available through USB simply disallow such a thing.
You may wonder why a keyboard layout containing all of Unicode is not devised then? The limited number of keycodes available through USB simply disallows such a thing.
## How to (Maybe) Enter Unicode Characters

82
docs/i2c_driver.md Normal file
View File

@ -0,0 +1,82 @@
# I2C Master Driver
The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs.
## Available functions
|Function |Description |
|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`void i2c_init(void);` |Initializes the I2C driver. This function should be called once before any transaction is initiated. |
|`uint8_t i2c_start(uint8_t address);` |Starts an I2C transaction. Address is the 7-bit slave address without the direction bit. |
|`uint8_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);` |Transmit data over I2C. Address is the 7-bit slave address without the direction. Returns status of transaction. |
|`uint8_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);` |Receive data over I2C. Address is the 7-bit slave address without the direction. Saves number of bytes specified by `length` in `data` array. Returns status of transaction. |
|`uint8_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` |Same as the `i2c_transmit` function but `regaddr` sets where in the slave the data will be written. |
|`uint8_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` |Same as the `i2c_receive` function but `regaddr` sets from where in the slave the data will be read. |
|`uint8_t i2c_stop(uint16_t timeout);` |Stops the I2C driver. |
### Function Return
All the above functions, except `void i2c_init(void);` return the following truth table:
|Return Value |Description |
|---------------|---------------------------------------------------|
|0 |Operation executed successfully. |
|-1 |Operation failed. |
|-2 |Operation timed out. |
## AVR
### Configuration
The following defines can be used to configure the I2C master driver.
|Variable |Description |Default|
|------------------|---------------------------------------------------|-------|
|`#F_SCL` |Clock frequency in Hz |400KHz |
|`#Prescaler` |Divides master clock to aid in I2C clock selection |1 |
AVRs usually have set GPIO which turn into I2C pins, therefore no further configuration is required.
## ARM
For ARM the Chibios I2C HAL driver is under the hood.
This section assumes an STM32 MCU.
### Configuration
The configuration for ARM MCUs can be quite complex as often there are multiple I2C drivers which can be assigned to a variety of ports.
Firstly the `mcuconf.h` file must be setup to enable the necessary hardware drivers.
|Variable |Description |Default|
|------------------------------|------------------------------------------------------------------------------------|-------|
|`#STM32_I2C_USE_XXX` |Enable/Disable the hardware driver XXX (each driver should be explicitly listed) |FALSE |
|`#STM32_I2C_BUSY_TIMEOUT` |Time in ms until the I2C command is aborted if no response is received |50 |
|`#STM32_I2C_XXX_IRQ_PRIORITY` |Interrupt priority for hardware driver XXX (THIS IS AN EXPERT SETTING) |10 |
|`#STM32_I2C_USE_DMA` |Enable/Disable the ability of the MCU to offload the data transfer to the DMA unit |TRUE |
|`#STM32_I2C_XXX_DMA_PRIORITY` |Priority of DMA unit for hardware driver XXX (THIS IS AN EXPERT SETTING) |1 |
Secondly, in the `halconf.h` file, `#define HAL_USE_I2C` must be set to `TRUE`. This allows ChibiOS to load its I2C driver.
Lastly, we need to assign the correct GPIO pins depending on the I2C hardware driver we want to use.
By default the I2C1 hardware driver is assumed to be used. If another hardware driver is used, `#define I2C_DRIVER I2CDX` should be added to the `config.h` file with X being the number of hardware driver used. For example is I2C3 is enabled, the `config.h` file should contain `#define I2C_DRIVER I2CD3`. This aligns the QMK I2C driver with the Chibios I2C driver.
STM32 MCUs allows a variety of pins to be configured as I2C pins depending on the hardware driver used. By default B6 and B7 are set to I2C.
This can be changed by declaring the `i2c_init` function which intentionally has a weak attribute. Please consult the datasheet of your MCU for the available GPIO configurations. The following is an example initialization function:
```C
void i2c_init(void)
{
setPinInput(B6); // Try releasing special pins for a short time
setPinInput(B7);
chThdSleepMilliseconds(10); // Wait for the release to happen
palSetPadMode(GPIOB, 6, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B6 to I2C function
palSetPadMode(GPIOB, 7, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B7 to I2C function
}
```

3
docs/index.html
View File

@ -25,7 +25,8 @@
placeholder: 'Search Documentation...',
noData: 'We could not find any documents matching your search.',
depth: 6
}
},
fallbackLanguages: ['zh']
}
</script>
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>

23
docs/internals_gpio_control.md Normal file
View File

@ -0,0 +1,23 @@
# GPIO Control
QMK has a GPIO control abstraction layer which is micro-controller agnostic. This is done to allow easy access to pin control across different platforms.
## Functions
The following functions can provide basic control of GPIOs and are found in `quantum/quantum.h`.
|Function |Description |
|----------------------|------------------------------------------------------------------|
|`setPinInput(pin)` |Set pin as input with high impedance (High-Z) |
|`setPinInputHigh(pin)`|Set pin as input with build in pull-up |
|`setPinInputLow(pin)` |Set pin as input with build in pull-down (Supported only on STM32)|
|`setPinOutput(pin)` |Set pin as output |
|`writePinHigh(pin)` |Set pin level as high, assuming it is an output |
|`writePinLow(pin)` |Set pin level as low, assuming it is an output |
|`writePin(pin, level)`|Set pin level, assuming it is an output |
|`readPin(pin)` |Returns the level of the pin |
## Advance settings
Each micro-controller can have multiple advance settings regarding its GPIO. This abstraction layer does not limit the use of architecture specific functions. Advance users should consult the datasheet of there desired device and include any needed libraries. For AVR the standard avr/io.h library is used and for STM32 the Chibios [PAL library](http://chibios.sourceforge.net/docs3/hal/group___p_a_l.html) is used.

261
docs/keycode.txt
View File

@ -1,261 +0,0 @@
Keycode Symbol Table
====================
Keycodes are defined in `common/keycode.h`.
Range of 00-A4 and E0-E7 are identical with HID Usage:
<http://www.usb.org/developers/hidpage/Hut1_12v2.pdf>
Virtual keycodes are defined out of above range to support special actions.
Keycode Symbol Short name Description
--------------------------------------------------------------------------------
KC_NO 00 Reserved (no event indicated)
KC_ROLL_OVER 01 Keyboard ErrorRollOver
KC_POST_FAIL 02 Keyboard POSTFail
KC_UNDEFINED 03 Keyboard ErrorUndefined
KC_A 04 Keyboard a and A
KC_B 05 Keyboard b and B
KC_C 06 Keyboard c and C
KC_D 07 Keyboard d and D
KC_E 08 Keyboard e and E
KC_F 09 Keyboard f and F
KC_G 0A Keyboard g and G
KC_H 0B Keyboard h and H
KC_I 0C Keyboard i and I
KC_J 0D Keyboard j and J
KC_K 0E Keyboard k and K
KC_L 0F Keyboard l and L
KC_M 10 Keyboard m and M
KC_N 11 Keyboard n and N
KC_O 12 Keyboard o and O
KC_P 13 Keyboard p and P
KC_Q 14 Keyboard q and Q
KC_R 15 Keyboard r and R
KC_S 16 Keyboard s and S
KC_T 17 Keyboard t and T
KC_U 18 Keyboard u and U
KC_V 19 Keyboard v and V
KC_W 1A Keyboard w and W
KC_X 1B Keyboard x and X
KC_Y 1C Keyboard y and Y
KC_Z 1D Keyboard z and Z
KC_1 1E Keyboard 1 and !
KC_2 1F Keyboard 2 and @
KC_3 20 Keyboard 3 and #
KC_4 21 Keyboard 4 and $
KC_5 22 Keyboard 5 and %
KC_6 23 Keyboard 6 and ^
KC_7 24 Keyboard 7 and &
KC_8 25 Keyboard 8 and *
KC_9 26 Keyboard 9 and (
KC_0 27 Keyboard 0 and )
KC_ENTER KC_ENT 28 Keyboard Return (ENTER)
KC_ESCAPE KC_ESC 29 Keyboard ESCAPE
KC_BSPACE KC_BSPC 2A Keyboard DELETE (Backspace)
KC_TAB 2B Keyboard Tab
KC_SPACE KC_SPC 2C Keyboard Spacebar
KC_MINUS KC_MINS 2D Keyboard - and (underscore)
KC_EQUAL KC_EQL 2E Keyboard = and +
KC_LBRACKET KC_LBRC 2F Keyboard [ and {
KC_RBRACKET KC_RBRC 30 Keyboard ] and }
KC_BSLASH KC_BSLS 31 Keyboard \ and |
KC_NONUS_HASH KC_NUHS 32 Keyboard Non-US # and ~
KC_SCOLON KC_SCLN 33 Keyboard ; and :
KC_QUOTE KC_QUOT 34 Keyboard ‘ and “
KC_GRAVE KC_GRV 35 Keyboard Grave Accent and Tilde
KC_COMMA KC_COMM 36 Keyboard , and <
KC_DOT 37 Keyboard . and >
KC_SLASH KC_SLSH 38 Keyboard / and ?
KC_CAPSLOCK KC_CAPS 39 Keyboard Caps Lock
KC_F1 3A Keyboard F1
KC_F2 3B Keyboard F2
KC_F3 3C Keyboard F3
KC_F4 3D Keyboard F4
KC_F5 3E Keyboard F5
KC_F6 3F Keyboard F6
KC_F7 40 Keyboard F7
KC_F8 41 Keyboard F8
KC_F9 42 Keyboard F9
KC_F10 43 Keyboard F10
KC_F11 44 Keyboard F11
KC_F12 45 Keyboard F12
KC_PSCREEN KC_PSCR 46 Keyboard PrintScreen
KC_SCROLLLOCK KC_SLCK 47 Keyboard Scroll Lock
KC_PAUSE KC_PAUS 48 Keyboard Pause
KC_INSERT KC_INS 49 Keyboard Insert
KC_HOME 4A Keyboard Home
KC_PGUP 4B Keyboard PageUp
KC_DELETE KC_DEL 4C Keyboard Delete Forward
KC_END 4D Keyboard End
KC_PGDOWN KC_PGDN 4E Keyboard PageDown
KC_RIGHT KC_RGHT 4F Keyboard RightArrow
KC_LEFT 50 Keyboard LeftArrow
KC_DOWN 51 Keyboard DownArrow
KC_UP 52 Keyboard UpArrow
KC_NUMLOCK KC_NLCK 53 Keypad Num Lock and Clear
KC_KP_SLASH KC_PSLS 54 Keypad /
KC_KP_ASTERISK KC_PAST 55 Keypad *
KC_KP_MINUS KC_PMNS 56 Keypad -
KC_KP_PLUS KC_PPLS 57 Keypad +
KC_KP_ENTER KC_PENT 58 Keypad ENTER
KC_KP_1 KC_P1 59 Keypad 1 and End
KC_KP_2 KC_P2 5A Keypad 2 and Down Arrow
KC_KP_3 KC_P3 5B Keypad 3 and PageDn
KC_KP_4 KC_P4 5C Keypad 4 and Left Arrow
KC_KP_5 KC_P5 5D Keypad 5
KC_KP_6 KC_P6 5E Keypad 6 and Right Arrow
KC_KP_7 KC_P7 5F Keypad 7 and Home
KC_KP_8 KC_P8 60 Keypad 8 and Up Arrow
KC_KP_9 KC_P9 61 Keypad 9 and PageUp
KC_KP_0 KC_P0 62 Keypad 0 and Insert
KC_KP_DOT KC_PDOT 63 Keypad . and Delete
KC_NONUS_BSLASH KC_NUBS 64 Keyboard Non-US \ and |
KC_APPLICATION KC_APP 65 Keyboard Application
KC_POWER 66 Keyboard Power
KC_KP_EQUAL KC_PEQL 67 Keypad =
KC_F13 68 Keyboard F13
KC_F14 69 Keyboard F14
KC_F15 6A Keyboard F15
KC_F16 6B Keyboard F16
KC_F17 6C Keyboard F17
KC_F18 6D Keyboard F18
KC_F19 6E Keyboard F19
KC_F20 6F Keyboard F20
KC_F21 70 Keyboard F21
KC_F22 71 Keyboard F22
KC_F23 72 Keyboard F23
KC_F24 73 Keyboard F24
KC_EXECUTE 74 Keyboard Execute
KC_HELP 75 Keyboard Help
KC_MENU 76 Keyboard Menu
KC_SELECT 77 Keyboard Select
KC_STOP 78 Keyboard Stop
KC_AGAIN 79 Keyboard Again
KC_UNDO 7A Keyboard Undo
KC_CUT 7B Keyboard Cut
KC_COPY 7C Keyboard Copy
KC_PASTE 7D Keyboard Paste
KC_FIND 7E Keyboard Find
KC__MUTE 7F Keyboard Mute
KC__VOLUP 80 Keyboard Volume Up
KC__VOLDOWN 81 Keyboard Volume Down
KC_LOCKING_CAPS 82 Keyboard Locking Caps Lock
KC_LOCKING_NUM 83 Keyboard Locking Num Lock
KC_LOCKING_SCROLL 84 Keyboard Locking Scroll Lock
KC_KP_COMMA KC_PCMM 85 Keypad Comma
KC_KP_EQUAL_AS400 86 Keypad Equal Sign
KC_INT1 KC_RO 87 Keyboard International115
KC_INT2 KC_KANA 88 Keyboard International216
KC_INT3 KC_JYEN 89 Keyboard International317
KC_INT4 KC_HENK 8A Keyboard International418
KC_INT5 KC_MHEN 8B Keyboard International519
KC_INT6 8C Keyboard International620
KC_INT7 8D Keyboard International721
KC_INT8 8E Keyboard International822
KC_INT9 8F Keyboard International922
KC_LANG1 90 Keyboard LANG125
KC_LANG2 91 Keyboard LANG226
KC_LANG3 92 Keyboard LANG330
KC_LANG4 93 Keyboard LANG431
KC_LANG5 94 Keyboard LANG532
KC_LANG6 95 Keyboard LANG68
KC_LANG7 96 Keyboard LANG78
KC_LANG8 97 Keyboard LANG88
KC_LANG9 98 Keyboard LANG98
KC_ALT_ERASE 99 Keyboard Alternate Erase
KC_SYSREQ 9A Keyboard SysReq/Attention
KC_CANCEL 9B Keyboard Cancel
KC_CLEAR 9C Keyboard Clear
KC_PRIOR 9D Keyboard Prior
KC_RETURN 9E Keyboard Return
KC_SEPARATOR 9F Keyboard Separator
KC_OUT A0 Keyboard Out
KC_OPER A1 Keyboard Oper
KC_CLEAR_AGAIN A2 Keyboard Clear/Again
KC_CRSEL A3 Keyboard CrSel/Props
KC_EXSEL A4 Keyboard ExSel
/* Modifiers */
KC_LCTRL KC_LCTL E0 Keyboard LeftControl
KC_LSHIFT KC_LSFT E1 Keyboard LeftShift
KC_LALT E2 Keyboard LeftAlt
KC_LGUI E3 Keyboard Left GUI(Windows/Apple/Meta key)
KC_RCTRL KC_RCTL E4 Keyboard RightControl
KC_RSHIFT KC_RSFT E5 Keyboard RightShift
KC_RALT E6 Keyboard RightAlt
KC_RGUI E7 Keyboard Right GUI(Windows/Apple/Meta key)
/*
* Virtual keycodes
*/
/* System Control */
KC_SYSTEM_POWER KC_PWR System Power Down
KC_SYSTEM_SLEEP KC_SLEP System Sleep
KC_SYSTEM_WAKE KC_WAKE System Wake
/* Consumer Page */
KC_AUDIO_MUTE KC_MUTE
KC_AUDIO_VOL_UP KC_VOLU
KC_AUDIO_VOL_DOWN KC_VOLD
KC_MEDIA_NEXT_TRACK KC_MNXT
KC_MEDIA_PREV_TRACK KC_MPRV
KC_MEDIA_STOP KC_MSTP
KC_MEDIA_PLAY_PAUSE KC_MPLY
KC_MEDIA_SELECT KC_MSEL
KC_MAIL KC_MAIL
KC_CALCULATOR KC_CALC
KC_MY_COMPUTER KC_MYCM
KC_WWW_SEARCH KC_WSCH
KC_WWW_HOME KC_WHOM
KC_WWW_BACK KC_WBAK
KC_WWW_FORWARD KC_WFWD
KC_WWW_STOP KC_WSTP
KC_WWW_REFRESH KC_WREF
KC_WWW_FAVORITES KC_WFAV
/* Mousekey */
KC_MS_UP KC_MS_U Mouse Cursor Up
KC_MS_DOWN KC_MS_D Mouse Cursor Down
KC_MS_LEFT KC_MS_L Mouse Cursor Left
KC_MS_RIGHT KC_MS_R Mouse Cursor Right
KC_MS_BTN1 KC_BTN1 Mouse Button 1
KC_MS_BTN2 KC_BTN2 Mouse Button 2
KC_MS_BTN3 KC_BTN3 Mouse Button 3
KC_MS_BTN4 KC_BTN4 Mouse Button 4
KC_MS_BTN5 KC_BTN5 Mouse Button 5
KC_MS_WH_UP KC_WH_U Mouse Wheel Up
KC_MS_WH_DOWN KC_WH_D Mouse Wheel Down
KC_MS_WH_LEFT KC_WH_L Mouse Wheel Left
KC_MS_WH_RIGHT KC_WH_R Mouse Wheel Right
KC_MS_ACCEL0 KC_ACL0 Mouse Acceleration 0
KC_MS_ACCEL1 KC_ACL1 Mouse Acceleration 1
KC_MS_ACCEL2 KC_ACL2 Mouse Acceleration 2
/* Fn key */
KC_FN0
KC_FN1
KC_FN2
KC_FN3
KC_FN4
KC_FN5
KC_FN6
KC_FN7
KC_FN8
KC_FN9
KC_FN10
KC_FN11
KC_FN12
KC_FN13
KC_FN14
KC_FN15
KC_FN16
KC_FN17
KC_FN18
KC_FN19
KC_FN20
KC_FN21
KC_FN22
KC_FN23
KC_FN24
KC_FN25
KC_FN26
KC_FN27
KC_FN28
KC_FN29
KC_FN30
KC_FN31

79
docs/keycodes.md
View File

@ -141,9 +141,9 @@ This is a reference only. Each group of keys links to the page documenting their
|`KC_LOCKING_SCROLL` |`KC_LSCR` |Locking Scroll Lock |
|`KC_KP_COMMA` |`KC_PCMM` |Keypad `,` |
|`KC_KP_EQUAL_AS400` | |Keypad `=` on AS/400 keyboards |
|`KC_INT1` |`KC_RO` |JIS `\` and <code>&#124;</code> |
|`KC_INT1` |`KC_RO` |JIS `\` and `_` |
|`KC_INT2` |`KC_KANA` |JIS Katakana/Hiragana |
|`KC_INT3` |`KC_JYEN` |JIS `¥` |
|`KC_INT3` |`KC_JYEN` |JIS `¥` and <code>&#124;</code> |
|`KC_INT4` |`KC_HENK` |JIS Henkan |
|`KC_INT5` |`KC_MHEN` |JIS Muhenkan |
|`KC_INT6` | |JIS Numpad `,` |
@ -177,7 +177,7 @@ This is a reference only. Each group of keys links to the page documenting their
|`KC_LGUI` |`KC_LCMD`, `KC_LWIN`|Left GUI (Windows/Command/Meta key) |
|`KC_RCTRL` |`KC_RCTL` |Right Control |
|`KC_RSHIFT` |`KC_RSFT` |Right Shift |
|`KC_RALT` | |Right Alt |
|`KC_RALT` |`KC_ALGR` |Right Alt (AltGr) |
|`KC_RGUI` |`KC_RCMD`, `KC_RWIN`|Right GUI (Windows/Command/Meta key) |
|`KC_SYSTEM_POWER` |`KC_PWR` |System Power Down |
|`KC_SYSTEM_SLEEP` |`KC_SLEP` |System Sleep |
@ -203,29 +203,32 @@ This is a reference only. Each group of keys links to the page documenting their
|`KC_WWW_FAVORITES` |`KC_WFAV` |Browser Favorites (Windows) |
|`KC_MEDIA_FAST_FORWARD`|`KC_MFFD` |Next Track (macOS) |
|`KC_MEDIA_REWIND` |`KC_MRWD` |Previous Track (macOS) |
|`KC_BRIGHTNESS_UP` |`KC_BRIU` |Brightness Up |
|`KC_BRIGHTNESS_DOWN` |`KC_BRID` |Brightness Down |
## [Quantum Keycodes](quantum_keycodes.md#qmk-keycodes)
|Key |Aliases |Description |
|-------------|-----------|---------------------------------------------------------------------|
|`RESET` | |Put the keyboard into DFU mode for flashing |
|`DEBUG` | |Toggle debug mode |
|`KC_GESC` |`GRAVE_ESC`|Escape when tapped, <code>&#96;</code> when pressed with Shift or GUI|
|`KC_LSPO` | |Left Shift when held, `(` when tapped |
|`KC_RSPC` | |Right Shift when held, `)` when tapped |
|`KC_LEAD` | |The [Leader key](feature_leader_key.md) |
|`KC_LOCK` | |The [Lock key](feature_key_lock.md) |
|`FUNC(n)` |`F(n)` |Call `fn_action(n)` (deprecated) |
|`M(n)` | |Call macro `n` |
|`MACROTAP(n)`| |Macro-tap `n` idk FIXME |
|Key |Aliases |Description |
|---------------|-----------|---------------------------------------------------------------------|
|`RESET` | |Put the keyboard into DFU mode for flashing |
|`DEBUG` | |Toggle debug mode |
|`EEPROM_RESET` |`EEP_RST` |Resets EEPROM state by reinitializing it |
|`KC_GESC` |`GRAVE_ESC`|Escape when tapped, <code>&#96;</code> when pressed with Shift or GUI|
|`KC_LSPO` | |Left Shift when held, `(` when tapped |
|`KC_RSPC` | |Right Shift when held, `)` when tapped |
|`KC_LEAD` | |The [Leader key](feature_leader_key.md) |
|`KC_LOCK` | |The [Lock key](feature_key_lock.md) |
|`FUNC(n)` |`F(n)` |Call `fn_action(n)` (deprecated) |
|`M(n)` | |Call macro `n` |
|`MACROTAP(n)` | |Macro-tap `n` idk FIXME |
## [Audio Keys](feature_audio.md)
|Key |Aliases |Description |
|----------------|---------|----------------------------------|
|`AU_ON` | |Audio mode on |
|`AU_OFF` | |Audio mode off |
|`AU_TOG` | |Toggles Audio mode |
|`AU_ON` | |Turns on Audio Feature |
|`AU_OFF` | |Turns off Audio Feature |
|`AU_TOG` | |Toggles Audio state |
|`CLICKY_TOGGLE` |`CK_TOGG`|Toggles Audio clicky mode |
|`CLICKY_UP` |`CK_UP` |Increases frequency of the clicks |
|`CLICKY_DOWN` |`CK_DOWN`|Decreases frequency of the clicks |
@ -271,6 +274,7 @@ This is a reference only. Each group of keys links to the page documenting their
|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`| |Unswap `\` and Backspace |
|`MAGIC_UNHOST_NKRO` | |Force NKRO off |
|`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_TOGGLE_NKRO` | |Turn NKRO on or off |
## [Bluetooth](feature_bluetooth.md)
@ -284,15 +288,16 @@ This is a reference only. Each group of keys links to the page documenting their
## [Layer Switching](feature_advanced_keycodes.md#switching-and-toggling-layers)
|Key |Description |
|-----------------|---------------------------------------------------------------------|
|`DF(layer)` |Switches the default layer |
|`MO(layer)` |Momentarily activates layer, switches off when you let go |
|`LM(layer, mod)` |As `MO(layer)` but with `mod` active |
|`LT(layer, kc)` |Momentarily activates layer if held, sends kc if tapped |
|`TG(layer)` |Toggles the layer (enables it if no active, and vise versa) |
|`TO(layer)` |Activates layer and deactivates all other layers |
|`TT(layer)` |Momentarily activates layer if held, toggles it if tapped repeatedly |
|Key |Description |
|----------------|----------------------------------------------------------------------------------|
|`DF(layer)` |Set the base (default) layer |
|`MO(layer)` |Momentarily turn on `layer` when pressed (requires `KC_TRNS` on destination layer)|
|`OSL(layer)` |Momentarily activates `layer` until a key is pressed. See [One Shot Keys](https://docs.qmk.fm/#/feature_advanced_keycodes?id=one-shot-keys) for details. |
|`LM(layer, mod)`|Momentarily turn on `layer` (like MO) with `mod` active as well.
|`LT(layer, kc)` |Turn on `layer` when held, `kc` when tapped |
|`TG(layer)` |Toggle `layer` on or off |
|`TO(layer)` |Turn on `layer` when pressed |
|`TT(layer)` |Normally acts like MO unless it's tapped multiple times, which toggles `layer` on |
## [Mouse Keys](feature_mouse_keys.md)
@ -318,7 +323,7 @@ This is a reference only. Each group of keys links to the page documenting their
## [Modifiers](feature_advanced_keycodes.md#modifier-keys)
|Key |Aliases |Description |
|----------|---------- |----------------------------------------------------|
|----------|----------------------|----------------------------------------------------|
|`KC_HYPR` | |Hold Left Control, Shift, Alt and GUI |
|`KC_MEH` | |Hold Left Control, Shift and Alt |
|`LCTL(kc)`| |Hold Left Control and press `kc` |
@ -327,12 +332,11 @@ This is a reference only. Each group of keys links to the page documenting their
|`LGUI(kc)`|`LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc` |
|`RCTL(kc)`| |Hold Right Control and press `kc` |
|`RSFT(kc)`| |Hold Right Shift and press `kc` |
|`RALT(kc)`| |Hold Right Alt and press `kc` |
|`RALT(kc)`|`ALGR(kc)` |Hold Right Alt and press `kc` |
|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)`|Hold Right GUI and press `kc` |
|`HYPR(kc)`| |Hold Left Control, Shift, Alt and GUI and press `kc`|
|`MEH(kc)` | |Hold Left Control, Shift and Alt and press `kc` |
|`LCAG(kc)`| |Hold Left Control, Alt and GUI and press `kc` |
|`ALTG(kc)`| |Hold Right Control and Alt and press `kc` |
|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`|Hold Left Shift and GUI and press `kc` |
|`LCA(kc)` | |Hold Left Control and Alt and press `kc` |
@ -353,7 +357,7 @@ This is a reference only. Each group of keys links to the page documenting their
|`LCAG_T(kc)`| |Left Control, Alt and GUI when held, `kc` when tapped |
|`RCAG_T(kc)`| |Right Control, Alt and GUI when held, `kc` when tapped |
|`ALL_T(kc)` | |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)|
|`SCMD_T(kc)`|`SWIN_T(kc)` |Left Shift and GUI when held, `kc` when tapped |
|`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)` |Left Shift and GUI when held, `kc` when tapped |
|`LCA_T(kc)` | |Left Control and Alt when held, `kc` when tapped |
## [RGB Lighting](feature_rgblight.md)
@ -428,18 +432,6 @@ This is a reference only. Each group of keys links to the page documenting their
|`KC_RIGHT_ANGLE_BRACKET`|`KC_RABK`, `KC_GT` |`>` |
|`KC_QUESTION` |`KC_QUES` |`?` |
## [Switching and Toggling Layers](feature_advanced_keycodes.md#switching-and-toggling-layers)
|Key |Description |
|----------------|----------------------------------------------------------------------------------|
|`LT(layer, kc)` |Turn on `layer` when held, `kc` when tapped |
|`TO(layer)` |Turn on `layer` when pressed |
|`MO(layer)` |Momentarily turn on `layer` when pressed (requires `KC_TRNS` on destination layer)|
|`DF(layer)` |Set the base (default) layer |
|`TG(layer)` |Toggle `layer` on or off |
|`TT(layer)` |Normally acts like MO unless it's tapped multiple times, which toggles `layer` on |
|`LM(layer, mod)`|Momentarily turn on `layer` (like MO) with `mod` active as well. |
## [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
|Key |Description |
@ -459,6 +451,7 @@ This is a reference only. Each group of keys links to the page documenting their
|`SH_MOFF` |Momentarily turns off swap. |
|`SH_TG` |Toggles swap on and off with every key press. |
|`SH_TT` |Toggles with a tap; momentary when held. |
## [Unicode Support](feature_unicode.md)
|Key |Aliases| |

10
docs/keycodes_basic.md
View File

@ -1,6 +1,6 @@
# Basic Keycodes
The basic set of keycodes are based on the [HID Keyboard/Keypad Usage Page (0x07)](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) with the exception of `KC_NO`, `KC_TRNS` and keycodes in the `0xA5-DF` range. See below for more details.
The basic set of keycodes are based on the [HID Keyboard/Keypad Usage Page (0x07)](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf) with the exception of `KC_NO`, `KC_TRNS` and keycodes in the `0xA5-DF` range. See below for more details.
## Letters and Numbers
@ -116,16 +116,16 @@ The basic set of keycodes are based on the [HID Keyboard/Keypad Usage Page (0x07
|`KC_LGUI` |`KC_LCMD`, `KC_LWIN`|Left GUI (Windows/Command/Meta key) |
|`KC_RCTRL` |`KC_RCTL` |Right Control |
|`KC_RSHIFT`|`KC_RSFT` |Right Shift |
|`KC_RALT` | |Right Alt |
|`KC_RALT` |`KC_ALGR` |Right Alt (AltGr) |
|`KC_RGUI` |`KC_RCMD`, `KC_RWIN`|Right GUI (Windows/Command/Meta key)|
## International
|Key |Aliases |Description |
|----------|---------|-------------------------------|
|`KC_INT1` |`KC_RO` |JIS `\` and <code>&#124;</code>|
|`KC_INT1` |`KC_RO` |JIS `\` and `_` |
|`KC_INT2` |`KC_KANA`|JIS Katakana/Hiragana |
|`KC_INT3` |`KC_JYEN`|JIS `¥` |
|`KC_INT3` |`KC_JYEN`|JIS `¥` and <code>&#124;</code>|
|`KC_INT4` |`KC_HENK`|JIS Henkan |
|`KC_INT5` |`KC_MHEN`|JIS Muhenkan |
|`KC_INT6` | |JIS Numpad `,` |
@ -219,6 +219,8 @@ Windows and macOS use different keycodes for "next track" and "previous track".
|`KC_WWW_FAVORITES` |`KC_WFAV`|Browser Favorites (Windows) |
|`KC_MEDIA_FAST_FORWARD`|`KC_MFFD`|Next Track (macOS) |
|`KC_MEDIA_REWIND` |`KC_MRWD`|Previous Track (macOS) |
|`KC_BRIGHTNESS_UP` |`KC_BRIU`|Brightness Up |
|`KC_BRIGHTNESS_DOWN` |`KC_BRID`|Brightness Down |
## Number Pad

4
docs/keycodes_us_ansi_shifted.md
View File

@ -6,6 +6,10 @@ These keycodes correspond to characters that are "shifted" on a standard US ANSI
Unfortunately, these keycodes cannot be used in Mod-Taps or Layer-Taps, since any modifiers specified in the keycode are ignored.
Additionally, you may run into issues when using Remote Desktop Connection on Windows. Because these codes send shift very fast, Remote Desktop may miss the codes.
To fix this, open Remote Desktop Connection, click on "Show Options", open the the "Local Resources" tab. In the keyboard section, change the drop down to "On this Computer". This will fix the issue, and allow the characters to work correctly.
## Keycodes
|Key |Aliases |Description |

12
docs/keymap.md
View File

@ -89,11 +89,15 @@ There are 3 main sections of a `keymap.c` file you'll want to concern yourself w
At the top of the file you'll find this:
#include "clueboard.h"
#include QMK_KEYBOARD_H
// Helpful defines
#define GRAVE_MODS (MOD_BIT(KC_LSHIFT)|MOD_BIT(KC_RSHIFT)|MOD_BIT(KC_LGUI)|MOD_BIT(KC_RGUI)|MOD_BIT(KC_LALT)|MOD_BIT(KC_RALT))
#define _______ KC_TRNS
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* You can use _______ in place for KC_TRNS (transparent) *
* Or you can use XXXXXXX for KC_NO (NOOP) *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
// Each layer gets a name for readability.
// The underscores don't mean anything - you can
@ -105,7 +109,9 @@ At the top of the file you'll find this:
#define _FL 1
#define _CL 2
These are some handy definitions we can use when building our keymap and our custom function. The `GRAVE_MODS` definition will be used later in our custom function. The `_______` define makes it easier to see what keys a layer is overriding, while the `_BL`, `_FL`, and `_CL` defines make it easier to refer to each of our layers.
These are some handy definitions we can use when building our keymap and our custom function. The `GRAVE_MODS` definition will be used later in our custom function, and the following `_BL`, `_FL`, and `_CL` defines make it easier to refer to each of our layers.
Note: You may also find some older keymap files may also have a define(s) for `_______` and/or `XXXXXXX`. These can be used in place for `KC_TRNS` and `KC_NO` respectively, making it easier to see what keys a layer is overriding. These definitions are now unecessary, as they are included by default.
### Layers and Keymaps

6
docs/newbs.md
View File

@ -6,13 +6,17 @@ Not sure if your keyboard can run QMK? If it's a mechanical keyboard you built y
## Overview
There are 4 main sections to this guide:
There are 6 main sections to this guide:
* [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)
* [Git Best Practices](newbs_best_practices.md)
* [Learn More with these Resources](newbs_learn_more_resources.md)
This guide is focused on helping someone who has never compiled software before. It makes choices and recommendations based on that viewpoint. There are alternative methods for many of these procedures, and we support most of those alternatives. If you have any doubt about how to accomplish a task you can [ask us for guidance](getting_started_getting_help.md).
## Additional Resources
* [Thomas Baart's QMK Basics Blog](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – A user-created blog covering the basics of how to use QMK Firmware, as seen from a new user's perspective.

163
docs/newbs_best_practices.md Normal file
View File

@ -0,0 +1,163 @@
# Best Practices
## Or, "How I Learned to Stop Worrying and Love Git."
This document aims to instruct novices in the best ways to have a smooth experience in contributing to QMK. We will walk through the process of contributing to QMK, detailing some ways to make this task easier, and then later we'll break some things in order to teach you how to fix them.
This document assumes a few things:
1. You have a GitHub account, and have [forked the qmk_firmware repository](getting_started_github.md) to your account.
2. You've [set up your build environment](newbs_getting_started.md?id=environment-setup).
## Your fork's master: Update Often, Commit Never
It is highly recommended for QMK development, regardless of what is being done or where, to keep your `master` branch updated, but ***never*** commit to it. Instead, do all your changes in a development branch and issue pull requests from your branches when you're developing.
To reduce the chances of merge conflicts &mdash; instances where two or more users have edited the same part of a file concurrently &mdash; keep your `master` branch relatively up-to-date, and start any new developments by creating a new branch.
### Updating your master branch
To keep your `master` branch updated, it is recommended to add the QMK Firmware repository ("repo") as a remote repository in git. To do this, open your Git command line interface and enter:
```
git remote add upstream https://github.com/qmk/qmk_firmware.git
```
To verify that the repository has been added, run `git remote -v`, which should return the following:
```
$ git remote -v
origin https://github.com/<your_username>/qmk_firmware.git (fetch)
origin https://github.com/<your_username>/qmk_firmware.git (push)
upstream https://github.com/qmk/qmk_firmware.git (fetch)
upstream https://github.com/qmk/qmk_firmware.git (push)
```
Now that this is done, you can check for updates to the repo by running `git fetch upstream`. This retrieves the branches and tags &mdash; collectively referred to as "refs" &mdash; from the QMK repo, which now has the nickname `upstream`. We can now compare the data on our fork `origin` to that held by QMK.
To update your fork's master, run the following, hitting the Enter key after each line:
```
git checkout master
git fetch upstream
git pull upstream master
git push origin master
```
This switches you to your `master` branch, retrieves the refs from the QMK repo, downloads the current QMK `master` branch to your computer, and then uploads it to your fork.
### Making Changes
To make changes, create a new branch by entering:
```
git checkout -b dev_branch
git push --set-upstream origin dev_branch
```
This creates a new branch named `dev_branch`, checks it out, and then saves the new branch to your fork. The `--set-upstream` argument tells git to use your fork and the `dev_branch` branch every time you use `git push` or `git pull` from this branch. It only needs to be used on the first push; after that, you can safely use `git push` or `git pull`, without the rest of the arguments.
!> With `git push`, you can use `-u` in place of `--set-upstream` &mdash; `-u` is an alias for `--set-upstream`.
You can name your branch nearly anything you want, though it is recommended to name it something related to the changes you are going to make.
By default `git checkout -b` will base your new branch on the branch that is checked out. You can base your new branch on an existing branch that is not checked out by adding the name of the existing branch to the command:
```
git checkout -b dev_branch master
```
Now that you have a development branch, open your text editor and make whatever changes you need to make. It is recommended to make many small commits to your branch; that way, any change that causes issues can be more easily traced and undone if needed. To make your changes, edit and save any files that need to be updated, add them to Git's *staging area*, and then commit them to your branch:
```
git add path/to/updated_file
git commit -m "My commit message."
```
`git add` adds files that have been changed to Git's *staging area*, which is Git's "loading zone." This contains the changes that are going to be *committed* by `git commit`, which saves the changes to the repo. Use descriptive commit messages so you can know what was changed at a glance.
!> If you've changed a lot of files, but all the files are part of the same change, you can use `git add .` to add all the changed files that are in your current directory, rather than having to add each file individually.
### Publishing Your Changes
The last step is to push your changes to your fork. To do this, enter `git push`. Git now publishes the current state of `dev_branch` to your fork.
## Resolving Merge Conflicts
Sometimes when your work in a branch takes a long time to complete, changes that have been made by others conflict with changes you have made to your branch when you open a pull request. This is called a *merge conflict*, and is what happens when multiple people edit the same parts of the same files.
### Rebasing Your Changes
A *rebase* is Git's way of taking changes that were applied at one point, reversing them, and then applying the same changes to another point. In the case of a merge conflict, you can rebase your branch to grab the changes that were made between when you created your branch and the present time.
To start, run the following:
```
git fetch upstream
git rev-list --left-right --count HEAD...upstream/master
```
The `git rev-list` command entered here returns the number of commits that differ between the current branch and QMK's master branch. We run `git fetch` first to make sure we have the refs that represent the current state of the upstream repo. The output of the `git rev-list` command entered returns two numbers:
```
$ git rev-list --left-right --count HEAD...upstream/master
7 35
```
The first number represents the number of commits on the current branch since it was created, and the second number is the number of commits made to `upstream/master` since the current branch was created, and thus, the changes that are not recorded in the current branch.
Now that the current states of both the current branch and the upstream repo are known, we can start a rebase operation:
```
git rebase upstream/master
```
This tells Git to undo the commits on the current branch, and then reapply them against QMK's master branch.
```
$ git rebase upstream/master
First, rewinding head to replay your work on top of it...
Applying: Commit #1
Using index info to reconstruct a base tree...
M conflicting_file_1.txt
Falling back to patching base and 3-way merge...
Auto-merging conflicting_file_1.txt
CONFLICT (content): Merge conflict in conflicting_file_1.txt
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch' to see the failed patch
Patch failed at 0001 Commit #1
Resolve all conflicts manually, mark them as resolved with
"git add/rm <conflicted_files>", then run "git rebase --continue".
You can instead skip this commit: run "git rebase --skip".
To abort and get back to the state before "git rebase", run "git rebase --abort".
```
This tells us that we have a merge conflict, and gives the name of the file with the conflict. Open the conflicting file in your text editor, and somewhere in the file, you'll find something like this:
```
<<<<<<< HEAD
<p>For help with any issues, email us at support@webhost.us.</p>
=======
<p>Need help? Email support@webhost.us.</p>
>>>>>>> Commit #1
```
The line `<<<<<<< HEAD` marks the beginning of a merge conflict, and the `>>>>>>> Commit #1` line marks the end, with the conflicting sections separated by `=======`. The part on the `HEAD` side is from the QMK master version of the file, and the part marked with the commit message is from the current branch and commit.
Because Git tracks *changes to files* rather than the contents of the files directly, if Git can't find the text that was in the file previous to the commit that was made, it won't know how to edit the file. Re-editing the file will solve the conflict. Make your changes, and then save the file.
```
<p>Need help? Email support@webhost.us.</p>
```
Now run:
```
git add conflicting_file_1.txt
git rebase --continue
```
Git logs the changes to the conflicting file, and continues applying the commits from our branch until it reaches the end.

16
docs/newbs_building_firmware.md
View File

@ -16,12 +16,26 @@ Start by navigating to the `keymaps` folder for your keyboard.
?> Windows:
start keyboards/<keyboard_folder>/keymaps
start .\\keyboards\\<keyboard_folder>\\keymaps
## Create a Copy Of The `default` Keymap
Once you have the `keymaps` folder open you will want to create a copy of the `default` folder. We highly recommend you name your folder the same as your GitHub username, but you can use any name you want as long as it contains only lower case letters, numbers, and the underscore character.
To automate the process, you also have the option to run the `new_keymap.sh` script.
Navigate to the `qmk_firmware/util` directory and type the following:
```
./new_keymap.sh <keyboard path> <username>
```
For example, for a user named John, trying to make a new keymap for the 1up60hse, they would type in
```
./new_keymap.sh 1upkeyboards/1up60hse john
```
## Open `keymap.c` In Your Favorite Text Editor
Open up your `keymap.c`. Inside this file you'll find the structure that controls how your keyboard behaves. At the top of `keymap.c` there may be some defines and enums that make the keymap easier to read. Farther down you'll find a line that looks like this:

78
docs/newbs_getting_started.md
View File

@ -1,99 +1,97 @@
# Introduction
Your computer keyboard has a processor inside of it, not unlike the one inside your computer. This processor runs software that is responsible for detecting button presses and sending reports about the state of the keyboard when they are pressed or released. QMK fills the role of that software, detecting button presses and passing that information on to the host computer. When you build your custom layout you are creating the equivalent of an .exe for your keyboard.
Your computer keyboard has a processor inside of it, not unlike the one inside your computer. This processor runs software that is responsible for detecting button presses and sending reports about the state of the keyboard when buttons are pressed or released. QMK fills the role of that software, detecting button presses and passing that information on to the host computer. When you build your custom keymap, you are creating the equivalent of an executable program for your keyboard.
QMK tries to put a lot of power into your hands by making easy things easy, and hard things possible. You don't have to know how to program to create powerful layouts, you only have to follow a few simple syntax rules.
QMK tries to put a lot of power into your hands by making easy things easy, and hard things possible. You don't have to know how to program to create powerful keymaps — you only have to follow a few simple syntax rules.
# Getting Started
Before you can build keymaps you need to install some software and setup your build environment. This only has to be done one time no matter how many keyboards you want to compile firmware for.
Before you can build keymaps, you need to install some software and set up your build environment. This only has to be done once no matter how many keyboards you plan to compile firmware for.
## Download Software
### Text Editor
You'll need a program that can edit and save **plain text** files. If you are on Windows you can make due with Notepad, and on Linux you can use Gedit, both of which are simple but functional text editors. On macOS be careful with TextEdit.app, it will not save plain text files unless you make sure to select "Make Plain text" from the "Format" menu, or you can use another program such as Sublime Text.
You'll need a program that can edit and save **plain text** files. If you're on Windows you can make do with Notepad, and on Linux you can use gedit. Both of these are simple but functional text editors. On macOS, be careful with the default TextEdit app: it will not save plain text files unless you explicitly select _Make Plain Text_ from the _Format_ menu.
You can also download and install a dedicated text editor like [Sublime Text](https://www.sublimetext.com/) or [VS Code](https://code.visualstudio.com/). This is probably the best way to go regardless of platform, as these programs are specifically made for editing code.
?> Not sure which text editor to use? Laurence Bradford wrote [a great introduction](https://learntocodewith.me/programming/basics/text-editors/) to the subject.
### QMK Toolbox
QMK Toolbox is an optional graphical Windows and macOS program that allows you to both program and debug your custom keyboard. You will likely prefer it to easily flash your keyboard and receive the debugging messages that your keyboard will print.
QMK Toolbox is an optional graphical program for Windows and macOS that allows you to both program and debug your custom keyboard. You will likely find it invaluable for easily flashing your keyboard and viewing debug messages that it prints.
Download the files from the links below:
[Download the latest release here.](https://github.com/qmk/qmk_toolbox/releases/latest)
For Windows: "qmk_toolbox.exe" or "qmk_toolbox_install.exe" (with installer)
* For Windows: `qmk_toolbox.exe` (portable) or `qmk_toolbox_install.exe` (installer)
* For macOS: `QMK.Toolbox.app.zip` (portable) or `QMK.Toolbox.pkg` (installer)
For Mac: "QMK.Toolbox.app.zip" or "QMK.Toolbox.pkg" (with installer)
## Set Up Your Environment
* [Newest Release](https://github.com/qmk/qmk_toolbox/releases/latest)
* [Source Code](https://github.com/qmk/qmk_toolbox/)
We've tried to make QMK as easy to set up as possible. You only have to prepare your Linux or Unix environment, then let QMK install the rest.
## Environment Setup
We've tried to make QMK as easy to setup as possible. You only have to prepare your Linux or Unix environment and let QMK install the rest.
?> If you haven't worked with the Linux/Unix command line before there are a few basic concepts and commands you should learn. These resources will teach you enough to work with QMK:<br>
?> If you haven't worked with the Linux/Unix command line before, there are a few basic concepts and commands you should learn. These resources will teach you enough to be able to work with QMK:<br>
[Must Know Linux Commands](https://www.guru99.com/must-know-linux-commands.html)<br>
[Some Basic Unix Commands](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html)
### Windows
You will need to install msys2 and git.
You will need to install MSYS2 and Git.
* Follow the installation instructions on the msys2 homepage: http://www.msys2.org
* Close any open msys2 terminals, and open a new terminal
* Install git by running this command: `pacman -S git`
* Follow the installation instructions on the [MSYS2 homepage](http://www.msys2.org).
* Close any open MSYS2 terminals and open a new MSYS2 MinGW 64-bit terminal.
* Install Git by running this command: `pacman -S git`.
### macOS
You will need to install homebrew. Follow the instructions on the homebrew homepage: https://brew.sh
You will need to install Homebrew. Follow the instructions on the [Homebrew homepage](https://brew.sh).
After homebrew is installed continue with "Download QMK", following step "Setup QMK" runs a script that will install other packages.
After Homebrew is installed, continue with _Set Up QMK_. In that step you will run a script that will install other packages.
### Linux
You will need to install git. It's extremely likely you already have it, but if not one of the following commands should install it:
You will need to install Git. It's very likely that you already have it, but if not, one of the following commands should install it:
* Debian/Ubuntu/Devuan: `apt-get install git`
* Fedora/Redhat/Centos: `yum install git`
* Debian / Ubuntu / Devuan: `apt-get install git`
* Fedora / Red Hat / CentOS: `yum install git`
* Arch: `pacman -S git`
## Download QMK
?> Docker is also an option on all platforms. [Click here for details.](getting_started_build_tools.md#docker)
Once you have setup your Linux/Unix environment you are ready to download QMK. We will do this by using git to "clone" the QMK repository. Open a Terminal or MSYS2 Console window and leave it open for the remainder of this guide. Inside that window run these two commands:
## Set Up QMK
Once you have set up your Linux/Unix environment, you are ready to download QMK. We will do this by using Git to "clone" the QMK repository. Open a Terminal or MSYS2 MinGW window and leave it open for the remainder of this guide. Inside that window run these two commands:
git clone https://github.com/qmk/qmk_firmware.git
cd qmk_firmware
?> If you already know [how to use GitHub](getting_started_github.md) we recommend you create and clone your own fork instead. If you don't know what that means you can safely ignore this message.
?> If you already know [how to use GitHub](getting_started_github.md), we recommend that you create and clone your own fork instead. If you don't know what that means, you can safely ignore this message.
## Setup QMK
QMK comes with a script to help you set up the rest of what you'll need. You should run it now by typing in this command:
QMK comes with a script to help you setup the rest of what you'll need. You should run it now by typing in this command:
./util/qmk_install.sh
util/qmk_install.sh
## Test Your Build Environment
Now that your QMK build environment is setup you can build a firmware for your keyboard. Start by trying to build the default layout for your keyboard. You should be able to do that with a command in this format:
Now that your QMK build environment is set up, you can build a firmware for your keyboard. Start by trying to build the keyboard's default keymap. You should be able to do that with a command in this format:
make <keyboard>:default
For example, to build a firmware for a Clueboard 66% use:
For example, to build a firmware for a Clueboard 66% you would use:
make clueboard/66/rev3:default
When it is done you should have a lot of output that ends similar to this:
```
Linking: .build/clueboard_66_rev2_default.elf [OK]
Creating load file for flashing: .build/clueboard_66_rev2_default.hex [OK]
Copying clueboard_66_rev2_default.hex to qmk_firmware folder [OK]
Checking file size of clueboard_66_rev2_default.hex [OK]
* File size is fine - 25174/28672
Linking: .build/clueboard_66_rev3_default.elf [OK]
Creating load file for flashing: .build/clueboard_66_rev3_default.hex [OK]
Copying clueboard_66_rev3_default.hex to qmk_firmware folder [OK]
Checking file size of clueboard_66_rev3_default.hex [OK]
* The firmware size is fine - 26356/28672 (2316 bytes free)
```
## Creating Your Layout
# Creating Your Keymap
Now you are ready to create your own personal layout. Move on to [Building Your First Firmware](newbs_building_firmware.md) for that.
You are now ready to create your own personal keymap! Move on to [Building Your First Firmware](newbs_building_firmware.md) for that.

16
docs/newbs_learn_more_resources.md
View File

@ -1,13 +1,15 @@
# Learning Resources
These resources are aimed at giving new members in the qmk community more understanding to the information provided in the newbs docs.
These resources are aimed at giving new members in the QMK community more understanding to the information provided in the Newbs docs.
Git resources:
*
*[Great General Tutorial](https://www.codecademy.com/learn/learn-git)
*[Git Game To Learn From Examples](https://learngitbranching.js.org/)
*[Git Resources to Learn More About Github](getting_started_github.md)
*[Git Resources Aimed Specificly toward QMK](contributing.md)
* [Great General Tutorial](https://www.codecademy.com/learn/learn-git)
* [Git Game To Learn From Examples](https://learngitbranching.js.org/)
* [Git Resources to Learn More About Github](getting_started_github.md)
* [Git Resources Aimed Specifically toward QMK](contributing.md)
Command Line resources:
*[Good General Tutorial on Command Line](https://www.codecademy.com/learn/learn-the-command-line)
* [Good General Tutorial on Command Line](https://www.codecademy.com/learn/learn-the-command-line)

2
docs/newbs_testing_debugging.md
View File

@ -28,6 +28,6 @@ Sometimes it's useful to print debug messages from within your [custom code](cus
After that you can use a few different print functions:
* `print("string")`: Print a simple string.
* `sprintf("%s string", var)`: Print a formatted string
* `uprintf("%s string", var)`: Print a formatted string
* `dprint("string")` Print a simple string, but only when debug mode is enabled
* `dprintf("%s string", var)`: Print a formatted string, but only when debug mode is enabled

25
docs/quantum_keycodes.md
View File

@ -8,15 +8,16 @@ On this page we have documented keycodes between `0x00FF` and `0xFFFF` which are
## QMK Keycodes
|Key |Aliases |Description |
|-------------|-----------|---------------------------------------------------------------------|
|`RESET` | |Put the keyboard into DFU mode for flashing |
|`DEBUG` | |Toggle debug mode |
|`KC_GESC` |`GRAVE_ESC`|Escape when tapped, <code>&#96;</code> when pressed with Shift or GUI|
|`KC_LSPO` | |Left Shift when held, `(` when tapped |
|`KC_RSPC` | |Right Shift when held, `)` when tapped |
|`KC_LEAD` | |The [Leader key](feature_leader_key.md) |
|`KC_LOCK` | |The [Lock key](feature_key_lock.md) |
|`FUNC(n)` |`F(n)` |Call `fn_action(n)` (deprecated) |
|`M(n)` | |Call macro `n` |
|`MACROTAP(n)`| |Macro-tap `n` idk FIXME |
|Key |Aliases |Description |
|---------------|-----------|---------------------------------------------------------------------|
|`RESET` | |Put the keyboard into DFU mode for flashing |
|`DEBUG` | |Toggle debug mode |
|`EEPROM_RESET` |`EEP_RST` |Resets EEPROM state by reinitializing it |
|`KC_GESC` |`GRAVE_ESC`|Escape when tapped, <code>&#96;</code> when pressed with Shift or GUI|
|`KC_LSPO` | |Left Shift when held, `(` when tapped |
|`KC_RSPC` | |Right Shift when held, `)` when tapped |
|`KC_LEAD` | |The [Leader key](feature_leader_key.md) |
|`KC_LOCK` | |The [Lock key](feature_key_lock.md) |
|`FUNC(n)` |`F(n)` |Call `fn_action(n)` (deprecated) |
|`M(n)` | |Call macro `n` |
|`MACROTAP(n)` | |Macro-tap `n` idk FIXME |

97
docs/ref_functions.md
View File

@ -1,28 +1,79 @@
# List of Useful Core Functions To Make Your Keyboard Better
There are a lot of hidden functions in QMK that are incredible useful, or may add a bit of functionality that you've been wanting. Functions that are specific to certain features are not included here, as those will be on their respective feature page.
There are a lot of hidden functions in QMK that are incredible useful, or may add a bit of functionality that you've been wanting. Functions that are specific to certain features are not included here, as those will be on their respective feature page.
## (OLKB) Tri Layers
There are actually separate functions that you can use there, depending on what you're after.
There are actually separate functions that you can use there, depending on what you're after.
The first is the `update_tri_layer(x, y, z)` function. This function check to see if layers `x` and `y` are both on. If they are both on, then it runs on layer `z`. Otherwise, if both `x` and `y` are not both on (either only one is, or neither is), then it runs off layer `z`.
### `update_tri_layer(x, y, z)`
This function is useful if you want to create specific keys that have this functionality, but other layer keycodes won't do this.
The first is the `update_tri_layer(x, y, z)` function. This function check to see if layers `x` and `y` are both on. If they are both on, then it runs on layer `z`. Otherwise, if both `x` and `y` are not both on (either only one is, or neither is), then it runs off layer `z`.
The other function is `update_tri_layer_state(state, x, y, z)`. This function is meant to be called from they [`layer_state_set_*` functions](custom_quantum_functions.md#layer-change-code). This means that any time that you use a keycode to change the layer, this will be checked. So you could use `LT(layer, kc)` to change the layer and it will trigger the same layer check.
This function is useful if you want to create specific keys that have this functionality, but other layer keycodes won't do this.
The caveat to this method is that you cannot access the `z` layer without having `x` and `y` layers on, since if you try to activate just layer `z`, it will run this code and turn off layer `z` before you could use it.
#### Example
```c
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case LOWER:
if (record->event.pressed) {
layer_on(_LOWER);
update_tri_layer(_LOWER, _RAISE, _ADJUST);
} else {
layer_off(_LOWER);
update_tri_layer(_LOWER, _RAISE, _ADJUST);
}
return false;
break;
case RAISE:
if (record->event.pressed) {
layer_on(_RAISE);
update_tri_layer(_LOWER, _RAISE, _ADJUST);
} else {
layer_off(_RAISE);
update_tri_layer(_LOWER, _RAISE, _ADJUST);
}
return false;
break;
}
return true;
}
```
### `update_tri_layer_state(state, x, y, z)`
The other function is `update_tri_layer_state(state, x, y, z)`. This function is meant to be called from they [`layer_state_set_*` functions](custom_quantum_functions.md#layer-change-code). This means that any time that you use a keycode to change the layer, this will be checked. So you could use `LT(layer, kc)` to change the layer and it will trigger the same layer check.
The caveat to this method is that you cannot access the `z` layer without having `x` and `y` layers on, since if you try to activate just layer `z`, it will run this code and turn off layer `z` before you could use it.
#### Example
```c
uint32_t layer_state_set_user(uint32_t state) {
return update_tri_layer_state(state, _LOWER, _RAISE, _ADJUST);
}
```
Alternatively, you don't have to immediately "return" the value. This is useful if you want to add multiple tri layers, or if you want to add additional effects.
```c
uint32_t layer_state_set_user(uint32_t state) {
state = update_tri_layer_state(state, _LOWER, _RAISE, _ADJUST);
state = update_tri_layer_state(state, _RAISE, _SYMB, _SPECIAL);
return state;
}
```
## Setting the Persistent Default Layer
Do you want to set the default layer, so that it's retained even after you unplug the board? If so, this is the function for you.
Do you want to set the default layer, so that it's retained even after you unplug the board? If so, this is the function for you.
To use this, you would use `set_single_persistent_default_layer(layer)`. If you have a name defined for your layer, you can use that instead (such as _QWERTY, _DVORAK or _COLEMAK).
To use this, you would use `set_single_persistent_default_layer(layer)`. If you have a name defined for your layer, you can use that instead (such as _QWERTY, _DVORAK or _COLEMAK).
This will set the default layer, update the persistent settings, and play a tune if you have [Audio](feature_audio.md) enabled on your board, and the default layer sounds set.
This will set the default layer, update the persistent settings, and play a tune if you have [Audio](feature_audio.md) enabled on your board, and the default layer sounds set.
To configure the default layer sounds, you would want to define this in your `config.h` file, like this:
To configure the default layer sounds, you would want to define this in your `config.h` file, like this:
```c
#define DEFAULT_LAYER_SONGS { SONG(QWERTY_SOUND), \
@ -36,13 +87,33 @@ To configure the default layer sounds, you would want to define this in your `co
## Reseting the keyboard
There is the `RESET` quantum keycode that you can use. But if you want to reset the board as part of a macro, rather than hitting a key separately, you can do that.
There is the `RESET` quantum keycode that you can use. But if you want to reset the board as part of a macro, rather than hitting a key separately, you can do that.
And to do so, add `reset_keyboard()` to your function or macro, and this will reset to bootloader.
## 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). Bootmagic is one way to do this, but if that isn't enabled, 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). Bootmagic is one way to do this, but if that isn't enabled, 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.
To wipe the EEPROM, run `eeconfig_init()` from your function or macro to reset most of the settings to default.
## Tap random key
If you want to send a random character to the host computer, you can use the `tap_random_base64()` function. This [pseudorandomly](https://en.wikipedia.org/wiki/Pseudorandom_number_generator) selects a number between 0 and 63, and then sends a key press based on that selection. (0–25 is `A`–`Z`, 26–51 is `a`–`z`, 52–61 is `0`–`9`, 62 is `+` and 63 is `/`).
?> Needless to say, but this is _not_ a cryptographically secure method of generating random Base64 keys or passwords.
## Software Timers
It's possible to start timers and read values for time-specific events. Here's an example:
```c
static uint16_t key_timer;
key_timer = timer_read();
if (timer_elapsed(key_timer) < 100) {
// do something if less than 100ms have passed
} else {
// do something if 100ms or more have passed
}
```

195
docs/reference_configurator_support.md Normal file
View File

@ -0,0 +1,195 @@
# Supporting Your Keyboard in QMK Configurator
This page covers how to properly support keyboards in the [QMK Configurator](https://config.qmk.fm/).
## How the Configurator Understands Keyboards
To understand how the Configurator understands keyboards, first one must understand layout macros. For this exercise, we're going to imagine a 17-key numpad PCB, which we're going to call `numpad`.
```
┌───┬───┬───┬───┐
│NLk│ / │ * │ - │
├───┼───┼───┼───┤
│7 │8 │9 │ + │
├───┼───┼───┤ │
│4 │5 │6 │ │
├───┼───┼───┼───┤
│1 │2 │3 │Ent│
├───┴───┼───┤ │
│0 │ . │ │
└───────┴───┴───┘
```
?> For more on layout macros, see [Understanding QMK: Matrix Scanning](understanding_qmk.md?id=matrix-scanning) and [Understanding QMK: Matrix to Physical Layout Map](understanding_qmk.md?id=matrix-to-physical-layout-map).
The Configurator's API reads the keyboard's `.h` file from `qmk_firmware/keyboards/<keyboard>/<keyboard>.h`. For our numpad, this file would be `qmk_firmware/keyboards/numpad/numpad.h`:
```c
#pragma once
#define LAYOUT( \
k00, k01, k02, k03, \
k10, k11, k12, k13, \
k20, k21, k22, \
k30, k31, k32, k33, \
k40, k42 \
) { \
{ k00, k01, k02, k03 }, \
{ k10, k11, k12, k13 }, \
{ k20, k21, k22, KC_NO }, \
{ k30, k31, k32, k33 }, \
{ k40, KC_NO, k42, KC_NO } \
}
```
QMK uses `KC_NO` to designate places in the switch matrix where there is no switch. Sometimes, `XXX`, `___` or `____` are used as shorthand to make this section easier to read if it needs to be debugged. This is usually defined near the beginning of the `.h` file:
```c
#pragma once
#define XXX KC_NO
#define LAYOUT( \
k00, k01, k02, k03, \
k10, k11, k12, k13, \
k20, k21, k22, \
k30, k31, k32, k33, \
k40, k42 \
) { \
{ k00, k01, k02, k03 }, \
{ k10, k11, k12, k13 }, \
{ k20, k21, k22, XXX }, \
{ k30, k31, k32, k33 }, \
{ k40, XXX, k42, XXX } \
}
```
!> This usage differs from that of keymap macros, which almost always use `XXXXXXX` (seven capital X's) for `KC_NO` and `_______` (seven underscores) for `KC_TRNS`.
!> To prevent user confusion, using `KC_NO` is preferred.
The layout macro tells the Configurator that our keyboard has 17 keys, arranged in five rows of four columns each. Our switch positions are named `k<row><column>`, counting from 0. The names themselves actually don't matter, as long as they match between the top section, which receives the keycodes from the keymap, and the bottom half which designates where each key is in the matrix.
To display our keyboard in a way that resembles the physical keyboard, we need to build a JSON file that tells the Configurator how to tie the physical locations and sizes of our keys to our switch matrix.
## Building the JSON file
To build the JSON file, the easiest way is to build the layout in [Keyboard Layout Editor](http://www.keyboard-layout-editor.com/) ("KLE"), from which we'll feed the Raw Data into a QMK tool that converts this data into a JSON the Configurator will read and use. Since KLE opens by default with a numpad layout, we're just going to remove the Getting Started instructions, and use what's left.
Once the layout is as desired, move to the Raw Data tab in KLE, and copy the contents:
```
["Num Lock","/","*","-"],
["7\nHome","8\n↑","9\nPgUp",{h:2},"+"],
["4\n←","5","6\n→"],
["1\nEnd","2\n↓","3\nPgDn",{h:2},"Enter"],
[{w:2},"0\nIns",".\nDel"]
```
To convert this data into our JSON, go to the [QMK KLE-JSON Converter](https://qmk.fm/converter/), paste the Raw Data into the Input field, and click the Convert button. After a moment, our JSON data will appear in the Output field. Copy the contents to a new text document, and name the document `info.json`, saving it in the same folder that contains `numpad.h`.
Use the `keyboard_name` object to set the name of the keyboard. The `bootloader` object is deprecated, so it can be deleted. For instruction purposes, we will put each key's object on its own line. This is only to make the file more human-readable, and does not affect the Configurator's functionality.
```json
{
"keyboard_name": "Numpad",
"url": "",
"maintainer": "qmk",
"tags": {
"form_factor": "numpad"
},
"width": 4,
"height": 5,
"layouts": {
"LAYOUT": {
"layout": [
{"label":"Num Lock", "x":0, "y":0},
{"label":"/", "x":1, "y":0},
{"label":"*", "x":2, "y":0},
{"label":"-", "x":3, "y":0},
{"label":"7", "x":0, "y":1},
{"label":"8", "x":1, "y":1},
{"label":"9", "x":2, "y":1},
{"label":"+", "x":3, "y":1, "h":2},
{"label":"4", "x":0, "y":2},
{"label":"5", "x":1, "y":2},
{"label":"6", "x":2, "y":2},
{"label":"1", "x":0, "y":3},
{"label":"2", "x":1, "y":3},
{"label":"3", "x":2, "y":3},
{"label":"Enter", "x":3, "y":3, "h":2},
{"label":"0", "x":0, "y":4, "w":2},
{"label":".", "x":2, "y":4}
]
}
}
}
```
The `layouts` object contains the data that represents the physical layout of the keyboard. It has an object `LAYOUT`, which needs to match the name of our layout macro from `numpad.h`. The `LAYOUT` object itself has an object named `layout`, which contains one JSON object for each physical key on our keyboard, formatted as follows:
```
┌ The name of the key. Not displayed in the Configurator.
│ ┌ The key's X-axis location, in key units from the
│ │ keyboard's left edge.
│ │ ┌ The key's Y-axis location, in key units from
│ │ │ the keyboard's top (rear-facing) edge.
↓ ↓ ↓
{"label":"Num Lock", "x":0, "y":0},
```
Some objects will also have `"w"` and `"h"` keys, which represent a key's width and height, respectively.
?> For more on the `info.json` files, see [QMK Keyboard Guidelines: Keyboard Metadata](hardware_keyboard_guidelines.md?id=keyboard-metadata)
## How the Configurator Programs Keys
The Configurator's API uses the layout macro and the JSON file we've given it to create a visual representation of the keyboard that has each visual object tied to a specific key, in sequence:
key in layout macro | JSON object used
:---: | :----
k00 | {"label":"Num Lock", "x":0, "y":0}
k01 | {"label":"/", "x":1, "y":0}
k02 | {"label":"*", "x":2, "y":0}
k03 | {"label":"-", "x":3, "y":0}
k10 | {"label":"7", "x":0, "y":1}
k11 | {"label":"8", "x":1, "y":1}
k12 | {"label":"9", "x":2, "y":1}
k13 | {"label":"+", "x":3, "y":1, "h":2}
k20 | {"label":"4", "x":0, "y":2}
k21 | {"label":"5", "x":1, "y":2}
k22 | {"label":"6", "x":2, "y":2}
k30 | {"label":"1", "x":0, "y":3}
k31 | {"label":"2", "x":1, "y":3}
k32 | {"label":"3", "x":2, "y":3}
k33 | {"label":"Enter", "x":3, "y":3, "h":2}
k40 | {"label":"0", "x":0, "y":4, "w":2}
k42 | {"label":".", "x":2, "y":4}
When a user selects the top-left key in the Configurator, and assigns Num Lock to it, the Configurator builds a keymap file with `KC_NLCK` as the first key, and so on as the keymap is built. The `label` keys are not used; they are only for the user's reference in identifying specific keys when debugging the `info.json` file.
## Issues and Hazards
Currently, the Configurator does not support key rotation or non-rectangular key shapes like ISO Enter. Additionally, keys that are vertically-offset from their "row" &mdash; the arrow keys on 1800-layouts like the [TKC1800](https://github.com/qmk/qmk_firmware/tree/4ac48a61a66206beaf2fdd5f2939d8bbedd0004c/keyboards/tkc1800/) being a prominent example &mdash; confuse the KLE-to-JSON Converter, if not adjusted for by the contributor of the `info.json` file.
### Workarounds
#### Non-rectangular keys
For ISO Enter keys, QMK custom is to display it as a rectangular key, 1.25u wide and 2u high, aligned so its right edge is aligned with the right edge of the alphanumeric key block.
![](https://i.imgur.com/JKngtTw.png)
*A 60% keyboard in standard ISO layout, as rendered by QMK Configurator.*
#### Vertically-offset keys
For vertically-offset keys, place them in KLE as if they were not offset, then edit the Y-values as needed in the converted JSON file
![](https://i.imgur.com/fmDvDzR.png)
*An 1800-layout keyboard as rendered in Keyboard Layout Editor, without the vertical offset applied to the arrow keys.*
![](https://i.imgur.com/8beYMBR.png)
*A Unix diff file, showing the changes needed to vertically-offset the arrow keys in our keyboard's JSON file.*

2
docs/reference_glossary.md
View File

@ -128,7 +128,7 @@ The standard Deutsche (German) keyboard layout. Named for the first 6 letters on
The term for pressing a key while a key is already held down. Variants include 2KRO, 6KRO, and NKRO.
## Scancode
A 1 byte number that is sent as part of a HID report over USB that represents a single key. These numbers are documented in the [HID Usage Tables](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) published by the [USB-IF](http://www.usb.org/).
A 1 byte number that is sent as part of a HID report over USB that represents a single key. These numbers are documented in the [HID Usage Tables](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf) published by the [USB-IF](http://www.usb.org/).
## Space Cadet Shift
A special set of shift keys which allow you to type various types of braces by tapping the left or right shift one or more times.

43
docs/support.md Normal file
View File

@ -0,0 +1,43 @@
# Support
If you need help with something, the best place to get quick support is going to be on our [Discord Server](https://discord.gg/Uq7gcHh). There is usually somebody online, and there are a bunch of very helpful people there.
Don't forget to read our [Code of Conduct](https://qmk.fm/coc/).
## Help! I don't know where to start!
If this is the case, then you should start with our [Newbs Guide](https://docs.qmk.fm/#/newbs). There is a lot of great info there, and that should cover everything you need to get started.
If that's an issue, hop onto the [QMK Configurator](https://config.qmk.fm), as that will handle a majority of what you need there.
## Help! I'm having issues flashing!
First, head to the [Compiling/Flashing FAQ Page](https://docs.qmk.fm/#/faq_build). There is a good deal of info there, and you'll find a bunch of solutions to common issues there.
## Help, I have an issue that isn't covered by the links above
Okay, that's fine. Then please check the [open issues in our GitHub](https://github.com/qmk/qmk_firmware/issues) to see if somebody is experiencing the same thing (make sure it's not just similar, but actually the same).
If you can't find anything, then please open a [new issue](https://github.com/qmk/qmk_firmware/issues/new)!
## What if I found a bug?
Then please open an [issue](https://github.com/qmk/qmk_firmware/issues/new), and if you know how to fix it, open up a Pull Request on GitHub with the fix.
## But `git` and `GitHub` are intimidating!
Don't worry, we have some pretty nice [Guidelines](https://docs.qmk.fm/#/newbs_best_practices) on how to start using `git` and GitHub to make things easier to develop.
Additionally, you can find additional `git` and GitHub related links [here](https://docs.qmk.fm/#/newbs_learn_more_resources).
## I have a Keyboard that I want to add support for
Awesome! Open up a Pull Request for it. We'll review the code, and merge it!
### What if I want to do brand it with `QMK`?
That's amazing! We would love to assist you with that!
In fact, we have a [whole page](https://qmk.fm/powered/) dedicated to adding QMK Branding to your page and keyboard. This covers pretty much everything you need (knowledge and images) to officially support QMK.
If you have any questions about this, open an issue or head to [Discord](https://discord.gg/Uq7gcHh).

49
docs/understanding_qmk.md
View File

@ -12,7 +12,7 @@ You can think of QMK as no different from any other computer program. It is star
The reason for this is the different platforms that QMK supports. The most common platform is `lufa`, which runs on AVR processors such at the atmega32u4. We also support `chibios` and `vusb`.
We'll focus on AVR processors for the moment, which use the `lufa` platform. You can find the `main()` function in [tmk_core/protocol/lufa/lufa.c](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/protocol/lufa/lufa.c#L1129). If you browse through that function you'll find that it initializes any hardware that has been configured (including USB to the host) and then it starts the core part of the program with a [`while(1)`](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/protocol/lufa/lufa.c#L1182). This is [The Main Loop](#the_main_loop).
We'll focus on AVR processors for the moment, which use the `lufa` platform. You can find the `main()` function in [tmk_core/protocol/lufa/lufa.c](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/tmk_core/protocol/lufa/lufa.c#L1019). If you browse through that function you'll find that it initializes any hardware that has been configured (including USB to the host) and then it starts the core part of the program with a [`while(1)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/tmk_core/protocol/lufa/lufa.c#L1060). This is [The Main Loop](#the-main-loop).
## The Main Loop
@ -22,7 +22,7 @@ This section of code is called "The Main Loop" because it's responsible for loop
keyboard_task();
```
This is where all the keyboard specific functionality is dispatched. The source code for `keyboard_task()` can be found in [tmk_core/common/keyboard.c](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keyboard.c#L154), and it is responsible for detecting changes in the matrix and turning status LED's on and off.
This is where all the keyboard specific functionality is dispatched. The source code for `keyboard_task()` can be found in [tmk_core/common/keyboard.c](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/tmk_core/common/keyboard.c#L206), and it is responsible for detecting changes in the matrix and turning status LED's on and off.
Within `keyboard_task()` you'll find code to handle:
@ -77,7 +77,7 @@ At the keyboard level we define a C macro (typically named `KEYMAP()`) which map
Notice how the second block of our `KEYMAP()` macro matches the Matrix Scanning array above? This macro is what will map the matrix scanning array to keycodes. However, if you look at a 17 key numpad you'll notice that it has 3 places where the matrix could have a switch but doesn't, due to larger keys. We have populated those spaces with `KC_NO` so that our keymap definition doesn't have to.
You can also use this macro to handle unusual matrix layouts, for example the [Clueboard rev 2](https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/66/rev2/rev2.h). Explaining that is outside the scope of this document.
You can also use this macro to handle unusual matrix layouts, for example the [Clueboard rev 2](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/keyboards/clueboard/66/rev2/rev2.h). Explaining that is outside the scope of this document.
##### Keycode Assignment
@ -130,26 +130,31 @@ Comparing against our keymap we can see that the pressed key is KC_NLCK. From he
##### Process Record
The `process_record()` function itself is deceptively simple, but hidden within is a gateway to overriding functionality at various levels of QMK. The chain of events is described below, using cluecard whenever we need to look at the keyboard/keymap level functions.
The `process_record()` function itself is deceptively simple, but hidden within is a gateway to overriding functionality at various levels of QMK. The chain of events is listed below, using cluecard whenever we need to look at the keyboard/keymap level functions. Depending on options set in rule.mk or elsewhere, only a subset of the functions below will be included in final firmware.
* [`void process_record(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action.c#L128)
* [`bool process_record_quantum(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/quantum.c#L140)
* [Map this record to a keycode](https://github.com/qmk/qmk_firmware/blob/master/quantum/quantum.c#L143)
* [`bool process_record_kb(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/card/card.c#L20)
* [`bool process_record_user(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/card/keymaps/default/keymap.c#L58)
* [`bool process_midi(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_midi.c#L102)
* [`bool process_audio(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_audio.c#L10)
* [`bool process_music(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_music.c#L69)
* [`bool process_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_tap_dance.c#L75)
* [`bool process_leader(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_leader.c#L32)
* [`bool process_chording(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_chording.c#L41)
* [`bool process_combo(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_combo.c#L115)
* [`bool process_unicode(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_unicode.c#L22)
* [`bool process_ucis(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_ucis.c#L91)
* [`bool process_printer(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_printer.c#L77)
* [`bool process_auto_shift(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_auto_shift.c#L47)
* [`bool process_unicode_map(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_unicodemap.c#L47)
* [Identify and process quantum specific keycodes](https://github.com/qmk/qmk_firmware/blob/master/quantum/quantum.c#L211)
* [`void process_record(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/tmk_core/common/action.c#L172)
* [`bool process_record_quantum(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/quantum/quantum.c#L193)
* [Map this record to a keycode](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/quantum/quantum.c#L213)
* [`void preprocess_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/quantum/process_keycode/process_tap_dance.c#L115)
* [`bool process_key_lock(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/quantum/process_keycode/process_key_lock.c#L62)
* [`bool process_clicky(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/quantum/process_keycode/process_clicky.c#L44)
* [`bool process_record_kb(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/keyboards/clueboard/card/card.c#L20)
* [`bool process_record_user(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/keyboards/clueboard/card/keymaps/default/keymap.c#L58)
* [`bool process_rgb_matrix(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/fdd0f915271f79b104aa5d216566bcc3fd134e85/quantum/rgb_matrix.c#L139)
* [`bool process_midi(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_midi.c#L81)
* [`bool process_audio(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_audio.c#L19)
* [`bool process_steno(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_steno.c#L160)
* [`bool process_music(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_music.c#L114)
* [`bool process_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_tap_dance.c#L136)
* [`bool process_leader(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_leader.c#L38)
* [`bool process_combo(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_combo.c#L115)
* [`bool process_unicode(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_unicode.c#L22)
* [`bool process_ucis(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_ucis.c#L91)
* [`bool process_printer(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_printer.c#L77)
* [`bool process_auto_shift(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_auto_shift.c#L94)
* [`bool process_unicode_map(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_unicodemap.c#L47)
* [`bool process_terminal(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_terminal.c#L264)
* [Identify and process quantum specific keycodes](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/quantum.c#L287)
At any step during this chain of events a function (such as `process_record_kb()`) can `return false` to halt all further processing.

32
docs/zh/README.md Normal file
View File

@ -0,0 +1,32 @@
# QMK鍵盤固件
[![當前版本](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags)
[![築邦](https://travis-ci.org/qmk/qmk_firmware.svg?branch=master)](https://travis-ci.org/qmk/qmk_firmware)
[![不和諧](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh)
[![文檔狀態](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm)
[![GitHub的貢獻者](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
[![GitHub的叉](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
## 什麼是QMK固件？
QMK是一個由社群維護的開源鍵盤韌體，其中包含了QMK Toolbox、qmk.fm和其它文件。QMK韌體是以[tmk\_keyboard](http://github.com/tmk/tmk_keyboard)為基礎，讓一些有用的功能在Atmel AVR控制器實現，使用於[OLKB](https://olkb.com)、[ergodox EZ](http://www.ergodox-ez.com)，和[Clueboard](http://clueboard.co/)的產品中。它也被移植到使用ChibiOS的ARM晶片上。你也可以用它來讓你徒手佈線，或是客製的鍵盤PCB發揮功能。
## 如何得到QMK
如果你打算貢獻鍵盤佈局，鍵盤或功能QMK，最容易做的事情是[叉通過Github上爬行](https://github.com/qmk/qmk_firmware#fork-destination-box)，和克隆你爬在本地進行更改，推動他們，然後打開從你的叉子[拉請求](https://github.com/qmk/qmk_firmware/pulls)。
否則，您可以直接下載([拉鍊](https://github.com/qmk/qmk_firmware/zipball/master) [焦油](https://github.com/qmk/qmk_firmware/tarball/master))，或者通過GIT中克隆它(`git@github.com:qmk/qmk_firmware.git`)或HTTP(`https://github.com/qmk/qmk_firmware.git`)。
## 如何編譯
你可以編譯之前，你需要[安裝環境](getting_started_build_tools.md)用於AVR或/和ARM開發。一旦完成，你會使用`make`命令建立一個鍵盤並用以下符號鍵盤佈局
make planck/rev4:default
這將建立`rev4` `planck`的修訂與`default`鍵盤映射。並非所有鍵盤有一個修訂版(也稱為子項目或文件夾)，在這種情況下，它可以被省略：
make preonic:default
## 如何赶近
QMK有很多[特點](features.md)探索和很好的協議[參考文獻](http://docs.qmk.fm)挖通的。大部分功能通過修改[鍵盤映射(keymap.md)，並改變[鍵碼](keycodes.md)冤大頭。

99
docs/zh/_sidebar.md Normal file
View File

@ -0,0 +1,99 @@
* [完全指南菜鳥](zh/newbs.md)
* [入門](zh/newbs_getting_started.md)
* [構建第一個固件](zh/newbs_building_firmware.md)
* [刷新固件](zh/newbs_flashing.md)
* [測試和調試](zh/newbs_testing_debugging.md)
* [最佳實踐](zh/newbs_best_practices.md)
* [學習資源](zh/newbs_learn_more_resources.md)
* [QMK基礎](zh/README.md)
* [QMK簡介](zh/getting_started_introduction.md)
* [特約QMK](zh/contributing.md)
* [如何使用Github上](zh/getting_started_github.md)
* [獲得幫助](zh/getting_started_getting_help.md)
* [常問問題](zh/faq.md)
* [常問問題](zh/faq_general.md)
* [構建/編譯QMK](zh/faq_build.md)
* [調試/故障排除QMK](zh/faq_debug.md)
* [鍵盤佈局](zh/faq_keymap.md)
* 詳細指南
* [安裝編譯工具](zh/getting_started_build_tools.md)
* [流浪漢指南](zh/getting_started_vagrant.md)
* [構建/編譯器指令](zh/getting_started_make_guide.md)
* [刷新固件](zh/flashing.md)
* [定制功能](zh/custom_quantum_functions.md)
* [鍵盤映射概述](zh/keymap.md)
* [硬件](zh/hardware.md)
* [AVR處理器](zh/hardware_avr.md)
* [司機](zh/hardware_drivers.md)
* 參考
* [Keyboard Guidelines](zh/hardware_keyboard_guidelines.md)
* [Config Options](zh/config_options.md)
* [Keycodes](zh/keycodes.md)
* [Documentation Best Practices](zh/documentation_best_practices.md)
* [Documentation Templates](zh/documentation_templates.md)
* [Glossary](zh/reference_glossary.md)
* [Unit Testing](zh/unit_testing.md)
* [Useful Functions](zh/ref_functions.md)
* [Configurator Support](zh/reference_configurator_support.md)
* [特點](zh/features.md)
* [Basic Keycodes](zh/keycodes_basic.md)
* [Quantum Keycodes](zh/quantum_keycodes.md)
* [Advanced Keycodes](zh/feature_advanced_keycodes.md)
* [Audio](zh/feature_audio.md)
* [Auto Shift](zh/feature_auto_shift.md)
* [Backlight](zh/feature_backlight.md)
* [Bluetooth](zh/feature_bluetooth.md)
* [Bootmagic](zh/feature_bootmagic.md)
* [Combos](zh/feature_combo)
* [Command](zh/feature_command.md)
* [Dynamic Macros](zh/feature_dynamic_macros.md)
* [Encoders](zh/feature_encoders.md)
* [Grave Escape](zh/feature_grave_esc.md)
* [Key Lock](zh/feature_key_lock.md)
* [Layouts](zh/feature_layouts.md)
* [Leader Key](zh/feature_leader_key.md)
* [Macros](zh/feature_macros.md)
* [Mouse Keys](zh/feature_mouse_keys.md)
* [One Shot Keys](zh/feature_advanced_keycodes.md#one-shot-keys)
* [Pointing Device](zh/feature_pointing_device.md)
* [PS/2 Mouse](zh/feature_ps2_mouse.md)
* [RGB Lighting](zh/feature_rgblight.md)
* [RGB Matrix](zh/feature_rgb_matrix.md)
* [Space Cadet Shift](zh/feature_space_cadet_shift.md)
* [Space Cadet Shift Enter](zh/feature_space_cadet_shift_enter.md)
* [Stenography](zh/feature_stenography.md)
* [Swap Hands](zh/feature_swap_hands.md)
* [Tap Dance](zh/feature_tap_dance.md)
* [Terminal](zh/feature_terminal.md)
* [Thermal Printer](zh/feature_thermal_printer.md)
* [Unicode](zh/feature_unicode.md)
* [Userspace](zh/feature_userspace.md)
* [US ANSI Shifted Keys](zh/keycodes_us_ansi_shifted.md)
* 對於製造商和遊戲模組
* [Hand Wiring Guide](zh/hand_wire.md)
* [ISP Flashing Guide](zh/isp_flashing_guide.md)
* [ARM Debugging Guide](zh/arm_debugging.md)
* [I2C Driver](zh/i2c_driver.md)
* 為了更深入的了解
* [How Keyboards Work](zh/how_keyboards_work.md)
* [Understanding QMK](zh/understanding_qmk.md)
* 其它主題
* [Using Eclipse with QMK](zh/eclipse.md)
* QMK內部（進行中）
* [Defines](zh/internals_defines.md)
* [Input Callback Reg](zh/internals_input_callback_reg.md)
* [Midi Device](zh/internals_midi_device.md)
* [Midi Device Setup Process](zh/internals_midi_device_setup_process.md)
* [Midi Util](zh/internals_midi_util.md)
* [Send Functions](zh/internals_send_functions.md)
* [Sysex Tools](zh/internals_sysex_tools.md)

15
drivers/arm/i2c_master.c
View File

@ -26,12 +26,13 @@
*/
#include "i2c_master.h"
#include "quantum.h"
#include <string.h>
#include <hal.h>
static uint8_t i2c_address;
// This configures the I2C clock to 400Mhz assuming a 72Mhz clock
// This configures the I2C clock to 400khz assuming a 72Mhz clock
// For more info : https://www.st.com/en/embedded-software/stsw-stm32126.html
static const I2CConfig i2cconfig = {
STM32_TIMINGR_PRESC(15U) |
@ -41,13 +42,17 @@ static const I2CConfig i2cconfig = {
0
};
__attribute__ ((weak))
void i2c_init(void)
{
palSetGroupMode(GPIOB, GPIOB_PIN6 | GPIOB_PIN7, 0, PAL_MODE_INPUT); // Try releasing special pins for a short time
chThdSleepMilliseconds(10);
// Try releasing special pins for a short time
palSetPadMode(GPIOB, 6, PAL_MODE_INPUT);
palSetPadMode(GPIOB, 7, PAL_MODE_INPUT);
palSetPadMode(GPIOB, 6, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP);
palSetPadMode(GPIOB, 7, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP);
chThdSleepMilliseconds(10);
palSetPadMode(GPIOB, 6, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN);
palSetPadMode(GPIOB, 7, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN);
//i2cInit(); //This is invoked by halInit() so no need to redo it.
}

1
drivers/arm/i2c_master.h
View File

@ -34,6 +34,7 @@ void i2c_init(void);
uint8_t i2c_start(uint8_t address);
uint8_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);
uint8_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);
uint8_t i2c_transmit_receive(uint8_t address, uint8_t * tx_body, uint16_t tx_length, uint8_t * rx_body, uint16_t rx_length);
uint8_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);
uint8_t i2c_readReg(uint8_t devaddr, uint8_t* regaddr, uint8_t* data, uint16_t length, uint16_t timeout);
uint8_t i2c_stop(uint16_t timeout);

2
drivers/avr/i2c_master.c
View File

@ -8,7 +8,9 @@
#include "i2c_master.h"
#include "timer.h"
#ifndef F_SCL
#define F_SCL 400000UL // SCL frequency
#endif
#define Prescaler 1
#define TWBR_val ((((F_CPU / F_SCL) / Prescaler) - 16 ) / 2)

3
drivers/avr/ws2812.h
View File

@ -69,7 +69,4 @@ void ws2812_sendarray_mask(uint8_t *array,uint16_t length, uint8_t pinmask);
#define CONCAT_EXP(a, b) CONCAT(a, b)
#endif
// #define ws2812_PORTREG CONCAT_EXP(PORT,ws2812_port)
// #define ws2812_DDRREG CONCAT_EXP(DDR,ws2812_port)
#endif /* LIGHT_WS2812_H_ */

129
drivers/haptic/DRV2605L.c Normal file
View File

@ -0,0 +1,129 @@
/* Copyright 2018 ishtob
* Driver for DRV2605L written for 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 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 "DRV2605L.h"
#include "print.h"
#include <stdlib.h>
#include <stdio.h>
#include <math.h>
uint8_t DRV2605L_transfer_buffer[20];
uint8_t DRV2605L_tx_register[0];
uint8_t DRV2605L_read_buffer[0];
uint8_t DRV2605L_read_register;
void DRV_write(uint8_t drv_register, uint8_t settings) {
DRV2605L_transfer_buffer[0] = drv_register;
DRV2605L_transfer_buffer[1] = settings;
i2c_transmit(DRV2605L_BASE_ADDRESS << 1, DRV2605L_transfer_buffer, 2, 100);
}
uint8_t DRV_read(uint8_t regaddress) {
DRV2605L_tx_register[0] = regaddress;
if (MSG_OK != i2c_transmit_receive(DRV2605L_BASE_ADDRESS << 1,
DRV2605L_tx_register, 1,
DRV2605L_read_buffer, 1
)){
printf("err reading reg \n");
}
DRV2605L_read_register = (uint8_t)DRV2605L_read_buffer[0];
return DRV2605L_read_register;
}
void DRV_init(void)
{
i2c_init();
i2c_start(DRV2605L_BASE_ADDRESS);
/* 0x07 sets DRV2605 into calibration mode */
DRV_write(DRV_MODE,0x07);
// DRV_write(DRV_FEEDBACK_CTRL,0xB6);
#if FB_ERM_LRA == 0
/* ERM settings */
DRV_write(DRV_RATED_VOLT, (RATED_VOLTAGE/21.33)*1000);
#if ERM_OPEN_LOOP == 0
DRV_write(DRV_OVERDRIVE_CLAMP_VOLT, (((V_PEAK*(DRIVE_TIME+BLANKING_TIME+IDISS_TIME))/0.02133)/(DRIVE_TIME-0.0003)));
#elif ERM_OPEN_LOOP == 1
DRV_write(DRV_OVERDRIVE_CLAMP_VOLT, (V_PEAK/0.02196));
#endif
#elif FB_ERM_LRA == 1
DRV_write(DRV_RATED_VOLT, ((V_RMS * sqrt(1 - ((4 * ((150+(SAMPLE_TIME*50))*0.000001)) + 0.0003)* F_LRA)/0.02071)));
#if LRA_OPEN_LOOP == 0
DRV_write(DRV_OVERDRIVE_CLAMP_VOLT, ((V_PEAK/sqrt(1-(F_LRA*0.0008))/0.02133)));
#elif LRA_OPEN_LOOP == 1
DRV_write(DRV_OVERDRIVE_CLAMP_VOLT, (V_PEAK/0.02196));
#endif
#endif
DRVREG_FBR FB_SET;
FB_SET.Bits.ERM_LRA = FB_ERM_LRA;
FB_SET.Bits.BRAKE_FACTOR = FB_BRAKEFACTOR;
FB_SET.Bits.LOOP_GAIN =FB_LOOPGAIN;
FB_SET.Bits.BEMF_GAIN = 0; /* auto-calibration populates this field*/
DRV_write(DRV_FEEDBACK_CTRL, (uint8_t) FB_SET.Byte);
DRVREG_CTRL1 C1_SET;
C1_SET.Bits.C1_DRIVE_TIME = DRIVE_TIME;
C1_SET.Bits.C1_AC_COUPLE = AC_COUPLE;
C1_SET.Bits.C1_STARTUP_BOOST = STARTUP_BOOST;
DRV_write(DRV_CTRL_1, (uint8_t) C1_SET.Byte);
DRVREG_CTRL2 C2_SET;
C2_SET.Bits.C2_BIDIR_INPUT = BIDIR_INPUT;
C2_SET.Bits.C2_BRAKE_STAB = BRAKE_STAB;
C2_SET.Bits.C2_SAMPLE_TIME = SAMPLE_TIME;
C2_SET.Bits.C2_BLANKING_TIME = BLANKING_TIME;
C2_SET.Bits.C2_IDISS_TIME = IDISS_TIME;
DRV_write(DRV_CTRL_2, (uint8_t) C2_SET.Byte);
DRVREG_CTRL3 C3_SET;
C3_SET.Bits.C3_LRA_OPEN_LOOP = LRA_OPEN_LOOP;
C3_SET.Bits.C3_N_PWM_ANALOG = N_PWM_ANALOG;
C3_SET.Bits.C3_LRA_DRIVE_MODE = LRA_DRIVE_MODE;
C3_SET.Bits.C3_DATA_FORMAT_RTO = DATA_FORMAT_RTO;
C3_SET.Bits.C3_SUPPLY_COMP_DIS = SUPPLY_COMP_DIS;
C3_SET.Bits.C3_ERM_OPEN_LOOP = ERM_OPEN_LOOP;
C3_SET.Bits.C3_NG_THRESH = NG_THRESH;
DRV_write(DRV_CTRL_3, (uint8_t) C3_SET.Byte);
DRVREG_CTRL4 C4_SET;
C4_SET.Bits.C4_ZC_DET_TIME = ZC_DET_TIME;
C4_SET.Bits.C4_AUTO_CAL_TIME = AUTO_CAL_TIME;
DRV_write(DRV_CTRL_4, (uint8_t) C4_SET.Byte);
DRV_write(DRV_LIB_SELECTION,LIB_SELECTION);
//start autocalibration
DRV_write(DRV_GO, 0x01);
/* 0x00 sets DRV2605 out of standby and to use internal trigger
* 0x01 sets DRV2605 out of standby and to use external trigger */
DRV_write(DRV_MODE,0x00);
/* 0x06: LRA library */
DRV_write(DRV_WAVEFORM_SEQ_1, 0x01);
/* 0xB9: LRA, 4x brake factor, medium gain, 7.5x back EMF
* 0x39: ERM, 4x brake factor, medium gain, 1.365x back EMF */
/* TODO: setup auto-calibration as part of initiation */
}
void DRV_pulse(uint8_t sequence)
{
DRV_write(DRV_GO, 0x00);
DRV_write(DRV_WAVEFORM_SEQ_1, sequence);
DRV_write(DRV_GO, 0x01);
}

394
drivers/haptic/DRV2605L.h Normal file
View File

@ -0,0 +1,394 @@
/* Copyright 2018 ishtob
* Driver for DRV2605L written for 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 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 "i2c_master.h"
/* Initialization settings
* Feedback Control Settings */
#ifndef FB_ERM_LRA
#define FB_ERM_LRA 1 /* For ERM:0 or LRA:1*/
#endif
#ifndef FB_BRAKEFACTOR
#define FB_BRAKEFACTOR 3 /* For 1x:0, 2x:1, 3x:2, 4x:3, 6x:4, 8x:5, 16x:6, Disable Braking:7 */
#endif
#ifndef FB_LOOPGAIN
#define FB_LOOPGAIN 1 /* For Low:0, Medium:1, High:2, Very High:3 */
#endif
#ifndef RATED_VOLTAGE
#define RATED_VOLTAGE 2 /* 2v as safe range in case device voltage is not set */
#ifndef V_PEAK
#define V_PEAK 2.8
#endif
#endif
/* LRA specific settings */
#if FB_ERM_LRA == 1
#ifndef V_RMS
#define V_RMS 2.0
#endif
#ifndef V_PEAK
#define V_PEAK 2.1
#endif
#ifndef F_LRA
#define F_LRA 205
#endif
#endif
/* Library Selection */
#ifndef LIB_SELECTION
#if FB_ERM_LRA == 1
#define LIB_SELECTION 6 /* For Empty:0' TS2200 library A to D:1-5, LRA Library: 6 */
#else
#define LIB_SELECTION 1
#endif
#endif
/* Control 1 register settings */
#ifndef DRIVE_TIME
#define DRIVE_TIME 25
#endif
#ifndef AC_COUPLE
#define AC_COUPLE 0
#endif
#ifndef STARTUP_BOOST
#define STARTUP_BOOST 1
#endif
/* Control 2 Settings */
#ifndef BIDIR_INPUT
#define BIDIR_INPUT 1
#endif
#ifndef BRAKE_STAB
#define BRAKE_STAB 1 /* Loopgain is reduced when braking is almost complete to improve stability */
#endif
#ifndef SAMPLE_TIME
#define SAMPLE_TIME 3
#endif
#ifndef BLANKING_TIME
#define BLANKING_TIME 1
#endif
#ifndef IDISS_TIME
#define IDISS_TIME 1
#endif
/* Control 3 settings */
#ifndef NG_THRESH
#define NG_THRESH 2
#endif
#ifndef ERM_OPEN_LOOP
#define ERM_OPEN_LOOP 1
#endif
#ifndef SUPPLY_COMP_DIS
#define SUPPLY_COMP_DIS 0
#endif
#ifndef DATA_FORMAT_RTO
#define DATA_FORMAT_RTO 0
#endif
#ifndef LRA_DRIVE_MODE
#define LRA_DRIVE_MODE 0
#endif
#ifndef N_PWM_ANALOG
#define N_PWM_ANALOG 0
#endif
#ifndef LRA_OPEN_LOOP
#define LRA_OPEN_LOOP 0
#endif
/* Control 4 settings */
#ifndef ZC_DET_TIME
#define ZC_DET_TIME 0
#endif
#ifndef AUTO_CAL_TIME
#define AUTO_CAL_TIME 3
#endif
/* register defines -------------------------------------------------------- */
#define DRV2605L_BASE_ADDRESS 0x5A /* DRV2605L Base address */
#define DRV_STATUS 0x00
#define DRV_MODE 0x01
#define DRV_RTP_INPUT 0x02
#define DRV_LIB_SELECTION 0x03
#define DRV_WAVEFORM_SEQ_1 0x04
#define DRV_WAVEFORM_SEQ_2 0x05
#define DRV_WAVEFORM_SEQ_3 0x06
#define DRV_WAVEFORM_SEQ_4 0x07
#define DRV_WAVEFORM_SEQ_5 0x08
#define DRV_WAVEFORM_SEQ_6 0x09
#define DRV_WAVEFORM_SEQ_7 0x0A
#define DRV_WAVEFORM_SEQ_8 0x0B
#define DRV_GO 0x0C
#define DRV_OVERDRIVE_TIME_OFFSET 0x0D
#define DRV_SUSTAIN_TIME_OFFSET_P 0x0E
#define DRV_SUSTAIN_TIME_OFFSET_N 0x0F
#define DRV_BRAKE_TIME_OFFSET 0x10
#define DRV_AUDIO_2_VIBE_CTRL 0x11
#define DRV_AUDIO_2_VIBE_MIN_IN 0x12
#define DRV_AUDIO_2_VIBE_MAX_IN 0x13
#define DRV_AUDIO_2_VIBE_MIN_OUTDRV 0x14
#define DRV_AUDIO_2_VIBE_MAX_OUTDRV 0x15
#define DRV_RATED_VOLT 0x16
#define DRV_OVERDRIVE_CLAMP_VOLT 0x17
#define DRV_AUTO_CALIB_COMP_RESULT 0x18
#define DRV_AUTO_CALIB_BEMF_RESULT 0x19
#define DRV_FEEDBACK_CTRL 0x1A
#define DRV_CTRL_1 0x1B
#define DRV_CTRL_2 0x1C
#define DRV_CTRL_3 0x1D
#define DRV_CTRL_4 0x1E
#define DRV_CTRL_5 0x1F
#define DRV_OPEN_LOOP_PERIOD 0x20
#define DRV_VBAT_VOLT_MONITOR 0x21
#define DRV_LRA_RESONANCE_PERIOD 0x22
void DRV_init(void);
void DRV_write(const uint8_t drv_register, const uint8_t settings);
uint8_t DRV_read(const uint8_t regaddress);
void DRV_pulse(const uint8_t sequence);
typedef enum DRV_EFFECT{
clear_sequence = 0,
strong_click = 1,
strong_click_60 = 2,
strong_click_30 = 3,
sharp_click = 4,
sharp_click_60 = 5,
sharp_click_30 = 6,
soft_bump = 7,
soft_bump_60 = 8,
soft_bump_30 = 9,
dbl_click = 10,
dbl_click_60 = 11,
trp_click = 12,
soft_fuzz = 13,
strong_buzz = 14,
alert_750ms = 15,
alert_1000ms = 16,
strong_click1 = 17,
strong_click2_80 = 18,
strong_click3_60 = 19,
strong_click4_30 = 20,
medium_click1 = 21,
medium_click2_80 = 22,
medium_click3_60 = 23,
sharp_tick1 = 24,
sharp_tick2_80 = 25,
sharp_tick3_60 = 26,
sh_dblclick_str = 27,
sh_dblclick_str_80 = 28,
sh_dblclick_str_60 = 29,
sh_dblclick_str_30 = 30,
sh_dblclick_med = 31,
sh_dblclick_med_80 = 32,
sh_dblclick_med_60 = 33,
sh_dblsharp_tick = 34,
sh_dblsharp_tick_80 = 35,
sh_dblsharp_tick_60 = 36,
lg_dblclick_str = 37,
lg_dblclick_str_80 = 38,
lg_dblclick_str_60 = 39,
lg_dblclick_str_30 = 40,
lg_dblclick_med = 41,
lg_dblclick_med_80 = 42,
lg_dblclick_med_60 = 43,
lg_dblsharp_tick = 44,
lg_dblsharp_tick_80 = 45,
lg_dblsharp_tick_60 = 46,
buzz = 47,
buzz_80 = 48,
buzz_60 = 49,
buzz_40 = 50,
buzz_20 = 51,
pulsing_strong = 52,
pulsing_strong_80 = 53,
pulsing_medium = 54,
pulsing_medium_80 = 55,
pulsing_sharp = 56,
pulsing_sharp_80 = 57,
transition_click = 58,
transition_click_80 = 59,
transition_click_60 = 60,
transition_click_40 = 61,
transition_click_20 = 62,
transition_click_10 = 63,
transition_hum = 64,
transition_hum_80 = 65,
transition_hum_60 = 66,
transition_hum_40 = 67,
transition_hum_20 = 68,
transition_hum_10 = 69,
transition_rampdown_long_smooth1 = 70,
transition_rampdown_long_smooth2 = 71,
transition_rampdown_med_smooth1 = 72,
transition_rampdown_med_smooth2 = 73,
transition_rampdown_short_smooth1 = 74,
transition_rampdown_short_smooth2 = 75,
transition_rampdown_long_sharp1 = 76,
transition_rampdown_long_sharp2 = 77,
transition_rampdown_med_sharp1 = 78,
transition_rampdown_med_sharp2 = 79,
transition_rampdown_short_sharp1 = 80,
transition_rampdown_short_sharp2 = 81,
transition_rampup_long_smooth1 = 82,
transition_rampup_long_smooth2 = 83,
transition_rampup_med_smooth1 = 84,
transition_rampup_med_smooth2 = 85,
transition_rampup_short_smooth1 = 86,
transition_rampup_short_smooth2 = 87,
transition_rampup_long_sharp1 = 88,
transition_rampup_long_sharp2 = 89,
transition_rampup_med_sharp1 = 90,
transition_rampup_med_sharp2 = 91,
transition_rampup_short_sharp1 = 92,
transition_rampup_short_sharp2 = 93,
transition_rampdown_long_smooth1_50 = 94,
transition_rampdown_long_smooth2_50 = 95,
transition_rampdown_med_smooth1_50 = 96,
transition_rampdown_med_smooth2_50 = 97,
transition_rampdown_short_smooth1_50 = 98,
transition_rampdown_short_smooth2_50 = 99,
transition_rampdown_long_sharp1_50 = 100,
transition_rampdown_long_sharp2_50 = 101,
transition_rampdown_med_sharp1_50 = 102,
transition_rampdown_med_sharp2_50 = 103,
transition_rampdown_short_sharp1_50 = 104,
transition_rampdown_short_sharp2_50 = 105,
transition_rampup_long_smooth1_50 = 106,
transition_rampup_long_smooth2_50 = 107,
transition_rampup_med_smooth1_50 = 108,
transition_rampup_med_smooth2_50 = 109,
transition_rampup_short_smooth1_50 = 110,
transition_rampup_short_smooth2_50 = 111,
transition_rampup_long_sharp1_50 = 112,
transition_rampup_long_sharp2_50 = 113,
transition_rampup_med_sharp1_50 = 114,
transition_rampup_med_sharp2_50 = 115,
transition_rampup_short_sharp1_50 = 116,
transition_rampup_short_sharp2_50 = 117,
long_buzz_for_programmatic_stopping = 118,
smooth_hum1_50 = 119,
smooth_hum2_40 = 120,
smooth_hum3_30 = 121,
smooth_hum4_20 = 122,
smooth_hum5_10 = 123,
} DRV_EFFECT;
/* Register bit array unions */
typedef union DRVREG_STATUS { /* register 0x00 */
uint8_t Byte;
struct {
uint8_t OC_DETECT :1; /* set to 1 when overcurrent event is detected */
uint8_t OVER_TEMP :1; /* set to 1 when device exceeds temp threshold */
uint8_t FB_STS :1; /* set to 1 when feedback controller has timed out */
/* auto-calibration routine and diagnostic result
* result | auto-calibation | diagnostic |
* 0 | passed | actuator func normal |
* 1 | failed | actuator func fault* |
* * actuator is not present or is shorted, timing out, or giving out–of-range back-EMF */
uint8_t DIAG_RESULT :1;
uint8_t :1;
uint8_t DEVICE_ID :3; /* Device IDs 3: DRV2605 4: DRV2604 5: DRV2604L 6: DRV2605L */
} Bits;
} DRVREG_STATUS;
typedef union DRVREG_MODE { /* register 0x01 */
uint8_t Byte;
struct {
uint8_t MODE :3; /* Mode setting */
uint8_t :3;
uint8_t STANDBY :1; /* 0:standby 1:ready */
} Bits;
} DRVREG_MODE;
typedef union DRVREG_WAIT {
uint8_t Byte;
struct {
uint8_t WAIT_MODE :1; /* Set to 1 to interpret as wait for next 7 bits x10ms */
uint8_t WAIT_TIME :7;
} Bits;
} DRVREG_WAIT;
typedef union DRVREG_FBR{ /* register 0x1A */
uint8_t Byte;
struct {
uint8_t BEMF_GAIN :2;
uint8_t LOOP_GAIN :2;
uint8_t BRAKE_FACTOR :3;
uint8_t ERM_LRA :1;
} Bits;
} DRVREG_FBR;
typedef union DRVREG_CTRL1{ /* register 0x1B */
uint8_t Byte;
struct {
uint8_t C1_DRIVE_TIME :5;
uint8_t C1_AC_COUPLE :1;
uint8_t :1;
uint8_t C1_STARTUP_BOOST :1;
} Bits;
} DRVREG_CTRL1;
typedef union DRVREG_CTRL2{ /* register 0x1C */
uint8_t Byte;
struct {
uint8_t C2_IDISS_TIME :2;
uint8_t C2_BLANKING_TIME :2;
uint8_t C2_SAMPLE_TIME :2;
uint8_t C2_BRAKE_STAB :1;
uint8_t C2_BIDIR_INPUT :1;
} Bits;
} DRVREG_CTRL2;
typedef union DRVREG_CTRL3{ /* register 0x1D */
uint8_t Byte;
struct {
uint8_t C3_LRA_OPEN_LOOP :1;
uint8_t C3_N_PWM_ANALOG :1;
uint8_t C3_LRA_DRIVE_MODE :1;
uint8_t C3_DATA_FORMAT_RTO :1;
uint8_t C3_SUPPLY_COMP_DIS :1;
uint8_t C3_ERM_OPEN_LOOP :1;
uint8_t C3_NG_THRESH :2;
} Bits;
} DRVREG_CTRL3;
typedef union DRVREG_CTRL4{ /* register 0x1E */
uint8_t Byte;
struct {
uint8_t C4_OTP_PROGRAM :1;
uint8_t :1;
uint8_t C4_OTP_STATUS :1;
uint8_t :1;
uint8_t C4_AUTO_CAL_TIME :2;
uint8_t C4_ZC_DET_TIME :2;
} Bits;
} DRVREG_CTRL4;
typedef union DRVREG_CTRL5{ /* register 0x1F */
uint8_t Byte;
struct {
uint8_t C5_IDISS_TIME :2;
uint8_t C5_BLANKING_TIME :2;
uint8_t C5_PLAYBACK_INTERVAL :1;
uint8_t C5_LRA_AUTO_OPEN_LOOP :1;
uint8_t C5_AUTO_OL_CNT :2;
} Bits;
} DRVREG_CTRL5;

102
drivers/issi/is31fl3218.c Normal file
View File

@ -0,0 +1,102 @@
/* Copyright 2018 Jason Williams (Wilba)
*
* 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 "is31fl3218.h"
#include "i2c_master.h"
// This is the full 8-bit address
#define ISSI_ADDRESS 0b10101000
// These are the register addresses
#define ISSI_REG_SHUTDOWN 0x00
#define ISSI_REG_PWM 0x01
#define ISSI_REG_CONTROL 0x13
#define ISSI_REG_UPDATE 0x16
#define ISSI_REG_RESET 0x17
// Default timeout if no I2C response
#define ISSI_TIMEOUT 100
// Reusable buffer for transfers
uint8_t g_twi_transfer_buffer[20];
// IS31FL3218 has 18 PWM outputs and a fixed I2C address, so no chaining.
// If used as RGB LED driver, LEDs are assigned RGB,RGB,RGB,RGB,RGB,RGB
uint8_t g_pwm_buffer[18];
bool g_pwm_buffer_update_required = false;
void IS31FL3218_write_register( uint8_t reg, uint8_t data )
{
g_twi_transfer_buffer[0] = reg;
g_twi_transfer_buffer[1] = data;
i2c_transmit( ISSI_ADDRESS, g_twi_transfer_buffer, 2, ISSI_TIMEOUT);
}
void IS31FL3218_write_pwm_buffer( uint8_t *pwm_buffer )
{
g_twi_transfer_buffer[0] = ISSI_REG_PWM;
for ( int i=0; i<18; i++ ) {
g_twi_transfer_buffer[1+i] = pwm_buffer[i];
}
i2c_transmit( ISSI_ADDRESS, g_twi_transfer_buffer, 19, ISSI_TIMEOUT);
}
void IS31FL3218_init(void)
{
// In case we ever want to reinitialize (?)
IS31FL3218_write_register( ISSI_REG_RESET, 0x00 );
// Turn off software shutdown
IS31FL3218_write_register( ISSI_REG_SHUTDOWN, 0x01 );
// Set all PWM values to zero
for ( uint8_t i = 0; i < 18; i++ ) {
IS31FL3218_write_register( ISSI_REG_PWM+i, 0x00 );
}
// Enable all channels
for ( uint8_t i = 0; i < 3; i++ ) {
IS31FL3218_write_register( ISSI_REG_CONTROL+i, 0b00111111 );
}
// Load PWM registers and LED Control register data
IS31FL3218_write_register( ISSI_REG_UPDATE, 0x01 );
}
void IS31FL3218_set_color( int index, uint8_t red, uint8_t green, uint8_t blue )
{
g_pwm_buffer[index * 3 + 0] = red;
g_pwm_buffer[index * 3 + 1] = green;
g_pwm_buffer[index * 3 + 2] = blue;
g_pwm_buffer_update_required = true;
}
void IS31FL3218_set_color_all( uint8_t red, uint8_t green, uint8_t blue )
{
for ( int i = 0; i < 6; i++ ) {
IS31FL3218_set_color( i, red, green, blue );
}
}
void IS31FL3218_update_pwm_buffers(void)
{
if ( g_pwm_buffer_update_required ) {
IS31FL3218_write_pwm_buffer( g_pwm_buffer );
// Load PWM registers and LED Control register data
IS31FL3218_write_register( ISSI_REG_UPDATE, 0x01 );
}
g_pwm_buffer_update_required = false;
}

24
drivers/issi/is31fl3218.h Normal file
View File

@ -0,0 +1,24 @@
/* Copyright 2018 Jason Williams (Wilba)
*
* 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>
void IS31FL3218_init(void);
void IS31FL3218_set_color( int index, uint8_t red, uint8_t green, uint8_t blue );
void IS31FL3218_set_color_all( uint8_t red, uint8_t green, uint8_t blue );
void IS31FL3218_update_pwm_buffers(void);

1
drivers/issi/is31fl3731.c
View File

@ -268,4 +268,3 @@ void IS31FL3731_update_led_control_registers( uint8_t addr1, uint8_t addr2 )
}
}
}

3
drivers/issi/is31fl3733.c
View File

@ -24,10 +24,10 @@
#include "wait.h"
#endif
#include "is31fl3733.h"
#include <string.h>
#include "i2c_master.h"
#include "progmem.h"
#include "rgb_matrix.h"
// 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)
@ -250,4 +250,3 @@ void IS31FL3733_update_led_control_registers( uint8_t addr1, uint8_t addr2 )
}
}
}

306
drivers/issi/is31fl3736.c Normal file
View File

@ -0,0 +1,306 @@
/* Copyright 2018 Jason Williams (Wilba)
*
* 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/>.
*/
#ifdef __AVR__
#include <avr/interrupt.h>
#include <avr/io.h>
#include <util/delay.h>
#else
#include "wait.h"
#endif
#include "is31fl3736.h"
#include <string.h>
#include "i2c_master.h"
#include "progmem.h"
// 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)
// The address will vary depending on your wiring:
// 00 <-> GND
// 01 <-> SCL
// 10 <-> SDA
// 11 <-> VCC
// ADDR1 represents A1:A0 of the 7-bit address.
// ADDR2 represents A3:A2 of the 7-bit address.
// The result is: 0b101(ADDR2)(ADDR1)
#define ISSI_ADDR_DEFAULT 0x50
#define ISSI_COMMANDREGISTER 0xFD
#define ISSI_COMMANDREGISTER_WRITELOCK 0xFE
#define ISSI_INTERRUPTMASKREGISTER 0xF0
#define ISSI_INTERRUPTSTATUSREGISTER 0xF1
#define ISSI_PAGE_LEDCONTROL 0x00 //PG0
#define ISSI_PAGE_PWM 0x01 //PG1
#define ISSI_PAGE_AUTOBREATH 0x02 //PG2
#define ISSI_PAGE_FUNCTION 0x03 //PG3
#define ISSI_REG_CONFIGURATION 0x00 //PG3
#define ISSI_REG_GLOBALCURRENT 0x01 //PG3
#define ISSI_REG_RESET 0x11// PG3
#define ISSI_REG_SWPULLUP 0x0F //PG3
#define ISSI_REG_CSPULLUP 0x10 //PG3
#ifndef ISSI_TIMEOUT
#define ISSI_TIMEOUT 100
#endif
#ifndef ISSI_PERSISTENCE
#define ISSI_PERSISTENCE 0
#endif
// Transfer buffer for TWITransmitData()
uint8_t g_twi_transfer_buffer[20];
// These buffers match the IS31FL3736 PWM registers.
// The control buffers match the PG0 LED On/Off registers.
// Storing them like this is optimal for I2C transfers to the registers.
// We could optimize this and take out the unused registers from these
// buffers and the transfers in IS31FL3736_write_pwm_buffer() but it's
// probably not worth the extra complexity.
uint8_t g_pwm_buffer[DRIVER_COUNT][192];
bool g_pwm_buffer_update_required = false;
uint8_t g_led_control_registers[DRIVER_COUNT][24] = { { 0 }, { 0 } };
bool g_led_control_registers_update_required = false;
void IS31FL3736_write_register( uint8_t addr, uint8_t reg, uint8_t data )
{
g_twi_transfer_buffer[0] = reg;
g_twi_transfer_buffer[1] = data;
#if ISSI_PERSISTENCE > 0
for (uint8_t i = 0; i < ISSI_PERSISTENCE; i++) {
if (i2c_transmit(addr << 1, g_twi_transfer_buffer, 2, ISSI_TIMEOUT) == 0)
break;
}
#else
i2c_transmit(addr << 1, g_twi_transfer_buffer, 2, ISSI_TIMEOUT);
#endif
}
void IS31FL3736_write_pwm_buffer( uint8_t addr, uint8_t *pwm_buffer )
{
// assumes PG1 is already selected
// transmit PWM registers in 12 transfers of 16 bytes
// g_twi_transfer_buffer[] is 20 bytes
// iterate over the pwm_buffer contents at 16 byte intervals
for ( int i = 0; i < 192; i += 16 ) {
g_twi_transfer_buffer[0] = i;
// copy the data from i to i+15
// device will auto-increment register for data after the first byte
// thus this sets registers 0x00-0x0F, 0x10-0x1F, etc. in one transfer
for ( int j = 0; j < 16; j++ ) {
g_twi_transfer_buffer[1 + j] = pwm_buffer[i + j];
}
#if ISSI_PERSISTENCE > 0
for (uint8_t i = 0; i < ISSI_PERSISTENCE; i++) {
if (i2c_transmit(addr << 1, g_twi_transfer_buffer, 17, ISSI_TIMEOUT) == 0)
break;
}
#else
i2c_transmit(addr << 1, g_twi_transfer_buffer, 17, ISSI_TIMEOUT);
#endif
}
}
void IS31FL3736_init( uint8_t addr )
{
// In order to avoid the LEDs being driven with garbage data
// in the LED driver's PWM registers, shutdown is enabled last.
// Set up the mode and other settings, clear the PWM registers,
// then disable software shutdown.
// Unlock the command register.
IS31FL3736_write_register( addr, ISSI_COMMANDREGISTER_WRITELOCK, 0xC5 );
// Select PG0
IS31FL3736_write_register( addr, ISSI_COMMANDREGISTER, ISSI_PAGE_LEDCONTROL );
// Turn off all LEDs.
for ( int i = 0x00; i <= 0x17; i++ )
{
IS31FL3736_write_register( addr, i, 0x00 );
}
// Unlock the command register.
IS31FL3736_write_register( addr, ISSI_COMMANDREGISTER_WRITELOCK, 0xC5 );
// Select PG1
IS31FL3736_write_register( addr, ISSI_COMMANDREGISTER, ISSI_PAGE_PWM );
// Set PWM on all LEDs to 0
// No need to setup Breath registers to PWM as that is the default.
for ( int i = 0x00; i <= 0xBF; i++ )
{
IS31FL3736_write_register( addr, i, 0x00 );
}
// Unlock the command register.
IS31FL3736_write_register( addr, ISSI_COMMANDREGISTER_WRITELOCK, 0xC5 );
// Select PG3
IS31FL3736_write_register( addr, ISSI_COMMANDREGISTER, ISSI_PAGE_FUNCTION );
// Set global current to maximum.
IS31FL3736_write_register( addr, ISSI_REG_GLOBALCURRENT, 0xFF );
// Disable software shutdown.
IS31FL3736_write_register( addr, ISSI_REG_CONFIGURATION, 0x01 );
// Wait 10ms to ensure the device has woken up.
#ifdef __AVR__
_delay_ms( 10 );
#else
wait_ms(10);
#endif
}
void IS31FL3736_set_color( int index, uint8_t red, uint8_t green, uint8_t blue )
{
if ( index >= 0 && index < DRIVER_LED_TOTAL ) {
is31_led led = g_is31_leds[index];
g_pwm_buffer[led.driver][led.r] = red;
g_pwm_buffer[led.driver][led.g] = green;
g_pwm_buffer[led.driver][led.b] = blue;
g_pwm_buffer_update_required = true;
}
}
void IS31FL3736_set_color_all( uint8_t red, uint8_t green, uint8_t blue )
{
for ( int i = 0; i < DRIVER_LED_TOTAL; i++ )
{
IS31FL3736_set_color( i, red, green, blue );
}
}
void IS31FL3736_set_led_control_register( uint8_t index, bool red, bool green, bool blue )
{
is31_led led = g_is31_leds[index];
// IS31FL3733
// The PWM register for a matrix position (0x00 to 0xBF) can be
// divided by 8 to get the LED control register (0x00 to 0x17),
// then mod 8 to get the bit position within that register.
// IS31FL3736
// The PWM register for a matrix position (0x00 to 0xBF) is interleaved, so:
// A1=0x00 A2=0x02 A3=0x04 A4=0x06 A5=0x08 A6=0x0A A7=0x0C A8=0x0E
// B1=0x10 B2=0x12 B3=0x14
// But also, the LED control registers (0x00 to 0x17) are also interleaved, so:
// A1-A4=0x00 A5-A8=0x01
// So, the same math applies.
uint8_t control_register_r = led.r / 8;
uint8_t control_register_g = led.g / 8;
uint8_t control_register_b = led.b / 8;
uint8_t bit_r = led.r % 8;
uint8_t bit_g = led.g % 8;
uint8_t bit_b = led.b % 8;
if ( red ) {
g_led_control_registers[led.driver][control_register_r] |= (1 << bit_r);
} else {
g_led_control_registers[led.driver][control_register_r] &= ~(1 << bit_r);
}
if ( green ) {
g_led_control_registers[led.driver][control_register_g] |= (1 << bit_g);
} else {
g_led_control_registers[led.driver][control_register_g] &= ~(1 << bit_g);
}
if ( blue ) {
g_led_control_registers[led.driver][control_register_b] |= (1 << bit_b);
} else {
g_led_control_registers[led.driver][control_register_b] &= ~(1 << bit_b);
}
g_led_control_registers_update_required = true;
}
void IS31FL3736_mono_set_brightness( int index, uint8_t value )
{
if ( index >= 0 && index < 96 ) {
// Index in range 0..95 -> A1..A8, B1..B8, etc.
// Map index 0..95 to registers 0x00..0xBE (interleaved)
uint8_t pwm_register = index * 2;
g_pwm_buffer[0][pwm_register] = value;
g_pwm_buffer_update_required = true;
}
}
void IS31FL3736_mono_set_brightness_all( uint8_t value )
{
for ( int i = 0; i < 96; i++ )
{
IS31FL3736_mono_set_brightness( i, value );
}
}
void IS31FL3736_mono_set_led_control_register( uint8_t index, bool enabled )
{
// Index in range 0..95 -> A1..A8, B1..B8, etc.
// Map index 0..95 to registers 0x00..0xBE (interleaved)
uint8_t pwm_register = index * 2;
// Map register 0x00..0xBE (interleaved) into control register and bit
uint8_t control_register = pwm_register / 8;
uint8_t bit = pwm_register % 8;
if ( enabled ) {
g_led_control_registers[0][control_register] |= (1 << bit);
} else {
g_led_control_registers[0][control_register] &= ~(1 << bit);
}
g_led_control_registers_update_required = true;
}
void IS31FL3736_update_pwm_buffers( uint8_t addr1, uint8_t addr2 )
{
if ( g_pwm_buffer_update_required )
{
// Firstly we need to unlock the command register and select PG1
IS31FL3736_write_register( addr1, ISSI_COMMANDREGISTER_WRITELOCK, 0xC5 );
IS31FL3736_write_register( addr1, ISSI_COMMANDREGISTER, ISSI_PAGE_PWM );
IS31FL3736_write_pwm_buffer( addr1, g_pwm_buffer[0] );
//IS31FL3736_write_pwm_buffer( addr2, g_pwm_buffer[1] );
}
g_pwm_buffer_update_required = false;
}
void IS31FL3736_update_led_control_registers( uint8_t addr1, uint8_t addr2 )
{
if ( g_led_control_registers_update_required )
{
// Firstly we need to unlock the command register and select PG0
IS31FL3736_write_register( addr1, ISSI_COMMANDREGISTER_WRITELOCK, 0xC5 );
IS31FL3736_write_register( addr1, ISSI_COMMANDREGISTER, ISSI_PAGE_LEDCONTROL );
for ( int i=0; i<24; i++ )
{
IS31FL3736_write_register(addr1, i, g_led_control_registers[0][i] );
//IS31FL3736_write_register(addr2, i, g_led_control_registers[1][i] );
}
}
}

172
drivers/issi/is31fl3736.h Normal file
View File

@ -0,0 +1,172 @@
/* Copyright 2018 Jason Williams (Wilba)
*
* 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>
// Simple interface option.
// If these aren't defined, just define them to make it compile
#ifndef DRIVER_COUNT
#define DRIVER_COUNT 2
#endif
#ifndef DRIVER_LED_TOTAL
#define DRIVER_LED_TOTAL 96
#endif
typedef struct is31_led {
uint8_t driver:2;
uint8_t r;
uint8_t g;
uint8_t b;
} __attribute__((packed)) is31_led;
extern const is31_led g_is31_leds[DRIVER_LED_TOTAL];
void IS31FL3736_init( uint8_t addr );
void IS31FL3736_write_register( uint8_t addr, uint8_t reg, uint8_t data );
void IS31FL3736_write_pwm_buffer( uint8_t addr, uint8_t *pwm_buffer );
void IS31FL3736_set_color( int index, uint8_t red, uint8_t green, uint8_t blue );
void IS31FL3736_set_color_all( uint8_t red, uint8_t green, uint8_t blue );
void IS31FL3736_set_led_control_register( uint8_t index, bool red, bool green, bool blue );
void IS31FL3736_mono_set_brightness( int index, uint8_t value );
void IS31FL3736_mono_set_brightness_all( uint8_t value );
void IS31FL3736_mono_set_led_control_register( uint8_t index, bool enabled );
// This should not be called from an interrupt
// (eg. from a timer interrupt).
// Call this while idle (in between matrix scans).
// If the buffer is dirty, it will update the driver with the buffer.
void IS31FL3736_update_pwm_buffers( uint8_t addr1, uint8_t addr2 );
void IS31FL3736_update_led_control_registers( uint8_t addr1, uint8_t addr2 );
#define A_1 0x00
#define A_2 0x02
#define A_3 0x04
#define A_4 0x06
#define A_5 0x08
#define A_6 0x0A
#define A_7 0x0C
#define A_8 0x0E
#define B_1 0x10
#define B_2 0x12
#define B_3 0x14
#define B_4 0x16
#define B_5 0x18
#define B_6 0x1A
#define B_7 0x1C
#define B_8 0x1E
#define C_1 0x20
#define C_2 0x22
#define C_3 0x24
#define C_4 0x26
#define C_5 0x28
#define C_6 0x2A
#define C_7 0x2C
#define C_8 0x2E
#define D_1 0x30
#define D_2 0x32
#define D_3 0x34
#define D_4 0x36
#define D_5 0x38
#define D_6 0x3A
#define D_7 0x3C
#define D_8 0x3E
#define E_1 0x40
#define E_2 0x42
#define E_3 0x44
#define E_4 0x46
#define E_5 0x48
#define E_6 0x4A
#define E_7 0x4C
#define E_8 0x4E
#define F_1 0x50
#define F_2 0x52
#define F_3 0x54
#define F_4 0x56
#define F_5 0x58
#define F_6 0x5A
#define F_7 0x5C
#define F_8 0x5E
#define G_1 0x60
#define G_2 0x62
#define G_3 0x64
#define G_4 0x66
#define G_5 0x68
#define G_6 0x6A
#define G_7 0x6C
#define G_8 0x6E
#define H_1 0x70
#define H_2 0x72
#define H_3 0x74
#define H_4 0x76
#define H_5 0x78
#define H_6 0x7A
#define H_7 0x7C
#define H_8 0x7E
#define I_1 0x80
#define I_2 0x82
#define I_3 0x84
#define I_4 0x86
#define I_5 0x88
#define I_6 0x8A
#define I_7 0x8C
#define I_8 0x8E
#define J_1 0x90
#define J_2 0x92
#define J_3 0x94
#define J_4 0x96
#define J_5 0x98
#define J_6 0x9A
#define J_7 0x9C
#define J_8 0x9E
#define K_1 0xA0
#define K_2 0xA2
#define K_3 0xA4
#define K_4 0xA6
#define K_5 0xA8
#define K_6 0xAA
#define K_7 0xAC
#define K_8 0xAE
#define L_1 0xB0
#define L_2 0xB2
#define L_3 0xB4
#define L_4 0xB6
#define L_5 0xB8
#define L_6 0xBA
#define L_7 0xBC
#define L_8 0xBE

691
drivers/qwiic/micro_oled.c Normal file
View File

@ -0,0 +1,691 @@
/* Jim Lindblom @ SparkFun Electronics
* October 26, 2014
* https://github.com/sparkfun/Micro_OLED_Breakout/tree/master/Firmware/Arduino/libraries/SFE_MicroOLED
*
* Modified by:
* Emil Varughese @ Edwin Robotics Pvt. Ltd.
* July 27, 2015
* https://github.com/emil01/SparkFun_Micro_OLED_Arduino_Library/
*
* This code was heavily based around the MicroView library, written by GeekAmmo
* (https://github.com/geekammo/MicroView-Arduino-Library).
*
* Adapted for QMK by:
* Jack Humbert <jack.humb@gmail.com>
* October 11, 2018
*
* 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 "micro_oled.h"
#include <stdlib.h>
#include "util/font5x7.h"
#include "util/font8x16.h"
#include "string.h"
#define TOTALFONTS 2
const unsigned char * fonts_pointer[]= { font5x7, font8x16 };
uint8_t foreColor,drawMode,fontWidth, fontHeight, fontType, fontStartChar, fontTotalChar, cursorX, cursorY;
uint16_t fontMapWidth;
#define _BV(x) (1 << (x))
#define swap(a, b) { uint8_t t = a; a = b; b = t; }
uint8_t micro_oled_transfer_buffer[20];
static uint8_t micro_oled_screen_current[LCDWIDTH*LCDWIDTH/8] = { 0 };
/* LCD Memory organised in 64 horizontal pixel and 6 rows of byte
B B .............B -----
y y .............y \
t t .............t \
e e .............e \
0 1 .............63 \
\
D0 D0.............D0 \
D1 D1.............D1 / ROW 0
D2 D2.............D2 /
D3 D3.............D3 /
D4 D4.............D4 /
D5 D5.............D5 /
D6 D6.............D6 /
D7 D7.............D7 ----
*/
#if LCDWIDTH == 64
#if LCDWIDTH == 48
static uint8_t micro_oled_screen_buffer[] = {
// QMK Logo - generated at http://www.majer.ch/lcd/adf_bitmap.php
//64x48 image
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0xF0, 0xF0, 0x00, 0x00, 0x00, 0xF0, 0xF0, 0x00, 0x00,
0x00, 0xF0, 0xF0, 0x00, 0x00, 0x00, 0xF0, 0xF0, 0x00, 0x00,
0x00, 0xF0, 0xF0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x60, 0x60, 0x60, 0x60,
0xF8, 0xFE, 0xFE, 0xFF, 0xFF, 0xFF, 0x1F, 0x1F, 0xFF, 0xFF,
0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x1F, 0x1F, 0xFF, 0xFF, 0xFF,
0xFF, 0xFF, 0xFF, 0xFF, 0x1F, 0x1F, 0xFF, 0xFF, 0xFF, 0xFE,
0xFE, 0xF8, 0x60, 0x60, 0x60, 0x60, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x8C, 0x8C, 0x8C, 0x8C, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
0x00, 0x00, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x00,
0x00, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x00, 0x00,
0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x8C, 0x8C, 0x8C, 0x8C,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x31, 0x31, 0x31, 0x31, 0xFF, 0xFF,
0xFF, 0xFF, 0xFF, 0xFF, 0xFC, 0xF8, 0xF1, 0xE3, 0xE7, 0xCF,
0xCF, 0xCF, 0xCF, 0x00, 0x00, 0xCF, 0xCF, 0xCF, 0xC7, 0xE7,
0xE3, 0xF1, 0xF8, 0xFC, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
0x31, 0x31, 0x31, 0x31, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x06, 0x06,
0x06, 0x06, 0x1F, 0x7F, 0x7F, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xF8, 0xF8, 0xFF,
0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
0xFF, 0x7F, 0x7F, 0x1F, 0x06, 0x06, 0x06, 0x06, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x0F, 0x0F, 0x00, 0x00, 0x00, 0x0F, 0x0F, 0x00, 0x00,
0x00, 0x0F, 0x0F, 0x00, 0x00, 0x00, 0x0F, 0x0F, 0x00, 0x00,
0x00, 0x0F, 0x0F, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00
};
#endif
#elif LCDWIDTH == 128
#if LCDHEIGHT == 32
static uint8_t micro_oled_screen_buffer[LCDWIDTH*LCDWIDTH/8] = {
//128x32 qmk image
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x80, 0xC0, 0xE0, 0xE0, 0xFC, 0xFC, 0xE0, 0xFC, 0xFC,
0xE0, 0xF0, 0xFC, 0xE0, 0xE0, 0xFC, 0xE0, 0xE0, 0xFC, 0xFC,
0xE0, 0xE0, 0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0xF0, 0x10, 0x10, 0x30, 0xE0, 0x00, 0x00,
0x80, 0x80, 0x80, 0x80, 0x80, 0x00, 0x00, 0x80, 0x00, 0x00,
0x00, 0x80, 0x00, 0x00, 0x00, 0x80, 0x00, 0x00, 0x80, 0x80,
0x00, 0x80, 0x00, 0x00, 0x00, 0x80, 0x80, 0x80, 0x00, 0x00,
0x80, 0x80, 0x00, 0x80, 0x00, 0x00, 0x00, 0x80, 0x80, 0x80,
0x80, 0xF0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x12, 0xB2, 0xB2, 0xFF,
0xFF, 0xFF, 0xFF, 0xFF, 0x01, 0x03, 0xFF, 0xFF, 0xFF, 0x03,
0x01, 0xFF, 0xFF, 0xFF, 0xFF, 0x01, 0x03, 0xFF, 0xFF, 0xFF,
0xFF, 0xB7, 0xB2, 0xB2, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x1F, 0x02, 0x02, 0x03, 0x01, 0x00, 0x06, 0x1F, 0x10,
0x10, 0x10, 0x1F, 0x06, 0x00, 0x03, 0x1E, 0x18, 0x0F, 0x01,
0x0F, 0x18, 0x1E, 0x01, 0x00, 0x0F, 0x1F, 0x12, 0x02, 0x12,
0x13, 0x00, 0x00, 0x1F, 0x00, 0x00, 0x00, 0x0E, 0x1F, 0x12,
0x02, 0x12, 0x13, 0x00, 0x00, 0x1F, 0x10, 0x10, 0x10, 0x1F,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x48, 0x4D, 0x4D, 0xFF, 0xFF, 0xFF,
0xFF, 0xFF, 0xFE, 0xF8, 0xF9, 0xF3, 0xF3, 0xC0, 0x80, 0xF3,
0xF3, 0xF3, 0xF9, 0xFC, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xED,
0x4D, 0x4D, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0xFE, 0x20, 0x10, 0x10, 0xE0, 0xC0, 0x00, 0x70, 0xC0,
0x00, 0x80, 0x70, 0x00, 0x00, 0x00, 0x00, 0x00, 0xF0, 0x0C,
0x04, 0x04, 0x04, 0x04, 0x1C, 0xF0, 0x00, 0x00, 0xFC, 0x0C,
0x38, 0xE0, 0x00, 0x00, 0xC0, 0x38, 0x0C, 0xFC, 0x00, 0x00,
0xFC, 0xFC, 0x60, 0x90, 0x0C, 0x04, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x03, 0x07, 0x07, 0x3F,
0x3F, 0x07, 0x3F, 0x3F, 0x07, 0x0F, 0x3F, 0x07, 0x07, 0x3F,
0x07, 0x07, 0x3F, 0x3F, 0x07, 0x07, 0x03, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x07,
0x06, 0x04, 0x04, 0x07, 0x01, 0x00, 0x00, 0x13, 0x1E, 0x03,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x06, 0x04, 0x04,
0x04, 0x04, 0x07, 0x0D, 0x08, 0x00, 0x07, 0x00, 0x00, 0x01,
0x07, 0x07, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x07, 0x07,
0x00, 0x01, 0x03, 0x06, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00
};
#elif LCDHEIGHT == 64
static uint8_t micro_oled_screen_buffer[LCDWIDTH*LCDWIDTH/8] = {
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xC0, 0xC0,
0x00, 0x00, 0xC0, 0xC0, 0x00, 0x00, 0xC0, 0xC0, 0x00, 0x00,
0xC0, 0xC0, 0x00, 0x00, 0xC0, 0xC0, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0xC0, 0xC0, 0xC0, 0xC0, 0xF8, 0xFC, 0xFC, 0xFE, 0xFE, 0xFF,
0x7F, 0x7E, 0xFE, 0xFF, 0xFF, 0xFE, 0xFE, 0x7F, 0x7F, 0xFE,
0xFE, 0xFF, 0xFF, 0xFE, 0x7E, 0x7F, 0xFF, 0xFE, 0xFE, 0xFC,
0xFC, 0xF8, 0xC0, 0xC0, 0xC0, 0xC0, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x88, 0x88, 0x88, 0xDD, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
0xFF, 0x00, 0x00, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x00, 0x00,
0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x00, 0x00, 0xFF, 0xFF, 0xFF,
0xFF, 0xFF, 0xFF, 0xDD, 0x88, 0x88, 0x88, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x99, 0x99, 0x99, 0x99, 0xFF, 0xFF, 0xFF, 0xFF,
0xFF, 0xFF, 0xFE, 0xF8, 0xF0, 0xF3, 0xF3, 0xE7, 0xE7, 0x00,
0x00, 0xE7, 0xE7, 0xF3, 0xF3, 0xF0, 0xF8, 0xFE, 0xFF, 0xFF,
0xFF, 0xFF, 0xFF, 0xFF, 0x99, 0x99, 0x99, 0x99, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x01, 0x01, 0x01, 0x01, 0x0F, 0x1F, 0x3F,
0x3F, 0x3F, 0xFF, 0xFF, 0x3F, 0x3F, 0xFF, 0xFF, 0x3F, 0x3F,
0xFF, 0xFF, 0x3F, 0x3F, 0xFF, 0xFF, 0x3F, 0x3F, 0xFF, 0xFF,
0x3F, 0x3F, 0x3F, 0x1F, 0x0F, 0x01, 0x01, 0x01, 0x01, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x03, 0x01, 0x00, 0x00, 0x03, 0x01, 0x00,
0x80, 0x03, 0x03, 0x00, 0x00, 0x01, 0x03, 0x00, 0x80, 0x01,
0x03, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0xFF, 0x11, 0x11, 0x11, 0x0E, 0x00, 0x70,
0x88, 0x04, 0x04, 0x04, 0xF8, 0x00, 0x00, 0x3C, 0xE0, 0xC0,
0x38, 0x1C, 0xE0, 0x80, 0x70, 0x0C, 0x00, 0xF8, 0xAC, 0x24,
0x24, 0x3C, 0x30, 0x00, 0x00, 0xFC, 0x0C, 0x04, 0x00, 0xF8,
0xAC, 0x24, 0x24, 0x2C, 0x30, 0x00, 0x70, 0xDC, 0x04, 0x04,
0x88, 0xFF, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF,
0x8C, 0x04, 0x04, 0xF8, 0x00, 0x04, 0x3C, 0xE0, 0x80, 0xF0,
0x1C, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFE, 0x83, 0x01, 0x01,
0x01, 0x81, 0xFE, 0x3C, 0x00, 0x00, 0xFF, 0x03, 0x0E, 0x70,
0xC0, 0xE0, 0x38, 0x06, 0x03, 0xFF, 0x00, 0x00, 0xFF, 0x18,
0x38, 0x66, 0xC3, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x01, 0x01, 0x01, 0x00, 0x00, 0x00, 0x00, 0x01,
0x01, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x01,
0x01, 0x01, 0x01, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00,
0x00, 0x01, 0x01, 0x01, 0x01, 0x00, 0x00, 0x00, 0x01, 0x01,
0x01, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x01, 0x01, 0x01, 0x01, 0x00, 0x00, 0x00, 0x00, 0x04, 0x03,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
0x01, 0x01, 0x01, 0x01, 0x03, 0x02, 0x00, 0x01, 0x00, 0x00,
0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x01,
0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
};
//TODO: generate bitmap of QMK logo here
#endif
#else
//catchall for custom screen szies
static uint8_t micro_oled_screen_buffer[LCDWIDTH*LCDWIDTH/8] = {0};
#endif
void micro_oled_init(void) {
i2c_init();
i2c_start(I2C_ADDRESS_SA0_1);
// Display Init sequence for 64x48 OLED module
send_command(DISPLAYOFF); // 0xAE
send_command(SETDISPLAYCLOCKDIV); // 0xD5
send_command(0x80); // the suggested ratio 0x80
send_command(SETMULTIPLEX); // 0xA8
send_command(LCDHEIGHT - 1);
send_command(SETDISPLAYOFFSET); // 0xD3
send_command(0x00); // no offset
send_command(SETSTARTLINE | 0x00); // line #0
send_command(CHARGEPUMP); // enable charge pump
send_command(0x14);
send_command(NORMALDISPLAY); // 0xA6
send_command(DISPLAYALLONRESUME); // 0xA4
//display at regular orientation
send_command(SEGREMAP | 0x1);
send_command(COMSCANDEC);
//rotate display 180
#ifdef micro_oled_rotate_180
send_command(SEGREMAP);
send_command(COMSCANINC);
#endif
send_command(MEMORYMODE);
send_command(0x10);
send_command(SETCOMPINS); // 0xDA
if (LCDHEIGHT > 32) {
send_command(0x12);
} else {
send_command(0x02);
}
send_command(SETCONTRAST); // 0x81
send_command(0x8F);
send_command(SETPRECHARGE); // 0xd9
send_command(0xF1);
send_command(SETVCOMDESELECT); // 0xDB
send_command(0x40);
send_command(DISPLAYON); //--turn on oled panel
clear_screen(); // Erase hardware memory inside the OLED controller to avoid random data in memory.
send_buffer();
}
void send_command(uint8_t command) {
micro_oled_transfer_buffer[0] = I2C_COMMAND;
micro_oled_transfer_buffer[1] = command;
i2c_transmit(I2C_ADDRESS_SA0_1 << 1, micro_oled_transfer_buffer, 2, 100);
}
void send_data(uint8_t data) {
micro_oled_transfer_buffer[0] = I2C_DATA;
micro_oled_transfer_buffer[1] = data;
i2c_transmit(I2C_ADDRESS_SA0_1 << 1, micro_oled_transfer_buffer, 2, 100);
}
/** \brief Set SSD1306 page address.
Send page address command and address to the SSD1306 OLED controller.
*/
void set_page_address(uint8_t address) {
address = (0xB0 | address);
send_command(address);
}
/** \brief Set SSD1306 column address.
Send column address command and address to the SSD1306 OLED controller.
*/
void set_column_address(uint8_t address) {
send_command( ( 0x10 | (address >> 4) ) + ((128 - LCDWIDTH) >> 8) );
send_command( 0x0F & address );
}
/** \brief Clear SSD1306's memory.
To clear GDRAM inside the LCD controller.
*/
void clear_screen(void) {
for (int i=0;i<8; i++) {
set_page_address(i);
set_column_address(0);
for (int j=0; j<0x80; j++) {
send_data(0);
}
}
}
/** \brief Clear SSD1306's memory.
To clear GDRAM inside the LCD controller.
*/
void clear_buffer(void) {
//384
memset(micro_oled_screen_buffer, 0, LCDWIDTH*LCDWIDTH/8);
}
/** \brief Invert display.
The PIXEL_ON color of the display will turn to PIXEL_OFF and the PIXEL_OFF will turn to PIXEL_ON.
*/
void invert_screen(bool invert) {
if (invert) {
send_command(INVERTDISPLAY);
} else {
send_command(NORMALDISPLAY);
}
}
/** \brief Set contrast.
OLED contract value from 0 to 255. Note: Contrast level is not very obvious.
*/
void set_contrast(uint8_t contrast) {
send_command(SETCONTRAST); // 0x81
send_command(contrast);
}
/** \brief Transfer display buffer.
Sends the updated buffer to the controller - the current status is checked before to save i2c exectution time
*/
void send_buffer(void) {
uint8_t i, j;
uint8_t page_addr = 0xFF;
for (i = 0; i < LCDHEIGHT/8; i++) {
uint8_t col_addr = 0xFF;
for (j = 0; j < LCDWIDTH; j++) {
if (micro_oled_screen_buffer[i*LCDWIDTH+j] != micro_oled_screen_current[i*LCDWIDTH+j]) {
if (page_addr != i) {
set_page_address(i);
}
if (col_addr != j) {
set_column_address(j);
}
send_data(micro_oled_screen_buffer[i*LCDWIDTH+j]);
micro_oled_screen_current[i*LCDWIDTH+j] = micro_oled_screen_buffer[i*LCDWIDTH+j];
col_addr = j + 1;
}
}
}
}
/** \brief Draw pixel with color and mode.
Draw color pixel in the screen buffer's x,y position with NORM or XOR draw mode.
*/
void draw_pixel(uint8_t x, uint8_t y, uint8_t color, uint8_t mode) {
if ((x<0) || (x>=LCDWIDTH) || (y<0) || (y>=LCDHEIGHT))
return;
if (mode == XOR) {
if (color == PIXEL_ON)
micro_oled_screen_buffer[x + (y/8)*LCDWIDTH] ^= _BV((y%8));
} else {
if (color == PIXEL_ON)
micro_oled_screen_buffer[x + (y/8)*LCDWIDTH] |= _BV((y%8));
else
micro_oled_screen_buffer[x + (y/8)*LCDWIDTH] &= ~_BV((y%8));
}
}
/** \brief Draw line with color and mode.
Draw line using color and mode from x0,y0 to x1,y1 of the screen buffer.
*/
void draw_line(uint8_t x0, uint8_t y0, uint8_t x1, uint8_t y1, uint8_t color, uint8_t mode) {
uint8_t steep = abs(y1 - y0) > abs(x1 - x0);
if (steep) {
swap(x0, y0);
swap(x1, y1);
}
if (x0 > x1) {
swap(x0, x1);
swap(y0, y1);
}
uint8_t dx, dy;
dx = x1 - x0;
dy = abs(y1 - y0);
int8_t err = dx / 2;
int8_t ystep;
if (y0 < y1) {
ystep = 1;
} else {
ystep = -1;}
for (; x0<x1; x0++) {
if (steep) {
draw_pixel(y0, x0, color, mode);
} else {
draw_pixel(x0, y0, color, mode);
}
err -= dy;
if (err < 0) {
y0 += ystep;
err += dx;
}
}
}
/** \brief Draw horizontal line with color and mode.
Draw horizontal line using color and mode from x,y to x+width,y of the screen buffer.
*/
void draw_line_hori(uint8_t x, uint8_t y, uint8_t width, uint8_t color, uint8_t mode) {
draw_line(x,y,x+width,y,color,mode);
}
/** \brief Draw vertical line.
Draw vertical line using current fore color and current draw mode from x,y to x,y+height of the screen buffer.
*/
void draw_line_vert(uint8_t x, uint8_t y, uint8_t height, bool color, uint8_t mode) {
draw_line(x,y,x,y+height,color,mode);
}
/** \brief Draw rectangle with color and mode.
Draw rectangle using color and mode from x,y to x+width,y+height of the screen buffer.
*/
void draw_rect(uint8_t x, uint8_t y, uint8_t width, uint8_t height, uint8_t color, uint8_t mode) {
uint8_t tempHeight;
draw_line_hori(x,y, width, color, mode);
draw_line_hori(x,y+height-1, width, color, mode);
tempHeight=height-2;
// skip drawing vertical lines to avoid overlapping of pixel that will
// affect XOR plot if no pixel in between horizontal lines
if (tempHeight<1) return;
draw_line_vert(x,y+1, tempHeight, color, mode);
draw_line_vert(x+width-1, y+1, tempHeight, color, mode);
}
/** \brief Draw rectangle with color and mode.
Draw rectangle using color and mode from x,y to x+width,y+height of the screen buffer.
*/
void draw_rect_soft(uint8_t x, uint8_t y, uint8_t width, uint8_t height, uint8_t color, uint8_t mode) {
uint8_t tempHeight;
draw_line_hori(x+1,y, width-2, color, mode);
draw_line_hori(x+1,y+height-1, width-2, color, mode);
tempHeight=height-2;
// skip drawing vertical lines to avoid overlapping of pixel that will
// affect XOR plot if no pixel in between horizontal lines
if (tempHeight<1) return;
draw_line_vert(x,y+1, tempHeight, color, mode);
draw_line_vert(x+width-1, y+1, tempHeight, color, mode);
}
/** \brief Draw filled rectangle with color and mode.
Draw filled rectangle using color and mode from x,y to x+width,y+height of the screen buffer.
*/
void draw_rect_filled(uint8_t x, uint8_t y, uint8_t width, uint8_t height, uint8_t color, uint8_t mode) {
// TODO - need to optimise the memory map draw so that this function will not call pixel one by one
for (int i=x; i<x+width;i++) {
draw_line_vert(i,y, height, color, mode);
}
}
/** \brief Draw filled rectangle with color and mode.
Draw filled rectangle using color and mode from x,y to x+width,y+height of the screen buffer.
*/
void draw_rect_filled_soft(uint8_t x, uint8_t y, uint8_t width, uint8_t height, uint8_t color, uint8_t mode) {
// TODO - need to optimise the memory map draw so that this function will not call pixel one by one
for (int i=x; i<x+width;i++) {
if (i == x || i == (x + width - 1))
draw_line_vert(i, y+1, height-2, color, mode);
else
draw_line_vert(i, y, height, color, mode);
}
}
/** \brief Draw character with color and mode.
Draw character c using color and draw mode at x,y.
*/
void draw_char(uint8_t x, uint8_t y, uint8_t c, uint8_t color, uint8_t mode, uint8_t font) {
// TODO - New routine to take font of any height, at the moment limited to font height in multiple of 8 pixels
uint8_t rowsToDraw,row, tempC;
uint8_t i,j,temp;
uint16_t charPerBitmapRow,charColPositionOnBitmap,charRowPositionOnBitmap,charBitmapStartPosition;
if ((font>=TOTALFONTS) || (font<0))
return;
uint8_t fontType = font;
uint8_t fontWidth = pgm_read_byte(fonts_pointer[fontType]+0);
uint8_t fontHeight = pgm_read_byte(fonts_pointer[fontType]+1);
uint8_t fontStartChar = pgm_read_byte(fonts_pointer[fontType]+2);
uint8_t fontTotalChar = pgm_read_byte(fonts_pointer[fontType]+3);
uint16_t fontMapWidth = (pgm_read_byte(fonts_pointer[fontType]+4)*100)+pgm_read_byte(fonts_pointer[fontType]+5); // two bytes values into integer 16
if ((c<fontStartChar) || (c>(fontStartChar+fontTotalChar-1))) // no bitmap for the required c
return;
tempC=c-fontStartChar;
// each row (in datasheet is call page) is 8 bits high, 16 bit high character will have 2 rows to be drawn
rowsToDraw=fontHeight/8; // 8 is LCD's page size, see SSD1306 datasheet
if (rowsToDraw<=1) rowsToDraw=1;
// the following draw function can draw anywhere on the screen, but SLOW pixel by pixel draw
if (rowsToDraw==1) {
for (i=0;i<fontWidth+1;i++) {
if (i==fontWidth) // this is done in a weird way because for 5x7 font, there is no margin, this code add a margin after col 5
temp=0;
else
temp=pgm_read_byte(fonts_pointer[fontType]+FONTHEADERSIZE+(tempC*fontWidth)+i);
for (j=0;j<8;j++) { // 8 is the LCD's page height (see datasheet for explanation)
if (temp & 0x1) {
draw_pixel(x+i, y+j, color,mode);
}
else {
draw_pixel(x+i, y+j, !color,mode);
}
temp >>=1;
}
}
return;
}
// font height over 8 bit
// take character "0" ASCII 48 as example
charPerBitmapRow = fontMapWidth/fontWidth; // 256/8 =32 char per row
charColPositionOnBitmap = tempC % charPerBitmapRow; // =16
charRowPositionOnBitmap = (int)(tempC/charPerBitmapRow); // =1
charBitmapStartPosition = (charRowPositionOnBitmap * fontMapWidth * (fontHeight/8)) + (charColPositionOnBitmap * fontWidth) ;
// each row on LCD is 8 bit height (see datasheet for explanation)
for(row=0;row<rowsToDraw;row++) {
for (i=0; i<fontWidth;i++) {
temp=pgm_read_byte(fonts_pointer[fontType]+FONTHEADERSIZE+(charBitmapStartPosition+i+(row*fontMapWidth)));
for (j=0;j<8;j++) { // 8 is the LCD's page height (see datasheet for explanation)
if (temp & 0x1) {
draw_pixel(x+i,y+j+(row*8), color, mode);
}
else {
draw_pixel(x+i,y+j+(row*8), !color, mode);
}
temp >>=1;
}
}
}
}
void draw_string(uint8_t x, uint8_t y, char * string, uint8_t color, uint8_t mode, uint8_t font) {
if ((font>=TOTALFONTS) || (font<0))
return;
uint8_t fontType = font;
uint8_t fontWidth = pgm_read_byte(fonts_pointer[fontType]+0);
uint8_t cur_x = x;
for (int i = 0; i < strlen(string); i++) {
draw_char(cur_x, y, string[i], color, mode, font);
cur_x += fontWidth + 1;
}
}

134
drivers/qwiic/micro_oled.h Normal file
View File

@ -0,0 +1,134 @@
/* Jim Lindblom @ SparkFun Electronics
* October 26, 2014
* https://github.com/sparkfun/Micro_OLED_Breakout/tree/master/Firmware/Arduino/libraries/SFE_MicroOLED
*
* Modified by:
* Emil Varughese @ Edwin Robotics Pvt. Ltd.
* July 27, 2015
* https://github.com/emil01/SparkFun_Micro_OLED_Arduino_Library/
*
* This code was heavily based around the MicroView library, written by GeekAmmo
* (https://github.com/geekammo/MicroView-Arduino-Library).
*
* Adapted for QMK by:
* Jack Humbert <jack.humb@gmail.com>
* October 11, 2018
*
* 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/>.
*/
#pragma once
#include "qwiic.h"
void micro_oled_init(void);
void send_command(uint8_t command);
void send_data(uint8_t data);
void set_page_address(uint8_t address);
void set_column_address(uint8_t address);
void clear_screen(void);
void clear_buffer(void);
void send_buffer(void);
void draw_pixel(uint8_t x, uint8_t y, uint8_t color, uint8_t mode);
void draw_line(uint8_t x0, uint8_t y0, uint8_t x1, uint8_t y1, uint8_t color, uint8_t mode);
void draw_line_hori(uint8_t x, uint8_t y, uint8_t width, uint8_t color, uint8_t mode);
void draw_line_vert(uint8_t x, uint8_t y, uint8_t height, bool color, uint8_t mode);
void draw_rect(uint8_t x, uint8_t y, uint8_t width, uint8_t height, uint8_t color, uint8_t mode);
void draw_rect_soft(uint8_t x, uint8_t y, uint8_t width, uint8_t height, uint8_t color, uint8_t mode);
void draw_rect_filled(uint8_t x, uint8_t y, uint8_t width, uint8_t height, uint8_t color, uint8_t mode);
void draw_rect_filled_soft(uint8_t x, uint8_t y, uint8_t width, uint8_t height, uint8_t color, uint8_t mode);
void draw_char(uint8_t x, uint8_t y, uint8_t c, uint8_t color, uint8_t mode, uint8_t font);
void draw_string(uint8_t x, uint8_t y, char * string, uint8_t color, uint8_t mode, uint8_t font);
#define I2C_ADDRESS_SA0_0 0b0111100
#ifndef I2C_ADDRESS_SA0_1
#define I2C_ADDRESS_SA0_1 0b0111101
#endif
#define I2C_COMMAND 0x00
#define I2C_DATA 0x40
#define PIXEL_OFF 0
#define PIXEL_ON 1
#ifndef LCDWIDTH
#define LCDWIDTH 64
#endif
#ifndef LCDWIDTH
#define LCDHEIGHT 48
#endif
#define FONTHEADERSIZE 6
#define NORM 0
#define XOR 1
#define PAGE 0
#define ALL 1
#define WIDGETSTYLE0 0
#define WIDGETSTYLE1 1
#define WIDGETSTYLE2 2
#define SETCONTRAST 0x81
#define DISPLAYALLONRESUME 0xA4
#define DISPLAYALLON 0xA5
#define NORMALDISPLAY 0xA6
#define INVERTDISPLAY 0xA7
#define DISPLAYOFF 0xAE
#define DISPLAYON 0xAF
#define SETDISPLAYOFFSET 0xD3
#define SETCOMPINS 0xDA
#define SETVCOMDESELECT 0xDB
#define SETDISPLAYCLOCKDIV 0xD5
#define SETPRECHARGE 0xD9
#define SETMULTIPLEX 0xA8
#define SETLOWCOLUMN 0x00
#define SETHIGHCOLUMN 0x10
#define SETSTARTLINE 0x40
#define MEMORYMODE 0x20
#define COMSCANINC 0xC0
#define COMSCANDEC 0xC8
#define SEGREMAP 0xA0
#define CHARGEPUMP 0x8D
#define EXTERNALVCC 0x01
#define SWITCHCAPVCC 0x02
// Scroll
#define ACTIVATESCROLL 0x2F
#define DEACTIVATESCROLL 0x2E
#define SETVERTICALSCROLLAREA 0xA3
#define RIGHTHORIZONTALSCROLL 0x26
#define LEFT_HORIZONTALSCROLL 0x27
#define VERTICALRIGHTHORIZONTALSCROLL 0x29
#define VERTICALLEFTHORIZONTALSCROLL 0x2A
typedef enum CMD {
CMD_CLEAR, //0
CMD_INVERT, //1
CMD_CONTRAST, //2
CMD_DISPLAY, //3
CMD_SETCURSOR, //4
CMD_PIXEL, //5
CMD_LINE, //6
CMD_LINEH, //7
CMD_LINEV, //8
CMD_RECT, //9
CMD_RECTFILL, //10
CMD_CIRCLE, //11
CMD_CIRCLEFILL, //12
CMD_DRAWCHAR, //13
CMD_DRAWBITMAP, //14
CMD_GETLCDWIDTH, //15
CMD_GETLCDHEIGHT, //16
CMD_SETCOLOR, //17
CMD_SETDRAWMODE //18
} commCommand_t;

31
drivers/qwiic/qwiic.c Normal file
View File

@ -0,0 +1,31 @@
/* Copyright 2018 Jack Humbert <jack.humb@gmail.com>
*
* 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 "qwiic.h"
void qwiic_init(void) {
#ifdef QWIIC_JOYSTIIC_ENABLE
joystiic_init();
#endif
#ifdef QWIIC_MICRO_OLED_ENABLE
micro_oled_init();
#endif
}
void qwiic_task(void) {
#ifdef QWIIC_JOYSTIIC_ENABLE
joystiic_task();
#endif
}

28
drivers/qwiic/qwiic.h Normal file
View File

@ -0,0 +1,28 @@
/* Copyright 2018 Jack Humbert <jack.humb@gmail.com>
*
* 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 "i2c_master.h"
#ifdef QWIIC_JOYSTIIC_ENABLE
#include "joystiic.h"
#endif
#ifdef QWIIC_MICRO_OLED_ENABLE
#include "micro_oled.h"
#endif
void qwiic_init(void);
void qwiic_task(void);

18
drivers/qwiic/qwiic.mk Normal file
View File

@ -0,0 +1,18 @@
ifneq ($(strip $(QWIIC_ENABLE)),)
COMMON_VPATH += $(DRIVER_PATH)/qwiic
OPT_DEFS += -DQWIIC_ENABLE
SRC += qwiic.c
ifeq ($(filter "i2c_master.c", $(SRC)),)
SRC += i2c_master.c
endif
endif
ifneq ($(filter JOYSTIIC, $(QWIIC_ENABLE)),)
OPT_DEFS += -DQWIIC_JOYSTIIC_ENABLE
SRC += joystiic.c
endif
ifneq ($(filter MICRO_OLED, $(QWIIC_ENABLE)),)
OPT_DEFS += -DQWIIC_MICRO_OLED_ENABLE
SRC += micro_oled.c
endif

288
drivers/qwiic/util/font5x7.h Normal file
View File

@ -0,0 +1,288 @@
/******************************************************************************
font5x7.h
Definition for small font
This file was imported from the MicroView library, written by GeekAmmo
(https://github.com/geekammo/MicroView-Arduino-Library), and released 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/>.
Modified by:
Emil Varughese @ Edwin Robotics Pvt. Ltd.
July 27, 2015
https://github.com/emil01/SparkFun_Micro_OLED_Arduino_Library/
******************************************************************************/
#pragma once
#include "progmem.h"
// Standard ASCII 5x7 font
static const unsigned char font5x7[] PROGMEM = {
// first row defines - FONTWIDTH, FONTHEIGHT, ASCII START CHAR, TOTAL CHARACTERS, FONT MAP WIDTH HIGH, FONT MAP WIDTH LOW (2,56 meaning 256)
5,8,0,255,12,75,
0x00, 0x00, 0x00, 0x00, 0x00,
0x3E, 0x5B, 0x4F, 0x5B, 0x3E,
0x3E, 0x6B, 0x4F, 0x6B, 0x3E,
0x1C, 0x3E, 0x7C, 0x3E, 0x1C,
0x18, 0x3C, 0x7E, 0x3C, 0x18,
0x1C, 0x57, 0x7D, 0x57, 0x1C,
0x1C, 0x5E, 0x7F, 0x5E, 0x1C,
0x00, 0x18, 0x3C, 0x18, 0x00,
0xFF, 0xE7, 0xC3, 0xE7, 0xFF,
0x00, 0x18, 0x24, 0x18, 0x00,
0xFF, 0xE7, 0xDB, 0xE7, 0xFF,
0x30, 0x48, 0x3A, 0x06, 0x0E,
0x26, 0x29, 0x79, 0x29, 0x26,
0x40, 0x7F, 0x05, 0x05, 0x07,
0x40, 0x7F, 0x05, 0x25, 0x3F,
0x5A, 0x3C, 0xE7, 0x3C, 0x5A,
0x7F, 0x3E, 0x1C, 0x1C, 0x08,
0x08, 0x1C, 0x1C, 0x3E, 0x7F,
0x14, 0x22, 0x7F, 0x22, 0x14,
0x5F, 0x5F, 0x00, 0x5F, 0x5F,
0x06, 0x09, 0x7F, 0x01, 0x7F,
0x00, 0x66, 0x89, 0x95, 0x6A,
0x60, 0x60, 0x60, 0x60, 0x60,
0x94, 0xA2, 0xFF, 0xA2, 0x94,
0x08, 0x04, 0x7E, 0x04, 0x08,
0x10, 0x20, 0x7E, 0x20, 0x10,
0x08, 0x08, 0x2A, 0x1C, 0x08,
0x08, 0x1C, 0x2A, 0x08, 0x08,
0x1E, 0x10, 0x10, 0x10, 0x10,
0x0C, 0x1E, 0x0C, 0x1E, 0x0C,
0x30, 0x38, 0x3E, 0x38, 0x30,
0x06, 0x0E, 0x3E, 0x0E, 0x06,
0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x5F, 0x00, 0x00,
0x00, 0x07, 0x00, 0x07, 0x00,
0x14, 0x7F, 0x14, 0x7F, 0x14,
0x24, 0x2A, 0x7F, 0x2A, 0x12,
0x23, 0x13, 0x08, 0x64, 0x62,
0x36, 0x49, 0x56, 0x20, 0x50,
0x00, 0x08, 0x07, 0x03, 0x00,
0x00, 0x1C, 0x22, 0x41, 0x00,
0x00, 0x41, 0x22, 0x1C, 0x00,
0x2A, 0x1C, 0x7F, 0x1C, 0x2A,
0x08, 0x08, 0x3E, 0x08, 0x08,
0x00, 0x80, 0x70, 0x30, 0x00,
0x08, 0x08, 0x08, 0x08, 0x08,
0x00, 0x00, 0x60, 0x60, 0x00,
0x20, 0x10, 0x08, 0x04, 0x02,
0x3E, 0x51, 0x49, 0x45, 0x3E,
0x00, 0x42, 0x7F, 0x40, 0x00,
0x72, 0x49, 0x49, 0x49, 0x46,
0x21, 0x41, 0x49, 0x4D, 0x33,
0x18, 0x14, 0x12, 0x7F, 0x10,
0x27, 0x45, 0x45, 0x45, 0x39,
0x3C, 0x4A, 0x49, 0x49, 0x31,
0x41, 0x21, 0x11, 0x09, 0x07,
0x36, 0x49, 0x49, 0x49, 0x36,
0x46, 0x49, 0x49, 0x29, 0x1E,
0x00, 0x00, 0x14, 0x00, 0x00,
0x00, 0x40, 0x34, 0x00, 0x00,
0x00, 0x08, 0x14, 0x22, 0x41,
0x14, 0x14, 0x14, 0x14, 0x14,
0x00, 0x41, 0x22, 0x14, 0x08,
0x02, 0x01, 0x59, 0x09, 0x06,
0x3E, 0x41, 0x5D, 0x59, 0x4E,
0x7C, 0x12, 0x11, 0x12, 0x7C,
0x7F, 0x49, 0x49, 0x49, 0x36,
0x3E, 0x41, 0x41, 0x41, 0x22,
0x7F, 0x41, 0x41, 0x41, 0x3E,
0x7F, 0x49, 0x49, 0x49, 0x41,
0x7F, 0x09, 0x09, 0x09, 0x01,
0x3E, 0x41, 0x41, 0x51, 0x73,
0x7F, 0x08, 0x08, 0x08, 0x7F,
0x00, 0x41, 0x7F, 0x41, 0x00,
0x20, 0x40, 0x41, 0x3F, 0x01,
0x7F, 0x08, 0x14, 0x22, 0x41,
0x7F, 0x40, 0x40, 0x40, 0x40,
0x7F, 0x02, 0x1C, 0x02, 0x7F,
0x7F, 0x04, 0x08, 0x10, 0x7F,
0x3E, 0x41, 0x41, 0x41, 0x3E,
0x7F, 0x09, 0x09, 0x09, 0x06,
0x3E, 0x41, 0x51, 0x21, 0x5E,
0x7F, 0x09, 0x19, 0x29, 0x46,
0x26, 0x49, 0x49, 0x49, 0x32,
0x03, 0x01, 0x7F, 0x01, 0x03,
0x3F, 0x40, 0x40, 0x40, 0x3F,
0x1F, 0x20, 0x40, 0x20, 0x1F,
0x3F, 0x40, 0x38, 0x40, 0x3F,
0x63, 0x14, 0x08, 0x14, 0x63,
0x03, 0x04, 0x78, 0x04, 0x03,
0x61, 0x59, 0x49, 0x4D, 0x43,
0x00, 0x7F, 0x41, 0x41, 0x41,
0x02, 0x04, 0x08, 0x10, 0x20,
0x00, 0x41, 0x41, 0x41, 0x7F,
0x04, 0x02, 0x01, 0x02, 0x04,
0x40, 0x40, 0x40, 0x40, 0x40,
0x00, 0x03, 0x07, 0x08, 0x00,
0x20, 0x54, 0x54, 0x78, 0x40,
0x7F, 0x28, 0x44, 0x44, 0x38,
0x38, 0x44, 0x44, 0x44, 0x28,
0x38, 0x44, 0x44, 0x28, 0x7F,
0x38, 0x54, 0x54, 0x54, 0x18,
0x00, 0x08, 0x7E, 0x09, 0x02,
0x18, 0xA4, 0xA4, 0x9C, 0x78,
0x7F, 0x08, 0x04, 0x04, 0x78,
0x00, 0x44, 0x7D, 0x40, 0x00,
0x20, 0x40, 0x40, 0x3D, 0x00,
0x7F, 0x10, 0x28, 0x44, 0x00,
0x00, 0x41, 0x7F, 0x40, 0x00,
0x7C, 0x04, 0x78, 0x04, 0x78,
0x7C, 0x08, 0x04, 0x04, 0x78,
0x38, 0x44, 0x44, 0x44, 0x38,
0xFC, 0x18, 0x24, 0x24, 0x18,
0x18, 0x24, 0x24, 0x18, 0xFC,
0x7C, 0x08, 0x04, 0x04, 0x08,
0x48, 0x54, 0x54, 0x54, 0x24,
0x04, 0x04, 0x3F, 0x44, 0x24,
0x3C, 0x40, 0x40, 0x20, 0x7C,
0x1C, 0x20, 0x40, 0x20, 0x1C,
0x3C, 0x40, 0x30, 0x40, 0x3C,
0x44, 0x28, 0x10, 0x28, 0x44,
0x4C, 0x90, 0x90, 0x90, 0x7C,
0x44, 0x64, 0x54, 0x4C, 0x44,
0x00, 0x08, 0x36, 0x41, 0x00,
0x00, 0x00, 0x77, 0x00, 0x00,
0x00, 0x41, 0x36, 0x08, 0x00,
0x02, 0x01, 0x02, 0x04, 0x02,
0x3C, 0x26, 0x23, 0x26, 0x3C,
0x1E, 0xA1, 0xA1, 0x61, 0x12,
0x3A, 0x40, 0x40, 0x20, 0x7A,
0x38, 0x54, 0x54, 0x55, 0x59,
0x21, 0x55, 0x55, 0x79, 0x41,
0x21, 0x54, 0x54, 0x78, 0x41,
0x21, 0x55, 0x54, 0x78, 0x40,
0x20, 0x54, 0x55, 0x79, 0x40,
0x0C, 0x1E, 0x52, 0x72, 0x12,
0x39, 0x55, 0x55, 0x55, 0x59,
0x39, 0x54, 0x54, 0x54, 0x59,
0x39, 0x55, 0x54, 0x54, 0x58,
0x00, 0x00, 0x45, 0x7C, 0x41,
0x00, 0x02, 0x45, 0x7D, 0x42,
0x00, 0x01, 0x45, 0x7C, 0x40,
0xF0, 0x29, 0x24, 0x29, 0xF0,
0xF0, 0x28, 0x25, 0x28, 0xF0,
0x7C, 0x54, 0x55, 0x45, 0x00,
0x20, 0x54, 0x54, 0x7C, 0x54,
0x7C, 0x0A, 0x09, 0x7F, 0x49,
0x32, 0x49, 0x49, 0x49, 0x32,
0x32, 0x48, 0x48, 0x48, 0x32,
0x32, 0x4A, 0x48, 0x48, 0x30,
0x3A, 0x41, 0x41, 0x21, 0x7A,
0x3A, 0x42, 0x40, 0x20, 0x78,
0x00, 0x9D, 0xA0, 0xA0, 0x7D,
0x39, 0x44, 0x44, 0x44, 0x39,
0x3D, 0x40, 0x40, 0x40, 0x3D,
0x3C, 0x24, 0xFF, 0x24, 0x24,
0x48, 0x7E, 0x49, 0x43, 0x66,
0x2B, 0x2F, 0xFC, 0x2F, 0x2B,
0xFF, 0x09, 0x29, 0xF6, 0x20,
0xC0, 0x88, 0x7E, 0x09, 0x03,
0x20, 0x54, 0x54, 0x79, 0x41,
0x00, 0x00, 0x44, 0x7D, 0x41,
0x30, 0x48, 0x48, 0x4A, 0x32,
0x38, 0x40, 0x40, 0x22, 0x7A,
0x00, 0x7A, 0x0A, 0x0A, 0x72,
0x7D, 0x0D, 0x19, 0x31, 0x7D,
0x26, 0x29, 0x29, 0x2F, 0x28,
0x26, 0x29, 0x29, 0x29, 0x26,
0x30, 0x48, 0x4D, 0x40, 0x20,
0x38, 0x08, 0x08, 0x08, 0x08,
0x08, 0x08, 0x08, 0x08, 0x38,
0x2F, 0x10, 0xC8, 0xAC, 0xBA,
0x2F, 0x10, 0x28, 0x34, 0xFA,
0x00, 0x00, 0x7B, 0x00, 0x00,
0x08, 0x14, 0x2A, 0x14, 0x22,
0x22, 0x14, 0x2A, 0x14, 0x08,
0xAA, 0x00, 0x55, 0x00, 0xAA,
0xAA, 0x55, 0xAA, 0x55, 0xAA,
0x00, 0x00, 0x00, 0xFF, 0x00,
0x10, 0x10, 0x10, 0xFF, 0x00,
0x14, 0x14, 0x14, 0xFF, 0x00,
0x10, 0x10, 0xFF, 0x00, 0xFF,
0x10, 0x10, 0xF0, 0x10, 0xF0,
0x14, 0x14, 0x14, 0xFC, 0x00,
0x14, 0x14, 0xF7, 0x00, 0xFF,
0x00, 0x00, 0xFF, 0x00, 0xFF,
0x14, 0x14, 0xF4, 0x04, 0xFC,
0x14, 0x14, 0x17, 0x10, 0x1F,
0x10, 0x10, 0x1F, 0x10, 0x1F,
0x14, 0x14, 0x14, 0x1F, 0x00,
0x10, 0x10, 0x10, 0xF0, 0x00,
0x00, 0x00, 0x00, 0x1F, 0x10,
0x10, 0x10, 0x10, 0x1F, 0x10,
0x10, 0x10, 0x10, 0xF0, 0x10,
0x00, 0x00, 0x00, 0xFF, 0x10,
0x10, 0x10, 0x10, 0x10, 0x10,
0x10, 0x10, 0x10, 0xFF, 0x10,
0x00, 0x00, 0x00, 0xFF, 0x14,
0x00, 0x00, 0xFF, 0x00, 0xFF,
0x00, 0x00, 0x1F, 0x10, 0x17,
0x00, 0x00, 0xFC, 0x04, 0xF4,
0x14, 0x14, 0x17, 0x10, 0x17,
0x14, 0x14, 0xF4, 0x04, 0xF4,
0x00, 0x00, 0xFF, 0x00, 0xF7,
0x14, 0x14, 0x14, 0x14, 0x14,
0x14, 0x14, 0xF7, 0x00, 0xF7,
0x14, 0x14, 0x14, 0x17, 0x14,
0x10, 0x10, 0x1F, 0x10, 0x1F,
0x14, 0x14, 0x14, 0xF4, 0x14,
0x10, 0x10, 0xF0, 0x10, 0xF0,
0x00, 0x00, 0x1F, 0x10, 0x1F,
0x00, 0x00, 0x00, 0x1F, 0x14,
0x00, 0x00, 0x00, 0xFC, 0x14,
0x00, 0x00, 0xF0, 0x10, 0xF0,
0x10, 0x10, 0xFF, 0x10, 0xFF,
0x14, 0x14, 0x14, 0xFF, 0x14,
0x10, 0x10, 0x10, 0x1F, 0x00,
0x00, 0x00, 0x00, 0xF0, 0x10,
0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
0xF0, 0xF0, 0xF0, 0xF0, 0xF0,
0xFF, 0xFF, 0xFF, 0x00, 0x00,
0x00, 0x00, 0x00, 0xFF, 0xFF,
0x0F, 0x0F, 0x0F, 0x0F, 0x0F,
0x38, 0x44, 0x44, 0x38, 0x44,
0x7C, 0x2A, 0x2A, 0x3E, 0x14,
0x7E, 0x02, 0x02, 0x06, 0x06,
0x02, 0x7E, 0x02, 0x7E, 0x02,
0x63, 0x55, 0x49, 0x41, 0x63,
0x38, 0x44, 0x44, 0x3C, 0x04,
0x40, 0x7E, 0x20, 0x1E, 0x20,
0x06, 0x02, 0x7E, 0x02, 0x02,
0x99, 0xA5, 0xE7, 0xA5, 0x99,
0x1C, 0x2A, 0x49, 0x2A, 0x1C,
0x4C, 0x72, 0x01, 0x72, 0x4C,
0x30, 0x4A, 0x4D, 0x4D, 0x30,
0x30, 0x48, 0x78, 0x48, 0x30,
0xBC, 0x62, 0x5A, 0x46, 0x3D,
0x3E, 0x49, 0x49, 0x49, 0x00,
0x7E, 0x01, 0x01, 0x01, 0x7E,
0x2A, 0x2A, 0x2A, 0x2A, 0x2A,
0x44, 0x44, 0x5F, 0x44, 0x44,
0x40, 0x51, 0x4A, 0x44, 0x40,
0x40, 0x44, 0x4A, 0x51, 0x40,
0x00, 0x00, 0xFF, 0x01, 0x03,
0xE0, 0x80, 0xFF, 0x00, 0x00,
0x08, 0x08, 0x6B, 0x6B, 0x08,
0x36, 0x12, 0x36, 0x24, 0x36,
0x06, 0x0F, 0x09, 0x0F, 0x06,
0x00, 0x00, 0x18, 0x18, 0x00,
0x00, 0x00, 0x10, 0x10, 0x00,
0x30, 0x40, 0xFF, 0x01, 0x01,
0x00, 0x1F, 0x01, 0x01, 0x1E,
0x00, 0x19, 0x1D, 0x17, 0x12,
0x00, 0x3C, 0x3C, 0x3C, 0x3C,
0x00, 0x00, 0x00, 0x00, 0x00
};

127
drivers/qwiic/util/font8x16.h Normal file
View File

@ -0,0 +1,127 @@
/******************************************************************************
font8x16.h
Definition for medium font
This file was imported from the MicroView library, written by GeekAmmo
(https://github.com/geekammo/MicroView-Arduino-Library), and released 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/>.
Modified by:
Emil Varughese @ Edwin Robotics Pvt. Ltd.
July 27, 2015
https://github.com/emil01/SparkFun_Micro_OLED_Arduino_Library/
******************************************************************************/
#pragma once
#include "progmem.h"
static const unsigned char font8x16[] PROGMEM = {
// first row defines - FONTWIDTH, FONTHEIGHT, ASCII START CHAR, TOTAL CHARACTERS, FONT MAP WIDTH HIGH, FONT MAP WIDTH LOW (2,56 meaning 256)
8,16,32,96,2,56,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFE, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x0E, 0x00, 0x0E, 0x00, 0x00, 0x00, 0x00, 0xD0, 0xBE, 0x90, 0xD0, 0xBE, 0x90, 0x00,
0x00, 0x1C, 0x62, 0xFF, 0xC2, 0x80, 0x00, 0x00, 0x0C, 0x12, 0x92, 0x4C, 0xB0, 0x88, 0x06, 0x00,
0x80, 0x7C, 0x62, 0xB2, 0x1C, 0xC0, 0x00, 0x00, 0x00, 0x00, 0x0E, 0x0E, 0x00, 0x00, 0x00, 0x00,
0x00, 0xE0, 0x18, 0x04, 0x02, 0x02, 0x00, 0x00, 0x00, 0x02, 0x02, 0x04, 0x18, 0xE0, 0x00, 0x00,
0x00, 0x24, 0x18, 0x7E, 0x18, 0x24, 0x00, 0x00, 0x80, 0x80, 0x80, 0xF0, 0x80, 0x80, 0x80, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x80, 0x80, 0x80, 0x80, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x80, 0x60, 0x18, 0x06, 0x00, 0x00,
0xF8, 0x04, 0xC2, 0x32, 0x0C, 0xF8, 0x00, 0x00, 0x00, 0x04, 0x04, 0xFE, 0x00, 0x00, 0x00, 0x00,
0x00, 0x02, 0x82, 0x42, 0x22, 0x1C, 0x00, 0x00, 0x00, 0x02, 0x22, 0x22, 0x22, 0xDC, 0x00, 0x00,
0xC0, 0xA0, 0x98, 0x84, 0xFE, 0x80, 0x80, 0x00, 0x00, 0x1E, 0x12, 0x12, 0x22, 0xC2, 0x00, 0x00,
0xF8, 0x44, 0x22, 0x22, 0x22, 0xC0, 0x00, 0x00, 0x00, 0x02, 0x02, 0xC2, 0x32, 0x0A, 0x06, 0x00,
0x00, 0x8C, 0x52, 0x22, 0x52, 0x8C, 0x00, 0x00, 0x3C, 0x42, 0x42, 0x42, 0x26, 0xF8, 0x00, 0x00,
0x00, 0x00, 0x30, 0x30, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x30, 0x00, 0x00, 0x00, 0x00,
0x80, 0x80, 0x40, 0x40, 0x20, 0x20, 0x10, 0x00, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x00, 0x00,
0x10, 0x20, 0x20, 0x40, 0x40, 0x80, 0x80, 0x00, 0x00, 0x02, 0x82, 0x42, 0x22, 0x1C, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00,
0x00, 0x04, 0x04, 0x0F, 0x04, 0x03, 0x00, 0x00, 0x04, 0x02, 0x01, 0x03, 0x04, 0x04, 0x03, 0x00,
0x03, 0x04, 0x04, 0x04, 0x05, 0x03, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x03, 0x06, 0x08, 0x10, 0x10, 0x00, 0x00, 0x00, 0x10, 0x10, 0x08, 0x06, 0x03, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x16, 0x0E, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x06, 0x06, 0x00, 0x00, 0x00, 0x00, 0x04, 0x02, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00,
0x01, 0x03, 0x04, 0x04, 0x02, 0x01, 0x00, 0x00, 0x00, 0x04, 0x04, 0x07, 0x04, 0x04, 0x00, 0x00,
0x00, 0x07, 0x04, 0x04, 0x04, 0x04, 0x00, 0x00, 0x00, 0x04, 0x04, 0x04, 0x04, 0x03, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00, 0x04, 0x04, 0x04, 0x04, 0x03, 0x00, 0x00,
0x01, 0x02, 0x04, 0x04, 0x04, 0x03, 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x03, 0x04, 0x04, 0x04, 0x03, 0x00, 0x00, 0x00, 0x04, 0x04, 0x04, 0x02, 0x01, 0x00, 0x00,
0x00, 0x00, 0x06, 0x06, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x16, 0x0E, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x01, 0x01, 0x02, 0x02, 0x04, 0x00, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x00, 0x00,
0x04, 0x02, 0x02, 0x01, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00, 0x00,
0xF8, 0x04, 0x72, 0x8A, 0xFA, 0x84, 0x78, 0x00, 0x00, 0xC0, 0x38, 0x06, 0x38, 0xC0, 0x00, 0x00,
0x00, 0xFE, 0x22, 0x22, 0x22, 0xDC, 0x00, 0x00, 0xF8, 0x04, 0x02, 0x02, 0x02, 0x02, 0x00, 0x00,
0xFE, 0x02, 0x02, 0x02, 0x04, 0xF8, 0x00, 0x00, 0x00, 0xFE, 0x22, 0x22, 0x22, 0x22, 0x00, 0x00,
0x00, 0xFE, 0x22, 0x22, 0x22, 0x22, 0x00, 0x00, 0xF8, 0x04, 0x02, 0x02, 0x22, 0xE2, 0x00, 0x00,
0xFE, 0x20, 0x20, 0x20, 0x20, 0xFE, 0x00, 0x00, 0x00, 0x02, 0x02, 0xFE, 0x02, 0x02, 0x00, 0x00,
0x00, 0x00, 0x00, 0x02, 0x02, 0xFE, 0x00, 0x00, 0xFE, 0x40, 0xB0, 0x08, 0x04, 0x02, 0x00, 0x00,
0x00, 0xFE, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFE, 0x0C, 0x70, 0x80, 0x70, 0x0C, 0xFE, 0x00,
0xFE, 0x0C, 0x30, 0xC0, 0x00, 0xFE, 0x00, 0x00, 0xF8, 0x04, 0x02, 0x02, 0x04, 0xF8, 0x00, 0x00,
0xFE, 0x42, 0x42, 0x42, 0x22, 0x1C, 0x00, 0x00, 0xF8, 0x04, 0x02, 0x02, 0x04, 0xF8, 0x00, 0x00,
0x00, 0xFE, 0x42, 0x42, 0xA2, 0x1C, 0x00, 0x00, 0x00, 0x1C, 0x22, 0x42, 0x42, 0x80, 0x00, 0x00,
0x02, 0x02, 0x02, 0xFE, 0x02, 0x02, 0x02, 0x00, 0xFE, 0x00, 0x00, 0x00, 0x00, 0xFE, 0x00, 0x00,
0x06, 0x38, 0xC0, 0x00, 0xC0, 0x38, 0x06, 0x00, 0x3E, 0xC0, 0xF0, 0x0E, 0xF0, 0xC0, 0x3E, 0x00,
0x00, 0x06, 0x98, 0x60, 0x98, 0x06, 0x00, 0x00, 0x00, 0x06, 0x18, 0xE0, 0x18, 0x06, 0x00, 0x00,
0x02, 0x02, 0xC2, 0x32, 0x0A, 0x06, 0x00, 0x00, 0x00, 0x00, 0xFE, 0x02, 0x02, 0x02, 0x02, 0x00,
0x00, 0x06, 0x18, 0x60, 0x80, 0x00, 0x00, 0x00, 0x02, 0x02, 0x02, 0x02, 0xFE, 0x00, 0x00, 0x00,
0x40, 0x30, 0x0C, 0x0C, 0x30, 0x40, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x01, 0x02, 0x04, 0x04, 0x04, 0x00, 0x00, 0x00, 0x06, 0x01, 0x01, 0x01, 0x01, 0x01, 0x06, 0x00,
0x00, 0x07, 0x04, 0x04, 0x04, 0x03, 0x00, 0x00, 0x01, 0x02, 0x04, 0x04, 0x04, 0x04, 0x00, 0x00,
0x07, 0x04, 0x04, 0x04, 0x02, 0x01, 0x00, 0x00, 0x00, 0x07, 0x04, 0x04, 0x04, 0x04, 0x00, 0x00,
0x00, 0x07, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x02, 0x04, 0x04, 0x04, 0x07, 0x00, 0x00,
0x07, 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x04, 0x04, 0x07, 0x04, 0x04, 0x00, 0x00,
0x00, 0x04, 0x04, 0x04, 0x04, 0x03, 0x00, 0x00, 0x07, 0x00, 0x00, 0x01, 0x02, 0x04, 0x00, 0x00,
0x00, 0x07, 0x04, 0x04, 0x04, 0x04, 0x00, 0x00, 0x07, 0x00, 0x00, 0x01, 0x00, 0x00, 0x07, 0x00,
0x07, 0x00, 0x00, 0x00, 0x03, 0x07, 0x00, 0x00, 0x01, 0x02, 0x04, 0x04, 0x02, 0x01, 0x00, 0x00,
0x07, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x02, 0x04, 0x0C, 0x12, 0x11, 0x10, 0x00,
0x00, 0x07, 0x00, 0x00, 0x01, 0x06, 0x00, 0x00, 0x00, 0x04, 0x04, 0x04, 0x04, 0x03, 0x00, 0x00,
0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00, 0x03, 0x04, 0x04, 0x04, 0x04, 0x03, 0x00, 0x00,
0x00, 0x00, 0x01, 0x06, 0x01, 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00,
0x00, 0x06, 0x01, 0x00, 0x01, 0x06, 0x00, 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
0x06, 0x05, 0x04, 0x04, 0x04, 0x04, 0x00, 0x00, 0x00, 0x00, 0x1F, 0x10, 0x10, 0x10, 0x10, 0x00,
0x00, 0x00, 0x00, 0x00, 0x01, 0x02, 0x04, 0x00, 0x10, 0x10, 0x10, 0x10, 0x1F, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x00, 0x00,
0x00, 0x00, 0x02, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00, 0xE0, 0x10, 0x10, 0x10, 0xF0, 0x00, 0x00,
0x00, 0xFE, 0x20, 0x10, 0x10, 0xE0, 0x00, 0x00, 0x00, 0xE0, 0x10, 0x10, 0x10, 0x10, 0x00, 0x00,
0x00, 0xE0, 0x10, 0x10, 0x10, 0xFE, 0x00, 0x00, 0x00, 0xE0, 0x90, 0x90, 0x90, 0xE0, 0x00, 0x00,
0x00, 0x20, 0xFC, 0x22, 0x22, 0x22, 0x02, 0x00, 0x00, 0xE0, 0x10, 0x10, 0x10, 0xF0, 0x00, 0x00,
0x00, 0xFE, 0x20, 0x10, 0x10, 0xE0, 0x00, 0x00, 0x10, 0x10, 0xF2, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x10, 0x10, 0x10, 0xF2, 0x00, 0x00, 0x00, 0x00, 0xFE, 0x80, 0x40, 0x20, 0x10, 0x00, 0x00,
0x00, 0x02, 0x02, 0xFE, 0x00, 0x00, 0x00, 0x00, 0xF0, 0x20, 0x10, 0xF0, 0x20, 0x10, 0xF0, 0x00,
0x00, 0xF0, 0x20, 0x10, 0x10, 0xE0, 0x00, 0x00, 0x00, 0xE0, 0x10, 0x10, 0x10, 0xE0, 0x00, 0x00,
0x00, 0xF0, 0x20, 0x10, 0x10, 0xE0, 0x00, 0x00, 0x00, 0xE0, 0x10, 0x10, 0x10, 0xF0, 0x00, 0x00,
0x00, 0xF0, 0x20, 0x10, 0x10, 0x70, 0x00, 0x00, 0x00, 0x60, 0x90, 0x90, 0x90, 0x20, 0x00, 0x00,
0x00, 0x20, 0x20, 0xFC, 0x20, 0x20, 0x20, 0x00, 0x00, 0xF0, 0x00, 0x00, 0x00, 0xF0, 0x00, 0x00,
0x00, 0x70, 0x80, 0x00, 0x80, 0x70, 0x00, 0x00, 0xF0, 0x00, 0xC0, 0x30, 0xC0, 0x00, 0xF0, 0x00,
0x00, 0x30, 0xC0, 0xC0, 0x30, 0x00, 0x00, 0x00, 0x00, 0x30, 0xC0, 0x00, 0x80, 0x70, 0x00, 0x00,
0x00, 0x10, 0x10, 0x90, 0x50, 0x30, 0x00, 0x00, 0x00, 0x80, 0x80, 0x7E, 0x02, 0x02, 0x00, 0x00,
0x00, 0x00, 0x00, 0xFE, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0x02, 0x7E, 0x80, 0x80, 0x00, 0x00,
0x00, 0x80, 0x80, 0x00, 0x00, 0x00, 0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03, 0x04, 0x04, 0x02, 0x07, 0x00, 0x00,
0x00, 0x07, 0x04, 0x04, 0x04, 0x03, 0x00, 0x00, 0x00, 0x03, 0x04, 0x04, 0x04, 0x04, 0x00, 0x00,
0x00, 0x03, 0x04, 0x04, 0x02, 0x07, 0x00, 0x00, 0x00, 0x03, 0x04, 0x04, 0x04, 0x04, 0x00, 0x00,
0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x33, 0x24, 0x24, 0x22, 0x1F, 0x00, 0x00,
0x00, 0x07, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00, 0x07, 0x04, 0x04, 0x00, 0x00, 0x00,
0x20, 0x20, 0x20, 0x20, 0x1F, 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x01, 0x02, 0x04, 0x00, 0x00,
0x00, 0x00, 0x00, 0x07, 0x04, 0x04, 0x00, 0x00, 0x07, 0x00, 0x00, 0x07, 0x00, 0x00, 0x07, 0x00,
0x00, 0x07, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x03, 0x04, 0x04, 0x04, 0x03, 0x00, 0x00,
0x00, 0x3F, 0x04, 0x04, 0x04, 0x03, 0x00, 0x00, 0x00, 0x03, 0x04, 0x04, 0x02, 0x3F, 0x00, 0x00,
0x00, 0x07, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0x04, 0x04, 0x04, 0x03, 0x00, 0x00,
0x00, 0x00, 0x00, 0x03, 0x04, 0x04, 0x04, 0x00, 0x00, 0x03, 0x04, 0x04, 0x02, 0x07, 0x00, 0x00,
0x00, 0x00, 0x03, 0x04, 0x03, 0x00, 0x00, 0x00, 0x01, 0x06, 0x01, 0x00, 0x01, 0x06, 0x01, 0x00,
0x00, 0x06, 0x01, 0x01, 0x06, 0x00, 0x00, 0x00, 0x20, 0x20, 0x31, 0x0E, 0x03, 0x00, 0x00, 0x00,
0x00, 0x06, 0x05, 0x04, 0x04, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00, 0x1F, 0x10, 0x10, 0x00, 0x00,
0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x10, 0x1F, 0x00, 0x00, 0x00, 0x00,
0x01, 0x00, 0x00, 0x01, 0x01, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
};

1
keyboards/1upkeyboards/1up60hse/keymaps/default/config.h
View File

@ -1,4 +1,5 @@
/* Copyright 2018 MechMerlin
* Copyright 2018 Logan Huskins
*
* 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

41
keyboards/1upkeyboards/1up60hse/keymaps/default/keymap.c
View File

@ -1,4 +1,5 @@
/* Copyright 2018 MechMerlin
* Copyright 2018 Logan Huskins
*
* 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
@ -17,28 +18,26 @@
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = LAYOUT_60_ansi(
KC_ESC, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_BSPC,
KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS,
MO(1), KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_ENT,
KC_LSFT, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_LSFT,
KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_RALT, MO(2), KC_RGUI, KC_RCTL),
KC_ESC, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_BSPC,
KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS,
KC_CAPS, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_ENT,
KC_LSFT, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RSFT,
KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_RALT, KC_RGUI, MO(1), KC_LCTL
),
[1] = LAYOUT_60_ansi(
KC_GRV, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, KC_TRNS,
KC_TRNS, KC_TRNS, KC_UP, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,
KC_TRNS, KC_LEFT, KC_DOWN, KC_RGHT, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,
KC_LSFT, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,
KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS),
[1] = LAYOUT_60_ansi(
KC_GRV, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, KC_DEL,
KC_TRNS, KC_TRNS, KC_UP, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_PSCR, KC_SLCK, KC_PAUS, KC_TRNS,
KC_TRNS, KC_LEFT, KC_DOWN, KC_RGHT, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_INS, KC_HOME, KC_PGUP, KC_TRNS,
KC_TRNS, KC_VOLU, KC_VOLD, KC_MUTE, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_END, KC_PGDN, KC_TRNS,
KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, MO(2), KC_TRNS, KC_TRNS
),
[2] = LAYOUT_60_ansi(
RESET, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,
KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,
KC_CAPS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, BL_STEP, BL_DEC, BL_INC, BL_TOGG, KC_TRNS, KC_TRNS, KC_TRNS,
KC_TRNS, KC_TRNS, KC_TRNS, RGB_VAD, RGB_VAI, RGB_SAI, RGB_HUD, RGB_HUI, RGB_MOD, RGB_TOG, KC_TRNS, KC_TRNS,
KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS),
KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, RESET,
BL_TOGG, BL_INC, BL_DEC, BL_STEP, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,
RGB_TOG, RGB_MOD, RGB_HUI, RGB_SAI, RGB_VAI, RGB_SPI, RGB_M_P, RGB_M_B, RGB_M_R, RGB_M_SW, KC_TRNS, KC_TRNS, KC_TRNS,
KC_TRNS, RGB_RMOD, RGB_HUD, RGB_SAD, RGB_VAD, RGB_SPD, RGB_M_SN, RGB_M_K, RGB_M_X, RGB_M_G, KC_TRNS, KC_TRNS,
KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS
),
};
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
return true;
}

6
keyboards/1upkeyboards/1up60hse/keymaps/default/readme.md
View File

@ -1,6 +1,4 @@
# 1up60hse default keymap
# 1up60hse default keymap generated by QMK Configurator
This is the default keymap provided by [1upkeyboards](https://www.1upkeyboards.com).
This is the keymap used by [QMK Configurator](https://config.qmk.fm/#/1upkeyboards/1up60hse/LAYOUT_60_ansi) as default.
## Notes
- Software reset key is located on `Esc` on the third layer.

4
keyboards/1upkeyboards/1up60hse/readme.md
View File

@ -10,6 +10,6 @@ Hardware Availability: [1upkeyboards.com](https://www.1upkeyboards.com/shop/cont
Make example for this keyboard (after setting up your build environment):
make 1up60hse:default
make 1upkeyboards/1up60hse:default
See [build environment setup](https://docs.qmk.fm/build_environment_setup.html) then the [make instructions](https://docs.qmk.fm/make_instructions.html) for more information.
See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs).

3
keyboards/1upkeyboards/1up60rgb/config.h
View File

@ -43,9 +43,6 @@
keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)) \
)
/* prevent stuck modifiers */
#define PREVENT_STUCK_MODIFIERS
#define RGB_DI_PIN E2
#ifdef RGB_DI_PIN
#define RGBLIGHT_ANIMATIONS

4
keyboards/1upkeyboards/1up60rgb/readme.md
View File

@ -8,6 +8,6 @@ Hardware Availability: [1upkeyboards](https://www.1upkeyboards.com/shop/controll
Make example for this keyboard (after setting up your build environment):
make 1up60rgb:default
make 1upkeyboards/1up60rgb:default
See [build environment setup](https://docs.qmk.fm/build_environment_setup.html) then the [make instructions](https://docs.qmk.fm/make_instructions.html) for more information.
See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs).

7
keyboards/1upkeyboards/sweet16/config.h
View File

@ -9,7 +9,7 @@
#define DEVICE_VER 0x0001
#define MANUFACTURER 1up Keyboards
#define PRODUCT Sweet16
#define DESCRIPTION 4x4 grid
#define DESCRIPTION 4x4 grid
/* key matrix size */
#define MATRIX_ROWS 4
@ -43,9 +43,6 @@
keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)) \
)
/* prevent stuck modifiers */
#define PREVENT_STUCK_MODIFIERS
#define RGB_DI_PIN B1
#ifdef RGB_DI_PIN
#define RGBLIGHT_ANIMATIONS
@ -55,4 +52,4 @@
#define RGBLIGHT_VAL_STEP 8
#endif
#endif
#endif

15
keyboards/1upkeyboards/sweet16/keymaps/ridingintraffic/config.h Normal file
View File

@ -0,0 +1,15 @@
#pragma once
/* tap dance stuff*/
#undef TAPPING_TERM
#define TAPPING_TERM 500
#define TAPPING_TOGGLE 2
#define EXAMPLESTRING1 "tapdance_1"
#define EXAMPLESTRING2 "tapdance_2"
#define EXAMPLESTRING3 "tapdance_3"
#define EXAMPLESTRING4 "tapdance_4"
#undef RGBLED_NUM
#define RGBLED_NUM 16

215
keyboards/1upkeyboards/sweet16/keymaps/ridingintraffic/keymap.c Normal file
View File

@ -0,0 +1,215 @@
/*
tap danc eis turned on in the rules now...
*/
#include QMK_KEYBOARD_H
#define _EMOJI 0
#define _TAPLAND 1
#define _LEDCNTL 2
enum custom_keycodes {
SHRUG,
DISFACE,
FU,
TFLIP,
TFLIP2,
SAD_EYES,
TPUT,
HAPPYFACE,
HEARTFACE,
CLOUD,
CHANFACE,
CMDCLEAR
};
//Tap Dance Declarations
enum {
TD_EXAMPLE1 = 0,
TD_EXAMPLE2,
TD_EXAMPLE3,
TD_EXAMPLE4
};
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
/* EMOJI Pad
* ,-------------------------------.
* |TFLIP | TFlIP2|DISFACE| FU |
* |------+-------+-------+--------|
* | CLOUD| | | CLEAR |
* |------+-------+-------+--------|
* |SHRUG |DISFACE| HRTFAC| HAPPYF |
* |------+-------+-------+--------|
* | ENTER| |LEDCNTR| tapland|
* `-------------------------------'
*/
//purple
[_EMOJI] = LAYOUT_ortho_4x4(
TFLIP, TFLIP2, KC_NO, FU ,
CLOUD, KC_NO, KC_NO, CMDCLEAR,
SHRUG, DISFACE, HEARTFACE, HAPPYFACE,
KC_ENT, RGB_TOG, MO(_LEDCNTL), MO(_TAPLAND)
),
/* TapLand //
* ,-------------------------------.
* | str1 | str2 | str3 | str4 |
* |------+-------+-------+--------|
* | | | | |
* |------+-------+-------+--------|
* | | | | |
* |------+-------+-------+--------|
* | | | | |
* `-------------------------------'
*/
//blue
[_TAPLAND] = LAYOUT_ortho_4x4(
TD(TD_EXAMPLE1), TD(TD_EXAMPLE2), TD(TD_EXAMPLE3), TD(TD_EXAMPLE4),
KC_NO, KC_NO, KC_NO, KC_NO,
KC_NO, KC_NO, KC_NO, KC_NO,
KC_NO, KC_NO, KC_NO, KC_NO
),
/* LEDControl Pad
* ,-------------------------------.
* | snake|breathe|rainbow|gradient|
* |------+-------+-------+--------|
* | xmas | Val+ | Sat+ | HUE+ |
* |------+-------+-------+--------|
* |kngrdr| Val- | Sat- | HUE- |
* |------+-------+-------+--------|
* | swirl| PLAIN | | ON/OFF |
* `-------------------------------'
*/
//blue
[_LEDCNTL] = LAYOUT_ortho_4x4(
RGB_M_SN, RGB_M_B, RGB_M_R, RGB_M_G,
RGB_M_X, RGB_VAI, RGB_SAI, RGB_HUI,
RGB_M_K, RGB_VAD, RGB_SAD, RGB_HUD,
RGB_M_SW, RGB_M_P, KC_NO, RGB_TOG
),
};
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
if (record->event.pressed) {
switch(keycode) {
case CLOUD: // (っ◕‿◕)っ
if(record->event.pressed){
send_unicode_hex_string("0028 3063 25D5 203F 25D5 0029 3063");
}
return false;
break;
case FU: // t(-_-t)
if(record->event.pressed){
SEND_STRING("t(-_-t)");
}
return false;
break;
case HAPPYFACE: // ʘ‿ʘ
if(record->event.pressed){
send_unicode_hex_string("0298 203F 0298");
}
return false;
break;
case CMDCLEAR:
if (record->event.pressed) {
register_code(KC_LGUI);
tap_code(KC_A);
unregister_code(KC_LGUI);
tap_code(KC_DEL);
}
return false;
break;
case SHRUG: // ¯\_(ツ)_/¯
if (record->event.pressed) {
send_unicode_hex_string("00AF 005C 005F 0028 30C4 0029 005F 002F 00AF");
}
return false;
break;
case HEARTFACE: // ♥‿♥
if(record->event.pressed){
send_unicode_hex_string("2665 203F 2665");
}
return false;
break;
case DISFACE: // ಠ_ಠ
if(record->event.pressed){
send_unicode_hex_string("0CA0 005F 0CA0");
}
return false;
break;
case TFLIP: // (╯°□°)╯ ︵ ┻━┻
if(record->event.pressed){
send_unicode_hex_string("0028 256F 00B0 25A1 00B0 0029 256F 0020 FE35 0020 253B 2501 253B");
}
return false;
break;
case TFLIP2: // ┻━┻︵ \(°□°)/ ︵ ┻━┻
if(record->event.pressed){
send_unicode_hex_string("253B 2501 253B FE35 0020 005C 0028 00B0 25A1 00B0 0029 002F 0020 FE35 0020 253B 2501 253B");
}
return false;
break;
}
}
return true;
}
/* tap dance time */
void tdexample1(qk_tap_dance_state_t *state, void *user_data) {
if (state->count >= 2) {
SEND_STRING(EXAMPLESTRING1);
reset_tap_dance (state);
}
}
void tdexample2(qk_tap_dance_state_t *state, void *user_data) {
if (state->count >= 2) {
SEND_STRING(EXAMPLESTRING2);
reset_tap_dance (state);
}
}
void tdexample3(qk_tap_dance_state_t *state, void *user_data) {
if (state->count >= 2) {
SEND_STRING(EXAMPLESTRING3);
reset_tap_dance (state);
}
}
void tdexample4(qk_tap_dance_state_t *state, void *user_data) {
if (state->count >= 2) {
SEND_STRING(EXAMPLESTRING4);
reset_tap_dance (state);
}
}
qk_tap_dance_action_t tap_dance_actions[] = {
[TD_EXAMPLE1] = ACTION_TAP_DANCE_FN(tdexample1),
[TD_EXAMPLE2] = ACTION_TAP_DANCE_FN(tdexample2),
[TD_EXAMPLE3] = ACTION_TAP_DANCE_FN(tdexample3),
[TD_EXAMPLE4] = ACTION_TAP_DANCE_FN(tdexample4)
};
// Runs just one time when the keyboard initializes.
void matrix_scan_user(void) {
static bool has_ran_yet;
if (!has_ran_yet) {
has_ran_yet = true;
rgblight_setrgb (16, 0, 16);
}
}
uint32_t layer_state_set_user(uint32_t state) {
switch (biton32(state)) {
case _TAPLAND:
rgblight_setrgb(0, 16, 0); //green
break;
case _LEDCNTL:
rgblight_setrgb(0, 0, 16); //blue
break;
case _EMOJI:
rgblight_setrgb (16, 0, 16); //purple
break;
default: // for any other layers, or the default layer
rgblight_setrgb (16, 0, 16); //purple
break;
}
return state;
}

10
keyboards/1upkeyboards/sweet16/keymaps/ridingintraffic/readme.md Normal file
View File

@ -0,0 +1,10 @@
# Ridingtraffic's examples
===
This keymap has many features:
3 layers
Momentary layer switching
16 pixel neopixel
Unicode Enabled
Tap dance enabled
The rgb also updates depending on what layer you are on, and then flips back when done.

5
keyboards/1upkeyboards/sweet16/keymaps/ridingintraffic/rules.mk Normal file
View File

@ -0,0 +1,5 @@
# turning on tap dance
TAP_DANCE_ENABLE = yes
RGBLIGHT_ENABLE = yes
MOUSEKEY_ENABLE = no
UNICODE_ENABLE = yes

4
keyboards/1upkeyboards/sweet16/readme.md
View File

@ -9,6 +9,6 @@ Hardware Availability: [1up Keyboards](https://1upkeyboards.com/)
Make example for this keyboard (after setting up your build environment):
make sweet16:default
make 1upkeyboards/sweet16:default
See [build environment setup](https://docs.qmk.fm/build_environment_setup.html) then the [make instructions](https://docs.qmk.fm/make_instructions.html) for more information.
See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs).

1
keyboards/30wer/30wer.c Normal file
View File

@ -0,0 +1 @@
#include "30wer.h"

14
keyboards/30wer/30wer.h Normal file
View File

@ -0,0 +1,14 @@
#pragma once
#include "quantum.h"
#define LAYOUT( \
k00, k01, k02, k03, k04, k05, k06, k07, k08, k09, k0a, k0b, k0c, \
k10, k11, k12, k13, k14, k15, k16, k17, k18, k19, k1a, k1b, k1c, \
k20, k21, k22, k23, k24, k25, k26, k27, k28, k29, k2a, k2b \
) \
{ \
{ k00, k01, k02, k03, k04, k05, k06, k07, k08, k09, k0a, k0b, k0c }, \
{ k10, k11, k12, k13, k14, k15, k16, k17, k18, k19, k1a, k1b, k1c }, \
{ k20, k21, k22, k23, k24, k25, k26, k27, k28, k29, k2a, k2b } \
}

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