diff options
Diffstat (limited to 'docs')
97 files changed, 4004 insertions, 1731 deletions
diff --git a/docs/_langs.md b/docs/_langs.md index 7fb4a29d33..f7b375fb94 100644 --- a/docs/_langs.md +++ b/docs/_langs.md @@ -4,5 +4,6 @@ - [:es: Español](/es/) - [:fr: Français](/fr-fr/) - [:he: עברית](/he-il/) + - [:brazil: Português](/pt-br/) - [:ru: Русский](/ru-ru/) - [:jp: 日本語](/ja/) diff --git a/docs/_summary.md b/docs/_summary.md index 808a8de4a0..de81481382 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -3,7 +3,10 @@ * [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) + * [Best Git Practices](newbs_git_best_practices.md) + * [Using Your Fork's Master](newbs_git_using_your_master_branch.md) + * [Resolving Merge Conflicts](newbs_git_resolving_merge_conflicts.md) + * [Resynchronizing a Branch](newbs_git_resynchronize_a_branch.md) * [Learning Resources](newbs_learn_more_resources.md) * [QMK Basics](README.md) @@ -98,9 +101,11 @@ * [Hand Wiring Guide](hand_wire.md) * [ISP Flashing Guide](isp_flashing_guide.md) * [ARM Debugging Guide](arm_debugging.md) + * [ADC Driver](adc_driver.md) * [I2C Driver](i2c_driver.md) * [WS2812 Driver](ws2812_driver.md) * [GPIO Controls](internals_gpio_control.md) + * [Custom Matrix](custom_matrix.md) * [Proton C Conversion](proton_c_conversion.md) * For a Deeper Understanding @@ -111,7 +116,7 @@ * [Using Eclipse with QMK](other_eclipse.md) * [Using VSCode with QMK](other_vscode.md) * [Support](support.md) - * [How to add translations](translating.md) + * [Translating the QMK Docs](translating.md) * QMK Internals (In Progress) * [Defines](internals_defines.md) diff --git a/docs/adc_driver.md b/docs/adc_driver.md new file mode 100644 index 0000000000..26e148addd --- /dev/null +++ b/docs/adc_driver.md @@ -0,0 +1,50 @@ +# ADC Driver + +QMK can leverage the Analog-to-Digital Converter (ADC) on supported MCUs to measure voltages on certain pins. This can be useful for implementing things such as battery level indicators for Bluetooth keyboards, or volume controls using a potentiometer, as opposed to a [rotary encoder](feature_encoders.md). + +This driver is currently AVR-only. The values returned are 10-bit integers (0-1023) mapped between 0V and VCC (usually 5V or 3.3V). + +## Usage + +To use this driver, add the following to your `rules.mk`: + +```make +SRC += analog.c +``` + +Then place this include at the top of your code: + +```c +#include "analog.h" +``` + +## Channels + +|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328P| +|-------|-------------|-------------|---------|----------| +|0 |`F0` |`F0` |`A0` |`C0` | +|1 |`F1` |`F1` |`A1` |`C1` | +|2 |`F2` | |`A2` |`C2` | +|3 |`F3` | |`A3` |`C3` | +|4 |`F4` |`F4` |`A4` |`C4` | +|5 |`F5` |`F5` |`A5` |`C5` | +|6 |`F6` |`F6` |`A6` |* | +|7 |`F7` |`F7` |`A7` |* | +|8 | |`D4` | | | +|9 | |`D6` | | | +|10 | |`D7` | | | +|11 | |`B4` | | | +|12 | |`B5` | | | +|13 | |`B6` | | | + +<sup>\* The ATmega328P possesses two extra ADC channels; however, they are not present on the DIP pinout, and are not shared with GPIO pins. You can use `adc_read()` directly to gain access to these.</sup> + +## Functions + +|Function |Description | +|----------------------------|-------------------------------------------------------------------------------------------------------------------| +|`analogReference(mode)` |Sets the analog voltage reference source. Must be one of `ADC_REF_EXTERNAL`, `ADC_REF_POWER` or `ADC_REF_INTERNAL`.| +|`analogRead(pin)` |Reads the value from the specified Arduino pin, eg. `4` for ADC6 on the ATmega32U4. | +|`analogReadPin(pin)` |Reads the value from the specified QMK pin, eg. `F6` for ADC6 on the ATmega32U4. | +|`pinToMux(pin)` |Translates a given QMK pin to a mux value. If an unsupported pin is given, returns the mux value for "0V (GND)". | +|`adc_read(mux)` |Reads the value from the ADC according to the specified mux. See your MCU's datasheet for more information. | diff --git a/docs/arm_debugging.md b/docs/arm_debugging.md index 448b7a8fcc..04887d88b7 100644 --- a/docs/arm_debugging.md +++ b/docs/arm_debugging.md @@ -1,4 +1,4 @@ -# ARM Debugging usign Eclipse +# ARM Debugging using 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. @@ -18,7 +18,7 @@ XPM installation instructions can be found [here](https://www.npmjs.com/package/ ### 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`. +Using XPM it is very easy to install the ARM toolchain. Enter the command `xpm install --global @xpack-dev-tools/arm-none-eabi-gcc`. ### Windows build tools @@ -33,7 +33,7 @@ If you have an ST-Link the drivers can be found [here](https://www.st.com/en/dev ### OpenOCD -This dependency allows SWD access from GDB and it is essential for debugging. Run `xpm install --global @gnu-mcu-eclipse/openocd`. +This dependency allows SWD access from GDB and it is essential for debugging. Run `xpm install --global @xpack-dev-tools/openocd`. ### Java @@ -45,17 +45,17 @@ Now its finally time to install the IDE. Use the Release page [here](https://git ## 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. +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 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 Toolchains Paths. Press xPack and OK. Repeat for OpenOCD Path and if you are on Windows for Build Tools 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. +Now its time to install the necessary MCU packages. Go to Packs perspective by selecting Window -> Perspective -> Open Perspective -> Other... -> 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++. +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 STMicroelectronics -> 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 -> Perspective -> Open Perspective -> Other... -> 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 +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. +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 @@ -71,7 +71,7 @@ NOTE: Make sure the SW |