marco/qmk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Minor updates to docs (#2406)

Browse Source 
* [docs/] Cleaning up some language to make it more clear.

* [docs/] Adding instructions for installing deps on RH / Fedora.
This commit is contained in:
Ben Hilburn 2018-02-19 14:09:05 -05:00 committed by Jack Humbert
parent 0e92d99cdc
commit 8df2ee4ec3
3 changed files with 27 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
docs/faq_build.md
View File

@ -1,40 +1,25 @@
# Frequently Asked Build Questions # Frequently Asked Build Questions
This page covers questions about building QMK. If you have not yet you should read the [Build Environment Setup](getting_started_build_tools.md) and [Make Instructions](getting_started_make_guide.md) guides. This page covers questions about building QMK. If you haven't yet done so, you should read the [Build Environment Setup](getting_started_build_tools.md) and [Make Instructions](getting_started_make_guide.md) guides.
## Can't Program on Linux ## Can't Program on Linux
You will need proper permission to operate a device. For Linux users see udev rules below. Easy way is to use `sudo` command, if you are not familiar with this command check its manual with `man sudo` or this page on line. You will need proper permissions to operate a device. For Linux users, see the instructions regarding `udev` rules, below. If you have issues with `udev`, a work-around is to use the `sudo` command. If you are not familiar with this command, check its manual with `man sudo` or [see this webpage](https://linux.die.net/man/8/sudo).
In short when your controller is ATMega32u4, An example of using `sudo`, when your controller is ATMega32u4:
$ sudo dfu-programmer atmega32u4 erase --force $ sudo dfu-programmer atmega32u4 erase --force
$ sudo dfu-programmer atmega32u4 flash your.hex $ sudo dfu-programmer atmega32u4 flash your.hex
$ sudo dfu-programmer atmega32u4 reset $ sudo dfu-programmer atmega32u4 reset
or just or just:
$ sudo make <keyboard>:<keymap>:dfu $ sudo make <keyboard>:<keymap>:dfu
But to run `make` with root privilege is not good idea. Use former method if possible. Note that running `make` with `sudo` is generally *not* a good idea, and you should use one of the former methods, if possible.
## 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).
## USB VID and PID
You can use any ID you want with editing `config.h`. Using any presumably unused ID will be no problem in fact except for very low chance of collision with other product.
Most boards in QMK use `0xFEED` as the vendor ID. You should look through other keyboards to make sure you pick a unique Product ID.
Also see this.
https://github.com/tmk/tmk_keyboard/issues/150
You can buy a really unique VID:PID here. I don't think you need this for personal use.
- 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
## Linux `udev` Rules ## Linux `udev` Rules
On Linux you need proper privilege to access device file of MCU, you'll have to use `sudo` when flashing firmware. You can circumvent this with placing these files in `/etc/udev/rules.d/`. 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/`.
**/etc/udev/rules.d/50-atmel-dfu.rules:** **/etc/udev/rules.d/50-atmel-dfu.rules:**
``` ```
@ -52,6 +37,21 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="066
SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666" SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
``` ```
## 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).
## USB VID and PID
You can use any ID you want with editing `config.h`. Using any presumably unused ID will be no problem in fact except for very low chance of collision with other product.
Most boards in QMK use `0xFEED` as the vendor ID. You should look through other keyboards to make sure you pick a unique Product ID.
Also see this.
https://github.com/tmk/tmk_keyboard/issues/150
You can buy a really unique VID:PID here. I don't think you need this for personal use.
- 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
## Cortex: `cstddef: No such file or directory` ## Cortex: `cstddef: No such file or directory`
GCC 4.8 of Ubuntu 14.04 had this problem and had to update to 4.9 with this PPA. GCC 4.8 of Ubuntu 14.04 had this problem and had to update to 4.9 with this PPA.
@ -61,7 +61,6 @@ https://github.com/tmk/tmk_keyboard/issues/212
https://github.com/tmk/tmk_keyboard/wiki/mbed-cortex-porting#compile-error-cstddef https://github.com/tmk/tmk_keyboard/wiki/mbed-cortex-porting#compile-error-cstddef
https://developer.mbed.org/forum/mbed/topic/5205/ https://developer.mbed.org/forum/mbed/topic/5205/
## `clock_prescale_set` and `clock_div_1` Not Available ## `clock_prescale_set` and `clock_div_1` Not Available
Your toolchain is too old to support the MCU. For example WinAVR 20100110 doesn't support ATMega32u2. Your toolchain is too old to support the MCU. For example WinAVR 20100110 doesn't support ATMega32u2.

5
docs/getting_started_build_tools.md
View File

@ -31,11 +31,14 @@ git
Install the dependencies with your favorite package manager. Install the dependencies with your favorite package manager.
Debian/Ubuntu example: Debian / Ubuntu example:
sudo apt-get update sudo apt-get update
sudo apt-get install gcc 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 sudo apt-get install gcc 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
Fedora / Red Hat example:
sudo dnf install gcc unzip wget zip dfu-util dfu-programmer avr-gcc avr-libc binutils-avr32-linux-gnu arm-none-eabi-gcc-cs arm-none-eabi-binutils-cs arm-none-eabi-newlib
## Nix ## Nix
If you're on [NixOS](https://nixos.org/), or have Nix installed on Linux or macOS, run `nix-shell` from the repository root to get a build environment. If you're on [NixOS](https://nixos.org/), or have Nix installed on Linux or macOS, run `nix-shell` from the repository root to get a build environment.

2
docs/keymap.md
View File

@ -33,7 +33,7 @@ The state of the Keymap layer is determined by two 32 bit parameters:
* **`default_layer_state`** indicates a base keymap layer (0-31) which is always valid and to be referred (the default layer). * **`default_layer_state`** indicates a base keymap layer (0-31) which is always valid and to be referred (the default layer).
* **`layer_state`** has current on/off status of each layer in its bits. * **`layer_state`** has current on/off status of each layer in its bits.
Keymap layer '0' is usually `default_layer`, wither other layers initially off after booting up the firmware, although this can configured differently in `config.h`. It is useful to change `default_layer` when you completely switch a key layout, for example, if you want to switch to Colemak instead of Qwerty. Keymap layer '0' is usually the `default_layer`, with other layers initially off after booting up the firmware, although this can configured differently in `config.h`. It is useful to change `default_layer` when you completely switch a key layout, for example, if you want to switch to Colemak instead of Qwerty.
Initial state of Keymap Change base layout Initial state of Keymap Change base layout
----------------------- ------------------ ----------------------- ------------------