diff --git a/docs/faq_build.md b/docs/faq_build.md index e2d0f9b27a..131844a2b7 100644 --- a/docs/faq_build.md +++ b/docs/faq_build.md @@ -13,65 +13,76 @@ An example of using `sudo`, when your controller is ATMega32u4: or just: - $ sudo make ::dfu + $ sudo make ::flash 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 -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/`. Once added run the following: -```console + +On Linux, you'll need proper privileges to communicate with the bootloader device. You can either use `sudo` when flashing firmware, or place this file in `/etc/udev/rules.d/`: + +**/etc/udev/rules.d/50-qmk.rules:** +``` +# Atmel DFU +SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="2FEF", TAG+="uaccess", RUN{builtin}+="uaccess" # ATmega16U2 +SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="2FF0", TAG+="uaccess", RUN{builtin}+="uaccess" # ATmega32U2 +SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="2FF3", TAG+="uaccess", RUN{builtin}+="uaccess" # ATmega16U4 +SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="2FF4", TAG+="uaccess", RUN{builtin}+="uaccess" # ATmega32U4 +SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="2FF9", TAG+="uaccess", RUN{builtin}+="uaccess" # AT90USB64 +SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="2FFB", TAG+="uaccess", RUN{builtin}+="uaccess" # AT90USB128 + +# Input Club +SUBSYSTEMS=="usb", ATTRS{idVendor}=="1C11", ATTRS{idProduct}=="B007", TAG+="uaccess", RUN{builtin}+="uaccess" + +# STM32duino +SUBSYSTEMS=="usb", ATTRS{idVendor}=="1EAF", ATTRS{idProduct}=="0003", TAG+="uaccess", RUN{builtin}+="uaccess" +# STM32 DFU +SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="DF11", TAG+="uaccess", RUN{builtin}+="uaccess" + +# BootloadHID +SUBSYSTEMS=="usb", ATTRS{idVendor}=="16C0", ATTRS{idProduct}=="05DF", TAG+="uaccess", RUN{builtin}+="uaccess" + +# USBAspLoader +SUBSYSTEMS=="usb", ATTRS{idVendor}=="16C0", ATTRS{idProduct}=="05DC", TAG+="uaccess", RUN{builtin}+="uaccess" + +# ModemManager should ignore the following devices +# Atmel SAM-BA (Massdrop) +SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="6124", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" + +# Caterina (Pro Micro) +# Spark Fun Electronics +SUBSYSTEMS=="usb", ATTRS{idVendor}=="1B4F", ATTRS{idProduct}=="9203", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" # Pro Micro 3V3/8MHz +SUBSYSTEMS=="usb", ATTRS{idVendor}=="1B4F", ATTRS{idProduct}=="9205", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" # Pro Micro 5V/16MHz +SUBSYSTEMS=="usb", ATTRS{idVendor}=="1B4F", ATTRS{idProduct}=="9207", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" # LilyPad 3V3/8MHz (and some Pro Micro clones) +# Pololu Electronics +SUBSYSTEMS=="usb", ATTRS{idVendor}=="1FFB", ATTRS{idProduct}=="0101", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" # A-Star 32U4 +# Arduino SA +SUBSYSTEMS=="usb", ATTRS{idVendor}=="2341", ATTRS{idProduct}=="0036", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" # Leonardo +SUBSYSTEMS=="usb", ATTRS{idVendor}=="2341", ATTRS{idProduct}=="0037", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" # Micro +# Adafruit Industries LLC +SUBSYSTEMS=="usb", ATTRS{idVendor}=="239A", ATTRS{idProduct}=="000C", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" # Feather 32U4 +SUBSYSTEMS=="usb", ATTRS{idVendor}=="239A", ATTRS{idProduct}=="000D", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" # ItsyBitsy 32U4 3V3/8MHz +SUBSYSTEMS=="usb", ATTRS{idVendor}=="239A", ATTRS{idProduct}=="000E", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" # ItsyBitsy 32U4 5V/16MHz +# dog hunter AG +SUBSYSTEMS=="usb", ATTRS{idVendor}=="2A03", ATTRS{idProduct}=="0036", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" # Leonardo +SUBSYSTEMS=="usb", ATTRS{idVendor}=="2A03", ATTRS{idProduct}=="0037", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" # Micro +``` + +Once added, run the following: + +``` sudo udevadm control --reload-rules sudo udevadm trigger ``` -**/etc/udev/rules.d/50-atmel-dfu.rules:** -``` -# Atmel ATMega32U4 -SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", TAG+="uaccess", RUN{builtin}+="uaccess" -# Atmel USBKEY AT90USB1287 -SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", TAG+="uaccess", RUN{builtin}+="uaccess" -# Atmel ATMega32U2 -SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", TAG+="uaccess", RUN{builtin}+="uaccess" -``` - -**/etc/udev/rules.d/54-input-club-keyboard.rules:** +**Note:** With older versions of ModemManager (< 1.12), filtering only works when not in strict mode. The following commands can update that setting: ``` -# Input Club keyboard bootloader -SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", ATTRS{idProduct}=="b007", TAG+="uaccess", RUN{builtin}+="uaccess" -``` - -**/etc/udev/rules.d/55-caterina.rules:** -``` -# ModemManager should ignore the following devices -SUBSYSTEMS=="usb", ATTRS{idVendor}=="2a03", ATTRS{idProduct}=="0036", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" -SUBSYSTEMS=="usb", ATTRS{idVendor}=="2341", ATTRS{idProduct}=="0036", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" -SUBSYSTEMS=="usb", ATTRS{idVendor}=="1b4f", ATTRS{idProduct}=="9205", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" -SUBSYSTEMS=="usb", ATTRS{idVendor}=="1b4f", ATTRS{idProduct}=="9203", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" -``` - -**Note:** With older (before 1.12) ModemManager, filtering only works when not in strict mode, the following commands can update that settings: -```console printf '[Service]\nExecStart=\nExecStart=/usr/sbin/ModemManager --filter-policy=default' | sudo tee /etc/systemd/system/ModemManager.service.d/policy.conf sudo systemctl daemon-reload sudo systemctl restart ModemManager ``` -**/etc/udev/rules.d/56-dfu-util.rules:** -``` -# stm32duino -SUBSYSTEMS=="usb", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0003", TAG+="uaccess", RUN{builtin}+="uaccess" -# Generic stm32 -SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", TAG+="uaccess", RUN{builtin}+="uaccess" -``` - -**/etc/udev/rules.d/57-bootloadhid.rules:** -``` -# bootloadHID -SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05df", TAG+="uaccess", RUN{builtin}+="uaccess" -``` - ### Serial device is not detected in bootloader mode on Linux Make sure your kernel has appropriate support for your device. If your device uses USB ACM, such as Pro Micro (Atmega32u4), make sure to include `CONFIG_USB_ACM=y`. Other devices may require `USB_SERIAL` and any of its sub options. @@ -96,46 +107,6 @@ You can buy a really unique VID:PID here. I don't think you need this for person - http://www.obdev.at/products/vusb/license.html - http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1 -## BOOTLOADER_SIZE for AVR -Note that Teensy2.0++ bootloader size is 2048byte. Some Makefiles may have wrong comment. - -``` -# Boot Section Size in *bytes* -# Teensy halfKay 512 -# Teensy++ halfKay 2048 -# Atmel DFU loader 4096 (TMK Alt Controller) -# LUFA bootloader 4096 -# USBaspLoader 2048 -OPT_DEFS += -DBOOTLOADER_SIZE=2048 -``` - -## `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)` on MacOS - -This is an issue with updating on brew, causing symlinks that avr-gcc depend on getting mangled. - -The solution is to remove and reinstall all affected modules. - -``` -brew rm avr-gcc avr-gcc@8 dfu-programmer dfu-util gcc-arm-none-eabi arm-gcc-bin@8 avrdude qmk -brew install qmk/qmk/qmk -brew link --force avr-gcc@8 -brew link --force arm-gcc-bin@8 -``` - -### `avr-gcc` and LUFA - -If you updated your `avr-gcc` and you see errors involving LUFA, for example: - -`lib/lufa/LUFA/Drivers/USB/Class/Device/AudioClassDevice.h:380:5: error: 'const' attribute on function returning 'void'` - -For now, you need to rollback `avr-gcc` to 8 in Homebrew. - -``` -brew uninstall --force avr-gcc -brew install avr-gcc@8 -brew link --force avr-gcc@8 -``` - ### I just flashed my keyboard and it does nothing/keypresses don't register - it's also ARM (rev6 planck, clueboard 60, hs60v2, etc...) (Feb 2019) Due to how EEPROM works on ARM based chips, saved settings may no longer be valid. This affects the default layers, and *may*, under certain circumstances we are still figuring out, make the keyboard unusable. Resetting the EEPROM will correct this. diff --git a/docs/faq_debug.md b/docs/faq_debug.md index 08c84fe4fd..7d5473678b 100644 --- a/docs/faq_debug.md +++ b/docs/faq_debug.md @@ -31,20 +31,6 @@ Check: - try using 'print' function instead of debug print. See **common/print.h**. - disconnect other devices with console function. See [Issue #97](https://github.com/tmk/tmk_keyboard/issues/97). -## Linux or UNIX Like System Requires Super User Privilege -Just use 'sudo' to execute *hid_listen* with privilege. -``` -$ sudo hid_listen -``` - -Or add an *udev rule* for TMK devices with placing a file in rules directory. The directory may vary on each system. - -File: /etc/udev/rules.d/52-tmk-keyboard.rules(in case of Ubuntu) -``` -# tmk keyboard products https://github.com/tmk/tmk_keyboard -SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666" -``` - *** # Miscellaneous diff --git a/lib/python/qmk/cli/doctor.py b/lib/python/qmk/cli/doctor.py index 920615396e..bad864f72d 100755 --- a/lib/python/qmk/cli/doctor.py +++ b/lib/python/qmk/cli/doctor.py @@ -150,25 +150,58 @@ def check_udev_rules(): ok = True udev_dir = Path("/etc/udev/rules.d/") desired_rules = { - 'dfu': {_udev_rule("03eb", "2ff4"), _udev_rule("03eb", "2ffb"), _udev_rule("03eb", "2ff0")}, - 'input_club': {_udev_rule("1c11", "b007")}, - 'stm32': {_udev_rule("1eaf", "0003"), _udev_rule("0483", "df11")}, - 'bootloadhid': {_udev_rule("16c0", "05df")}, + 'atmel-dfu': { + _udev_rule("03EB", "2FEF"), # ATmega16U2 + _udev_rule("03EB", "2FF0"), # ATmega32U2 + _udev_rule("03EB", "2FF3"), # ATmega16U4 + _udev_rule("03EB", "2FF4"), # ATmega32U4 + _udev_rule("03EB", "2FF9"), # AT90USB64 + _udev_rule("03EB", "2FFB") # AT90USB128 + }, + 'kiibohd': { + _udev_rule("1C11", "B007") + }, + 'stm32': { + _udev_rule("1EAF", "0003"), # STM32duino + _udev_rule("0483", "DF11") # STM32 DFU + }, + 'bootloadhid': { + _udev_rule("16C0", "05DF") + }, + 'usbasploader': { + _udev_rule("16C0", "05DC") + }, + 'massdrop': { + _udev_rule("03EB", "6124") + }, 'caterina': { - _udev_rule("2341", "0036", 'ENV{ID_MM_DEVICE_IGNORE}="1"'), - _udev_rule("1b4f", "9205", 'ENV{ID_MM_DEVICE_IGNORE}="1"'), - _udev_rule("1b4f", "9203", 'ENV{ID_MM_DEVICE_IGNORE}="1"'), - _udev_rule("2a03", "0036", 'ENV{ID_MM_DEVICE_IGNORE}="1"') + # Spark Fun Electronics + _udev_rule("1B4F", "9203", 'ENV{ID_MM_DEVICE_IGNORE}="1"'), # Pro Micro 3V3/8MHz + _udev_rule("1B4F", "9205", 'ENV{ID_MM_DEVICE_IGNORE}="1"'), # Pro Micro 5V/16MHz + _udev_rule("1B4F", "9207", 'ENV{ID_MM_DEVICE_IGNORE}="1"'), # LilyPad 3V3/8MHz (and some Pro Micro clones) + # Pololu Electronics + _udev_rule("1FFB", "0101", 'ENV{ID_MM_DEVICE_IGNORE}="1"'), # A-Star 32U4 + # Arduino SA + _udev_rule("2341", "0036", 'ENV{ID_MM_DEVICE_IGNORE}="1"'), # Leonardo + _udev_rule("2341", "0037", 'ENV{ID_MM_DEVICE_IGNORE}="1"'), # Micro + # Adafruit Industries LLC + _udev_rule("239A", "000C", 'ENV{ID_MM_DEVICE_IGNORE}="1"'), # Feather 32U4 + _udev_rule("239A", "000D", 'ENV{ID_MM_DEVICE_IGNORE}="1"'), # ItsyBitsy 32U4 3V3/8MHz + _udev_rule("239A", "000E", 'ENV{ID_MM_DEVICE_IGNORE}="1"'), # ItsyBitsy 32U4 5V/16MHz + # dog hunter AG + _udev_rule("2A03", "0036", 'ENV{ID_MM_DEVICE_IGNORE}="1"'), # Leonardo + _udev_rule("2A03", "0037", 'ENV{ID_MM_DEVICE_IGNORE}="1"') # Micro } } # These rules are no longer recommended, only use them to check for their presence. deprecated_rules = { - 'dfu': {_deprecated_udev_rule("03eb", "2ff4"), _deprecated_udev_rule("03eb", "2ffb"), _deprecated_udev_rule("03eb", "2ff0")}, - 'input_club': {_deprecated_udev_rule("1c11")}, + 'atmel-dfu': {_deprecated_udev_rule("03eb", "2ff4"), _deprecated_udev_rule("03eb", "2ffb"), _deprecated_udev_rule("03eb", "2ff0")}, + 'kiibohd': {_deprecated_udev_rule("1c11")}, 'stm32': {_deprecated_udev_rule("1eaf", "0003"), _deprecated_udev_rule("0483", "df11")}, 'bootloadhid': {_deprecated_udev_rule("16c0", "05df")}, - 'caterina': {'ATTRS{idVendor}=="2a03", ENV{ID_MM_DEVICE_IGNORE}="1"', 'ATTRS{idVendor}=="2341", ENV{ID_MM_DEVICE_IGNORE}="1"'} + 'caterina': {'ATTRS{idVendor}=="2a03", ENV{ID_MM_DEVICE_IGNORE}="1"', 'ATTRS{idVendor}=="2341", ENV{ID_MM_DEVICE_IGNORE}="1"'}, + 'tmk': {_deprecated_udev_rule("feed")} } if udev_dir.exists(): @@ -194,7 +227,7 @@ def check_udev_rules(): if deprecated_rule and deprecated_rule.issubset(current_rules): cli.log.warn("{bg_yellow}Found old, deprecated udev rules for '%s' boards. The new rules on https://docs.qmk.fm/#/faq_build?id=linux-udev-rules offer better security with the same functionality.", bootloader) else: - cli.log.warn("{bg_yellow}Missing udev rules for '%s' boards. You'll need to use `sudo` in order to flash them.", bootloader) + cli.log.warn("{bg_yellow}Missing udev rules for '%s' boards. See https://docs.qmk.fm/#/faq_build?id=linux-udev-rules for more details.", bootloader) return ok