Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
* 'master' of https://github.com/qmk/qmk_firmware: (27 commits)
  Add Portuguese keymap and sendstring lookup tables (qmk#8390)
  Update link for Learn Plover google site (qmk#8410)
  [Keymap] ninjonas keymap updates (qmk#8373)
  Fix bootloader for Maypad (qmk#8411)
  Add decorators for determining keyboard and keymap based on current directory (qmk#8191)
  format code according to conventions [skip ci]
  Fix pressing two keys with the same keycode but different modifiers (qmk#2710)
  format code according to conventions [skip ci]
  Decouple mouse cursor and mouse wheel in accelerated mode (qmk#6685)
  [Keyboard] Add Wallaby (qmk#8398)
  [Keyboard] Abacus Keyboard ReMerge (qmk#8308)
  Restore getting_started_github.md doc
  Update Swedish keymap and add sendstring LUT (qmk#8365)
  Update Spanish keymap and sendstring LUT (qmk#8364)
  use qmk.path.normpath to locate the output file.
  [Keyboard] Candybar update (qmk#8335)
  Add new keymap with split shift and split backspace for bananas… (qmk#8395)
  Enable custom backlight driver for kmac (qmk#8397)
  Force "blank" issue template to end of list (qmk#8387)
  Fix darkmode (qmk#8393)
  ...
  • Loading branch information
Shinichi-Ohki committed Mar 14, 2020
2 parents 4f559f7 + dc79792 commit 835ef5a
Show file tree
Hide file tree
Showing 123 changed files with 4,861 additions and 2,163 deletions.
File renamed without changes.
4 changes: 4 additions & 0 deletions common_features.mk
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,10 @@ else
SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
OPT_DEFS += -DEEPROM_EMU_STM32F072xB
OPT_DEFS += -DSTM32_EEPROM_ENABLE
else ifneq ($(filter $(MCU_SERIES),STM32L0xx STM32L1xx),)
OPT_DEFS += -DEEPROM_DRIVER
COMMON_VPATH += $(DRIVER_PATH)/eeprom
SRC += eeprom_driver.c eeprom_stm32_L0_L1.c
else
# This will effectively work the same as "transient" if not supported by the chip
SRC += $(PLATFORM_COMMON_DIR)/eeprom_teensy.c
Expand Down
105 changes: 104 additions & 1 deletion docs/adc_driver.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

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).
This driver currently supports both AVR and a limited selection of ARM devices. On AVR devices, the values returned are 10-bit integers (0-1023) mapped between 0V and VCC (usually 5V or 3.3V). On supported ARM devices, there is more flexibility in control of operation through `#define`s, but by default the values returned are 12-bit integers (0-4095) mapped between 0V and VCC (usually 3.3V).

## Usage

Expand All @@ -20,6 +20,8 @@ Then place this include at the top of your code:

## Channels

### AVR

|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328P|
|-------|-------------|-------------|---------|----------|
|0 |`F0` |`F0` |`A0` |`C0` |
Expand All @@ -39,12 +41,113 @@ Then place this include at the top of your code:

<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>

### ARM

Note that some of these pins are doubled-up on ADCs with the same channel. This is because the pins can be used for either ADC.

Also note that the F0 and F3 use different numbering schemes. The F0 has a single ADC and the channels are 0-based, whereas the F3 has 4 ADCs and the channels are 1 based. This is because the F0 uses the `ADCv1` implementation of the ADC, whereas the F3 uses the `ADCv3` implementation.

|ADC|Channel|STM32F0XX|STM32F3XX|
|---|-------|---------|---------|
|1 |0 |`A0` | |
|1 |1 |`A1` |`A0` |
|1 |2 |`A2` |`A1` |
|1 |3 |`A3` |`A2` |
|1 |4 |`A4` |`A3` |
|1 |5 |`A5` |`F4` |
|1 |6 |`A6` |`C0` |
|1 |7 |`A7` |`C1` |
|1 |8 |`B0` |`C2` |
|1 |9 |`B1` |`C3` |
|1 |10 |`C0` |`F2` |
|1 |11 |`C1` | |
|1 |12 |`C2` | |
|1 |13 |`C3` | |
|1 |14 |`C4` | |
|1 |15 |`C5` | |
|1 |16 | | |
|2 |1 | |`A4` |
|2 |2 | |`A5` |
|2 |3 | |`A6` |
|2 |4 | |`A7` |
|2 |5 | |`C4` |
|2 |6 | |`C0` |
|2 |7 | |`C1` |
|2 |8 | |`C2` |
|2 |9 | |`C3` |
|2 |10 | |`F2` |
|2 |11 | |`C5` |
|2 |12 | |`B2` |
|2 |13 | | |
|2 |14 | | |
|2 |15 | | |
|2 |16 | | |
|3 |1 | |`B1` |
|3 |2 | |`E9` |
|3 |3 | |`E13` |
|3 |4 | | |
|3 |5 | | |
|3 |6 | |`E8` |
|3 |7 | |`D10` |
|3 |8 | |`D11` |
|3 |9 | |`D12` |
|3 |10 | |`D13` |
|3 |11 | |`D14` |
|3 |12 | |`B0` |
|3 |13 | |`E7` |
|3 |14 | |`E10` |
|3 |15 | |`E11` |
|3 |16 | |`E12` |
|4 |1 | |`E14` |
|4 |2 | |`B12` |
|4 |3 | |`B13` |
|4 |4 | |`B14` |
|4 |5 | |`B15` |
|4 |6 | |`E8` |
|4 |7 | |`D10` |
|4 |8 | |`D11` |
|4 |9 | |`D12` |
|4 |10 | |`D13` |
|4 |11 | |`D14` |
|4 |12 | |`D8` |
|4 |13 | |`D9` |
|4 |14 | | |
|4 |15 | | |
|4 |16 | | |

## Functions

### AVR

|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. |

### ARM

Note that care was taken to match all of the functions used for AVR devices, however complications in the ARM platform prevent that from always being possible. For example, the `STM32` chips do not have assigned Arduino pins. We could use the default pin numbers, but those numbers change based on the package type of the device. For this reason, please specify your target pins with their identifiers (`A0`, `F3`, etc.). Also note that there are some variants of functions that accept the target ADC for the pin. Some pins can be used for multiple ADCs, and this specified can help you pick which ADC will be used to interact with that pin.

|Function |Description |
|----------------------------|--------------------------------------------------------------------------------------------------------------------|
|`analogReadPin(pin)` |Reads the value from the specified QMK pin, eg. `A0` for channel 0 on the STM32F0 and ADC1 channel 1 on the STM32F3. Note that if a pin can be used for multiple ADCs, it will pick the lower numbered ADC for this function. eg. `C0` will be channel 6 of ADC 1 when it could be used for ADC 2 as well.|
|`analogReadPinAdc(pin, adc)`|Reads the value from the specified QMK pin and ADC, eg. `C0, 1` will read from channel 6, ADC 2 instead of ADC 1. Note that the ADCs are 0-indexed for this function.|
|`pinToMux(pin)` |Translates a given QMK pin to a channel and ADC combination. 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 pin and adc combination. See your MCU's datasheet for more information.|

## Configuration

## ARM

The ARM implementation of the ADC has a few additional options that you can override in your own keyboards and keymaps to change how it operates.

|`#define` |Type |Default |Description|
|-------------------|------|---------------------|-----------|
|ADC_CIRCULAR_BUFFER|`bool`|`false` |If `TRUE`, then the implementation will use a circular buffer.|
|ADC_NUM_CHANNELS |`int` |`1` |Sets the number of channels that will be scanned as part of an ADC operation. The current implementation only supports `1`.|
|ADC_BUFFER_DEPTH |`int` |`2` |Sets the depth of each result. Since we are only getting a 12-bit result by default, we set this to `2` bytes so we can contain our one value. This could be set to 1 if you opt for a 8-bit or lower result.|
|ADC_SAMPLING_RATE |`int` |`ADC_SMPR_SMP_1P5` |Sets the sampling rate of the ADC. By default, it is set to the fastest setting. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.|
|ADC_RESOLUTION |`int` |`ADC_CFGR1_RES_12BIT`|The resolution of your result. We choose 12 bit by default, but you can opt for 12, 10, 8, or 6 bit. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.|
12 changes: 7 additions & 5 deletions docs/eeprom_driver.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,16 @@

The EEPROM driver can be swapped out depending on the needs of the keyboard, or whether extra hardware is present.

Driver | Description
--------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`EEPROM_DRIVER = vendor` | Uses the on-chip driver provided by the chip manufacturer. For AVR, this is provided by avr-libc. This is supported on ARM for a subset of chips -- STM32F3xx, STM32F1xx, and STM32F072xB will be emulated by writing to flash. Other chips will generally act as "transient" below.
`EEPROM_DRIVER = i2c` | Supports writing to I2C-based 24xx EEPROM chips. See the driver section below.
`EEPROM_DRIVER = transient` | Fake EEPROM driver -- supports reading/writing to RAM, and will be discarded when power is lost.
Driver | Description
-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`EEPROM_DRIVER = vendor` (default) | Uses the on-chip driver provided by the chip manufacturer. For AVR, this is provided by avr-libc. This is supported on ARM for a subset of chips -- STM32F3xx, STM32F1xx, and STM32F072xB will be emulated by writing to flash. STM32L0xx and STM32L1xx will use the onboard dedicated true EEPROM. Other chips will generally act as "transient" below.
`EEPROM_DRIVER = i2c` | Supports writing to I2C-based 24xx EEPROM chips. See the driver section below.
`EEPROM_DRIVER = transient` | Fake EEPROM driver -- supports reading/writing to RAM, and will be discarded when power is lost.

## Vendor Driver Configuration

!> Resetting EEPROM using an STM32L0/L1 device takes up to 1 second for every 1kB of internal EEPROM used.

No configurable options are available.

## I2C Driver Configuration
Expand Down
3 changes: 3 additions & 0 deletions docs/feature_mouse_keys.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,8 @@ This is the default mode. You can adjust the cursor and scrolling acceleration u
|`MOUSEKEY_INTERVAL` |50 |Time between cursor movements |
|`MOUSEKEY_MAX_SPEED` |10 |Maximum cursor speed at which acceleration stops |
|`MOUSEKEY_TIME_TO_MAX` |20 |Time until maximum cursor speed is reached |
|`MOUSEKEY_WHEEL_DELAY` |300 |Delay between pressing a wheel key and wheel movement |
|`MOUSEKEY_WHEEL_INTERVAL` |100 |Time between wheel movements |
|`MOUSEKEY_WHEEL_MAX_SPEED` |8 |Maximum number of scroll steps per scroll action |
|`MOUSEKEY_WHEEL_TIME_TO_MAX`|40 |Time until maximum scroll speed is reached |

Expand All @@ -66,6 +68,7 @@ Tips:
* Setting `MOUSEKEY_DELAY` too low makes the cursor unresponsive. Setting it too high makes small movements difficult.
* For smoother cursor movements, lower the value of `MOUSEKEY_INTERVAL`. If the refresh rate of your display is 60Hz, you could set it to `16` (1/60). As this raises the cursor speed significantly, you may want to lower `MOUSEKEY_MAX_SPEED`.
* Setting `MOUSEKEY_TIME_TO_MAX` or `MOUSEKEY_WHEEL_TIME_TO_MAX` to `0` will disable acceleration for the cursor or scrolling respectively. This way you can make one of them constant while keeping the other accelerated, which is not possible in constant speed mode.
* Setting `MOUSEKEY_WHEEL_INTERVAL` too low will make scrolling too fast. Setting it too high will make scrolling too slow when the wheel key is held down.

Cursor acceleration uses the same algorithm as the X Window System MouseKeysAccel feature. You can read more about it [on Wikipedia](https://en.wikipedia.org/wiki/Mouse_keys).

Expand Down
2 changes: 1 addition & 1 deletion docs/feature_stenography.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ On the display tab click 'Open stroke display'. With Plover disabled you should

## Learning Stenography

* [Learn Plover!](https://sites.google.com/site/ploverdoc/)
* [Learn Plover!](https://sites.google.com/site/learnplover/)
* [QWERTY Steno](http://qwertysteno.com/Home/)
* [Steno Jig](https://joshuagrams.github.io/steno-jig/)
* More resources at the Plover [Learning Stenography](https://github.com/openstenoproject/plover/wiki/Learning-Stenography) wiki
Expand Down
65 changes: 65 additions & 0 deletions docs/getting_started_github.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# How to Use Github with QMK

Github can be a little tricky to those that aren't familiar with it - this guide will walk through each step of forking, cloning, and submitting a pull request with QMK.

?> This guide assumes you're somewhat comfortable with running things at the command line, and have git installed on your system.

Start on the [QMK Github page](https://github.com/qmk/qmk_firmware), and you'll see a button in the upper right that says "Fork":

![Fork on Github](http://i.imgur.com/8Toomz4.jpg)

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)

And be sure to select "HTTPS", and select the link and copy it:

![HTTPS link](http://i.imgur.com/eGO0ohO.jpg)

From here, enter `git clone --recurse-submodules ` into the command line, and then paste your link:

```
user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git
Cloning into 'qmk_firmware'...
remote: Enumerating objects: 9, done.
remote: Counting objects: 100% (9/9), done.
remote: Compressing objects: 100% (5/5), done.
remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874
Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done.
Resolving deltas: 100% (119972/119972), done.
...
Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b'
Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
```

You now have your QMK fork on your local machine, and you can add your keymap, compile it and flash it to your board. Once you're happy with your changes, you can add, commit, and push them to your fork like this:

```
user@computer:~$ git add .
user@computer:~$ git commit -m "adding my keymap"
[master cccb1608] adding my keymap
1 file changed, 1 insertion(+)
create mode 100644 keyboards/planck/keymaps/mine/keymap.c
user@computer:~$ git push
Counting objects: 1, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (1/1), done.
Writing objects: 100% (1/1), 1.64 KiB | 0 bytes/s, done.
Total 1 (delta 1), reused 0 (delta 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local objects.
To https://github.com/whoeveryouare/qmk_firmware.git
+ 20043e64...7da94ac5 master -> master
```

Your changes now exist on your fork on Github - if you go back there (`https://github.com/<whoeveryouare>/qmk_firmware`), you can create a "New Pull Request" by clicking this button:

![New Pull Request](http://i.imgur.com/DxMHpJ8.jpg)

Here you'll be able to see exactly what you've committed - if it all looks good, you can finalize it by clicking "Create Pull Request":

![Create Pull Request](http://i.imgur.com/Ojydlaj.jpg)

After submitting, we may talk to you about your changes, ask that you make changes, and eventually accept it! Thanks for contributing to QMK :)
3 changes: 2 additions & 1 deletion docs/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/buble.css" title="light">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/dark.css" media="(prefers-color-scheme: dark)">
<link rel="stylesheet" href="//unpkg.com/docsify-toc@1.0.0/dist/toc.css">
<link rel="stylesheet" href="sidebar.css" />
<link rel="stylesheet" href="qmk_custom_light.css">
<link rel="stylesheet" href="qmk_custom_dark.css" media="(prefers-color-scheme: dark)">
</head>
<body>
<div id="app"></div>
Expand Down
29 changes: 29 additions & 0 deletions docs/qmk_custom_dark.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
.sidebar li.active {
background-color: #555;
}

.markdown-section p.tip,
.markdown-section tr:nth-child(2n) {
background-color:#444;
}

.markdown-section tr {
border-top: 1px solid #555;
}

.markdown-section td, .markdown-section th {
border: 1px solid #555;
}

.markdown-section p.tip code {
background-color: #555;
color: #fff;
}

.page_toc code {
background-color: #555;
}

.markdown-section hr, .search {
border-bottom: 1px solid #777 !important;
}
File renamed without changes.
Loading

0 comments on commit 835ef5a

Please sign in to comment.