diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_summary.md | 1 | ||||
| -rw-r--r-- | docs/config_options.md | 7 | ||||
| -rw-r--r-- | docs/feature_hd44780.md | 6 | ||||
| -rw-r--r-- | docs/feature_rawhid.md | 65 | ||||
| -rw-r--r-- | docs/feature_rgb_matrix.md | 16 | ||||
| -rw-r--r-- | docs/feature_rgblight.md | 70 | ||||
| -rw-r--r-- | docs/feature_swap_hands.md | 1 | ||||
| -rw-r--r-- | docs/index.html | 3 | ||||
| -rw-r--r-- | docs/internals_gpio_control.md | 1 | ||||
| -rw-r--r-- | docs/isp_flashing_guide.md | 18 | ||||
| -rw-r--r-- | docs/ja/feature_haptic_feedback.md | 163 | ||||
| -rw-r--r-- | docs/ja/feature_hd44780.md | 2 | ||||
| -rw-r--r-- | docs/ja/feature_key_lock.md | 27 | ||||
| -rw-r--r-- | docs/keycodes.md | 1 | ||||
| -rw-r--r-- | docs/keymap.md | 20 | ||||
| -rw-r--r-- | docs/spi_driver.md | 19 | ||||
| -rw-r--r-- | docs/unit_testing.md | 2 |
17 files changed, 388 insertions, 34 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index 842422665e..75b9a83e66 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -75,6 +75,7 @@ * [Layers](feature_layers.md) * [One Shot Keys](one_shot_keys.md) * [Pointing Device](feature_pointing_device.md) + * [Raw HID](feature_rawhid.md) * [Swap Hands](feature_swap_hands.md) * [Tap Dance](feature_tap_dance.md) * [Tap-Hold Configuration](tap_hold.md) diff --git a/docs/config_options.md b/docs/config_options.md index 16fea83a33..b96079e605 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -191,7 +191,12 @@ If you define these options you will enable the associated feature, which may in * `#define RGBLIGHT_ANIMATIONS` * run RGB animations * `#define RGBLIGHT_LAYERS` - * Lets you define [lighting layers](feature_rgblight.md) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state. + * Lets you define [lighting layers](feature_rgblight.md?id=lighting-layers) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state. +* `#define RGBLIGHT_MAX_LAYERS` + * Defaults to 8. Can be expanded up to 32 if more [lighting layers](feature_rgblight.md?id=lighting-layers) are needed. + * Note: Increasing the maximum will increase the firmware size and slow sync on split keyboards. +* `#define RGBLIGHT_LAYER_BLINK` + * Adds ability to [blink](feature_rgblight.md?id=lighting-layer-blink) a lighting layer for a specified number of milliseconds (e.g. to acknowledge an action). * `#define RGBLED_NUM 12` * number of LEDs * `#define RGBLIGHT_SPLIT` diff --git a/docs/feature_hd44780.md b/docs/feature_hd44780.md index 0a174035be..dc476c734f 100644 --- a/docs/feature_hd44780.md +++ b/docs/feature_hd44780.md @@ -1,6 +1,6 @@ # HD44780 LCD Displays -This is an integration of Peter Fleury's LCD library. This page will explain the basics. [For in depth documentation visit his page.](http://homepage.hispeed.ch/peterfleury/doxygen/avr-gcc-libraries/group__pfleury__lcd.html) +This is an integration of Peter Fleury's LCD library. This page will explain the basics. [For in depth documentation visit his page.](http://www.peterfleury.epizy.com/doxygen/avr-gcc-libraries/group__pfleury__lcd.html) You can enable support for HD44780 Displays by setting the `HD44780_ENABLE` flag in your keyboards `rules.mk` to yes. @@ -50,8 +50,8 @@ LCD_DISP_ON_CURSOR_BLINK : display on, cursor on flashing ```` This is best done in your keyboards `matrix_init_kb` or your keymaps `matrix_init_user`. It is advised to clear the display before use. -To do so call `lcd_clrsrc()`. +To do so call `lcd_clrscr()`. To now print something to your Display you first call `lcd_gotoxy(column, line)`. To go to the start of the first line you would call `lcd_gotoxy(0, 0)` and then print a string with `lcd_puts("example string")`. -There are more methods available to control the display. [For in depth documentation please visit the linked page.](http://homepage.hispeed.ch/peterfleury/doxygen/avr-gcc-libraries/group__pfleury__lcd.html) +There are more methods available to control the display. [For in depth documentation please visit the linked page.](http://www.peterfleury.epizy.com/doxygen/avr-gcc-libraries/group__pfleury__lcd.html) diff --git a/docs/feature_rawhid.md b/docs/feature_rawhid.md new file mode 100644 index 0000000000..ed848a4c79 --- /dev/null +++ b/docs/feature_rawhid.md @@ -0,0 +1,65 @@ +# Raw HID + +Raw HID allows for bidirectional communication between QMK and the host computer over an HID interface. This has many potential use cases, such as switching keymaps on the fly or changing RGB LED colors and modes. + +There are two main components to getting raw HID working with your keyboard. + +## Keyboard firmware + +The implementation is fairly straightforward for the firmware. +In your `rules.mk` add: + +```make +RAW_ENABLE = yes +``` + +In your `keymap.c` include `"raw_hid.h"` and implement the following: + +```C +void raw_hid_receive(uint8_t *data, uint8_t length) { + // Your code goes here. data is the packet received from host. +} +``` + +The `"raw_hid.h"` header also declares `void raw_hid_send(uint8_t *data, uint8_t length);` which allows sending packets from keyboard to host. As an example, it can also be used for debugging when building your host application by returning all data back to the host. + +```C +void raw_hid_receive(uint8_t *data, uint8_t length) { + raw_hid_send(data, length); +} +``` + +`raw_hid_receive` can receive variable size packets from host with maximum length `RAW_EPSIZE`. `raw_hid_send` on the other hand can send packets to host of exactly `RAW_EPSIZE` length, therefore it should be used with data of length `RAW_EPSIZE`. + +Make sure to flash raw enabled firmware before proceeding with working on the host side. + +## Host (Windows/macOS/Linux) + +This is the more complicated part as it will require some digging. + +To connect your host computer to your keyboard with raw HID you need four pieces of information about your keyboard: + +1. Vendor ID +2. Product ID +3. Usage Page +4. Usage + +The first two can easily be found in your keyboard's `config.h` in the keyboard's main directory under `VENDOR_ID` and `PRODUCT_ID`. **Usage Page** is **`0xFF60`** and **Usage** is **`0x0061`**. + +### Building your host + +You can build your host using any language that has an available HID implementation library if you don't wish to make your own. The ones we know of for popular languages are: + +* Node: [node-hid](https://github.com/node-hid/node-hid). +* C: [hidapi](https://github.com/libusb/hidapi). +* Java: [purejavahidapi](https://github.com/nyholku/purejavahidapi) and [hid4java](https://github.com/gary-rowe/hid4java). +* Python: [pyhidapi](https://pypi.org/project/hid/). + +This is not an exhaustive cross-platform list but should get you started. There are no special requirements for using raw HID so any HID library should work. + +Now that you have all four pieces of information required to open HID interface to your keyboard. All you need to do is use your library's available functions to open the device with its ID parameters. + +Note that Vendor ID and Product ID are not actually required to open the device. They are used only to filter to a specific device out of the many HID devices you have plugged in. Many libraries will give you the option to open the device using Product Name or Manufacturer Name instead, `node-hid` being a prime example. This will create issues for devices with builtin USB Hub or any extra HID interfaces where you will have multiple interfaces with the same name or from the same manufacturer. The Vendor ID together with Product ID create a unique designation to a single interface and will not exhibit this problem. Therefore, even if your library doesn't require you to, it is best to use them to avoid issues. +Unlike Vendor ID and Product ID though, Usage Page and Usage are necessary for successful communication. + +It should go without saying that regardless of the library you're using, you should always make sure to close the interface when finished. Depending on the operating system and your particular environment there may be issues connecting to it again afterwards with another client or another instance of the same client if it's not explicitly closed. diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 2cec55ee77..15057827c8 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -437,12 +437,16 @@ Where `28` is an unused index from `eeconfig.h`. |`rgb_matrix_sethsv_noeeprom(h, s, v)` |Set LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) | ### Query Current Status :id=query-current-status -|Function |Description | -|-----------------------|-----------------| -|`rgb_matrix_get_mode()` |Get current mode | -|`rgb_matrix_get_hue()` |Get current hue | -|`rgb_matrix_get_sat()` |Get current sat | -|`rgb_matrix_get_val()` |Get current val | +|Function |Description | +|---------------------------------|---------------------------| +|`rgb_matrix_is_enabled()` |Gets current on/off status | +|`rgb_matrix_get_mode()` |Gets current mode | +|`rgb_matrix_get_hue()` |Gets current hue | +|`rgb_matrix_get_sat()` |Gets current sat | +|`rgb_matrix_get_val()` |Gets current val | +|`rgb_matrix_get_hsv()` |Gets hue, sat, and val and returns a [`HSV` structure](https://github.com/qmk/qmk_firmware/blob/7ba6456c0b2e041bb9f97dbed265c5b8b4b12192/quantum/color.h#L56-L61)| +|`rgb_matrix_get_speed()` |Gets current speed | +|`rgb_matrix_get_suspend_state()` |Gets current suspend state | ## Callbacks :id=callbacks diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index 219cd8317b..7f5c8a36c1 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -94,6 +94,7 @@ if `RGBLIGHT_EFFECT_xxxx` or `RGBLIGHT_ANIMATIONS` is defined, you also have a n |`RGBLIGHT_MODE_STATIC_GRADIENT`| 0,1,..,9 |Static gradient | |`RGBLIGHT_MODE_RGB_TEST` | *None* |RGB Test | |`RGBLIGHT_MODE_ALTERNATING` | *None* |Alternating | +|`RGBLIGHT_MODE_TWINKLE` | 0,1,2,3,4,5 |Twinkle | Check out [this video](https://youtube.com/watch?v=VKrpPAHlisY) for a demonstration. @@ -103,8 +104,8 @@ Note: For versions older than 0.6.117, The mode numbers were written directly. I Use these defines to add or remove animations from the firmware. When you are running low on flash space, it can be helpful to disable animations you are not using. -|Define |Default |Description | -|------------------------------------|-------------|-------------------------------------------------------------------------------------| +|Define |Default |Description | +|------------------------------------|-------------|-------------------------------------------------------------------------| |`RGBLIGHT_ANIMATIONS` |*Not defined*|Enable all additional animation modes. | |`RGBLIGHT_EFFECT_ALTERNATING` |*Not defined*|Enable alternating animation mode. | |`RGBLIGHT_EFFECT_BREATHING` |*Not defined*|Enable breathing animation mode. | @@ -115,6 +116,7 @@ Use these defines to add or remove animations from the firmware. When you are ru |`RGBLIGHT_EFFECT_RGB_TEST` |*Not defined*|Enable RGB test animation mode. | |`RGBLIGHT_EFFECT_SNAKE` |*Not defined*|Enable snake animation mode. | |`RGBLIGHT_EFFECT_STATIC_GRADIENT` |*Not defined*|Enable static gradient mode. | +|`RGBLIGHT_EFFECT_TWINKLE` |*Not defined*|Enable twinkle animation mode. | ### Effect and Animation Settings @@ -131,6 +133,8 @@ The following options are used to tweak the various animations: |`RGBLIGHT_EFFECT_KNIGHT_OFFSET` |`0` |The number of LEDs to start the "Knight" animation from the start of the strip by | |`RGBLIGHT_RAINBOW_SWIRL_RANGE` |`255` |Range adjustment for the rainbow swirl effect to get different swirls | |`RGBLIGHT_EFFECT_SNAKE_LENGTH` |`4` |The number of LEDs to light up for the "Snake" animation | +|`RGBLIGHT_EFFECT_TWINKLE_LIFE` |`75` |Adjusts how quickly each LED brightens and dims when twinkling (in animation steps) | +|`RGBLIGHT_EFFECT_TWINKLE_PROBABILITY`|`1/127` |Adjusts how likely each LED is to twinkle (on each animation step) | ### Example Usage to Reduce Memory Footprint 1. Remove `RGBLIGHT_ANIMATIONS` from `config.h`. @@ -168,6 +172,9 @@ const uint8_t RGBLED_SNAKE_INTERVALS[] PROGMEM = {100, 50, 20}; // How long (in milliseconds) to wait between animation steps for each of the "Knight" animations const uint8_t RGBLED_KNIGHT_INTERVALS[] PROGMEM = {127, 63, 31}; +// How long (in milliseconds) to wait between animation steps for each of the "Twinkle" animations +const uint8_t RGBLED_TWINKLE_INTERVALS[] PROGMEM = {50, 25, 10}; + // These control which hues are selected for each of the "Static gradient" modes const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64}; ``` @@ -177,6 +184,10 @@ const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64}; By including `#define RGBLIGHT_LAYERS` in your `config.h` file you can enable lighting layers. These make it easy to use your underglow LEDs as status indicators to show which keyboard layer is currently active, or the state of caps lock, all without disrupting any animations. [Here's a video](https://youtu.be/uLGE1epbmdY) showing an example of what you can do. +### Defining Lighting Layers :id=defining-lighting-layers + +By default, 8 layers are possible. This can be expanded to as many as 32 by overriding the definition of `RGBLIGHT_MAX_LAYERS` in `config.h` (e.g. `#define RGBLIGHT_MAX_LAYERS 32`). Please note, if you use a split keyboard, you will need to flash both sides of the split after changing this. Also, increasing the maximum will increase the firmware size, and will slow sync on split keyboards. + To define a layer, we modify `keymap.c` to list out LED ranges and the colors we want to overlay on them using an array of `rgblight_segment_t` using the `RGBLIGHT_LAYER_SEGMENTS` macro. We can define multiple layers and enable/disable them independently: ```c @@ -211,8 +222,12 @@ void keyboard_post_init_user(void) { rgblight_layers = my_rgb_layers; } ``` +Note: For split keyboards with two controllers, both sides need to be flashed when updating the contents of rgblight_layers. + +### Enabling and disabling lighting layers :id=enabling-lighting-layers -Finally, we enable and disable the lighting layers whenever the state of the keyboard changes: +Everything above just configured the definition of each lighting layer. +We can now enable and disable the lighting layers whenever the state of the keyboard changes: ```c layer_state_t layer_state_set_user(layer_state_t state) { @@ -228,7 +243,40 @@ bool led_update_user(led_t led_state) { } ``` -Note: For split keyboards with two controllers, both sides need to be flashed when updating the contents of rgblight_layers. +### Lighting layer blink :id=lighting-layer-blink + +By including `#define RGBLIGHT_LAYER_BLINK` in your `config.h` file you can turn a lighting +layer on for a specified duration. Once the specified number of milliseconds has elapsed +the layer will be turned off. This is useful, e.g., if you want to acknowledge some +action (e.g. toggling some setting): + +```c +const rgblight_segment_t PROGMEM _yes_layer[] = RGBLIGHT_LAYER_SEGMENTS( {9, 6, HSV_GREEN} ); +const rgblight_segment_t PROGMEM _no_layer[] = RGBLIGHT_LAYER_SEGMENTS( {9, 6, HSV_RED} ); + +const rgblight_segment_t* const PROGMEM _rgb_layers[] = + RGBLIGHT_LAYERS_LIST( _yes_layer, _no_layer ); + +void keyboard_post_init_user(void) { + rgblight_layers = _rgb_layers; +} + +// Note we user post_process_record_user because we want the state +// after the flag has been flipped... +void post_process_record_user(uint16_t keycode, keyrecord_t *record) { + switch (keycode) { + case DEBUG: + rgblight_blink_layer(debug_enable ? 0 : 1, 500); + break; + + case NK_TOGG: + case NK_ON: + case NK_OFF: + rgblight_blink_layer(keymap_config.nkro ? 0 : 1, 500); + break; + } +} +``` ## Functions @@ -328,12 +376,14 @@ rgblight_sethsv(HSV_GREEN, 2); // led 2 |`rgblight_set_layer_state(i, is_on)` |Enable or disable lighting layer `i` based on value of `bool is_on` | #### query -|Function |Description | -|-----------------------|-----------------| -|`rgblight_get_mode()` |Get current mode | -|`rgblight_get_hue()` |Get current hue | -|`rgblight_get_sat()` |Get current sat | -|`rgblight_get_val()` |Get current val | +|Function |Description | +|-----------------------|---------------------------| +|`rgblight_is_enabled()`|Gets current on/off status | +|`rgblight_get_mode()` |Gets current mode | +|`rgblight_get_hue()` |Gets current hue | +|`rgblight_get_sat()` |Gets current sat | +|`rgblight_get_val()` |Gets current val | +|`rgblight_get_speed()` |Gets current speed | ## Colors diff --git a/docs/feature_swap_hands.md b/docs/feature_swap_hands.md index 09e01d50d3..009477d203 100644 --- a/docs/feature_swap_hands.md +++ b/docs/feature_swap_hands.md @@ -28,3 +28,4 @@ Note that the array indices are reversed same as the matrix and the values are o |`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. | +|`SH_OS` |One shot swap hands: toggles while pressed or until next key press. | diff --git a/docs/index.html b/docs/index.html index f810e6c38f..68bd00f6dd 100644 --- a/docs/index.html +++ b/docs/index.html @@ -32,7 +32,7 @@ // Moved pages '/adding_a_keyboard_to_qmk': '/hardware_keyboard_guidelines', - '/build_environment_setup': '/getting_started_build_tools', + '/build_environment_setup': '/newbs_getting_started', '/cli_dev_configuration': '/cli_configuration', '/dynamic_macros': '/feature_dynamic_macros', '/feature_common_shortcuts': '/feature_advanced_keycodes', @@ -45,6 +45,7 @@ '/tap_dance': '/feature_tap_dance', '/unicode': '/feature_unicode', '/python_development': '/cli_development', + '/getting_started_build_tools':'/newbs_getting_started', }, basePath: '/', name: 'QMK Firmware', diff --git a/docs/internals_gpio_control.md b/docs/internals_gpio_control.md index 74ac090355..48eaf8875b 100644 --- a/docs/internals_gpio_control.md +++ b/docs/internals_gpio_control.md @@ -16,6 +16,7 @@ The following functions can provide basic control of GPIOs and are found in `qua | `writePinLow(pin)` | Set pin level as low, assuming it is an output | `PORTB &= ~(1<<2)` | `palClearLine(pin)` | | `writePin(pin, level)` | Set pin level, assuming it is an output | `(level) ? PORTB \|= (1<<2) : PORTB &= ~(1<<2)` | `(level) ? palSetLine(pin) : palClearLine(pin)` | | `readPin(pin)` | Returns the level of the pin | `_SFR_IO8(pin >> 4) & _BV(pin & 0xF)` | `palReadLine(pin)` | +| `togglePin(pin)` | Invert pin level, assuming it is an output | `PORTB ^= (1<<2)` | `palToggleLine(pin)` | ## Advanced Settings :id=advanced-settings diff --git a/docs/isp_flashing_guide.md b/docs/isp_flashing_guide.md index 944dd34622..8ee5a40d9e 100644 --- a/docs/isp_flashing_guide.md +++ b/docs/isp_flashing_guide.md @@ -115,12 +115,18 @@ The simplest and quickest way to get things back to normal is to flash only a bo You can find the stock bootloaders in the [`util/` folder](https://github.com/qmk/qmk_firmware/tree/master/util). Be sure to flash the correct bootloader for your chip: -* [`atmega32u4`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32u4_1_0_0.hex) - Most keyboards, Planck Rev 1-5, Preonic Rev 1-2 -* [`Pro Micro`](https://github.com/sparkfun/Arduino_Boards/blob/master/sparkfun/avr/bootloaders/caterina/Caterina-promicro16.hex) - The default bootloader for Pro Micro controllers -* [`at90usb1286`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb128x_1_0_1.hex) - Planck Light Rev 1 -* [`atmega32a`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32a_1_0_0.hex) - jj40, and other V-USB/ps2avrGB keyboards - -If you're not sure what your board uses, look in the `rules.mk` file for the keyboard in QMK. The `MCU =` line will have the value you need. It may differ between different versions of the board. +* **Atmel DFU** + * [ATmega16U4](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega16u4_1.0.1.hex) + * [ATmega32U4](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32u4_1.0.0.hex) + * [AT90USB64](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb64_1.0.0.hex) + * [AT90USB128](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb128_1.0.1.hex) +* **Caterina** + * [Pro Micro (5V/16MHz)](https://github.com/sparkfun/Arduino_Boards/blob/master/sparkfun/avr/bootloaders/caterina/Caterina-promicro16.hex) + * [Pro Micro (3.3V/8MHz)](https://github.com/sparkfun/Arduino_Boards/blob/master/sparkfun/avr/bootloaders/caterina/Caterina-promicro8.hex) +* **BootloadHID (PS2AVRGB)** + * [ATmega32A](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_ps2avrgb_bootloadhid_1.0.1.hex) + +If you're not sure what your board uses, look in the `rules.mk` file for the keyboard in QMK. The `MCU` and `BOOTLOADER` lines will have the value you need. It may differ between different versions of the board. ### Production Techniques diff --git a/docs/ja/feature_haptic_feedback.md b/docs/ja/feature_haptic_feedback.md new file mode 100644 index 0000000000..b9b4267014 --- /dev/null +++ b/docs/ja/feature_haptic_feedback.md @@ -0,0 +1,163 @@ +# 触覚フィードバック + +<!--- + original document: 0.8.123:docs/feature_haptic_feedback.md + git diff 0.8.123 HEAD -- docs/feature_haptic_feedback.md | cat +--> + +## 触覚フィードバック の rules.mk オプション + +現在のところ、`rules.mk` で触覚フィードバック用に以下のオプションを利用可能です: + +`HAPTIC_ENABLE += DRV2605L` + +`HAPTIC_ENABLE += SOLENOID` + +## サポートされる既知のハードウェア + +| 名前 | 説明 | +|--------------------|-------------------------------------------------| +| [LV061228B-L65-A](https://www.digikey.com/product-detail/en/jinlong-machinery-electronics-inc/LV061228B-L65-A/1670-1050-ND/7732325) | z-axis 2v LRA | +| [Mini Motor Disc](https://www.adafruit.com/product/1201) | small 2-5v ERM | + +## 触覚キーコード + +以下のキーコードは、選択した触覚メカニズムに依存して動作するかどうか決まります。 + +| 名前 | 説明 | +|-----------|-------------------------------------------------------| +| `HPT_ON` | 触覚フィードバックをオン | +| `HPT_OFF` | 触覚フィードバックをオフ | +| `HPT_TOG` | 触覚フィードバックのオン/オフを切り替え | +| `HPT_RST` | 触覚フィードバック設定をデフォルトに戻す | +| `HPT_FBK` | キー押下またはリリースまたはその両方でフィードバックを切り替え | +| `HPT_BUZ` | ソレノイドの振動のオン/オフを切り替え | +| `HPT_MODI` | 次の DRV2605L 波形に移動 | +| `HPT_MODD` | 前の DRV2605L 波形に移動 | +| `HPT_CONT` | 連続触覚モードのオン/オフを切り替え | +| `HPT_CONI` | DRV2605L の連続触覚強度を増加 | +| `HPT_COND` | DRV2605L の連続触覚強度を減少 | +| `HPT_DWLI` | ソレノイドの滞留時間を増加 | +| `HPT_DWLD` | ソレノイドの滞留時間を減少 | + +### ソレノイド + +ほとんどの MCU はソレノイドのコイルを駆動するために必要な電流を供給できないため、最初に MOSFET を介してソレノイドを駆動する回路を構築する必要があります。 + +[Adafruit が提供する配線図](https://playground.arduino.cc/uploads/Learning/solenoid_driver.pdf) + + +| 設定 | デフォルト | 説明 | +|--------------------------|---------------|-------------------------------------------------------| +| `SOLENOID_PIN` | *定義なし* | ソレノイドが接続されているピンを設定する。 | +| `SOLENOID_DEFAULT_DWELL` | `12` ms | ソレノイドのデフォルトの滞留時間を設定する。 | +| `SOLENOID_MIN_DWELL` | `4` ms | 滞留時間の下限を設定する。 | +| `SOLENOID_MAX_DWELL` | `100` ms | 滞留時間の上限を設定する。 | + +?> 滞留時間とは、「プランジャー」が作動したままになる時間です。滞留時間により、ソレノイドの音が変わります。 + +ブートローダ実行中に一部のピンが給電されているかもしれず (例えば、STM32F303 チップ上の A13)、そうすると書き込みプロセスの間ずっとソレノイドがオン状態になることに注意してください。これはソレノイドを加熱し損傷を与えるかもしれません。ソレノイドが接続されているピンがブートローダ/DFU 実行中にソレノイドをオンにしていることが分かった場合は、他のピンを選択してください。 + +### DRV2605L + +DRV2605Lは i2c プロトコルで制御され、SDA および SCL ピンに接続する必要があります。これらは使用する MCU によって異なります。 + +#### フィードバックモータのセットアップ + +このドライバは2つの異なるフィードバックモータをサポートします。選択したモータに基づいて、`config.h` で以下を設定します。 + +##### ERM + +偏心回転質量振動モータ (ERM) は偏りのある重りが取り付けられたモータで、駆動信号が取り付けられると偏りのある重りが回転し、正弦波が振動に変換されます。 + +``` +#define FB_ERM_LRA 0 +#define FB_BRAKEFACTOR 3 /* For 1x:0, 2x:1, 3x:2, 4x:3, 6x:4, 8x:5, 16x:6, Disable Braking:7 */ +#define FB_LOOPGAIN 1 /* For Low:0, Medium:1, High:2, Very High:3 */ + +/* 特定のモータに最適な設定については、データシートを参照してください。*/ +#define RATED_VOLTAGE 3 +#define V_PEAK 5 +``` +##### LRA + +線形共振アクチュエータ (LRA、線形バイブレータとしても知られています)は、ERM と異なります。LRA は重りと磁石をバネで吊るしたものとボイスコイルで構成されています。駆動信号が印加されるとされると、重りは単一の軸で振動します (左右または上下)。重りはバネに取り付けられているため、特定の周波数で共振効果があります。この周波数は LRA が最も効率的に動作する箇所です。この周波数の推奨範囲については、モータのデータシートを参照してください。 + +``` +#define FB_ERM_LRA 1 +#define FB_BRAKEFACTOR 3 /* For 1x:0, 2x:1, 3x:2, 4x:3, 6x:4, 8x:5, 16x:6, Disable Braking:7 */ +#define FB_LOOPGAIN 1 /* For Low:0, Medium:1, High:2, Very High:3 */ + +/* 特定のモータに最適な設定については、データシートを参照してください。*/ +#define RATED_VOLTAGE 2 +#define V_PEAK 2.8 +#define V_RMS 2.0 +#define V_PEAK 2.1 +#define F_LRA 205 /* 共振周波数 */ +``` + +#### DRV2605L 波形ライブラリ + +DRV2605L には呼び出して再生できる様々な波形シーケンスのプリロードライブラリが同梱されています。マクロを書く場合、これらの波形は `DRV_pulse(*sequence name or number*)` を使って再生することができます + +データシートの波形シーケンスのリスト + +| seq# | シーケンス名 | seq# | シーケンス名 | seq# | シーケンス名 | +|-----|---------------------|-----|-----------------------------------|-----|--------------------------------------| +| 1 | strong_click | 43 | lg_dblclick_med_60 | 85 | transition_rampup_med_smooth2 | +| 2 | strong_click_60 | 44 | lg_dblsharp_tick | 86 | transition_rampup_short_smooth1 | +| 3 | strong_click_30 | 45 | lg_dblsharp_tick_80 | 87 | transition_rampup_short_smooth2 | +| 4 | sharp_click | 46 | lg_dblsharp_tick_60 | 88 | transition_rampup_long_sharp1 | +| 5 | sharp_click_60 | 47 | buzz | 89 | transition_rampup_long_sharp2 | +| 6 | sharp_click_30 | 48 | buzz_80 | 90 | transition_rampup_med_sharp1 | +| 7 | soft_bump | 49 | buzz_60 | 91 | transition_rampup_med_sharp2 | +| 8 | soft_bump_60 | 50 | buzz_40 | 92 | transition_rampup_short_sharp1 | +| 9 | soft_bump_30 | 51 | buzz_20 | 93 | transition_rampup_short_sharp2 | +| 10 | dbl_click | 52 | pulsing_strong | 94 | transition_rampdown_long_smooth1_50 | +| 11 | dbl_click_60 | 53 | pulsing_strong_80 | 95 | transition_rampdown_long_smooth2_50 | +| 12 | trp_click | 54 | pulsing_medium | 96 | transition_rampdown_med_smooth1_50 | +| 13 | soft_fuzz | 55 | pulsing_medium_80 | 97 | transition_rampdown_med_smooth2_50 | +| 14 | strong_buzz | 56 | pulsing_sharp | 98 | transition_rampdown_short_smooth1_50 | +| 15 | alert_750ms | 57 | pulsing_sharp_80 | 99 | transition_rampdown_short_smooth2_50 | +| 16 | alert_1000ms | 58 | transition_click | 100 | transition_rampdown_long_sharp1_50 | +| 17 | strong_click1 | 59 | transition_click_80 | 101 | transition_rampdown_long_sharp2_50 | +| 18 | strong_click2_80 | 60 | transition_click_60 | 102 | transition_rampdown_med_sharp1_50 | +| 19 | strong_click3_60 | 61 | transition_click_40 | 103 | transition_rampdown_med_sharp2_50 | +| 20 | strong_click4_30 | 62 | transition_click_20 | 104 | transition_rampdown_short_sharp1_50 | +| 21 | medium_click1 | 63 | transition_click_10 | 105 | transition_rampdown_short_sharp2_50 | +| 22 | medium_click2_80 | 64 | transition_hum | 106 | transition_rampup_long_smooth1_50 | +| 23 | medium_click3_60 | 65 | transition_hum_80 | 107 | transition_rampup_long_smooth2_50 | +| 24 | sharp_tick1 | 66 | transition_hum_60 | 108 | transition_rampup_med_smooth1_50 | +| 25 | sharp_tick2_80 | 67 | transition_hum_40 | 109 | transition_rampup_med_smooth2_50 | +| 26 | sharp_tick3_60 | 68 | transition_hum_20 | 110 | transition_rampup_short_smooth1_50 | +| 27 | sh_dblclick_str | 69 | transition_hum_10 | 111 | transition_rampup_short_smooth2_50 | +| 28 | sh_dblclick_str_80 | 70 | transition_rampdown_long_smooth1 | 112 | transition_rampup_long_sharp1_50 | +| 29 | sh_dblclick_str_60 | 71 | transition_rampdown_long_smooth2 | 113 | transition_rampup_long_sharp2_50 | +| 30 | sh_dblclick_str_30 | 72 | transition_rampdown_med_smooth1 | 114 | transition_rampup_med_sharp1_50 | +| 31 | sh_dblclick_med | 73 | transition_rampdown_med_smooth2 | 115 | transition_rampup_med_sharp2_50 | +| 32 | sh_dblclick_med_80 | 74 | transition_rampdown_short_smooth1 | 116 | transition_rampup_short_sharp1_50 | +| 33 | sh_dblclick_med_60 | 75 | transition_rampdown_short_smooth2 | 117 | transition_rampup_short_sharp2_50 | +| 34 | sh_dblsharp_tick | 76 | transition_rampdown_long_sharp1 | 118 | long_buzz_for_programmatic_stopping | +| 35 | sh_dblsharp_tick_80 | 77 | transition_rampdown_long_sharp2 | 119 | smooth_hum1_50 | +| 36 | sh_dblsharp_tick_60 | 78 | transition_rampdown_med_sharp1 | 120 | smooth_hum2_40 | +| 37 | lg_dblclick_str | 79 | transition_rampdown_med_sharp2 | 121 | smooth_hum3_30 | +| 38 | lg_dblclick_str_80 | 80 | transition_rampdown_short_sharp1 | 122 | smooth_hum4_20 | +| 39 | lg_dblclick_str_60 | 81 | transition_rampdown_short_sharp2 | 123 | smooth_hum5_10 | +| 40 | lg_dblclick_str_30 | 82 | transition_rampup_long_smooth1 | | | +| 41 | lg_dblclick_med | 83 | transition_rampup_long_smooth2 | | | +| 42 | lg_dblclick_med_80 | 84 | transition_rampup_med_smooth1 | | | +### オプションの DRV2605L の定義 + +``` +#define DRV_GREETING *sequence name or number* +``` +触覚フィードバッグが有効な場合、キーボード起動時に特定のシーケンスに合わせて振動します。以下の定義を使って選択することができます: + +``` +#define DRV_MODE_DEFAULT *sequence name or number* +``` +これにより HPT_RST がアクティブモードとして設定するシーケンスを設定します。未定義の場合、HPT_RST が押された時にモードが 1 に設定されます。 + +### DRV2605L 連続触覚モード + +このモードは強さを増減するオプションを使って連続触覚フィードバッグを設定します。 diff --git a/docs/ja/feature_hd44780.md b/docs/ja/feature_hd44780.md index 5258632536..5ca4aade1e 100644 --- a/docs/ja/feature_hd44780.md +++ b/docs/ja/feature_hd44780.md @@ -55,7 +55,7 @@ LCD_DISP_ON_CURSOR_BLINK : ディスプレイオン、点滅カーソル ```` これはキーボードの `matrix_init_kb` またはキーマップの `matrix_init_user` で行うのが最適です。 使用前にディスプレイをクリアすることをお勧めします。 -そのためには、`lcd_clrsrc()` を呼びます。 +そのためには、`lcd_clrscr()` を呼びます。 ディスプレイに何かを表示するには、最初に `lcd_gotoxy(column, line)` を呼びます。最初の行の先頭に移動するには、`lcd_gotoxy(0, 0)` を呼び出し、その後 `lcd_puts("example string")` を使って文字列を出力します。 diff --git a/docs/ja/feature_key_lock.md b/docs/ja/feature_key_lock.md new file mode 100644 index 0000000000..b786fbb048 --- /dev/null +++ b/docs/ja/feature_key_lock.md @@ -0,0 +1,27 @@ +# キーロック + +<!--- + original document: 0.8.134:docs/feature_key_lock.md + git diff 0.8.134 HEAD -- docs/feature_key_lock.md | cat +--> + +特定のキーを長時間押すことが必要になる場合があります。キーロックは次に押すキーを押したままにします。もう一度押すと、リリースされます。 + +いくつかの文を全て大文字で入力する必要があるとしましょう。`KC_LOCK` を押し、次にシフトを押します。これで、シフトは次にタップするまで押していると見なされます。キーロックを Caps Lock と考えることができますが、さらに強力です。 + +## 使用法 + +最初に `rules.mk` で `KEY_LOCK_ENABLE = yes` を設定することでキーロックを有効にします。次に、キーマップでキーを選択し、それをキーコード `KC_LOCK` に割り当てます。 + +## キーコード + +| キーコード | 説明 | +|---------|--------------------------------------------------------------| +| `KC_LOCK` | キーが再び押されるまで次のキーを押したままにします。 | + +## 注意事項 + +キーロックは、標準アクションキーと[ワンショットモディファイア](ja/one_shot_keys.md)キー (例えば、Shift を `OSM(KC_LSFT)` と定義した場合)のみを押し続けることができます。 +これは、QMK の特殊機能(ワンショットモディファイアを除く)、または `KC_LPRN` のような shift を押されたキーのバージョンは含みません。[基本的なキーコード](ja/keycodes_basic.md)リストにある場合、押したままにすることができます。 + +レイヤーの切り替えは、キーロックを解除しません。 diff --git a/docs/keycodes.md b/docs/keycodes.md index 18fd811184..40a46964a8 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -531,6 +531,7 @@ See also: [Swap Hands](feature_swap_hands.md) |`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. | +|`SH_OS` |One shot swap hands: toggle while pressed or until next key press. | ## Unicode Support :id=unicode-support diff --git a/docs/keymap.md b/docs/keymap.md index ba358edbe0..ef476e87f5 100644 --- a/docs/keymap.md +++ b/docs/keymap.md @@ -71,10 +71,22 @@ On the other hand, you can change `layer_state` to overlay the base layer with o ### Layer Precedence and Transparency -Note that ***higher layer has higher priority on stack of layers***, namely firmware falls down from top layer to bottom to look up keycode. Once it spots keycode other than **`KC_TRNS`**(transparent) on a layer it stops searching and lower layers aren't referred. - -You can place `KC_TRANS` on overlay layer changes just part of layout to fall back on lower or base layer. -Key with `KC_TRANS` (`KC_TRNS` and `_______` are the alias) doesn't has its own keycode and refers to lower valid layers for keycode, instead. +Note that ***higher layers have higher priority within the stack of layers***. The firmware works its way down from the highest active layers to look up keycodes. Once the firmware locates a keycode other than `KC_TRNS` (transparent) on an active layer, it stops searching, and lower layers aren't referenced. + + ____________ + / / <--- Higher layer + / KC_TRNS // + /___________// <--- Lower layer (KC_A) + /___________/ + + In the above scenario, the non-transparent keys on the higher layer would be usable, but whenever `KC_TRNS` (or equivalent) is defined, the keycode (`KC_A`) on the lower level would be used. + +**Note:** Valid ways to denote transparency on a given layer: +* `KC_TRANSPARENT` +* `KC_TRNS` (alias) +* `_______` (alias) + +These keycodes allow the processing to fall through to lower layers in search of a non-transparent keycode to process. ## Anatomy of a `keymap.c` diff --git a/docs/spi_driver.md b/docs/spi_driver.md index e2b5b140b7..c170bf1dfc 100644 --- a/docs/spi_driver.md +++ b/docs/spi_driver.md @@ -18,7 +18,24 @@ You may use more than one slave select pin, not just the `SS` pin. This is usefu ## ChibiOS/ARM Configuration -ARM support for this driver is not ready yet. Check back later! +You'll need to determine which pins can be used for SPI -- as an example, STM32 parts generally have multiple SPI peripherals, labeled SPI1, SPI2, SPI3 etc. + +To enable SPI, modify your board's `halconf.h` to enable SPI - both `HAL_USE_SPI` and `SPI_USE_WAIT` should be `TRUE`, and `SPI_SELECT_MODE` should be `SPI_SELECT_MODE_PAD`. +Then, modify your board's `mcuconf.h` to enable the SPI peripheral you've chosen -- in the case of using SPI2, modify `STM32_SPI_USE_SPI2` to be `TRUE`. + +As per the AVR configuration, you may select any other standard GPIO as a slave select pin, and can be supplied to `spi_start()`. + +Configuration-wise, you'll need to set up the peripheral as per your MCU's datasheet -- the defaults match the pins for a Proton-C, i.e. STM32F303. + +`config.h` override | Description | Default Value +----------------------------|---------------------------------------------------------------|-------------- +`#define SPI_DRIVER` | SPI peripheral to use - SPI1 => `SPID1`, SPI2 => `SPID2` etc. | `SPID2` +`#define SPI_SCK_PIN` | The pin to use for the SCK | `B13` +`#define SPI_SCK_PAL_MODE` | The alternate function mode for the SCK pin | `5` +`#define SPI_MOSI_PIN` | The pin to use for the MOSI | `B15` +`#define SPI_MOSI_PAL_MODE` | The alternate function mode for the MOSI pin | `5` +`#define SPI_MISO_PIN` | The pin to use for the MISO | `B14` +`#define SPI_MISO_PAL_MODE` | The alternate function mode for the MISO pin | `5` ## Functions diff --git a/docs/unit_testing.md b/docs/unit_testing.md index 4de5c217e8..a63ffff5d3 100644 --- a/docs/unit_testing.md +++ b/docs/unit_testing.md @@ -50,7 +50,7 @@ In that model you would emulate the input, and expect a certain output from the # Tracing Variables :id=tracing-variables -Sometimes you might wonder why a variable gets changed and where, and this can be quite tricky to track down without having a debugger. It's of course possible to manually add print statements to track it, but you can also enable the variable trace feature. This works for both for variables that are changed by the code, and when the variable is changed by some memory corruption. +Sometimes you might wonder why a variable gets changed and where, and this can be quite tricky to track down without having a debugger. It's of course possible to manually add print statements to track it, but you can also enable the variable trace feature. This works for both variables that are changed by the code, and when the variable is changed by some memory corruption. To take the feature into use add `VARIABLE_TRACE=x` to the end of you make command. `x` represents the number of variables you want to trace, which is usually 1. |