Compare commits
10 Commits
0d084a0a3e
...
8a2ce30e7f
| Author | SHA1 | Date | |
|---|---|---|---|
| 8a2ce30e7f | |||
| d27b779550 | |||
| 9e5189d9cd | |||
| dac1f1ef66 | |||
| 6ceb87a1d0 | |||
| a2c86b4053 | |||
| e33ae91091 | |||
| 39b43b676e | |||
| 8c8e1ad4d3 | |||
| 105f3f893c |
@ -1,30 +0,0 @@
|
||||
---
|
||||
BasedOnStyle: Google
|
||||
AlignAfterOpenBracket: Align
|
||||
AlignConsecutiveAssignments: 'true'
|
||||
AlignConsecutiveDeclarations: 'true'
|
||||
AlignOperands: 'true'
|
||||
AllowAllParametersOfDeclarationOnNextLine: 'false'
|
||||
AllowShortCaseLabelsOnASingleLine: 'false'
|
||||
AllowShortFunctionsOnASingleLine: Empty
|
||||
AllowShortLoopsOnASingleLine: 'false'
|
||||
AlwaysBreakAfterDefinitionReturnType: None
|
||||
AlwaysBreakAfterReturnType: None
|
||||
AlwaysBreakBeforeMultilineStrings: 'false'
|
||||
BinPackArguments: 'true'
|
||||
BinPackParameters: 'true'
|
||||
ColumnLimit: '1000'
|
||||
IndentCaseLabels: 'true'
|
||||
IndentPPDirectives: AfterHash
|
||||
IndentWidth: '4'
|
||||
MaxEmptyLinesToKeep: '1'
|
||||
PointerAlignment: Right
|
||||
SortIncludes: 'false'
|
||||
SpaceBeforeAssignmentOperators: 'true'
|
||||
SpaceBeforeParens: ControlStatements
|
||||
SpaceInEmptyParentheses: 'false'
|
||||
SpacesBeforeTrailingComments: 1
|
||||
TabWidth: '4'
|
||||
UseTab: Never
|
||||
|
||||
...
|
||||
4
.clangd
4
.clangd
@ -1,4 +0,0 @@
|
||||
CompileFlags:
|
||||
Add: [-Wno-unknown-attributes, -Wno-maybe-uninitialized, -Wno-unknown-warning-option]
|
||||
Remove: [-W*, -mcall-prologues]
|
||||
Compiler: clang
|
||||
@ -1,42 +0,0 @@
|
||||
# EditorConfig helps developers define and maintain consistent coding styles between different editors and IDEs
|
||||
# editorconfig.org
|
||||
|
||||
root = true
|
||||
|
||||
[*]
|
||||
indent_style = space
|
||||
indent_size = 4
|
||||
|
||||
# We recommend you to keep these unchanged
|
||||
charset = utf-8
|
||||
trim_trailing_whitespace = true
|
||||
insert_final_newline = true
|
||||
|
||||
[*.md]
|
||||
trim_trailing_whitespace = false
|
||||
indent_size = 4
|
||||
|
||||
[{qmk,*.py}]
|
||||
charset = utf-8
|
||||
max_line_length = 200
|
||||
|
||||
# Make these match what we have in .gitattributes
|
||||
[*.mk]
|
||||
end_of_line = lf
|
||||
indent_style = tab
|
||||
|
||||
[Makefile]
|
||||
end_of_line = lf
|
||||
indent_style = tab
|
||||
|
||||
[*.sh]
|
||||
end_of_line = lf
|
||||
|
||||
# The gitattributes file will handle the line endings conversion properly according to the operating system settings for other files
|
||||
|
||||
|
||||
# We don't have gitattributes properly for these
|
||||
# So if the user have for example core.autocrlf set to true
|
||||
# the line endings would be wrong.
|
||||
[lib/**]
|
||||
end_of_line = unset
|
||||
96
.gitattributes
vendored
96
.gitattributes
vendored
@ -1,96 +0,0 @@
|
||||
# auto for anything unspecified
|
||||
* text=auto
|
||||
|
||||
# sources
|
||||
*.c text eol=lf
|
||||
*.cc text eol=lf
|
||||
*.cxx text eol=lf
|
||||
*.cpp text eol=lf
|
||||
*.c++ text eol=lf
|
||||
*.hpp text eol=lf
|
||||
*.h text eol=lf
|
||||
*.h++ text eol=lf
|
||||
*.hh text eol=lf
|
||||
*.bat text eol=crlf
|
||||
*.cmd text eol=crlf
|
||||
*.coffee text eol=lf
|
||||
*.css text eol=lf
|
||||
*.htm text eol=lf
|
||||
*.html text eol=lf
|
||||
*.inc text eol=lf
|
||||
*.ini text eol=crlf
|
||||
*.js text eol=lf
|
||||
*.jsx text eol=lf
|
||||
*.json text eol=lf
|
||||
*.less text eol=lf
|
||||
*.php text eol=lf
|
||||
*.pl text eol=lf
|
||||
*.py text eol=lf
|
||||
*.rb text eol=lf
|
||||
*.sass text eol=lf
|
||||
*.scm text eol=lf
|
||||
*.scss text eol=lf
|
||||
*.sh text eol=lf
|
||||
*.sql text eol=lf
|
||||
*.styl text eol=lf
|
||||
*.ts text eol=lf
|
||||
*.xml text eol=lf
|
||||
*.xhtml text eol=lf
|
||||
|
||||
# make files (need to always use lf for compatibility with Windows 10 bash)
|
||||
Makefile eol=lf
|
||||
*.mk eol=lf
|
||||
|
||||
# make files (need to always use lf for compatibility with Windows 10 bash)
|
||||
*.sh eol=lf
|
||||
|
||||
# documentation
|
||||
*.markdown text eol=lf
|
||||
*.md text eol=lf
|
||||
*.mdwn text eol=lf
|
||||
*.mdown text eol=lf
|
||||
*.mkd text eol=lf
|
||||
*.mkdn text eol=lf
|
||||
*.mdtxt text eol=lf
|
||||
*.mdtext text eol=lf
|
||||
*.txt text eol=lf
|
||||
AUTHORS text eol=lf
|
||||
CHANGELOG text eol=lf
|
||||
CHANGES text eol=lf
|
||||
CONTRIBUTING text eol=lf
|
||||
COPYING text eol=lf
|
||||
INSTALL text eol=lf
|
||||
license text eol=lf
|
||||
LICENSE text eol=lf
|
||||
NEWS text eol=lf
|
||||
readme text eol=lf
|
||||
*README* text eol=lf
|
||||
TODO text eol=lf
|
||||
|
||||
GRAPHICS
|
||||
*.ai binary
|
||||
*.bmp binary
|
||||
*.eps binary
|
||||
*.gif binary
|
||||
*.ico binary
|
||||
*.jng binary
|
||||
*.jp2 binary
|
||||
*.jpg binary
|
||||
*.jpeg binary
|
||||
*.jpx binary
|
||||
*.jxr binary
|
||||
*.pdf binary
|
||||
*.png binary
|
||||
*.psb binary
|
||||
*.psd binary
|
||||
*.svg text eol=lf
|
||||
*.svgz binary
|
||||
*.tif binary
|
||||
*.tiff binary
|
||||
*.wbmp binary
|
||||
*.webp binary
|
||||
|
||||
# hex files
|
||||
*.hex binary
|
||||
*.eep binary
|
||||
nix/sources.nix linguist-generated=true
|
||||
41
.github/ISSUE_TEMPLATE/bug_report.yml
vendored
41
.github/ISSUE_TEMPLATE/bug_report.yml
vendored
@ -1,41 +0,0 @@
|
||||
name: Bug report
|
||||
description: Create a report to help us improve QMK Firmware.
|
||||
title: "[Bug] "
|
||||
labels: ["bug", "help wanted"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Provide a general summary of the bug in the title above.
|
||||
- type: textarea
|
||||
attributes:
|
||||
label: Describe the Bug
|
||||
description: A clear and concise description of what the bug is.
|
||||
- type: input
|
||||
attributes:
|
||||
label: Keyboard Used
|
||||
description: The name of the keyboard from the `make` or `qmk compile`/`qmk flash` commands, eg. `planck/rev6`.
|
||||
- type: input
|
||||
attributes:
|
||||
label: Link to product page (if applicable)
|
||||
- type: input
|
||||
attributes:
|
||||
label: Operating System
|
||||
- type: textarea
|
||||
attributes:
|
||||
label: qmk doctor Output
|
||||
description: Output from running the `qmk doctor` command.
|
||||
render: text
|
||||
- type: checkboxes
|
||||
attributes:
|
||||
label: Is AutoHotKey / Karabiner installed
|
||||
options:
|
||||
- label: AutoHotKey (Windows)
|
||||
- label: Karabiner (macOS)
|
||||
- type: input
|
||||
attributes:
|
||||
label: Other keyboard-related software installed
|
||||
- type: textarea
|
||||
attributes:
|
||||
label: Additional Context
|
||||
description: Add any other relevant information about the problem here.
|
||||
8
.github/ISSUE_TEMPLATE/config.yml
vendored
8
.github/ISSUE_TEMPLATE/config.yml
vendored
@ -1,8 +0,0 @@
|
||||
blank_issues_enabled: false
|
||||
contact_links:
|
||||
- name: QMK Discord
|
||||
url: https://discord.gg/Uq7gcHh
|
||||
about: Ask questions, discuss issues and features. Chill.
|
||||
- name: OLKB Subreddit
|
||||
url: https://www.reddit.com/r/olkb
|
||||
about: All things OLKB and QMK.
|
||||
24
.github/ISSUE_TEMPLATE/feature_request.yml
vendored
24
.github/ISSUE_TEMPLATE/feature_request.yml
vendored
@ -1,24 +0,0 @@
|
||||
name: Feature request
|
||||
description: Suggest a new feature or changes to existing features.
|
||||
title: "[Feature Request] "
|
||||
labels: ["enhancement", "help wanted"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Provide a general summary of the changes you want in the title above.
|
||||
|
||||
Please refrain from asking maintainers to add support for specific keyboards -- it is unlikely they will have hardware available, and will not be able to help.
|
||||
Your best bet is to take the initiative, add support, then submit a PR yourself.
|
||||
- type: checkboxes
|
||||
attributes:
|
||||
label: Feature Request Type
|
||||
options:
|
||||
- label: Core functionality
|
||||
- label: Add-on hardware support (eg. audio, RGB, OLED screen, etc.)
|
||||
- label: Alteration (enhancement/optimization) of existing feature(s)
|
||||
- label: New behavior
|
||||
- type: textarea
|
||||
attributes:
|
||||
label: Description
|
||||
description: A few sentences describing what it is that you'd like to see in QMK. Additional information (such as links to spec sheets, licensing info, other related issues or PRs, etc) would be helpful.
|
||||
19
.github/ISSUE_TEMPLATE/other_issues.yml
vendored
19
.github/ISSUE_TEMPLATE/other_issues.yml
vendored
@ -1,19 +0,0 @@
|
||||
name: Other issues
|
||||
description: Anything else that doesn't fall into the above categories.
|
||||
labels: ["help wanted", "question"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Provide a general summary of the changes you want in the title above.
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Please check [https://docs.qmk.fm/#/support](https://docs.qmk.fm/#/support) for additional resources first. If that doesn't answer your question, choose the bug report template instead, as that may be more appropriate.
|
||||
|
||||
Please refrain from asking maintainers to add support for specific keyboards -- it is unlikely they will have hardware available, and will not be able to help.
|
||||
Your best bet is to take the initiative, add support, then submit a PR yourself.
|
||||
- type: textarea
|
||||
attributes:
|
||||
label: Issue Description
|
||||
description: Describe your issue in as much detail as possible.
|
||||
11
.github/ISSUE_TEMPLATE/zzz_blank.md
vendored
11
.github/ISSUE_TEMPLATE/zzz_blank.md
vendored
@ -1,11 +0,0 @@
|
||||
---
|
||||
name: Blank issue
|
||||
about: If you're 100% sure that you don't need one of the other issue templates, use
|
||||
this one instead.
|
||||
title: ''
|
||||
labels: help wanted, question
|
||||
assignees: ''
|
||||
|
||||
---
|
||||
|
||||
|
||||
35
.github/PULL_REQUEST_TEMPLATE.md
vendored
35
.github/PULL_REQUEST_TEMPLATE.md
vendored
@ -1,35 +0,0 @@
|
||||
<!--- Provide a general summary of your changes in the title above. -->
|
||||
|
||||
<!--- This template is entirely optional and can be removed, but is here to help both you and us. -->
|
||||
<!--- Anything on lines wrapped in comments like these will not show up in the final text. -->
|
||||
|
||||
## Description
|
||||
|
||||
<!--- Describe your changes in detail here. -->
|
||||
|
||||
## Types of Changes
|
||||
|
||||
<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply. -->
|
||||
- [ ] Core
|
||||
- [ ] Bugfix
|
||||
- [ ] New feature
|
||||
- [ ] Enhancement/optimization
|
||||
- [ ] Keyboard (addition or update)
|
||||
- [ ] Keymap/layout/userspace (addition or update)
|
||||
- [ ] Documentation
|
||||
|
||||
## Issues Fixed or Closed by This PR
|
||||
|
||||
*
|
||||
|
||||
## Checklist
|
||||
|
||||
<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
|
||||
<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
|
||||
- [ ] My code follows the code style of this project: [**C**](https://docs.qmk.fm/#/coding_conventions_c), [**Python**](https://docs.qmk.fm/#/coding_conventions_python)
|
||||
- [ ] I have read the [**PR Checklist** document](https://docs.qmk.fm/#/pr_checklist) and have made the appropriate changes.
|
||||
- [ ] My change requires a change to the documentation.
|
||||
- [ ] I have updated the documentation accordingly.
|
||||
- [ ] I have read the [**CONTRIBUTING** document](https://docs.qmk.fm/#/contributing).
|
||||
- [ ] I have added tests to cover my changes.
|
||||
- [ ] I have tested the changes and verified that they work and don't break anything (as well as I can manage).
|
||||
9
.github/dependabot.yml
vendored
9
.github/dependabot.yml
vendored
@ -1,9 +0,0 @@
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "github-actions"
|
||||
directory: "/"
|
||||
labels: CI
|
||||
reviewers:
|
||||
- "qmk/collaborators"
|
||||
schedule:
|
||||
interval: "daily"
|
||||
46
.github/labeler.yml
vendored
46
.github/labeler.yml
vendored
@ -1,46 +0,0 @@
|
||||
core:
|
||||
- quantum/**/*
|
||||
- tmk_core/**/*
|
||||
- drivers/**/*
|
||||
- tests/**/*
|
||||
- util/**/*
|
||||
- platforms/**/*
|
||||
- builddefs/**/*
|
||||
- Makefile
|
||||
- '*.mk'
|
||||
dependencies:
|
||||
- any:
|
||||
- 'lib/**/*'
|
||||
- '!lib/python/**/*'
|
||||
keyboard:
|
||||
- any:
|
||||
- 'keyboards/**/*'
|
||||
- '!keyboards/**/keymaps/**/*'
|
||||
keymap:
|
||||
- users/**/*
|
||||
- layouts/**/*
|
||||
- keyboards/**/keymaps/**/*
|
||||
via:
|
||||
- keyboards/**/keymaps/via/*
|
||||
cli:
|
||||
- requirements.txt
|
||||
- lib/python/**/*
|
||||
python:
|
||||
- '**/*.py'
|
||||
documentation:
|
||||
- docs/**/*
|
||||
translation:
|
||||
- docs/fr-fr/**/*
|
||||
- docs/es/**/*
|
||||
- docs/ja/**/*
|
||||
- docs/he-il/**/*
|
||||
- docs/pt-br/**/*
|
||||
- docs/zh-cn/**/*
|
||||
- docs/de/**/*
|
||||
- docs/ru-ru/**/*
|
||||
CI:
|
||||
- .github/**/*
|
||||
dd:
|
||||
- data/constants/**/*
|
||||
- data/mappings/**/*
|
||||
- data/schemas/**/*
|
||||
50
.github/workflows/api.yml
vendored
50
.github/workflows/api.yml
vendored
@ -1,50 +0,0 @@
|
||||
name: Update API Data
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
- develop
|
||||
paths:
|
||||
- 'keyboards/**'
|
||||
- 'layouts/community/**'
|
||||
- 'lib/python/**'
|
||||
- 'data/**'
|
||||
- '.github/workflows/api.yml'
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
api_data:
|
||||
runs-on: ubuntu-latest
|
||||
container: ghcr.io/qmk/qmk_cli
|
||||
|
||||
# protect against those who work in their fork on 'important' branches
|
||||
if: github.repository == 'qmk/qmk_firmware'
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 1
|
||||
persist-credentials: false
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
pip3 install -r requirements-dev.txt
|
||||
|
||||
- name: Generate API Data
|
||||
run: |
|
||||
qmk generate-api
|
||||
|
||||
- name: Upload API Data
|
||||
uses: jakejarvis/s3-sync-action@master
|
||||
with:
|
||||
args: --acl public-read --follow-symlinks --delete
|
||||
env:
|
||||
AWS_S3_BUCKET: ${{ github.ref == 'refs/heads/develop' && secrets['API_SPACE_DEVELOP'] || secrets['API_SPACE_MASTER'] }}
|
||||
AWS_ACCESS_KEY_ID: ${{ secrets.SPACES_ACCESS_KEY }}
|
||||
AWS_SECRET_ACCESS_KEY: ${{ secrets.SPACES_SECRET_KEY }}
|
||||
AWS_S3_ENDPOINT: https://nyc3.digitaloceanspaces.com
|
||||
SOURCE_DIR: '.build/api_data'
|
||||
20
.github/workflows/auto_approve.yml
vendored
20
.github/workflows/auto_approve.yml
vendored
@ -1,20 +0,0 @@
|
||||
name: Automatic Approve
|
||||
|
||||
permissions: {}
|
||||
|
||||
on:
|
||||
schedule:
|
||||
- cron: "*/5 * * * *"
|
||||
|
||||
jobs:
|
||||
automatic_approve:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
if: github.repository == 'qmk/qmk_firmware'
|
||||
|
||||
steps:
|
||||
- uses: mheap/automatic-approve-action@v1
|
||||
with:
|
||||
token: ${{ secrets.QMK_BOT_TOKEN }}
|
||||
workflows: "format.yml,lint.yml,unit_test.yml"
|
||||
dangerous_files: "lib/python/,Makefile,paths.mk,builddefs/"
|
||||
38
.github/workflows/auto_tag.yml
vendored
38
.github/workflows/auto_tag.yml
vendored
@ -1,38 +0,0 @@
|
||||
name: Essential files modified
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
paths:
|
||||
- builddefs/**/*
|
||||
- drivers/**/*
|
||||
- platforms/**/*
|
||||
- quantum/**/*
|
||||
- tests/**/*
|
||||
- tmk_core/**/*
|
||||
- util/**/*
|
||||
- Makefile
|
||||
- '*.mk'
|
||||
|
||||
jobs:
|
||||
tag:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
# protect against those who develop with their fork on master
|
||||
if: github.repository == 'qmk/qmk_firmware'
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Bump version and push tag
|
||||
uses: anothrNick/github-tag-action@1.66.0
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
DEFAULT_BUMP: 'patch'
|
||||
74
.github/workflows/ci_builds.yml
vendored
74
.github/workflows/ci_builds.yml
vendored
@ -1,74 +0,0 @@
|
||||
name: CI Builds
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [master, develop]
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
branch:
|
||||
type: choice
|
||||
description: 'Branch to build'
|
||||
options: [master, develop]
|
||||
|
||||
concurrency: ci_build-${{ github.event.inputs.branch || github.ref_name }}
|
||||
|
||||
jobs:
|
||||
ci_builds:
|
||||
if: github.repository == 'qmk/qmk_firmware'
|
||||
name: "CI Build"
|
||||
runs-on: self-hosted
|
||||
timeout-minutes: 1380
|
||||
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
keymap: [default, via]
|
||||
|
||||
container: ghcr.io/qmk/qmk_cli
|
||||
|
||||
steps:
|
||||
- name: Disable safe.directory check
|
||||
run : git config --global --add safe.directory '*'
|
||||
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
submodules: recursive
|
||||
ref: ${{ github.event.inputs.branch || github.ref }}
|
||||
|
||||
- name: Install dependencies
|
||||
run: pip3 install -r requirements.txt
|
||||
|
||||
- name: Run `qmk mass-compile` (keymap ${{ matrix.keymap }})
|
||||
run: |
|
||||
export NCPUS=$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null)
|
||||
qmk mass-compile -t -j $NCPUS -km ${{ matrix.keymap }} -e DUMP_CI_METADATA=yes || touch .failed
|
||||
# Generate the step summary markdown
|
||||
./util/ci/generate_failure_markdown.sh > $GITHUB_STEP_SUMMARY || true
|
||||
# Truncate to a maximum of 1MB to deal with GitHub workflow limit
|
||||
truncate --size='<960K' $GITHUB_STEP_SUMMARY || true
|
||||
# Exit with failure if the compilation stage failed
|
||||
[ ! -f .failed ] || exit 1
|
||||
|
||||
- name: 'Upload artifacts'
|
||||
uses: actions/upload-artifact@v3
|
||||
if: always()
|
||||
with:
|
||||
name: artifacts-${{ github.event.inputs.branch || github.ref_name }}-${{ matrix.keymap }}
|
||||
if-no-files-found: ignore
|
||||
path: |
|
||||
*.bin
|
||||
*.hex
|
||||
*.uf2
|
||||
.build/failed.*
|
||||
|
||||
- name: 'CI Discord Notification'
|
||||
if: always()
|
||||
working-directory: util/ci/
|
||||
env:
|
||||
DISCORD_WEBHOOK: ${{ secrets.CI_DISCORD_WEBHOOK }}
|
||||
run: |
|
||||
python3 -m pip install -r requirements.txt
|
||||
python3 ./discord-results.py --branch ${{ github.event.inputs.branch || github.ref_name }} --keymap ${{ matrix.keymap }} --url ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
|
||||
34
.github/workflows/cli.yml
vendored
34
.github/workflows/cli.yml
vendored
@ -1,34 +0,0 @@
|
||||
name: CLI CI
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
- develop
|
||||
pull_request:
|
||||
paths:
|
||||
- 'lib/python/**'
|
||||
- 'requirements.txt'
|
||||
- '.github/workflows/cli.yml'
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
container: ghcr.io/qmk/qmk_cli
|
||||
|
||||
steps:
|
||||
- name: Disable safe.directory check
|
||||
run : git config --global --add safe.directory '*'
|
||||
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
submodules: recursive
|
||||
|
||||
- name: Install dependencies
|
||||
run: pip3 install -r requirements-dev.txt
|
||||
- name: Run tests
|
||||
run: qmk pytest
|
||||
37
.github/workflows/develop_update.yml
vendored
37
.github/workflows/develop_update.yml
vendored
@ -1,37 +0,0 @@
|
||||
name: Update develop after master merge
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
|
||||
jobs:
|
||||
develop_update:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
if: github.repository == 'qmk/qmk_firmware'
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
token: ${{ secrets.QMK_BOT_TOKEN }}
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Disable automatic eol conversion
|
||||
run: |
|
||||
echo "* -text" > .git/info/attributes
|
||||
|
||||
- name: Checkout develop
|
||||
run: |
|
||||
git fetch origin master develop
|
||||
git checkout develop
|
||||
|
||||
- name: Update develop from master
|
||||
run: |
|
||||
git config --global user.name "QMK Bot"
|
||||
git config --global user.email "hello@qmk.fm"
|
||||
git merge origin/master
|
||||
git push origin develop
|
||||
46
.github/workflows/docs.yml
vendored
46
.github/workflows/docs.yml
vendored
@ -1,46 +0,0 @@
|
||||
name: Generate Docs
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
paths:
|
||||
- 'tmk_core/**'
|
||||
- 'quantum/**'
|
||||
- 'platforms/**'
|
||||
- 'docs/**'
|
||||
- '.github/workflows/docs.yml'
|
||||
|
||||
jobs:
|
||||
generate:
|
||||
runs-on: ubuntu-latest
|
||||
container: ghcr.io/qmk/qmk_cli
|
||||
|
||||
# protect against those who develop with their fork on master
|
||||
if: github.repository == 'qmk/qmk_firmware'
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 1
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
apt-get update && apt-get install -y rsync nodejs npm doxygen
|
||||
npm install -g moxygen
|
||||
|
||||
- name: Build docs
|
||||
run: |
|
||||
qmk --verbose generate-docs
|
||||
|
||||
- name: Deploy
|
||||
uses: JamesIves/github-pages-deploy-action@v4.4.3
|
||||
with:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
BASE_BRANCH: master
|
||||
BRANCH: gh-pages
|
||||
FOLDER: .build/docs
|
||||
GIT_CONFIG_EMAIL: hello@qmk.fm
|
||||
43
.github/workflows/feature_branch_update.yml
vendored
43
.github/workflows/feature_branch_update.yml
vendored
@ -1,43 +0,0 @@
|
||||
name: Update feature branches after develop merge
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- develop
|
||||
|
||||
jobs:
|
||||
feature_branch_update:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
if: github.repository == 'qmk/qmk_firmware'
|
||||
|
||||
strategy:
|
||||
matrix:
|
||||
branch:
|
||||
- xap
|
||||
- riot
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
token: ${{ secrets.QMK_BOT_TOKEN }}
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Disable automatic eol conversion
|
||||
run: |
|
||||
echo "* -text" > .git/info/attributes
|
||||
|
||||
- name: Checkout branch
|
||||
run: |
|
||||
git fetch origin develop ${{ matrix.branch }}
|
||||
git checkout ${{ matrix.branch }}
|
||||
|
||||
- name: Update branch from develop
|
||||
run: |
|
||||
git config --global user.name "QMK Bot"
|
||||
git config --global user.email "hello@qmk.fm"
|
||||
git merge origin/develop
|
||||
git push origin ${{ matrix.branch }}
|
||||
55
.github/workflows/format.yml
vendored
55
.github/workflows/format.yml
vendored
@ -1,55 +0,0 @@
|
||||
name: PR Lint Format
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- 'drivers/**'
|
||||
- 'lib/arm_atsam/**'
|
||||
- 'lib/lib8tion/**'
|
||||
- 'lib/python/**'
|
||||
- 'platforms/**'
|
||||
- 'quantum/**'
|
||||
- 'tests/**'
|
||||
- 'tmk_core/**'
|
||||
|
||||
jobs:
|
||||
lint:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
container: ghcr.io/qmk/qmk_cli
|
||||
|
||||
steps:
|
||||
- name: Disable safe.directory check
|
||||
run : git config --global --add safe.directory '*'
|
||||
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
pip3 install -r requirements-dev.txt
|
||||
|
||||
- name: Get changed files
|
||||
id: file_changes
|
||||
uses: tj-actions/changed-files@v39
|
||||
|
||||
- name: Run qmk formatters
|
||||
shell: 'bash {0}'
|
||||
run: |
|
||||
echo '${{ steps.file_changes.outputs.added_files}}' '${{ steps.file_changes.outputs.modified_files}}' > ~/files_changed.txt
|
||||
qmk format-c --core-only $(< ~/files_changed.txt) || true
|
||||
qmk format-python $(< ~/files_changed.txt) || true
|
||||
qmk format-text $(< ~/files_changed.txt) || true
|
||||
|
||||
- name: Fail when formatting required
|
||||
run: |
|
||||
git diff
|
||||
for file in $(git diff --name-only); do
|
||||
echo "File '${file}' Requires Formatting"
|
||||
echo "::error file=${file}::Requires Formatting"
|
||||
done
|
||||
test -z "$(git diff --name-only)"
|
||||
59
.github/workflows/format_push.yml
vendored
59
.github/workflows/format_push.yml
vendored
@ -1,59 +0,0 @@
|
||||
name: Lint Format
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
- develop
|
||||
|
||||
jobs:
|
||||
lint:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
container: ghcr.io/qmk/qmk_cli
|
||||
|
||||
steps:
|
||||
- name: Disable safe.directory check
|
||||
run : git config --global --add safe.directory '*'
|
||||
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Disable automatic eol conversion
|
||||
run: |
|
||||
echo "* -text" > .git/info/attributes
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
pip3 install -r requirements-dev.txt
|
||||
|
||||
- name: Run qmk formatters
|
||||
shell: 'bash {0}'
|
||||
run: |
|
||||
qmk format-c -a
|
||||
qmk format-python -a
|
||||
qmk format-text -a
|
||||
git diff
|
||||
|
||||
- uses: rlespinasse/github-slug-action@v3.x
|
||||
|
||||
- name: Become QMK Bot
|
||||
run: |
|
||||
git config user.name 'QMK Bot'
|
||||
git config user.email 'hello@qmk.fm'
|
||||
|
||||
- name: Create Pull Request
|
||||
uses: peter-evans/create-pull-request@v5
|
||||
if: ${{ github.repository == 'qmk/qmk_firmware'}}
|
||||
with:
|
||||
token: ${{ secrets.QMK_BOT_TOKEN }}
|
||||
delete-branch: true
|
||||
branch: bugfix/format_${{ env.GITHUB_REF_SLUG }}
|
||||
author: QMK Bot <hello@qmk.fm>
|
||||
committer: QMK Bot <hello@qmk.fm>
|
||||
commit-message: Format code according to conventions
|
||||
title: '[CI] Format code according to conventions'
|
||||
18
.github/workflows/labeler.yml
vendored
18
.github/workflows/labeler.yml
vendored
@ -1,18 +0,0 @@
|
||||
name: "Pull Request Labeler"
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pull-requests: write
|
||||
|
||||
on:
|
||||
pull_request_target:
|
||||
types: [opened, synchronize, reopened, ready_for_review, locked]
|
||||
|
||||
jobs:
|
||||
triage:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/labeler@main
|
||||
with:
|
||||
repo-token: "${{ secrets.GITHUB_TOKEN }}"
|
||||
configuration-path: '.github/labeler.yml'
|
||||
83
.github/workflows/lint.yml
vendored
83
.github/workflows/lint.yml
vendored
@ -1,83 +0,0 @@
|
||||
name: PR Lint keyboards
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- 'keyboards/**'
|
||||
|
||||
jobs:
|
||||
lint:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
container: ghcr.io/qmk/qmk_cli
|
||||
|
||||
steps:
|
||||
- name: Disable safe.directory check
|
||||
run : git config --global --add safe.directory '*'
|
||||
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Install dependencies
|
||||
run: pip3 install -r requirements-dev.txt
|
||||
|
||||
- name: Get changed files
|
||||
id: file_changes
|
||||
uses: tj-actions/changed-files@v39
|
||||
|
||||
- name: Print info
|
||||
run: |
|
||||
git rev-parse --short HEAD
|
||||
echo ${{ github.event.pull_request.base.sha }}
|
||||
echo '${{ steps.file_changes.outputs.all_changed_files}}'
|
||||
|
||||
- name: Run qmk lint
|
||||
if: always()
|
||||
shell: 'bash {0}'
|
||||
run: |
|
||||
QMK_CHANGES=$(echo -e '${{ steps.file_changes.outputs.all_changed_files}}' | sed 's/ /\n/g')
|
||||
QMK_KEYBOARDS=$(qmk list-keyboards)
|
||||
|
||||
exit_code=0
|
||||
|
||||
for KB in $QMK_KEYBOARDS; do
|
||||
KEYBOARD_CHANGES=$(echo "$QMK_CHANGES" | grep -E '^(keyboards/'${KB}'/)')
|
||||
if [[ -z "$KEYBOARD_CHANGES" ]]; then
|
||||
# skip as no changes for this keyboard
|
||||
continue
|
||||
fi
|
||||
|
||||
KEYMAP_ONLY=$(echo "$KEYBOARD_CHANGES" | grep -cv /keymaps/)
|
||||
if [[ $KEYMAP_ONLY -gt 0 ]]; then
|
||||
echo "linting ${KB}"
|
||||
|
||||
qmk lint --keyboard ${KB} && qmk info -l --keyboard ${KB}
|
||||
exit_code=$(($exit_code + $?))
|
||||
fi
|
||||
done
|
||||
|
||||
qmk format-text ${{ steps.file_changes.outputs.all_changed_files}} || true
|
||||
for file in ${{ steps.file_changes.outputs.all_changed_files}}; do
|
||||
if ! git diff --quiet $file; then
|
||||
echo "File '${file}' Requires Formatting"
|
||||
echo "::error file=${file}::Requires Formatting"
|
||||
exit_code=$(($exit_code + 1))
|
||||
fi
|
||||
done
|
||||
|
||||
if [[ $exit_code -gt 255 ]]; then
|
||||
exit 255
|
||||
fi
|
||||
exit $exit_code
|
||||
|
||||
- name: Verify keyboard aliases
|
||||
if: always()
|
||||
shell: 'bash {0}'
|
||||
run: |
|
||||
git reset --hard
|
||||
git clean -xfd
|
||||
qmk ci-validate-aliases
|
||||
36
.github/workflows/regen.yml
vendored
36
.github/workflows/regen.yml
vendored
@ -1,36 +0,0 @@
|
||||
name: PR Regenerate Files
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- 'data/constants/**'
|
||||
- 'lib/python/**'
|
||||
|
||||
jobs:
|
||||
regen:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
container: ghcr.io/qmk/qmk_cli
|
||||
|
||||
steps:
|
||||
- name: Disable safe.directory check
|
||||
run : git config --global --add safe.directory '*'
|
||||
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Run qmk generators
|
||||
run: |
|
||||
util/regen.sh
|
||||
git diff
|
||||
|
||||
- name: Fail when regeneration required
|
||||
run: |
|
||||
git diff
|
||||
for file in $(git diff --name-only); do
|
||||
echo "File '${file}' Requires Regeneration"
|
||||
echo "::error file=${file}::Requires Regeneration"
|
||||
done
|
||||
test -z "$(git diff --name-only)"
|
||||
46
.github/workflows/regen_push.yml
vendored
46
.github/workflows/regen_push.yml
vendored
@ -1,46 +0,0 @@
|
||||
name: Regenerate Files
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
- develop
|
||||
|
||||
jobs:
|
||||
regen:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
container: ghcr.io/qmk/qmk_cli
|
||||
|
||||
steps:
|
||||
- name: Disable safe.directory check
|
||||
run : git config --global --add safe.directory '*'
|
||||
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Run qmk generators
|
||||
run: |
|
||||
util/regen.sh
|
||||
git diff
|
||||
|
||||
- uses: rlespinasse/github-slug-action@v3.x
|
||||
|
||||
- name: Become QMK Bot
|
||||
run: |
|
||||
git config user.name 'QMK Bot'
|
||||
git config user.email 'hello@qmk.fm'
|
||||
|
||||
- name: Create Pull Request
|
||||
uses: peter-evans/create-pull-request@v5
|
||||
if: ${{ github.repository == 'qmk/qmk_firmware'}}
|
||||
with:
|
||||
token: ${{ secrets.QMK_BOT_TOKEN }}
|
||||
delete-branch: true
|
||||
branch: bugfix/regen_${{ env.GITHUB_REF_SLUG }}
|
||||
author: QMK Bot <hello@qmk.fm>
|
||||
committer: QMK Bot <hello@qmk.fm>
|
||||
commit-message: Regenerate Files
|
||||
title: '[CI] Regenerate Files'
|
||||
65
.github/workflows/stale.yml
vendored
65
.github/workflows/stale.yml
vendored
@ -1,65 +0,0 @@
|
||||
name: 'Close stale issues and PRs'
|
||||
|
||||
permissions:
|
||||
issues: write
|
||||
pull-requests: write
|
||||
|
||||
on:
|
||||
schedule:
|
||||
- cron: '30 1 * * *'
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
stale:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/stale@v8
|
||||
with:
|
||||
repo-token: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
remove-stale-when-updated: true
|
||||
exempt-draft-pr: true
|
||||
ascending: true
|
||||
operations-per-run: 150
|
||||
|
||||
stale-issue-label: stale
|
||||
days-before-issue-stale: 90
|
||||
days-before-issue-close: 30
|
||||
exempt-issue-labels: bug,in progress,on hold,discussion,to do
|
||||
|
||||
stale-issue-message: >
|
||||
This issue has been automatically marked as stale because it has not had activity in the
|
||||
last 90 days. It will be closed in the next 30 days unless it is tagged properly or other activity
|
||||
occurs.
|
||||
|
||||
For maintainers: Please label with `bug`, `in progress`, `on hold`, `discussion` or `to do` to prevent
|
||||
the issue from being re-flagged.
|
||||
|
||||
close-issue-message: >
|
||||
This issue has been automatically closed because it has not had activity in the last 30 days.
|
||||
If this issue is still valid, re-open the issue and let us know.
|
||||
|
||||
// [stale-action-closed]
|
||||
|
||||
stale-pr-label: stale
|
||||
days-before-pr-stale: 45
|
||||
days-before-pr-close: 30
|
||||
exempt-pr-labels: bug,awaiting review,breaking_change,in progress,on hold
|
||||
|
||||
stale-pr-message: >
|
||||
Thank you for your contribution!
|
||||
|
||||
This pull request has been automatically marked as stale because it has not had
|
||||
activity in the last 45 days. It will be closed in 30 days if no further activity occurs.
|
||||
Please feel free to give a status update now, or re-open when it's ready.
|
||||
|
||||
For maintainers: Please label with `bug`, `awaiting review`, `breaking_change`, `in progress`, or `on hold`
|
||||
to prevent the issue from being re-flagged.
|
||||
|
||||
close-pr-message: >
|
||||
Thank you for your contribution!
|
||||
|
||||
This pull request has been automatically closed because it has not had activity in the last 30 days.
|
||||
Please feel free to give a status update now, ping for review, or re-open when it's ready.
|
||||
|
||||
// [stale-action-closed]
|
||||
35
.github/workflows/unit_test.yml
vendored
35
.github/workflows/unit_test.yml
vendored
@ -1,35 +0,0 @@
|
||||
name: Unit Tests
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
- develop
|
||||
pull_request:
|
||||
paths:
|
||||
- 'builddefs/**'
|
||||
- 'quantum/**'
|
||||
- 'platforms/**'
|
||||
- 'tmk_core/**'
|
||||
- 'tests/**'
|
||||
- '*.mk'
|
||||
- 'Makefile'
|
||||
- '.github/workflows/unit_test.yml'
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
container: ghcr.io/qmk/qmk_cli
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
submodules: recursive
|
||||
- name: Install dependencies
|
||||
run: pip3 install -r requirements-dev.txt
|
||||
- name: Run tests
|
||||
run: make test:all
|
||||
6
.gitmodules
vendored
6
.gitmodules
vendored
@ -1,9 +1,3 @@
|
||||
[submodule "lib/lufa"]
|
||||
path = lib/lufa
|
||||
url = https://github.com/qmk/lufa
|
||||
[submodule "lib/vusb"]
|
||||
path = lib/vusb
|
||||
url = https://github.com/qmk/v-usb
|
||||
[submodule "lib/printf"]
|
||||
path = lib/printf
|
||||
url = https://github.com/qmk/printf
|
||||
|
||||
10
.vscode/extensions.json
vendored
10
.vscode/extensions.json
vendored
@ -1,10 +0,0 @@
|
||||
// Suggested extensions
|
||||
{
|
||||
"recommendations": [
|
||||
"EditorConfig.EditorConfig",
|
||||
"xaver.clang-format",
|
||||
"llvm-vs-code-extensions.vscode-clangd",
|
||||
"bierner.github-markdown-preview",
|
||||
"donjayamanne.git-extension-pack"
|
||||
]
|
||||
}
|
||||
34
.vscode/settings.json
vendored
34
.vscode/settings.json
vendored
@ -1,34 +0,0 @@
|
||||
// Place your settings in this file to overwrite default and user settings.
|
||||
{
|
||||
// Unofficially, QMK uses spaces for indentation
|
||||
"editor.insertSpaces": true,
|
||||
// Configure glob patterns for excluding files and folders.
|
||||
"files.exclude": {
|
||||
"**/.build": true,
|
||||
"**/*.hex": true,
|
||||
"**/*.bin": true,
|
||||
"**/*.uf2": true
|
||||
},
|
||||
"files.associations": {
|
||||
"*.h": "c",
|
||||
"*.c": "c",
|
||||
"*.inc": "c",
|
||||
"*.cpp": "cpp",
|
||||
"*.hpp": "cpp",
|
||||
"xstddef": "c",
|
||||
"type_traits": "c",
|
||||
"utility": "c",
|
||||
"ranges": "c"
|
||||
},
|
||||
"[markdown]": {
|
||||
"editor.trimAutoWhitespace": false,
|
||||
"files.trimTrailingWhitespace": false
|
||||
},
|
||||
"python.formatting.provider": "yapf",
|
||||
"[json]": {
|
||||
"editor.formatOnSave": false
|
||||
},
|
||||
"clangd.arguments": [
|
||||
"--header-insertion=never"
|
||||
]
|
||||
}
|
||||
@ -1,47 +0,0 @@
|
||||
# Quantum Mechanical Keyboard Firmware
|
||||
|
||||
<!---
|
||||
original document: 0.8.58:docs/README.md
|
||||
git diff 0.8.58 HEAD -- docs/README.md | cat
|
||||
-->
|
||||
|
||||
[](https://github.com/qmk/qmk_firmware/tags)
|
||||
[](https://discord.gg/Uq7gcHh)
|
||||
[](https://docs.qmk.fm)
|
||||
[](https://github.com/qmk/qmk_firmware/pulse/monthly)
|
||||
[](https://github.com/qmk/qmk_firmware/)
|
||||
|
||||
## QMK ファームウェアとは何でしょうか？
|
||||
|
||||
QMK (*Quantum Mechanical Keyboard*)は、コンピュータ入力デバイスの開発を中心としたオープンソースコミュニティです。コミュニティには、キーボード、マウス、MIDI デバイスなど、全ての種類の入力デバイスが含まれます。協力者の中心グループは、[QMK ファームウェア](https://github.com/qmk/qmk_firmware)、[QMK Configurator](https://config.qmk.fm)、[QMK ツールボックス](https://github.com/qmk/qmk_toolbox)、[qmk.fm](https://qmk.fm)、そして、このドキュメントを、あなたのようなコミュニティメンバーの助けを借りて保守しています。
|
||||
|
||||
## 始めましょう
|
||||
|
||||
QMK は初めてですか？始めるには2つの方法があります:
|
||||
|
||||
* 基本: [QMK Configurator](https://config.qmk.fm)
|
||||
* ドロップダウンからあなたのキーボードを選択し、キーボードをプログラムします。
|
||||
* 見ることができる [紹介ビデオ](https://www.youtube.com/watch?v=-imgglzDMdY) があります。
|
||||
* 読むことができる概要 [ドキュメント](ja/newbs_building_firmware_configurator.md) があります。
|
||||
* 発展: [ソースを使用します](ja/newbs.md)
|
||||
* より強力ですが、使うのはより困難です。
|
||||
|
||||
## 自分用にアレンジします
|
||||
|
||||
QMK には、探求すべき多くの[機能](ja/features.md)と、深く知るためのリファレンスドキュメントがたくさんあります。ほとんどの機能は[キーマップ](ja/keymap.md)を変更し、[キーコード](ja/keycodes.md)を変更することで活用されます。
|
||||
|
||||
## 手助けが必要ですか？
|
||||
|
||||
[サポートページ](ja/support.md) をチェックして、QMK の使い方について手助けを得る方法を確認してください。
|
||||
|
||||
## 貢献する
|
||||
|
||||
QMK コミュニティに貢献する方法はたくさんあります。始める最も簡単な方法は、それを使って友人に QMK という単語を広めることです。
|
||||
|
||||
* フォーラムやチャットルームで人々を支援します:
|
||||
* [/r/olkb](https://www.reddit.com/r/olkb/)
|
||||
* [Discord サーバ](https://discord.gg/Uq7gcHh)
|
||||
* 下にある「Edit This Page」をクリックしてドキュメントに貢献します
|
||||
* [ドキュメントをあなたの言語に翻訳します](ja/translating.md)
|
||||
* [バグを報告します](https://github.com/qmk/qmk_firmware/issues/new/choose)
|
||||
* [プルリクエストを開きます](ja/contributing.md)
|
||||
@ -1,181 +0,0 @@
|
||||
* チュートリアル
|
||||
* [入門](ja/newbs.md)
|
||||
* [セットアップ](ja/newbs_getting_started.md)
|
||||
* [初めてのファームウェアの構築](ja/newbs_building_firmware.md)
|
||||
* [ファームウェアのフラッシュ](ja/newbs_flashing.md)
|
||||
* [手助けを得る/サポート](ja/support.md)
|
||||
* [他のリソース](ja/newbs_learn_more_resources.md)
|
||||
* [シラバス](ja/syllabus.md)
|
||||
|
||||
* FAQ
|
||||
* [一般的な FAQ](ja/faq_general.md)
|
||||
* [QMK のビルド/コンパイル](ja/faq_build.md)
|
||||
* [QMK のデバッグ](ja/faq_debug.md)
|
||||
* [QMK のトラブルシューティング](ja/faq_misc.md)
|
||||
* [キーマップ FAQ](ja/faq_keymap.md)
|
||||
* [用語](ja/reference_glossary.md)
|
||||
|
||||
* Configurator
|
||||
* [概要](ja/newbs_building_firmware_configurator.md)
|
||||
* [ステップ・バイ・ステップ](ja/configurator_step_by_step.md)
|
||||
* [トラブルシューティング](ja/configurator_troubleshooting.md)
|
||||
* QMK API
|
||||
* [概要](ja/api_overview.md)
|
||||
* [API ドキュメント](ja/api_docs.md)
|
||||
* [キーボードサポート](ja/reference_configurator_support.md)
|
||||
* [デフォルトキーマップの追加](ja/configurator_default_keymaps.md)
|
||||
|
||||
* CLI
|
||||
* [概要](ja/cli.md)
|
||||
* [設定](ja/cli_configuration.md)
|
||||
* [コマンド](ja/cli_commands.md)
|
||||
* [Tab 補完](ja/cli_tab_complete.md)
|
||||
|
||||
* QMK を使う
|
||||
* ガイド
|
||||
* [機能のカスタマイズ](ja/custom_quantum_functions.md)
|
||||
* [Zadig を使ったドライバのインストール](ja/driver_installation_zadig.md)
|
||||
* [キーマップの概要](ja/keymap.md)
|
||||
* 開発環境
|
||||
* [Docker のガイド](ja/getting_started_docker.md)
|
||||
* 書き込み
|
||||
* [書き込み](ja/flashing.md)
|
||||
* [ATmega32A の書き込み (ps2avrgb)](ja/flashing_bootloadhid.md)
|
||||
* IDE
|
||||
* [QMK での Eclipse の使用](ja/other_eclipse.md)
|
||||
* [QMK での VSCode の使用](ja/other_vscode.md)
|
||||
* Git のベストプラクティス
|
||||
* [入門](ja/newbs_git_best_practices.md)
|
||||
* [フォーク](ja/newbs_git_using_your_master_branch.md)
|
||||
* [マージの競合の解決](ja/newbs_git_resolving_merge_conflicts.md)
|
||||
* [ブランチの修正](ja/newbs_git_resynchronize_a_branch.md)
|
||||
* キーボードを作る
|
||||
* [Hand Wiring ガイド](ja/hand_wire.md)
|
||||
* [ISP 書き込みガイド](ja/isp_flashing_guide.md)
|
||||
|
||||
* 単純なキーコード
|
||||
* [完全なリスト](ja/keycodes.md)
|
||||
* [基本的なキーコード](ja/keycodes_basic.md)
|
||||
* [言語固有のキーコード](ja/reference_keymap_extras.md)
|
||||
* [修飾キー](ja/feature_advanced_keycodes.md)
|
||||
* [Quantum キーコード](ja/quantum_keycodes.md)
|
||||
|
||||
* 高度なキーコード
|
||||
* [コマンド](ja/feature_command.md)
|
||||
* [動的マクロ](ja/feature_dynamic_macros.md)
|
||||
* [グレイブ エスケープ](ja/feature_grave_esc.md)
|
||||
* [リーダーキー](ja/feature_leader_key.md)
|
||||
* [モッドタップ](ja/mod_tap.md)
|
||||
* [マクロ](ja/feature_macros.md)
|
||||
* [マウスキー](ja/feature_mouse_keys.md)
|
||||
* [Repeat Key](ja/feature_repeat_key.md)
|
||||
* [Space Cadet Shift](ja/feature_space_cadet.md)
|
||||
* [US ANSI シフトキー](ja/keycodes_us_ansi_shifted.md)
|
||||
|
||||
* ソフトウェア機能
|
||||
* [自動シフト](ja/feature_auto_shift.md)
|
||||
* [コンボ](ja/feature_combo.md)
|
||||
* [デバウンス API](ja/feature_debounce_type.md)
|
||||
* [キーロック](ja/feature_key_lock.md)
|
||||
* [レイヤー](ja/feature_layers.md)
|
||||
* [ワンショットキー](ja/one_shot_keys.md)
|
||||
* [ポインティング デバイス](ja/feature_pointing_device.md)
|
||||
* [ロー HID](ja/feature_rawhid.md)
|
||||
* [シーケンサー](ja/feature_sequencer.md)
|
||||
* [スワップハンド](ja/feature_swap_hands.md)
|
||||
* [タップダンス](ja/feature_tap_dance.md)
|
||||
* [タップホールド設定](ja/tap_hold.md)
|
||||
* [ユニコード](ja/feature_unicode.md)
|
||||
* [ユーザスペース](ja/feature_userspace.md)
|
||||
* [WPM 計算](ja/feature_wpm.md)
|
||||
|
||||
* ハードウェア機能
|
||||
* 表示
|
||||
* [HD44780 LCD コントローラ](ja/feature_hd44780.md)
|
||||
* [OLED ドライバ](ja/feature_oled_driver.md)
|
||||
* 電飾
|
||||
* [バックライト](ja/feature_backlight.md)
|
||||
* [LED マトリックス](ja/feature_led_matrix.md)
|
||||
* [RGB ライト](ja/feature_rgblight.md)
|
||||
* [RGB マトリックス](ja/feature_rgb_matrix.md)
|
||||
* [オーディオ](ja/feature_audio.md)
|
||||
* [Bluetooth](ja/feature_bluetooth.md)
|
||||
* [ブートマジック](ja/feature_bootmagic.md)
|
||||
* [カスタムマトリックス](ja/custom_matrix.md)
|
||||
* [DIP スイッチ](ja/feature_dip_switch.md)
|
||||
* [エンコーダ](ja/feature_encoders.md)
|
||||
* [触覚フィードバック](ja/feature_haptic_feedback.md)
|
||||
* [ジョイスティック](ja/feature_joystick.md)
|
||||
* [LED インジケータ](ja/feature_led_indicators.md)
|
||||
* [Proton C 変換](ja/proton_c_conversion.md)
|
||||
* [PS/2 マウス](ja/feature_ps2_mouse.md)
|
||||
* [分割キーボード](ja/feature_split_keyboard.md)
|
||||
* [速記](ja/feature_stenography.md)
|
||||
* [感熱式プリンタ](ja/feature_thermal_printer.md)
|
||||
* [Velocikey](ja/feature_velocikey.md)
|
||||
|
||||
* QMK の開発
|
||||
* [PR チェックリスト](ja/pr_checklist.md)
|
||||
* 互換性を破る変更/Breaking changes
|
||||
* [概要](ja/breaking_changes.md)
|
||||
* [プルリクエストにフラグが付けられた](ja/breaking_changes_instructions.md)
|
||||
* [最近の変更履歴](ChangeLog/20210227.md "QMK v0.12.0 - 2021 Feb 27")
|
||||
* [過去の互換性を破る変更](ja/breaking_changes_history.md)
|
||||
|
||||
* C 開発
|
||||
* [ARM デバッグ ガイド](ja/arm_debugging.md)
|
||||
* [AVR プロセッサ](ja/hardware_avr.md)
|
||||
* [コーディング規約](ja/coding_conventions_c.md)
|
||||
* [互換性のあるマイクロコントローラ](ja/compatible_microcontrollers.md)
|
||||
* [ドライバ](ja/hardware_drivers.md)
|
||||
* [ADC ドライバ](ja/adc_driver.md)
|
||||
* [オーディオドライバ](ja/audio_driver.md)
|
||||
* [I2C ドライバ](ja/i2c_driver.md)
|
||||
* [SPI ドライバ](ja/spi_driver.md)
|
||||
* [WS2812 ドライバ](ja/ws2812_driver.md)
|
||||
* [EEPROM ドライバ](ja/eeprom_driver.md)
|
||||
* [シリアル ドライバ](ja/serial_driver.md)
|
||||
* [UART ドライバ](ja/uart_driver.md)
|
||||
* [GPIO 制御](ja/gpio_control.md)
|
||||
* [キーボード ガイドライン](ja/hardware_keyboard_guidelines.md)
|
||||
|
||||
* Python 開発
|
||||
* [コーディング規約](ja/coding_conventions_python.md)
|
||||
* [QMK CLI 開発](ja/cli_development.md)
|
||||
|
||||
* Configurator 開発
|
||||
* QMK API
|
||||
* [開発環境](ja/api_development_environment.md)
|
||||
* [アーキテクチャの概要](ja/api_development_overview.md)
|
||||
|
||||
* ハードウェアプラットフォーム開発
|
||||
* Arm/ChibiOS
|
||||
* [MCU の選択](ja/platformdev_selecting_arm_mcu.md)
|
||||
* [早期初期化](ja/platformdev_chibios_earlyinit.md)
|
||||
|
||||
* QMK Reference
|
||||
* [QMK への貢献](ja/contributing.md)
|
||||
* [QMK ドキュメントの翻訳](ja/translating.md)
|
||||
* [設定オプション](ja/config_options.md)
|
||||
* [データ駆動型コンフィギュレーション](ja/data_driven_config.md)
|
||||
* [Make ドキュメント](ja/getting_started_make_guide.md)
|
||||
* [ドキュメント ベストプラクティス](ja/documentation_best_practices.md)
|
||||
* [ドキュメント テンプレート](ja/documentation_templates.md)
|
||||
* [コミュニティレイアウト](ja/feature_layouts.md)
|
||||
* [ユニットテスト](ja/unit_testing.md)
|
||||
* [便利な関数](ja/ref_functions.md)
|
||||
* [info.json 形式](ja/reference_info_json.md)
|
||||
|
||||
* より深く知るために
|
||||
* [キーボードがどのように動作するか](ja/how_keyboards_work.md)
|
||||
* [マトリックスがどのように動作するか](ja/how_a_matrix_works.md)
|
||||
* [QMK を理解する](ja/understanding_qmk.md)
|
||||
|
||||
* QMK の内部詳細(作成中)
|
||||
* [定義](ja/internals/defines.md)
|
||||
* [入力コールバック登録](ja/internals/input_callback_reg.md)
|
||||
* [Midi デバイス](ja/internals/midi_device.md)
|
||||
* [Midi デバイスのセットアップ手順](ja/internals/midi_device_setup_process.md)
|
||||
* [Midi ユーティリティ](ja/internals/midi_util.md)
|
||||
* [Midi 送信関数](ja/internals/send_functions.md)
|
||||
* [Sysex Tools](ja/internals/sysex_tools.md)
|
||||
@ -1,155 +0,0 @@
|
||||
# ADC ドライバ
|
||||
|
||||
<!---
|
||||
original document: 0.10.52:docs/adc_driver.md
|
||||
git diff 0.10.52 HEAD -- docs/adc_driver.md | cat
|
||||
-->
|
||||
|
||||
QMK は対応している MCU のアナログ・デジタルコンバータ（ADC) を使用し、特定のピンの電圧を計測することができます。この機能はデジタル出力の[ロータリーエンコーダ](ja/feature_encoders.md)などではなく、アナログ計測が必要な可変抵抗器を使用したボリュームコントロールや Bluetooth キーボードのバッテリー残量表示などの実装に役立ちます。
|
||||
|
||||
このドライバは現在 AVR と一部の ARM デバイスをサポートしています。返される値は 0V と VCC (通常 AVR の場合は 5V または 3.3V、ARM の場合は 3.3V)の間でマッピングされた 10ビットの整数 (0-1023) ですが、ARM の場合、もしもより精度が必要であれば `#define` を使うと操作をより柔軟に制御できます。
|
||||
|
||||
## 使い方
|
||||
|
||||
このドライバを使うには、`rules.mk` に以下を追加します:
|
||||
|
||||
```make
|
||||
SRC += analog.c
|
||||
```
|
||||
|
||||
そして、コードの先頭に以下の include を置きます:
|
||||
|
||||
```c
|
||||
#include "analog.h"
|
||||
```
|
||||
|
||||
## チャンネル
|
||||
|
||||
### AVR
|
||||
|
||||
|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328/P|
|
||||
|-------|-------------|-------------|---------|-----------|
|
||||
|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>\* ATmega328/P には余分な2つの ADC チャンネルがありますが、DIP ピンアウトには存在せず、GPIO ピンとは共有されません。これらに直接アクセスするために、`adc_read()` を使えます。
|
||||
|
||||
### ARM
|
||||
|
||||
これらのピンの一部は同じチャンネルを使って ADC 上でダブルアップされることに注意してください。これは、これらのピンがどちらかの ADC に使われる可能性があるからです。
|
||||
|
||||
また、F0 と F3 は異なるナンバリングスキーマを使うことに注意してください。F0 には1つの ADC があり、チャンネルは0から始まるインデックスですが、F3 には4つの ADC があり、チャンネルは1から始まるインデックスです。これは、F0 が ADC の `ADCv1` 実装を使用するのに対し、F3 が `ADCv3` 実装を使用するためです。
|
||||
|
||||
|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 | | |
|
||||
|
||||
## 関数
|
||||
|
||||
### AVR
|
||||
|
||||
|関数 |説明 |
|
||||
|----------------------------|------------------------------------------------------------------------------------------------------------------------------------|
|
||||
|`analogReference(mode)` |アナログの電圧リファレンスソースを設定する。`ADC_REF_EXTERNAL`、`ADC_REF_POWER`、`ADC_REF_INTERNAL` のいずれかでなければなりません。|
|
||||
|`analogReadPin(pin)` |指定されたピンから値を読み取ります。例えば、ATmega32U4 の ADC6 の場合 `F6`。 |
|
||||
|`pinToMux(pin)` |指定されたピンを mux 値に変換します。サポートされていないピンが指定された場合、"0V (GND)" の mux 値を返します。 |
|
||||
|`adc_read(mux)` |指定された mux に従って ADC から値を読み取ります。詳細は、MCU のデータシートを見てください。 |
|
||||
|
||||
### ARM
|
||||
|
||||
|関数 |説明 |
|
||||
|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
|`analogReadPin(pin)` |指定されたピンから値を読み取ります。STM32F0 では チャンネル 0 の `A0`、STM32F3 ではチャンネル 1 の ADC1。ピンを複数の ADC に使える場合は、この関数のために番号の小さい ADC が選択されることに注意してください。例えば、`C0` は、ADC2 にも使える場合、ADC1 のチャンネル 6 になります。 |
|
||||
|`analogReadPinAdc(pin, adc)`|指定されたピンと ADC から値を読み取ります。例えば、`C0, 1` は、ADC1 ではなく ADC2 のチャンネル 6 から読み取ります。この関数では、ADC はインデックス 0 から始まることに注意してください。 |
|
||||
|`pinToMux(pin)` |指定されたピンをチャンネルと ADC の組み合わせに変換します。サポートされていないピンが指定された場合、"0V (GND)" の mux 値を返します。 |
|
||||
|`adc_read(mux)` |指定されたピンと ADC の組み合わせに応じて ADC から値を読み取ります。詳細は、MCU のデータシートを見てください。 |
|
||||
|
||||
## 設定
|
||||
|
||||
## ARM
|
||||
|
||||
ADC の ARM 実装には、独自のキーボードとキーマップでオーバーライドして動作方法を変更できる幾つかの追加オプションがあります。利用可能なオプションの詳細については、特定のマイクロコントローラについて ChibiOS の対応する `hal_adc_lld.h` を調べてください。
|
||||
|
||||
|`#define` |型 |既定値 |説明 |
|
||||
|---------------------|------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
|`ADC_CIRCULAR_BUFFER`|`bool`|`false` |`true` の場合、この実装は循環バッファを使います。 |
|
||||
|`ADC_NUM_CHANNELS` |`int` |`1` |ADC 動作の一部としてスキャンされるチャンネル数を設定します。現在の実装は `1` のみをサポートします。 |
|
||||
|`ADC_BUFFER_DEPTH` |`int` |`2` |各結果の深さを設定します。デフォルトでは12ビットの結果しか取得できないため、これを2バイトに設定して1つの値を含めることができます。8ビット以下の結果を選択した場合は、これを 1 に設定できます。 |
|
||||
|`ADC_SAMPLING_RATE` |`int` |`ADC_SMPR_SMP_1P5` |ADC のサンプリングレートを設定します。デフォルトでは、最も速い設定に設定されています。 |
|
||||
|`ADC_RESOLUTION` |`int` |`ADC_CFGR1_RES_12BIT`|結果の分解能。デフォルトでは12ビットを選択しますが、12、10、8、6ビットを選択できます。 |
|
||||
@ -1,8 +0,0 @@
|
||||
# 開発環境のセットアップ
|
||||
|
||||
<!---
|
||||
original document: 0.9.50:docs/api_development_environment.md
|
||||
git diff 0.9.50 HEAD -- docs/api_development_environment.md | cat
|
||||
-->
|
||||
|
||||
開発環境をセットアップするには、[qmk_web_stack](https://github.com/qmk/qmk_web_stack) に行ってください。
|
||||
@ -1,49 +0,0 @@
|
||||
# QMK コンパイラ開発ガイド
|
||||
|
||||
<!---
|
||||
original document: 0.9.50:docs/api_development_overview.md
|
||||
git diff 0.9.50 HEAD -- docs/api_development_overview.md | cat
|
||||
-->
|
||||
|
||||
このページでは、開発者に QMK コンパイラを紹介しようと思います。コードを読まなければならないような核心となる詳細に立ち入って調べることはしません。ここで得られるものは、コードを読んで理解を深めるためのフレームワークです。
|
||||
|
||||
# 概要
|
||||
|
||||
QMK Compile API は、いくつかの可動部分からできています:
|
||||
|
||||
|
||||
|
||||
API クライアントは API サービスと排他的にやりとりをします。ここでジョブをサブミットし、状態を調べ、結果をダウンロードします。API サービスはコンパイルジョブを [Redis Queue](https://python-rq.org) に挿入し、それらのジョブの結果について RQ と S3 の両方を調べます。
|
||||
|
||||
ワーカーは RQ から新しいコンパイルジョブを取り出し、ソースとバイナリを S3 互換のストレージエンジンにアップロードします。
|
||||
|
||||
# ワーカー
|
||||
|
||||
QMK コンパイラワーカーは実際のビルド作業に責任を持ちます。ワーカーは RQ からジョブを取り出し、ジョブを完了するためにいくつかの事を行います:
|
||||
|
||||
* 新しい qmk_firmware のチェックアウトを作成する
|
||||
* 指定されたレイヤーとキーボードメタデータを使って `keymap.c` をビルドする
|
||||
* ファームウェアをビルドする
|
||||
* ソースのコピーを zip 形式で圧縮する
|
||||
* ファームウェア、ソースの zip ファイル、メタデータファイルを S3 にアップロードする
|
||||
* ジョブの状態を RQ に送信する
|
||||
|
||||
# API サービス
|
||||
|
||||
API サービスは比較的単純な Flask アプリケーションです。理解しておくべきことが幾つかあります。
|
||||
|
||||
## @app.route('/v1/compile', methods=['POST'])
|
||||
|
||||
これは API の主なエントリーポイントです。クライアントとのやりとりはここから開始されます。クライアントはキーボードを表す JSON ドキュメントを POST し、API はコンパイルジョブをサブミットする前にいくらかの(とても)基本的な検証を行います。
|
||||
|
||||
## @app.route('/v1/compile/<string:job_id>', methods=['GET'])
|
||||
|
||||
これは最もよく呼ばれるエンドポイントです。ジョブの詳細が redis から利用可能であればそれを取り出し、そうでなければ S3 からキャッシュされたジョブの詳細を取り出します。
|
||||
|
||||
## @app.route('/v1/compile/<string:job_id>/download', methods=['GET'])
|
||||
|
||||
このメソッドによりユーザはコンパイルされたファームウェアファイルをダウンロードすることができます。
|
||||
|
||||
## @app.route('/v1/compile/<string:job_id>/source', methods=['GET'])
|
||||
|
||||
このメソッドによりユーザはファームウェアのソースをダウンロードすることができます。
|
||||
@ -1,73 +0,0 @@
|
||||
# QMK API
|
||||
|
||||
<!---
|
||||
original document: 0.13.15:docs/api_docs.md
|
||||
git diff 0.13.15 HEAD -- docs/api_docs.md | cat
|
||||
-->
|
||||
|
||||
このページは QMK API の使い方を説明します。もしあなたがアプリケーション開発者であれば、全ての [QMK](https://qmk.fm) キーボードのファームウェアをコンパイルするために、この API を使うことができます。
|
||||
|
||||
## 概要
|
||||
|
||||
このサービスは、カスタムキーマップをコンパイルするための非同期 API です。API に 何らかの JSON を POST し、定期的に状態をチェックし、ファームウェアのコンパイルが完了していれば、結果のファームウェアと(もし希望すれば)そのファームウェアのソースコードをダウンロードすることができます。
|
||||
|
||||
#### JSON ペイロードの例:
|
||||
|
||||
```json
|
||||
{
|
||||
"keyboard": "clueboard/66/rev2",
|
||||
"keymap": "my_awesome_keymap",
|
||||
"layout": "LAYOUT_all",
|
||||
"layers": [
|
||||
["KC_GRV","KC_1","KC_2","KC_3","KC_4","KC_5","KC_6","KC_7","KC_8","KC_9","KC_0","KC_MINS","KC_EQL","KC_GRV","KC_BSPC","KC_PGUP","KC_TAB","KC_Q","KC_W","KC_E","KC_R","KC_T","KC_Y","KC_U","KC_I","KC_O","KC_P","KC_LBRC","KC_RBRC","KC_BSLS","KC_PGDN","KC_CAPS","KC_A","KC_S","KC_D","KC_F","KC_G","KC_H","KC_J","KC_K","KC_L","KC_SCLN","KC_QUOT","KC_NUHS","KC_ENT","KC_LSFT","KC_NUBS","KC_Z","KC_X","KC_C","KC_V","KC_B","KC_N","KC_M","KC_COMM","KC_DOT","KC_SLSH","KC_RO","KC_RSFT","KC_UP","KC_LCTL","KC_LGUI","KC_LALT","KC_MHEN","KC_SPC","KC_SPC","KC_HENK","KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"],
|
||||
["KC_ESC","KC_F1","KC_F2","KC_F3","KC_F4","KC_F5","KC_F6","KC_F7","KC_F8","KC_F9","KC_F10","KC_F11","KC_F12","KC_TRNS","KC_DEL","BL_STEP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","_______","KC_TRNS","KC_PSCR","KC_SCRL","KC_PAUS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_PGUP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_LEFT","KC_PGDN","KC_RGHT"],
|
||||
["KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","QK_BOOT","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_TRNS","KC_TRNS","KC_TRNS"]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
ご覧のとおり、ペイロードにはファームウェアを作成および生成するために必要なキーボードの全ての側面を記述します。各レイヤーは QMK キーコードの1つのリストで、キーボードの `LAYOUT` マクロと同じ長さです。もしキーボードが複数の `LAYOUT` マクロをサポートする場合、どのマクロを使うかを指定することができます。
|
||||
|
||||
## コンパイルジョブのサブミット
|
||||
|
||||
キーマップをファームウェアにコンパイルするには、単純に JSON を `/v1/compile` エンドポイントに POST します。以下の例では、JSON ペイロードを `json_data` という名前のファイルに配置しています。
|
||||
|
||||
```
|
||||
$ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" https://api.qmk.fm/v1/compile
|
||||
{
|
||||
"enqueued": true,
|
||||
"job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6"
|
||||
}
|
||||
```
|
||||
|
||||
## 状態のチェック
|
||||
|
||||
キーマップをサブミットした後で、簡単な HTTP GET 呼び出しを使って状態をチェックすることができます:
|
||||
|
||||
```
|
||||
$ curl https://api.qmk.fm/v1/compile/ea1514b3-bdfc-4a7b-9b5c-08752684f7f6
|
||||
{
|
||||
"created_at": "Sat, 19 Aug 2017 21:39:12 GMT",
|
||||
"enqueued_at": "Sat, 19 Aug 2017 21:39:12 GMT",
|
||||
"id": "f5f9b992-73b4-479b-8236-df1deb37c163",
|
||||
"status": "running",
|
||||
"result": null
|
||||
}
|
||||
```
|
||||
|
||||
これは、ジョブをキューに入れることに成功し、現在実行中であることを示しています。5つの状態がありえます:
|
||||
|
||||
* **failed**: なんらかの理由でコンパイルサービスが失敗しました。
|
||||
* **finished**: コンパイルが完了し、結果を見るには `result` をチェックする必要があります。
|
||||
* **queued**: キーマップはコンパイルサーバが利用可能になるのを待っています。
|
||||
* **running**: コンパイルが進行中で、まもなく完了するはずです。
|
||||
* **unknown**: 深刻なエラーが発生し、[バグを報告](https://github.com/qmk/qmk_compiler/issues)する必要があります。
|
||||
|
||||
## 完了した結果を検証
|
||||
|
||||
コンパイルジョブが完了したら、`result` キーをチェックします。このキーの値は幾つかの情報を含むハッシュです:
|
||||
|
||||
* `firmware_binary_url`: 書き込み可能なファームウェアの URL のリスト
|
||||
* `firmware_keymap_url`: `keymap.c` の URL のリスト
|
||||
* `firmware_source_url`: ファームウェアの完全なソースコードの URL のリスト
|
||||
* `output`: このコンパイルジョブの stdout と stderr。エラーはここで見つけることができます。
|
||||
@ -1,20 +0,0 @@
|
||||
# QMK API
|
||||
|
||||
<!---
|
||||
original document: 0.13.15:docs/api_overview.md
|
||||
git diff 0.13.15 HEAD -- docs/api_overview.md | cat
|
||||
-->
|
||||
|
||||
QMK API は、Web と GUI ツールが [QMK](https://qmk.fm/) によってサポートされるキーボード用の任意のキーマップをコンパイルするために使うことができる、非同期 API を提供します。標準のキーマップテンプレートは、C コードのサポートを必要としない全ての QMK キーコードをサポートします。キーボードのメンテナは独自のカスタムテンプレートを提供して、より多くの機能を実現することができます。
|
||||
|
||||
## アプリケーション開発者
|
||||
|
||||
もしあなたがアプリケーションでこの API を使うことに興味があるアプリケーション開発者であれば、[API の使用](ja/api_docs.md) に行くべきです。
|
||||
|
||||
## キーボードのメンテナ
|
||||
|
||||
もし QMK Compiler API でのあなたのキーボードのサポートを強化したい場合は、[キーボードサポート](ja/reference_configurator_support.md) の節に行くべきです。
|
||||
|
||||
## バックエンド開発者
|
||||
|
||||
もし API 自体に取り組むことに興味がある場合は、[開発環境](ja/api_development_environment.md)のセットアップから始め、それから [API のハッキング](ja/api_development_overview.md) を調べるべきです。
|
||||
@ -1,92 +0,0 @@
|
||||
# Eclipse を使った ARM デバッグ
|
||||
|
||||
<!---
|
||||
original document: 0.8.58:docs/arm_debugging.md
|
||||
git diff 0.8.58 HEAD -- docs/arm_debugging.md | cat
|
||||
-->
|
||||
|
||||
このページでは、SWD アダプタとオープンソース/フリーツールを使って ARM MCU をデバッグするためのセットアップ方法について説明します。このガイドでは、GNU MCU Eclipse IDE for C/C++ Developers および OpenOCD を必要な依存関係と一緒にインストールします。
|
||||
|
||||
このガイドは上級者向けであり、あなたのマシンで、MAKE フローを使って、ARM 互換キーボードをコンパイルできることを前提にしています。
|
||||
|
||||
## ソフトウェアのインストール
|
||||
|
||||
ここでの主な目的は MCU Eclipse IDE を正しくマシンにインストールすることです。必要な手順は[この](https://gnu-mcu-eclipse.github.io/install/)インストールガイドから派生しています。
|
||||
|
||||
### xPack マネージャ
|
||||
|
||||
このツールはソフトウェアパッケージマネージャであり、必要な依存関係を取得するために使われます。
|
||||
|
||||
XPM は Node.js を使って実行されるため、[ここ](https://nodejs.org/en/)から取得してください。インストール後に、ターミナルを開き `npm -v` と入力します。バージョン番号が返ってくるとインストールは成功です。
|
||||
|
||||
XPM のインストール手順は[ここ](https://www.npmjs.com/package/xpm)で見つけることができ、OS 固有のものです。ターミナルに `xpm --version` と入力すると、ソフトウェアのバージョンが返ってくるはずです。
|
||||
|
||||
### ARM ツールチェーン
|
||||
|
||||
XPM を使うと、ARM ツールチェーンをとても簡単にインストールできます。`xpm install --global @xpack-dev-tools/arm-none-eabi-gcc` とコマンドを入力します。
|
||||
|
||||
### Windows ビルドツール
|
||||
|
||||
Windows を使っている場合は、これをインストールする必要があります！
|
||||
|
||||
`xpm install --global @gnu-mcu-eclipse/windows-build-tools`
|
||||
|
||||
### プログラマ/デバッガドライバ
|
||||
|
||||
プログラマのドライバをインストールします。このチュートリアルはほとんどどこでも入手できる ST-Link v2 を使って作成されました。
|
||||
ST-Link を持っている場合は、ドライバは[ここ](https://www.st.com/en/development-tools/stsw-link009.html)で見つけることができます。そうでない場合はツールの製造元にお問い合わせください。
|
||||
|
||||
### OpenOCD
|
||||
|
||||
この依存関係により、SWD は GDB からアクセスでき、デバッグに不可欠です。`xpm install --global @xpack-dev-tools/openocd` を実行します。
|
||||
|
||||
### Java
|
||||
|
||||
Java は Eclipse で必要とされるため、[ここ](https://www.oracle.com/technetwork/java/javase/downloads/index.html)からダウンロードしてください。
|
||||
|
||||
### GNU MCU Eclipse IDE
|
||||
|
||||
最後に IDE をインストールする番です。[ここ](https://github.com/gnu-mcu-eclipse/org.eclipse.epp.packages/releases/)のリリースページから最新バージョンを取得します。
|
||||
|
||||
## Eclipse の設定
|
||||
|
||||
ダウンロードした Eclipse IDE を開きます。QMK ディレクトリをインポートするために、File -> Import -> C/C++ -> Existing Code as Makefile Project を選択します。Next を選択し、Browse を使用して QMK フォルダを選択します。tool-chain リストから ARM Cross GCC を選択し、Finish を選択します。
|
||||
|
||||
これで、左側に QMK フォルダが表示されます。右クリックして、Properties を選択します。左側で MCU を展開し、ARM Toolchains Paths を選択します。xPack を押して OK を押します。OpenOCD Path で同じことを繰り返し、Windows の場合は、Build Tools Path でも同じことを繰り返します。Apply and Close を選択します。
|
||||
|
||||
ここで、必要な MCU パッケージをインストールします。Window -> Perspective -> Open Perspective -> Other... -> Packs を選択して、Packs perspective に移動します。Packs タブの横にある黄色のリフレッシュ記号を選択します。これは様々な場所から MCU の定義を要求するため、時間が掛かります。一部のリンクが失敗した場合は、おそらく Ignore を選択できます。
|
||||
|
||||
これが終了すると、ビルドやデバッグする MCU を見つけることができるはずです。この例では、STM32F3 シリーズの MCU を使います。左側で、STMicroelectronics -> STM32F3 Series を選択します。中央のウィンドウに、pack が表示されます。右クリックし、Install を選択します。それが終了したら、Window -> Perspective -> Open Perspective -> Other... -> C/C++ を選択してデフォルトのパースペクティブに戻ることができます。
|
||||
|
||||
Eclipse に QMK をビルドしようとするデバイスを教える必要があります。QMK フォルダを右クリック -> Properties -> C/C++ Build -> Settings を選択します。Devices タブを選択し、Devices の下から MCU の適切な種類を選択します。私の例では、STM32F303CC です。
|
||||
|
||||
この間に、Build コマンドもセットアップしましょう。C/C++ Build を選択し、Behavior タブを選択します。Build コマンドのところで、`all` を必要な make コマンドに置き換えます。例えば、rev6 Planck の default キーマップの場合、これは `planck/rev6:default` になります。Apply and Close を選択します。
|
||||
|
||||
## ビルド
|
||||
|
||||
全て正しくセットアップできていれば、ハンマーボタンを押すとファームウェアがビルドされ、.bin ファイルが出力されるはずです。
|
||||
|
||||
## デバッグ
|
||||
|
||||
### デバッガの接続
|
||||
|
||||
ARM MCU は、クロック信号(SWCLK) とデータ信号(SWDIO) で構成される Single Wire Debug (SWD) プロトコルを使います。MCU を完全に操作するには、この2本のワイヤとグラウンドを接続するだけで十分です。ここでは、キーボードは USB を介して電力が供給されると想定しています。手動でリセットボタンを使えるため、RESET 信号は必要ありません。より高度なセットアップのために printf と scanf をホストに非同期にパイプする SWO 信号を使用できますが、私たちのセットアップでは無視します。
|
||||
|
||||
注意: SWCLK と SWDIO ピンがキーボードのマトリックスで使われていないことを確認してください。もし使われている場合は、一時的に他のピンに切り替えることができます。
|
||||
|
||||
### デバッガの設定
|
||||
|
||||
QMK フォルダを右クリックし、Debug As -> Debug Configurations... を選択します。ここで、GDB OpenOCD Debugging をダブルクリックします。Debugger タブを選択し、MCU に必要な設定を入力します。これを見つけるにはいじったりググったりする必要があるかもしれません。STM32F3 用のデフォルトスクリプトは `stm32f3discovery.cfg` と呼ばれます。OpenOCD に伝えるには、Config options で `-f board/stm32f3discovery.cfg` と入力します。
|
||||
|
||||
注意: 私の場合、この設定スクリプトはリセット操作を無効にするために編集が必要です。スクリプトの場所は、通常はパス `openocd/version/.content/scripts/board` の下の実際の実行可能フィールドの中で見つかります。ここで、私は `reset_config srst_only` を `reset_config none` に編集しました。
|
||||
|
||||
Apply and Close を選択します。
|
||||
|
||||
### デバッガの実行
|
||||
|
||||
キーボードをリセットしてください。
|
||||
|
||||
虫アイコンをクリックし、もし全てうまく行けば Debug パースペクティブに移動します。ここでは、main 関数の最初でプログラムカウンタが停止し、Play ボタンが押されるのを待ちます。全てのデバッガのほとんどの機能は Arm MCU で動作しますが、正確な詳細については Google があなたのお友達です！
|
||||
|
||||
|
||||
ハッピーデバッギング！
|
||||
@ -1,120 +0,0 @@
|
||||
# Breaking changes/互換性を破る変更
|
||||
|
||||
<!---
|
||||
grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
|
||||
original document: 0.10.33:docs/breaking_changes.md
|
||||
git diff 0.10.33 HEAD -- docs/breaking_changes.md | cat
|
||||
-->
|
||||
|
||||
このドキュメントは QMK の互換性を破る変更(Breaking change) のプロセスについて説明します。
|
||||
互換性を破る変更とは、互換性がなかったり潜在的な危険が生じるように QMK の動作を変える変更を指します。
|
||||
ユーザが QMK ツリーを更新しても自分のキーマップが壊れない事を確信できるように、これらの変更を制限します。(訳注：以後、原文のまま Breaking change を用語として使用します。)
|
||||
|
||||
Breaking change ピリオドとは、危険な変更、または予想外の変更を QMK へ行なう PR をマージする時のことです。
|
||||
付随するテスト期間があるため、問題が起きることはまれか、有りえないと確信しています。
|
||||
|
||||
## 過去の Breaking change には何が含まれますか？
|
||||
|
||||
* [2020年8月29日](ja/ChangeLog/20200829.md)
|
||||
* [2020年5月30日](ja/ChangeLog/20200530.md)
|
||||
* [2020年2月29日](ja/ChangeLog/20200229.md)
|
||||
* [2019年8月30日](ja/ChangeLog/20190830.md)
|
||||
|
||||
## 次の Breaking change はいつですか？
|
||||
|
||||
次の Breaking change は2020年11月28日に予定されています。
|
||||
|
||||
### 重要な日付
|
||||
|
||||
* [x] 2020年 8月29日 - `develop` が作成されました。毎週リベースされます。
|
||||
* [ ] 2020年10月31日 - `develop` は新しいPRを取り込みません。
|
||||
* [ ] 2020年10月31日 - テスターの募集。
|
||||
* [ ] 2020年11月26日 - `master`がロックされ、PR はマージされません。
|
||||
* [ ] 2020年11月28日 - `develop` を `master` にマージします。
|
||||
* [ ] 2020年11月28日 - `master` のロックが解除されます。PR を再びマージすることができます。
|
||||
|
||||
## どのような変更が含まれますか？
|
||||
|
||||
最新の Breaking change 候補を見るには、[`breaking_change` ラベル](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr)を参照してください。
|
||||
現在から `develop` が閉じられるまでの間に新しい変更が追加される可能性があり、そのラベルが適用された PR はマージされることは保証されていません。
|
||||
|
||||
このラウンドに、あなたの Breaking change を含めたい場合は、`breaking_change` ラベルを持つ PR を作成し、`develop` が閉じる前に承認してもらう必要があります。
|
||||
`develop` が閉じた後は、新しい Breaking change は受け付けられません。
|
||||
|
||||
受け入れの基準:
|
||||
|
||||
* PR が完了し、マージの準備ができている
|
||||
* PR が ChangeLog を持つ
|
||||
|
||||
# チェックリスト
|
||||
|
||||
ここでは、Breaking change プロセスを実行する時に使用する様々なプロセスについて説明します。
|
||||
|
||||
## `master` から `develop` をリベースします
|
||||
|
||||
これは `develop` が開いている間、毎週金曜日に実行されます。
|
||||
|
||||
プロセス:
|
||||
|
||||
```
|
||||
cd qmk_firmware
|
||||
git checkout master
|
||||
git pull --ff-only
|
||||
git checkout develop
|
||||
git rebase master
|
||||
git push --force
|
||||
```
|
||||
|
||||
## `develop` ブランチの作成
|
||||
|
||||
以前の `develop` ブランチがマージされた直後に、これが発生します。
|
||||
|
||||
* `qmk_firmware` git commands
|
||||
* [ ] `git checkout master`
|
||||
* [ ] `git pull --ff-only`
|
||||
* [ ] `git checkout -b develop`
|
||||
* [ ] Edit `readme.md`
|
||||
* [ ] これがテストブランチであることを上部に大きな通知で追加します。
|
||||
* [ ] このドキュメントへのリンクを含めます
|
||||
* [ ] `git commit -m 'Branch point for <DATE> Breaking Change'`
|
||||
* [ ] `git tag breakpoint_<YYYY>_<MM>_<DD>`
|
||||
* [ ] `git tag <next_version>` # ブレーキング ポイント タグがバージョンの増分を混乱させないようにします
|
||||
* [ ] `git push origin develop`
|
||||
* [ ] `git push --tags`
|
||||
|
||||
## マージの 4 週間前
|
||||
|
||||
* `develop` は新しい PR に対して閉じられ、現在の PR の修正のみがマージされる可能性があります。
|
||||
* テスターの呼び出しを投稿します
|
||||
* [ ] Discord
|
||||
* [ ] GitHub PR
|
||||
* [ ] https://reddit.com/r/olkb
|
||||
|
||||
## マージの 1 週間前
|
||||
|
||||
* master が < 2 日前> から <マージの日> まで閉じられることを発表します
|
||||
* [ ] Discord
|
||||
* [ ] GitHub PR
|
||||
* [ ] https://reddit.com/r/olkb
|
||||
|
||||
## マージの 2 日前
|
||||
|
||||
* master が 2 日間閉じられることを発表します
|
||||
* [ ] Discord
|
||||
* [ ] GitHub PR
|
||||
* [ ] https://reddit.com/r/olkb
|
||||
|
||||
## マージの日
|
||||
|
||||
* `qmk_firmware` git commands
|
||||
* [ ] `git checkout develop`
|
||||
* [ ] `git pull --ff-only`
|
||||
* [ ] `git rebase origin/master`
|
||||
* [ ] Edit `readme.md`
|
||||
* [ ] `develop` についてのメモを削除
|
||||
* [ ] ChangeLog を 1 つのファイルにまとめます。
|
||||
* [ ] `git commit -m 'Merge point for <DATE> Breaking Change'`
|
||||
* [ ] `git push origin develop`
|
||||
* GitHub Actions
|
||||
* [ ] `develop`の PR を作成します
|
||||
* [ ] `develop` PR をマージします
|
||||
@ -1,51 +0,0 @@
|
||||
# breaking changes/互換性を破る変更: プルリクエストにフラグが付けられた
|
||||
|
||||
<!---
|
||||
grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
|
||||
original document: 0.9.0:docs/breaking_changes_instructions.md
|
||||
git diff 0.9.0 HEAD -- docs/breaking_changes_instructions.md | cat
|
||||
-->
|
||||
|
||||
QMK のメンバーがあなたのプルリクエストに返信し、あなたの提出したものは Breaking change (互換性を破る変更) であると述べている場合があります。メンバーの判断では、あなたが提案した変更は QMK やその利用者にとってより大きな影響を持つと考えられます。
|
||||
|
||||
プルリクエストにフラグが立てられる原因となるものには、以下のようなものがあります:
|
||||
|
||||
- **ユーザーのキーマップに対する編集**
|
||||
ユーザーが自分のキーマップを QMK に提出した後、しばらくしてさらに更新してプルリクエストを開いたところ、それが `qmk/qmk_firmware` リポジトリで編集されていたためにマージできなかったことに気づくことがあるかもしれません。すべてのユーザーが Git や GitHub を使いこなせるわけではないので、ユーザー自身で問題を修正できないことに気づくかもしれません。
|
||||
- **期待される動作の変更**
|
||||
QMK の動作を変更すると、既存の QMK 機能への変更を組み込んだ新しいファームウェアをフラッシュした場合、ユーザはハードウェアまたは QMK が壊れていると考え、希望する動作を復元する手段がないことに気付くことがあります。
|
||||
- **ユーザーのアクションを必要とする変更**
|
||||
変更には、ツールチェインを更新したり、Git で何らかのアクションを取るなど、ユーザーがアクションを行う必要がある場合もあります。
|
||||
- **精査が必要な変更**
|
||||
時には、投稿がプロジェクトとしての QMK に影響を与えることもあります。これは、著作権やライセンスの問題、コーディング規約、大規模な機能のオーバーホール、コミュニティによるより広範なテストを必要とする「リスクの高い」変更、あるいは全く別のものである可能性があります。
|
||||
- **エンドユーザーとのコミュニケーションを必要とする変更**
|
||||
これには、将来の非推奨化への警告、時代遅れの慣習、その他伝えなければならないが上記のカテゴリのどれかに当てはまらないものが含まれます。
|
||||
|
||||
## 何をすればいいのか?
|
||||
|
||||
提出したものが Breaking change だと判断された場合、手続きをスムーズに進めるためにできることがいくつかあります。
|
||||
|
||||
### PR を分割することを検討する
|
||||
|
||||
あなたがコアコードを投稿していて、それが Breaking change プロセスを経る必要がある唯一の理由が、あなたの変更に合わせてキーマップを更新していることである場合、古いキーマップが機能し続けるような方法であなたの機能を投稿できるかどうかを検討してください。
|
||||
そののち、Breaking change プロセスを経て古いコードを削除する別の PR を提出してください。
|
||||
|
||||
### ChangeLog エントリの提供
|
||||
|
||||
Breaking change プロセスを経て提出する際には、変更ログのエントリを含めることを我々は要請します。
|
||||
エントリーは、あなたのプルリクエストが行う変更の短い要約としてください – [ここの各セクションは changelog として開始されました](ja/ChangeLog/20190830.md "n.b. This should link to the 2019 Aug 30 Breaking Changes doc - @noroadsleft")。
|
||||
|
||||
変更ログは `docs/ChangeLog/YYYYMMDD/PR####.md` に置いてください。
|
||||
ここで、`YYYYMMDD` は QMK の breaking change ブランチ – 通常は `develop` という名称 – が `master` ブランチにマージされる日付、`####` はプルリクエストの番号です。
|
||||
|
||||
ユーザー側でのアクションを必要とする場合、あなたの変更ログは、どのようなアクションを取らなければならないかをユーザーに指示するか、そのようなアクションを指示する場所にリンクする必要があります。
|
||||
|
||||
### 変更点を文書化する
|
||||
|
||||
提出物の目的を理解し、それが必要とする可能性のある意味合いやアクションを理解することで、レビュープロセスをより簡単にすることができます。この目的のためには変更履歴で十分かもしれませんが、より広範囲の変更を行う場合には、変更履歴には不向きな詳細レベルが必要になるかもしれません。
|
||||
|
||||
あなたのプルリクエストにコメントしたり、質問やコメント、変更要求に対応したりすることは、非常にありがたいことです。
|
||||
|
||||
### 助けを求める
|
||||
|
||||
あなたの提出物にフラグが立ったことで、あなたはびっくりしてしまったかもしれません。もし、あなた自身が脅されたり、圧倒されたりしていると感じたら、私たちに知らせてください。プルリクエストにコメントするか、[Discord で QMK チームに連絡を取ってください](https://discord.gg/Uq7gcHh)。
|
||||
@ -1,43 +0,0 @@
|
||||
# QMK CLI :id=qmk-cli
|
||||
|
||||
<!---
|
||||
original document: 0.9.19:docs/cli.md
|
||||
git diff 0.9.19 HEAD -- docs/cli.md | cat
|
||||
-->
|
||||
|
||||
## 概要 :id=overview
|
||||
|
||||
QMK CLI を使用すると QMK キーボードの構築と作業が簡単になります。QMK ファームウェアの取得とコンパイル、キーマップの作成などのようなタスクを簡素化し合理化するためのコマンドを多く提供します。
|
||||
|
||||
### 必要事項 :id=requirements
|
||||
|
||||
QMK は Python 3.6 以上を必要とします。我々は必要事項の数を少なくしようとしていますが、[`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt) に列挙されているパッケージもインストールする必要があります。これらは QMK CLI をインストールするときに自動的にインストールされます。
|
||||
|
||||
### Homebrew を使ったインストール (macOS、いくつかの Linux) :id=install-using-homebrew
|
||||
|
||||
[Homebrew](https://brew.sh) をインストールしている場合は、タップして QMK をインストールすることができます:
|
||||
|
||||
```
|
||||
brew install qmk/qmk/qmk
|
||||
export QMK_HOME='~/qmk_firmware' # オプション、`qmk_firmware` の場所を設定します
|
||||
qmk setup # これは `qmk/qmk_firmware` をクローンし、オプションでビルド環境をセットアップします
|
||||
```
|
||||
|
||||
### pip を使ってインストール :id=install-using-easy_install-or-pip
|
||||
|
||||
上で列挙した中にあなたのシステムがない場合は、QMK を手動でインストールすることができます。最初に、python 3.6 (以降)をインストールしていて、pip をインストールしていることを確認してください。次に以下のコマンドを使って QMK をインストールします:
|
||||
|
||||
```
|
||||
python3 -m pip install qmk
|
||||
export QMK_HOME='~/qmk_firmware' # オプション、`qmk_firmware` の場所を設定します
|
||||
qmk setup # これは `qmk/qmk_firmware` をクローンし、オプションでビルド環境をセットアップします
|
||||
```
|
||||
|
||||
### 他のオペレーティングシステムのためのパッケージ :id=packaging-for-other-operating-systems
|
||||
|
||||
より多くのオペレーティングシステム用に `qmk` パッケージを作成および保守する人を探しています。OS 用のパッケージを作成する場合は、以下のガイドラインに従ってください:
|
||||
|
||||
* これらのガイドラインと矛盾する場合は、OS のベストプラクティスに従ってください
|
||||
* 逸脱する場合は、理由をコメントに文章化してください。
|
||||
* virtualenv を使ってインストールしてください
|
||||
* 環境変数 `QMK_HOME` を設定して、ファームウェアソースを `~/qmk_firmware` 以外のどこかにチェックアウトするようにユーザに指示してください。
|
||||
@ -1,296 +0,0 @@
|
||||
# QMK CLI コマンド
|
||||
|
||||
<!---
|
||||
original document: 0.9.19:docs/cli_command.md
|
||||
git diff 0.9.19 HEAD -- docs/cli_command.md | cat
|
||||
-->
|
||||
|
||||
# ユーザー用コマンド
|
||||
|
||||
## `qmk compile`
|
||||
|
||||
このコマンドにより、任意のディレクトリからファームウェアをコンパイルすることができます。<https://config.qmk.fm> からエクスポートした JSON をコンパイルするか、リポジトリ内でキーマップをコンパイルするか、現在の作業ディレクトリでキーボードをコンパイルすることができます。
|
||||
|
||||
このコマンドはディレクトリを認識します。キーボードやキーマップのディレクトリにいる場合、自動的に KEYBOARD や KEYMAP を入力します。
|
||||
|
||||
**Configurator Exports での使い方**:
|
||||
|
||||
```
|
||||
qmk compile <configuratorExport.json>
|
||||
```
|
||||
|
||||
**キーマップでの使い方**:
|
||||
|
||||
```
|
||||
qmk compile -kb <keyboard_name> -km <keymap_name>
|
||||
```
|
||||
|
||||
**キーボードディレクトリでの使い方**:
|
||||
|
||||
default キーマップのあるキーボードディレクトリ、キーボードのキーマップディレクトリ、`--keymap <keymap_name>` で与えられるキーマップディレクトリにいなければなりません。
|
||||
```
|
||||
qmk compile
|
||||
```
|
||||
|
||||
**指定したキーマップをサポートする全てのキーボードをビルドする場合の使い方**:
|
||||
|
||||
```
|
||||
qmk compile -kb all -km <keymap_name>
|
||||
```
|
||||
|
||||
**例**:
|
||||
```
|
||||
$ qmk config compile.keymap=default
|
||||
$ cd ~/qmk_firmware/keyboards/planck/rev6
|
||||
$ qmk compile
|
||||
Ψ Compiling keymap with make planck/rev6:default
|
||||
...
|
||||
```
|
||||
あるいはオプションのキーマップ引数を指定して
|
||||
|
||||
```
|
||||
$ cd ~/qmk_firmware/keyboards/clueboard/66/rev4
|
||||
$ qmk compile -km 66_iso
|
||||
Ψ Compiling keymap with make clueboard/66/rev4:66_iso
|
||||
...
|
||||
```
|
||||
あるいはキーマップディレクトリで
|
||||
|
||||
```
|
||||
$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
|
||||
$ qmk compile
|
||||
Ψ Compiling keymap with make gh60/satan:colemak
|
||||
...
|
||||
```
|
||||
|
||||
**レイアウトディレクトリでの使い方**:
|
||||
|
||||
`qmk_firmware/layouts/` 以下のキーマップディレクトリにいなければなりません。
|
||||
```
|
||||
qmk compile -kb <keyboard_name>
|
||||
```
|
||||
|
||||
**例**:
|
||||
```
|
||||
$ cd ~/qmk_firmware/layouts/community/60_ansi/mechmerlin-ansi
|
||||
$ qmk compile -kb dz60
|
||||
Ψ Compiling keymap with make dz60:mechmerlin-ansi
|
||||
...
|
||||
```
|
||||
|
||||
## `qmk flash`
|
||||
|
||||
このコマンドは `qmk compile` に似ていますが、ブートローダを対象にすることもできます。ブートローダはオプションで、デフォルトでは `:flash` に設定されています。
|
||||
違うブートローダを指定するには、`-bl <bootloader>` を使ってください。利用可能なブートローダの詳細については、[ファームウェアを書き込む](ja/flashing.md)を見てください。
|
||||
|
||||
このコマンドはディレクトリを認識します。キーボードやキーマップのディレクトリにいる場合、自動的に KEYBOARD や KEYMAP を入力します。
|
||||
|
||||
**Configurator Exports での使い方**:
|
||||
|
||||
```
|
||||
qmk flash <configuratorExport.json> -bl <bootloader>
|
||||
```
|
||||
|
||||
**キーマップでの使い方**:
|
||||
|
||||
```
|
||||
qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader>
|
||||
```
|
||||
|
||||
**ブートローダの列挙**
|
||||
|
||||
```
|
||||
qmk flash -b
|
||||
```
|
||||
|
||||
## `qmk config`
|
||||
|
||||
このコマンドにより QMK の挙動を設定することができます。完全な `qmk config` のドキュメントについては、[CLI 設定](ja/cli_configuration.md)を見てください。
|
||||
|
||||
**使用法**:
|
||||
|
||||
```
|
||||
qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
|
||||
```
|
||||
|
||||
## `qmk doctor`
|
||||
|
||||
このコマンドは環境を調査し、潜在的なビルドあるいは書き込みの問題について警告します。必要に応じてそれらの多くを修正できます。
|
||||
|
||||
**使用法**:
|
||||
|
||||
```
|
||||
qmk doctor [-y] [-n]
|
||||
```
|
||||
|
||||
**例**:
|
||||
|
||||
環境に問題がないか確認し、それらを修正するよう促します:
|
||||
|
||||
qmk doctor
|
||||
|
||||
環境を確認し、見つかった問題を自動的に修正します:
|
||||
|
||||
qmk doctor -y
|
||||
|
||||
環境を確認し、問題のみをレポートします:
|
||||
|
||||
qmk doctor -n
|
||||
|
||||
## `qmk info`
|
||||
|
||||
QMK のキーボードやキーマップに関する情報を表示します。キーボードに関する情報を取得したり、レイアウトを表示したり、基礎となるキーマトリックスを表示したり、JSON キーマップをきれいに印刷したりするのに使用できます。
|
||||
|
||||
**使用法**:
|
||||
|
||||
```
|
||||
qmk info [-f FORMAT] [-m] [-l] [-km KEYMAP] [-kb KEYBOARD]
|
||||
```
|
||||
|
||||
このコマンドはディレクトリを認識します。キーボードやキーマップのディレクトリにいる場合、自動的に KEYBOARD や KEYMAP を入力します。
|
||||
|
||||
**例**:
|
||||
|
||||
キーボードの基本情報を表示する:
|
||||
|
||||
qmk info -kb planck/rev5
|
||||
|
||||
キーボードのマトリクスを表示する:
|
||||
|
||||
qmk info -kb ergodox_ez -m
|
||||
|
||||
キーボードの JSON キーマップを表示する:
|
||||
|
||||
qmk info -kb clueboard/california -km default
|
||||
|
||||
## `qmk json2c`
|
||||
|
||||
QMK Configurator からエクスポートしたものから keymap.c を生成します。
|
||||
|
||||
**使用法**:
|
||||
|
||||
```
|
||||
qmk json2c [-o OUTPUT] filename
|
||||
```
|
||||
|
||||
## `qmk list-keyboards`
|
||||
|
||||
このコマンドは現在 `qmk_firmware` で定義されている全てのキーボードを列挙します。
|
||||
|
||||
**使用法**:
|
||||
|
||||
```
|
||||
qmk list-keyboards
|
||||
```
|
||||
|
||||
## `qmk list-keymaps`
|
||||
|
||||
このコマンドは指定されたキーボード(とリビジョン)の全てのキーマップを列挙します。
|
||||
|
||||
このコマンドはディレクトリを認識します。キーボードのディレクトリにいる場合、自動的に KEYBOARD を入力します。
|
||||
|
||||
**使用法**:
|
||||
|
||||
```
|
||||
qmk list-keymaps -kb planck/ez
|
||||
```
|
||||
|
||||
## `qmk new-keymap`
|
||||
|
||||
このコマンドは、キーボードの既存のデフォルトのキーマップに基づいて新しいキーマップを作成します。
|
||||
|
||||
このコマンドはディレクトリを認識します。キーボードやキーマップのディレクトリにいる場合、自動的に KEYBOARD や KEYMAP を入力します。
|
||||
|
||||
**使用法**:
|
||||
|
||||
```
|
||||
qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 開発者用コマンド
|
||||
|
||||
## `qmk format-c`
|
||||
|
||||
このコマンドは clang-format を使って C コードを整形します。
|
||||
|
||||
引数無しで実行すると、変更された全てのコアコードを整形します。デフォルトでは `git diff` で `origin/master` をチェックし、ブランチは `-b <branch_name>` を使って変更できます。
|
||||
|
||||
`-a` で全てのコアコードを整形するか、コマンドラインでファイル名を渡して特定のファイルに対して実行します。
|
||||
|
||||
**指定したファイルに対する使い方**:
|
||||
|
||||
```
|
||||
qmk format-c [file1] [file2] [...] [fileN]
|
||||
```
|
||||
|
||||
**全てのコアファイルに対する使い方**:
|
||||
|
||||
```
|
||||
qmk format-c -a
|
||||
```
|
||||
|
||||
**origin/master で変更されたファイルのみに対する使い方**:
|
||||
|
||||
```
|
||||
qmk format-c
|
||||
```
|
||||
|
||||
**branch_name で変更されたファイルのみに対する使い方**:
|
||||
|
||||
```
|
||||
qmk format-c -b branch_name
|
||||
```
|
||||
|
||||
## `qmk docs`
|
||||
|
||||
このコマンドは、ドキュメントを参照または改善するために使うことができるローカル HTTP サーバを起動します。デフォルトのポートは 8936 です。
|
||||
|
||||
**使用法**:
|
||||
|
||||
```
|
||||
qmk docs [-p PORT]
|
||||
```
|
||||
|
||||
## `qmk kle2json`
|
||||
|
||||
このコマンドにより、生の KLE データから QMK Configurator の JSON へ変換することができます。絶対パスあるいは現在のディレクトリ内のファイル名のいずれかを受け取ります。デフォルトでは、`info.json` が既に存在している場合は上書きしません。上書きするには、`-f` あるいは `--force` フラグを使ってください。
|
||||
|
||||
**使用法**:
|
||||
|
||||
```
|
||||
qmk kle2json [-f] <filename>
|
||||
```
|
||||
|
||||
**例**:
|
||||
|
||||
```
|
||||
$ qmk kle2json kle.txt
|
||||
☒ File info.json already exists, use -f or --force to overwrite.
|
||||
```
|
||||
|
||||
```
|
||||
$ qmk kle2json -f kle.txt -f
|
||||
Ψ Wrote out to info.json
|
||||
```
|
||||
|
||||
## `qmk format-python`
|
||||
|
||||
このコマンドは `qmk_firmware` 内の python コードを整形します。
|
||||
|
||||
**使用法**:
|
||||
|
||||
```
|
||||
qmk format-python
|
||||
```
|
||||
|
||||
## `qmk pytest`
|
||||
|
||||
このコマンドは python のテストスィートを実行します。python コードに変更を加えた場合、これの実行が成功することを確認する必要があります。
|
||||
|
||||
**使用法**:
|
||||
|
||||
```
|
||||
qmk pytest
|
||||
```
|
||||
@ -1,126 +0,0 @@
|
||||
# QMK CLI 設定
|
||||
|
||||
<!---
|
||||
original document: 0.9.0:docs/cli_configuration.md
|
||||
git diff 0.9.0 HEAD -- docs/cli_configuration.md | cat
|
||||
-->
|
||||
|
||||
このドキュメントは `qmk config` がどのように動作するかを説明します。
|
||||
|
||||
# はじめに
|
||||
|
||||
QMK CLI の設定はキーバリューシステムです。各キーはピリオドで区切られたサブコマンドと引数名で構成されます。これにより、設定キーと設定された引数の間で簡単かつ直接的な変換が可能になります。
|
||||
|
||||
## 簡単な例
|
||||
|
||||
例として、`qmk compile --keyboard clueboard/66/rev4 --keymap default` コマンドを見てみましょう。
|
||||
|
||||
設定から読み取ることができる2つのコマンドライン引数があります:
|
||||
|
||||
* `compile.keyboard`
|
||||
* `compile.keymap`
|
||||
|
||||
これらを設定してみましょう:
|
||||
|
||||
```
|
||||
$ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default
|
||||
compile.keyboard: None -> clueboard/66/rev4
|
||||
compile.keymap: None -> default
|
||||
Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
|
||||
```
|
||||
|
||||
これで、毎回キーボードとキーマップを設定することなく、`qmk compile` を実行することができます。
|
||||
|
||||
## ユーザデフォルトの設定
|
||||
|
||||
複数のコマンド間で設定を共有したい場合があります。例えば、いくつかのコマンドは引数 `--keyboard` を受け取ります。全てのコマンドでこの値を設定する代わりに、その引数を受け取る全てのコマンドで使われるユーザ値を設定することができます。
|
||||
|
||||
例:
|
||||
|
||||
```
|
||||
$ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default
|
||||
user.keyboard: None -> clueboard/66/rev4
|
||||
user.keymap: None -> default
|
||||
Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
|
||||
```
|
||||
|
||||
# CLI ドキュメント (`qmk config`)
|
||||
|
||||
`qmk config` コマンドは基礎となる設定とやり取りするために使われます。引数無しで実行すると、現在の設定を表示します。引数が指定された場合、それらは設定トークンと見なされます。設定トークンは以下の形式の空白を含まない文字列です:
|
||||
|
||||
<subcommand|general|default>[.<key>][=<value>]
|
||||
|
||||
## 設定値の設定
|
||||
|
||||
設定キーに等号 (=) を入れることで、設定値を設定することができます。キーは常に完全な `<section>.<key>` 形式である必要があります。
|
||||
|
||||
例:
|
||||
|
||||
```
|
||||
$ qmk config default.keymap=default
|
||||
default.keymap: None -> default
|
||||
Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
|
||||
```
|
||||
|
||||
## 設定値の読み込み
|
||||
|
||||
設定全体、単一のキー、あるいはセクション全体の設定値を読み取ることができます。1つ以上の値を表示するために複数のキーを指定することができます。
|
||||
|
||||
### 全体の構成例
|
||||
|
||||
qmk config
|
||||
|
||||
### セクション全体の例
|
||||
|
||||
qmk config compile
|
||||
|
||||
### 単一キーの例 :id=single-key-example
|
||||
|
||||
qmk config compile.keyboard
|
||||
|
||||
### 複数キーの例
|
||||
|
||||
qmk config user compile.keyboard compile.keymap
|
||||
|
||||
## 設定値の削除
|
||||
|
||||
設定値を特別な文字列 `None` に設定することで、設定値を削除することができます。
|
||||
|
||||
例:
|
||||
|
||||
```
|
||||
$ qmk config default.keymap=None
|
||||
default.keymap: default -> None
|
||||
Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
|
||||
```
|
||||
|
||||
## 複数の操作
|
||||
|
||||
複数の読み込みおよび書き込み操作を1つのコマンドに組み合わせることができます。それらは順番に実行および表示されます:
|
||||
|
||||
```
|
||||
$ qmk config compile default.keymap=default compile.keymap=None
|
||||
compile.keymap=skully
|
||||
compile.keyboard=clueboard/66_hotswap/gen1
|
||||
default.keymap: None -> default
|
||||
compile.keymap: skully -> None
|
||||
Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
|
||||
```
|
||||
|
||||
# ユーザ設定オプション
|
||||
|
||||
| キー | デフォルト値 | 説明 |
|
||||
|-----|---------------|-------------|
|
||||
| user.keyboard | None | キーボードのパス (例: `clueboard/66/rev4`) |
|
||||
| user.keymap | None | キーマップ名 (例: `default`) |
|
||||
| user.name | None | ユーザの GitHub のユーザ名。 |
|
||||
|
||||
# 全ての設定オプション
|
||||
|
||||
| キー | デフォルト値 | 説明 |
|
||||
|-----|---------------|-------------|
|
||||
| compile.keyboard | None | キーボードのパス (例: `clueboard/66/rev4`) |
|
||||
| compile.keymap | None | キーマップ名 (例: `default`) |
|
||||
| hello.name | None | 実行時の挨拶の名前 |
|
||||
| new_keyboard.keyboard | None | キーボードのパス (例: `clueboard/66/rev4`) |
|
||||
| new_keyboard.keymap | None | キーマップ名 (例: `default`) |
|
||||
@ -1,223 +0,0 @@
|
||||
# QMK CLI 開発
|
||||
|
||||
<!---
|
||||
original document: 0.9.19:docs/cli_development.md
|
||||
git diff 0.9.19 HEAD -- docs/cli_development.md | cat
|
||||
-->
|
||||
|
||||
このドキュメントは、新しい `qmk` サブコマンドを書きたい開発者に役立つ情報が含まれています。
|
||||
|
||||
# 概要
|
||||
|
||||
QMK CLI は git で有名になったサブコマンドパターンを使って動作します。メインの `qmk` スクリプトは単に環境をセットアップし、実行する正しいエントリポイントを選択するためにあります。各サブコマンドは、何らかのアクションを実行しシェルのリターンコード、または None を返すエントリーポイント (`@cli.subcommand()` で修飾されます)を備えた自己完結型のモジュールです。
|
||||
|
||||
## 開発者モード:
|
||||
|
||||
キーボードを保守、あるいは QMK に貢献したい場合は、CLI の「開発者」モードを有効にすることができます:
|
||||
|
||||
`qmk config user.developer=True`
|
||||
|
||||
これにより利用可能な全てのサブコマンドが表示されます。
|
||||
**注意:** 追加で必要なものをインストールする必要があります:
|
||||
```bash
|
||||
python3 -m pip install -r requirements-dev.txt
|
||||
```
|
||||
|
||||
# サブコマンド
|
||||
|
||||
[MILC](https://github.com/clueboard/milc) は、`qmk` が引数の解析、設定、ログ、およびほかの多くの機能を処理するために使用する CLI フレームワークです。グルーコードを書くために時間を無駄にすることなく、ツールの作成に集中できます。
|
||||
|
||||
ローカル CLI 内のサブコマンドは、常に `qmk_firmware/lib/python/qmk/cli` で見つかります。
|
||||
|
||||
サブコマンドの例を見てみましょう。これは `lib/python/qmk/cli/hello.py` です:
|
||||
|
||||
```python
|
||||
"""QMK Python Hello World
|
||||
|
||||
This is an example QMK CLI script.
|
||||
"""
|
||||
from milc import cli
|
||||
|
||||
|
||||
@cli.argument('-n', '--name', default='World', help='Name to greet.')
|
||||
@cli.subcommand('QMK Hello World.')
|
||||
def hello(cli):
|
||||
"""Log a friendly greeting.
|
||||
"""
|
||||
cli.log.info('Hello, %s!', cli.config.hello.name)
|
||||
```
|
||||
|
||||
最初に `milc` から `cli` をインポートします。これが、ユーザとやり取りをし、スクリプトの挙動を制御する方法です。`@cli.argument()` を使って、コマンドラインフラグ `--name` を定義します。これは、ユーザが設定できる `hello.name` (そして対応する `user.name`) という名前の設定変数も作成し、引数を指定する必要が無くなります。`cli.subcommand()` デコレータは、この関数をサブコマンドとして指定します。サブコマンドの名前は関数の名前から取られます。
|
||||
|
||||
関数の中に入ると、典型的な "Hello, World!" プログラムが見つかります。`cli.log` を使って、基礎となる [ロガーオブジェクト](https://docs.python.org/3.6/library/logging.html#logger-objects) にアクセスし、その挙動はユーザが制御できます。またユーザが指定した名前の値に `cli.config.hello.name` でアクセスします。`cli.config.hello.name` の値は、ユーザが指定した `--name` 引数を調べることで決定されます。指定されていない場合、`qmk.ini` 設定ファイルの中の値が使われ、どちらも指定されていない場合は `cli.argument()` デコレータで指定されたデフォルトが代用されます。
|
||||
|
||||
# ユーザとの対話処理
|
||||
|
||||
MILC と QMK CLI にはユーザとやり取りするための幾つかの便利なツールがあります。これらの標準ツールを使うと、テキストに色を付けて対話し易くし、ユーザはその情報をいつどのように表示および保存するかを制御することができます。
|
||||
|
||||
## テキストの表示
|
||||
|
||||
サブコマンド内でテキストを出力するための2つの主な方法があります- `cli.log` と `cli.echo()`。それらは似た方法で動作しますが、ほとんどの一般的な目的の出力には `cli.log.info()` を使うことをお勧めします。
|
||||
|
||||
特別なトークンを使用してテキストを色付けし、プログラムの出力を理解しやすくすることができます。以下の[テキストの色付け](#colorizing-text)を見てください。
|
||||
|
||||
これらの両方の方法は python の [printf 形式の文字列書式化](https://docs.python.org/3.6/library/stdtypes.html#old-string-formatting) を使った組み込みの文字列書式化をサポートします。テキスト文字列内で`%s` と `%d` のようなトークンを使い、引数で値を渡すことができます。例として、上記の Hello、World プログラムを見てください。
|
||||
|
||||
書式演算子 (`%`) を直接使わないでください、常に引数で値を渡します。
|
||||
|
||||
### ログ (`cli.log`)
|
||||
|
||||
`cli.log` オブジェクトは[ロガーオブジェクト](https://docs.python.org/3.6/library/logging.html#logger-objects)へのアクセスを与えます。ログ出力を設定し、ユーザに各ログレベルの素敵な絵文字(またはターミナルが unicode をサポートしない場合はログレベル名)を表示します。このようにして、ユーザは何か問題が発生した時に最も重要なメッセージを一目で確認することができます。
|
||||
|
||||
デフォルトのログレベルは `INFO` です。ユーザが `qmk -v <subcommand>` を実行すると、デフォルトのログレベルは `DEBUG` に設定されます。
|
||||
|
||||
| 関数 | 絵文字 |
|
||||
|----------|-------|
|
||||
| cli.log.critical | `{bg_red}{fg_white}¬_¬{style_reset_all}` |
|
||||
| cli.log.error | `{fg_red}☒{style_reset_all}` |
|
||||
| cli.log.warning | `{fg_yellow}⚠{style_reset_all}` |
|
||||
| cli.log.info | `{fg_blue}Ψ{style_reset_all}` |
|
||||
| cli.log.debug | `{fg_cyan}☐{style_reset_all}` |
|
||||
| cli.log.notset | `{style_reset_all}¯\\_(o_o)_/¯` |
|
||||
|
||||
### 出力 (`cli.echo`)
|
||||
|
||||
場合によっては単にログシステムの外部でテキストを出力する必要があります。これは、固定データを出力したり、ログに記録してはいけない何かを書きだす場合に適しています。ほとんどの場合、`cli.echo` よりも `cli.log.info()` を選ぶべきです。
|
||||
|
||||
### テキストの色付け
|
||||
|
||||
テキスト内に色トークンを含めることで、テキストの出力を色付けすることができます。情報を伝えるためではなく、強調するために色を使います。ユーザは色を無効にできることを覚えておいてください。色を無効にした場合でもサブコマンドは引き続き使えるようにしてください。
|
||||
|
||||
背景色を設定するのは、あなたがやっていることに不可欠ではない限り、通常は避けるべきです。ユーザは、ターミナルの色に関しては多くの好みを持つため、あなたは黒と白のどちらの背景に対してもうまく機能する色を選択する必要があることを覚えておいてください。
|
||||
|
||||
'fg' という接頭辞の付いた色は、前景(テキスト)色に影響します。'bg' という接頭辞の付いた色は、背景色に影響します。
|
||||
|
||||
| 色 | 背景 | 拡張背景 | 前景 | 拡張前景 |
|
||||
|-------|------------|---------------------|------------|--------------------|
|
||||
| 黒 | {bg_black} | {bg_lightblack_ex} | {fg_black} | {fg_lightblack_ex} |
|
||||
| 青 | {bg_blue} | {bg_lightblue_ex} | {fg_blue} | {fg_lightblue_ex} |
|
||||
| シアン | {bg_cyan} | {bg_lightcyan_ex} | {fg_cyan} | {fg_lightcyan_ex} |
|
||||
| 緑 | {bg_green} | {bg_lightgreen_ex} | {fg_green} | {fg_lightgreen_ex} |
|
||||
| マゼンタ | {bg_magenta} | {bg_lightmagenta_ex} | {fg_magenta} | {fg_lightmagenta_ex} |
|
||||
| 赤 | {bg_red} | {bg_lightred_ex} | {fg_red} | {fg_lightred_ex} |
|
||||
| 白 | {bg_white} | {bg_lightwhite_ex} | {fg_white} | {fg_lightwhite_ex} |
|
||||
| 黄 | {bg_yellow} | {bg_lightyellow_ex} | {fg_yellow} | {fg_lightyellow_ex} |
|
||||
|
||||
ANSI 出力の挙動を変更するために使うことができる制御シーケンスもあります。
|
||||
|
||||
| 制御シーケンス | 説明 |
|
||||
|-------------------|-------------|
|
||||
| {style_bright} | テキストを明るくする |
|
||||
| {style_dim} | テキストを暗くする |
|
||||
| {style_normal} | テキストを通常にする (`{style_bright}` または `{style_dim}` のどちらでもない) |
|
||||
| {style_reset_all} | 全てのテキストの属性をデフォルトに再設定する(これは自動的に全ての文字列の最後に自動的に追加されます。) |
|
||||
| {bg_reset} | 背景色をユーザのデフォルトに再設定します。 |
|
||||
| {fg_reset} | 背景色をユーザのデフォルトに再設定します。 |
|
||||
|
||||
# 引数と設定
|
||||
|
||||
QMK は引数の解析と設定の詳細をあなたの代わりに処理します。新しい引数を追加すると、サブコマンドの名前と引数の長い名前に基づいて設定ツリーに自動的に組み込まれます。属性形式のアクセス (`cli.config.<subcommand>.<argument>`) あるいは辞書形式のアクセス (`cli.config['<subcommand>']['<argument>']`) を使って、`cli.config` 内のこの設定にアクセスすることができます。
|
||||
|
||||
内部では、QMK は [設定ファイルのパーサ](https://docs.python.org/3/library/configparser.html) を使って設定を格納します。これにより、人間が編集可能な方法で設定を表す簡単で分かり易い方法を提供します。この設定へのアクセスをラップして、設定ファイルのパーサーが通常持たない幾つかの機能を提供しています。
|
||||
|
||||
## 設定値の読み込み
|
||||
|
||||
通常期待される全ての方法で `cli.config` とやり取りすることができます。例えば、`qmk compile` コマンドは `cli.config.compile.keyboard` からキーボード名を取得します。値がコマンドライン、環境変数あるいは設定ファイルからきたものであるかどうかを知る必要はありません。
|
||||
|
||||
繰り返しもサポートされます:
|
||||
|
||||
```
|
||||
for section in cli.config:
|
||||
for key in cli.config[section]:
|
||||
cli.log.info('%s.%s: %s', section, key, cli.config[section][key])
|
||||
```
|
||||
|
||||
## 設定値の設定
|
||||
|
||||
通常の方法で設定値を設定することができます。
|
||||
|
||||
辞書形式:
|
||||
|
||||
```
|
||||
cli.config['<section>']['<key>'] = <value>
|
||||
```
|
||||
|
||||
属性形式:
|
||||
|
||||
```
|
||||
cli.config.<section>.<key> = <value>
|
||||
```
|
||||
|
||||
## 設定値の削除
|
||||
|
||||
通常の方法で設定値を削除することができます。
|
||||
|
||||
辞書形式:
|
||||
|
||||
```
|
||||
del(cli.config['<section>']['<key>'])
|
||||
```
|
||||
|
||||
属性形式:
|
||||
|
||||
```
|
||||
del(cli.config.<section>.<key>)
|
||||
```
|
||||
|
||||
## 設定ファイルの書き方
|
||||
|
||||
設定は変更しても書き出されません。ほとんどのコマンドでこれをする必要はありません。ユーザに `qmk config` を使って設定を慎重に変更させることをお勧めします。
|
||||
|
||||
設定を書き出すために `cli.save_config()` を使うことができます。
|
||||
|
||||
## 設定からの引数の除外
|
||||
|
||||
一部の引数は設定ファイルに反映すべきではありません。これらは引数を作成する時に `arg_only=True` を追加することで除外することができます。
|
||||
|
||||
例:
|
||||
|
||||
```
|
||||
@cli.argument('-o', '--output', arg_only=True, help='File to write to')
|
||||
@cli.argument('filename', arg_only=True, help='Configurator JSON file')
|
||||
@cli.subcommand('Create a keymap.c from a QMK Configurator export.')
|
||||
def json_keymap(cli):
|
||||
pass
|
||||
```
|
||||
|
||||
`cli.args` を使ってのみこれらの引数にアクセスすることができます。例えば:
|
||||
|
||||
```
|
||||
cli.log.info('Reading from %s and writing to %s', cli.args.filename, cli.args.output)
|
||||
```
|
||||
|
||||
# テスト、リントおよびフォーマット
|
||||
|
||||
nose2、flake8 および yapf を使ってコードをテスト、リントおよびフォーマットします。これらのテストを実行するために `pytest` と `format-python` サブコマンドを使うことができます。
|
||||
|
||||
### テストとリント
|
||||
|
||||
qmk pytest
|
||||
|
||||
### フォーマット
|
||||
|
||||
qmk format-python
|
||||
|
||||
## フォーマットの詳細
|
||||
|
||||
[yapf](https://github.com/google/yapf) を使ってコードを自動的にフォーマットします。フォーマットの設定は `setup.cfg` の `[yapf]` セクションにあります。
|
||||
|
||||
?> ヒント- 多くのエディタは yapf をプラグインとして使って、入力したコードを自動的にフォーマットすることができます。
|
||||
|
||||
## テストの詳細
|
||||
|
||||
テストは `lib/python/qmk/tests/` にあります。このディレクトリに単体テストと統合テストの両方があります。コードの単体テストと統合テストの両方を書いてほしいですが、一方のみ書く場合は統合テストを優先してください。
|
||||
|
||||
PR にテストの包括的なセットが含まれない場合は、次のようなコメントをコードに追加して、他の人が手助けできるようにしてください:
|
||||
|
||||
# TODO(unassigned/<your_github_username>): Write <unit|integration> tests
|
||||
|
||||
[nose2](https://nose2.readthedocs.io/en/latest/getting_started.html) を使ってテストを実行します。テスト関数でできることの詳細については、nose2 のドキュメントを参照してください。
|
||||
|
||||
## リントの詳細
|
||||
|
||||
flake8 を使ってコードをリントします。PR を開く前に、コードは flake8 をパスしなければなりません。これは `qmk pytest` を実行するときにチェックされ、PR を登録したときに CI によってチェックされます。
|
||||
@ -1,63 +0,0 @@
|
||||
# コーディング規約 (C)
|
||||
|
||||
<!---
|
||||
original document: 0.13.15:docs/coding_conventions_c.md
|
||||
git diff 0.13.15 HEAD -- docs/coding_conventions_c.md | cat
|
||||
-->
|
||||
|
||||
私たちのスタイルのほとんどはかなり理解しやすいですが、現時点では完全に一貫しているわけではありません。変更箇所周辺のコードのスタイルと一致させる必要がありますが、そのコードに一貫性が無い場合や不明瞭な場合は以下のガイドラインに従ってください:
|
||||
|
||||
* 4つのスペース (ソフトタブ) を使ってインデントします。
|
||||
* 修正版 One True Brace Style を使います。
|
||||
* 開き括弧: ブロックを開始する文と同じ行の最後
|
||||
* 閉じ括弧: ブロックを開始した文と同じ字下げ
|
||||
* Else If: 行の先頭に閉じ括弧を置き、次の開き括弧を同じ行の最後に置きます。
|
||||
* 省略可能な括弧: 常に括弧を付け加えます。
|
||||
* 良い: if (condition) { return false; }
|
||||
* 悪い: if (condition) return false;
|
||||
* C 形式のコメントの使用を推奨します: `/* */`
|
||||
* コメントを機能を説明するストーリーと考えて下さい。
|
||||
* 特定の決定がなされた理由を充分なコメントで説明してください。
|
||||
* 分かり切ったコメントは書かないでください。
|
||||
* 分かり切ったコメントであるか確信できない場合は、コメントを含めてください。
|
||||
* 一般的に、行を折り返さないで、必要なだけ長くすることができます。行を折り返すことを選択した場合は、76列を超えて折り返さないでください。
|
||||
* 古い形式のインクルードガード (`#ifndef THIS_FILE_H`、`#define THIS_FILE_H`、...、`#endif`) ではなく、ヘッダファイルの先頭で `#pragma once` を使います。
|
||||
* プリプロセッサ if の両方の形式を受け付けます: `#ifdef DEFINED` と `#if defined(DEFINED)`
|
||||
* どちらがいいかわからない場合は、`#if defined(DEFINED)` 形式を使ってください。
|
||||
* 複数の条件 `#if` に移行する場合を除き、既存のコードを別のスタイルに変更しないでください。
|
||||
* プリプロセッサディレクティブをインデントする方法(あるいはするかどうか)を決定する時は、以下の事に留意してください:
|
||||
* 一貫性よりも読みやすさが重要です。
|
||||
* ファイルの既存のスタイルに従ってください。ファイルのスタイルが混在している場合は、修正しようとしているセクションに適したスタイルに従ってください。
|
||||
* インデントする時は、ハッシュを行の先頭に置き、`#` と `if` の間に空白を追加します。`#` の後ろに4つスペースを入れて開始します。
|
||||
* 周りの C コードのインデントレベルに従うか、プリプロセッサのディレクティブに独自のインデントレベルを設定することができます。コードの意図を最もよく伝えるスタイルを選択してください。
|
||||
|
||||
わかりやすいように例を示します:
|
||||
|
||||
```c
|
||||
/* Enums for foo */
|
||||
enum foo_state {
|
||||
FOO_BAR,
|
||||
FOO_BAZ,
|
||||
};
|
||||
|
||||
/* Returns a value */
|
||||
int foo(void) {
|
||||
if (some_condition) {
|
||||
return FOO_BAR;
|
||||
} else {
|
||||
return -1;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
# clang-format を使った自動整形
|
||||
|
||||
[Clang-format](https://clang.llvm.org/docs/ClangFormat.html) は LLVM の一部で、誰もが手動で整形するほど暇ではないため、コードを自動整形することができます。私たちは、上記のコーディング規約のほとんどを適用する設定ファイルを提供しています。空白と改行のみを変更するため、省略可能な括弧は自分で付け加えることを忘れないでください。
|
||||
|
||||
Windows で clang-format を入手するには [full LLVM インストーラ](https://llvm.org/builds/)を使い、Ubuntu では `sudo apt install clang-format` を使ってください。
|
||||
|
||||
コマンドラインから実行する場合、オプションとして `-style=file` を渡すと、QMK ルートディレクトリ内の .clang-format 設定ファイルを自動的に見つけます。
|
||||
|
||||
VSCode を使う場合は、標準の C/C++ プラグインが clang-format をサポートしますが、その他にも [独立した拡張機能](https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.ClangFormat) があります。
|
||||
|
||||
幾つかのコード (LAYOUT マクロのような)が clang-format によって破壊されるため、これらのファイルで clang-format を実行しないか、整形したくないコードを `// clang-format off` と `// clang-format on` で囲みます。
|
||||
@ -1,331 +0,0 @@
|
||||
# コーディング規約 (Python)
|
||||
|
||||
<!---
|
||||
original document: 0.9.19:docs/coding_conventions_python.md
|
||||
git diff 0.9.19 HEAD -- docs/coding_conventions_python.md | cat
|
||||
-->
|
||||
|
||||
私たちのスタイルの大部分は PEP8 に従いますが、神経質にならないように幾つかのローカルな変更を加えています。
|
||||
|
||||
* サポートされる全てのプラットフォームとの互換性のために、Python 3.6 を対象にしています。
|
||||
* 4つのスペース (ソフトタブ) を使ってインデントします
|
||||
* 充分なコメントを書くことを推奨します
|
||||
* コメントを機能を説明するストーリーと考えて下さい
|
||||
* 特定の決定がなされた理由を充分なコメントで説明してください。
|
||||
* 分かり切ったコメントは書かないでください
|
||||
* 分かり切ったコメントであるか確信できない場合は、コメントを含めてください。
|
||||
* 全ての関数について、役に立つ docstring を必要とします。
|
||||
* 一般的に、行を折り返さないで、必要なだけ長くすることができます。行を折り返すことを選択した場合は、76列を超えて折り返さないでください。
|
||||
* 私たちの慣習の幾つかは、Python 使いでは無い人にコードベースをより身近にするために、python コミュニティに広まっているものとは競合しています。
|
||||
|
||||
# YAPF
|
||||
|
||||
コードを整形するために [yapf](https://github.com/google/yapf) を使うことができます。[setup.cfg](setup.cfg) で設定を提供しています。
|
||||
|
||||
# インポート
|
||||
|
||||
`import ...` や `from ... import ...` をいつ使うかについての厳密なルールはありません。理解しやすさと保守性が究極の目的です。
|
||||
|
||||
一般的に、コードを短く理解しやすくするためにモジュールから特定の関数とクラス名をインポートする方が望ましいです。これにより、名前が曖昧になることがあります。代わりにモジュールをインポートするようにします。互換性のあるモジュールをインポートする時を除いて、インポートする時は "as" キーワードを避けるべきです。
|
||||
|
||||
インポートは各モジュール1行にする必要があります。標準的な python ルールに従って、インポート文をシステム、サードパーティ、ローカルにグループ化します。
|
||||
|
||||
`from foo import *` を使わないでください。代わりにインポートしたいオブジェクトのリストを指定するか、モジュール全体をインポートします。
|
||||
|
||||
## インポートの例
|
||||
|
||||
良い:
|
||||
|
||||
```
|
||||
from qmk import effects
|
||||
|
||||
effects.echo()
|
||||
```
|
||||
|
||||
悪い:
|
||||
|
||||
```
|
||||
from qmk.effects import echo
|
||||
|
||||
echo() # echoがどこから来たのかが不明瞭です
|
||||
```
|
||||
|
||||
良い:
|
||||
|
||||
```
|
||||
from qmk.keymap import compile_firmware
|
||||
|
||||
compile_firmware()
|
||||
```
|
||||
|
||||
良いですが、上の方がより良いです:
|
||||
|
||||
```
|
||||
import qmk.keymap
|
||||
|
||||
qmk.keymap.compile_firmware()
|
||||
```
|
||||
|
||||
# 命令文
|
||||
|
||||
各行1文としてください。
|
||||
|
||||
可能な場合(例えば `if foo: bar`)でも、2つの文を1行にまとめないでください。
|
||||
|
||||
# 命名
|
||||
|
||||
`module_name`, `package_name`, `ClassName`, `method_name`, `ExceptionName`, `function_name`, `GLOBAL_CONSTANT_NAME`, `global_var_name`, `instance_var_name`, `function_parameter_name`, `local_var_name`.
|
||||
|
||||
関数名、変数名 およびファイル名は説明的でなければなりません; 略語を避けます。特に、プロジェクト外の読み手に曖昧あるいは馴染みのない略語を使わず、単語内の文字を削除して略さないでください。
|
||||
|
||||
常に .py のファイル名の拡張子を使います。ダッシュを使わないでください。
|
||||
|
||||
## 避けるべき名前
|
||||
|
||||
* カウンタあるいはイテレータ以外の1文字の名前。try/except 文では例外の識別子として `e` を使うことができます。
|
||||
* パッケージ/モジュール名内のダッシュ (`-`)
|
||||
* `__double_leading_and_trailing_underscore__` (2つのアンダースコアで始まる名前と終わる名前、Python で予約済み)
|
||||
|
||||
# Docstring
|
||||
|
||||
docstring の一貫性を維持するために、以下のガイドラインを設定しました。
|
||||
|
||||
* マークダウン(Markdown)形式の使用
|
||||
* 常に少なくとも1つの改行を含む3つのダブルクォートの docstring を使ってください: `"""\n"""`
|
||||
* 最初の行は、関数が行うことの短い (70文字未満) 説明です。
|
||||
* docstring が更に必要な場合は、説明と残りの間に空白行を入れます。
|
||||
* 開始の3つのダブルクォートと同じインデントレベルでインデント行を始めます
|
||||
* 以下で説明する形式を使って全ての関数の引数について記述します
|
||||
* Args:、Returns: および Raises: が存在する場合、それらは docstring の最後の3つの要素で、それぞれ空白行で区切られなければなりません。
|
||||
|
||||
## 簡単な docstring の例
|
||||
|
||||
```
|
||||
def my_awesome_function():
|
||||
"""1970 Jan 1 00:00 UTC からの秒数を返します。
|
||||
"""
|
||||
return int(time.time())
|
||||
```
|
||||
|
||||
## 複雑な docstring の例
|
||||
|
||||
```
|
||||
def my_awesome_function():
|
||||
"""1970 Jan 1 00:00 UTC からの秒数を返します。
|
||||
|
||||
この関数は常に整数の秒数を返します。
|
||||
"""
|
||||
return int(time.time())
|
||||
```
|
||||
|
||||
## 関数の引数の docstring の例
|
||||
|
||||
```
|
||||
def my_awesome_function(start=None, offset=0):
|
||||
"""1970 Jan 1 00:00 UTC からの秒数を返します。
|
||||
|
||||
この関数は常に整数の秒数を返します。
|
||||
|
||||
|
||||
Args:
|
||||
start
|
||||
1970 Jan 1 00:00 UTC の代わりの開始時間
|
||||
|
||||
offset
|
||||
最初の引数からこの秒数が引かれた答えを返します
|
||||
|
||||
Returns:
|
||||
秒数を表す整数。
|
||||
|
||||
Raises:
|
||||
ValueError
|
||||
`start` あるいは `offset` が正の数ではない場合
|
||||
"""
|
||||
if start < 0 or offset < 0:
|
||||
raise ValueError('start and offset must be positive numbers.')
|
||||
|
||||
if not start:
|
||||
start = time.time()
|
||||
|
||||
return int(start - offset)
|
||||
```
|
||||
|
||||
# 例外
|
||||
|
||||
例外は例外的な状況を処理するために使われます。フローの制御のために使われるべきではありません。これは Python の「許しを請う」という規範からの逸脱です。例外をキャッチする場合、異常な状況を処理する必要があります。
|
||||
|
||||
何らかの理由で全ての例外のキャッチを使う場合は、cli.log を使って例外とスタックトレースを記録する必要があります。
|
||||
|
||||
try/except ブロックをできるだけ短くします。多数の try 文が必要な場合は、コードを再構成する必要があるかもしれません。
|
||||
|
||||
# タプル
|
||||
|
||||
1項目のタプルを定義する場合、タプルを使用していることが明らかになるように、常に末尾のカンマを含めます。暗黙的な1項目のタプルのアンパックに頼らないでください。明確なリストを使う方が良いです。
|
||||
|
||||
これはよく使用される printf 形式の書式文字列を使う場合に、特に重要です。
|
||||
|
||||
# リストと辞書
|
||||
|
||||
シーケンス形式と末尾のカンマとを区別するように YAPF を設定しました。末尾のカンマが省略されると、YAPF はシーケンスを1つの行として整形します。末尾のカンマがある場合、YAPF はシーケンスを1行1項目で整形します。
|
||||
|
||||
一般的に1行が短い定義になるようにすべきです。読みやすさと保守性を向上させるために、後からではなく早めに複数の行を分割してください。
|
||||
|
||||
# 括弧
|
||||
|
||||
過度な括弧は避けますが、括弧を使ってコードを理解しやすくします。タプルを明示的に返すか、あるいは数式の一部である場合を除き、return 文で括弧を使わないでください。
|
||||
|
||||
# 書式文字列
|
||||
|
||||
一般的に printf 形式の書式文字列を用います。例:
|
||||
|
||||
```
|
||||
name = 'World'
|
||||
print('Hello, %s!' % (name,))
|
||||
```
|
||||
|
||||
このスタイルはログモジュールで使われており、私たちはそれを広範囲で利用しており、一貫性を保つために他の場所でも採用しています。これは、私たちの気まぐれな読者の大部分である C プログラマにもおなじみのスタイルです。
|
||||
|
||||
付属の CLI モジュールは、パーセント (%) 演算子を使わずにこれらを使うことをサポートしています。詳細は、`cli.echo()` と様々な `cli.log` 関数 (例えば、`cli.log.info()`) を見てください。
|
||||
|
||||
# 内包表記とジェネレータ表記
|
||||
|
||||
内包表記とジェネレータの自由な使用を推奨しますが、あまりに複雑にしないでください。複雑になる場合は、理解しやすい for ループで代替します。
|
||||
|
||||
# ラムダ
|
||||
|
||||
使っても問題ありませんが、おそらく避けるべきです。内包表記とジェネレータを使えば、ラムダの必要性は以前ほど強くありません。
|
||||
|
||||
# 条件式
|
||||
|
||||
変数の割り当てでは問題ありませんが、そうでなければ避けるべきです。
|
||||
|
||||
条件式はコードに続く if 文です。例えば:
|
||||
|
||||
```
|
||||
x = 1 if cond else 2
|
||||
```
|
||||
|
||||
一般にこれらを関数の引数、シーケンス項目などとして使用することはお勧めできません。見落としやすくなります。
|
||||
|
||||
# デフォルト引数
|
||||
|
||||
推奨されていますが、値は不変オブジェクトでなければなりません。
|
||||
|
||||
デフォルト値に引数リストを指定する場合は、その場で変更できないオブジェクトを指定するように常に注意してください。可変オブジェクトを使うと変更は呼び出しの間で持続しますが、これは通常あなたの望むものではありませんそれがあなたのやろうとしていることであっても、他の人にとっては混乱するもので理解を妨げます。
|
||||
|
||||
悪い:
|
||||
|
||||
```
|
||||
def my_func(foo={}):
|
||||
pass
|
||||
```
|
||||
|
||||
良い:
|
||||
|
||||
```
|
||||
def my_func(foo=None):
|
||||
if not foo:
|
||||
foo = {}
|
||||
```
|
||||
|
||||
# プロパティ
|
||||
|
||||
getter および setter 関数の代わりにプロパティを常に使います。
|
||||
|
||||
```
|
||||
class Foo(object):
|
||||
def __init__(self):
|
||||
self._bar = None
|
||||
|
||||
@property
|
||||
def bar(self):
|
||||
return self._bar
|
||||
|
||||
@bar.setter
|
||||
def bar(self, bar):
|
||||
self._bar = bar
|
||||
```
|
||||
|
||||
# True/False の評価
|
||||
|
||||
一般的に、if 文で等価性を調べるのではなく、暗黙的な True/False 評価を行うべきです。
|
||||
|
||||
悪い:
|
||||
|
||||
```
|
||||
if foo == True:
|
||||
pass
|
||||
|
||||
if bar == False:
|
||||
pass
|
||||
```
|
||||
|
||||
良い:
|
||||
|
||||
```
|
||||
if foo:
|
||||
pass
|
||||
|
||||
if not bar:
|
||||
pass
|
||||
```
|
||||
|
||||
# デコレータ
|
||||
|
||||
適切な時に使ってください。理解に役立つ時を除き、魔法の(ように見える技巧の)使いすぎは避けるようにしてください。
|
||||
|
||||
# スレッドとマルチプロセス
|
||||
|
||||
避けるべきです。これが必要な場合は、私たちがコードをマージする前に十分な理由を述べる必要があります。
|
||||
|
||||
# 強力な機能
|
||||
|
||||
Python は非常に柔軟な言語で、独自のメタクラス、バイトコードへのアクセス、実行中コンパイル、動的な継承、オブジェクトの親の変更、インポートハック、リフレクション、システム内部の変更など、多くの素晴らしい機能を提供します。
|
||||
|
||||
これらを使わないでください。
|
||||
|
||||
パフォーマンスは私たちにとって重要な関心ごとではなく、コードのわかりやすさに関心があります。私たちは、コードベースを1日か2日しかいじっていない人が利用できるようにしたいです。これらの機能は一般的に理解のしやすさを犠牲にするため、より高速あるいはよりコンパクトなコードよりも、容易に理解できるコードの方が望ましいです。
|
||||
|
||||
一部の標準ライブラリモジュールはこれらの手法を使っており、これらのモジュールを利用しても問題ありません。ただし、それらを使う時には、読みやすさと理解のしやすさを忘れないでください。
|
||||
|
||||
# 型アノテーション付きコード
|
||||
|
||||
今のところ型アノテーションシステムを使っていないため、コードにアノテーションをつけないようにしてください。将来的にはこれを再検討する可能性があります。
|
||||
|
||||
# 関数の長さ
|
||||
|
||||
小さくて焦点のあった関数にしてください。
|
||||
|
||||
長い関数が時には適切であることを理解しているので、関数の長さには厳密な制限はありません。関数が約40行を超える場合は、プログラムの構造を損なわずに分割できるかどうかを検討してください。
|
||||
|
||||
今のところ長い関数が完全に機能するとしても、数か月でそれを変更する人が新しい挙動を追加するかもしれません。これにより見つけにくいバグが発生するかもしれません。関数を短くかつシンプルにすることで、他の人がコードを読んで修正しやすくします。
|
||||
|
||||
幾つかのコードで作業をすると、長く複雑な関数を見つけるかもしれません。既存コードを変更することを怖がらないでください: もし、難しいことが判明したり、エラーがデバッグしづらいとわかったり、いくつかの異なるコンテキストで一部を使いたいような関数を扱っている場合、関数を小さくてより扱いやすい単位に分割することを検討してください。
|
||||
|
||||
# FIXME
|
||||
|
||||
FIXME をコードに残しても構いません。なぜでしょうか？このコードを文章化しないままにするよりも、少なくとも考え抜く必要がある(あるいは混乱している)コードの一部を文章化するように奨励する方が、このコードを文章化しないままにするよりも良いです。
|
||||
|
||||
全ての FIXME は以下のように書式化されるべきです:
|
||||
|
||||
```
|
||||
FIXME(username): 何々機能が完了したらこのコードを再検討する。
|
||||
```
|
||||
|
||||
...username はあなたの GitHub のユーザ名です。
|
||||
|
||||
# テスト
|
||||
|
||||
統合テストと単体テストの組み合わせを使ってコードが可能な限りバグが無いようにします。全てのテストは `lib/python/qmk/tests/` にあります。`qmk pytest` を使って全てのテストを実行することができます。
|
||||
|
||||
これを書いている時点では、テストは全く完全なものではありません。現在のテストを見て、テストされていない状況のための新しいテストケースを書くことは、コードベースに精通し、QMK に貢献するという両方の点で素晴らしい方法です。
|
||||
|
||||
## 統合テスト
|
||||
|
||||
統合テストは `lib/python/qmk/tests/test_cli_commands.py` にあります。ここで実際に CLI コマンドが実行され、全体的な動作が検証されます。[`subprocess`](https://docs.python.org/3.6/library/subprocess.html#module-subprocess) を使って各 CLI コマンドを起動し、正しく動作するかを判断するために出力とリターンコードの組み合わせを使います。
|
||||
|
||||
## ユニットテスト
|
||||
|
||||
`lib/python/qmk/tests/` 内の他の `test_*.py` ファイルはユニットテストを含みます。`lib/python/qmk/` 内の個々の関数のテストをここに書くことができます。一般的にこれらのファイルはモジュールに基づいて名前を付けられ、ドットはアンダースコアで置き換えられます。
|
||||
|
||||
これを書いている時点では、テストのためのモックを作っていません。これを変更する手伝いをしたい場合は、[issue を開く](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) か [Discord の #cli に参加](https://discord.gg/heQPAgy)し、そこで会話を開始してください。
|
||||
@ -1,54 +0,0 @@
|
||||
# 互換性のあるマイクロコントローラ
|
||||
|
||||
<!---
|
||||
original document: 0.14.14:docs/compatible_microcontrollers.md
|
||||
git diff 0.14.14 HEAD -- docs/compatible_microcontrollers.md | cat
|
||||
-->
|
||||
|
||||
QMK は十分な容量のフラッシュメモリを備えた USB 対応 AVR または ARM マイクロコントローラで実行されます - 一般的に 32kB 以上ですが、ほとんどの機能を無効にすると*ほんの* 16kB に詰め込むことができます。
|
||||
|
||||
## Atmel AVR
|
||||
|
||||
以下は、USB スタックとして [LUFA](https://www.fourwalledcubicle.com/LUFA.php) を使います:
|
||||
|
||||
* [ATmega16U2](https://www.microchip.com/wwwproducts/en/ATmega16U2) / [ATmega32U2](https://www.microchip.com/wwwproducts/en/ATmega32U2)
|
||||
* [ATmega16U4](https://www.microchip.com/wwwproducts/en/ATmega16U4) / [ATmega32U4](https://www.microchip.com/wwwproducts/en/ATmega32U4)
|
||||
* [AT90USB64](https://www.microchip.com/wwwproducts/en/AT90USB646) / [AT90USB128](https://www.microchip.com/wwwproducts/en/AT90USB1286)
|
||||
* [AT90USB162](https://www.microchip.com/wwwproducts/en/AT90USB162)
|
||||
|
||||
組み込みの USB インターフェースを持たない、いくつかの MCU は代わりに [V-USB](https://www.obdev.at/products/vusb/index.html) を使います:
|
||||
|
||||
* [ATmega32A](https://www.microchip.com/wwwproducts/en/ATmega32A)
|
||||
* [ATmega328P](https://www.microchip.com/wwwproducts/en/ATmega328P)
|
||||
* [ATmega328](https://www.microchip.com/wwwproducts/en/ATmega328)
|
||||
|
||||
## ARM
|
||||
|
||||
[ChibiOS](https://www.chibios.org) がサポートする USB 付きの ARM チップを使うこともできます。ほとんどのチップには十分な容量のフラッシュメモリがあります。動作するとわかっているのは:
|
||||
|
||||
### STMicroelectronics (STM32)
|
||||
|
||||
* [STM32F0x2](https://www.st.com/en/microcontrollers-microprocessors/stm32f0x2.html)
|
||||
* [STM32F103](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html)
|
||||
* [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html)
|
||||
* [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html)
|
||||
* [STM32F405](https://www.st.com/en/microcontrollers-microprocessors/stm32f405-415.html)
|
||||
* [STM32F407](https://www.st.com/en/microcontrollers-microprocessors/stm32f407-417.html)
|
||||
* [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html)
|
||||
* [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html)
|
||||
* [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html)
|
||||
* [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html)
|
||||
* [STM32L412](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html)
|
||||
* [STM32L422](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html)
|
||||
* [STM32L433](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html)
|
||||
* [STM32L443](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html)
|
||||
|
||||
### NXP (Kinetis)
|
||||
|
||||
* [MKL26Z64](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/kl-series-cortex-m0-plus/kinetis-kl2x-72-96-mhz-usb-ultra-low-power-microcontrollers-mcus-based-on-arm-cortex-m0-plus-core:KL2x)
|
||||
* [MK20DX128](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k2x-usb/kinetis-k20-50-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-based-on-arm-cortex-m4-core:K20_50)
|
||||
* [MK20DX256](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k2x-usb/kinetis-k20-72-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-mcus-based-on-arm-cortex-m4-core:K20_72)
|
||||
|
||||
## Atmel ATSAM
|
||||
|
||||
Atmel の ATSAM マイクロコントローラの一つである、[Massdrop keyboards](https://github.com/qmk/qmk_firmware/tree/master/keyboards/massdrop) で使用されている [ATSAMD51J18A](https://www.microchip.com/wwwproducts/en/ATSAMD51J18A) には限定的なサポートがあります。
|
||||
@ -1,410 +0,0 @@
|
||||
# QMK の設定
|
||||
|
||||
<!---
|
||||
original document: 0.13.17:docs/config_options.md
|
||||
git diff 0.13.17 HEAD -- docs/config_options.md | cat
|
||||
-->
|
||||
|
||||
QMK はほぼ無制限に設定可能です。可能なところはいかなるところでも、やりすぎな程、ユーザーがコードサイズを犠牲にしてでも彼らのキーボードをカスタマイズをすることを許しています。ただし、このレベルの柔軟性により設定が困難になります。
|
||||
|
||||
QMK には主に２種類の設定ファイルがあります- `config.h` と `rules.mk`。これらのファイルは QMK の様々なレベルに存在し、同じ種類の全てのファイルは最終的な設定を構築するために組み合わされます。最低の優先度から最高の優先度までのレベルは以下の通りです:
|
||||
|
||||
* QMK デフォルト
|
||||
* キーボード
|
||||
* フォルダ (最大5レべルの深さ)
|
||||
* キーマップ
|
||||
|
||||
## QMK デフォルト
|
||||
|
||||
QMK での全ての利用可能な設定にはデフォルトがあります。その設定がキーボード、フォルダ、あるいはキーマップレべルで設定されない場合、これが使用される設定です。
|
||||
|
||||
## キーボード
|
||||
|
||||
このレベルにはキーボード全体に適用される設定オプションが含まれています。一部の設定は、リビジョンあるいはほとんどのキーマップで変更されません。他の設定はこのキーボードのデフォルトに過ぎず、フォルダあるいはキーマップによって上書きされる可能性があります。
|
||||
|
||||
## フォルダ
|
||||
|
||||
一部のキーボードには、異なるハードウェア構成のためのフォルダとサブフォルダがあります。ほとんどのキーボードは深さ1のフォルダのみですが、QMK は最大深さ5のフォルダの構造をサポートします。各フォルダは、最終的な設定に組み込まれる独自の `config.h` と `rules.mk` ファイルを持つことができます。
|
||||
|
||||
## キーマップ
|
||||
|
||||
このレベルには特定のキーマップのための全てのオプションが含まれています。以前の定義を上書きしたい場合は、`#undef <variable>` を使って定義を解除し、エラー無しで再定義することができます。
|
||||
|
||||
# `config.h` ファイル
|
||||
|
||||
これは最初に include されるものの 1 つである C ヘッダファイルで、プロジェクト全体(もし含まれる場合)にわたって持続します。多くの変数をここで設定し、他の場所からアクセスすることができます。`config.h` ファイルでは、以下のもの以外の、他の `config.h` ファイルやその他のファイルの include をしないでください:
|
||||
|
||||
```c
|
||||
#include "config_common.h"
|
||||
```
|
||||
|
||||
|
||||
## ハードウェアオプション
|
||||
* `#define VENDOR_ID 0x1234`
|
||||
* VID を定義します。ほとんどの DIY プロジェクトにおいて、任意のものを定義できます
|
||||
* `#define PRODUCT_ID 0x5678`
|
||||
* PID を定義します。ほとんどの DIY プロジェクトでは、任意のものを定義できます
|
||||
* `#define DEVICE_VER 0`
|
||||
* デバイスのバージョンを定義します (多くの場合リビジョンに使われます)
|
||||
* `#define MANUFACTURER Me`
|
||||
* 一般的に、誰もしくはどのブランドがボードを作成したか
|
||||
* `#define PRODUCT Board`
|
||||
* キーボードの名前
|
||||
* `#define MATRIX_ROWS 5`
|
||||
* キーボードのマトリックスの行の数
|
||||
* `#define MATRIX_COLS 15`
|
||||
* キーボードのマトリックスの列の数
|
||||
* `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }`
|
||||
* 行のピン、上から下へ
|
||||
* `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }`
|
||||
* 列のピン、左から右へ
|
||||
* `#define MATRIX_IO_DELAY 30`
|
||||
* マトリックスピン状態の変更と値の読み取り間のマイクロ秒単位の遅延
|
||||
* `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }`
|
||||
* 参考として、キーボードで使われていないピン
|
||||
* `#define MATRIX_HAS_GHOST`
|
||||
* マトリックスにゴーストがあるか(ありそうにないか)定義します
|
||||
* `#define DIODE_DIRECTION COL2ROW`
|
||||
* COL2ROW あるいは ROW2COL - マトリックスがどのように設定されているか。COL2ROW は、スイッチとロウ(行)ラインの間にダイオードが黒い印をロウ(行)ラインに向けて置いてあることを意味します。
|
||||
* `#define DIRECT_PINS { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
|
||||
* ロウ(行)ラインとカラム(列)ラインにマップされているピンを左から右に。各スイッチが個別のピンとグラウンドに接続されているマトリックスを定義します。
|
||||
* `#define AUDIO_VOICES`
|
||||
* (循環させるために)代替音声を有効にします
|
||||
* `#define C4_AUDIO`
|
||||
* ピン C4 のオーディオを有効にします
|
||||
* 非推奨。`#define AUDIO_PIN C4` を使ってください
|
||||
* `#define C5_AUDIO`
|
||||
* ピン C5 のオーディオを有効にします
|
||||
* 非推奨。`#define AUDIO_PIN C5` を使ってください
|
||||
* `#define C6_AUDIO`
|
||||
* ピン C6 のオーディオを有効にします
|
||||
* 非推奨。`#define AUDIO_PIN C6` を使ってください
|
||||
* `#define B5_AUDIO`
|
||||
* ピン B5 のオーディオを有効にします (C ピンの1つとともに B ピンの1つが有効にされている場合、疑似ステレオが有効にされます)
|
||||
* 非推奨。もし `AUDIO_PIN` で `C` ピンを有効にしている場合は、`#define AUDIO_PIN_ALT B5` を使い、そうでなければ `#define AUDIO_PIN B5` を使います。
|
||||
* `#define B6_AUDIO`
|
||||
* ピン B6 のオーディオを有効にします (C ピンの1つとともに B ピンの1つが有効にされている場合、疑似ステレオが有効にされます)
|
||||
* 非推奨。もし `AUDIO_PIN` で `C` ピンを有効にしている場合は、`#define AUDIO_PIN_ALT B6` を使い、そうでなければ `#define AUDIO_PIN B6` を使います。
|
||||
* `#define B7_AUDIO`
|
||||
* ピン B7 のオーディオを有効にします (C ピンの1つとともに B ピンの1つが有効にされている場合、疑似ステレオが有効にされます)
|
||||
* 非推奨。もし `AUDIO_PIN` で `C` ピンを有効にしている場合は、`#define AUDIO_PIN_ALT B7` を使い、そうでなければ `#define AUDIO_PIN B7` を使います。
|
||||
* `#define BACKLIGHT_PIN B7`
|
||||
* バックライトのピン
|
||||
* `#define BACKLIGHT_LEVELS 3`
|
||||
* バックライトのレベル数 (off を除いて最大31)
|
||||
* `#define BACKLIGHT_BREATHING`
|
||||
* バックライトのブレスを有効にします
|
||||
* `#define BREATHING_PERIOD 6`
|
||||
* 1つのバックライトの "ブレス" の長さの秒数
|
||||
* `#define DEBOUNCE 5`
|
||||
* ピンの値を読み取る時の遅延 (5がデフォルト)
|
||||
* `#define LOCKING_SUPPORT_ENABLE`
|
||||
* メカニカルロックのサポート。キーマップで KC_LCAP、KC_LNUM そして KC_LSCR を使えるようにします
|
||||
* `#define LOCKING_RESYNC_ENABLE`
|
||||
* キーボードの LED の状態をスイッチの状態と一致させ続けようとします
|
||||
* `#define IS_COMMAND() (get_mods() == MOD_MASK_SHIFT)`
|
||||
* マジックコマンドの使用を可能にするキーの組み合わせ (デバッグに便利です)
|
||||
* `#define USB_MAX_POWER_CONSUMPTION 500`
|
||||
* デバイスの USB 経由の最大電力(mA) を設定します (デフォルト: 500)
|
||||
* `#define USB_POLLING_INTERVAL_MS 10`
|
||||
* キーボード、マウス および 共有 (NKRO/メディアキー) インタフェースのための USB ポーリングレートをミリ秒で設定します
|
||||
* `#define USB_SUSPEND_WAKEUP_DELAY 0`
|
||||
* ウェイクアップパケットを送信した後で一時停止するミリ秒を設定します
|
||||
* `#define F_SCL 100000L`
|
||||
* I2C を使用するキーボードのための I2C クロックレート速度を設定します。デフォルトは `400000L` ですが、`split_common` を使っているキーボードは別でデフォルトは `100000L` です。
|
||||
|
||||
## 無効にできる機能
|
||||
|
||||
これらのオプションを定義すると、関連する機能が無効になり、コードサイズを節約できます。
|
||||
|
||||
* `#define NO_DEBUG`
|
||||
* デバッグを無効にします
|
||||
* `#define NO_PRINT`
|
||||
* hid_listen を使った出力やデバッグを無効にします
|
||||
* `#define NO_ACTION_LAYER`
|
||||
* レイヤーを無効にします
|
||||
* `#define NO_ACTION_TAPPING`
|
||||
* タップダンスと他のタップ機能を無効にします
|
||||
* `#define NO_ACTION_ONESHOT`
|
||||
* ワンショットモディファイアを無効にします
|
||||
* `#define NO_ACTION_MACRO`
|
||||
* `MACRO()`、`action_get_macro()` _(非推奨)_ を使う古い形式のマクロ処理を無効にします
|
||||
* `#define NO_ACTION_FUNCTION`
|
||||
* `fn_actions`、`action_function()` _(非推奨)_ を使う古い形式の関数処理を無効にします
|
||||
|
||||
## 有効にできる機能
|
||||
|
||||
これらのオプションを定義すると、関連する機能が有効になり、コードサイズが大きくなるかもしれません。
|
||||
|
||||
* `#define FORCE_NKRO`
|
||||
* NKRO をデフォルトでオンにする必要があります。これにより EEPROM の設定に関係なく、キーボードの起動時に NKRO が強制的にオンになります。NKRO は引き続きオフにできますが、キーボードを再起動すると再びオンになります。
|
||||
* `#define STRICT_LAYER_RELEASE`
|
||||
* キーリリースがどのレイヤーから来たのかを覚えるのではなく、現在のレイヤースタックを使って強制的に評価されるようにします (高度なケースに使われます)
|
||||
|
||||
## 設定可能な挙動 :id=behaviors-that-can-be-configured
|
||||
|
||||
* `#define TAPPING_TERM 200`
|
||||
* タップがホールドになるまでの時間。
|
||||
* `#define TAPPING_TERM_PER_KEY`
|
||||
* キーごとの `TAPPING_TERM` 設定の処理を有効にします
|
||||
* `#define RETRO_TAPPING`
|
||||
* 押下とリリースの間に他のキーによる中断がなければ、TAPPING_TERM の後であってもとにかくタップします
|
||||
* 詳細は [Retro Tapping](ja/tap_hold.md#retro-tapping) を見てください
|
||||
* `#define RETRO_TAPPING_PER_KEY`
|
||||
* キーごとの `RETRO_TAPPING` 設定の処理を有効にします
|
||||
* `#define TAPPING_TOGGLE 2`
|
||||
* トグルを引き起こす前のタップ数
|
||||
* `#define PERMISSIVE_HOLD`
|
||||
* `TAPPING_TERM` にヒットしていなくても、リリースする前に別のキーが押されると、タップとホールドキーがホールドを引き起こします
|
||||
* 詳細は [Permissive Hold](ja/tap_hold.md#permissive-hold) を見てください
|
||||
* `#define PERMISSIVE_HOLD_PER_KEY`
|
||||
* キーごとの `PERMISSIVE_HOLD` 設定の処理を有効にします
|
||||
* `#define TAPPING_FORCE_HOLD`
|
||||
* タップされた直後に、デュアルロールキーを修飾子として使用できるようにします
|
||||
* [Tapping Force Hold](ja/tap_hold.md#tapping-force-hold)を見てください
|
||||
* タップトグル機能を無効にします (`TT` あるいは One Shot Tap Toggle)
|
||||
* `#define TAPPING_FORCE_HOLD_PER_KEY`
|
||||
* キーごとの `TAPPING_FORCE_HOLD` 設定処理を有効にします。
|
||||
* `#define LEADER_TIMEOUT 300`
|
||||
* リーダーキーがタイムアウトするまでの時間
|
||||
* タイムアウトする前にシーケンスを終了できない場合は、タイムアウトの設定を増やす必要があるかもしれません。あるいは、`LEADER_PER_KEY_TIMING` オプションを有効にすると良いでしょう。これは各キーがタップされた後でタイムアウトを再設定します。
|
||||
* `#define LEADER_PER_KEY_TIMING`
|
||||
* 全体では無く各キーを押すたびに実行されるリーダーキーコードのタイマーを設定します
|
||||
* `#define LEADER_KEY_STRICT_KEY_PROCESSING`
|
||||
* Mod-Tap および Layer-Tap キーコードのためのキーコードフィルタリングを無効にします。例えば、これを有効にすると、`KC_A` を使いたい場合は `MT(MOD_CTL, KC_A)` を指定する必要があります。
|
||||
* `#define ONESHOT_TIMEOUT 300`
|
||||
* ワンショットがタイムアウトするまでの時間
|
||||
* `#define ONESHOT_TAP_TOGGLE 2`
|
||||
* ワンショットトグルが引き起こされるまでのタップ数
|
||||
* `#define COMBO_TERM 200`
|
||||
* コンボキーが検出されるまでの時間。定義されていない場合は、デフォルトは `TAPPING_TERM` です。
|
||||
* `#define TAP_CODE_DELAY 100`
|
||||
* 適切な登録に問題がある場合(VUSB ボードで珍しくない)、`register_code` と `unregister_code` の間の遅延を設定します。値はミリ秒です。
|
||||
* `#define TAP_HOLD_CAPS_DELAY 80`
|
||||
* MacOS で特別な処理が行われるため、`KC_CAPSLOCK` を使う時にタップホールドキー (`LT`, `MT`) に遅延を設定します。この値はミリ秒で、定義されていない場合はデフォルトは80msです。macOS については、これを200以上に設定すると良いでしょう。
|
||||
|
||||
## RGB ライト設定 :id=rgb-light-configuration
|
||||
|
||||
* `#define RGB_DI_PIN D7`
|
||||
* WS2812 の DI 端子につなぐピン
|
||||
* `#define RGBLIGHT_LAYERS`
|
||||
* オンとオフを切り替えることができる [ライトレイヤー](ja/feature_rgblight.md?id=lighting-layers) を定義できます。現在のキーボードレイヤーまたは Caps Lock 状態を表示するのに最適です。
|
||||
* `#define RGBLIGHT_MAX_LAYERS`
|
||||
* デフォルトは8です。もしさらに [ライトレイヤー](ja/feature_rgblight.md?id=lighting-layers) が必要であれば、32まで拡張できます。
|
||||
* メモ: 最大値を大きくするとファームウェアサイズが大きくなり、分割キーボードで同期が遅くなります。
|
||||
* `#define RGBLIGHT_LAYER_BLINK`
|
||||
* 指定されたミリ秒の間、ライトレイヤーを [点滅](ja/feature_rgblight.md?id=lighting-layer-blink) する機能を追加します(例えば、アクションを確認するため)。
|
||||
* `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF`
|
||||
* 定義されている場合、RGB ライトがオフになっている場合でも [ライトレイヤー](ja/feature_rgblight?id=overriding-rgb-lighting-onoff-status) が表示されます。
|
||||
* `#define RGBLED_NUM 12`
|
||||
* LED の数
|
||||
* `#define RGBLIGHT_SPLIT`
|
||||
* 分割キーボードの左半分の RGB LED の出力を右半分の RGB LED の入力につなげるかわりに、それぞれの側で個別にコントローラの出力ピンが直接 RGB LED の入力に繋がっているときは、この定義が必要です。
|
||||
* `#define RGBLED_SPLIT { 6, 6 }`
|
||||
* 分割キーボードの各半分の `RGB_DI_PIN` に直接配線されている接続されている LED の数
|
||||
* 最初の値は左半分の LED の数を示し、2番目の値は右半分です。
|
||||
* RGBLED_SPLIT が定義されている場合、RGBLIGHT_SPLIT は暗黙的に定義されます。
|
||||
* `#define RGBLIGHT_HUE_STEP 12`
|
||||
* 色相の増減時のステップ単位
|
||||
* `#define RGBLIGHT_SAT_STEP 25`
|
||||
* 彩度の増減時のステップ単位
|
||||
* `#define RGBLIGHT_VAL_STEP 12`
|
||||
* 値(明度)の増減時のステップ単位
|
||||
* `#define RGBW`
|
||||
* RGBW LED のサポートを有効にします
|
||||
|
||||
## マウスキーオプション
|
||||
|
||||
* `#define MOUSEKEY_INTERVAL 20`
|
||||
* `#define MOUSEKEY_DELAY 0`
|
||||
* `#define MOUSEKEY_TIME_TO_MAX 60`
|
||||
* `#define MOUSEKEY_MAX_SPEED 7`
|
||||
* `#define MOUSEKEY_WHEEL_DELAY 0`
|
||||
|
||||
## 分割キーボードオプション
|
||||
|
||||
分割キーボード固有のオプション。あなたの rules.mk に 'SPLIT_KEYBOARD = yes' が有ることを確認してください。
|
||||
|
||||
* `SPLIT_TRANSPORT = custom`
|
||||
* 標準の分割通信ルーチンをカスタムのものに置き換えることができます。現在、ARM ベースの分割キーボードはこれを使わなければなりません。
|
||||
|
||||
### 左右の設定
|
||||
|
||||
1つ覚えておかなければならないことは、USB ポートが接続されている側が常にマスター側であるということです。USB に接続されていない側はスレーブです。
|
||||
|
||||
分割キーボードの左右を設定するには、幾つかの異なる方法があります (優先度の順にリストされています):
|
||||
|
||||
1. `SPLIT_HAND_PIN` を設定します: 左右を決定するためにピンを読み込みます。ピンが high の場合、それが左側です。low であれば、その半分側が右側であると決定されます。
|
||||
2. `EE_HANDS` を設定し、各半分に `eeprom-lefthand.eep`/`eeprom-righthand.eep` を書き込みます
|
||||
* DFU ブートローダを搭載したボードでは、これらの EEPROM ファイルを書き込むために `:dfu-split-left`/`:dfu-split-right` を使うことができます
|
||||
* Caterina ブートローダを搭載したボード (標準的な Pro Micros など)では、`:avrdude-split-left`/`:avrdude-split-right` を使ってください
|
||||
* ARM DFU ブートローダを搭載したボード (Proton C など)では、`:dfu-util-split-left`/`:dfu-util-split-right` を使ってください
|
||||
3. `MASTER_RIGHT` を設定します: USB ポートに差し込まれた側はマスター側で右側であると決定されます(デフォルトの逆)
|
||||
4. デフォルト: USB ポートに差し込まれている側がマスター側であり、左側であると見なされます。スレーブ側は右側です
|
||||
|
||||
#### 左右を定義します
|
||||
|
||||
* `#define SPLIT_HAND_PIN B7`
|
||||
* high/low ピンを使って左右を決定します。low = 右手、high = 左手。`B7` を使っているピンに置き換えます。これはオプションで、`SPLIT_HAND_PIN` が未定義のままである場合、EE_HANDS メソッドまたは標準の Let's Splitが使っている MASTER_LEFT / MASTER_RIGHT 定義をまだ使うことができます。
|
||||
|
||||
* `#define SPLIT_HAND_MATRIX_GRID <out_pin>,<in_pin>`
|
||||
* 左右はキーマトリックスのキースイッチが存在しない交点を使って決定されます。通常、この交点が短絡している(ローレベル)のときに左側と見なされます。もし `#define SPLIT_HAND_MATRIX_GRID_LOW_IS_RIGHT` が定義されている場合は、ローレベルの時に右側と決定されます。
|
||||
|
||||
* `#define EE_HANDS` (`SPLIT_HAND_PIN` と `SPLIT_HAND_MATRIX_GRID` が定義されていない場合のみ動作します)
|
||||
* `eeprom-lefthand.eep`/`eeprom-righthand.eep` がそれぞれの半分に書き込まれた後で、EEPROM 内に格納されている左右の設定の値を読み込みます。
|
||||
|
||||
* `#define MASTER_RIGHT`
|
||||
* マスター側が右側と定義されます。
|
||||
|
||||
### 他のオプション
|
||||
|
||||
* `#define USE_I2C`
|
||||
* Serial の代わりに I2C を使う場合 (デフォルトは serial)
|
||||
|
||||
* `#define SOFT_SERIAL_PIN D0`
|
||||
* serial を使う場合、これを定義します。`D0` あるいは `D1`,`D2`,`D3`,`E6`。
|
||||
|
||||
* `#define MATRIX_ROW_PINS_RIGHT { <row pins> }`
|
||||
* `#define MATRIX_COL_PINS_RIGHT { <col pins> }`
|
||||
* 右半分に左半分と異なるピン配置を指定したい場合は、`MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT` を定義することができます。現在のところ、`MATRIX_ROW_PINS` のサイズは `MATRIX_ROW_PINS_RIGHT` と同じでなければならず、列の定義も同様です。
|
||||
|
||||
* `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
|
||||
* 右半分に左半分と異なる直接ピン配置を指定したい場合は、`DIRECT_PINS_RIGHT` を定義することができます。現在のところ、`DIRECT_PINS` のサイズは `DIRECT_PINS_RIGHT` と同じでなければなりません。
|
||||
|
||||
* `#define RGBLED_SPLIT { 6, 6 }`
|
||||
* [RGB ライト設定](#rgb-light-configuration)を見てください。
|
||||
|
||||
* `#define SELECT_SOFT_SERIAL_SPEED <speed>` (デフォルトの速度は1です)
|
||||
* serial 通信を使う時のプロトコルの速度を設定します。
|
||||
* 速度:
|
||||
* 0: 約 189kbps (実験目的のみ)
|
||||
* 1: 約 137kbps (デフォルト)
|
||||
* 2: 約 75kbps
|
||||
* 3: 約 39kbps
|
||||
* 4: 約 26kbps
|
||||
* 5: 約 20kbps
|
||||
|
||||
* `#define SPLIT_USB_DETECT`
|
||||
* マスタ/スレーブを委任する時に(タイムアウト付きで) USB 接続を検出します
|
||||
* ARM についてはデフォルトの挙動
|
||||
* AVR Teensy については必須
|
||||
|
||||
* `#define SPLIT_USB_TIMEOUT 2000`
|
||||
* `SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合の最大タイムアウト
|
||||
|
||||
* `#define SPLIT_USB_TIMEOUT_POLL 10`
|
||||
* `SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合のポーリング頻度
|
||||
|
||||
# `rules.mk` ファイル
|
||||
|
||||
これは、トップレベルの `Makefile` から include される [make](https://www.gnu.org/software/make/manual/make.html) ファイルです。これは特定の機能を有効または無効にするだけでなく、コンパイルする MCU に関する情報を設定するために使われます。
|
||||
|
||||
## ビルドオプション
|
||||
|
||||
* `DEFAULT_FOLDER`
|
||||
* キーボードに1つ以上のサブフォルダがある場合にデフォルトのフォルダを指定するために使われます。
|
||||
* `FIRMWARE_FORMAT`
|
||||
* ビルドの後でルート `qmk_firmware` フォルダにコピーされる形式 (bin, hex) を定義します。
|
||||
* `SRC`
|
||||
* コンパイル・リンクリストにファイルを追加するために使われます。
|
||||
* `LIB_SRC`
|
||||
* コンパイル・リンクリストにライブラリとしてファイルを追加するために使われます。
|
||||
`LIB_SRC` で指定されたファイルは、`SRC` で指定されたファイルの後にリンクされます。
|
||||
例えば、次のように指定した場合:
|
||||
```
|
||||
SRC += a.c
|
||||
LIB_SRC += lib_b.c
|
||||
SRC += c.c
|
||||
LIB_SRC += lib_d.c
|
||||
```
|
||||
リンク順は以下の通りです。
|
||||
```
|
||||
... a.o c.o ... lib_b.a lib_d.a ...
|
||||
```
|
||||
* `LAYOUTS`
|
||||
* このキーボードがサポートする[レイアウト](ja/feature_layouts.md)のリスト
|
||||
* `LTO_ENABLE`
|
||||
* キーボードをコンパイルする時に、Link Time Optimization (LTO) を有効にします。これは処理に時間が掛かりますが、コンパイルされたサイズを大幅に減らします (そして、ファームウェアが小さいため、追加の時間は分からないくらいです)。
|
||||
ただし、LTO が有効な場合、古い TMK のマクロと関数の機能が壊れるため、自動的にこれらの機能を無効にします。これは `NO_ACTION_MACRO` と `NO_ACTION_FUNCTION` を自動的に定義することで行われます。(メモ: これは QMK の [マクロ](ja/feature_macros.md) と [レイヤー](ja/feature_layers.md) には影響を与えません。)
|
||||
|
||||
## AVR MCU オプション
|
||||
* `MCU = atmega32u4`
|
||||
* `F_CPU = 16000000`
|
||||
* `ARCH = AVR8`
|
||||
* `F_USB = $(F_CPU)`
|
||||
* `OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT`
|
||||
* `BOOTLOADER = atmel-dfu` と以下のオプション:
|
||||
* `atmel-dfu`
|
||||
* `lufa-dfu`
|
||||
* `qmk-dfu`
|
||||
* `halfkay`
|
||||
* `caterina`
|
||||
* `bootloadHID`
|
||||
* `USBasp`
|
||||
|
||||
## 機能オプション :id=feature-options
|
||||
|
||||
これらを使って特定の機能のビルドを有効または無効にします。有効にすればするほどファームウェアが大きくなり、MCU には大きすぎるファームウェアを構築するリスクがあります。
|
||||
|
||||
* `BOOTMAGIC_ENABLE`
|
||||
* ブートマジックライトを有効にします
|
||||
* `MOUSEKEY_ENABLE`
|
||||
* マウスキー
|
||||
* `EXTRAKEY_ENABLE`
|
||||
* オーディオ制御とシステム制御
|
||||
* `CONSOLE_ENABLE`
|
||||
* デバッグ用コンソール
|
||||
* `COMMAND_ENABLE`
|
||||
* デバッグ及び設定用のコマンド
|
||||
* `COMBO_ENABLE`
|
||||
* キーコンボ機能
|
||||
* `NKRO_ENABLE`
|
||||
* USB N-キーロールオーバー - これが動作しない場合は、ここを見てください: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
|
||||
* `AUDIO_ENABLE`
|
||||
* オーディオサブシステムを有効にします。
|
||||
* `RGBLIGHT_ENABLE`
|
||||
* キーボードアンダーライト機能を有効にします
|
||||
* `LEADER_ENABLE`
|
||||
* リーダーキーコードを有効にします
|
||||
* `MIDI_ENABLE`
|
||||
* MIDI 制御
|
||||
* `UNICODE_ENABLE`
|
||||
* Unicode
|
||||
* `BLUETOOTH`
|
||||
* 現在のオプションは、AdafruitBLE、RN42
|
||||
* `SPLIT_KEYBOARD`
|
||||
* 分割キーボード (let's split や bakingpy のキーボードのようなデュアル MCU) のサポートを有効にし、quantum/split_common にある全ての必要なファイルをインクルードします
|
||||
* `CUSTOM_MATRIX`
|
||||
* 標準マトリックス走査ルーチンを独自のものに置き換えることができます。
|
||||
* `DEBOUNCE_TYPE`
|
||||
* 標準キーデバウンスルーチンを代替または独自のものに置き換えることができます。
|
||||
* `WAIT_FOR_USB`
|
||||
* キーボードが起動する前に、USB 接続が確立されるのをキーボードに待機させます
|
||||
* `NO_USB_STARTUP_CHECK`
|
||||
* キーボードの起動後の usb サスペンドチェックを無効にします。通常、キーボードはタスクが実行される前にホストがウェイク アップするのを待ちます。分割キーボードは半分はウェイクアップコールを取得できませんが、マスタにコマンドを送信する必要があるため、役に立ちます。
|
||||
|
||||
## USB エンドポイントの制限
|
||||
|
||||
USB 経由でサービスを提供するために、QMK は USB エンドポイントを使う必要があります。
|
||||
これらは有限なリソースです: 各マイクロコントローラは特定の数しか持ちません。
|
||||
これは一緒に有効にできる機能を制限します。
|
||||
利用可能なエンドポイントを超えると、ビルドエラーをひきおこします。
|
||||
|
||||
以下の機能は個別のエンドポイントを必要とするかもしれません:
|
||||
|
||||
* `MOUSEKEY_ENABLE`
|
||||
* `EXTRAKEY_ENABLE`
|
||||
* `CONSOLE_ENABLE`
|
||||
* `NKRO_ENABLE`
|
||||
* `MIDI_ENABLE`
|
||||
* `RAW_ENABLE`
|
||||
* `VIRTSER_ENABLE`
|
||||
|
||||
エンドポイントの使用率を向上させるために、HID 機能を組み合わせて1つのエンドポイントを使うようにすることができます。
|
||||
デフォルトでは、`MOUSEKEY`、`EXTRAKEY` および `NKRO` が単一のエンドポイントに結合されます。
|
||||
|
||||
基本キーボード機能も、`KEYBOARD_SHARED_EP = yes` を設定することで同じエンドポイントに結合することができます。
|
||||
これによりもう1つのエンドポイントが解放されますが、一部の BIOS ではブートキーボードプロトコルの切り替えを実装しないため、キーボードが動作しなくなるかもしれません。
|
||||
|
||||
マウスの結合も、ブートマウス互換性を破壊します。
|
||||
この機能が必要な場合は、`MOUSE_SHARED_EP = no` を設定することで、マウスを結合しないようにすることができます。
|
||||
@ -1,67 +0,0 @@
|
||||
# QMK Configurator: ステップ・バイ・ステップ
|
||||
|
||||
<!---
|
||||
grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
|
||||
original document: 0.9.0:docs/configurator_step_by_step.md
|
||||
git diff 0.9.0 HEAD -- docs/configurator_step_by_step.md | cat
|
||||
-->
|
||||
|
||||
このページでは、QMK Configurator でファームウェアを構築する手順を説明します。
|
||||
|
||||
## ステップ 1: キーボードを選ぶ
|
||||
|
||||
ドロップダウンボックスをクリックして、キーマップを作成するキーボードを選択します。
|
||||
|
||||
?> **キーボードに複数のバージョンがある場合は、正しいバージョンを選択してください。**
|
||||
|
||||
大事なことなのでもう一度言います。
|
||||
|
||||
!> **正しいバージョンを選択してください!**
|
||||
|
||||
キーボードが QMK を搭載していると宣伝されていてもリストにない場合は、開発者がまだ作業中か、私たちがまだマージするきっかけがなかった可能性があります。
|
||||
アクティブな [プルリクエスト](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) がない場合、[qmk_firmware](https://github.com/qmk/qmk_firmware/issues)で報告して、その特定のキーボードのサポートをリクエストします。
|
||||
製作者自身の GitHub アカウントにある QMK 搭載キーボードもあります。
|
||||
それも再確認してください。
|
||||
|
||||
## ステップ2: キーボードのレイアウトを選択する
|
||||
|
||||
作成したいと思うキーマップに最も近いレイアウトを選択します。一部のキーボードには、まだ十分なレイアウトや正しいレイアウトが定義されていません。これらは将来サポートされる予定です。
|
||||
|
||||
## ステップ3: キーマップの名前を決める
|
||||
|
||||
お好みの名前をキーマップにつけます。
|
||||
|
||||
?> コンパイル時に問題が発生した場合は、もしかすると QMK ファームウェアリポジトリに既に同じ名前が存在しているのかもしれません。名前を変更してみてください。
|
||||
|
||||
## ステップ4: キーマップを定義する
|
||||
|
||||
キーコードの入力は、3つの方法のいずれかで行います。
|
||||
|
||||
1. ドラッグ・アンド・ドロップ
|
||||
2. レイアウト上の空の場所をクリックして、希望するキーコードをクリックします
|
||||
3. レイアウト上の空の場所をクリックして、キーボードの物理キーを押します
|
||||
|
||||
?> マウスをキーの上に置くと、そのキーコードの機能の短い説明文が出ます。より詳細な説明については以下を見てください:
|
||||
|
||||
* [基本的なキーコードリファレンス](ja/keycodes_basic.md)
|
||||
* [高度なキーコードリファレンス](ja/feature_advanced_keycodes.md)
|
||||
|
||||
!> 選択したレイアウトが物理的なビルドと一致しない場合は、使用していないキーは空白のままにしておきます。どのキーが使用されているかわからない場合、例えば、バックスペースキーは1つだが `LAYOUT_all` には2つのキーがある場合は、同じキーコードを両方の場所に配置してください。
|
||||
|
||||
## ステップ5: 後日のためにキーマップを保存する
|
||||
|
||||
キーマップに満足するか、または後で作業したい場合は、`Export Keymap' ボタンを押します。
|
||||
これでキーマップがあなたのコンピュータに保存されます。
|
||||
その後、`Import Keymap` ボタンを押すことで、この .json ファイルを後で読み込むことができます。
|
||||
|
||||
!> **注意:** このファイルは、kbfirmware.com またはその他のツールに使用される .json ファイルと同じ形式ではありません。これらのツールにこの .json を使用したり、QMK Configurator でこれらのツールの .json を使用しようとすると、問題が発生します。
|
||||
|
||||
## ステップ6: ファームウェアをコンパイルする
|
||||
|
||||
緑色の `Compile` ボタンを押します。
|
||||
|
||||
コンパイルが完了すると、緑色の `Download Firmware` ボタンを押すことができます。
|
||||
|
||||
## 次のステップ: キーボードに書き込む(フラッシュする)
|
||||
|
||||
[ファームウェアを書きこむ](ja/newbs_flashing.md) を参照してください。
|
||||
@ -1,32 +0,0 @@
|
||||
# Configurator トラブルシューティング
|
||||
|
||||
<!---
|
||||
grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
|
||||
original document: 0.9.0:docs/configurator_troubleshooting.md
|
||||
git diff 0.9.0 HEAD -- docs/configurator_troubleshooting.md | cat
|
||||
-->
|
||||
|
||||
## 私の .json ファイルが動きません
|
||||
|
||||
.json ファイルが QMK Configurator で作ったものの場合、おめでとうございます。バグに遭遇しました。 [qmk_configurator](https://github.com/qmk/qmk_configurator/issues) で報告してください。
|
||||
|
||||
そうでない場合は、... 他の .json ファイルを使用しないようにという、上に書いた注意書きを見逃してませんか？
|
||||
|
||||
#### レイアウトに余分なスペースがありますか？どうすればいいですか？
|
||||
|
||||
もしスペースバーが3つに分かれている場合は、全てスペースバーで埋めるのが最善の方法です。バックスペースや Shift キーについても同じことができます。
|
||||
|
||||
#### キーコードってなに？
|
||||
|
||||
以下を見てください。
|
||||
|
||||
* [基本的なキーコードリファレンス](ja/keycodes_basic.md)
|
||||
* [高度なキーコードリファレンス](ja/feature_advanced_keycodes.md)
|
||||
|
||||
#### コンパイルできません
|
||||
|
||||
キーマップの他のレイヤーを再確認して、おかしなキーが存在しないことを確認してください。
|
||||
|
||||
## 問題とバグ
|
||||
|
||||
私たちは利用者の依頼やバグレポートを常に受け入れています。[qmk_configurator](https://github.com/qmk/qmk_configurator/issues) で報告してください。
|
||||
@ -1,173 +0,0 @@
|
||||
# 貢献方法
|
||||
|
||||
<!---
|
||||
original document: 0.14.22:docs/contributing.md
|
||||
git diff 0.14.22 HEAD -- docs/contributing.md | cat
|
||||
-->
|
||||
|
||||
👍🎉 まず、これを読み貢献する時間を作ってくれてありがとうございます！🎉👍
|
||||
|
||||
サードパーティの貢献は、QMK の成長と改善に役立ちます。プルリクエストと貢献プロセスを貢献者とメンテナの両方にとって便利で簡単なものにしたいです。この目的のために、大きな変更をせずにプルリクエストが受け入れられるように貢献者向けのガイドラインをまとめました。
|
||||
|
||||
* [プロジェクトの概要](#project-overview)
|
||||
* [コーディング規約](#coding-conventions)
|
||||
* [一般的なガイドライン](#general-guidelines)
|
||||
* [行動規範は私にとって何を意味しますか？](#what-does-the-code-of-conduct-mean-for-me)
|
||||
|
||||
## この全てを読みたくはありません！単純に質問があります！
|
||||
|
||||
QMK について質問したい場合は、[OLKB Subreddit](https://reddit.com/r/olkb) あるいは [Discord](https://discord.gg/Uq7gcHh) ですることができます。
|
||||
|
||||
以下の事を覚えておいてください:
|
||||
|
||||
* 誰かがあなたの質問に答えるのに数時間掛かるかもしれません。しばらくお待ちください！
|
||||
* QMK に関わる全ての人が彼らの時間とエネルギーを提供しています。QMK に関する作業や質問への回答に対する報酬はありません。
|
||||
* できるだけ簡単に答えられるように質問してみてください。その方法が分からない場合は、以下に幾つかの良いガイドがあります:
|
||||
* https://opensource.com/life/16/10/how-ask-technical-questions
|
||||
* http://www.catb.org/esr/faqs/smart-questions.html
|
||||
|
||||
# プロジェクトの概要 :id=project-overview
|
||||
|
||||
QMK は主に C で書かれており、特定の機能と部品は C++ で書かれています。QMK は、キーボードの中の組み込みプロセッサ、特に AVR ([LUFA](https://www.fourwalledcubicle.com/LUFA.php)) と ARM ([ChibiOS](https://www.chibios.org)) を対象にしています。すでに Arduino プログラミングに精通している場合は、多くの概念と制限がおなじみのものです。QMK に貢献するには Arduino を使用した経験は必要ありません。
|
||||
|
||||
<!-- FIXME: We should include a list of resources for learning C here. -->
|
||||
|
||||
# どこで助けを得られますか？
|
||||
|
||||
助けが必要であれば、[issue を開く](https://github.com/qmk/qmk_firmware/issues) か [Discord で会話する](https://discord.gg/Uq7gcHh)ことができます。
|
||||
|
||||
# どうやって貢献することができますか？
|
||||
|
||||
以前にオープンソースに貢献したことはありませんか？ QMK で貢献がどのように機能するかが疑問ですか？ ここに簡単な説明があります！
|
||||
|
||||
0. [GitHub](https://github.com) アカウントにサインアップします。
|
||||
1. 貢献するためのキーマップをまとめるか、解決に興味がある[問題を見つける](https://github.com/qmk/qmk_firmware/issues)、あるいは追加したい[機能](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature)を見つけます。
|
||||
2. 問題に関連付けられているリポジトリをあなたの GitHub アカウントにフォークします。これは、`GitHub上のあなたのユーザー名/qmk_firmware` の下にリポジトリのコピーを持つことを意味します。
|
||||
3. `git clone https://github.com/GitHub上のあなたのユーザー名/repository-name.git` を使ってローカルマシンにリポジトリをクローンします。
|
||||
4. 新しい機能に取り組んでいる場合は、issue を開きこれから行う作業について話し合うことを検討してください。
|
||||
5. `git checkout -b branch-name-here` を使って修正用の新しいブランチを作成します。
|
||||
6. 解決しようとしている問題、あるいは追加したい機能について適切な変更を加えます。
|
||||
7. `git add insert-paths-of-changed-files-here` を使って変更されたファイルの内容を git がプロジェクトの状態を管理するために使用する "snapshot"、インデックスとしても知られている、に追加します。
|
||||
8. `git commit -m "Insert a short message of the changes made here"` を使って、説明的なメッセージとともにインデックスの内容を保存します。
|
||||
9. `git push origin branch-name-here` を使って GitHub 上のリポジトリに変更をプッシュします。
|
||||
10. プルリクエストを [QMK Firmware](https://github.com/qmk/qmk_firmware/pull/new/master) にサブミットします。
|
||||
11. 行われた変更の簡単な説明と、変更に関する問題またはバグ番号を使って、プルリクエストにタイトルを付けます。例えば、issue に "Added more log outputting to resolve #4352" のようなタイトルをつけることができます。
|
||||
12. プルリクエストの説明では、行った変更、行ったプルリクエストに存在すると思われる問題、およびメンテナに対する質問を説明します。プルリクエストが完ぺきではない場合(プルリクエストが無い場合)でも問題ありません。レビュワーが問題の修正と改善を手伝います。
|
||||
13. プルリクエストがメンテナによってレビューされるのを待ちます。
|
||||
14. レビューをしているメンテナが変更を推奨する場合は、プルリクエストに変更を加えます。
|
||||
15. プルリクエストがマージされた後で成功を祝います！
|
||||
|
||||
# コーディング規約 :id=coding-conventions
|
||||
|
||||
私たちのスタイルのほとんどは簡単に理解できます。C あるいは Python のいずれかに精通している場合は、ローカルスタイルにそれほど問題はないはずです。
|
||||
|
||||
* [コーディング規約 - C](ja/coding_conventions_c.md)
|
||||
* [コーディング規約 - Python](ja/coding_conventions_python.md)
|
||||
|
||||
# 一般的なガイドライン :id=general-guidelines
|
||||
|
||||
QMK には幾つかの異なるタイプの変更があり、それぞれ異なるレベルの厳密さが必要です。どのような種類の変更を行っても、次のガイドラインに留意してください。
|
||||
|
||||
* PR を論理単位に分割します。例えば、2つの個別の機能をカバーする1つの PR を送信するのではなく、代わりに機能ごとに個別の PR をサブミットします。
|
||||
* コミットする前に、`git diff --check` を使って不要な空白を確認します。
|
||||
* コードの変更が実際にコンパイルされることを確認してください。
|
||||
* キーマップ: `make keyboard:your_new_keymap` がエラーを返さないことを確認してください。
|
||||
* キーボード: `make keyboard:all` がエラーを返さないことを確認してください。
|
||||
* コア: `make all` がエラーを返さないことを確認してください。
|
||||
* コミットメッセージがそれ自体で理解できることを確認してください。最初の行に短い説明(70文字以内)を入れ、2行目は空にし、3行目以降では必要に応じてコミットを詳細に説明する必要があります。例:
|
||||
|
||||
```
|
||||
kerpleplork の fronzlebop を調整します
|
||||
|
||||
kerpleplork はエラーコード 23 で連続的に失敗していました。根本的な原因は fronzlebop 設定で、これにより kerpleplork は N 回の繰り返しごとにアクティブになります。
|
||||
|
||||
私が使用できるデバイスの限られた実験では、kerpleplork の混乱を避けるために 7 は十分高い値であることを示していますが、念のため ARM デバイスを持つ人たちからフィードバックを得たいです。
|
||||
```
|
||||
|
||||
!> **重要:** デフォルト以外のキーマップ、ユーザスペースおよびレイアウトのようなユーザコードへのバグ修正あるいは改善に貢献したい場合は、PR にコードの元の提出者にタグをつけてください。Git と GitHub のスキルレベルに関係なく、多くのユーザは知らないうちにコードが変更されることに混乱したりイライラしたりするかもしれません。
|
||||
|
||||
## ドキュメント
|
||||
|
||||
ドキュメントは QMK への貢献を始める最も簡単な方法の1つです。ドキュメントが間違っているか不完全な場所を見つけ、これらを修正するのは簡単です！私たちもドキュメントを編集する人を非常に必要としています。編集するスキルがあるが、どこにどのように飛び乗ればいいのか分からない場合は、[助けをもとめて](#where-can-i-go-for-help)ください！
|
||||
|
||||
全てのドキュメントは `qmk_firmware/docs` ディレクトリの中にあります。あるいは web ベースのワークフローを使いたい場合は、https://docs.qmk.fm/ の各ページの下部にある "Edit this page" リンクをクリックすることができます。
|
||||
|
||||
ドキュメントの中にコードの例を提供する場合は、ドキュメント内の他の場所で使用されている命名規則を順守してください。例えば、一貫性を保つために、`my_layers` あるいは `my_keycodes` として列挙型を標準化します:
|
||||
|
||||
```c
|
||||
enum my_layers {
|
||||
_FIRST_LAYER,
|
||||
_SECOND_LAYER
|
||||
};
|
||||
|
||||
enum my_keycodes {
|
||||
FIRST_LAYER = SAFE_RANGE,
|
||||
SECOND_LAYER
|
||||
};
|
||||
```
|
||||
|
||||
### ドキュメントのプレビュー :id=previewing-the-documentation
|
||||
|
||||
開発環境をセットアップした場合は、プルリクエストを開く前に以下のコマンドを `qmk_firmware/` フォルダから実行することで、あなたの変更をプレビューすることができます:
|
||||
|
||||
./bin/qmk docs
|
||||
|
||||
または、Python 3 のみがインストールされている場合:
|
||||
|
||||
python3 -m http.server 8936
|
||||
|
||||
その後、ウェブブラウザで、`http://localhost:8936/` を表示します。
|
||||
|
||||
## キーマップ
|
||||
|
||||
ほとんどの初めての QMK 貢献者は、個人のキーマップから始めます。キーマップの標準はかなりカジュアルなものにしようとしています(キーマップは結局のところ作成者の性格を反映しています)が、他の人があなたのキーマップを簡単に見つけて学ぶことができるように、これらのガイドラインに従うようにお願いします。
|
||||
|
||||
* [テンプレート](ja/documentation_templates.md) を使って `readme.md` を書きます。
|
||||
* 全てのキーマップの PR は squash されるため、コミットがどのように squash されるかを気にする場合は、自分で行う必要があります。
|
||||
* キーマップの PR に機能をまとめないでください。最初に機能をサブミットし、次にキーマップのための2つ目の PR をサブミットします。
|
||||
* `Makefile` をキーマップフォルダに含めないでください(もう使われていません)。
|
||||
* ファイルヘッダの著作権を更新します (`%YOUR_NAME%` を探します)
|
||||
|
||||
## キーボード
|
||||
|
||||
キーボードは QMK の存在理由です。一部のキーボードはコミュニティによって管理されていますが、他のキーボードはそれぞれのキーボードを作成する責任者によって管理されています。`readme.md` を見るとそのキーボードを管理しているのが誰かが分かります。特定のキーボードに関する質問がある場合、[Issue を開いて](https://github.com/qmk/qmk_firmware/issues)質問にメンテナをタグ付けしてください。(訳注: タグ付け は [メンションする](https://help.github.com/ja/github/writing-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) という意味です。)
|
||||
|
||||
また以下のガイドラインに従うことをお願いします:
|
||||
|
||||
* [テンプレート](ja/documentation_templates.md) を使って `readme.md` を書きます。
|
||||
* コミットの数を適切に保ってください。そうでなければあなたの PR を squash します。
|
||||
* コア機能を新しいキーボードにまとめないでください。最初に機能をサブミットし、次にキーボード用に別の PR をサブミットしてください。
|
||||
* `.c`/`.h` ファイルにすぐ上の親フォルダに従って名前を付けます。例えば、`/keyboards/<kb1>/<kb2>/<kb2>.[ch]`
|
||||
* `Makefile` をキーボードフォルダに含めないでください(もう使われていません)
|
||||
* ファイルヘッダの著作権を更新します (`%YOUR_NAME%` を探します)
|
||||
|
||||
## Quantum/TMK コア
|
||||
|
||||
新しい機能をビルドするために多くの作業を行う前に、最適な方法で実装していることを確認する必要があります。[QMK の理解](ja/understanding_qmk.md)を読むことで、QMK の基本的な理解を得ることができます。これはあなたを QMK のプログラムフローのツアーに連れて行きます。ここから、あなたのアイデアを実装するための最良の方法の感覚をつかむために、私たちと話す必要があります。これを行うには主に2つの方法があります:
|
||||
|
||||
* [Discord でのチャット](https://discord.gg/Uq7gcHh)
|
||||
* [Issue を開く](https://github.com/qmk/qmk_firmware/issues/new)
|
||||
|
||||
機能とバグ修正の PR は全てのキーボードに影響します。また、私たちは QMK の再編も進めています。このため、実装が行われる前に特に重要な変更について議論することが特に重要です。最初に私たちと話をせずに PR を開いた場合、あなたの選択が私たちの計画した方向とうまく合わない場合は幾つかの大きな再作業を行う覚悟をしてください。
|
||||
|
||||
機能やバグの修正に取り組む時に留意すべき幾つかの事があります。
|
||||
|
||||
* **デフォルトで無効** - QMK がサポートするほとんどのチップでメモリがかなり制限されており、現在のキーマップが壊れていないことが重要です。ですので、あなたの機能をオフにするのではなく**オン**にするようにしてください。デフォルトでオンにすべき場合、あるいはコードのサイズを小さくする必要がある場合は、相談してください。
|
||||
* **サブミットする前にローカルでコンパイル** - これが明白であることを願っていますが、コンパイルする必要があります。プルリクエストを作成する前に、変更した内容がコンパイルできるかどうかを常に確認する必要があります。
|
||||
* **リビジョンと異なるチップベースを考慮** - 僅かに異なる設定、さらには異なるチップベースを可能にするリビジョンを持つキーボードが幾つかあります。ARM および AVR でサポートされる機能を作成する、あるいは動作しないプラットフォームでは自動的に無効化するようにしてください。
|
||||
* **機能の説明** - 新しいファイルあるいは既存のファイルの一部として、`docs/` の中に文章化します。文章化しないと、他の人はあなたの苦労から利益を得ることができません。
|
||||
|
||||
また以下のガイドラインに従うことをお願いします:
|
||||
|
||||
* コミットの数を適切に保ってください。そうでなければあなたの PR を squash します。
|
||||
* キーボードあるいはキーマップをコアの変更にまとめないでください。コアの変更を最初にサブミットしてください。
|
||||
* 機能のための[ユニット テスト](ja/unit_testing.md)を書いてください。
|
||||
* 編集しているファイルのスタイルに従ってください。スタイルが明確でないか、スタイルが混在している場合は、上記の[コーディング規約](#coding-conventions)に準拠する必要があります。
|
||||
|
||||
## リファクタリング
|
||||
|
||||
QMK で物事がどのようにレイアウトされるかについて明確なビジョンを維持するために、私たちはリファクタリングを詳細に計画し、変更をする協力者がいます。リファクタリングのアイデアあるいは提案がある場合は、[issue を開いてください](https://github.com/qmk/qmk_firmware/issues)。QMK を改善する方法についてお話ししたいと思います。
|
||||
|
||||
# 行動規範は私にとって何を意味しますか？ :id=what-does-the-code-of-conduct-mean-for-me
|
||||
|
||||
私たちの[行動規範](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md)は、身元に関係なくあなたがプロジェクトの全員を敬意と礼儀を持って扱う責任があることを意味します。あなたが行動規範に記載されている不適切な行動やコメントの被害者である場合は、私たちはあなたのためにここにおり、私たちのコードに従って虐待者が適切に懲戒されるように最善を尽くします。
|
||||
@ -1,114 +0,0 @@
|
||||
# カスタムマトリックス
|
||||
|
||||
<!---
|
||||
grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
|
||||
original document: 0.8.46:docs/custom_matrix.md
|
||||
git diff 0.8.46 HEAD -- docs/custom_matrix.md | cat
|
||||
-->
|
||||
|
||||
QMKは、デフォルトのマトリックススキャンルーチンを独自のコードで部分的に入れ替えたり全部入れ替えたりしたりするメカニズムを提供します。
|
||||
|
||||
この機能を使用する理由は次のとおりです:
|
||||
|
||||
* キーボードのスイッチと MCU ピンの間に追加のハードウェアがある場合
|
||||
* I/O マルチプレクサ
|
||||
* ラインデコーダー
|
||||
* 一般的ではないキースイッチマトリックス
|
||||
* `COL2ROW` と `ROW2COL` の同時使用
|
||||
|
||||
## 前提条件
|
||||
|
||||
カスタムマトリックスの実装には、通常、追加のソースファイルのコンパイルが含まれます。
|
||||
一貫性を保つために、このソースファイルのファイル名は `matrix.c` とすることをお勧めします。
|
||||
|
||||
あなたのキーボードディレクトリに新しいファイルを追加します:
|
||||
```text
|
||||
keyboards/<keyboard>/matrix.c
|
||||
```
|
||||
|
||||
そして、新しいファイルのコンパイルを指定するため、以下を `rules.mk` に追加します
|
||||
```make
|
||||
SRC += matrix.c
|
||||
```
|
||||
|
||||
## マトリックスコードの部分置き換え :id=lite
|
||||
|
||||
カスタムマトリックスを実装する際、定型コードを書かなくてすむように、さまざまなスキャン関数のデフォルト実装を提供しています。
|
||||
|
||||
設定するには、以下を `rules.mk` に追加します：
|
||||
```make
|
||||
CUSTOM_MATRIX = lite
|
||||
```
|
||||
|
||||
そして、キーボードディレクトリの `matrix.c` ファイルに次の関数を実装します。
|
||||
|
||||
```c
|
||||
void matrix_init_custom(void) {
|
||||
// TODO: ここでハードウェアの初期化をする
|
||||
}
|
||||
|
||||
bool matrix_scan_custom(matrix_row_t current_matrix[]) {
|
||||
bool matrix_has_changed = false;
|
||||
|
||||
// TODO: ここで、マトリックススキャンを行なう
|
||||
|
||||
return matrix_has_changed;
|
||||
}
|
||||
```
|
||||
|
||||
## マトリックスコードの全面置き換え
|
||||
|
||||
スキャンルーチンをさらに変更する必要がある場合は、完全なスキャンルーチンを実装することを選択できます。
|
||||
|
||||
設定するには、以下を `rules.mk` に追加します：
|
||||
```make
|
||||
CUSTOM_MATRIX = yes
|
||||
```
|
||||
|
||||
そして、キーボードディレクトリの `matrix.c` ファイルに次の関数を実装します。
|
||||
|
||||
```c
|
||||
matrix_row_t matrix_get_row(uint8_t row) {
|
||||
// TODO: 要求された行データを返します
|
||||
}
|
||||
|
||||
void matrix_print(void) {
|
||||
// TODO: printf() を使って現在のマトリックスの状態をコンソールにダンプします
|
||||
}
|
||||
|
||||
void matrix_init(void) {
|
||||
// TODO: ここでハードウェアとグローバルマトリックスの状態を初期化します
|
||||
|
||||
// ハードウェアによるデバウンスがない場合 - 設定されているデバウンスルーチンを初期化します
|
||||
debounce_init(MATRIX_ROWS);
|
||||
|
||||
// 正しいキーボード動作のためにこれを呼び出す*必要があります*
|
||||
matrix_init_kb();
|
||||
}
|
||||
|
||||
uint8_t matrix_scan(void) {
|
||||
bool changed = false;
|
||||
|
||||
// TODO: ここにマトリックススキャンルーチンを追加します
|
||||
|
||||
// ハードウェアによるデバウンスがない場合 - 設定されているデバウンスルーチンを使用します
|
||||
changed = debounce(raw_matrix, matrix, MATRIX_ROWS, changed);
|
||||
|
||||
// 正しいキーボード動作のためにこれを呼び出す*必要があります*
|
||||
matrix_scan_kb();
|
||||
|
||||
return changed;
|
||||
}
|
||||
```
|
||||
|
||||
また、次のコールバックのデフォルトも提供します。
|
||||
|
||||
```c
|
||||
__attribute__((weak)) void matrix_init_kb(void) { matrix_init_user(); }
|
||||
|
||||
__attribute__((weak)) void matrix_scan_kb(void) { matrix_scan_user(); }
|
||||
|
||||
__attribute__((weak)) void matrix_init_user(void) {}
|
||||
|
||||
__attribute__((weak)) void matrix_scan_user(void) {}
|
||||
```
|
||||
@ -1,403 +0,0 @@
|
||||
# キーボードの挙動をカスタマイズする方法
|
||||
|
||||
<!---
|
||||
original document: 0.12.41:docs/custom_quantum_functions.md
|
||||
git diff 0.12.41 HEAD -- docs/custom_quantum_functions.md | cat
|
||||
-->
|
||||
|
||||
多くの人にとって、カスタムキーボードはボタンの押下をコンピュータに送信するだけではありません。単純なボタンの押下やマクロよりも複雑なことを実行できるようにしたいでしょう。QMK にはコードを挿入したり、機能を上書きしたり、様々な状況でキーボードの挙動をカスタマイズできるフックがあります。
|
||||
|
||||
このページでは、QMK に関する特別な知識は想定していませんが、[QMK の理解](ja/understanding_qmk.md)を読むとより根本的なレベルで何が起きているかを理解するのに役立ちます。
|
||||
|
||||
## コア、キーボード、キーマップ階層 :id=a-word-on-core-vs-keyboards-vs-keymap
|
||||
|
||||
私たちは QMK を階層として構造化しました:
|
||||
|
||||
* コア (`_quantum`)
|
||||
* キーボード/リビジョン (`_kb`)
|
||||
* キーマップ (`_user`)
|
||||
|
||||
以下で説明される各関数は `_kb()` サフィックスあるいは `_user()` サフィックスを使って定義することができます。`_kb()` サフィックスはキーボード/リビジョンレベルで使うことを意図しており、一方で `_user()` サフィックスはキーマップレベルで使われるべきです。
|
||||
|
||||
キーボード/リビジョンレベルで関数を定義する場合、`_kb()` は他の何かを実行する前に `_user()` を呼び出すよう実装することが重要です。そうでなければ、キーマップレベル関数は呼ばれないでしょう。
|
||||
|
||||
# カスタムキーコード
|
||||
|
||||
最も一般的なタスクは、既存のキーコードの挙動を変更するか、新しいキーコードを作成することです。コードの観点からは、それぞれの仕組みは非常に似ています。
|
||||
|
||||
## 新しいキーコードの定義
|
||||
|
||||
独自のカスタムキーコードを作成する最初のステップは、それらを列挙することです。これは、カスタムキーコードに名前を付け、そのキーコードにユニークな番号を割り当てることの両方を意味します。QMK は、カスタムキーコードを固定範囲の番号に制限するのではなく、`SAFE_RANGE` マクロを提供します。カスタムキーコードを列挙する時に `SAFE_RANGE` を使うと、ユニークな番号を取得することが保証されます。
|
||||
|
||||
|
||||
これは2つのキーコードを列挙する例です。このブロックを `keymap.c` に追加した後で、キーマップの中で `FOO` と `BAR` を使うことができます。
|
||||
|
||||
```c
|
||||
enum my_keycodes {
|
||||
FOO = SAFE_RANGE,
|
||||
BAR
|
||||
};
|
||||
```
|
||||
|
||||
## 任意のキーコードの挙動のプログラミング :id=programming-the-behavior-of-any-keycode
|
||||
|
||||
既存のキーの挙動を上書きしたい場合、あるいは新しいキーについて挙動を定義する場合、`process_record_kb()` および `process_record_user()` 関数を使うべきです。これらは実際のキーイベントが処理される前のキー処理中に QMK によって呼び出されます。これらの関数が `true` を返す場合、QMK はキーコードを通常通りに処理します。これは、キーを置き換えるのではなく、キーの機能を拡張するのに便利です。これらの関数が `false` を返す場合、QMK は通常のキー処理をスキップし、必要なキーのアップまたはダウンイベントを送信するのかはユーザ次第です。
|
||||
|
||||
これらの関数はキーが押されるか放されるたびに呼び出されます。
|
||||
|
||||
### `process_record_user()` の実装例
|
||||
|
||||
この例は2つの事を行います。`FOO` と呼ばれるカスタムキーコードの挙動を定義し、Enter キーが押されるたびに音を再生します。
|
||||
|
||||
```c
|
||||
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
|
||||
switch (keycode) {
|
||||
case FOO:
|
||||
if (record->event.pressed) {
|
||||
// 押された時に何かをします
|
||||
} else {
|
||||
// 放された時に何かをします
|
||||
}
|
||||
return false; // このキーの以降の処理をスキップします
|
||||
case KC_ENTER:
|
||||
// enter が押された時に音を再生します
|
||||
if (record->event.pressed) {
|
||||
PLAY_SONG(tone_qwerty);
|
||||
}
|
||||
return true; // QMK に enter のプレスまたはリリースイベントを送信させます
|
||||
default:
|
||||
return true; // 他の全てのキーコードを通常通りに処理します
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `process_record_*` 関数のドキュメント
|
||||
|
||||
* キーボード/リビジョン: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
|
||||
* キーマップ: `bool process_record_user(uint16_t keycode, keyrecord_t *record)`
|
||||
|
||||
`keycode` 引数はキーマップで定義されているものです。例えば `MO(1)`、`KC_L` など。これらのイベントを処理するには `switch...case` ブロックを使うべきです。
|
||||
|
||||
`record` 引数は実際のプレスに関する情報を含みます:
|
||||
|
||||
```c
|
||||
keyrecord_t record {
|
||||
keyevent_t event {
|
||||
keypos_t key {
|
||||
uint8_t col
|
||||
uint8_t row
|
||||
}
|
||||
bool pressed
|
||||
uint16_t time
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
# キーボードの初期化コード
|
||||
|
||||
キーボードの初期化プロセスには幾つかのステップがあります。何をしたいかによって、どの関数を使うべきかに影響します。
|
||||
|
||||
3つの主な初期化関数があり、呼び出される順番にリストされています。
|
||||
|
||||
* `keyboard_pre_init_*` - ほとんどのものが開始される前に起こります。非常に早くに実行したいハードウェアのセットアップに適しています。
|
||||
* `matrix_init_*` - ファームウェアのスタートアッププロセスの途中で起こります。ハードウェアは初期化されますが、機能はまだ初期化されていない場合があります。
|
||||
* `keyboard_post_init_*` - ファームウェアのスタートアッププロセスの最後に起こります。これはほとんどの場合、 "カスタマイズ"コードを配置する場所です。
|
||||
|
||||
!> ほとんどの人にとって、`keyboard_post_init_user` が呼び出したいものです。例えば、ここで RGB アンダーグローのセットアップを行います。
|
||||
|
||||
## キーボードの事前初期化コード
|
||||
|
||||
これは USB さえ起動する前の、起動中の非常に早い段階で実行されます。
|
||||
|
||||
この直後にマトリックスが初期化されます。
|
||||
|
||||
これは主にハードウェア向きの初期化のためであるため、ほとんどのユーザは使うべきではありません。
|
||||
|
||||
ただし、初期化が必要なハードウェアがある場合には、これが最適な場所です (LED ピンの初期化など)。
|
||||
|
||||
### `keyboard_pre_init_user()` の実装例
|
||||
|
||||
この例は、キーボードレベルで、LED ピンとして B0、B1、B2、B3 および B4 をセットアップします。
|
||||
|
||||
```c
|
||||
void keyboard_pre_init_user(void) {
|
||||
// キーボードの事前初期コードを呼び出します。
|
||||
|
||||
// LED ピンを出力として設定します
|
||||
setPinOutput(B0);
|
||||
setPinOutput(B1);
|
||||
setPinOutput(B2);
|
||||
setPinOutput(B3);
|
||||
setPinOutput(B4);
|
||||
}
|
||||
```
|
||||
|
||||
### `keyboard_pre_init_*` 関数のドキュメント :id=keyboard_pre_init_-function-documentation
|
||||
|
||||
* キーボード/リビジョン: `void keyboard_pre_init_kb(void)`
|
||||
* キーマップ: `void keyboard_pre_init_user(void)`
|
||||
|
||||
## マトリックスの初期化コード
|
||||
|
||||
これは、マトリックスが初期化され、ハードウェアの一部がセットアップされた後で、ただし機能の多くが初期化される前に、呼び出されます。
|
||||
|
||||
他の場所で必要になるかもしれないものをセットアップするのに役立ちますが、ハードウェアに関連するものではなく、開始場所に依存するものでもありません。
|
||||
|
||||
|
||||
### `matrix_init_*` 関数のドキュメント
|
||||
|
||||
* キーボード/リビジョン: `void matrix_init_kb(void)`
|
||||
* キーマップ: `void matrix_init_user(void)`
|
||||
|
||||
|
||||
## キーボードの事後初期化コード
|
||||
|
||||
キーボードの初期化プロセスの極めて最後のタスクとして実行されます。この時点で初期化される必要があるような、特定の機能を変更したい場合に便利です。
|
||||
|
||||
|
||||
### `keyboard_post_init_user()` の実装例
|
||||
|
||||
この例は、他の全てのものが初期化された後で実行され、rgb アンダーグローの設定をセットアップします。
|
||||
|
||||
```c
|
||||
void keyboard_post_init_user(void) {
|
||||
// post init コードを呼びます
|
||||
rgblight_enable_noeeprom(); // 設定を保存せずに Rgb を有効にします
|
||||
rgblight_sethsv_noeeprom(180, 255, 255); // 保存せずに色を青緑/シアンに設定します
|
||||
rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // 保存せずにモードを高速なブリージングに設定します
|
||||
}
|
||||
```
|
||||
|
||||
### `keyboard_post_init_*` 関数のドキュメント
|
||||
|
||||
* キーボード/リビジョン: `void keyboard_post_init_kb(void)`
|
||||
* キーマップ: `void keyboard_post_init_user(void)`
|
||||
|
||||
# マトリックススキャンコード :id=matrix-scanning-code
|
||||
|
||||
可能であれば常に `process_record_*()` を使ってキーボードをカスタマイズし、その方法でイベントをフックし、コードがキーボードのパフォーマンスに悪影響を与えないようにします。ただし、まれにマトリックススキャンにフックする必要があります。これらの関数は1秒あたり少なくとも10回は呼び出されるため、これらの関数のコードのパフォーマンスに非常に注意してください。
|
||||
|
||||
### `matrix_scan_*` の実装例
|
||||
|
||||
この例は意図的に省略されています。このようなパフォーマンスに敏感な領域にフックする前に、例を使わずにこれを書くために、QMK 内部について十分理解する必要があります。助けが必要であれば、[issue を開く](https://github.com/qmk/qmk_firmware/issues/new) か [Discord で会話](https://discord.gg/Uq7gcHh)してください。
|
||||
|
||||
### `matrix_scan_*` 関数のドキュメント
|
||||
|
||||
* キーボード/リビジョン: `void matrix_scan_kb(void)`
|
||||
* キーマップ: `void matrix_scan_user(void)`
|
||||
|
||||
この関数はマトリックススキャンのたびに呼び出されます。これは基本的に MCU が処理できる頻度です。大量に実行されるため、ここに何を置くかについては注意してください。
|
||||
|
||||
カスタムマトリックススキャンコードが必要な場合は、この関数を使う必要があります。また、カスタムステータス出力 (LED あるいはディスプレイなど)や、ユーザが入力していない場合でも定期的にトリガーするその他の機能のために使うことができます。
|
||||
|
||||
# キーボードハウスキーピング :id=keyboard-housekeeping
|
||||
|
||||
* キーボード/リビジョン: `void housekeeping_task_kb(void)`
|
||||
* キーマップ: `void housekeeping_task_user(void)`
|
||||
|
||||
この関数は、全ての QMK 処理の最後に、次の繰り返しを開始する前に呼び出されます。`housekeeping_task_*` の関数が呼び出された時点で、QMK が最後のマトリックススキャンを処理したと、安全に見なすことができます -- レイヤーの状態が更新され、USB レポートが送信され、LED が更新され、表示が描画されています。
|
||||
|
||||
`matrix_scan_*` と同様に、これらは MCU が処理できる頻度で呼び出されます。キーボードの応答性を維持するために、これらの関数の呼び出し中にできるだけ何もしないことをお勧めします。実際に何か特別なものを実装する必要がある場合に動作を停止させる可能性があります。
|
||||
|
||||
# キーボードアイドリング/ウェイクコード
|
||||
|
||||
キーボードがサポートしている場合、多くの機能を停止することで"アイドル"にすることができます。これの良い例は、RGB ライトあるいはバックライトです。これにより、電力消費を節約できるか、キーボードの動作が改善されるかもしれません。
|
||||
|
||||
これは2つの関数によって制御されます: `suspend_power_down_*` および `suspend_wakeup_init_*`。これらはシステムキーボードがアイドルになった時と、起動した時のそれぞれで呼ばれます。
|
||||
|
||||
|
||||
### suspend_power_down_user() と suspend_wakeup_init_user() の実装例
|
||||
|
||||
|
||||
```c
|
||||
void suspend_power_down_user(void) {
|
||||
// code will run multiple times while keyboard is suspended
|
||||
}
|
||||
|
||||
void suspend_wakeup_init_user(void) {
|
||||
// code will run on keyboard wakeup
|
||||
}
|
||||
```
|
||||
|
||||
### キーボードサスペンド/ウェイク関数のドキュメント
|
||||
|
||||
* キーボード/リビジョン : `void suspend_power_down_kb(void)` および `void suspend_wakeup_init_user(void)`
|
||||
* キーマップ: `void suspend_power_down_kb(void)` および `void suspend_wakeup_init_user(void)`
|
||||
|
||||
# レイヤー切り替えコード :id=layer-change-code
|
||||
|
||||
これはレイヤーが切り替えられるたびにコードを実行します。レイヤー表示あるいはカスタムレイヤー処理に役立ちます。
|
||||
|
||||
### `layer_state_set_*` の実装例
|
||||
|
||||
この例は、レイヤーに基づいて [RGB アンダーグロー](ja/feature_rgblight.md)を設定する方法を示していて、Planck を例として使っています。
|
||||
|
||||
```c
|
||||
layer_state_t layer_state_set_user(layer_state_t state) {
|
||||
switch (get_highest_layer(state)) {
|
||||
case _RAISE:
|
||||
rgblight_setrgb (0x00, 0x00, 0xFF);
|
||||
break;
|
||||
case _LOWER:
|
||||
rgblight_setrgb (0xFF, 0x00, 0x00);
|
||||
break;
|
||||
case _PLOVER:
|
||||
rgblight_setrgb (0x00, 0xFF, 0x00);
|
||||
break;
|
||||
case _ADJUST:
|
||||
rgblight_setrgb (0x7A, 0x00, 0xFF);
|
||||
break;
|
||||
default: // 他の全てのレイヤーあるいはデフォルトのレイヤー
|
||||
rgblight_setrgb (0x00, 0xFF, 0xFF);
|
||||
break;
|
||||
}
|
||||
return state;
|
||||
}
|
||||
```
|
||||
|
||||
特定のレイヤーの状態を確認するには、`IS_LAYER_ON_STATE(state, layer)` と `IS_LAYER_OFF_STATE(state, layer)` マクロを使います。
|
||||
|
||||
`layer_state_set_*` 関数の外では、グローバルなレイヤー状態を確認するために `IS_LAYER_ON(layer)` と `IS_LAYER_OFF(layer)` マクロを使えます。
|
||||
|
||||
### `layer_state_set_*` 関数のドキュメント
|
||||
|
||||
* キーボード/リビジョン: `layer_state_t layer_state_set_kb(layer_state_t state)`
|
||||
* キーマップ: `layer_state_t layer_state_set_user(layer_state_t state)`
|
||||
|
||||
|
||||
[キーマップの概要](ja/keymap.md#keymap-layer-status)で説明されるように、`state` はアクティブなレイヤーのビットマスクです。
|
||||
|
||||
|
||||
# 永続的な設定 (EEPROM)
|
||||
|
||||
これによりキーボードのための永続的な設定を設定することができます。これらの設定はコントローラの EEPROM に保存され、電源が落ちた後であっても保持されます。設定は `eeconfig_read_kb` および `eeconfig_read_user` を使って読み取ることができ、`eeconfig_update_kb` および `eeconfig_update_user` を使って書きこむことができます。これは切り替え可能な機能 (rgb レイヤーの表示の切り替えなど)に役立ちます。さらに、`eeconfig_init_kb` および `eeconfig_init_user` を使って EEPROM のデフォルト値を設定できます。
|
||||
|
||||
ここでの複雑な部分は、EEPROM を介してデータを保存およびアクセスできる方法がたくさんあり、これを行うための"正しい"方法が無いということです。ただし、各関数には DWORD (4 バイト)しかありません。
|
||||
|
||||
EEPROM の書き込み回数には制限があることに注意してください。これは非常に高い値ですが、EEPROM に書き込むのはこれだけではなく、もし頻繁に書き込むと、MCU の寿命を大幅に短くする可能性があります。
|
||||
|
||||
* この例を理解していない場合は、この機能はかなり複雑なため、この機能を使うことを避けても構いません。
|
||||
|
||||
### 実装例
|
||||
|
||||
これは、設定を追加し、読み書きする例です。この例では、ユーザキーマップを使っています。これは複雑な機能で、多くのことが行われています。実際、動作のために上記の多くの関数を使います！
|
||||
|
||||
|
||||
keymap.c ファイルの中で、先頭にこれを追加します:
|
||||
```c
|
||||
typedef union {
|
||||
uint32_t raw;
|
||||
struct {
|
||||
bool rgb_layer_change :1;
|
||||
};
|
||||
} user_config_t;
|
||||
|
||||
user_config_t user_config;
|
||||
```
|
||||
|
||||
これは、設定をメモリ内に保存し、EEPROM に書き込むことができる32ビット構造体をセットアップします。これを使うと、この構造体に変数が定義されるため、変数を定義する必要が無くなります。`bool` (boolean) の値は1ビットを使い、`uint8_t` は8ビットを使い、`uint16_t` は16ビットを使うことに注意してください。組み合わせて使うことができますが、順番の変更は読み書きされる値が変更されるため、問題が発生するかもしれません。
|
||||
|
||||
`layer_state_set_*` 関数のために `rgb_layer_change` を使い、全てを設定するために `keyboard_post_init_user` および `process_record_user` を使います。
|
||||
|
||||
ここで、上の `keyboard_post_init_user` コードを使って、作成したばかりの構造体を設定するために `eeconfig_read_user()` を追加します。そして、この構造体をすぐに使ってキーマップの機能を制御することができます。それは以下のようになります:
|
||||
```c
|
||||
void keyboard_post_init_user(void) {
|
||||
// キーマップレベルのマトリックスの初期化処理を呼びます
|
||||
|
||||
// EEPROM からユーザ設定を読み込みます
|
||||
user_config.raw = eeconfig_read_user();
|
||||
|
||||
// 有効な場合はデフォルトレイヤーを設定します
|
||||
if (user_config.rgb_layer_change) {
|
||||
rgblight_enable_noeeprom();
|
||||
rgblight_sethsv_noeeprom_cyan();
|
||||
rgblight_mode_noeeprom(1);
|
||||
}
|
||||
}
|
||||
```
|
||||
上記の関数は読み取ったばかりの EEPROM 設定を使い、デフォルトのレイヤーの RGB 色を設定します。その「生の」値は、上で作成した「共用体」に基づいて使用可能な構造に変換されます。
|
||||
|
||||
```c
|
||||
layer_state_t layer_state_set_user(layer_state_t state) {
|
||||
switch (get_highest_layer(state)) {
|
||||
case _RAISE:
|
||||
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); }
|
||||
break;
|
||||
case _LOWER:
|
||||
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_red(); rgblight_mode_noeeprom(1); }
|
||||
break;
|
||||
case _PLOVER:
|
||||
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_green(); rgblight_mode_noeeprom(1); }
|
||||
break;
|
||||
case _ADJUST:
|
||||
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); }
|
||||
break;
|
||||
default: // 他の全てのレイヤーあるいはデフォルトのレイヤー
|
||||
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); }
|
||||
break;
|
||||
}
|
||||
return state;
|
||||
}
|
||||
```
|
||||
これにより、値が有効になっていた場合のみ、RGB アンダーグローが変更されます。この値を設定するために、`RGB_LYR` と呼ばれる `process_record_user` 用の新しいキーコードを作成します。さらに、通常の RGB コードを使う場合、上記の例を使ってオフになることを確認します。以下のようになります:
|
||||
```c
|
||||
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
|
||||
switch (keycode) {
|
||||
case FOO:
|
||||
if (record->event.pressed) {
|
||||
// 押された時に何かをします
|
||||
} else {
|
||||
// 放された時に何かをします
|
||||
}
|
||||
return false; // このキーの以降の処理をスキップします
|
||||
case KC_ENTER:
|
||||
// enter が押された時に音を再生します
|
||||
if (record->event.pressed) {
|
||||
PLAY_SONG(tone_qwerty);
|
||||
}
|
||||
return true; // QMK に enter のプレスまたはリリースイベントを送信させます
|
||||
case RGB_LYR: // これにより、アンダーグローをレイヤー表示として、あるいは通常通りに使うことができます。
|
||||
if (record->event.pressed) {
|
||||
user_config.rgb_layer_change ^= 1; // 状態を切り替えます
|
||||
eeconfig_update_user(user_config.raw); // 新しい状態を EEPROM に書き込みます
|
||||
if (user_config.rgb_layer_change) { // レイヤーの状態表示が有効な場合
|
||||
layer_state_set(layer_state); // すぐにレイヤーの色を更新します
|
||||
}
|
||||
}
|
||||
return false;
|
||||
case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // 任意の RGB コード に対して(quantum_keycodes.h を見てください。400行目参照)
|
||||
if (record->event.pressed) { // これはレイヤー表示を無効にします。これを変更する場合は、無効にしたいだろうため。
|
||||
if (user_config.rgb_layer_change) { // 有効な場合のみ
|
||||
user_config.rgb_layer_change = false; // 無効にします
|
||||
eeconfig_update_user(user_config.raw); // 設定を EEPROM に書き込みます
|
||||
}
|
||||
}
|
||||
return true; break;
|
||||
default:
|
||||
return true; // 他の全てのキーコードを通常通りに処理します
|
||||
}
|
||||
}
|
||||
```
|
||||
最後に、`eeconfig_init_user` 関数を追加して、EEPROM がリセットされた時にデフォルト値、さらにはカスタムアクションを指定できるようにします。EEPROM を強制的にリセットするには、`EEP_RST` キーコードあるいは[ブートマジック](ja/feature_bootmagic.md)機能を使います。例えば、デフォルトで rgb レイヤー表示を設定し、デフォルト値を保存したい場合。
|
||||
|
||||
```c
|
||||
void eeconfig_init_user(void) { // EEPROM がリセットされます！
|
||||
user_config.raw = 0;
|
||||
user_config.rgb_layer_change = true; // デフォルトでこれを有効にします
|
||||
eeconfig_update_user(user_config.raw); // デフォルト値を EEPROM に書き込みます
|
||||
|
||||
// これらの値も EEPROM に書き込むためには、noeeprom 以外のバージョンを使います
|
||||
rgblight_enable(); // デフォルトで RGB を有効にします
|
||||
rgblight_sethsv_cyan(); // デフォルトでシアンに設定します
|
||||
rgblight_mode(1); // デフォルトでソリッドに設定します
|
||||
}
|
||||
```
|
||||
|
||||
これで完了です。RGB レイヤー表示は必要な場合にのみ機能します。キーボードを取り外した後でも保存されます。RGB コードのいずれかを使うと、レイヤー表示が無効になり、設定したモードと色がそのままになります。
|
||||
|
||||
### 'EECONFIG' 関数のドキュメント
|
||||
|
||||
* キーボード/リビジョン: `void eeconfig_init_kb(void)`、`uint32_t eeconfig_read_kb(void)` および `void eeconfig_update_kb(uint32_t val)`
|
||||
* キーマップ: `void eeconfig_init_user(void)`、`uint32_t eeconfig_read_user(void)` および `void eeconfig_update_user(uint32_t val)`
|
||||
|
||||
`val` は EEPROM に書き込みたいデータの値です。`eeconfig_read_*` 関数は EEPROM から32ビット(DWORD) 値を返します。
|
||||
@ -1,123 +0,0 @@
|
||||
# データ駆動型コンフィギュレーション
|
||||
|
||||
<!---
|
||||
grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
|
||||
original document: 0.12.7:docs/data_driven_config.md
|
||||
git diff 0.12.7 HEAD -- docs/data_driven_config.md | cat
|
||||
-->
|
||||
|
||||
このページでは、QMK のデータ駆動型 JSON コンフィギュレーションシステムがどのように動作するかを説明します。これは、QMK 自体に取り組みたい開発者を対象としています。
|
||||
|
||||
## ヒストリー
|
||||
|
||||
これまで、QMK は、`rules.mk` と `config.h` の2つのメカニズムを組み合わせてコンフィギュレーションされてきました。
|
||||
この方法は、QMK がほんの一握りのキーボードをサポートしていたときは上手く機能していましたが、今では、サポートするキーボードは1500近くまで成長しました。
|
||||
`keyboards` の下だけで6000個の設定ファイルがあることが推定されます。
|
||||
これらのファイルの自由形式の性質と、重複を避けるために人々が使用してきたユニークなパターンが継続的なメンテナンスを困難にしており、また、多くのキーボードが時代遅れで時には理解が難しいパターンに従っています。
|
||||
|
||||
また、CLI に慣れていない人に QMK のパワーを提供することにも取り組んでおり、VIA などの他のプロジェクトでは、プログラムをインストールするのと同じくらい簡単に QMK を使用できるように取り組んでいます。
|
||||
これらのツールには、ユーザーが QMK を最大限に活用できるように、キーボードのレイアウト方法や使用可能なピンと機能に関する情報が必要です。
|
||||
その第一歩として `info.json` を導入しました。
|
||||
QMK API は、これら3つの情報源（`config.h`、` rules.mk`、および `info.json`）を、エンドユーザーツールが使用できる信頼できる単一の情報源に結合するための取り組みです。
|
||||
|
||||
これで、`info.json`から `rules.mk` と `config.h` の値を生成することがサポートされ、信頼できる単一の情報源を持つことができます。
|
||||
これにより、自動化されたツールを使用してキーボードを保守できるため、時間と保守作業を大幅に節約できます。
|
||||
|
||||
## 概要
|
||||
|
||||
C 側では何も変わりません。
|
||||
新しいルールを作成したり、定義したりする必要がある場合は、同じプロセスに従います。
|
||||
|
||||
1. `docs/config_options.md` に追加します。
|
||||
1. 適切なコアファイルにデフォルトを設定します。
|
||||
1. 必要に応じて ifdef 文を追加します。
|
||||
|
||||
次に、新しい構成のサポートを `info.json` に追加する必要があります。
|
||||
基本的なプロセスは次のとおりです。
|
||||
|
||||
1. `data/schemas/keyboards.jsonschema` のスキーマに追加します
|
||||
1. `data/maps` にマッピングを追加します
|
||||
1. （オプションおよび非推奨）構成を抽出/生成するコードを追加します。
|
||||
* `lib/python/qmk/info.py`
|
||||
* `lib/python/qmk/cli/generate/config_h.py`
|
||||
* `lib/python/qmk/cli/generate/rules_mk.py`
|
||||
|
||||
## info.json にオプションを追加する
|
||||
|
||||
このセクションでは、info.json に `config.h`/`rules.mk` の値のサポートを追加することについて説明します。
|
||||
|
||||
### スキーマに追加する
|
||||
|
||||
QMK では、[jsonschema](https:json-schema.org) のファイルを `data/schemas` に保持しています。
|
||||
キーボード固有の `info.json` ファイルに入る値は `keyboard.jsonschema` に保持されています。
|
||||
エンドユーザーが編集できるようにしたい値はすべてここに入れなければなりません。
|
||||
|
||||
場合によっては、新しいトップレベルキーを追加するだけで済みます。
|
||||
従うべきいくつかの例は、 `keyboard_name`、`maintainer`、 `processor`、および `url` です。
|
||||
これは、オプションが自己完結型で、他のオプションと直接関係がない場合に適しています。
|
||||
|
||||
その他の場合、1つの `object` の中に、似ているオプションを集める必要があります。
|
||||
これは、機能のサポートを追加する場合に特に当てはまります。
|
||||
このために従うべきいくつかの例は、`indicators`、`matrix_pins`、および `rgblight` です。
|
||||
新しいオプションを統合する方法がわからない場合は、[問題を開く](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=)か、[Discord で #cli に参加](https://discord.gg/heQPAgy)して、そこで会話を始めてください。
|
||||
|
||||
### マッピングを追加する
|
||||
|
||||
ほとんどの場合、単純なマッピングを追加することができます。
|
||||
これらは `data/mappings/info_config.json` と `data/mappings/info_rules.json` に JSON ファイルとして保持され、それぞれ `config.h` と `rules.mk` のマッピングを制御します。
|
||||
各マッピングは `config.h` または `rules.mk` 変数名をキーとし、値は以下のキーを持つハッシュです。
|
||||
|
||||
* `info_key`: (必須）この値の `info.json` 内の場所。 下記参照。
|
||||
* `value_type`: (オプション）デフォルトは `str`。 この変数の値の形式。 下記参照。
|
||||
* `to_json`: (オプション）デフォルトは `true`。 このマッピングを info.json から除外するには、`false` に設定します
|
||||
* `to_c`: (オプション）デフォルトは `true`。 このマッピングを config.h から除外するには、`false` に設定します
|
||||
* `warn_duplicate`: (オプション）デフォルトは `true`。 値が両方の場所に存在する場合に警告をオフにするには、`false` に設定します
|
||||
|
||||
#### Info Key
|
||||
|
||||
info.json 内の変数をアドレス指定するために JSON ドット表記を使用します。
|
||||
たとえば、`info_json["rgblight"]["split_count"]` にアクセスするには、`rgblight.split_count` を指定します。
|
||||
これにより、深くネストされたキーを単純な文字列でアドレス指定できます。
|
||||
|
||||
内部では [Dotty Dict](https://dotty-dict.readthedocs.io/en/latest/) を使用しています。これらの文字列がオブジェクトアクセスに変換される方法についてはそのドキュメントを参照してください。
|
||||
|
||||
#### Value Types
|
||||
|
||||
デフォルトでは、すべての値を単純な文字列として扱います。
|
||||
値がより複雑な場合は、次のいずれかのタイプを使用してデータをインテリジェントに解析できます。
|
||||
|
||||
* `array`: 文字列のコンマ区切りの配列
|
||||
* `array.int`: 整数のコンマ区切り配列
|
||||
* `int`: 整数
|
||||
* `hex`: 16進数としてフォーマットされた数値
|
||||
* `list`: 文字列のスペース区切りの配列
|
||||
* `mapping`: キーと値のペアのハッシュ
|
||||
|
||||
### 抽出するコードを追加する
|
||||
|
||||
ほとんどのユースケースは、上記のマッピングファイルによって解決できます。
|
||||
できない場合は、代わりに設定値を抽出するコードを書くことができます。
|
||||
|
||||
QMK が完全な `info.json` を生成するときはいつでも、`config.h` と `rules.mk` から情報を抽出します。
|
||||
あなたの新しい設定値のためのコードを `lib/python/qmk/info.py` に追加する必要があります。
|
||||
通常、これは、新しい `_extract_<feature>()` 関数を追加してから、 `_extract_config_h()` または `_extract_rules_mk()` のいずれかで関数を呼び出すことを意味します。
|
||||
|
||||
このファイルの編集方法がわからない場合、または Python に慣れていない場合は、[issue を開く](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=）か [Discord で #cli に参加](https://discord.gg/heQPAgy)すると、この部分を誰かが手伝ってくれるでしょう。
|
||||
|
||||
### 生成するコードを追加する
|
||||
|
||||
パズルの最後のピースは、ビルドシステムに新しいオプションを提供することです。
|
||||
これは、2つのファイルを生成することによって行われます。
|
||||
|
||||
* `.build/obj_<keyboard>_<keymap>/src/info_config.h`
|
||||
* `.build/obj_<keyboard>_<keymap>/src/rules.mk`
|
||||
|
||||
この2つのファイルは、次のコードによって生成されます。
|
||||
|
||||
* `lib/python/qmk/cli/generate/config_h.py`
|
||||
* `lib/python/qmk/cli/generate/rules_mk.py`
|
||||
|
||||
`config.h`値の場合、ルール用の関数を記述し、その関数を `generate_config_h()` で呼び出す必要があります。
|
||||
|
||||
`rules.mk` の新しいトップレベルの `info.json` キーがある場合は、`lib/python/qmk/cli/generate/rules_mk.py` の上部にある `info_to_rules` にキーを追加するだけです。
|
||||
それ以外の場合は、`generate_rules_mk()` で機能の新しい if ブロックを作成する必要があります。
|
||||
@ -1,69 +0,0 @@
|
||||
# ドキュメントベストプラクティス
|
||||
|
||||
<!---
|
||||
original document: 0.10.33:docs/documentation_best_practices.md
|
||||
git diff 0.10.33 HEAD -- docs/documentation_best_practices.md | cat
|
||||
-->
|
||||
|
||||
このページは QMK のためのドキュメントを作成する時のベストプラクティスを文章化するためのものです。これらのガイドラインに従うことで、一貫したトーンとスタイルを維持することでき、他の人が QMK をより理解しやすくすることができます。
|
||||
|
||||
# ページの開始
|
||||
|
||||
ドキュメントページは通常 H1 ヘッダで始まり、最初の段落を使ってこのページの内容を説明します。この見出しと段落は目次の次にあるため、見出しは短くして空白の無い長い文字列を避けるように気を付けてください。
|
||||
|
||||
例:
|
||||
|
||||
```
|
||||
# My Page Title
|
||||
|
||||
This page covers my super cool feature. You can use this feature to make coffee, squeeze fresh oj, and have an egg mcmuffin and hashbrowns delivered from your local macca's by drone.
|
||||
```
|
||||
|
||||
# 見出し
|
||||
|
||||
通常、ページには複数の "H1" 見出しが有るべきです。H1 と H2 見出しのみが目次に含まれるので、適切に計画してください。目次が広くなりすぎないように、H1 と H2 の見出しでは幅を広げないようにしてください。
|
||||
|
||||
# スタイル付きのヒントブロック
|
||||
|
||||
注意を引くためにテキストの周りにスタイル付きのヒントブロックを描くことができます。
|
||||
|
||||
### 重要なもの
|
||||
|
||||
```
|
||||
!> This is important
|
||||
```
|
||||
|
||||
以下のように表示されます:
|
||||
|
||||
!> This is important
|
||||
|
||||
### 一般的なヒント
|
||||
|
||||
```
|
||||
?> This is a helpful tip.
|
||||
```
|
||||
|
||||
以下のように表示されます:
|
||||
|
||||
?> This is a helpful tip.
|
||||
|
||||
|
||||
# 機能を文章化する
|
||||
|
||||
QMK のために新しい機能を作成した場合、そのドキュメントページを作成してください。長い必要は無く、機能を説明する幾つかの文と、関連するキーコードを列挙した表で十分です。以下は基本的なテンプレートです:
|
||||
|
||||
```markdown
|
||||
# My Cool Feature
|
||||
|
||||
This page describes my cool feature. You can use my cool feature to make coffee and order cream and sugar to be delivered via drone.
|
||||
|
||||
## My Cool Feature Keycodes
|
||||
|
||||
|Long Name|Short Name|Description|
|
||||
|---------|----------|-----------|
|
||||
|KC_COFFEE||Make Coffee|
|
||||
|KC_CREAM||Order Cream|
|
||||
|KC_SUGAR||Order Sugar|
|
||||
```
|
||||
|
||||
ドキュメントを `docs/feature_<my_cool_feature>.md` に配置し、そのファイルを `docs/_summary.md` の適切な場所に追加します。キーコードを追加した場合は、機能ページに戻るリンクとともに `docs/keycodes.md` に追加するようにしてください。
|
||||
@ -1,45 +0,0 @@
|
||||
# ドキュメントテンプレート
|
||||
|
||||
<!---
|
||||
original document: 0.13.15:docs/documentation_templates.md
|
||||
git diff 0.13.15 HEAD -- docs/documentation_templates.md | cat
|
||||
-->
|
||||
|
||||
このページでは、新しいキーマップやキーボードを QMK に提出する際に使うべきテンプレートをまとめています。
|
||||
|
||||
## キーマップ `readme.md` テンプレート :id=keyboard-readmemd-template
|
||||
|
||||
ほとんどのキーマップには、レイアウトを表す画像があります。画像を作成するには、[Keyboard Layout Editor](https://keyboard-layout-editor.com) を使うことができます。画像は [Imgur](https://imgur.com) や別のホスティングサービスにアップロードし、プルリクエストに画像を含めないでください。
|
||||
|
||||
画像の下には、キーマップを理解してもらうための簡単な説明文を書いてください。
|
||||
|
||||
```
|
||||
|
||||
|
||||
# Default Clueboard Layout
|
||||
|
||||
This is the default layout that comes flashed on every Clueboard. For the most
|
||||
part it's a straightforward and easy to follow layout. The only unusual key is
|
||||
the key in the upper left, which sends Escape normally, but Grave when any of
|
||||
the Ctrl, Alt, or GUI modifiers are held down.
|
||||
```
|
||||
|
||||
## キーボード `readme.md` テンプレート
|
||||
|
||||
```
|
||||
# Planck
|
||||
|
||||
|
||||
|
||||
A compact 40% (12x4) ortholinear keyboard kit made and sold by OLKB and Massdrop. [More info on qmk.fm](https://qmk.fm/planck/)
|
||||
|
||||
* Keyboard Maintainer: [Jack Humbert](https://github.com/jackhumbert)
|
||||
* Hardware Supported: Planck PCB rev1, rev2, rev3, rev4, Teensy 2.0
|
||||
* Hardware Availability: [OLKB.com](https://olkb.com), [Massdrop](https://www.massdrop.com/buy/planck-mechanical-keyboard?mode=guest_open)
|
||||
|
||||
Make example for this keyboard (after setting up your build environment):
|
||||
|
||||
make planck/rev4:default
|
||||
|
||||
See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs).
|
||||
```
|
||||
@ -1,53 +0,0 @@
|
||||
# Zadig を使ったブートローダドライバのインストール
|
||||
|
||||
<!---
|
||||
original document: 0.9.43:docs/driver_installation_zadig.md
|
||||
git diff 0.9.43 HEAD -- docs/driver_installation_zadig.md | cat
|
||||
-->
|
||||
|
||||
QMK はホストにたいして通常の HID キーボードデバイスとして振る舞うため特別なドライバは必要ありません。しかし、Windows でのキーボードへの書き込みは、多くの場合、キーボードをリセットした時に現れるブートローダデバイスで*行います*。
|
||||
|
||||
2つの注目すべき例外があります: 通常 Pro Micro で見られる Caterina ブートローダや、PJRC Teensy に書き込まれている HalfKay ブートローダは、それぞれシリアルポートと汎用 HID デバイスとして振る舞うため、ドライバは必要ありません。
|
||||
|
||||
[Zadig](https://zadig.akeo.ie/) ユーティリティを使うことをお勧めします。MSYS2 あるいは WSL を使って開発環境をセットアップした場合、`qmk_install.sh` スクリプトはドライバをインストールするかどうかをたずねます。
|
||||
|
||||
## インストール
|
||||
|
||||
`RESET` キーコード (別のレイヤにあるかもしれません)を押すか、通常はキーボードの下面にあるリセットスイッチを押して、キーボードをブートローダモードにします。どちらもキーボードに無い場合は、Escape または Space+`B` を押しながら接続してみてください (詳細は、[ブートマジック](ja/feature_bootmagic.md) ドキュメントを見てください)。一部のキーボードはブートマジックの代わりに[コマンド](ja/feature_command.md)を使います。この場合、キーボードが接続されている状態で「左Shift + 右Shift + `B`」あるいは「左Shift + 右Shift + Escape」を押すと、ブートローダモードに入ることができます。
|
||||
一部のキーボードはブートローダに入るために特定の操作をする必要があります。例えば、[ブートマジック Lite](ja/feature_bootmagic.md#bootmagic-lite) キー (デフォルト: Escape) は別のキー(例えば、左Control)かもしれません。また、コマンドを有効にするキーの組み合わせ (デフォルト: 左Shift + 右Shift) は何か他のキー(例えば 左Control + 右Control)を押し続ける必要がある場合があります。不明な場合は、キーボードの README ファイルを参照してください。
|
||||
|
||||
USBaspLoader を使ってデバイスをブートローダモードにするには、`BOOT` ボタンを押しながら `RESET` ボタンをタップしてください。
|
||||
あるいは `BOOT` を押し続けながら USB ケーブルを挿入します。
|
||||
|
||||
Zadig は自動的にブートローダデバイスを検知します。**Options → List All Devices** を確認する必要がある場合があります。
|
||||
|
||||
- Atmel AVR MCU を搭載したキーボードの場合、ブートローダは `ATm32U4DFU` に似た名前が付けられ、ベンダー ID は `03EB` です。
|
||||
- USBasp ブートローダは `USBasp` として表示され、VID/PID は`16C0:05DC` です。
|
||||
- QMK-DFU ブートローダを使って書き込まれた AVR キーボードは `<keyboard name> Bootloader` という名前が付けられ、VID は `03EB` です。
|
||||
- ほとんどの ARM キーボードでは、`STM32 BOOTLOADER` と呼ばれ、VID/PID は `0483:DF11` です。
|
||||
|
||||
!> Zadig が `HidUsb` ドライバを使用する1つ以上のデバイスを表示する場合、キーボードはおそらくブートローダモードではありません。矢印はオレンジ色になり、システムドライバの変更を確認するように求められます。この場合、続行**しないでください**！
|
||||
|
||||
矢印が緑色で表示されたら、ドライバを選択し、**Install Driver** をクリックします。`libusb-win32` ドライバは通常 AVR で動作し、`WinUSB`は ARM で動作しますが、それでもキーボードに書き込みできない場合は、リストから異なるドライバをインストールしてみてください。USBAspLoader デバイスは `libusbK` ドライバを使わなければなりません。
|
||||
|
||||
|
||||
|
||||
最後に、新しいドライバがロードされたことを確認するためにキーボードのプラグを抜いて再接続します。書き込みに QMK Toolbox を使う場合は、ドライバの変更を認識しない場合があるため、QMK Toolkit を終了して再起動します。
|
||||
|
||||
## 間違ったデバイスのインストールからの回復
|
||||
|
||||
キーボードが入力できなくなった場合は、ブートローダではなくキーボード自体のドライバを間違って入れ替えた可能性があります。これはキーボードがブートローダモードでない場合に起こりえます。これは Zadig で簡単に確認することができます - 健全なキーボードには、全てのインタフェースに `HidUsb` ドライバがインストールされています:
|
||||
|
||||
|
||||
|
||||
デバイスマネージャーを開き、キーボードと思われるデバイスを探します。
|
||||
|
||||
|
||||
|
||||
右クリックし、**デバイスのアンインストール** をクリックします。最初に **このデバイスのドライバーソフトウェアを削除します** にチェックが付いていることを確認してください。
|
||||
|
||||
|
||||
|
||||
**Action → Scan for hardware changes** をクリックします。この時点で、再び入力できるようになっているはずです。Zadig でキーボードデバイスが `HidUsb` ドライバを使っていることを再確認します。そうであれば完了です。キーボードは再び機能するはずです！
|
||||
|
||||
?> Windows が新しいドライバを使えるようにするために、この時点でコンピュータを完全に再起動する必要があるかもしれません。
|
||||
@ -1,73 +0,0 @@
|
||||
# よくあるビルドの質問
|
||||
|
||||
<!---
|
||||
original document: 0.12.43:docs/faq_build.md
|
||||
git diff 0.12.43 HEAD -- docs/faq_build.md | cat
|
||||
-->
|
||||
|
||||
このページは QMK のビルドに関する質問を説明します。まだビルドをしていない場合は、[ビルド環境のセットアップ](ja/getting_started_build_tools.md) および [Make 手順](ja/getting_started_make_guide.md)ガイドを読むべきです。
|
||||
|
||||
## Linux でプログラムできません
|
||||
デバイスを操作するには適切な権限が必要です。Linux ユーザの場合は、以下の `udev` ルールに関する指示を見てください。`udev` に問題がある場合は、回避策は `sudo` コマンドを使うことです。このコマンドに慣れていない場合は、`man sudo` コマンドでマニュアルを確認するか、[この web ページを見てください](https://linux.die.net/man/8/sudo)。
|
||||
|
||||
コントローラが ATMega32u4 の場合の `sudo` の使い方の例:
|
||||
|
||||
$ sudo dfu-programmer atmega32u4 erase --force
|
||||
$ sudo dfu-programmer atmega32u4 flash your.hex
|
||||
$ sudo dfu-programmer atmega32u4 reset
|
||||
|
||||
あるいは、単純に:
|
||||
|
||||
$ sudo make <keyboard>:<keymap>:flash
|
||||
|
||||
`make` を `sudo` で実行することは一般的には良い考えでは***なく***、可能であれば前者の方法のいずれかを使うべきです。
|
||||
|
||||
### Linux の `udev` ルール :id=linux-udev-rules
|
||||
|
||||
Linux では、ブートローダデバイスと通信するには適切な権限が必要です。ファームウェアを書き込む時に `sudo` を使うか(非推奨)、`/etc/udev/rules.d/` に[このファイル](https://github.com/qmk/qmk_firmware/tree/master/util/udev/50-qmk.rules)を配置することで、通信することができます。
|
||||
|
||||
追加が完了したら、以下を実行します:
|
||||
|
||||
```
|
||||
sudo udevadm control --reload-rules
|
||||
sudo udevadm trigger
|
||||
```
|
||||
|
||||
**注意:** 古い(1.12以前の) ModemManager では、フィルタリングは厳密なモードではない場合にのみ動作し、以下のコマンドはその設定を更新することができます。
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
### Linux のブートローダモードで Serial デバイスが検知されない
|
||||
カーネルがデバイスを適切にサポートしていることを確認してください。デバイスが、Pro Micro (Atmega32u4) のように USB ACM を使う場合、`CONFIG_USB_ACM=y` を含めるようにしてください。他のデバイスは `USB_SERIAL` およびそのサブオプションを必要とするかもしれません。
|
||||
|
||||
## DFU ブートローダの不明なデバイス
|
||||
|
||||
Windows 上でキーボードを書き込む時に発生する問題は、ブートローダ用に間違ったドライバがインストールされているか、全くインストールされていないかによるものがほとんどです。
|
||||
|
||||
QMK インストールスクリプト (MSYS2 あるいは WSL 内の `qmk_firmware` ディレクトリから `./util/qmk_install.sh`) を再実行するか、QMK Toolbox の再インストールでこの問題が解決するかもしれません。別のやり方として、手動で [`qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer) パッケージをダウンロードして実行することができます。
|
||||
|
||||
それでもうまく行かない場合は、Zadig をダウンロードして実行する必要があります。詳細な情報は [Zadig を使ったブートローダドライバのインストール](ja/driver_installation_zadig.md)を見てください。
|
||||
|
||||
## USB VID と PID
|
||||
`config.h` を編集することで任意の ID を使うことができます。おそらく未使用の ID を使っても、他の製品と衝突するとても低い可能性があることを除いて、実際には問題はありません。
|
||||
|
||||
QMK のほとんどのキーボードは、vendor ID として、`0xFEED` を使います。他のキーボードを調べて、ユニークな ID を選択してください。
|
||||
|
||||
またこれも見てください。
|
||||
https://github.com/tmk/tmk_keyboard/issues/150
|
||||
|
||||
ここで本当にユニークな VID:PID を買うことができます。個人的な使用にはこれは必要ないと思います。
|
||||
- https://www.obdev.at/products/vusb/license.html
|
||||
- https://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1
|
||||
|
||||
### キーボードに書き込んだが何も起こらない、あるいはキーの押下が登録されない - ARM (rev6 planck、clueboard 60、hs60v2 など) でも同じ (Feb 2019)
|
||||
ARM ベースのチップ上での EEPROM の動作によって、保存された設定が無効になる場合があります。これはデフォルトレイヤに影響し、まだ調査中の特定の環境下でキーボードが使えなくなるかも*しれません*。EEPROM のリセットでこれが修正されます。
|
||||
|
||||
[Planck rev6 reset EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/539284620861243409/planck_rev6_default.bin) を使って eeprom のリセットを強制することができます。このイメージを書き込んだ後で、通常のファームウェアを書き込むと、キーボードが _通常_ の動作順序に復元されます。
|
||||
[Preonic rev3 reset EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/537849497313738762/preonic_rev3_default.bin)
|
||||
|
||||
いずれかの形式でブートマジックが有効になっている場合は、これも実行できるはずです (実行方法の詳細については、[ブートマジックドキュメント](ja/feature_bootmagic.md)とキーボード情報を見てください)。
|
||||
@ -1,131 +0,0 @@
|
||||
# デバッグの FAQ
|
||||
|
||||
<!---
|
||||
original document: 0.12.45:docs/faq_debug.md
|
||||
git diff 0.12.45 HEAD -- docs/faq_debug.md | cat
|
||||
-->
|
||||
|
||||
このページは、キーボードのトラブルシューティングについての様々な一般的な質問を説明します。
|
||||
|
||||
## デバッグ :id=debugging
|
||||
|
||||
`rules.mk` へ `CONSOLE_ENABLE = yes` の設定をするとキーボードはデバッグ情報を出力します。デフォルトの出力は非常に限られたものですが、デバッグモードをオンにすることでデバッグ情報の量を増やすことが出来ます。キーマップの `DEBUG` キーコードを使用するか、デバッグモードを有効にする[コマンド](ja/feature_command.md)機能を使用するか、以下のコードをキーマップに追加します。
|
||||
|
||||
```c
|
||||
void keyboard_post_init_user(void) {
|
||||
// 希望する動作に合わせて値をカスタマイズします
|
||||
debug_enable=true;
|
||||
debug_matrix=true;
|
||||
//debug_keyboard=true;
|
||||
//debug_mouse=true;
|
||||
}
|
||||
```
|
||||
|
||||
## デバッグツール
|
||||
|
||||
キーボードのデバッグに使えるツールは2つあります。
|
||||
|
||||
### QMK Toolbox を使ったデバッグ
|
||||
|
||||
互換性のある環境では、[QMK Toolbox](https://github.com/qmk/qmk_toolbox) を使うことでキーボードからのデバッグメッセージを表示できます。
|
||||
|
||||
### hid_listen を使ったデバッグ
|
||||
|
||||
ターミナルベースの方法がお好みですか？PJRC が提供する [hid_listen](https://www.pjrc.com/teensy/hid_listen.html) もデバッグメッセージの表示に使用できます。ビルド済みの実行ファイルは Windows、Linux、MacOS 用が用意されています。
|
||||
|
||||
## 独自のデバッグメッセージを送信する
|
||||
|
||||
[カスタムコード](ja/custom_quantum_functions.md)内からデバッグメッセージを出力すると便利な場合があります。それはとても簡単です。ファイルの先頭に `print.h` のインクルードを追加します:
|
||||
|
||||
```c
|
||||
#include "print.h"
|
||||
```
|
||||
|
||||
その後は、いくつかの異なった print 関数を使用することが出来ます:
|
||||
|
||||
* `print("string")`: シンプルな文字列を出力します
|
||||
* `uprintf("%s string", var)`: フォーマットされた文字列を出力します
|
||||
* `dprint("string")` デバッグモードが有効な場合のみ、シンプルな文字列を出力します
|
||||
* `dprintf("%s string", var)`: デバッグモードが有効な場合のみ、フォーマットされた文字列を出力します
|
||||
|
||||
## デバッグの例
|
||||
|
||||
以下は現実世界での実際のデバッグ手法の例を集めたものです。
|
||||
|
||||
### マトリックス上のどの場所でキー押下が起こったか？
|
||||
|
||||
移植する場合や、PCB の問題を診断する場合、キー入力が正しくスキャンされているかどうかを確認することが役立つ場合があります。この手法でのロギングを有効化するには、`keymap.c` へ以下のコードを追加します。
|
||||
|
||||
```c
|
||||
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
|
||||
// コンソールが有効化されている場合、マトリックス上の位置とキー押下状態を出力します
|
||||
#ifdef CONSOLE_ENABLE
|
||||
uprintf("KL: kc: 0x%04X, col: %u, row: %u, pressed: %b, time: %u, interrupt: %b, count: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed, record->event.time, record->tap.interrupted, record->tap.count);
|
||||
#endif
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
出力例
|
||||
```text
|
||||
Waiting for device:.......
|
||||
Listening:
|
||||
KL: kc: 169, col: 0, row: 0, pressed: 1
|
||||
KL: kc: 169, col: 0, row: 0, pressed: 0
|
||||
KL: kc: 174, col: 1, row: 0, pressed: 1
|
||||
KL: kc: 174, col: 1, row: 0, pressed: 0
|
||||
KL: kc: 172, col: 2, row: 0, pressed: 1
|
||||
KL: kc: 172, col: 2, row: 0, pressed: 0
|
||||
```
|
||||
|
||||
### キースキャンにかかる時間の測定
|
||||
|
||||
パフォーマンスの問題をテストする場合、スイッチマトリックスをスキャンする頻度を知ることが役立ちます。この手法でのロギングを有効化するには `config.h` へ以下のコードを追加します。
|
||||
|
||||
```c
|
||||
#define DEBUG_MATRIX_SCAN_RATE
|
||||
```
|
||||
|
||||
出力例
|
||||
```text
|
||||
> matrix scan frequency: 315
|
||||
> matrix scan frequency: 313
|
||||
> matrix scan frequency: 316
|
||||
> matrix scan frequency: 316
|
||||
> matrix scan frequency: 316
|
||||
> matrix scan frequency: 316
|
||||
```
|
||||
|
||||
## `hid_listen` がデバイスを認識できない
|
||||
デバイスのデバッグコンソールの準備ができていない場合、以下のように表示されます:
|
||||
|
||||
```
|
||||
Waiting for device:.........
|
||||
```
|
||||
|
||||
デバイスが接続されると、*hid_listen* がデバイスを見つけ、以下のメッセージが表示されます:
|
||||
|
||||
```
|
||||
Waiting for new device:.........................
|
||||
Listening:
|
||||
```
|
||||
|
||||
この 'Listening:' のメッセージが表示されない場合は、[Makefile] を `CONSOLE_ENABLE=yes` に設定してビルドしてみてください
|
||||
|
||||
Linux のような OS でデバイスにアクセスするには、特権が必要かもしれません。`sudo hid_listen` を試してください。
|
||||
|
||||
多くの Linux ディストリビューションでは、次の内容で `/etc/udev/rules.d/70-hid-listen.rules` というファイルを作成することで、root として hid_listen を実行する必要がなくなります:
|
||||
|
||||
```
|
||||
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="abcd", ATTRS{idProduct}=="def1", TAG+="uaccess", RUN{builtin}+="uaccess"
|
||||
```
|
||||
|
||||
abcd と def1 をキーボードのベンダーとプロダクト IDに置き換えてください。文字は小文字でなければなりません。`RUN{builtin}+="uaccess"` の部分は、古いディストリビューションでのみ必要です。
|
||||
|
||||
## コンソールにメッセージが表示されない
|
||||
以下を調べてください:
|
||||
- *hid_listen* がデバイスを検出する。上記を見てください。
|
||||
- **Magic**+d を使ってデバッグを有効にする。[マジックコマンド](https://github.com/tmk/tmk_keyboard#magic-commands)を見てください。
|
||||
- `debug_enable=true` を設定します。[デバッグ](#debugging)を見てください。
|
||||
- デバッグプリントの代わりに `print` 関数を使ってみてください。**common/print.h** を見てください。
|
||||
- コンソール機能を持つ他のデバイスを切断します。[Issue #97](https://github.com/tmk/tmk_keyboard/issues/97) を見てください。
|
||||
@ -1,58 +0,0 @@
|
||||
# よくある質問
|
||||
|
||||
<!---
|
||||
original document: 0.13.17:docs/faq_general.md
|
||||
git diff 0.13.17 HEAD -- docs/faq_general.md | cat
|
||||
-->
|
||||
|
||||
## QMK とは何か？
|
||||
|
||||
Quantum Mechanical Keyboard の略である [QMK](https://github.com/qmk) は、カスタムキーボードのためのツールをビルドしている人々のグループです。[TMK](https://github.com/tmk/tmk_keyboard) の大幅に修正されたフォークである [QMK ファームウェア](https://github.com/qmk/qmk_firmware)から始まりました。
|
||||
|
||||
## どこから始めればいいかわかりません！
|
||||
|
||||
この場合は、[初心者ガイド](ja/newbs.md) から始めるべきです。ここには多くの素晴らしい情報があり、それらはあなたが始めるのに必要な全てをカバーするはずです。
|
||||
|
||||
問題がある場合は、[QMK Configurator](https://config.qmk.fm)にアクセスしてください。あなたが必要なものの大部分が処理されます。
|
||||
|
||||
## ビルドしたファームウェアを書き込むにはどうすればいいですか？
|
||||
|
||||
まず、[コンパイル/書き込み FAQ ページ](ja/faq-build.md) に進みます。そこにはたくさんの情報があり、そこには一般的な問題に対する多くの解決策があります。
|
||||
|
||||
## ここで取り上げていない問題がある場合はどうしますか？
|
||||
|
||||
OK、問題ありません。[GitHub で issue を開く](https://github.com/qmk/qmk_firmware/issues) をチェックして、誰かが同じこと(似ているかだけでなく実際に同じであることを確認してください)を経験しているかどうかを確認してください。
|
||||
|
||||
もし何も見つからない場合は、[新しい issue](https://github.com/qmk/qmk_firmware/issues/new) を開いてください！
|
||||
|
||||
## バグを見つけたらどうしますか？
|
||||
|
||||
[issue](https://github.com/qmk/qmk_firmware/issues/new) を開いてください。そしてもし修正方法を知っている場合は、GitHub で修正のプルリクエストを開いてください。
|
||||
|
||||
## しかし、`git` と `GitHub` は怖いです！
|
||||
|
||||
心配しないでください。開発を容易にするために `git` と GitHub を使い始めるための、かなり良い [ガイドライン](ja/newbs_git_best_practices.md) があります。
|
||||
|
||||
さらに、追加の `git` と GitHub の関連リンクを [ここ](ja/newbs_learn_more_resources.md) に見つけることができます。
|
||||
|
||||
## サポートを追加したいキーボードがあります
|
||||
|
||||
素晴らしい！プルリクエストを開いてください。私たちはコードをレビューし、マージします！
|
||||
|
||||
### `QMK` でブランドしたい場合はどうればいいですか？
|
||||
|
||||
素晴らしい！私たちはあなたを支援したいと思います！
|
||||
|
||||
実際、私たちにはあなたのページとキーボードに QMK ブランドを追加するための [完全なページ](https://qmk.fm/powered/) があります。これは QMK を公式にサポートするために必要なほぼ全て(知識と画像)をカバーしています。
|
||||
|
||||
これについて質問がある場合は、issue を開くか、[Discord](https://discord.gg/Uq7gcHh) に進んでください。
|
||||
|
||||
## QMK と TMK の違いは何か？
|
||||
|
||||
TMK は [Jun Wako](https://github.com/tmk) によって設計され実装されました。QMK は [Jack Humbert](https://github.com/jackhumbert) の Planck 用 TMK のフォークとして始まりました。しばらくして、Jack のフォークは TMK からかなり分岐し、2015年に Jack はフォークを QMK に名前を変えることにしました。
|
||||
|
||||
技術的な観点から、QMK は幾つかの新しい機能を追加した TMK に基づいています。最も注目すべきことは、QMK は利用可能なキーコードの数を増やし、`S()`、`LCTL()` および `MO()` などの高度な機能を実装するためにこれらを使っています。[キーコード](ja/keycodes.md)でこれらのキーコードの完全なリストを見ることができます。
|
||||
|
||||
プロジェクトとコミュニティの管理の観点から、TMK は公式にサポートされている全てのキーボードを自分で管理しており、コミュニティのサポートも少し受けています。他のキーボード用に別個のコミュニティが維持するフォークが存在するか、作成できます。デフォルトでは少数のキーマップのみが提供されるため、ユーザは一般的にお互いにキーマップを共有しません。QMK は集中管理されたリポジトリを介して、キーボードとキーマップの両方を共有することを奨励しており、品質基準に準拠する全てのプルリクエストを受け付けます。これらはほとんどコミュニティで管理されますが、必要な場合は QMK チームも支援します。
|
||||
|
||||
どちらのアプローチもメリットとデメリットがあり、理に適う場合は TMK と QMK の間でコードは自由にやり取りされます。
|
||||
@ -1,160 +0,0 @@
|
||||
# キーマップの FAQ
|
||||
|
||||
<!---
|
||||
original document: 0.13.15:docs/faq_keymap.md
|
||||
git diff 0.13.15 HEAD -- docs/faq_keymap.md | cat
|
||||
-->
|
||||
|
||||
このページは人々がキーマップについてしばしば持つ疑問について説明します。まだ読んだことが無い場合には、[キーマップの概要](ja/keymap.md)を最初に読むべきです。
|
||||
|
||||
## どのキーコードを使えますか？
|
||||
あなたが利用可能なキーコードのインデックスについては、[キーコード](ja/keycodes.md)を見てください。より広範なドキュメントがある場合は、そこからリンクしてあります。
|
||||
|
||||
キーコードは実際には [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/keycode.h) で定義されています。
|
||||
|
||||
## デフォルトのキーコードとは何か？
|
||||
|
||||
世界中で使用されている ANSI、ISO および JIS の3つの標準キーボードがあります。北米では主に ANSI が使われ、ヨーロッパおよびアフリカでは主に ISO が使われ、日本では JIS が使われます。言及されていない地域では、ANSI あるいは ISO が使われています。これらのレイアウトに対応するキーコードは以下の通りです:
|
||||
|
||||
<!-- Source for this image: https://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
|
||||
|
||||
|
||||
## 複雑なキーコードのカスタム名を作成する方法はありますか？
|
||||
|
||||
時には、読みやすくするために、一部のキーコードにカスタム名を定義すると役に立ちます。人々は、しばしば `#define` を使ってカスタム名を定義します。例えば:
|
||||
|
||||
```c
|
||||
#define FN_CAPS LT(_FL, KC_CAPSLOCK)
|
||||
#define ALT_TAB LALT(KC_TAB)
|
||||
```
|
||||
|
||||
これにより、キーマップで `FN_CAPS` と `ALT_TAB` を使えるようになり、読みやすくなります。
|
||||
|
||||
## 一部のキーが入れ替わっているか、または動作しない
|
||||
|
||||
QMK には2つの機能、ブートマジックとコマンドがあり、これによりその場でキーボードの動作を変更することができます。これには Ctrl/Caps の交換、Gui の無効化、Alt/Gui の交換、Backspace/Backslash の交換、全てのキーの無効化およびその他の動作の変更が含まれますが、これらに限定されません。
|
||||
|
||||
迅速な解決策として、キーボードを接続している時に `Space`+`Backspace` を押してみてください。これはキーボードに保存されている設定をリセットし、これらのキーを通常の操作に戻します。うまく行かない場合は、以下を見てください:
|
||||
|
||||
* [ブートマジック](ja/feature_bootmagic.md)
|
||||
* [コマンド](ja/feature_command.md)
|
||||
|
||||
## メニューキーが動作しない
|
||||
|
||||
ほとんどの最近のキーボードにある、`KC_RGUI` と `KC_RCTL` の間にあるキーは、実際には `KC_APP` と呼ばれます。これは、そのキーが発明された時に、関連する標準にすでに `MENU` という名前のキーが存在していたため、MS はそれを `APP` キーと呼ぶことを選択したためです。
|
||||
|
||||
## `KC_SYSREQ` が動作しません
|
||||
`KC_SYSREQ` の代わりに、Print Screen(`KC_PSCREEN` あるいは `KC_PSCR`) のキーコードを使ってください。'Alt + Print Screen' のキーの組み合わせは、'システムリクエスト' と認識されます。
|
||||
|
||||
[issue #168](https://github.com/tmk/tmk_keyboard/issues/168) と以下を見てください
|
||||
* https://en.wikipedia.org/wiki/Magic_SysRq_key
|
||||
* https://en.wikipedia.org/wiki/System_request
|
||||
|
||||
## 電源キーが動作しません
|
||||
|
||||
やや紛らわしいことに、QMK には2つの "Power" キーコードがあります: キーボード/キーパッド HID usage page では `KC_POWER`、Consumer page では `KC_SYSTEM_POWER` (あるいは `KC_PWR`)。
|
||||
|
||||
前者は macOS でのみ認識されますが、後者 `KC_SLEP` および `KC_WAKE` は3つの主要なオペレーティングシステム全てでサポートされるため、これらを使うことをお勧めします。Windows ではこれらのキーはすぐに機能しますが、macOS ではそれらはダイアログが表示されるまで押し続ける必要があります。
|
||||
|
||||
## ワンショットモディファイア
|
||||
私の個人的な 'the' の問題を解決します。'The' ではなく 'the' あるいは 'THe' を間違って入力することがありました。ワンショットシフトはこれを軽減します。
|
||||
https://github.com/tmk/tmk_keyboard/issues/67
|
||||
|
||||
## モディファイヤ/レイヤスタック
|
||||
修飾キーあるいはレイヤは、レイヤの切り替えが適切に設定されていない場合、スタックするかもしれません。
|
||||
修飾キーおよびレイヤ切り替えの場合、リリースイベント時に修飾キーの登録を解除する、もしくは前のレイヤに戻るために、目的のレイヤの同じ位置に `KC_TRANS` を配置する必要があります。
|
||||
|
||||
* https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
|
||||
* https://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
|
||||
* https://github.com/tmk/tmk_keyboard/issues/248
|
||||
|
||||
|
||||
## メカニカルロックスイッチのサポート
|
||||
|
||||
この機能は [Alps](https://deskthority.net/wiki/Alps_SKCL_Lock) のような*メカニカルロックスイッチ*用です。以下を `config.h` に追加することで有効にすることができます:
|
||||
|
||||
```
|
||||
#define LOCKING_SUPPORT_ENABLE
|
||||
#define LOCKING_RESYNC_ENABLE
|
||||
```
|
||||
|
||||
この機能を有効にした後で、キーマップでキーコード `KC_LCAP`、`KC_LNUM` および `KC_LSCR` を使います。
|
||||
|
||||
古いビンテージメカニカルキーボードにはロックスイッチが付いている場合がありますが、最新のものにはありません。***ほとんどの場合この機能は必要なく、単にキーコード `KC_CAPS`、`KC_NUM` および `KC_SCRL`*** を使います。
|
||||
|
||||
## セディーユ 'Ç' のような ASCII 以外の特別文字の入力
|
||||
|
||||
[ユニコード](ja/feature_unicode.md) 機能を見てください。
|
||||
|
||||
## macOS での `Fn` キー
|
||||
|
||||
ほとんどの Fn キーと異なり、Apple のキーボードの Fn キーには実際には独自のキーコードのようなものがあります。基本的な 6KRO HID レポートの6番目のキーコードの代わりになります -- つまり、Apple キーボードは実際には 5KRO のみです。
|
||||
|
||||
QMK にこのキーを送信させることは技術的に可能です。ただし、そうするには Fn キーの状態を追加するためにレポート形式の修正を必要とします。
|
||||
さらに悪いことに、キーボードの VID と PID が実際の Apple のキーボードのものと一致しない限り、認識されません。公式の QMK がこの機能をサポートすることで法的な問題が起きるため、サポートされることはないでしょう。
|
||||
|
||||
詳細については、[この issue](https://github.com/qmk/qmk_firmware/issues/2179) を見てください。
|
||||
|
||||
## Mac OSX でサポートされるキーは？
|
||||
このソースコードから、どのキーコードが OSX でサポートされるかを知ることができます。
|
||||
|
||||
`usb_2_adb_keymap` 配列は、キーボード/キーパッドページの Page usages を ADB スキャンコード(OSX 内部キーコード)にマップします。
|
||||
|
||||
https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c
|
||||
|
||||
`IOHIDConsumer::dispatchConsumerEvent` は Consumer page usages を処理します。
|
||||
|
||||
https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp
|
||||
|
||||
|
||||
## Mac OSX での JIS キー
|
||||
`無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)` のような日本語 JIS キーボード固有のキーは OSX では認識されません。**Seil** を使ってこれらのキーを使うことができます。以下のオプションを試してください。
|
||||
|
||||
* PC キーボードで NFER キーを有効にする
|
||||
* PC キーボードで XFER キーを有効にする
|
||||
* PC キーボードで KATAKANA キーを有効にする
|
||||
|
||||
https://pqrs.org/osx/karabiner/seil.html
|
||||
|
||||
|
||||
## RN-42 Bluetooth が Karabiner で動作しない
|
||||
Karabiner - Mac OSX 上のキーマッピングツール - は、デフォルトでは RN-42 モジュールからの入力を無視します。Karabiner をキーボードで動作させるにはこのオプションを有効にする必要があります。
|
||||
https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237
|
||||
|
||||
この問題の詳細についてはこれらを見てください。
|
||||
https://github.com/tmk/tmk_keyboard/issues/213
|
||||
https://github.com/tekezo/Karabiner/issues/403
|
||||
|
||||
|
||||
## 単一のキーでの Esc と<code>`</code>
|
||||
|
||||
[Grave Escape](ja/feature_grave_esc.md) 機能を見てください。
|
||||
|
||||
## Mac OSX での Eject
|
||||
`KC_EJCT` キーコードは OSX で動作します。https://github.com/tmk/tmk_keyboard/issues/250
|
||||
Windows 10 はコードを無視し、Linux/Xorg は認識しますが、デフォルトではマッピングがありません。
|
||||
|
||||
実際の Apple キーボードにある Eject キーコードは実際には分かりません。HHKB は Mac モードでは Eject キー (`Fn+f`) に `F20` を使いますが、これはおそらく Apple の Eject キーコードと同じではありません。
|
||||
|
||||
|
||||
## `action_util.c` の `weak_mods` と `real_mods` は何か
|
||||
___改善されるべきです___
|
||||
|
||||
real_mods は実際の物理的な修飾キーの状態を保持することを目的にしていますが、weak_mods は実際の修飾キーの状態に影響しない仮想あるいは一時的なモディファイアの状態を保持します。
|
||||
|
||||
物理的な左シフトキーを押しながら ACTION_MODS_KEY(LSHIFT, KC_A) を入力するとします
|
||||
|
||||
weak_mods では、
|
||||
* (1) 左シフトキーを押し続ける: real_mods |= MOD_BIT(LSHIFT)
|
||||
* (2) ACTION_MODS_KEY(LSHIFT, KC_A) を押す: weak_mods |= MOD_BIT(LSHIFT)
|
||||
* (3) ACTION_MODS_KEY(LSHIFT, KC_A) を放す: weak_mods &= ~MOD_BIT(LSHIFT)
|
||||
real_mods はモディファイアの状態を維持します。
|
||||
|
||||
weak mods 無しでは、
|
||||
* (1) 左シフトキーを押し続ける: real_mods |= MOD_BIT(LSHIFT)
|
||||
* (2) ACTION_MODS_KEY(LSHIFT, KC_A) を押す: real_mods |= MOD_BIT(LSHIFT)
|
||||
* (3) ACTION_MODS_KEY(LSHIFT, KC_A) を放す: real_mods &= ~MOD_BIT(LSHIFT)
|
||||
ここで、real_mods は 'physical left shift' '物理的な左シフト' の状態を見失います。
|
||||
|
||||
キーボードレポートが送信される時、weak_mods は real_mods と論理和がとられます。
|
||||
https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57
|
||||
@ -1,103 +0,0 @@
|
||||
# その他の FAQ
|
||||
|
||||
<!---
|
||||
original document: 0.12.45:docs/faq_misc.md
|
||||
git diff 0.12.45 HEAD -- docs/faq_misc.md | cat
|
||||
-->
|
||||
|
||||
## どうやってキーボードをテストすればいいですか？ :id=testing
|
||||
|
||||
通常、キーボードのテストは非常に簡単です。全てのキーをひとつずつ押して、期待するキーが送信されることを確認します。例え QMK で動作していない場合でも、[QMK Configurator](https://config.qmk.fm/#/test/) のテストモードを使用すると、キーボードをチェックできます。
|
||||
|
||||
## 安全性の考慮
|
||||
|
||||
あなたはおそらくキーボードを「文鎮化」したくないでしょう。文鎮化するとファームウェアを書き換えられないようになります。リスクがあまりに高い(そしてそうでないかもしれない)ものの一部のリストを示します。
|
||||
|
||||
- キーボードマップに QK_BOOT が含まれない場合、DFU モードに入るには、PCB のリセットボタンを押す必要があります。底部のネジを外す必要があります。
|
||||
- tmk_core / common にあるファイルを触るとキーボードが操作不能になるかもしれません。
|
||||
- .hex ファイルが大きすぎると問題を引き起こします; `make dfu` コマンドはブロックを削除し、サイズを検査し(おっと、間違った順序です！)、エラーを出力し、
|
||||
キーボードへの書き込みに失敗し、DFU モードのままになります。
|
||||
- この目的のためには、Planck の最大の .hex ファイルサイズは 7000h (10進数で28672)であることに注意してください。
|
||||
|
||||
```
|
||||
Linking: .build/planck_rev4_cbbrowne.elf [OK]
|
||||
Creating load file for Flash: .build/planck_rev4_cbbrowne.hex [OK]
|
||||
|
||||
Size after:
|
||||
text data bss dec hex filename
|
||||
0 22396 0 22396 577c planck_rev4_cbbrowne.hex
|
||||
```
|
||||
|
||||
- 上のファイルのサイズは 22396/577ch で、28672/7000h より小さいです。
|
||||
- 適切な代わりの .hex ファイルがある限り、それをロードして再試行することができます。
|
||||
- あなたがキーボードの Makefile で指定したかもしれない一部のオプションは、余分なメモリを消費します; BOOTMAGIC_ENABLE、MOUSEKEY_ENABLE、EXTRAKEY_ENABLE、CONSOLE_ENABLE、API_SYSEX_ENABLE に注意してください。
|
||||
- DFU ツールは(オプションの余計なフルーツサラダを投げ込まない限り)ブートローダに書き込むことを許可しないので、ここにはリスクはほとんどありません。
|
||||
- EEPROM の書き込みサイクルは、約100000(10万)です。ファームウェアを繰り返し継続的に書き換えるべきではありません。それは最終的に EEPROM を焼き焦がします。
|
||||
|
||||
## NKRO が動作しません
|
||||
最初に、**Makefile** 内でビルドオプション `NKRO_ENABLE` を使ってファームウェアをコンパイルする必要があります。
|
||||
|
||||
**NKRO** がまだ動作しない場合は、`Magic` **N** コマンド(デフォルトでは `LShift+RShift+N`)を試してみてください。**NKRO** モードと **6KRO** モード間を一時的に切り替えるためにこのコマンドを使うことができます。**NKRO** が機能しない状況、特に BIOS の場合は **6KRO** モードに切り替える必要があります。
|
||||
|
||||
|
||||
## トラックポイントははリセット回路が必要です (PS/2 マウスサポート)
|
||||
リセット回路が無いとハードウェアの不適切な初期化のために一貫性の無い結果になります。TPM754 の回路図を見てください:
|
||||
|
||||
- https://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
|
||||
- https://www.mikrocontroller.net/attachment/52583/tpm754.pdf
|
||||
|
||||
|
||||
## 16 を超えるマトリックの列を読み込めない
|
||||
列が 16 を超える場合、[matrix.h] の `read_cols()` 内の `1<<16` の代わりに `1UL<<16` を使ってください。
|
||||
|
||||
C では、AVR の場合 `1` は [16 bit] である [int] 型の1を意味し、15を超えて左にシフトすることはできません。従って、`1<<16` を計算すると予期せずゼロになります。これを回避するには `1UL` として [unsigned long] 型を使う必要があります。
|
||||
|
||||
https://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
|
||||
|
||||
## 特別なエクストラキーが動作しない(システム、オーディオコントロールキー)
|
||||
QMK でそれらを使うには、`rules.mk` 内で `EXTRAKEY_ENABLE` を定義する必要があります。
|
||||
|
||||
```
|
||||
EXTRAKEY_ENABLE = yes # オーディオ制御とシステム制御
|
||||
```
|
||||
|
||||
## スリープから復帰しない
|
||||
|
||||
**デバイスマネージャ**の**電源の管理**タブ内の `このデバイスで、コンピュータのスタンバイ状態を解除できるようにする` 設定を調べてください。また BIOS 設定も調べてください。スリープ中に任意のキーを押すとホストが起動するはずです。
|
||||
|
||||
## Arduino を使っていますか？
|
||||
|
||||
**Arduino のピンの命名は実際のチップと異なることに注意してください。** 例えば、Arduino のピン `D0` は `PD0` ではありません。回路図を自身で確認してください。
|
||||
|
||||
- https://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
|
||||
- https://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf
|
||||
|
||||
Arduino の Leonardo と micro には **ATMega32U4** が載っていて、TMK 用に使うことができますが、Arduino のブートローダが問題になることがあります。
|
||||
|
||||
## JTAG を有効にする
|
||||
|
||||
デフォルトでは、キーボードが起動するとすぐに JTAG デバッグインタフェースが無効になります。JTAG 対応 MCU は `JTAGEN` ヒューズが設定された状態で出荷されており、キーボードがスイッチマトリックス、LED などに使用している可能性のある MCU の特定のピンを乗っ取ります。
|
||||
|
||||
JTAG を有効にしたままにしたい場合は、単に以下のものを `config.h` に追加します:
|
||||
|
||||
```c
|
||||
#define NO_JTAG_DISABLE
|
||||
```
|
||||
|
||||
## USB 3 の互換性
|
||||
一部の問題は、USB 3.x ポートから USB 2.0 ポートに切り替えることで修正できます。
|
||||
|
||||
|
||||
## Mac の互換性
|
||||
### OS X 10.11 と Hub
|
||||
こちらを見てください: https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
|
||||
|
||||
|
||||
## BIOS (UEFI) 設定/リジューム (スリープとウェークアップ)/電源サイクルの問題
|
||||
一部の人がキーボードが BIOS で動作しなくなった、またはリジューム(電源サイクル)の後で動作しなくなったと報告しました。
|
||||
|
||||
今のところ、この問題の根本は明確ではないですが、幾つかのビルドオプションが関係しているようです。Makefile で、`CONSOLE_ENABLE`、`NKRO_ENABLE`、`SLEEP_LED_ENABLE` あるいは他のオプションを無効にしてみてください。
|
||||
|
||||
より詳しい情報:
|
||||
- https://github.com/tmk/tmk_keyboard/issues/266
|
||||
- https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
|
||||
@ -1,185 +0,0 @@
|
||||
# 修飾キー :id=modifier-keys
|
||||
|
||||
<!---
|
||||
original document: 0.14.6:docs/feature_advanced_keycodes.md
|
||||
git diff 0.14.6 HEAD -- docs/feature_advanced_keycodes.md | cat
|
||||
-->
|
||||
|
||||
以下のようにキーコードとモディファイアを組み合わせることができます。押すと、モディファイアのキーダウンイベントが送信され、次に `kc` のキーダウンイベントが送信されます。放すと、`kc` のキーアップイベントが送信され、次にモディファイアのキーアップイベントが送信されます。
|
||||
|
||||
| キー | エイリアス | 説明 |
|
||||
| ---------- | ---------------------------------- | ------------------------------------------------------------------- |
|
||||
| `LCTL(kc)` | `C(kc)` | 左 Control を押しながら `kc` を押します。 |
|
||||
| `LSFT(kc)` | `S(kc)` | 左 Shift を押しながら `kc` を押します。 |
|
||||
| `LALT(kc)` | `A(kc)`, `LOPT(kc)` | 左 Alt を押しながら `kc`を押します。 |
|
||||
| `LGUI(kc)` | `G(kc)`, `LCMD(kc)`, `LWIN(kc)` | 左 GUI を押しながら `kc` を押します。 |
|
||||
| `RCTL(kc)` | | 右 Control を押しながら `kc` を押します。 |
|
||||
| `RSFT(kc)` | | 右 Shift を押しながら `kc` を押します。 |
|
||||
| `RALT(kc)` | `ROPT(kc)`, `ALGR(kc)` | 右 Alt を押しながら `kc` を押します。 |
|
||||
| `RGUI(kc)` | `RCMD(kc)`, `LWIN(kc)` | 右 GUI を押しながら `kc` を押します。 |
|
||||
| `LSG(kc)` | `SGUI(kc)`, `SCMD(kc)`, `SWIN(kc)` | 左 Shift と左 GUI を押しながら `kc` を押します。 |
|
||||
| `LAG(kc)` | | 左 Alt と左 GUI を押しながら `kc` を押します。 |
|
||||
| `RSG(kc)` | | 右 Shift と右 GUI を押しながら `kc` を押します。 |
|
||||
| `RAG(kc)` | | 右 Alt と右 GUI を押しながら `kc` を押します。 |
|
||||
| `LCA(kc)` | | 左 Control と左 Alt を押しながら `kc` を押します。 |
|
||||
| `LSA(kc)` | | 左 Shift と左 Alt を押しながら `kc` を押します。 |
|
||||
| `RSA(kc)` | `SAGR(kc)` | 右 Shift と右 Alt (AltGr) を押しながら `kc` を押します。 |
|
||||
| `RCS(kc)` | | 右 Control と右 Shift を押しながら `kc` を押します。 |
|
||||
| `LCAG(kc)` | | 左 Control、左 Alt、左 GUI を押しながら `kc` を押します。 |
|
||||
| `MEH(kc)` | | 左 Control、左 Shift、左 Alt を押しながら `kc` を押します。 |
|
||||
| `HYPR(kc)` | | 左 Control、左 Shift、左 Alt、左 GUI を押しながら `kc` を押します。 |
|
||||
|
||||
また、それらを繋げることができます。例えば、`LCTL(LALT(KC_DEL))` または `C(A(KC_DEL))` は1回のキー押下で Control+Alt+Delete を送信するキーを作成します。
|
||||
|
||||
# モディファイアの状態を確認 :id=checking-modifier-state
|
||||
|
||||
|
||||
現在のモディファイアの状態は、2つの関数によって主にアクセスされます。: `get_mods()` 関数は通常のモディファイアとモッドタップの状態を、`get_oneshot_mods()` 関数はワンショットモディファイアの状態を確認する関数です。(ワンショットモディファイアはキーが押されていない限り、通常のモディファイアキーのように動作します。)
|
||||
|
||||
1つ以上の特定のモディファイアが現在のモディファイアの状態に含まれているかどうかは、モディファイアの状態と、照合したいモディファイアの組み合わせに相当するモッドマスクとを AND 演算することで検出できます。
|
||||
ビット演算が使われる理由は、モディファイアの状態が (GASC)<sub>R</sub>(GASC)<sub>L</sub> の形式で1バイトとして格納されるためです。
|
||||
|
||||
従って、例を挙げると、`01000010` は LShift+RALT の内部表現です。
|
||||
C 言語におけるビット演算のより詳しい情報は、[ここ](https://en.wikipedia.org/wiki/Bitwise_operations_in_C) をクリックして、Wikipedia のページのトピックを開いてください。
|
||||
|
||||
実際には、`get_mods() & MOD_BIT(KC_<modifier>)`([モディファイアキーコードのリスト](ja/keycodes_basic.md#modifiers) 参照) で、あるモディファイアが有効かどうかをチェックできるということです、また左右のモディファイアの違いが重要ではなく、両方にマッチさせたい場合は、`get_mods() & MOD_MASK_<modifier>`とします。ワンショットモディファイアについても、`get_mods()` を `get_oneshot_mods()` に置き換えれば同じことができます。
|
||||
|
||||
モディファイアの特定の組み合わせが同時にアクティブなのか確認する*だけ*なら、上で説明したモディファイアの状態とモッドマスクの論理積と、モッドマスク自身の結果を比較します。: `get_mods() & <mod mask> == <mod mask>`
|
||||
|
||||
例えば、左 Control キーと 左 Shift キーのワンショットモディファイアがオンで、その他のワンショットモディファイアがオフの場合にカスタムコードを起動したいとしましょう。そうするには、`(MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT))` で左 Control キーと Shift キーのモッドビットを組み合わせて目的のモッドマスクを構成し、それらを差し込みます: `get_oneshot_mods & (MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT)) == (MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT))`。モッドビットマスクの代わりに `MOD_MASK_CS` 使うと、条件を満たすために4つのモディファイアキー (左右両方の Control キーと Shift キー) を押す必要があります。
|
||||
|
||||
モッドマスクの完全なリストは、以下のとおりです。
|
||||
|
||||
| モッドマスク名 | マッチするモディファイア |
|
||||
|--------------------|-------------------------------------------------------------|
|
||||
| `MOD_MASK_CTRL` | 左 Control , 右 Control |
|
||||
| `MOD_MASK_SHIFT` | 左 Shift , 右 Shift |
|
||||
| `MOD_MASK_ALT` | 左 Alt , 右 Alt |
|
||||
| `MOD_MASK_GUI` | 左 GUI , 右 GUI |
|
||||
| `MOD_MASK_CS` | Control , Shift |
|
||||
| `MOD_MASK_CA` | (左/右) Control , (左/右) Alt |
|
||||
| `MOD_MASK_CG` | (左/右) Control , (左/右) GUI |
|
||||
| `MOD_MASK_SA` | (左/右) Shift , (左/右) Alt |
|
||||
| `MOD_MASK_SG` | (左/右) Shift , (左/右) GUI |
|
||||
| `MOD_MASK_AG` | (左/右) Alt , (左/右) GUI |
|
||||
| `MOD_MASK_CSA` | (左/右) Control , (左/右) Shift , (左/右) Alt |
|
||||
| `MOD_MASK_CSG` | (左/右) Control , (左/右) Shift , (左/右) GUI |
|
||||
| `MOD_MASK_CAG` | (左/右) Control , (左/右) Alt , (左/右) GUI |
|
||||
| `MOD_MASK_SAG` | (左/右) Shift , (左/右) Alt , (左/右) GUI |
|
||||
| `MOD_MASK_CSAG` | (左/右) Control , (左/右) Shift , (左/右) Alt , (左/右) GUI |
|
||||
|
||||
`get_mods()` 関数を使って現在アクティブなモディファイアにアクセスする以外に、モディファイアの状態を変更するために使えるいくつかの関数があります。ここでは、`mods` 引数はモディファイアビットマスクを表します。
|
||||
|
||||
* `add_mods(mods)`: その他のモディファイアに影響を与えずに `mods` を有効にします。
|
||||
* `register_mods(mods)`: `add_mods` に似ていますが、キーボードにすぐにレポートを送信します。
|
||||
* `del_mods(mods)`: その他のモディファイアに影響を与えずに `mods` を無効にします。
|
||||
* `unregister_mods(mods)`: `del_mods` に似ていますが、キーボードにすぐにレポートを送信します。
|
||||
* `set_mods(mods)`: `mods` で現在のモディファイアの状態を上書きします
|
||||
* `clear_mods()`: 全てのモディファイアを無効にすることによって、モディファイアの状態をリセットします。
|
||||
|
||||
同様に、`get_oneshot_mods()` 関数に加えて、ワンショットモディファイアのための関数もあります。
|
||||
|
||||
* `add_oneshot_mods(mods)`: その他のワンショットモディファイアに影響を与えずに `mods` を有効にします
|
||||
* `del_oneshot_mods(mods)`: その他のワンショットモディファイアに影響を与えずに `mods` を無効にします
|
||||
* `set_oneshot_mods(mods)`: `mods` で現在のワンショットモディファイアの状態を上書きします
|
||||
* `clear_oneshot_mods()`: 全てのワンショットモディファイアを無効にすることによって、ワンショットモディファイアの状態をリセットします。
|
||||
|
||||
## 例 :id=examples
|
||||
|
||||
次の例は、[マクロについてのページ](ja/feature_macros.md) で読める [高度なマクロ](ja/feature_macros.md?id=advanced-macro-functions) を使っています。
|
||||
### Alt + Tab の代わりの Alt + Escape :id=alt-escape-for-alt-tab
|
||||
|
||||
左 Alt と `KC_ESC` が押されたときに、アプリ切り替えの（左 Alt と） `KC_TAB` のように振る舞うことを実現する単純な例です。この例は、左 Alt だけがアクティブになっているかを厳格に確認します。つまり、Alt+Shift+Esc によるアプリの逆順での切り替えはできません。また、この例は、実際の Alt+Escape キーボードショートカットを起動することはできなくなりますが、AltGr+Escape キーボードショートカットを起動することはできることに留意してください。
|
||||
|
||||
```c
|
||||
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
|
||||
switch (keycode) {
|
||||
|
||||
case KC_ESC:
|
||||
// 左 Alt だけがアクティブか検知します
|
||||
if ((get_mods() & MOD_BIT(KC_LALT)) == MOD_BIT(KC_LALT)) {
|
||||
if (record->event.pressed) {
|
||||
// KC_LALT を登録する必要はありません。既にアクティブだからです。
|
||||
// Alt モディファイアはこの KC_TAB に適用されます。
|
||||
register_code(KC_TAB);
|
||||
} else {
|
||||
unregister_code(KC_TAB);
|
||||
}
|
||||
// QMK にこれ以上キーコードの処理をさせません。
|
||||
return false;
|
||||
}
|
||||
// それ以外の場合は、QMK に通常通り KC_ESC の処理をさせます。
|
||||
return true;
|
||||
|
||||
}
|
||||
return true;
|
||||
};
|
||||
```
|
||||
|
||||
### Delete の代わりの Shift + Backspace :id=shift-backspace-for-delete
|
||||
|
||||
`KC_BSPC` と組み合わせることで Shift の本来の動作が取り消され、そして、`KC_DEL` に完全に置き換えられる高度な例です。この例を適切に動作させるために2つのメイン変数が作られます。: `mod_state` と `delkey_registered` です。最初の1つ目の変数は、モディファイアの状態を記憶し、`KC_DEL` を登録した後に元に戻すために使われます。2つ目の変数はブール型変数 (true または false) で、`KC_DEL` の状態を追跡して Backspace/Delete キー全体のリリースを正確に管理します。
|
||||
|
||||
前の例と対照的に、この例は厳格なモディファイアの確認を行いません。このカスタムコードを起動するには、1つまたは2つの Shift キーがアクティブな間に `KC_BSPC` を押せば十分で、他のモディファイアの状態は関係ありません。この方法は、いくつかの特典を提供します。: Ctrl+Shift+Backspace は次の単語を削除 (Control+Delete) し、Ctrl+Alt+Shift+Backspace は Ctrl+Alt+Del キーボードショートカットを実行します。
|
||||
|
||||
```c
|
||||
// アクティブなモディファイアを表すバイナリデータを保持する変数を初期化します
|
||||
uint8_t mod_state;
|
||||
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
|
||||
// 後々の参照のために現在のモディファイアの状態を変数に格納します
|
||||
mod_state = get_mods();
|
||||
switch (keycode) {
|
||||
|
||||
case KC_BSPC:
|
||||
{
|
||||
// Delete キーの状態（登録されているかどうか）を追跡するブール型変数を初期化します。
|
||||
static bool delkey_registered;
|
||||
if (record->event.pressed) {
|
||||
// いずれかの Shift がアクティブか検知します
|
||||
if (mod_state & MOD_MASK_SHIFT) {
|
||||
// 最初に、 Shift キーを KC_DEL に適用しないため、
|
||||
// 一時的に左右両方の Shift キーをキャンセルします
|
||||
del_mods(MOD_MASK_SHIFT);
|
||||
register_code(KC_DEL);
|
||||
// KC_DEL の状態を反映させるためにブール型変数を更新します
|
||||
delkey_registered = true;
|
||||
// Backspace/Delete キーをタップした後でも押し続けている Shift キーが機能するように、
|
||||
// モディファイアの状態を再適用します。
|
||||
set_mods(mod_state);
|
||||
return false;
|
||||
}
|
||||
} else { // KC_BSPC キーを離した場合
|
||||
// KC_BSPC を離しても KC_DEL が送信されている場合
|
||||
if (delkey_registered) {
|
||||
unregister_code(KC_DEL);
|
||||
delkey_registered = false;
|
||||
return false;
|
||||
}
|
||||
}
|
||||
// QMK に Shift キーを除いて KC_BSPC を通常通り処理させます
|
||||
return true;
|
||||
}
|
||||
|
||||
}
|
||||
return true;
|
||||
};
|
||||
```
|
||||
# 過去の内容 :id=legacy-content
|
||||
|
||||
このページには多くの機能が含まれていました。このページを構成していた多くのセクションをそれぞれのページに移動しました。これより下は全て単なるリダイレクトであるため、web上で古いリンクをたどっている人は探しているものを見つけることができます。
|
||||
|
||||
## レイヤー :id=switching-and-toggling-layers
|
||||
|
||||
* [レイヤー](ja/feature_layers.md)
|
||||
|
||||
## モッドタップ :id=mod-tap
|
||||
|
||||
* [モッドタップ](ja/mod_tap.md)
|
||||
|
||||
## ワンショットキー :id=one-shot-keys
|
||||
|
||||
* [ワンショットキー](ja/one_shot_keys.md)
|
||||
|
||||
## タップホールド設定オプション :id=tap-hold-configuration-options
|
||||
|
||||
* [タップホールド設定オプション](ja/tap_hold.md)
|
||||
@ -1,322 +0,0 @@
|
||||
# オーディオ
|
||||
|
||||
<!---
|
||||
original document: 0.9.0:docs/feature_audio.md
|
||||
git diff 0.9.0 HEAD -- docs/feature_audio.md | cat
|
||||
-->
|
||||
|
||||
キーボードは音を出すことができます！Planck、Preonic あるいは特定の PWM 対応ピンにアクセスできる AVR キーボードがある場合は、単純なスピーカーを接続してビープ音を鳴らすことができます。これらのビープ音を使ってレイヤーの変化、モディファイア、特殊キーを示したり、あるいは単にイカした8ビットの曲を鳴らすことができます。
|
||||
|
||||
最大2つの同時オーディオ音声がサポートされ、1つはタイマー1によってもう一つはタイマー3によって駆動されます。以下のピンは config.h の中でオーディオ出力として定義することができます:
|
||||
|
||||
Timer 1:
|
||||
`#define B5_AUDIO`
|
||||
`#define B6_AUDIO`
|
||||
`#define B7_AUDIO`
|
||||
|
||||
Timer 3:
|
||||
`#define C4_AUDIO`
|
||||
`#define C5_AUDIO`
|
||||
`#define C6_AUDIO`
|
||||
|
||||
`rules.mk` に `AUDIO_ENABLE = yes` を追加すると、他の設定無しで自動的に有効になる幾つかの異なるサウンドがあります:
|
||||
|
||||
```
|
||||
STARTUP_SONG // キーボードの起動時に再生 (audio.c)
|
||||
GOODBYE_SONG // QK_BOOT キーを押すと再生 (quantum.c)
|
||||
AG_NORM_SONG // AG_NORM キーを押すと再生 (quantum.c)
|
||||
AG_SWAP_SONG // AG_SWAP キーを押すと再生 (quantum.c)
|
||||
CG_NORM_SONG // CG_NORM キーを押すと再生 (quantum.c)
|
||||
CG_SWAP_SONG // CG_SWAP キーを押すと再生 (quantum.c)
|
||||
MUSIC_ON_SONG // 音楽モードがアクティブになると再生 (process_music.c)
|
||||
MUSIC_OFF_SONG // 音楽モードが非アクティブになると再生 (process_music.c)
|
||||
CHROMATIC_SONG // 半音階音楽モードが選択された時に再生 (process_music.c)
|
||||
GUITAR_SONG // ギター音楽モードが選択された時に再生 (process_music.c)
|
||||
VIOLIN_SONG // バイオリン音楽モードが選択された時に再生 (process_music.c)
|
||||
MAJOR_SONG // メジャー音楽モードが選択された時に再生 (process_music.c)
|
||||
```
|
||||
|
||||
`config.h` の中で以下のような操作を行うことで、デフォルトの曲を上書きすることができます:
|
||||
|
||||
```c
|
||||
#ifdef AUDIO_ENABLE
|
||||
#define STARTUP_SONG SONG(STARTUP_SOUND)
|
||||
#endif
|
||||
```
|
||||
|
||||
サウンドの完全なリストは、[quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) で見つかります - このリストに自由に追加してください！利用可能な音は [quantum/audio/musical_notes.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/musical_notes.h) で見つかります。
|
||||
|
||||
特定の時にカスタムサウンドを再生するために、以下のように曲を定義することができます(ファイルの上部付近に):
|
||||
|
||||
```c
|
||||
float my_song[][2] = SONG(QWERTY_SOUND);
|
||||
```
|
||||
|
||||
以下のように曲を再生します:
|
||||
|
||||
```c
|
||||
PLAY_SONG(my_song);
|
||||
```
|
||||
|
||||
または、以下のようにループで再生することができます:
|
||||
|
||||
```c
|
||||
PLAY_LOOP(my_song);
|
||||
```
|
||||
|
||||
オーディオがキーボードに組み込まれていない時に問題が起きる事を避けるために、`#ifdef AUDIO_ENABLE` / `#endif` で全てのオーディオ機能をくるむことをお勧めします。
|
||||
|
||||
オーディオで利用可能なキーコードは以下の通りです:
|
||||
|
||||
* `AU_ON` - オーディオ機能をオン
|
||||
* `AU_OFF` - オーディオ機能をオフ
|
||||
* `AU_TOG` - オーディオ機能を切り替え
|
||||
|
||||
!> これらのキーコードは全てのオーディオ機能をオンおよびオフにします。オフにするとオーディオフィードバック、オーディオクリック、音楽モードなどが完全に無効になります。
|
||||
|
||||
## ARM オーディオボリューム
|
||||
|
||||
ARM デバイスの場合、DAC サンプル値を調整できます。キーボードがあなたやあなたの同僚にとって騒々しい場合、`config.h` 内の `DAC_SAMPLE_MAX` を使って最大量を設定することができます:
|
||||
|
||||
```c
|
||||
#define DAC_SAMPLE_MAX 65535U
|
||||
```
|
||||
|
||||
## 音楽モード
|
||||
|
||||
音楽モードは列を半音階に、行をオクターブにマップします。これは格子配列キーボードで最適に動作しますが、他のものでも動作させることができます。`0xFF` 未満の全てのキーコードはブロックされるため、音の演奏中は入力できません - 特別なキー/mod があればそれらは引き続き動作します。これを回避するには、音楽モードを有効にする前(あるいは後)で、KC_NO を使って別のレイヤーにジャンプします。
|
||||
|
||||
メモリの問題により、録音は実験的です - 奇妙な動作が発生した場合は、キーボードの取り外しと再接続で問題が解決するでしょう。
|
||||
|
||||
利用可能なキーコード:
|
||||
|
||||
* `MU_ON` - 音楽モードをオン
|
||||
* `MU_OFF` - 音楽モードをオフ
|
||||
* `MU_TOG` - 音楽モードの切り替え
|
||||
* `MU_MOD` - 音楽モードの循環
|
||||
* `CHROMATIC_MODE` - 半音階。行はオクターブを変更します
|
||||
* `GUITAR_MODE` - 半音階、ただし行は弦を変更します (+5 階)
|
||||
* `VIOLIN_MODE` - 半音階。ただし行は弦を変換します (+7 階)
|
||||
* `MAJOR_MODE` - メージャースケール
|
||||
|
||||
音楽モードでは、以下のキーコードは動作が異なり、通過しません:
|
||||
|
||||
* `LCTL` - 録音を開始
|
||||
* `LALT` - 録音を停止/演奏を停止
|
||||
* `LGUI` - 録音を再生
|
||||
* `KC_UP` - 再生をスピードアップ
|
||||
* `KC_DOWN` - 再生をスローダウン
|
||||
|
||||
ピッチ標準 (`PITCH_STANDARD_A`) はデフォルトで 440.0f です - これを変更するには、`config.h` に以下のようなものを追加します:
|
||||
|
||||
#define PITCH_STANDARD_A 432.0f
|
||||
|
||||
音楽モードも完全に無効にすることができます。コントローラの容量が足りなくて困っている場合に役に立ちます。無効にするには、これを `config.h` に追加します:
|
||||
|
||||
#define NO_MUSIC_MODE
|
||||
|
||||
### 音楽マスク
|
||||
|
||||
デフォルトで、`MUSIC_MASK` は `keycode < 0xFF` に設定されます。これは、`0xFF` 未満のキーコードが音に変換され、何も出力しないことを意味します。`config.h` の中で以下のものを定義することで、これを変更することができます:
|
||||
|
||||
#define MUSIC_MASK keycode != KC_NO
|
||||
|
||||
これは全てのキーコードを捕捉します - これは、キーボードを再起動するまで、音楽モードで動けなくなることに注意してください！
|
||||
|
||||
どのキーコードを引き続き処理するかを制御する、より高度な方法については、`<keyboard>.c` の中の `music_mask_kb(keycode)` および `keymap.c` の中の `music_mask_user(keycode)` を使うことができます:
|
||||
|
||||
bool music_mask_user(uint16_t keycode) {
|
||||
switch (keycode) {
|
||||
case RAISE:
|
||||
case LOWER:
|
||||
return false;
|
||||
default:
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
false を返すものはマスクの一部では無く、常に処理されます。
|
||||
|
||||
### 音楽マップ
|
||||
|
||||
デフォルトでは、音楽モードはキーのスケールを決定するために列と行を使います。キーボードレイアウトに一致する長方形のマトリックスを使うキーボードの場合、これで十分です。しかし、(Planck Rev6 あるいは多くの分割キーボードなどのように)より複雑なマトリックスを使うキーボードの場合、非常に歪んだ感じを受けることになります。
|
||||
|
||||
しかしながら、音楽マップオプションにより、音楽モードのためにスケーリングを再マップすることができるため、レイアウトに一致し、より自然になります。
|
||||
|
||||
この機能を使うには、`#define MUSIC_MAP` を `config.h` ファイルに追加します。そして、`キーボードの名前.c` または `keymap.c` に `uint8_t music_map` を追加します。
|
||||
|
||||
```c
|
||||
const uint8_t music_map[MATRIX_ROWS][MATRIX_COLS] = LAYOUT_ortho_4x12(
|
||||
36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47,
|
||||
24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35,
|
||||
12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23,
|
||||
0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
|
||||
);
|
||||
```
|
||||
|
||||
キーボードが使用する `LAYOUT` マクロも使用したいでしょう。これは正しいキーの位置にマップします。キーボードレイアウトの左下から開始し、右に移動してさらに上に移動します。完全なマトリックスができるまで、全てのエントリを入力します。
|
||||
|
||||
これを実装する方法の例として、[Planck Keyboard](https://github.com/qmk/qmk_firmware/blob/e9ace1487887c1f8b4a7e8e6d87c322988bec9ce/keyboards/planck/planck.c#L24-L29) を見ることができます。
|
||||
|
||||
## オーディオクリック
|
||||
|
||||
これは、ボタンを押すたびにクリック音を追加し、キーボードからのクリック音をシミュレートします。キーを押すたびにわずかに音が異なるため、すばやく入力しても長い単一の音のようには聞こえません。
|
||||
|
||||
* `CK_TOGG` - ステータスを切り替えます (有効にされた場合、音を再生します)
|
||||
* `CK_ON` - オーディオクリックをオンにします (音を再生します)
|
||||
* `CK_OFF` - オーディオクリックをオフにします (音を再生しません）
|
||||
* `CK_RST` - 周波数をデフォルトの状態に再設定します (デフォルトの周波数で音を再生します)
|
||||
* `CK_UP` - クリック音の周波数を増やします (新しい周波数で音を再生します)
|
||||
* `CK_DOWN` - クリック音の周波数を減らします (新しい周波数で音を再生します)
|
||||
|
||||
|
||||
容量を節約するためにデフォルトではこの機能は無効です。有効にするには、`config.h` に以下を追加します:
|
||||
|
||||
#define AUDIO_CLICKY
|
||||
|
||||
|
||||
これらの値を定義することで、デフォルト、最小および最大周波数、ステッピングおよび組み込みのランダム性を設定することができます:
|
||||
|
||||
| オプション | デフォルト値 | 説明 |
|
||||
|--------|---------------|-------------|
|
||||
| `AUDIO_CLICKY_FREQ_DEFAULT` | 440.0f | クリック音のデフォルト/開始音の周波数を設定します。 |
|
||||
| `AUDIO_CLICKY_FREQ_MIN` | 65.0f | 最小周波数を設定します (60f 未満は少しバグがあります)。 |
|
||||
| `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | 最大周波数を設定します。高すぎると同僚があなたを攻撃する可能性があります。 |
|
||||
| `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f | UP/DOWN キーコードのステップを設定します。これは掛け算の係数です。デフォルトでは、音楽のマイナーの1/3ずつ、周波数を上げ/下げします。 |
|
||||
| `AUDIO_CLICKY_FREQ_RANDOMNESS` | 0.05f | クリックのランダム性の係数を設定します。これを `0f` に設定すると各クリックが同一になり、`1.0f` に設定するとこの音は90年代のコンピュータ画面のスクロール/タイピングの効果があります。 |
|
||||
| `AUDIO_CLICKY_DELAY_DURATION` | 1 | 1がテンポの 1/16、または64分音符である整数音符の長さ (実装の詳細については、`quantum/audio/musical_notes.h` を見てください)。メインのクリック効果は、この時間だけ遅れます。これらを6-12前後の値に調整すると、うるさいスイッチの補正に役立ちます。 |
|
||||
|
||||
|
||||
|
||||
|
||||
## MIDI 機能
|
||||
|
||||
これはまだ WIP ですが、何が起きているかを見るために、`quantum/process_keycode/process_midi.c` を調べてください。Makefile から有効にします。
|
||||
|
||||
|
||||
## オーディオキーコード
|
||||
|
||||
| キー | エイリアス | 説明 |
|
||||
|----------------|---------|----------------------------------|
|
||||
| `AU_ON` | | オーディオモードオン |
|
||||
| `AU_OFF` | | オーディオモードオフ |
|
||||
| `AU_TOG` | | オーディオモードを切り替えます |
|
||||
| `CLICKY_TOGGLE` | `CK_TOGG` | オーディオクリックモードを切り替えます |
|
||||
| `CLICKY_UP` | `CK_UP` | クリック音の周波数を増やします |
|
||||
| `CLICKY_DOWN` | `CK_DOWN` | クリック音の周波数を減らします |
|
||||
| `CLICKY_RESET` | `CK_RST` | 周波数をデフォルトに再設定します |
|
||||
| `MU_ON` | | 音楽モードをオンにします |
|
||||
| `MU_OFF` | | 音楽モードをオフにします |
|
||||
| `MU_TOG` | | 音楽モードを切り替えます |
|
||||
| `MU_MOD` | | 音楽モードを循環します |
|
||||
|
||||
<!-- FIXME: this formatting needs work
|
||||
|
||||
## Audio
|
||||
|
||||
```c
|
||||
#ifdef AUDIO_ENABLE
|
||||
AU_ON,
|
||||
AU_OFF,
|
||||
AU_TOG,
|
||||
|
||||
// Music mode on/off/toggle
|
||||
MU_ON,
|
||||
MU_OFF,
|
||||
MU_TOG,
|
||||
|
||||
// Music voice iterate
|
||||
MUV_IN,
|
||||
MUV_DE,
|
||||
#endif
|
||||
```
|
||||
|
||||
### Midi
|
||||
|
||||
#if !MIDI_ENABLE_STRICT || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))
|
||||
MI_ON, // send midi notes when music mode is enabled
|
||||
MI_OFF, // don't send midi notes when music mode is enabled
|
||||
#endif
|
||||
|
||||
MIDI_TONE_MIN,
|
||||
MIDI_TONE_MAX
|
||||
|
||||
MI_C = MIDI_TONE_MIN,
|
||||
MI_Cs,
|
||||
MI_Db = MI_Cs,
|
||||
MI_D,
|
||||
MI_Ds,
|
||||
MI_Eb = MI_Ds,
|
||||
MI_E,
|
||||
MI_F,
|
||||
MI_Fs,
|
||||
MI_Gb = MI_Fs,
|
||||
MI_G,
|
||||
MI_Gs,
|
||||
MI_Ab = MI_Gs,
|
||||
MI_A,
|
||||
MI_As,
|
||||
MI_Bb = MI_As,
|
||||
MI_B,
|
||||
|
||||
MIDI_TONE_KEYCODE_OCTAVES > 1
|
||||
|
||||
where x = 1-5:
|
||||
MI_C_x,
|
||||
MI_Cs_x,
|
||||
MI_Db_x = MI_Cs_x,
|
||||
MI_D_x,
|
||||
MI_Ds_x,
|
||||
MI_Eb_x = MI_Ds_x,
|
||||
MI_E_x,
|
||||
MI_F_x,
|
||||
MI_Fs_x,
|
||||
MI_Gb_x = MI_Fs_x,
|
||||
MI_G_x,
|
||||
MI_Gs_x,
|
||||
MI_Ab_x = MI_Gs_x,
|
||||
MI_A_x,
|
||||
MI_As_x,
|
||||
MI_Bb_x = MI_As_x,
|
||||
MI_B_x,
|
||||
|
||||
MI_OCT_Nx 1-2
|
||||
MI_OCT_x 0-7
|
||||
MIDI_OCTAVE_MIN = MI_OCT_N2,
|
||||
MIDI_OCTAVE_MAX = MI_OCT_7,
|
||||
MI_OCTD, // octave down
|
||||
MI_OCTU, // octave up
|
||||
|
||||
MI_TRNS_Nx 1-6
|
||||
MI_TRNS_x 0-6
|
||||
MIDI_TRANSPOSE_MIN = MI_TRNS_N6,
|
||||
MIDI_TRANSPOSE_MAX = MI_TRNS_6,
|
||||
MI_TRNSD, // transpose down
|
||||
MI_TRNSU, // transpose up
|
||||
|
||||
MI_VEL_x 1-10
|
||||
MIDI_VELOCITY_MIN = MI_VEL_1,
|
||||
MIDI_VELOCITY_MAX = MI_VEL_9,
|
||||
MI_VELD, // velocity down
|
||||
MI_VELU, // velocity up
|
||||
|
||||
MI_CHx 1-16
|
||||
MIDI_CHANNEL_MIN = MI_CH1
|
||||
MIDI_CHANNEL_MAX = MI_CH16,
|
||||
MI_CHD, // previous channel
|
||||
MI_CHU, // next channel
|
||||
|
||||
MI_ALLOFF, // all notes off
|
||||
|
||||
MI_SUS, // sustain
|
||||
MI_PORT, // portamento
|
||||
MI_SOST, // sostenuto
|
||||
MI_SOFT, // soft pedal
|
||||
MI_LEG, // legato
|
||||
|
||||
MI_MOD, // modulation
|
||||
MI_MODSD, // decrease modulation speed
|
||||
MI_MODSU, // increase modulation speed
|
||||
#endif // MIDI_ADVANCED
|
||||
|
||||
-->
|
||||
@ -1,135 +0,0 @@
|
||||
# 自動シフト: なぜシフトキーが必要ですか？
|
||||
|
||||
<!---
|
||||
original document: 0.10.33:docs/feature_auto_shift.md
|
||||
git diff 0.10.33 HEAD -- docs/feature_auto_shift.md | cat
|
||||
-->
|
||||
|
||||
キーをタップすると、その文字を取得します。キーをタップするが、*わずかに*長く押し続けると、シフト状態になります。ほら！シフトキーは必要ありません！
|
||||
|
||||
## なぜ自動シフトなのですか？
|
||||
|
||||
多くの人が腱鞘炎などの症状に苦しんでいます。一般的な原因は、指を繰り返し長い距離を伸ばすことです。私たちはキーボード上でシフトキーに手を伸ばすためにあまりにも頻繁に小指を伸ばします。自動シフトキーはそれを軽減しようとしています。
|
||||
|
||||
## どのように動作しますか？
|
||||
|
||||
キーをタップする時に、キーを放す前にほんの短い間押したままにします。この押したままにする時間は全ての人にとって異なる長さです。自動シフトは、定数 `AUTO_SHIFT_TIMEOUT` を定義し、これは普段の押された状態の時間の2倍に通常は設定されます。タイマーは、キーを押す時に開始され、キーを放す時に止まります。押された時間が `AUTO_SHIFT_TIMEOUT` 以上の場合に、キーのシフトバージョンが発行されます。時間が `AUTO_SHIFT_TIMEOUT` 時間よりも短い場合は、通常の状態が発行されます。
|
||||
|
||||
## 自動シフトには制限がありますか？
|
||||
|
||||
残念ながらあります。
|
||||
|
||||
1. キーリピートが動作しなくなります。例えば、20個の 'a' 文字が必要な場合、'a' キーを1、2秒押し続けるかもしれません。オペレーティングシステムに押されたキーの状態を発行する代わりに押された時間を計るので、自動シフトでは動作しません。
|
||||
2. シフトをするつもりがない時にシフトされた文字を取得し、シフトしたい時にそうではない他の文字を取得するでしょう。これは結局は練習になります。急いでいる時は、シフトされたバージョンのために十分長くキーを押したと思うかもしれませんが、そうではありませんでした。一方、キーをタップしていると思うかもしれませんが、実際には予想よりも少し長い間押していました。
|
||||
|
||||
## どうやって自動シフトを有効にしますか？
|
||||
|
||||
キーマップフォルダの `rules.mk` に追加します:
|
||||
|
||||
AUTO_SHIFT_ENABLE = yes
|
||||
|
||||
`rules.mk` が存在しない場合、それを作成することができます。
|
||||
|
||||
そして自動シフトキーを有効にした新しいファームウェアをコンパイルしてインストールします！以上です！
|
||||
|
||||
## モディファイア
|
||||
|
||||
デフォルトで、1つ以上のモディファイアと一緒にキーが押されると自動シフトは無効になります。従って、本当に長い間 Ctrl+A を保持しても、Ctrl+Shift+A と同じではありません。
|
||||
|
||||
`config.h` に定義を追加することで、モディファイアの自動シフトを再度有効にすることができます
|
||||
|
||||
```c
|
||||
#define AUTO_SHIFT_MODIFIERS
|
||||
```
|
||||
|
||||
この場合、`AUTO_SHIFT_TIMEOUT` を超えて押された Ctrl+A は Ctrl+Shift+A として送信されます
|
||||
|
||||
|
||||
## 自動シフトの設定
|
||||
|
||||
必要に応じて、自動シフトの挙動を変更することができる幾つかの設定があります。キーマップフォルダにある `config.h` に様々な変数を設定することで行われます。`config.h` ファイルが存在しない場合、それを作成することができます。
|
||||
|
||||
例
|
||||
|
||||
```c
|
||||
#pragma once
|
||||
|
||||
#define AUTO_SHIFT_TIMEOUT 150
|
||||
#define NO_AUTO_SHIFT_SPECIAL
|
||||
```
|
||||
|
||||
### AUTO_SHIFT_TIMEOUT (単位: ミリ秒)
|
||||
|
||||
これは、シフトされた状態を取得するためにどれだけ長くキーを押し続けなければならないかを制御します。
|
||||
明らかにこれは人によって異なります。一般的な人にとって、135 から 150 の設定がうまく機能します。ただし、少なくとも 175 の値から開始する必要があります。これはデフォルト値です。その後、ここから下げていきます。間違って検出することなくシフトされた状態を取得するのに必要な、最も短い時間を得るという考え方です。
|
||||
|
||||
完璧に動作するまで、いろいろな値を試してみます。多くの人は、全てが所定の値で適切に動作するものの、時々、1つあるいは2つのキーがシフト状態を発行することが分かるでしょう。これは単に習慣と、幾つかのキーを他のキーよりも少し長く押し続けることによるものです。この値を見つけたら、問題のキーを通常よりも少し早くタップするとともに、その値を設定します。
|
||||
|
||||
?> 自動シフトには、この値を素早く取得するのに役立つ3つの特別なキーがあります。詳細は「自動シフトのセットアップ」を見てください！
|
||||
|
||||
### NO_AUTO_SHIFT_SPECIAL (単純にこのように定義します)
|
||||
|
||||
-\_, =+, [{, ]}, ;:, '", ,<, .> および /? を含む特殊キーを自動シフトしません
|
||||
|
||||
### NO_AUTO_SHIFT_NUMERIC (単純にこのように定義します)
|
||||
|
||||
0から9までの数字キーを自動シフトしません。
|
||||
|
||||
### NO_AUTO_SHIFT_ALPHA (単純にこのように定義します)
|
||||
|
||||
AからZを含むアルファベット文字を自動シフトしません。
|
||||
|
||||
## 自動シフトセットアップの使用
|
||||
|
||||
これにより、`AUTO_SHIFT_TIMEOUT` で設定している時間を一時的に増減させたり報告するために、3つのキーを定義することができます。
|
||||
|
||||
### セットアップ
|
||||
|
||||
3つのキーを一時的にキーマップにマップします:
|
||||
|
||||
| キー名 | 説明 |
|
||||
|----------|-----------------------------------------------------|
|
||||
| KC_ASDN | 自動シフトタイムアウト変数を下げる |
|
||||
| KC_ASUP | 自動シフトタイムアウト変数を上げる |
|
||||
| KC_ASRP | 現在の自動シフトタイムアウト値を報告する |
|
||||
| KC_ASON | 自動シフト機能をオンにする |
|
||||
| KC_ASOFF | 自動シフト機能をオフにする |
|
||||
| KC_ASTG | 自動シフト機能の状態を切り替える |
|
||||
|
||||
新しいファームウェアをコンパイルしてアップロードします。
|
||||
|
||||
### 使い方
|
||||
|
||||
これらのテスト中は、完全に普段通り入力する必要があり、意図的にシフトされたキーを使わずに入力するように注意する必要があります。
|
||||
|
||||
1. アルファベットの複数の文を入力します。
|
||||
2. 大文字に注意してください。
|
||||
3. 大文字が存在しない場合は、自動シフトタイムアウト値を減らすために `KC_ASDN` にマップしたキーを押し、ステップ1に戻ります。
|
||||
4. 大文字が幾つかある場合は、押す時間を短くしてこれらのキーをタップする必要があるか、あるいはタイムアウトを増やす必要があるかを決定します。
|
||||
5. タイムアウトを増やすことに決めた場合は、`KC_ASUP` にマップしたキーを押し、ステップ1に戻ります。
|
||||
6. 結果に満足したら、`KC_ASRP` にマップしたキーを押します。キーボードは `AUTO_SHIFT_TIMEOUT` の値を自動的に入力します。
|
||||
7. 報告された値で `config.h` の `AUTO_SHIFT_TIMEOUT` を更新します。
|
||||
8. `config.h` に `AUTO_SHIFT_NO_SETUP` を追加します。
|
||||
9. `KC_ASDN`、`KC_ASUP` および `KC_ASRP` のキーバインディングを削除します。
|
||||
10. 新しいファームウェアをコンパイルしてアップロードします。
|
||||
|
||||
#### 実行例
|
||||
|
||||
hello world. my name is john doe. i am a computer programmer playing with
|
||||
keyboards right now.
|
||||
|
||||
[KC_ASDN を何度か押します]
|
||||
|
||||
heLLo woRLd. mY nAMe is JOHn dOE. i AM A compUTeR proGRaMMER PlAYiNG witH
|
||||
KEYboArDS RiGHT NOw.
|
||||
|
||||
[KC_ASUP を数回押します]
|
||||
|
||||
hello world. my name is john Doe. i am a computer programmer playing with
|
||||
keyboarDs right now.
|
||||
|
||||
[KC_ASRPを押します]
|
||||
|
||||
115
|
||||
|
||||
キーボードは現在の `AUTO_SHIFT_TIMEOUT` 値を表す `115` を入力しました。これで設定が完了しました！テスト中に現れる *D* キーを少し練習してください。それで完璧です。
|
||||
@ -1,225 +0,0 @@
|
||||
# バックライト :id=backlighting
|
||||
|
||||
<!---
|
||||
original document: 0.14.14:docs/feature_backlight.md
|
||||
git diff 0.14.14 HEAD -- docs/feature_backlight.md | cat
|
||||
-->
|
||||
|
||||
多くのキーボードは、キースイッチを貫通して配置されたり、キースイッチの下に配置された個々の LED によって、バックライトキーをサポートします。この機能は通常スイッチごとに単一の色しか使用できないため、[RGB アンダーグロー](ja/feature_rgblight.md)および [RGB マトリックス](ja/feature_rgb_matrix.md)機能のどちらとも異なりますが、キーボードに複数の異なる単一色の LED を取り付けることは当然可能です。
|
||||
|
||||
QMK は *パルス幅変調* (*Pulse Width Modulation*) すなわち PWM として知られている技術で、一定の比率で素早くオンおよびオフを切り替えることで、これらの LED の輝度を制御できます。PWM 信号のデューティサイクルを変えることで、調光の錯覚を起こすことができます。
|
||||
|
||||
MCU は、GPIO ピンにはそんなに電流を供給できません。MCU から直接バックライトに給電せずに、バックライトピンは LED への電力を切り替えるトランジスタあるいは MOSFET に接続されます。
|
||||
|
||||
ほとんどのキーボードではバックライトをサポートしている場合にデフォルトで有効になっていますが、もし機能しない場合は `rules.mk` が以下を含んでいることを確認してください:
|
||||
|
||||
```makefile
|
||||
BACKLIGHT_ENABLE = yes
|
||||
```
|
||||
|
||||
## キーコード :id=keycodes
|
||||
|
||||
有効にすると、以下のキーコードを使ってバックライトレベルを変更することができます。
|
||||
|
||||
| キー | 説明 |
|
||||
| --------- | ------------------------------------ |
|
||||
| `BL_TOGG` | バックライトをオンあるいはオフにする |
|
||||
| `BL_STEP` | バックライトレベルを循環する |
|
||||
| `BL_ON` | バックライトを最大輝度に設定する |
|
||||
| `BL_OFF` | バックライトをオフにする |
|
||||
| `BL_INC` | バックライトレベルを上げる |
|
||||
| `BL_DEC` | バックライトレベルを下げる |
|
||||
| `BL_BRTG` | バックライトの明滅動作を切り替える |
|
||||
|
||||
## 関数群 :id=functions
|
||||
|
||||
次の関数を使って、カスタムコードでバックライトを変更することができます:
|
||||
|
||||
| 関数 | 説明 |
|
||||
| ------------------------ | -------------------------------------------- |
|
||||
| `backlight_toggle()` | バックライトをオンあるいはオフにする |
|
||||
| `backlight_enable()` | バックライトをオンにする |
|
||||
| `backlight_disable()` | バックライトをオフにする |
|
||||
| `backlight_step()` | バックライトレベルを循環する |
|
||||
| `backlight_increase()` | バックライトレベルを上げる |
|
||||
| `backlight_decrease()` | バックライトレベルを下げる |
|
||||
| `backlight_level(x)` | バックライトのレベルを特定のレベルに設定する |
|
||||
| `get_backlight_level()` | 現在のバックライトレベルを返す |
|
||||
| `is_backlight_enabled()` | バックライトが現在オンかどうかを返す |
|
||||
|
||||
バックライトの明滅が有効の場合(以下を参照)、以下の関数も利用できます:
|
||||
|
||||
| 関数 | 説明 |
|
||||
|-----------------------|----------------------------------------------|
|
||||
| `breathing_toggle()` | バックライトの明滅動作をオンまたはオフにする |
|
||||
| `breathing_enable()` | バックライトの明滅動作をオンにする |
|
||||
| `breathing_disable()` | バックライトの明滅動作をオフにする |
|
||||
|
||||
## 設定 :id=configuration
|
||||
|
||||
どのドライバを使うかを選択するには、以下を使って `rules.mk` を設定します:
|
||||
|
||||
```makefile
|
||||
BACKLIGHT_DRIVER = software
|
||||
```
|
||||
|
||||
有効なドライバの値は `pwm`, `software`, `custom`, `no` です。各ドライバについてのヘルプは以下を見てください。
|
||||
|
||||
バックライトを設定するには、`config.h` の中で以下の `#define` をします:
|
||||
|
||||
| 定義 | デフォルト | 説明 |
|
||||
| ----------------------------- | ------------------ | --------------------------------------------------------------------------------------------- |
|
||||
| `BACKLIGHT_PIN` | *定義なし* | LED を制御するピン |
|
||||
| `BACKLIGHT_LEVELS` | `3` | 輝度のレベルの数 (オフを除いて最大 31) |
|
||||
| `BACKLIGHT_CAPS_LOCK` | *定義なし* | バックライトを使って Caps Lock のインジケータを有効にする (専用 LED の無いキーボードのため) |
|
||||
| `BACKLIGHT_BREATHING` | *定義なし* | サポートされる場合は、バックライトの明滅動作を有効にする |
|
||||
| `BREATHING_PERIOD` | `6` | 各バックライトの "明滅" の長さ（秒） |
|
||||
| `BACKLIGHT_ON_STATE` | `1` | バックライトが "オン" の時のバックライトピンの状態 - high の場合は `1`、low の場合は `0` |
|
||||
| `BACKLIGHT_LIMIT_VAL` | `255` | バックライトの最大デューティサイクル -- `255` で最大輝度になり、それ未満では最大値が減少する |
|
||||
| `BACKLIGHT_DEFAULT_LEVEL` | `BACKLIGHT_LEVELS` | EEPROM をクリアする時に使うデフォルトのバックライトレベル |
|
||||
| `BACKLIGHT_DEFAULT_BREATHING` | *定義なし* | EEPROM をクリアする時に、バックライトのブリージングを有効にするかどうか |
|
||||
|
||||
独自のキーボードを設計しているわけではない限り、通常は `BACKLIGHT_PIN` または `BACKLIGHT_ON_STATE` を変更する必要はありません。
|
||||
|
||||
### バックライトオン状態 :id=backlight-on-state
|
||||
|
||||
ほとんどのバックライトの回路は N チャンネルの MOSFET あるいは NPN トランジスタによって駆動されます。これは、トランジスタを *オン* にして LED を点灯させるには、ゲートまたはベースに接続されているバックライトピンを *high* に駆動する必要があることを意味します。
|
||||
ただし、P チャンネルの MOSFET あるいは PNP トランジスタが使われる場合があります。この場合、トランジスタがオンの時、ピンは代わりに *low* で駆動されます。
|
||||
|
||||
この機能は `BACKLIGHT_ON_STATE` を定義することでキーボードレベルで設定されます。
|
||||
|
||||
### AVR ドライバ :id=avr-driver
|
||||
|
||||
`pwm` ドライバはデフォルトで設定されますが、`rules.mk` 内での同等の設定は以下の通りです:
|
||||
|
||||
```makefile
|
||||
BACKLIGHT_DRIVER = pwm
|
||||
```
|
||||
|
||||
#### 注意事項 :id=avr-caveats
|
||||
|
||||
AVR ボードでは、QMK はどのドライバを使うかを以下の表に従って自動的に決定します:
|
||||
|
||||
| バックライトピン | AT90USB64/128 | AT90USB162 | ATmega16/32U4 | ATmega16/32U2 | ATmega32A | ATmega328/P |
|
||||
| ---------------- | ------------- | ---------- | ------------- | ------------- | --------- | ----------- |
|
||||
| `B1` | | | | | | Timer 1 |
|
||||
| `B2` | | | | | | Timer 1 |
|
||||
| `B5` | Timer 1 | | Timer 1 | | | |
|
||||
| `B6` | Timer 1 | | Timer 1 | | | |
|
||||
| `B7` | Timer 1 | Timer 1 | Timer 1 | Timer 1 | | |
|
||||
| `C4` | Timer 3 | | | | | |
|
||||
| `C5` | Timer 3 | Timer 1 | | Timer 1 | | |
|
||||
| `C6` | Timer 3 | Timer 1 | Timer 3 | Timer 1 | | |
|
||||
| `D4` | | | | | Timer 1 | |
|
||||
| `D5` | | | | | Timer 1 | |
|
||||
|
||||
他の全てのピンはタイマー支援ソフトウェア PWM を使います。
|
||||
|
||||
| オーディオピン | オーディオタイマ | ソフトウェア PWM タイマ |
|
||||
| -------------- | ---------------- | ----------------------- |
|
||||
| `C4` | Timer 3 | Timer 1 |
|
||||
| `C5` | Timer 3 | Timer 1 |
|
||||
| `C6` | Timer 3 | Timer 1 |
|
||||
| `B5` | Timer 1 | Timer 3 |
|
||||
| `B6` | Timer 1 | Timer 3 |
|
||||
| `B7` | Timer 1 | Timer 3 |
|
||||
|
||||
両方のタイマーがオーディオのために使われている場合、バックライト PWM はハードウェアタイマを使うことができず、代わりにマトリックススキャンの間に引き起こされます。この場合、PWM の計算は十分なタイミングの精度で呼ばれない可能性があるため、バックライトの明滅はサポートされず、バックライトもちらつくかもしれません。
|
||||
|
||||
#### ハードウェア PWM 実装 :id=hardware-pwm-implementation
|
||||
|
||||
バックライト用にサポートされているピンを使う場合、QMK は PWM 信号を出力するように設定されたハードウェアタイマを使います。タイマーは 0 にリセットする前に `ICRx` (デフォルトでは `0xFFFF`) までカウントします。
|
||||
希望の輝度が計算され、`OCRxx` レジスタに格納されます。カウンタがこの値まで達すると、バックライトピンは low になり、カウンタがリセットされると再び high になります。
|
||||
このように `OCRxx` は基本的に LED のデューティサイクル、従って輝度を制御します。`0x0000` は完全にオフで、 `0xFFFF` は完全にオンです。
|
||||
|
||||
明滅動作の効果はカウンタがリセットされる(秒間あたりおよそ244回)たびに呼び出される `TIMER1_OVF_vect` の割り込みハンドラを登録することで可能になります。
|
||||
このハンドラで、増分カウンタの値が事前に計算された輝度曲線にマップされます。明滅動作をオフにするには、割り込みを単純に禁止し、輝度を EEPROM に格納されているレベルに再設定します。
|
||||
|
||||
#### タイマー支援 PWM 実装 :id=timer-assisted-implementation
|
||||
|
||||
`BACKLIGHT_PIN` がハードウェアバックライトピンに設定されていない場合、QMK はソフトウェア割り込みを引き起こすように設定されているハードウェアタイマを使います。タイマーは 0 にリセットする前に `ICRx` (デフォルトでは `0xFFFF`) までカウントします。
|
||||
0 に再設定すると、CPU は LED をオンにする OVF (オーバーフロー)割り込みを発火し、デューティサイクルを開始します。
|
||||
希望の輝度が計算され、`OCRxx` レジスタに格納されます。カウンタがこの値に達すると、CPU は比較出力一致割り込みを発火し、LED をオフにします。
|
||||
このように `OCRxx` は基本的に LED のデューティサイクル、従って輝度を制御します。 `0x0000` は完全にオフで、 `0xFFFF` は完全にオンです。
|
||||
|
||||
明滅の効果はハードウェア PWM 実装と同じです。
|
||||
|
||||
### ARM ドライバ :id=arm-configuration
|
||||
|
||||
まだ初期段階ですが、ARM バックライトサポートは最終的に AVR と同等の機能を持つことを目指しています。`pwm` ドライバはデフォルトで設定されますが、`rules.mk` 内での同等の設定は以下の通りです:
|
||||
|
||||
```makefile
|
||||
BACKLIGHT_DRIVER = pwm
|
||||
```
|
||||
|
||||
#### ChibiOS の設定 :id=arm-configuration
|
||||
|
||||
以下の `#define` は ARM ベースのキーボードにのみ適用されます:
|
||||
|
||||
| 定義 | デフォルト | 説明 |
|
||||
| ----------------------- | ---------- | ----------------------- |
|
||||
| `BACKLIGHT_PWM_DRIVER` | `PWMD4` | 使用する PWM ドライバ |
|
||||
| `BACKLIGHT_PWM_CHANNEL` | `3` | 使用する PWM チャンネル |
|
||||
| `BACKLIGHT_PAL_MODE` | `2` | 使用するピン代替関数 |
|
||||
|
||||
これらの値を決定するには、特定の MCU の ST データシートを参照してください。独自のキーボードを設計しているわけではない場合、通常はこれらを変更する必要はありません。
|
||||
|
||||
#### 注意事項 :id=arm-caveats
|
||||
|
||||
現在のところ、ハードウェア PWM のみがサポートされ、タイマー支援はなく、自動設定は提供されません。
|
||||
|
||||
### ソフトウェア PWM ドライバ :id=software-pwm-driver
|
||||
|
||||
このモードでは、他のキーボードのタスクを実行中に PWM は「エミュレート」されます。追加のプラットフォーム設定なしで最大のハードウェア互換性を提供します。トレードオフは、キーボードが忙しい時にバックライトが揺れる可能性があることです。有効にするには、`rules.mk` に以下を追加します:
|
||||
|
||||
```makefile
|
||||
BACKLIGHT_DRIVER = software
|
||||
```
|
||||
|
||||
#### 複数のバックライトピン :id=multiple-backlight-pins
|
||||
|
||||
ほとんどのキーボードは、全てのバックライト LED を制御するたった1つのバックライトピンを持ちます (特にバックライトがハードウェア PWM ピンに接続されている場合)。
|
||||
ソフトウェア PWM では、複数のバックライトピンを定義することができます。これらのピンは PWM デューティサイクル時に同時にオンおよびオフになります。
|
||||
|
||||
この機能により、例えば Caps Lock LED (またはその他の制御可能な LED) の輝度を、バックライトの他の LED と同じレベルに設定することができます。Caps Lock LED は通常バックライトとは別のピンに配線されるため、Caps Lock の代わりに Control をマップしていて、Caps Lock がオンの時に Caps Lock LED ではなくバックライトの一部をアクティブにする必要がある場合に便利です。
|
||||
|
||||
複数のバックライトピンをアクティブにするには、`config.h` に `BACKLIGHT_PIN` の代わりに次のようなものを追加します:
|
||||
|
||||
```c
|
||||
#define BACKLIGHT_PINS { F5, B2 }
|
||||
```
|
||||
|
||||
### カスタムドライバ :id=custom-driver
|
||||
|
||||
上記ドライバのいずれもキーボードに適用されていない場合(例えば、バックライトを制御するのに別の IC を使用している場合)、QMK が提供しているこの簡単な API を使ってカスタムバックライトドライバを実装することができます。有効にするには、`rules.mk` に以下を追加します:
|
||||
|
||||
```makefile
|
||||
BACKLIGHT_DRIVER = custom
|
||||
```
|
||||
|
||||
それから次のフックのいずれかを実装します:
|
||||
|
||||
```c
|
||||
void backlight_init_ports(void) {
|
||||
// オプション - 起動時に実行されます
|
||||
// 通常、ここでピンを設定します
|
||||
}
|
||||
void backlight_set(uint8_t level) {
|
||||
// オプション - レベルの変更時に実行されます
|
||||
// 通常、ここで新しい値に応答します
|
||||
}
|
||||
|
||||
void backlight_task(void) {
|
||||
// オプション - 定期的に実行されます
|
||||
// これはメインキーボードループで呼び出されることに注意してください
|
||||
// そのため、ここで長時間実行されるアクションはパフォーマンスの問題を引き起こします
|
||||
}
|
||||
```
|
||||
|
||||
## 回路図の例
|
||||
|
||||
この一般的な例では、バックライト LED は全て N チャンネル MOSFET に向かって並列に接続されています。そのゲートピンは、リンギングを回避するため 470Ωの抵抗を介してマイクロコントローラの GPIO ピンの1つに接続されています。
|
||||
プルダウン抵抗もゲートピンとグランドの間に配置されており、MCU によって駆動されていない場合にプルダウン抵抗を定義された状態に保ちます。
|
||||
これらの抵抗値は重要ではありません。詳細については、[this Electronics StackExchange question](https://electronics.stackexchange.com/q/68748) を参照してください。
|
||||
|
||||
|
||||
@ -1,49 +0,0 @@
|
||||
# Bluetooth
|
||||
|
||||
<!---
|
||||
original document: 0.10.33:docs/feature_bluetooth.md
|
||||
git diff 0.10.33 HEAD -- docs/feature_bluetooth.md | cat
|
||||
-->
|
||||
|
||||
## Bluetooth の既知のサポートハードウェア
|
||||
|
||||
現在のところ Bluetooth のサポートは AVR ベースのチップに限られます。Bluetooth 2.1 については、QMK は RN-42 モジュールをサポートします。より最近の BLE プロトコルについては、現在のところ Adafruit Bluefruit SPI Friend のみが直接サポートされています。iOS デバイスに接続するには、BLE が必要です。iOS はマウス入力をサポートしないことに注意してください。
|
||||
|
||||
| ボード | Bluetooth プロトコル | 接続タイプ | rules.mk | Bluetooth チップ |
|
||||
| ---------------------------------------------------------------- | -------------------- | ---------- | ------------------------- | ---------------- |
|
||||
| Roving Networks RN-42 (Sparkfun Bluesmirf) | Bluetooth Classic | UART | `BLUETOOTH = RN42` | RN-42 |
|
||||
| [Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633) | Bluetooth Low Energy | SPI | `BLUETOOTH = AdafruitBLE` | nRF51822 |
|
||||
|
||||
まだサポートされていませんが、可能性のあるもの:
|
||||
* [Bluefruit LE UART Friend](https://www.adafruit.com/product/2479)。[tmk 実装がおそらく見つかります](https://github.com/tmk/tmk_keyboard/issues/514)
|
||||
* RN-42 ファームウェアが書き込まれた HC-05 ボード。どちらも明らかに CSR BC417 チップを使っています。RN-42 ファームウェアを使って書き込むと、HID 機能が提供されます。
|
||||
* Sparkfun Bluetooth Mate
|
||||
* HM-13 ベースのボード
|
||||
|
||||
### Adafruit BLE SPI Friend
|
||||
現在のところ QMK によってサポートされている唯一の bluetooth チップセットは、Adafruit Bluefruit SPI Friend です。Adafruit のカスタムファームウェアを実行する Nordic nRF5182 ベースのチップです。データは Hardware SPI を介した Adafruit の SDEP を使って転送されます。[Feather 32u4 Bluefruit LE](https://www.adafruit.com/product/2829) は Adafruit ファームウェアを搭載した Nordic BLE チップに SPI 経由で接続された AVR mcu であるため、サポートされます。SPI friend を使ってカスタムボードを構築する場合、32u4 feather が使用するピン選択を使うのが最も簡単ですが、以下の定義で config.h オプションでピンを変更することができます:
|
||||
* #define AdafruitBleResetPin D4
|
||||
* #define AdafruitBleCSPin B4
|
||||
* #define AdafruitBleIRQPin E6
|
||||
|
||||
Bluefruit UART friend は SPI friend に変換することができますが、これにはMDBT40 チップへの直接の再書き込みとはんだ付けが[必要です](https://github.com/qmk/qmk_firmware/issues/2274)。
|
||||
|
||||
<!-- FIXME: Document bluetooth support more completely. -->
|
||||
## Bluetooth の Rules.mk オプション
|
||||
|
||||
現在サポートされている Bluetooth チップセットは [N-キーロールオーバー (NKRO)](ja/reference_glossary.md#n-key-rollover-nkro) をサポートしていません。そのため、`rules.mk` に `NKRO_ENABLE = no` を含めなければなりません。
|
||||
|
||||
Bluetooth を有効にするには、以下のうちの1つだけを使ってください:
|
||||
* BLUETOOTH_ENABLE = yes (レガシーオプション)
|
||||
* BLUETOOTH = RN42
|
||||
* BLUETOOTH = AdafruitBLE
|
||||
|
||||
## Bluetooth キーコード
|
||||
|
||||
これは複数のキーボードの出力が選択できる場合に使われます。現在のところ、これは USB と Bluetooth の両方をサポートするキーボードで、それらの間の切り替えのみが可能です。
|
||||
|
||||
| 名前 | 説明 |
|
||||
| ---------- | ------------------------------------- |
|
||||
| `OUT_AUTO` | USB と Bluetooth を自動的に切り替える |
|
||||
| `OUT_USB` | USB のみ |
|
||||
| `OUT_BT` | Bluetooth のみ |
|
||||
@ -1,182 +0,0 @@
|
||||
# ブートマジック
|
||||
|
||||
<!---
|
||||
original document: 0.9.0:docs/feature_bootmagic.md
|
||||
git diff 0.9.0 HEAD -- docs/feature_bootmagic.md | cat
|
||||
-->
|
||||
|
||||
再書き込みせずにキーボードの挙動を変更することができる、3つの独立した関連する機能があります。それぞれは似たような機能を持ちますが、キーボードがどのように設定されているかによって異なる方法でアクセスされます。
|
||||
|
||||
**ブートマジック**は初期化の間にキーボードを設定するためのシステムです。ブートマジックコマンドを起動するには、ブートマジックキーと1つ以上のコマンドキーを押し続けます。
|
||||
|
||||
**ブートマジックキーコード** は前に `MAGIC_` が付いており、キーボードが初期化された*後で*ブートマジックの機能にアクセスすることができます。キーコードを使うには、他のキーコードと同じようにそれらをキーマップに割り当てます。
|
||||
|
||||
以前は**マジック**として知られていた**コマンド**は、キーボードの異なる側面を制御することができる別の機能です。ブートマジックと一部の機能を共有しますが、コンソールにバージョン情報を出力するような、ブートマジックにはできないこともできます。詳細は、[コマンド](ja/feature_command.md)を見てください。
|
||||
|
||||
一部のキーボードでは、ブートマジックはデフォルトで無効になっています。その場合、`rules.mk` 内で以下のように明示的に有効にする必要があります:
|
||||
|
||||
```make
|
||||
BOOTMAGIC_ENABLE = yes
|
||||
```
|
||||
|
||||
?> `full` の代わりに `yes` が使われていることがあるかもしれませんが、これは問題ありません。ただし、`yes` は非推奨で、理想的には `full` (あるいは`lite`) が使われるべきです。
|
||||
|
||||
さらに、以下を `rules.mk` ファイルに追加することで、[ブートマジックライト](#bootmagic-lite) (スケールダウンした、とても基本的なバージョンのブートマジック)を使うことができます:
|
||||
|
||||
```make
|
||||
BOOTMAGIC_ENABLE = lite
|
||||
```
|
||||
|
||||
## ホットキー
|
||||
|
||||
キーボードを接続しながら、ブートマジックキー(デフォルトはスペース)と目的のホットキーを押します。例えば、スペースと `B` を押したままにすると、ブートローダに入ります。
|
||||
|
||||
| ホットキー | 説明 |
|
||||
|------------------|---------------------------------------------|
|
||||
| エスケープ | EEPROM のブートマジック設定を無視する |
|
||||
| `B` | ブートローダに入る |
|
||||
| `D` | シリアルを介するデバッグ出力の切り替え |
|
||||
| `X` | キーマトリックスのデバッグ出力の切り替え |
|
||||
| `K` | キーボードのデバッグの切り替え |
|
||||
| `M` | マウスのデバッグの切り替え |
|
||||
| `L` | EE_HANDS 左右設定に、"左手"を設定 |
|
||||
| `R` | EE_HANDS 左右設定に、"右手"を設定 |
|
||||
| Backspace | EEPROM をクリア |
|
||||
| Caps Lock | Caps Lock を左コントロールとして扱うかを切り替え |
|
||||
| 左 Control | Caps Lock と左コントロールの入れ替えを切り替え |
|
||||
| 左 Alt | 左 Alt と左 GUI の入れ替えを切り替え |
|
||||
| 右 Alt | 右 Alt と右 GUI の入れ替えを切り替え |
|
||||
| 左 GUI | GUI キーの有効・無効を切り替え (ゲームの時に便利です) |
|
||||
| <code>`</code> | <code>`</code> とエスケープの入れ替えを切り替え |
|
||||
| `\` | `\` とバックスペースの入れ替えを切り替え |
|
||||
| `N` | N キーロールオーバー (NKRO) の有効・無効を切り替え |
|
||||
| `0` | レイヤー 0 をデフォルトレイヤーにする |
|
||||
| `1` | レイヤー 1 をデフォルトレイヤーにする |
|
||||
| `2` | レイヤー 2 をデフォルトレイヤーにする |
|
||||
| `3` | レイヤー 3 をデフォルトレイヤーにする |
|
||||
| `4` | レイヤー 4 をデフォルトレイヤーにする |
|
||||
| `5` | レイヤー 5 をデフォルトレイヤーにする |
|
||||
| `6` | レイヤー 6 をデフォルトレイヤーにする |
|
||||
| `7` | レイヤー 7 をデフォルトレイヤーにする |
|
||||
|
||||
## キーコード :id=keycodes
|
||||
|
||||
| キー | エイリアス | 説明 |
|
||||
|----------------------------------|---------|--------------------------------------------------------------------------|
|
||||
| `MAGIC_SWAP_CONTROL_CAPSLOCK` | `CL_SWAP` | Caps Lock と左コントロールの入れ替え |
|
||||
| `MAGIC_UNSWAP_CONTROL_CAPSLOCK` | `CL_NORM` | Caps Lock と左コントロールの入れ替えの解除 |
|
||||
| `MAGIC_CAPSLOCK_TO_CONTROL` | `CL_CTRL` | Caps Lock をコントロールとして扱う |
|
||||
| `MAGIC_UNCAPSLOCK_TO_CONTROL` | `CL_CAPS` | Caps Lock をコントロールとして扱うことを止める |
|
||||
| `MAGIC_SWAP_LCTL_LGUI` | `LCG_SWP` | 左コントロールと GUI の入れ替え |
|
||||
| `MAGIC_UNSWAP_LCTL_LGUI` | `LCG_NRM` | 左コントロールと GUI の入れ替えを解除 |
|
||||
| `MAGIC_SWAP_RCTL_RGUI` | `RCG_SWP` | 右コントロールと GUI の入れ替え |
|
||||
| `MAGIC_UNSWAP_RCTL_RGUI` | `RCG_NRM` | 右コントロールと GUI の入れ替えを解除 |
|
||||
| `MAGIC_SWAP_CTL_GUI` | `CG_SWAP` | 両側のコントロールと GUI の入れ替え |
|
||||
| `MAGIC_UNSWAP_CTL_GUI` | `CG_NORM` | 両側のコントロールと GUI の入れ替えを解除 |
|
||||
| `MAGIC_TOGGLE_CTL_GUI` | `CG_TOGG` | 両側のコントロールと GUI の入れ替えの切り替え |
|
||||
| `MAGIC_SWAP_LALT_LGUI` | `LAG_SWP` | 左 Alt と GUI の入れ替え |
|
||||
| `MAGIC_UNSWAP_LALT_LGUI` | `LAG_NRM` | 左 Alt と GUI の入れ替えを解除 |
|
||||
| `MAGIC_SWAP_RALT_RGUI` | `RAG_SWP` | 右 Alt と GUI の入れ替え |
|
||||
| `MAGIC_UNSWAP_RALT_RGUI` | `RAG_NRM` | 右 Alt と GUI の入れ替えを解除 |
|
||||
| `MAGIC_SWAP_ALT_GUI` | `AG_SWAP` | 両側の Alt と GUI の入れ替え |
|
||||
| `MAGIC_UNSWAP_ALT_GUI` | `AG_NORM` | 両側の Alt と GUI の入れ替えを解除 |
|
||||
| `MAGIC_TOGGLE_ALT_GUI` | `AG_TOGG` | 両側の Alt と GUI の入れ替えの切り替え |
|
||||
| `MAGIC_NO_GUI` | `GUI_OFF` | GUI キーを無効にする |
|
||||
| `MAGIC_UNNO_GUI` | `GUI_ON` | GUI キーを有効にする |
|
||||
| `MAGIC_SWAP_GRAVE_ESC` | `GE_SWAP` | <code>`</code> とエスケープの入れ替え |
|
||||
| `MAGIC_UNSWAP_GRAVE_ESC` | `GE_NORM` | <code>`</code> とエスケープの入れ替えを解除 |
|
||||
| `MAGIC_SWAP_BACKSLASH_BACKSPACE` | `BS_SWAP` | `\` とバックスペースを入れ替え |
|
||||
| `MAGIC_UNSWAP_BACKSLASH_BACKSPACE` | `BS_NORM` | `\` とバックスペースの入れ替えを解除する |
|
||||
| `MAGIC_HOST_NKRO` | `NK_ON` | N キーロールオーバーを有効にする |
|
||||
| `MAGIC_UNHOST_NKRO` | `NK_OFF` | N キーロールオーバーを無効にする |
|
||||
| `MAGIC_TOGGLE_NKRO` | `NK_TOGG` | N キーロールオーバーの有効・無効を切り替え |
|
||||
| `MAGIC_EE_HANDS_LEFT` | `EH_LEFT` | 分割キーボードのマスター側を左手に設定(`EE_HANDS` 用) |
|
||||
| `MAGIC_EE_HANDS_RIGHT` | `EH_RGHT` | 分割キーボードのマスター側を右手に設定(`EE_HANDS` 用) |
|
||||
|
||||
## 設定
|
||||
|
||||
ブートマジックのためのホットキーの割り当てを変更したい場合は、キーボードあるいはキーマップレベルのどちらかで、`config.h` にこれらを `#define` します。
|
||||
|
||||
| 定義 | デフォルト | 説明 |
|
||||
|----------------------------------------|-------------|---------------------------------------------------|
|
||||
| `BOOTMAGIC_KEY_SALT` | `KC_SPACE` | ブートマジックキー |
|
||||
| `BOOTMAGIC_KEY_SKIP` | `KC_ESC` | EEPROM のブートマジック設定を無視する |
|
||||
| `BOOTMAGIC_KEY_EEPROM_CLEAR` | `KC_BSPACE` | EEPROM 設定をクリアする |
|
||||
| `BOOTMAGIC_KEY_BOOTLOADER` | `KC_B` | ブートローダに入る |
|
||||
| `BOOTMAGIC_KEY_DEBUG_ENABLE` | `KC_D` | シリアルを介するデバッグ出力の切り替え |
|
||||
| `BOOTMAGIC_KEY_DEBUG_MATRIX` | `KC_X` | マトリックスのデバッグを切り替え |
|
||||
| `BOOTMAGIC_KEY_DEBUG_KEYBOARD` | `KC_K` | キーボードのデバッグの切り替え |
|
||||
| `BOOTMAGIC_KEY_DEBUG_MOUSE` | `KC_M` | マウスのデバッグの切り替え |
|
||||
| `BOOTMAGIC_KEY_EE_HANDS_LEFT` | `KC_L` | EE_HANDS 左右設定に、"左手"を設定 |
|
||||
| `BOOTMAGIC_KEY_EE_HANDS_RIGHT` | `KC_R` | EE_HANDS 左右設定に、"右手"を設定 |
|
||||
| `BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK` | `KC_LCTRL` | 左コントロールと Caps Lock の入れ替え |
|
||||
| `BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL` | `KC_CAPSLOCK` | Caps Lock を左コントロールとして扱うかを切り替え |
|
||||
| `BOOTMAGIC_KEY_SWAP_LALT_LGUI` | `KC_LALT` | 左 Alt と左 GUI の入れ替えを切り替え (macOS 用) |
|
||||
| `BOOTMAGIC_KEY_SWAP_RALT_RGUI` | `KC_RALT` | 右 Alt と右 GUI の入れ替えを切り替え (macOS 用) |
|
||||
| `BOOTMAGIC_KEY_NO_GUI` | `KC_LGUI` | GUI キーの有効・無効を切り替え (ゲームの時に便利です) |
|
||||
| `BOOTMAGIC_KEY_SWAP_GRAVE_ESC` | `KC_GRAVE` | <code>`</code> とエスケープの入れ替えを切り替え |
|
||||
| `BOOTMAGIC_KEY_SWAP_BACKSLASH_BACKSPACE` | `KC_BSLASH` | `\` とバックスペースの入れ替えを切り替え |
|
||||
| `BOOTMAGIC_HOST_NKRO` | `KC_N` | N キーロールオーバー (NKRO) の有効・無効を切り替え |
|
||||
| `BOOTMAGIC_KEY_DEFAULT_LAYER_0` | `KC_0` | レイヤー 0 をデフォルトレイヤーにする |
|
||||
| `BOOTMAGIC_KEY_DEFAULT_LAYER_1` | `KC_1` | レイヤー 1 をデフォルトレイヤーにする |
|
||||
| `BOOTMAGIC_KEY_DEFAULT_LAYER_2` | `KC_2` | レイヤー 2 をデフォルトレイヤーにする |
|
||||
| `BOOTMAGIC_KEY_DEFAULT_LAYER_3` | `KC_3` | レイヤー 3 をデフォルトレイヤーにする |
|
||||
| `BOOTMAGIC_KEY_DEFAULT_LAYER_4` | `KC_4` | レイヤー 4 をデフォルトレイヤーにする |
|
||||
| `BOOTMAGIC_KEY_DEFAULT_LAYER_5` | `KC_5` | レイヤー 5 をデフォルトレイヤーにする |
|
||||
| `BOOTMAGIC_KEY_DEFAULT_LAYER_6` | `KC_6` | レイヤー 6 をデフォルトレイヤーにする |
|
||||
| `BOOTMAGIC_KEY_DEFAULT_LAYER_7` | `KC_7` | レイヤー 7 をデフォルトレイヤーにする |
|
||||
|
||||
# ブートマジックライト :id=bootmagic-lite
|
||||
|
||||
本格的なブートマジック機能の他に、ブートローダへのジャンプのみを処理するブートマジックライトがあります。これは、物理的なリセットボタンが無くブートローダにジャンプする方法が必要だが、ブートマジックが引き起こす問題を扱いたくないキーボードに適しています。
|
||||
|
||||
ブートマジックのこのバージョンを有効にするには、以下を使って `rules.mk` で有効にする必要があります:
|
||||
|
||||
```make
|
||||
BOOTMAGIC_ENABLE = lite
|
||||
```
|
||||
|
||||
さらに、どのキーを使うかを指定したほうが良いかもしれません。これは普通ではないマトリックスを持つキーボードで特に便利です。そのためには、使いたいキーの行と列を指定する必要があります。`config.h` ファイルにこれらのエントリを追加します:
|
||||
|
||||
```c
|
||||
#define BOOTMAGIC_LITE_ROW 0
|
||||
#define BOOTMAGIC_LITE_COLUMN 1
|
||||
```
|
||||
|
||||
デフォルトでは、これらは 0 と 0 に設定されます。これは通常はほとんどのキーボードで "ESC" キーです。
|
||||
|
||||
ブートローダを起動するには、キーボードを接続する時にこのキーを押し続けます。たった1つのキーです。
|
||||
|
||||
!> ブートマジックライトを使用すると、EEPROM を**常にリセットします**。つまり保存された全ての設定は失われます。
|
||||
|
||||
## 分割キーボード
|
||||
|
||||
`SPLIT_HAND_PIN` のようなオプションで、左右の設定があらかじめ決められている場合は、キーボードの左右で別のキーを設定する必要があるかもしれません。これを行うには、`config.h` ファイルに以下のエントリを追加します。
|
||||
|
||||
```c
|
||||
#define BOOTMAGIC_LITE_ROW_RIGHT 4
|
||||
#define BOOTMAGIC_LITE_COLUMN_RIGHT 1
|
||||
```
|
||||
|
||||
デフォルトでは、これらの値は設定されていません。
|
||||
|
||||
## 高度なブートマジックライト
|
||||
|
||||
`bootmagic_lite` 関数は必要に応じてコード内で置き換えることができるように、弱く定義されています。これの良い例は Zeal60 キーボードで、追加の処理が必要です。
|
||||
|
||||
関数を置き換えるには、以下のようなものをコードに追加するだけです:
|
||||
|
||||
```c
|
||||
void bootmagic_lite(void) {
|
||||
matrix_scan();
|
||||
wait_ms(DEBOUNCE * 2);
|
||||
matrix_scan();
|
||||
|
||||
if (matrix_get_row(BOOTMAGIC_LITE_ROW) & (1 << BOOTMAGIC_LITE_COLUMN)) {
|
||||
// ブートローダにジャンプする。
|
||||
bootloader_jump();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
追加の機能をここに追加することができます。例えば、eeprom のリセットやブートマジックを起動するために押す必要がある追加のキーです。`bootmagic_lite` はファームウェア内で大部分の機能が初期化される前に呼ばれることに注意してください。
|
||||
@ -1,108 +0,0 @@
|
||||
# コンボ
|
||||
|
||||
<!---
|
||||
original document: 0.10.36:docs/feature_combo.md
|
||||
git diff 0.10.36 HEAD -- docs/feature_combo.md | cat
|
||||
-->
|
||||
|
||||
コンボ機能は、同時押し方式でのカスタムアクション追加機能です。同時に複数のキーを押して、異なる効果を生み出すことができます。例えば、タッピング時間内で `A` と `S` を押すと、代わりに `ESC` が押されます。もっと複雑なタスクを実行させることもできます。
|
||||
|
||||
この機能を有効にするには、`rules.mk` に `COMBO_ENABLE = yes` を追加する必要があります。
|
||||
|
||||
さらに、使用するコンボの数を `config.h` の中で、`#define COMBO_COUNT 1` (1を使用するコンボの数で置き換えます)と書いて、指定する必要があります。
|
||||
<!-- At this time, this is necessary -->
|
||||
|
||||
また、デフォルトでは、コンボのタッピング時間は `TAPPING_TERM` と同じ値に設定されます (ほとんどのキーボードではデフォルトで 200)。ただし、`config.h` で定義することにより異なる値を指定することができます。例えば: `#define COMBO_TERM 300` はコンボのためのタイムアウト時間を 300ms に設定します。
|
||||
|
||||
次に、`keymap.c` ファイルに、`COMBO_END` で終了するキーのシーケンス、およびキーの組み合わせを列挙する構造体、その結果のアクションを定義する必要があります。
|
||||
|
||||
```c
|
||||
const uint16_t PROGMEM test_combo[] = {KC_A, KC_B, COMBO_END};
|
||||
combo_t key_combos[] = {COMBO(test_combo, KC_ESC)};
|
||||
```
|
||||
|
||||
これは、A と B のキーを押した場合に、"Escape" を送信します。
|
||||
|
||||
!> このメソッドは[基本的なキーコード](ja/keycodes_basic.md)のみをサポートします。詳細な制御については例を見てください。
|
||||
|
||||
## 例
|
||||
|
||||
リストを追加したい場合は、以下のようなものを使います:
|
||||
|
||||
```c
|
||||
enum combos {
|
||||
AB_ESC,
|
||||
JK_TAB
|
||||
};
|
||||
|
||||
const uint16_t PROGMEM ab_combo[] = {KC_A, KC_B, COMBO_END};
|
||||
const uint16_t PROGMEM jk_combo[] = {KC_J, KC_K, COMBO_END};
|
||||
|
||||
combo_t key_combos[] = {
|
||||
[AB_ESC] = COMBO(ab_combo, KC_ESC),
|
||||
[JK_TAB] = COMBO(jk_combo, KC_TAB)
|
||||
};
|
||||
```
|
||||
|
||||
より複雑な実装として、カスタム処理を追加するために `process_combo_event` 関数を使うことができます。
|
||||
|
||||
```c
|
||||
enum combo_events {
|
||||
ZC_COPY,
|
||||
XV_PASTE
|
||||
};
|
||||
|
||||
const uint16_t PROGMEM copy_combo[] = {KC_Z, KC_C, COMBO_END};
|
||||
const uint16_t PROGMEM paste_combo[] = {KC_X, KC_V, COMBO_END};
|
||||
|
||||
combo_t key_combos[] = {
|
||||
[ZC_COPY] = COMBO_ACTION(copy_combo),
|
||||
[XV_PASTE] = COMBO_ACTION(paste_combo),
|
||||
};
|
||||
|
||||
void process_combo_event(uint16_t combo_index, bool pressed) {
|
||||
switch(combo_index) {
|
||||
case ZC_COPY:
|
||||
if (pressed) {
|
||||
tap_code16(LCTL(KC_C));
|
||||
}
|
||||
break;
|
||||
case XV_PASTE:
|
||||
if (pressed) {
|
||||
tap_code16(LCTL(KC_V));
|
||||
}
|
||||
break;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
これは、Z と C を押すと Ctrl+C を送信し、X と V を押すと Ctrl+V を送信します。これを変更して、レイヤーの変更、サウンドの再生、設定の変更などを行うこともできます。
|
||||
|
||||
## 追加の設定
|
||||
|
||||
長いコンボあるいはさらに長いコンボを使っている場合、構造体があなたのしていることに対応するのに十分な大きさで無いかもしれないため、問題が発生するかもしれません。
|
||||
|
||||
この場合、`config.h` ファイルに `#define EXTRA_LONG_COMBOS` または `#define EXTRA_EXTRA_LONG_COMBOS` のどちらかを追加することができます。
|
||||
|
||||
`COMBO_ALLOW_ACTION_KEYS` を定義することでアクションキーを有効にすることもできます。
|
||||
|
||||
## キーコード
|
||||
|
||||
その場でコンボ機能を有効、無効および切り替えすることができます。ゲームなどで、一時的にそれらを無効にする必要がある場合に便利です。
|
||||
|
||||
| キーコード | 説明 |
|
||||
|----------|---------------------------------|
|
||||
| `CMB_ON` | コンボ機能をオンにします |
|
||||
| `CMB_OFF` | コンボ機能をオフにします |
|
||||
| `CMB_TOG` | コンボ機能のオンとオフを切り替えます |
|
||||
|
||||
## ユーザコールバック
|
||||
|
||||
キーコードに加えて、状態を設定または状態をチェックするために使うことができる幾つかの関数があります:
|
||||
|
||||
| 関数 | 説明 |
|
||||
|-----------|--------------------------------------------------------------------|
|
||||
| `combo_enable()` | コンボ機能を有効にします |
|
||||
| `combo_disable()` | コンボ機能を無効にし、コンボバッファをクリアします |
|
||||
| `combo_toggle()` | コンボ機能の状態を切り替えます |
|
||||
| `is_combo_enabled()` | コンボ機能の状態(true か false)を返します |
|
||||
@ -1,56 +0,0 @@
|
||||
# コマンド
|
||||
|
||||
<!---
|
||||
original document: 0.8.94:docs/feature_command.md
|
||||
git diff 0.8.94 HEAD -- docs/feature_command.md | cat
|
||||
-->
|
||||
|
||||
コマンド(旧称:マジック)は、ファームウェアを書き込んだり、[ブートマジック](ja/feature_bootmagic.md)を使うためにプラグを抜いたりすることなくキーボードの挙動を変更する方法です。この機能と[ブートマジックキーコード](feature_bootmagic.md#keycodes)には多くの重複があります。可能な限り、コマンドでは無くブートマジックキーコードの機能を使うことをお勧めします。
|
||||
|
||||
一部のキーボードではコマンドがデフォルトで無効になっています。その場合、`rules.mk` 内で明示的に有効にする必要があります:
|
||||
|
||||
```make
|
||||
COMMAND_ENABLE = yes
|
||||
```
|
||||
|
||||
## 使用法
|
||||
|
||||
コマンドを使うには、`IS_COMMAND()` マクロで定義されたキーの組み合わせを押し続けます。デフォルトでは、これは「左Shift + 右Shift」です。次に、目的のコマンドに対応するキーを押します。例えば、現在の QMK バージョンを QMK Toolbox コンソールに出力するには、「左Shift + 右Shift + `V`」を押します。
|
||||
|
||||
## 設定
|
||||
|
||||
コマンドのためのキーの割り当てを変更したい場合は、キーボードあるいはキーマップレベルのどちらかで、`config.h` にこれらを `#define` します。ここで割り当てる全てのキーコードは `KC_` 接頭辞を省略する必要があります。
|
||||
|
||||
| 定義 | デフォルト | 説明 |
|
||||
|------------------------------------|--------------------------------|------------------------------------------------|
|
||||
| `IS_COMMAND()` | `(get_mods() == MOD_MASK_SHIFT)` | コマンドをアクティブにするキーの組み合わせ |
|
||||
| `MAGIC_KEY_SWITCH_LAYER_WITH_FKEYS` | `true` | ファンクション行を使ってデフォルトレイヤーを設定 |
|
||||
| `MAGIC_KEY_SWITCH_LAYER_WITH_NKEYS` | `true` | 数字キーでデフォルトレイヤーを設定 |
|
||||
| `MAGIC_KEY_SWITCH_LAYER_WITH_CUSTOM` | `false` | `MAGIC_KEY_LAYER0..9` を使ってデフォルトレイヤーを設定 |
|
||||
| `MAGIC_KEY_DEBUG` | `D` | シリアルを介するデバッグの切り替え |
|
||||
| `MAGIC_KEY_DEBUG_MATRIX` | `X` | キーマトリックスのデバッグの切り替え |
|
||||
| `MAGIC_KEY_DEBUG_KBD` | `K` | キーボードのデバッグの切り替え |
|
||||
| `MAGIC_KEY_DEBUG_MOUSE` | `M` | マウスのデバッグの切り替え |
|
||||
| `MAGIC_KEY_CONSOLE` | `C` | コマンドコンソールを有効にする |
|
||||
| `MAGIC_KEY_VERSION` | `V` | コンソールに実行中の QMK バージョンを出力 |
|
||||
| `MAGIC_KEY_STATUS` | `S` | コンソールに現在のキーボードの状態を出力 |
|
||||
| `MAGIC_KEY_HELP` | `H` | コンソールにコマンドのヘルプを出力 |
|
||||
| `MAGIC_KEY_HELP_ALT` | `SLASH` | コンソールにコマンドのヘルプを出力 (代替) |
|
||||
| `MAGIC_KEY_LAYER0` | `0` | レイヤー 0 をデフォルトレイヤーにする |
|
||||
| `MAGIC_KEY_LAYER0_ALT` | `GRAVE` | レイヤー 0 をデフォルトレイヤーにする (代替) |
|
||||
| `MAGIC_KEY_LAYER1` | `1` | レイヤー 1 をデフォルトレイヤーにする |
|
||||
| `MAGIC_KEY_LAYER2` | `2` | レイヤー 2 をデフォルトレイヤーにする |
|
||||
| `MAGIC_KEY_LAYER3` | `3` | レイヤー 3 をデフォルトレイヤーにする |
|
||||
| `MAGIC_KEY_LAYER4` | `4` | レイヤー 4 をデフォルトレイヤーにする |
|
||||
| `MAGIC_KEY_LAYER5` | `5` | レイヤー 5 をデフォルトレイヤーにする |
|
||||
| `MAGIC_KEY_LAYER6` | `6` | レイヤー 6 をデフォルトレイヤーにする |
|
||||
| `MAGIC_KEY_LAYER7` | `7` | レイヤー 7 をデフォルトレイヤーにする |
|
||||
| `MAGIC_KEY_LAYER8` | `8` | レイヤー 8 をデフォルトレイヤーにする |
|
||||
| `MAGIC_KEY_LAYER9` | `9` | レイヤー 9 をデフォルトレイヤーにする |
|
||||
| `MAGIC_KEY_BOOTLOADER` | `B` | ブートローダにジャンプする |
|
||||
| `MAGIC_KEY_BOOTLOADER_ALT` | `ESC` | ブートローダにジャンプする (代替) |
|
||||
| `MAGIC_KEY_LOCK` | `CAPS` | 何も入力できないようにキーボードをロック |
|
||||
| `MAGIC_KEY_EEPROM` | `E` | 保存された EEPROM 設定をコンソールに出力 |
|
||||
| `MAGIC_KEY_EEPROM_CLEAR` | `BSPACE` | EEPROM をクリア |
|
||||
| `MAGIC_KEY_NKRO` | `N` | N キーロールオーバー (NKRO) の有効・無効を切り替え |
|
||||
| `MAGIC_KEY_SLEEP_LED` | `Z` | コンピュータがスリープの時に LED を切り替え |
|
||||
@ -1,128 +0,0 @@
|
||||
# 接点バウンス / 接点チャタリング
|
||||
|
||||
<!---
|
||||
original document: 0.11.53:docs/feature_debounce_type.md
|
||||
git diff 0.11.53 HEAD -- docs/feature_debounce_type.md | cat
|
||||
-->
|
||||
|
||||
メカニカルスイッチは押した状態と放した状態の間の移行が単純ではないことが良くあります。
|
||||
|
||||
理想的な世界では、スイッチを押すと、デジタルピンが次のようになることが期待されます:
|
||||
(X 軸は時間を表します
|
||||
```
|
||||
voltage +----------------------
|
||||
^ |
|
||||
| |
|
||||
| ------------------+
|
||||
----> time
|
||||
```
|
||||
|
||||
しかし実際の世界では、値が最終的に落ち着くまでに 0 と 1 の間を行ったり来たりする接点バウンスを見ることになるでしょう。（訳注：日本語では、バウンスとチャタリングを区別せずにチャタリングと呼んでいることが多いようです。）
|
||||
```
|
||||
+-+ +--+ +-------------
|
||||
| | | | |
|
||||
| | | | |
|
||||
+-----------------+ +-+ +-+
|
||||
```
|
||||
スイッチが落ち着くまでにかかる時間は、スイッチの種類や経年、押す技術によって異なる場合があります。
|
||||
|
||||
デバイスが接点バウンスを緩和しないことを選択した場合、スイッチが押された時に起きるアクションが複数回繰り返されることがよくあります。
|
||||
|
||||
接点バウンス(「デバウンス」)を処理する方法はたくさんあります。RC フィルタのような追加のハードウェアを採用する方法もありますが、ソフトウェアでデバウンスを行う様々な方法もあり、よくデバウンスアルゴリズムと呼ばれます。このページでは、QMK で利用できるデバウンスメソッドについて説明します。
|
||||
|
||||
技術的には接点バウンス/接点チャタリングとは見なされませんが、一部のスイッチテクノロジーはノイズの影響を受けやすく、キーの状態が変化していない時に、時々短くランダムに 0 と 1 の間を行き来する様子がデジタル回路によって読み取られる場合があります。例えば:
|
||||
```
|
||||
+-+
|
||||
| |
|
||||
| |
|
||||
+-----------------+ +--------------------
|
||||
```
|
||||
|
||||
多くのデバウンスメソッド(全てではないですが)は、デバイスにノイズ耐性を持たせます。
|
||||
ノイズの影響を受けやすい技術を使っている場合は、ノイズを緩和するデバウンスメソッドを選択しなければなりません。
|
||||
|
||||
## デバウンスアルゴリズムの種類
|
||||
|
||||
1) 時間の単位: タイムスタンプ (ミリ秒) vs 周期 (スキャン)
|
||||
* デバウンスアルゴリズムは1つの「デバウンス時間」パラメータを持つことがよくあり、スイッチ接点の最大セトリング時間を指定します。
|
||||
この時間は様々な単位で測定される場合があります:
|
||||
* 周期ベースデバウンスは n 周期(スキャン)待機し、matrix_scan ごとにカウントを1減らします。
|
||||
* タイムスタンプベースのデバウンスは、変更が発生したミリ秒のタイムスタンプを格納し、経過時間を計算するために減算を行います。
|
||||
* 通常、タイムスタンプベースのデバウンスは、特にノイズ耐性のあるデバイスで優れています。なぜなら、物理スイッチのセトリング時間は時間の単位で指定されており、キーボードのマトリックススキャンレートに依存しないからです。
|
||||
* 周期ベースのデバウンスは、補正できるセトリング時間がマトリックススキャンコードのパフォーマンスに依存するため、劣ると見なされる場合があります。
|
||||
周期ベースのデバウンスを使う場合、スキャンコードのパフォーマンスを大幅に向上させると、デバウンスの効果が低下する場合があります。
|
||||
周期ベースのデバウンスが望ましい状況は、ノイズが存在し、スキャンアルゴリズムが遅い、もしくは速度が可変である場合です。
|
||||
デバウンスアルゴリズムが基本的にノイズ耐性がある場合でも、スキャンが遅く、タイムスタンプベースのアルゴリズムを使っている場合は、
|
||||
2つのサンプル値に基づいてデバウンスを決定するため、アルゴリズムのノイズ耐性は制限されます。
|
||||
* 現在、全ての組み込みデバウンスアルゴリズムは、タイムスタンプベースのデバウンスのみサポートしています。将来的には周期ベースのデバウンスを実装し、```config.h``` マクロを介して選択できるようになるでしょう。
|
||||
|
||||
2) 対称 vs 非対称
|
||||
* 対称 - キーアップとキーダウンイベントの両方に、同じデバウンスアルゴリズムを適用します。
|
||||
* 推奨される命名規則: ```sym_*```
|
||||
* 非対称 - キーダウンとキーアップイベントに異なるデバウンスアルゴリズムを適用します。例えば、キーダウンはイーガー、キーアップはデファー。
|
||||
* 推奨される命名規則: ```asym_*``` の後に、キーダウン、キーアップの順に使っているアルゴリズムタイプの詳細が続きます。
|
||||
|
||||
3) イーガー vs デファー
|
||||
* イーガー - キーの変更はすぐに報告されます。DEBOUNCE ミリ秒以降の全ての入力は無視されます。
|
||||
* イーガーアルゴリズムはノイズ耐性はありません
|
||||
* 推奨される命名規則:
|
||||
* ```sym_eager_*```
|
||||
* ```asym_eager_*_*```: キーダウンはイーガーアルゴリズムを使います
|
||||
* ```asym_*_eager_*```: キーアップはイーガーアルゴリズムを使います
|
||||
* デファー - 変更を報告する前に DEBOUNCE ミリ秒の間変更がないことを待機します
|
||||
* デファーアルゴリズムはノイズ耐性があります
|
||||
* 推奨される命名規則:
|
||||
* ```sym_defer_*```
|
||||
* ```asym_defer_*_*```: キーダウンはデファーアルゴリズムを使います
|
||||
* ```asym_*_defer_*```: キーアップはデファーアルゴリズムを使います
|
||||
|
||||
4) グローバル vs キーごと vs 行ごと
|
||||
* グローバル - 全てのキーに対して1つのタイマー。キーの変更状態は、グローバルタイマーに影響を与えます。
|
||||
* 推奨される命名規則: ```*_g```
|
||||
* キーごと - キーごとに1つのタイマー。
|
||||
* 推奨される命名規則: ```*_pk```
|
||||
* 行ごと - 行ごとに1つのタイマー。
|
||||
* 推奨される命名規則: ```*_pr```
|
||||
* キーごとや行ごとのアルゴリズムはより多くのリソース(パフォーマンスと RAM 使用量の観点で)を消費しますが、高速なタイピストはグローバルよりもそれらを好む場合があります。
|
||||
|
||||
## QMK でサポートされるデバウンスアルゴリズム
|
||||
|
||||
QMK はデバウンス API を介して複数のデバウンスアルゴリズムをサポートします。
|
||||
|
||||
### デバウンスの選択
|
||||
|
||||
| DEBOUNCE_TYPE | 説明 | 他に必要なもの |
|
||||
| ------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| 未定義 | デフォルトのアルゴリズム、現在のところ sym_defer_g を使います | 無し |
|
||||
| custom | 独自のデバウンスコードを使います | ```SRC += debounce.c``` で独自の debounce.c を追加し、必要な関数を実装します |
|
||||
| その他 | quantum/debounce/* から他のアルゴリズムを使います | 無し |
|
||||
|
||||
**分割キーボードについて**:
|
||||
デバウンスコードは分割キーボードと互換性があります。
|
||||
|
||||
### インクルードされているデバウンスメソッドの選択
|
||||
キーボードは、```rules.mk``` に次の行を追加することで、既に実装されているデバウンスメソッドの1つを選択できます:
|
||||
```
|
||||
DEBOUNCE_TYPE = <アルゴリズムの名前>
|
||||
```
|
||||
アルゴリズムの名前は次のいずれかです:
|
||||
* ```sym_defer_g``` - キーボードごとにデバウンスします。状態が変化すると、グローバルタイマが設定されます。```DEBOUNCE``` ミリ秒の間何も変化がなければ、全ての入力の変更がプッシュされます。
|
||||
* これは現在のデフォルトアルゴリズムです。これはメモリ使用量が最も少ない最高のパフォーマンスのアルゴリズムで、ノイズ耐性もあります。
|
||||
* ```sym_eager_pr``` - 行ごとにデバウンスします。状態が変化すると、応答は即座に行われ、その後その行は ```DEBOUNCE``` ミリ秒の間入力されません。
|
||||
```NUM_KEYS``` の 8ビットカウンタの更新に高い計算コストがかかる、もしくは低スキャンレートのキーボード用で、各指は通常一度に1行しか叩かないようになっています。これは ErgoDox モデルに適しています; マトリックスは90度回転しているため、その「行」は実際には「列」であり、通常の使用では各指は一度に1つの「行」にしか当たりません。
|
||||
* ```sym_eager_pk``` - キーごとにデバウンスします。状態が変化すると、応答は即座に行われ、その後そのキーは ```DEBOUNCE``` ミリ秒の間入力されません。
|
||||
* ```sym_defer_pk``` - キーごとにデバウンスします。状態が変化すると、キーごとのタイマーが設定されます。```DEBOUNCE``` ミリ秒の間そのキーに変化がなければ、キーの状態の変更がプッシュされます。
|
||||
|
||||
### 将来実装される可能性のあるいくつかのアルゴリズム:
|
||||
* ```sym_defer_pr```
|
||||
* ```sym_eager_g```
|
||||
* ```asym_eager_defer_pk```
|
||||
|
||||
### 独自のデバウンスコードの使用
|
||||
独自のデバウンスアルゴリズムを実装するためのオプションがあります。次のようにします:
|
||||
* ```rules.mk``` に ```DEBOUNCE_TYPE = custom``` を設定します。
|
||||
* ```rules.mk``` に ```SRC += debounce.c``` を追加します。
|
||||
* 独自の ```debounce.c``` を追加します。例については、```quantum/debounce``` にある現在の実装を見てください。
|
||||
* デバウンスは、全てのマトリクススキャンの後で発生します。
|
||||
* MATRIX_ROWS ではなく num_rows を使って、分割キーボードが正しくサポートされるようにします。
|
||||
* アルゴリズムが他のキーボードにも適用できる可能性がある場合、```quantum/debounce``` に追加することを検討してください。
|
||||
@ -1,115 +0,0 @@
|
||||
# DIP スイッチ
|
||||
|
||||
<!---
|
||||
original document: 0.9.43:docs/feature_dip_switch.md
|
||||
git diff 0.9.43 HEAD -- docs/feature_dip_switch.md | cat
|
||||
-->
|
||||
|
||||
DIP スイッチは、以下を `rules.mk` に追加することでサポートされます:
|
||||
|
||||
DIP_SWITCH_ENABLE = yes
|
||||
|
||||
さらに、以下を `config.h` に追加します:
|
||||
|
||||
```c
|
||||
// Connects each switch in the dip switch to the GPIO pin of the MCU
|
||||
#define DIP_SWITCH_PINS { B14, A15, A10, B9 }
|
||||
// For split keyboards, you can separately define the right side pins
|
||||
#define DIP_SWITCH_PINS_RIGHT { ... }
|
||||
```
|
||||
|
||||
あるいは
|
||||
|
||||
```c
|
||||
// Connect each switch in the DIP switch to an unused intersections in the key matrix.
|
||||
#define DIP_SWITCH_MATRIX_GRID { {0,6}, {1,6}, {2,6} } // List of row and col pairs
|
||||
```
|
||||
|
||||
## コールバック
|
||||
|
||||
コールバック関数を `<keyboard>.c` に記述することができます:
|
||||
|
||||
```c
|
||||
bool dip_switch_update_kb(uint8_t index, bool active) {
|
||||
if !(dip_switch_update_user(index, active)) { return false; }
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
あるいは `keymap.c` に記述することもできます:
|
||||
|
||||
```c
|
||||
bool dip_switch_update_user(uint8_t index, bool active) {
|
||||
switch (index) {
|
||||
case 0:
|
||||
if(active) { audio_on(); } else { audio_off(); }
|
||||
break;
|
||||
case 1:
|
||||
if(active) { clicky_on(); } else { clicky_off(); }
|
||||
break;
|
||||
case 2:
|
||||
if(active) { music_on(); } else { music_off(); }
|
||||
break;
|
||||
case 3:
|
||||
if (active) {
|
||||
#ifdef AUDIO_ENABLE
|
||||
PLAY_SONG(plover_song);
|
||||
#endif
|
||||
layer_on(_PLOVER);
|
||||
} else {
|
||||
#ifdef AUDIO_ENABLE
|
||||
PLAY_SONG(plover_gb_song);
|
||||
#endif
|
||||
layer_off(_PLOVER);
|
||||
}
|
||||
break;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
更に、より複雑な処理ができるビットマスク関数をサポートします。
|
||||
|
||||
|
||||
```c
|
||||
bool dip_switch_update_mask_kb(uint32_t state) {
|
||||
if (!dip_switch_update_mask_user(state)) { return false; }
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
あるいは `keymap.c` に記述することもできます:
|
||||
|
||||
```c
|
||||
bool dip_switch_update_mask_user(uint32_t state) {
|
||||
if (state & (1UL<<0) && state & (1UL<<1)) {
|
||||
layer_on(_ADJUST); // C on esc
|
||||
} else {
|
||||
layer_off(_ADJUST);
|
||||
}
|
||||
if (state & (1UL<<0)) {
|
||||
layer_on(_TEST_A); // A on ESC
|
||||
} else {
|
||||
layer_off(_TEST_A);
|
||||
}
|
||||
if (state & (1UL<<1)) {
|
||||
layer_on(_TEST_B); // B on esc
|
||||
} else {
|
||||
layer_off(_TEST_B);
|
||||
}
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## ハードウェア
|
||||
|
||||
### DIP スイッチの各スイッチを MCU の GPIO ピンに接続する
|
||||
|
||||
DIP スイッチの片側は MCU のピンへ直接配線し、もう一方の側はグラウンドに配線する必要があります。機能的に同じであるため、どちら側がどちらに接続されているかは問題にはならないはずです。
|
||||
|
||||
### DIP スイッチの各スイッチをキーマトリクスの未使用の交点に接続する
|
||||
|
||||
キースイッチと同じように、ダイオードと DIP スイッチが ROW 線と COL 線に接続します。
|
||||
@ -1,72 +0,0 @@
|
||||
# 動的マクロ: ランタイムでのマクロの記録および再生
|
||||
|
||||
<!---
|
||||
original document: 0.10.33:docs/feature_dynamic_macros.md
|
||||
git diff 0.10.33 HEAD -- docs/feature_dynamic_macros.md | cat
|
||||
-->
|
||||
|
||||
QMK はその場で作られた一時的なマクロをサポートします。これらを動的マクロと呼びます。それらはユーザがキーボードから定義し、キーボードのプラグを抜くか再起動すると失われます。
|
||||
|
||||
1つまたは2つのマクロに合計128のキー押下を保存できます。RAM をより多く使用してサイズを増やすことができます。
|
||||
|
||||
有効にするには、最初に `rules.mk` に `DYNAMIC_MACRO_ENABLE = yes` を記述します。そして、以下のキーをキーマップに追加します:
|
||||
|
||||
| キー | Alias | 説明 |
|
||||
|------------------|----------|---------------------------------------------------|
|
||||
| `DYN_REC_START1` | `DM_REC1` | マクロ 1 の記録を開始します |
|
||||
| `DYN_REC_START2` | `DM_REC2` | マクロ 2 の記録を開始します |
|
||||
| `DYN_MACRO_PLAY1` | `DM_PLY1` | マクロ 1 を再生します |
|
||||
| `DYN_MACRO_PLAY2` | `DM_PLY2` | マクロ 2 を再生します |
|
||||
| `DYN_REC_STOP` | `DM_RSTP` | 現在記録中のマクロの記録を終了します。 |
|
||||
|
||||
これが必要な全てです。
|
||||
|
||||
マクロの記録を開始するには、`DYN_REC_START1` または `DYN_REC_START2` のどちらかを押します。
|
||||
|
||||
記録を終了するには、`DYN_REC_STOP` レイヤーボタンを押します。`DYN_REC_START1` または `DYN_REC_START2` をもう一度押すことでも記録を終了することができます。
|
||||
|
||||
マクロを再生するには、`DYN_MACRO_PLAY1` あるいは `DYN_MACRO_PLAY2` のどちらかを押します。
|
||||
|
||||
マクロの一部としてマクロを再生することができます。マクロ 1 を記録中にマクロ 2 を再生、またはその逆も問題ありません。ただし、再帰的なマクロ、つまりマクロ 1 を再生するマクロ 1 は作成しないでください。もしそうしてキーボードが反応しなくなった場合は、キーボードを取り外し再び接続します。これを完全に無効にするには、`config.h` ファイルで `DYNAMIC_MACRO_NO_NESTING` を定義します。
|
||||
|
||||
?> 動的マクロの内部の詳細については、`process_dynamic_macro.h` および `process_dynamic_macro.c` ファイルのコメントを読んでください。
|
||||
|
||||
## カスタマイズ
|
||||
|
||||
ある程度のカスタマイズを可能にするオプションがいくつか追加されています。
|
||||
|
||||
| 定義 | デフォルト | 説明 |
|
||||
|----------------------------|----------------|-----------------------------------------------------------------------------------------------------------------|
|
||||
| `DYNAMIC_MACRO_SIZE` | 128 | 動的マクロが使用できるメモリ量を設定します。これは限られたリソースであり、コントローラに依存します。 |
|
||||
| `DYNAMIC_MACRO_USER_CALL` | *定義なし* | これを定義すると、ユーザの `keymap.c` ファイルを使ってマクロが起動されます。 |
|
||||
| `DYNAMIC_MACRO_NO_NESTING` | *定義なし* | これを定義すると、別のマクロからマクロを呼び出す(入れ子になったマクロ)機能を無効にします。 |
|
||||
| `DYNAMIC_MACRO_DELAY` | *定義なし* | 各キーを送信する時の待ち時間（ms単位）を設定します。 |
|
||||
|
||||
|
||||
記録中にキーを押すたびに LED が点滅し始めた場合は、マクロバッファにマクロを入れるスペースがもう無いことを意味します。マクロを入れるには、他のマクロ(それらは同じバッファを共有します)を短くするか、`config.h` に `DYNAMIC_MACRO_SIZE` 定義を追加することでバッファを増やします(デフォルト値: 128; ヘッダ内のコメントを読んでください)。
|
||||
|
||||
|
||||
### DYNAMIC_MACRO_USER_CALL
|
||||
|
||||
以前のバージョンの動的マクロをお使いの方へ: 専用の `DYN_REC_STOP` キーを使わずに動的マクロキーへのアクセスに使われるレイヤーモディファイアのみを使って、マクロの記録を終了することもまだ可能です。この動作に戻したい場合は、`#define DYNAMIC_MACRO_USER_CALL` を `config.h` に追加し、以下のスニペットを `process_record_user()` 関数の先頭に記述します:
|
||||
|
||||
```c
|
||||
uint16_t macro_kc = (keycode == MO(_DYN) ? DYN_REC_STOP : keycode);
|
||||
|
||||
if (!process_record_dynamic_macro(macro_kc, record)) {
|
||||
return false;
|
||||
}
|
||||
```
|
||||
|
||||
### ユーザフック
|
||||
|
||||
カスタム機能とフィードバックオプションを動的マクロ機能に追加するために使うことができるフックが幾つかあります。これによりある程度のカスタマイズが可能になります。
|
||||
|
||||
direction がどのマクロであるかを示すことに注意してください。`1` がマクロ 1、`-1` がマクロ 2、0 がマクロ無しです。
|
||||
|
||||
* `dynamic_macro_record_start_user(int8_t direction)` - マクロの記録を開始する時に起動されます。
|
||||
* `dynamic_macro_play_user(int8_t direction)` - マクロを再生する時に起動されます。
|
||||
* `dynamic_macro_record_key_user(int8_t direction, keyrecord_t *record)` - マクロの記録中に各キー押下で起動されます。
|
||||
* `dynamic_macro_record_end_user(int8_t direction)` - マクロの記録を停止した時に起動されます。
|
||||
|
||||
さらに、動的マクロ機能が有効な場合にバックライトを点滅させるために `dynamic_macro_led_blink()` を呼び出すことができます。
|
||||
@ -1,85 +0,0 @@
|
||||
# エンコーダ
|
||||
|
||||
<!---
|
||||
original document: 0.9.43:docs/feature_encoders.md
|
||||
git diff 0.9.43 HEAD -- docs/feature_encoders.md | cat
|
||||
-->
|
||||
|
||||
以下を `rules.mk` に追加することで基本的なエンコーダがサポートされます:
|
||||
|
||||
```make
|
||||
ENCODER_ENABLE = yes
|
||||
```
|
||||
|
||||
さらに、以下を `config.h` に追加します:
|
||||
|
||||
```c
|
||||
#define ENCODERS_PAD_A { B12 }
|
||||
#define ENCODERS_PAD_B { B13 }
|
||||
```
|
||||
|
||||
各 PAD_A/B 変数は配列を定義するため、複数のエンコーダを定義することができます。例えば:
|
||||
|
||||
```c
|
||||
#define ENCODERS_PAD_A { encoder1a, encoder2a }
|
||||
#define ENCODERS_PAD_B { encoder1b, encoder2b }
|
||||
```
|
||||
|
||||
エンコーダの時計回りの方向が間違っている場合は、A と B のパッド定義を交換することができます。define を使って逆にすることもできます:
|
||||
|
||||
```c
|
||||
#define ENCODER_DIRECTION_FLIP
|
||||
```
|
||||
|
||||
さらに、エンコーダが各戻り止め(デテント)間に登録するパルス数を定義する解像度は、次のように定義できます:
|
||||
|
||||
```c
|
||||
#define ENCODER_RESOLUTION 4
|
||||
```
|
||||
|
||||
## 分割キーボード
|
||||
|
||||
分割キーボードのそれぞれの側のエンコーダに異なるピン配列を使っている場合、右側のピン配列を以下のように定義することができます:
|
||||
|
||||
```c
|
||||
#define ENCODERS_PAD_A_RIGHT { encoder1a, encoder2a }
|
||||
#define ENCODERS_PAD_B_RIGHT { encoder1b, encoder2b }
|
||||
```
|
||||
|
||||
## コールバック
|
||||
|
||||
コールバック関数を `<keyboard>.c` に記述することができます:
|
||||
|
||||
```c
|
||||
bool encoder_update_kb(uint8_t index, bool clockwise) {
|
||||
if (!encoder_update_user(index, clockwise)) {
|
||||
return false;
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
あるいは `keymap.c` に記述することもできます:
|
||||
|
||||
```c
|
||||
bool encoder_update_user(uint8_t index, bool clockwise) {
|
||||
if (index == 0) { /* First encoder */
|
||||
if (clockwise) {
|
||||
tap_code(KC_PGDN);
|
||||
} else {
|
||||
tap_code(KC_PGUP);
|
||||
}
|
||||
} else if (index == 1) { /* Second encoder */
|
||||
if (clockwise) {
|
||||
tap_code(KC_DOWN);
|
||||
} else {
|
||||
tap_code(KC_UP);
|
||||
}
|
||||
}
|
||||
return false;
|
||||
}
|
||||
```
|
||||
|
||||
## ハードウェア
|
||||
|
||||
エンコーダの A と B の線は MCU に直接配線し、C/common 線はグランドに配線する必要があります。
|
||||
@ -1,37 +0,0 @@
|
||||
# グレイブエスケープ
|
||||
|
||||
<!---
|
||||
original document: 0.8.123:docs/feature_grave_esc.md
|
||||
git diff 0.8.123 HEAD -- docs/feature_grave_esc.md | cat
|
||||
-->
|
||||
|
||||
60% キーボード、またはファンクションキー行の無い他のレイアウトを使っている場合、専用の Escape キーが無いことに気付くでしょう。グレイブエスケープは grave キー (<code>`</code> および `~`) を Escape と共有することができる機能です。
|
||||
|
||||
## 使用法
|
||||
|
||||
キーマップ内の `KC_GRAVE` キー (通常は`1` キーの左)を `QK_GESC` に置き換えます。ほとんどの場合、このキーは押された時に `KC_ESC` を出力します。ただし、Shift あるいは GUI を押したままにすると、代わりに `KC_GRV` を出力します。
|
||||
|
||||
## OS に見えるもの
|
||||
|
||||
メアリーがキーボードで GESC を押すと、OS には KC_ESC 文字が見えます。メアリーが Shift を押しながら GESC を押すと、`~` または Shift された時はバッククォートを出力します。彼女が GUI/CMD/WIN を押したままにすると、1つの <code>`</code> 文字を出力します。
|
||||
|
||||
## キーコード
|
||||
|
||||
| キー | エイリアス | 説明 |
|
||||
|---------|-----------|------------------------------------------------------------------|
|
||||
| `QK_GESC` | `GRAVE_ESC` | 押された場合に Escape。Shift あるいは GUI が押されたままの場合は <code>`</code> |
|
||||
|
||||
### 注意事項
|
||||
|
||||
macOS では、Command+<code>`</code> はデフォルトで "次のウィンドウを操作対象にする" にマップされます。つまりバッククォートを出力しません。さらに、ショートカットがキーボード環境設定で変更された場合でも、ターミナルは常にこのショートカットを認識してウィンドウを切り替えます。
|
||||
|
||||
## 設定
|
||||
|
||||
グレイブエスケープが壊す可能性のあるキーの組み合わせが幾つかあります。その中には、Windows では Control+Shift+Escape、macOSでは Command+Option+Escape があります。これを回避するには、`config.h` で以下のオプションを `#define` することができます:
|
||||
|
||||
| 定義 | 説明 |
|
||||
|--------------------------|-----------------------------------------|
|
||||
| `GRAVE_ESC_ALT_OVERRIDE` | Alt が押された場合、常に Escape を送信する |
|
||||
| `GRAVE_ESC_CTRL_OVERRIDE` | Control が押された場合、常に Escape を送信する |
|
||||
| `GRAVE_ESC_GUI_OVERRIDE` | GUI が押された場合、常に Escape を送信する |
|
||||
| `GRAVE_ESC_SHIFT_OVERRIDE` | Shift が押された場合、常に Escape を送信する |
|
||||
@ -1,173 +0,0 @@
|
||||
# 触覚フィードバック
|
||||
|
||||
<!---
|
||||
original document: 0.12.41:docs/feature_haptic_feedback.md
|
||||
git diff 0.12.41 HEAD -- docs/feature_haptic_feedback.md | cat
|
||||
-->
|
||||
|
||||
## 触覚フィードバック の rules.mk オプション
|
||||
|
||||
現在のところ、`rules.mk` で触覚フィードバック用に以下のオプションを利用可能です:
|
||||
|
||||
```
|
||||
HAPTIC_ENABLE = yes
|
||||
|
||||
HAPTIC_DRIVER += DRV2605L
|
||||
HAPTIC_DRIVER += 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://cdn-shop.adafruit.com/product-files/412/412_solenoid_driver.pdf)
|
||||
|
||||
|
||||
| 設定 | デフォルト | 説明 |
|
||||
|--------------------------|---------------|-------------------------------------------------------|
|
||||
| `SOLENOID_PIN` | *定義なし* | ソレノイドが接続されているピンを設定する。 |
|
||||
| `SOLENOID_DEFAULT_DWELL` | `12` ms | ソレノイドのデフォルトの滞留時間を設定する。 |
|
||||
| `SOLENOID_MIN_DWELL` | `4` ms | 滞留時間の下限を設定する。 |
|
||||
| `SOLENOID_MAX_DWELL` | `100` ms | 滞留時間の上限を設定する。 |
|
||||
| `SOLENOID_DWELL_STEP_SIZE` | `1` ms | `HPT_DWL*` キーコードが送信される時に使われるステップサイズ |
|
||||
| `SOLENOID_DEFAULT_BUZZ` | `0` (無効) | HPT_RST では、この値が "1" の場合、ブザー音が "on" に設定されます |
|
||||
| `SOLENOID_BUZZ_ACTUATED` | `SOLENOID_MIN_DWELL` | ソレノイドがブザー音モードの場合の動作時間 |
|
||||
| `SOLENOID_BUZZ_NONACTUATED` | `SOLENOID_MIN_DWELL` | ソレノイドがブザー音モードの場合の非動作時間 |
|
||||
|
||||
* ソレノイドのブザー音がオフの場合、滞留時間は「プランジャー」が作動したままになる時間です。滞留時間により、ソレノイドの音が変わります。
|
||||
* ソレノイドのブザー音がオンの場合、滞留時間は振動の長さを設定しますが、`SOLENOID_BUZZ_ACTUATED` と `SOLENOID_BUZZ_NONACTUATED` はブザー音の間の(非)動作時間を設定します。
|
||||
* 現在の実装では、上記の時間設定のいずれについても、設定の精度はキーボードがマトリックスをスキャンできる速度によって影響を受ける可能性があります。
|
||||
したがって、キーボードのスキャンルーチンが遅い場合は、`SOLENOID_DWELL_STEP_SIZE` をキーボードのスキャンに掛かる時間よりもわずかに小さい値に設定することをお勧めします。
|
||||
|
||||
ブートローダ実行中に一部のピンが給電されているかもしれず (例えば、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 連続触覚モード
|
||||
|
||||
このモードは強さを増減するオプションを使って連続触覚フィードバッグを設定します。
|
||||
@ -1,62 +0,0 @@
|
||||
# HD44780 LCD ディスプレイ
|
||||
|
||||
<!---
|
||||
original document: 0.9.43:docs/feature_hd44780.md
|
||||
git diff 0.9.43 HEAD -- docs/feature_hd44780.md | cat
|
||||
-->
|
||||
|
||||
これは Peter Fleury の LCD ライブラリの統合です。このページは基本について説明します。[詳細なドキュメントについてはこのページをご覧ください](http://www.peterfleury.epizy.com/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)
|
||||
|
||||
HD44780 ディスプレイのサポートを有効にするには、キーボードの `rules.mk` の `HD44780_ENABLE` フラグを yes に設定します。
|
||||
|
||||
## 設定
|
||||
|
||||
ディスプレイで使用されるピンとディスプレイの行と列の数を、キーボードの `config.h` に設定する必要があります。
|
||||
|
||||
|
||||
HD44780 のラベルが付いたセクションのコメントを外し、必要に応じてパラメータを変更します。
|
||||
````
|
||||
/*
|
||||
* HD44780 LCD ディスプレイ設定
|
||||
*/
|
||||
|
||||
#define LCD_LINES 2 //< ディスプレイの表示行数
|
||||
#define LCD_DISP_LENGTH 16 //< ディスプレイの行ごとの表示文字数
|
||||
#define LCD_IO_MODE 1 //< 0: メモリマップモード 1: IO ポートモード
|
||||
#if LCD_IO_MODE
|
||||
#define LCD_PORT PORTB //< LCD 行のためのポート
|
||||
#define LCD_DATA0_PORT LCD_PORT //< 4ビットデータビット 0 のポート
|
||||
#define LCD_DATA1_PORT LCD_PORT //< 4ビットデータビット 1 のポート
|
||||
#define LCD_DATA2_PORT LCD_PORT //< 4ビットデータビット 2 のポート
|
||||
#define LCD_DATA3_PORT LCD_PORT //< 4ビットデータビット 3 のポート
|
||||
#define LCD_DATA0_PIN 4 //< 4ビットデータビット 0 のピン
|
||||
#define LCD_DATA1_PIN 5 //< 4ビットデータビット 1 のピン
|
||||
#define LCD_DATA2_PIN 6 //< 4ビットデータビット 2 のピン
|
||||
#define LCD_DATA3_PIN 7 //< 4ビットデータビット 3 のピン
|
||||
#define LCD_RS_PORT LCD_PORT //< RS 線のためのポート
|
||||
#define LCD_RS_PIN 3 //< RS 線のためのピン
|
||||
#define LCD_RW_PORT LCD_PORT //< RW 線のためのポート
|
||||
#define LCD_RW_PIN 2 //< RW 線のためのピン
|
||||
#define LCD_E_PORT LCD_PORT //< Enable 線のためのポート
|
||||
#define LCD_E_PIN 1 //< Enable 線のためのピン
|
||||
#endif
|
||||
````
|
||||
|
||||
他のプロパティを設定する必要がある場合は、それらを `quantum/hd44780.h` からコピーし、`config.h` に設定することができます。（訳注）`quantum/hd44780.h` は `drivers/avr/hd44780.h` の間違いではないかと思われます。
|
||||
|
||||
## 使用法
|
||||
|
||||
ディスプレイを初期化するには、以下のパラメータのうちの1つを使って `lcd_init()` を呼び出します:
|
||||
````
|
||||
LCD_DISP_OFF : ディスプレイオフ
|
||||
LCD_DISP_ON : ディスプレイオン、カーソルオフ
|
||||
LCD_DISP_ON_CURSOR : ディスプレイオン、カーソルオン
|
||||
LCD_DISP_ON_CURSOR_BLINK : ディスプレイオン、点滅カーソル
|
||||
````
|
||||
これはキーボードの `matrix_init_kb` またはキーマップの `matrix_init_user` で行うのが最適です。
|
||||
使用前にディスプレイをクリアすることをお勧めします。
|
||||
そのためには、`lcd_clrscr()` を呼びます。
|
||||
|
||||
ディスプレイに何かを表示するには、最初に `lcd_gotoxy(column, line)` を呼びます。最初の行の先頭に移動するには、`lcd_gotoxy(0, 0)` を呼び出し、その後 `lcd_puts("example string")` を使って文字列を出力します。
|
||||
|
||||
ディスプレイを制御することができる、より多くのメソッドがあります。[詳細なドキュメントについてはリンクされたページをご覧ください](http://www.peterfleury.epizy.com/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)
|
||||
@ -1,27 +0,0 @@
|
||||
# キーロック
|
||||
|
||||
<!---
|
||||
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(MOD_LSFT)` と定義した場合)のみを押し続けることができます。
|
||||
これは、QMK の特殊機能(ワンショットモディファイアを除く)、または `KC_LPRN` のような shift を押されたキーのバージョンは含みません。[基本的なキーコード](ja/keycodes_basic.md)リストにある場合、押したままにすることができます。
|
||||
|
||||
レイヤーの切り替えは、キーロックを解除しません。
|
||||
@ -1,97 +0,0 @@
|
||||
# レイヤー :id=layers
|
||||
|
||||
<!---
|
||||
original document: 0.12.41:docs/feature_layers.md
|
||||
git diff 0.12.41 HEAD -- docs/feature_layers.md | cat
|
||||
-->
|
||||
|
||||
QMK ファームウェアの最も強力で良く使われている機能の一つは、レイヤーを使う機能です。ほとんどの人にとって、これはラップトップやタブレットキーボードにあるのと同じように、様々なキーを可能にするファンクションキーに相当します。
|
||||
|
||||
レイヤースタックがどのように動作するかの詳細な説明については、[キーマップの概要](ja/keymap.md#keymap-and-layers)を調べてください。
|
||||
|
||||
## レイヤーの切り替えとトグル :id=switching-and-toggling-layers
|
||||
|
||||
以下の関数により、様々な方法でレイヤーをアクティブにすることができます。レイヤーは通常、独立したレイアウトでは無いことに注意してください -- 複数のレイヤーを一度にアクティブにすることができ、レイヤーが `KC_TRNS` を使ってキーの押下を下のレイヤーへと透過させることが一般的です。MO()、LM()、TT() あるいは LT() を使って一時的なレイヤーの切り替えを使う場合、上のレイヤーのキーを透過にするようにしてください。さもないと意図したように動作しないかもしれません。
|
||||
|
||||
* `DF(layer)` - デフォルトレイヤーを切り替えます。デフォルトレイヤーは、他のレイヤーがその上に積み重なっている、常にアクティブな基本レイヤーです。デフォルトレイヤーの詳細については以下を見てください。これは QWERTY から Dvorak レイアウトに切り替えるために使うことができます。(これは一時的な切り替えであり、キーボードの電源が切れるまでしか持続しないことに注意してください。デフォルトレイヤーを永続的に変更するには、[process_record_user](ja/custom_quantum_functions.md#programming-the-behavior-of-any-keycode) 内で `set_single_persistent_default_layer` 関数を呼び出すなど、より深いカスタマイズが必要です。)
|
||||
* `MO(layer)` - 一時的に*レイヤー*をアクティブにします。キーを放すとすぐに、レイヤーは非アクティブになります。
|
||||
* `LM(layer, mod)` - (`MO` のように)一時的に*レイヤー*をアクティブにしますが、モディファイア *mod* がアクティブな状態です。layer 0-15 と、左モディファイアのみをサポートします: `MOD_LCTL`、`MOD_LSFT`、`MOD_LALT`、`MOD_LGUI` (`KC_` 定数の代わりに `MOD_` 定数を使うことに注意してください)。これらのモディファイアは、例えば `LM(_RAISE, MOD_LCTL | MOD_LALT)` のように、ビット単位の OR を使って組み合わせることができます。
|
||||
* `LT(layer, kc)` - ホールドされた時に*レイヤー*を一時的にアクティブにし、タップされた時に *kc* を送信します。layer 0-15 のみをサポートします。
|
||||
* `OSL(layer)` - 次のキーが押されるまで、一時的に*レイヤー*をアクティブにします。詳細と追加機能については、[ワンショットキー](ja/one_shot_keys.md)を見てください。
|
||||
* `TG(layer)` - *レイヤー*を切り替えます。非アクティブな場合はアクティブにし、逆も同様です。
|
||||
* `TO(layer)` - *レイヤー*をアクティブにし、他の全てのレイヤー(デフォルトレイヤーを除く)を非アクティブにします。この関数は特別です。1つのレイヤーをアクティブなレイヤースタックに追加/削除する代わりに、現在のアクティブなレイヤーを完全に置き換え、唯一上位のレイヤーを下位のレイヤーで置き換えることができるからです。これはキーダウンで(キーが押されるとすぐに)アクティブになります。
|
||||
* `TT(layer)` - レイヤーのタップ切り替え。キーを押したままにすると*レイヤー*がアクティブにされ、放すと非アクティブになります (`MO` 風)。繰り返しタップすると、レイヤーはオンあるいはオフを切り替えます (`TG` 風)。デフォルトでは5回のタップが必要ですが、`TAPPING_TOGGLE` を定義することで変更することができます -- 例えば、2回のタップだけで切り替えるには、`#define TAPPING_TOGGLE 2` を定義します。
|
||||
|
||||
### 注意事項 :id=caveats
|
||||
|
||||
現在のところ、`LT()` の `layer` 引数はレイヤー 0-15 に制限され、`kc` 引数は[基本的なキーコードセット](ja/keycodes_basic.md)に制限されています。つまり、`LCTL()`、`KC_TILD` あるいは `0xFF` より大きなキーコードを使うことができません。これは、QMK が16ビットのキーコードを使うためです。4ビットは機能の識別のために使われ、4ビットはレイヤーのために使われ、キーコードには8ビットしか残されていません。
|
||||
|
||||
これを拡張してもせいぜい複雑になるだけでしょう。32ビットキーコードに移行すると、これの多くが解決されますが、キーマップマトリックスが使用する領域が2倍になります。また、問題が起きる可能性もあります。タップしたキーコードにモディファイアを適用する必要がある場合は、[タップダンス](ja/feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys)を使うことができます。
|
||||
|
||||
## レイヤーとの連携 :id=working-with-layers
|
||||
|
||||
レイヤーを切り替える時は注意してください。(キーボードを取り外さずに)そのレイヤーを非アクティブにすることができずレイヤーから移動できなくなる可能性があります。最も一般的な問題を避けるためのガイドラインを作成しました。
|
||||
|
||||
### 初心者 :id=beginners
|
||||
|
||||
QMK を使い始めたばかりの場合は、全てを単純にしたいでしょう。レイヤーをセットアップする時は、これらのガイドラインに従ってください:
|
||||
|
||||
* デフォルトの "base" レイヤーとして、layer 0 をセットアップします。これは通常の入力レイヤーであり、任意のレイアウト (qwerty、dvorak、colemak など)にすることができます。通常はキーボードのキーのほとんどまたは全てが定義されているため、これを最下位のレイヤーとして設定することが重要です。そうすることで、もしそれが他のレイヤーの上 (つまりレイヤー番号が大きい)にある場合の影響を防ぎます。
|
||||
* layer 0 をルートとして、レイヤーを "ツリー" レイアウトに配置します。他の複数のレイヤーから同じレイヤーに行こうとしないでください。
|
||||
* 各レイヤーのキーマップでは、より高い番号のレイヤーのみを参照します。レイヤーは最大の番号(最上位)のアクティブレイヤーから処理されるため、下位レイヤーの状態を変更するのは難しくエラーが発生しやすくなります。
|
||||
|
||||
### 中級ユーザ :id=intermediate-users
|
||||
|
||||
複数の基本レイヤーが必要な場合があります。例えば、QWERTY と Dvorak を切り替える場合、国ごとに異なるレイアウトを切り替える場合、あるいは異なるビデオゲームごとにレイアウトを切り替える場合などです。基本レイヤーは常に最小の番号のレイヤーである必要があります。複数の基本レイヤーがある場合、常にそれらを相互排他的に扱う必要があります。1つの基本レイヤーがオンの場合、他をオフにします。
|
||||
|
||||
### 上級ユーザ :id=advanced-users
|
||||
|
||||
レイヤーがどのように動作し、何ができるかを理解したら、より創造的になります。初心者のセクションで列挙されている規則は、幾つかの巧妙な詳細を回避するのに役立ちますが、特に超コンパクトなキーボードのユーザにとって制約になる場合があります。レイヤーの仕組みを理解することで、レイヤーをより高度な方法で使うことができます。
|
||||
|
||||
レイヤーは番号順に上に積み重なっています。キーの押下の動作を決定する時に、QMK は上から順にレイヤーを走査し、`KC_TRNS` に設定されていない最初のアクティブなレイヤーに到達すると停止します。結果として、現在のレイヤーよりも数値的に低いレイヤーをアクティブにし、現在のレイヤー(あるいはアクティブでターゲットレイヤーよりも高い別のレイヤー)に `KC_TRNS` 以外のものがある場合、それが送信されるキーであり、アクティブ化したばかりのレイヤー上のキーではありません。これが、ほとんどの人の "なぜレイヤーが切り替わらないのか" 問題の原因です。
|
||||
|
||||
場合によっては、マクロ内あるいはタップダンスルーチンの一部としてレイヤーを切り替えほうが良いかもしれません。`layer_on` はレイヤーをアクティブにし、`layer_off` はそれを非アクティブにします。もっと多くのレイヤーに関する関数は、[action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/action_layer.h) で見つけることができます。
|
||||
|
||||
## 関数 :id=functions
|
||||
|
||||
レイヤーの使用あるいは操作に関係する多くの関数(と変数)があります。
|
||||
|
||||
| 関数 | 説明 |
|
||||
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
||||
| `layer_state_set(layer_mask)` | 直接レイヤーの状態を設定する (推奨。何をしているのか分かっていない場合は使わないでください)。 |
|
||||
| `layer_clear()` | 全てのレイヤーを消去する (全てをオフにします)。 |
|
||||
| `layer_move(layer)` | 指定されたレイヤーをオンにし、それ以外をオフにする。 |
|
||||
| `layer_on(layer)` | 指定されたレイヤーをオンにし、それ以外を既存の状態のままにする。 |
|
||||
| `layer_off(layer)` | 指定されたレイヤーをオフにし、それ以外を既存の状態のままにする。 |
|
||||
| `layer_invert(layer)` | 指定されたレイヤーの状態を反転/トグルする。 |
|
||||
| `layer_or(layer_mask)` | 指定されたレイヤーと既存のレイヤー状態の間で一致するビットに基づいてレイヤーをオンにする。 |
|
||||
| `layer_and(layer_mask)` | 指定されたレイヤーと既存のレイヤー状態の間で有効なビットに基づいてレイヤーをオンにする。 |
|
||||
| `layer_xor(layer_mask)` | 指定されたレイヤーと既存のレイヤー状態の間で一致しないビットに基づいてレイヤーをオンにする。 |
|
||||
| `layer_debug(layer_mask)` | デバッガのコンソールに現在のビットマスクと最も高いレイヤーを出力する。 |
|
||||
| `default_layer_set(layer_mask)` | 直接デフォルトレイヤーの状態を設定する (推奨。何をしているのか分かっていない場合は使わないでください)。 |
|
||||
| `default_layer_or(layer_mask)` | 指定されたレイヤーと既存のデフォルトレイヤー状態の間で一致するビットに基づいてレイヤーをオンにする。 |
|
||||
| `default_layer_and(layer_mask)` | 指定されたレイヤーと既存のデフォルトレイヤー状態の間で一致する有効なビットに基づいてレイヤーをオンにする。 |
|
||||
| `default_layer_xor(layer_mask)` | 指定されたレイヤーと既存のデフォルトレイヤー状態の間で一致しないビットに基づいてレイヤーをオンにする。 |
|
||||
| `default_layer_debug(layer_mask)` | デバッガのコンソールに現在のビットマスクと最も高いアクティブなレイヤーを出力する。 |
|
||||
| [`set_single_persistent_default_layer(layer)`](ja/ref_functions.md#setting-the-persistent-default-layer) | デフォルトレイヤーを設定し、それを永続化メモリ (EEPROM) に書き込む。 |
|
||||
| [`update_tri_layer(x, y, z)`](ja/ref_functions.md#update_tri_layerx-y-z) | レイヤー `x` と `y` の両方がオンであるかを調べ、それに基づいて `z` を設定する(両方がオンの場合オン、そうでなければオフ)。 |
|
||||
| [`update_tri_layer_state(state, x, y, z)`](ja/ref_functions.md#update_tri_layer_statestate-x-y-z) | `update_tri_layer(x, y, z)` と同じことをするが、`layer_state_set_*` 関数から呼ばれる。 |
|
||||
|
||||
|
||||
呼び出すことができる関数に加えて、レイヤーが変更されるたびに呼び出されるコールバック関数が幾つかあります。これはレイヤー状態を関数に渡し、読み取りや変更することができます。
|
||||
|
||||
| コールバック | 説明 |
|
||||
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
||||
| `layer_state_set_kb(layer_state_t state)` | キーボードレベルのレイヤー関数のためのコールバック。 |
|
||||
| `layer_state_set_user(layer_state_t state)` | ユーザレベルのレイヤー関数のためのコールバック。 |
|
||||
| `default_layer_state_set_kb(layer_state_t state)` | キーボードレベルのデフォルトレイヤー関数のためのコールバック。キーボードの初期化時に呼ばれます。 |
|
||||
| `default_layer_state_set_user(layer_state_t state)` | ユーザレベルのデフォルトレイヤー関数のためのコールバック。キーボードの初期化時に呼ばれます。 |
|
||||
|
||||
?> これらのコールバックを使うための追加の情報については、[レイヤー変換コード](ja/custom_quantum_functions.md#layer-change-code)のドキュメントを調べてください。
|
||||
|
||||
次の関数やマクロを使って、特定のレイヤーの状態を確認することもできます。
|
||||
|
||||
| 関数 | 説明 | 別名 |
|
||||
| ------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
|
||||
| `layer_state_is(layer)` | 指定された `layer` がグローバルに有効かどうかを確認する。 | `IS_LAYER_ON(layer)`, `IS_LAYER_OFF(layer)` |
|
||||
| `layer_state_cmp(state, layer)` | `state` を確認して指定された `layer` が有効かどうかを確認する。レイヤーのコールバックで使うことを目的とする。 | `IS_LAYER_ON_STATE(state, layer)`, `IS_LAYER_OFF_STATE(state, layer)` |
|
||||
@ -1,114 +0,0 @@
|
||||
# レイアウト: 複数のキーボードで1つのキーマップを使用
|
||||
|
||||
<!---
|
||||
original document: 0.8.134:docs/feature_layouts.md
|
||||
git diff 0.8.134 HEAD -- docs/feature_layouts.md | cat
|
||||
-->
|
||||
|
||||
`layouts/` フォルダは、様々なキーボードに適用できる色々な物理キーレイアウトを含みます。
|
||||
|
||||
```
|
||||
layouts/
|
||||
+ default/
|
||||
| + 60_ansi/
|
||||
| | + readme.md
|
||||
| | + layout.json
|
||||
| | + a_good_keymap/
|
||||
| | | + keymap.c
|
||||
| | | + readme.md
|
||||
| | | + config.h
|
||||
| | | + rules.mk
|
||||
| | + <keymap folder>/
|
||||
| | + ...
|
||||
| + <layout folder>/
|
||||
+ community/
|
||||
| + <layout folder>/
|
||||
| + ...
|
||||
```
|
||||
|
||||
`layouts/default/` と `layouts/community/` は、レイアウト「repositories」の2つの例です。現在のところ、`default` にはユーザの参考用に、レイアウトに関する全ての情報および、`default_<layout>` という名前の1つのデフォルトのキーマップが含まれています。`community` には全ての共有キーマップが含まれており、それらはユーザが `layouts/` にクローンするための別のリポジトリに分割することを最終的な目的としていますQMK は `layouts/` 内のすべてのフォルダを検索するため、ここに複数のリポジトリを持つことができます。
|
||||
|
||||
各レイアウトフォルダは、レイアウトの物理的な側面に基づいて、可能な限り一般的な名称で(`[a-z0-9_]`)という名前が付けられ、キーボードで定義されるレイアウトと一緒に `readme.md` を含みます。
|
||||
|
||||
```md
|
||||
# 60_ansi
|
||||
|
||||
LAYOUT_60_ansi
|
||||
```
|
||||
|
||||
新しい名前は既存のレイアウトで設定された標準に準拠しようと努力する必要があり、必要に応じて PR/Issue で議論することができます。
|
||||
|
||||
## レイアウトのサポート
|
||||
|
||||
キーボードがレイアウトをサポートするために、変数は `<keyboard>.h` で定義し、引数/キー (できれば物理レイアウト)の数に一致している必要があります。
|
||||
|
||||
#define LAYOUT_60_ansi KEYMAP_ANSI
|
||||
|
||||
レイアウトの名前は次の正規表現に一致しなければなりません: `[a-z0-9_]+`
|
||||
|
||||
フォルダ名はキーボードの `rules.mk` に追加する必要があります:
|
||||
|
||||
LAYOUTS = 60_ansi
|
||||
|
||||
`LAYOUTS` は任意のキーボードフォルダレべルの `rules.mk` に設定することができます:
|
||||
|
||||
LAYOUTS = 60_iso
|
||||
|
||||
ただし、`LAYOUT_<layout>` 変数は `<folder>.h` でも定義する必要があります。
|
||||
|
||||
## キーマップのビルド
|
||||
|
||||
以下の形式でコマンドを使ってキーボードキーマップを作成できるはずです:
|
||||
|
||||
make <keyboard>:<layout>
|
||||
|
||||
### レイアウトの競合
|
||||
キーボードが複数のレイアウトオプションをサポートし、
|
||||
|
||||
LAYOUTS = ortho_4x4 ortho_4x12
|
||||
|
||||
なおかつ両方のオプションについてレイアウトが存在する場合、
|
||||
```
|
||||
layouts/
|
||||
+ community/
|
||||
| + ortho_4x4/
|
||||
| | + <layout>/
|
||||
| | | + ...
|
||||
| + ortho_4x12/
|
||||
| | + <layout>/
|
||||
| | | + ...
|
||||
| + ...
|
||||
```
|
||||
|
||||
FORCE_LAYOUT 引数はどのレイアウトをビルドするかを指定するために使うことができます
|
||||
|
||||
make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x4
|
||||
make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x12
|
||||
|
||||
## キーボードに依存しないレイアウトを作成するためのヒント
|
||||
|
||||
### インクルード
|
||||
|
||||
`#include "planck.h"` を使う代わりに、以下の行を使ってコンパイルされる `<keyboard>.h` (`<folder>.h` はここでインクルードすべきではありません)ファイルをインクルードすることができます:
|
||||
|
||||
#include QMK_KEYBOARD_H
|
||||
|
||||
キーボード固有のコードを保持したい場合は、これらの変数を使って `#ifdef` 文でエスケープすることができます:
|
||||
|
||||
* `KEYBOARD_<folder1>_<folder2>`
|
||||
|
||||
例えば:
|
||||
|
||||
```c
|
||||
#ifdef KEYBOARD_planck
|
||||
#ifdef KEYBOARD_planck_rev4
|
||||
planck_rev4_function();
|
||||
#endif
|
||||
#endif
|
||||
```
|
||||
|
||||
名前は小文字でキーボード/リビジョンのフォルダ/ファイル名と正確に一致することに注意してください。
|
||||
|
||||
### キーマップ
|
||||
|
||||
同じレイアウトで分割および非分割キーボードをサポートするためには、キーマップでキーボード非依存の `LAYOUT_<layout name>` マクロを使う必要があります。例えば、Let's Split および Planck が同じレイアウトを共有するには、`LAYOUT_planck_grid` や C 配列の場合の単なる `{}` の代わりに、`LAYOUT_ortho_4x12` を使う必要があります。
|
||||
@ -1,164 +0,0 @@
|
||||
# リーダーキー: 新しい種類のモディファイア
|
||||
|
||||
<!---
|
||||
original document: 0.13.24:docs/feature_leader_key.md
|
||||
git diff 0.13.24 HEAD -- docs/feature_leader_key.md | cat
|
||||
-->
|
||||
|
||||
もしあなたが Vim を使ったことがある場合、リーダーキーは何であるかを知っています。そうでなければ、素晴らしい概念を発見しようとしています。:) 例えば、Alt+Shift+W を押す(3つのキーを同時に押す)代わりに、キーの_シーケンス_を押すことができたらどうでしょう？つまり、特別なモディファイア (リーダーキー)を押して、続けて W と C を押すと (単純にキーを高速に繋げます)、何かが起こります。
|
||||
|
||||
それが `KC_LEAD` の機能です。以下は例です:
|
||||
|
||||
1. リーダーキーとして使いたいキーボードのキーを選択します。それにキーコード `KC_LEAD` を割り当てます。このキーはこのためだけの専用です -- 単一アクションのキーで、他の用途には使うことができません。
|
||||
2. `config.h` に `#define LEADER_TIMEOUT 300` という行を追加します。これによって `KC_LEAD` キーのタイムアウトを設定します。具体的には、`KC_LEAD` キーを押してからリーダーキーのシーケンスを完了するまで一定の時間しかありません。ここでの `300` はそれを300msに設定します。この値を増やして、シーケンスを入力する時間を増やすことができます。ただし、この時間中に押されたキーは全て途中で遮られ、送信されません。そのためこの値は小さくしておいたほうが良いかもしれません。
|
||||
* デフォルトでは、このタイムアウトは、`KC_LEAD` を押してからシーケンス全体が完了するまでに掛かる時間です。これは一部の人にとっては非常に短いかもしれません。そのため、このタイムアウトを増やしたほうが良い場合もあります。必要に応じて、`LEADER_PER_KEY_TIMING` オプションを有効にしたほうが良い場合もあります。これは各キーがタップされる度にタイムアウトまでの時間をリセットする機能です。これにより、タイムアウト時間を短くしつつも、比較的長いシーケンスを使うことができます。このオプションを有効にするには、`config.h` に `#define LEADER_PER_KEY_TIMING` を追加します。
|
||||
3. `matrix_scan_user` 関数の中で、以下のようなものを追加します:
|
||||
|
||||
```c
|
||||
LEADER_EXTERNS();
|
||||
|
||||
void matrix_scan_user(void) {
|
||||
LEADER_DICTIONARY() {
|
||||
leading = false;
|
||||
leader_end();
|
||||
|
||||
SEQ_ONE_KEY(KC_F) {
|
||||
// マクロ内でできること
|
||||
SEND_STRING("QMK is awesome.");
|
||||
}
|
||||
SEQ_TWO_KEYS(KC_D, KC_D) {
|
||||
SEND_STRING(SS_LCTL("a") SS_LCTL("c"));
|
||||
}
|
||||
SEQ_THREE_KEYS(KC_D, KC_D, KC_S) {
|
||||
SEND_STRING("https://start.duckduckgo.com\n");
|
||||
}
|
||||
SEQ_TWO_KEYS(KC_A, KC_S) {
|
||||
register_code(KC_LGUI);
|
||||
register_code(KC_S);
|
||||
unregister_code(KC_S);
|
||||
unregister_code(KC_LGUI);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
ご覧のとおり、幾つかの関数があります。`SEQ_ONE_KEY` を単一キーシーケンス (リーダーの後に1つのキーのみ)に使い、より長いシーケンスについては `SEQ_TWO_KEYS`、`SEQ_THREE_KEYS` から `SEQ_FIVE_KEYS` を使うことができます。
|
||||
|
||||
これらはそれぞれ1つ以上のキーコードを引数として受け付けます。これは重要な点です: **キーボードの任意のレイヤー**のキーコードを使うことができます。当たり前ですが、リーダーマクロが発動するにはそのレイヤーがアクティブである必要があります
|
||||
|
||||
## `rules.mk` にリーダーキーサポートを追加
|
||||
|
||||
リーダーキーのサポートを追加するには、単純にキーマップの `rules.mk` に1行を追加します:
|
||||
|
||||
```make
|
||||
LEADER_ENABLE = yes
|
||||
```
|
||||
|
||||
## リーダーキーのキーごとのタイミング
|
||||
|
||||
長いリーダーキー文字列のためや 200wpm のタイピングスキルが無い場合に、非常に長いタイムアウト時間に頼るのではなく、キーを押すごとに入力を完了するまでの時間を増やす機能を使用することができます。これは、リーダーキーを使ってタップダンスを再現する場合に非常に役立ちます (C, C, C のような同じキーを複数回タップする場合)。
|
||||
|
||||
これを有効にするには、以下を `config.h` に配置します:
|
||||
```c
|
||||
#define LEADER_PER_KEY_TIMING
|
||||
```
|
||||
|
||||
この後、`LEADER_TIMEOUT` を 300ms 未満に下げることをお勧めします。
|
||||
|
||||
```c
|
||||
#define LEADER_TIMEOUT 250
|
||||
```
|
||||
|
||||
これで、リーダーキーのタイムアウト時間を 1000ms に設定することなく以下のようなことが可能になると思われます。
|
||||
|
||||
```c
|
||||
SEQ_THREE_KEYS(KC_C, KC_C, KC_C) {
|
||||
SEND_STRING("Per key timing is great!!!");
|
||||
}
|
||||
```
|
||||
|
||||
## リーダーキーの無限タイムアウト
|
||||
|
||||
リーダーキーが、シーケンスの残りのキーのような快適な場所にない場合があります。リーダーキーが右上の外側のキーの1つである場合、リーダーキーに届くように手の位置を変えなければならないことがあります。
|
||||
これにより、シーケンスの大部分をすばやく入力できたとしても、シーケンス全体を時間通りに入力するのが難しい場合があります。例えば、シーケンスが `Leader + asd` の場合、手をホーム行に置けば `asd` を素早く打つのは非常に簡単です。しかし、リーダーキーに届くようにホーム行から手を移動し、戻った後、時間内にシーケンスを開始することはできません。
|
||||
この状況が手に与えるストレスを取り除くために、リーダーキーだけに無限のタイムアウトを有効にすることができます。つまり、リーダーキーを押した後、シーケンスの残りを開始するまでの時間が無限になり、シーケンスの残りを快適に入力するための最適な位置に手を置くことができます。
|
||||
この無限のタイムアウトはリーダーキーにのみ影響するため、前述の `Leader + asd` の例では、`Leader` と `a` の間に無限の時間があります。ただし、シーケンスを開始すると、(グローバルまたはキーごとに)設定したタイムアウトは正常に機能します。
|
||||
このようにして、非常に短い `LEADER_TIMEOUT` を設定できますが、それでも手を置く時間は十分にあります。
|
||||
|
||||
これを有効にするには、以下を `config.h` に配置します:
|
||||
```c
|
||||
#define LEADER_NO_TIMEOUT
|
||||
```
|
||||
|
||||
## 厳密なキー処理
|
||||
|
||||
デフォルトでは、リーダーキー機能は、リーダーシーケンスの確認時に [`モッドタップ`](ja/mod_tap.md) および [`レイヤータップ`](ja/feature_layers.md#switching-and-toggling-layers) 機能からのキーコードをフィルターします。つまり、`LT(3, KC_A)` を使っている場合、`LT(3, KC_A)` ではなくシーケンスの `KC_A` として取り出され、新しいユーザにとってより期待される動作を提供します。
|
||||
|
||||
ほとんどの場合これで問題ありませんが、シーケンスでキーコード全体(例えば、上の例での `LT(3, KC_A)`) を指定したい場合は、`config.h` ファイルに `#define LEADER_KEY_STRICT_KEY_PROCESSING` を追加することこのような機能を有効にすることができます。これでフィルタリングが無効になり、キーコード全体を指定する必要があります。
|
||||
|
||||
## カスタマイズ
|
||||
|
||||
リーダーキー機能には、リーダーキー機能の動作にいくらかのカスタマイズを追加する方法があります。リーダーキー機能のプロセスの特定の部分で呼び出すことができる2つの関数、`leader_start()` と `leader_end()` です。
|
||||
|
||||
`KC_LEAD` キーがタップされた時に `leader_start()` 関数が呼ばれ、リーダーシーケンスが完了するか、リーダータイムアウトの時間に達した時に `leader_end()` 関数が呼ばれます。
|
||||
|
||||
リーダーシーケンスにフィードバック(ビープまたは音楽を再生するなど)を追加するために、これらの関数をコード (通常 は`keymap.c`)に追加することができます。
|
||||
|
||||
```c
|
||||
void leader_start(void) {
|
||||
// シーケンスの開始
|
||||
}
|
||||
|
||||
void leader_end(void) {
|
||||
// シーケンスの終了 (成功しない/失敗を検知)
|
||||
}
|
||||
```
|
||||
|
||||
### 例
|
||||
|
||||
この例では、リーダーシーケンスを開始するために `KC_LEAD` を押すとマリオの "One Up" 音が再生され、正常に完了した場合は "All Star" が再生され、失敗した場合は "Rick Roll" を再生されます。
|
||||
|
||||
```c
|
||||
bool did_leader_succeed;
|
||||
#ifdef AUDIO_ENABLE
|
||||
float leader_start[][2] = SONG(ONE_UP_SOUND );
|
||||
float leader_succeed[][2] = SONG(ALL_STAR);
|
||||
float leader_fail[][2] = SONG(RICK_ROLL);
|
||||
#endif
|
||||
LEADER_EXTERNS();
|
||||
|
||||
void matrix_scan_user(void) {
|
||||
LEADER_DICTIONARY() {
|
||||
did_leader_succeed = leading = false;
|
||||
|
||||
SEQ_ONE_KEY(KC_E) {
|
||||
// マクロ内でできること
|
||||
SEND_STRING(SS_LCTL(SS_LSFT("t")));
|
||||
did_leader_succeed = true;
|
||||
} else
|
||||
SEQ_TWO_KEYS(KC_E, KC_D) {
|
||||
SEND_STRING(SS_LGUI("r") "cmd\n" SS_LCTL("c"));
|
||||
did_leader_succeed = true;
|
||||
}
|
||||
leader_end();
|
||||
}
|
||||
}
|
||||
|
||||
void leader_start(void) {
|
||||
#ifdef AUDIO_ENABLE
|
||||
PLAY_SONG(leader_start);
|
||||
#endif
|
||||
}
|
||||
|
||||
void leader_end(void) {
|
||||
if (did_leader_succeed) {
|
||||
#ifdef AUDIO_ENABLE
|
||||
PLAY_SONG(leader_succeed);
|
||||
#endif
|
||||
} else {
|
||||
#ifdef AUDIO_ENABLE
|
||||
PLAY_SONG(leader_fail);
|
||||
#endif
|
||||
}
|
||||
}
|
||||
```
|
||||
@ -1,119 +0,0 @@
|
||||
# LED インジケータ
|
||||
|
||||
<!---
|
||||
original document: 0.10.52:docs/feature_led_indicators.md
|
||||
git diff 0.10.52 HEAD -- docs/feature_led_indicators.md | cat
|
||||
-->
|
||||
|
||||
QMK は HID 仕様で定義された5つの LED の読み取りメソッドを提供します:
|
||||
|
||||
* Num Lock
|
||||
* Caps Lock
|
||||
* Scroll Lock
|
||||
* Compose
|
||||
* Kana
|
||||
|
||||
ロック LED の状態を取得するには3つの方法があります:
|
||||
* `config.h` で設定オプションを指定する
|
||||
* `bool led_update_kb(led_t led_state)` あるいは `_user(led_t led_state)` を実装する、または
|
||||
* `led_t host_keyboard_led_state()` を呼び出す
|
||||
|
||||
!> `host_keyboard_led_state()` は `led_update_user()` が呼ばれる前に新しい値を既に反映している場合があります。
|
||||
|
||||
LED の状態を `uint8_t` として提供する2つの非推奨の関数があります:
|
||||
|
||||
* `uint8_t led_set_user(uint8_t usb_led)`
|
||||
* `uint8_t host_keyboard_leds()`
|
||||
|
||||
## 設定オプション :id=configuration-options
|
||||
|
||||
インジケータを設定するには、`config.h` で以下の `#define` をします:
|
||||
|
||||
| 定義 | 既定値 | 説明 |
|
||||
|-----------------------|------------|----------------------------------|
|
||||
| `LED_NUM_LOCK_PIN` | *定義なし* | `Num Lock` LED を制御するピン |
|
||||
| `LED_CAPS_LOCK_PIN` | *定義なし* | `Caps Lock` LED を制御するピン |
|
||||
| `LED_SCROLL_LOCK_PIN` | *定義なし* | `Scroll Lock` LED を制御するピン |
|
||||
| `LED_COMPOSE_PIN` | *定義なし* | `Compose` LED を制御するピン |
|
||||
| `LED_KANA_PIN` | *定義なし* | `Kana` LED を制御するピン |
|
||||
| `LED_PIN_ON_STATE` | `1` | LED が "オン" の時のインジケータピンの状態 - high の場合は`1`、low の場合は`0` |
|
||||
|
||||
独自のキーボードを設計しているわけではない限り、通常は上記の設定オプションを変更する必要はありません。
|
||||
|
||||
## `led_update_*()`
|
||||
|
||||
設定オプションが十分な柔軟性を提供しない場合は、提供される API フックにより LED の挙動の独自の制御ができます。これらの関数はこれら5つの LED のいずれかの状態が変化すると呼ばれます。LED の状態を構造体のパラメータとして受け取ります。
|
||||
|
||||
慣例により、`led_update_kb()` にそのコードを実行するようフックさせるために `led_update_user()` から `true` を返し、`led_update_kb()` でコードを実行したくない場合は `false` を返します。
|
||||
|
||||
以下はいくつかの例です:
|
||||
|
||||
- レイヤー表示のような何かのために LED を使うために LED を上書きする
|
||||
- `_kb()` 関数を実行したくないので、`false` を返します。これはレイヤーの挙動を上書きするためです。
|
||||
- LED がオンあるいはオフになった時に音楽を再生する。
|
||||
- `_kb` 関数を実行したいので、`true` を返します。これはデフォルトの LED の挙動に追加されます。
|
||||
|
||||
?> `led_set_*` 関数は `bool` の代わりに `void` を返すため、キーボードの LED 制御を上書きすることができません。従って、代わりに `led_update_*` を使うことをお勧めします。
|
||||
|
||||
### `led_update_kb()` の実装例
|
||||
|
||||
```c
|
||||
bool led_update_kb(led_t led_state) {
|
||||
bool res = led_update_user(led_state);
|
||||
if(res) {
|
||||
// writePin は 1 でピンを high に、0 で low に設定します。
|
||||
// この例では、ピンは反転していて、
|
||||
// low/0 は LED がオンになり、high/1 は LED がオフになります。
|
||||
// この挙動は、LED がピンと VCC の間にあるか、ピンと GND の間にあるかどうかに依存します。
|
||||
writePin(B0, !led_state.num_lock);
|
||||
writePin(B1, !led_state.caps_lock);
|
||||
writePin(B2, !led_state.scroll_lock);
|
||||
writePin(B3, !led_state.compose);
|
||||
writePin(B4, !led_state.kana);
|
||||
}
|
||||
return res;
|
||||
}
|
||||
```
|
||||
|
||||
### `led_update_user()` の実装例
|
||||
|
||||
この不完全な例は Caps Lock がオンまたはオフになった場合に音を再生します。また LED の状態を保持する必要があるため、`true` を返します。
|
||||
|
||||
```c
|
||||
#ifdef AUDIO_ENABLE
|
||||
float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND);
|
||||
float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND);
|
||||
#endif
|
||||
|
||||
bool led_update_user(led_t led_state) {
|
||||
#ifdef AUDIO_ENABLE
|
||||
static uint8_t caps_state = 0;
|
||||
if (caps_state != led_state.caps_lock) {
|
||||
led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off);
|
||||
caps_state = led_state.caps_lock;
|
||||
}
|
||||
#endif
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
### `led_update_*` 関数のドキュメント
|
||||
|
||||
* キーボード/リビジョン: `bool led_update_kb(led_t led_state)`
|
||||
* キーマップ: `bool led_update_user(led_t led_state)`
|
||||
|
||||
## `host_keyboard_led_state()`
|
||||
|
||||
最後に受信した LED の状態を `led_t` として取得するためにこの関数を呼びます。これは、`led_update_*` の外部から、例えば [`matrix_scan_user()`](#matrix-scanning-code) の中で LED の状態を読み取るのに便利です。
|
||||
|
||||
## 物理的な LED の状態の設定
|
||||
|
||||
一部のキーボードの実装は、物理的な LED の状態を設定するための便利なメソッドを提供しています。
|
||||
|
||||
### Ergodox キーボード
|
||||
|
||||
Ergodox の実装は、個々の LED をオンあるいはオフにするために `ergodox_right_led_1`/`2`/`3_on`/`off()` と、インデックスによってそれらをオンあるいはオフにするために `ergodox_right_led_on`/`off(uint8_t led)` を提供します。
|
||||
|
||||
さらに、LED の明度を指定することができます。全ての LED に同じ明度を指定するなら `ergodox_led_all_set(uint8_t n)` を使い、個別の LED の明度を指定するなら `ergodox_right_led_1`/`2`/`3_set(uint8_t n)` を使い、LED のインデックスを指定して明度を指定するには `ergodox_right_led_set(uint8_t led, uint8_t n)` を使います。
|
||||
|
||||
Ergodox キーボードは、最低の明度として `LED_BRIGHTNESS_LO` を、最高の輝度(これはデフォルトです)として `LED_BRIGHTNESS_HI` も定義しています。
|
||||
@ -1,96 +0,0 @@
|
||||
# LED マトリックスライト
|
||||
|
||||
<!---
|
||||
original document: 0.8.141:docs/feature_led_matrix.md
|
||||
git diff 0.8.141 HEAD -- docs/feature_led_matrix.md | cat
|
||||
-->
|
||||
|
||||
この機能により、外部ドライバによって駆動される LED マトリックスを使うことができます。この機能は、バックライト制御と同じキーコードを使えるようにするため、バックライトシステムに接続します。
|
||||
|
||||
RGB LED を使いたい場合は、代わりに [RGB マトリックスサブシステム](ja/feature_rgb_matrix.md) を使うべきです。
|
||||
|
||||
## ドライバ設定
|
||||
|
||||
### IS31FL3731
|
||||
|
||||
I2C IS31FL3731 RGB コントローラを使ったアドレス指定可能な LED マトリックスライトのための基本的なサポートがあります:有効にするには、`rules.mk` に以下を追加します:
|
||||
|
||||
LED_MATRIX_ENABLE = yes
|
||||
LED_MATRIX_DRIVER = IS31FL3731
|
||||
|
||||
1から4個の IS31FL3731 IC を使うことができます。キーボード上に存在しない IC の `LED_DRIVER_ADDR_<N>` 定義を指定しないでください。`config.h` に以下の項目を定義することができます:
|
||||
|
||||
| 変数 | 説明 | デフォルト |
|
||||
|----------|-------------|---------|
|
||||
| `ISSI_TIMEOUT` | (オプション) i2c メッセージを待つ時間 | 100 |
|
||||
| `ISSI_PERSISTENCE` | (オプション) 失敗したメッセージをこの回数再試行する | 0 |
|
||||
| `LED_DRIVER_COUNT` | (必須) LED ドライバ IC の数 | |
|
||||
| `DRIVER_LED_TOTAL` | (必須) 全てのドライバの LED ライトの数 | |
|
||||
| `LED_DRIVER_ADDR_1` | (必須) 最初の LED ドライバのアドレス | |
|
||||
| `LED_DRIVER_ADDR_2` | (オプション) 2番目の LED ドライバのアドレス | |
|
||||
| `LED_DRIVER_ADDR_3` | (オプション) 3番目の LED ドライバのアドレス | |
|
||||
| `LED_DRIVER_ADDR_4` | (オプション) 4番目の LED ドライバのアドレス | |
|
||||
|
||||
2つのドライバを使う例です。
|
||||
|
||||
// これは7ビットのアドレスで、左シフトされます
|
||||
// ビット0に0を設定すると書き込み、1を設定すると読み込みです (I2C プロトコルに従う)
|
||||
// アドレスは配線によって変わります:
|
||||
// 0b1110100 AD <-> GND
|
||||
// 0b1110111 AD <-> VCC
|
||||
// 0b1110101 AD <-> SCL
|
||||
// 0b1110110 AD <-> SDA
|
||||
#define LED_DRIVER_ADDR_1 0b1110100
|
||||
#define LED_DRIVER_ADDR_2 0b1110110
|
||||
|
||||
#define LED_DRIVER_COUNT 2
|
||||
#define LED_DRIVER_1_LED_COUNT 25
|
||||
#define LED_DRIVER_2_LED_COUNT 24
|
||||
#define DRIVER_LED_TOTAL LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL
|
||||
|
||||
現在、2つのドライバのみがサポートされますが、4つの組み合わせ全てをサポートすることは簡単です。
|
||||
|
||||
`<keyboard>.c` に全ての LED を列挙する配列を定義します:
|
||||
|
||||
const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = {
|
||||
/* これらの位置については IS31 マニュアルを参照してください
|
||||
* driver
|
||||
* | LED address
|
||||
* | | */
|
||||
{0, C3_3},
|
||||
....
|
||||
}
|
||||
|
||||
ここで、`Cx_y` は[データシート](https://www.issi.com/WW/pdf/31FL3731.pdf)およびヘッダファイル `drivers/led/issi/is31fl3731-simple.h` で定義されるマトリックス内の LED の位置です。`driver` は `config.h` で定義したドライバのインデックス(`0`、`1`、`2`、`3`のいずれか)です。
|
||||
|
||||
## キーコード
|
||||
|
||||
現在のところ、全ての LED マトリックスのキーコードは[バックライトシステム](ja/feature_backlight.md)と共有されます。
|
||||
|
||||
## LED マトリックス効果
|
||||
|
||||
現在のところ、LED マトリックス効果は作成されていません。
|
||||
|
||||
## カスタムレイヤー効果
|
||||
|
||||
カスタムレイヤー効果は `<keyboard>.c` 内で以下を定義することで行うことができます:
|
||||
|
||||
void led_matrix_indicators_kb(void) {
|
||||
led_matrix_set_value(index, value);
|
||||
}
|
||||
|
||||
同様の関数がキーマップ内で `led_matrix_indicators_user` として動作します。
|
||||
|
||||
## サスペンド状態
|
||||
|
||||
サスペンド機能を使うには、以下を `<keyboard>.c` に追加します:
|
||||
|
||||
void suspend_power_down_kb(void)
|
||||
{
|
||||
led_matrix_set_suspend_state(true);
|
||||
}
|
||||
|
||||
void suspend_wakeup_init_kb(void)
|
||||
{
|
||||
led_matrix_set_suspend_state(false);
|
||||
}
|
||||
@ -1,303 +0,0 @@
|
||||
# マクロ
|
||||
|
||||
<!---
|
||||
original document: 0.9.43:docs/feature_macros.md
|
||||
git diff 0.9.43 HEAD -- docs/feature_macros.md | cat
|
||||
-->
|
||||
|
||||
マクロにより、1つのキーを押すだけで複数のキーストロークを送信することができます。QMK にはマクロを定義し使う方法が幾つかあります。これらはなんでもすることができます: よく使うフレーズの入力、コピーペースト、反復的なゲームの動き、あるいはコードを書くことさえ手助けします。
|
||||
|
||||
!> **セキュリティの注意**: マクロを使って、パスワード、クレジットカード番号、その他の機密情報のいずれも送信することが可能ですが、それは非常に悪い考えです。あなたのキーボードを手に入れた人は誰でもテキストエディタを開いてその情報にアクセスすることができます。
|
||||
|
||||
## `SEND_STRING()` と `process_record_user`
|
||||
|
||||
単語またはフレーズを入力するキーが欲しい時があります。最も一般的な状況のために `SEND_STRING()` を提供しています。これは文字列(つまり、文字のシーケンス)を入力します。簡単にキーコードに変換することができる全ての ASCII 文字がサポートされています (例えば、`qmk 123\n\t`)。
|
||||
|
||||
以下は2キーのキーボードのための `keymap.c` の例です:
|
||||
|
||||
```c
|
||||
enum custom_keycodes {
|
||||
QMKBEST = SAFE_RANGE,
|
||||
};
|
||||
|
||||
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
|
||||
switch (keycode) {
|
||||
case QMKBEST:
|
||||
if (record->event.pressed) {
|
||||
// キーコード QMKBEST が押された時
|
||||
SEND_STRING("QMK is the best thing ever!");
|
||||
} else {
|
||||
// キーコード QMKBEST が放された時
|
||||
}
|
||||
break;
|
||||
}
|
||||
return true;
|
||||
};
|
||||
|
||||
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
|
||||
[0] = {
|
||||
{QMKBEST, KC_ESC},
|
||||
// ...
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
ここで起きることは以下の通りです:
|
||||
最初に他のキーコードで使用されていない範囲で新しいカスタムキーコードを定義します。
|
||||
次に、`process_record_user` 関数を使います。これはキーが押されるか放されるたびに呼び出され、カスタムキーコードがアクティブかどうかを確認します。
|
||||
アクティブな場合、`SEND_STRING` マクロ (これは C プロセッサのマクロで、QMK のマクロと混同しないでください)を介して文字列 `"QMK is the best thing ever!"` をコンピュータに送信します。
|
||||
呼び出し元に、処理したばかりのキー押下を通常通り(機能を置き換えたり変更したりしなかったので)処理し続けるよう指示するため、`true` を返します。
|
||||
最後に、最初のボタンがマクロをアクティブにし、2番目のボタンが単なるエスケープボタンになるようにキーマップを定義します。
|
||||
|
||||
複数のマクロを追加することもできます。
|
||||
以下のように、別のキーコードを追加し、switch 文に別の case ラベルを追加することで、それを行うことができます:
|
||||
|
||||
```c
|
||||
enum custom_keycodes {
|
||||
QMKBEST = SAFE_RANGE,
|
||||
QMKURL,
|
||||
MY_OTHER_MACRO,
|
||||
};
|
||||
|
||||
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
|
||||
switch (keycode) {
|
||||
case QMKBEST:
|
||||
if (record->event.pressed) {
|
||||
// キーコード QMKBEST が押された時
|
||||
SEND_STRING("QMK is the best thing ever!");
|
||||
} else {
|
||||
// キーコード QMKBEST が放された時
|
||||
}
|
||||
break;
|
||||
|
||||
case QMKURL:
|
||||
if (record->event.pressed) {
|
||||
// キーコード QMKURL が押された場合
|
||||
SEND_STRING("https://qmk.fm/\n");
|
||||
} else {
|
||||
// キーコード QMKURL が放された場合
|
||||
}
|
||||
break;
|
||||
|
||||
case MY_OTHER_MACRO:
|
||||
if (record->event.pressed) {
|
||||
SEND_STRING(SS_LCTL("ac")); // 全てを選択しコピーします
|
||||
}
|
||||
break;
|
||||
}
|
||||
return true;
|
||||
};
|
||||
|
||||
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
|
||||
[0] = {
|
||||
{MY_CUSTOM_MACRO, MY_OTHER_MACRO},
|
||||
// ...
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 高度なマクロ
|
||||
|
||||
`process_record_user()` 関数のほかに、`post_process_record_user()` 関数があります。これは `process_record` の後に実行され、キーストロークが送信された後の処理に使用できます。これは例えば、通常のキーの前に押され、通常のキーの後で放されるキーがほしい場合に便利です。
|
||||
|
||||
この例では、通常のキー入力を変更して、キーストロークが通常送信される前に `F22` が押されるようにし、キーが放された__後にのみ__ `F22` キーを放します。
|
||||
|
||||
```c
|
||||
static uint8_t f22_tracker;
|
||||
|
||||
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
|
||||
switch (keycode) {
|
||||
case KC_A ... KC_F21: // F22 をスキップする方法に注意してください
|
||||
case KC_F23 ... KC_EXSEL: //exsel は修飾キーの直前のキーです
|
||||
if (record->event.pressed) {
|
||||
register_code(KC_F22); //これは F22 を押したことを送信することを意味します
|
||||
f22_tracker++;
|
||||
register_code(keycode);
|
||||
return false;
|
||||
}
|
||||
break;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
void post_process_record_user(uint16_t keycode, keyrecord_t *record) {
|
||||
switch (keycode) {
|
||||
case KC_A ... KC_F21: // F22 をスキップする方法に注意してください
|
||||
case KC_F23 ... KC_EXSEL: //exsel は修飾キーの直前のキーです
|
||||
if (!record->event.pressed) {
|
||||
f22_tracker--;
|
||||
if (!f22_tracker) {
|
||||
unregister_code(KC_F22); //これは F22 を放したことを送信することを意味します
|
||||
}
|
||||
}
|
||||
break;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### タップ、ダウン、アップ
|
||||
|
||||
`Ctrl` あるいは `Home` など、ソースコードに文字列として表記できないキーをマクロで使うこともできます。
|
||||
以下のようにラップすることで任意のコードを送信することができます:
|
||||
|
||||
* `SS_TAP()` キーを押して放します。
|
||||
* `SS_DOWN()` キーを押します (ただし、放しません)。
|
||||
* `SS_UP()` キーを放します。
|
||||
|
||||
例えば:
|
||||
|
||||
SEND_STRING(SS_TAP(X_HOME));
|
||||
|
||||
`KC_HOME` をタップします - プリフィックスが `X_` で `KC_` ではないことに注意してください。以下のように、他の文字列と組み合わせることもできます:
|
||||
|
||||
SEND_STRING("VE"SS_TAP(X_HOME)"LO");
|
||||
|
||||
これは "VE" に続けて `KC_HOME` をタップ、そして "LO" (新しい行の場合は "LOVE" と綴る)を送信します。
|
||||
|
||||
文字列に遅延を追加することもできます:
|
||||
|
||||
* `SS_DELAY(msecs)` は指定されたミリ秒だけ遅らせます。
|
||||
|
||||
例えば:
|
||||
|
||||
SEND_STRING("VE" SS_DELAY(1000) SS_TAP(X_HOME) "LO");
|
||||
|
||||
これは "VE" 、1秒の遅延、`KC_HOME` をタップ、"LO" (新しい行の場合は "LOVE" と綴るが、中間に遅延がある) を送信します。
|
||||
|
||||
使用できるモッドショートカットもいくつかあります:
|
||||
|
||||
* `SS_LCTL(文字列)`
|
||||
* `SS_LSFT(文字列)`
|
||||
* `SS_LALT(文字列)`、`SS_LOPT(文字列)`
|
||||
* `SS_LGUI(文字列)`、`SS_LCMD(文字列)`、`SS_LWIN(文字列)`
|
||||
* `SS_RCTL(文字列)`
|
||||
* `SS_RSFT(文字列)`
|
||||
* `SS_RALT(文字列)`、`SS_ROPT(文字列)`、`SS_ALGR(文字列)`
|
||||
* `SS_RGUI(文字列)`、`SS_RCMD(文字列)`、`SS_RWIN(文字列)`
|
||||
|
||||
これらはそれぞれの修飾キーを押し、指定された文字列を送信してから、修飾キーを解放します。
|
||||
それらは以下のように使うことができます:
|
||||
|
||||
SEND_STRING(SS_LCTL("a"));
|
||||
|
||||
これは、左 Control +`a` (左 Control をダウンし、`a`、左 Control をアップ)を送信します - それらは文字列(例えば `"k"`)であり、`X_K` キーコードでは無いことに注意してください。
|
||||
|
||||
### 代替キーマップ
|
||||
|
||||
デフォルトでは、QWERTY レイアウトの US キーマップを想定しています; それを変更したい場合(例えば OS がソフトウェア Colemak を使う場合)、キーマップのどこかに以下を含めます:
|
||||
|
||||
```c
|
||||
#include "sendstring_colemak.h"
|
||||
```
|
||||
|
||||
### メモリ内の文字列
|
||||
|
||||
何らかの理由で文字列を操作していて、(リテラル、文字列定数の代わりに)生成したばかりのものを出力する必要がある場合は、以下のように `send_string()` を使うことができます:
|
||||
|
||||
```c
|
||||
char my_str[4] = "ok.";
|
||||
send_string(my_str);
|
||||
```
|
||||
|
||||
上で定義したショートカットは `send_string()` では動作しないですが、必要に応じて別の行に分けることができます:
|
||||
|
||||
```c
|
||||
char my_str[4] = "ok.";
|
||||
SEND_STRING("I said: ");
|
||||
send_string(my_str);
|
||||
SEND_STRING(".."SS_TAP(X_END));
|
||||
```
|
||||
|
||||
|
||||
## 高度なマクロ関数 :id=advanced-macro-functions
|
||||
|
||||
マクロの生成に役立つ関数が幾つかあります。マクロの中にかなり高度なコードを書くことができますが、機能が複雑になりすぎる場合は、代わりにカスタムキーコードを定義することをお勧めします。マクロはシンプルにしなければなりません。
|
||||
|
||||
?> 追加の機能として、[便利な関数](ja/ref_functions.md) の中で説明される関数を使うこともできます。例えば `reset_keyboard()` によりマクロの一部としてキーボードをリセットすることができます。
|
||||
|
||||
### `record->event.pressed`
|
||||
|
||||
これでスイッチが押されているか放されているかどうかをテストすることができます。以下が例です。
|
||||
|
||||
```c
|
||||
if (record->event.pressed) {
|
||||
// キーダウン時
|
||||
} else {
|
||||
// キーアップ時
|
||||
}
|
||||
```
|
||||
|
||||
### `register_code(<kc>);`
|
||||
|
||||
これはコンピュータに `<kc>` キーダウンイベントを送信します。例として `KC_ESC`、`KC_C`、`KC_4` や、`KC_LSFT` と `KC_LGUI` のような修飾キーなどもあります。
|
||||
|
||||
### `unregister_code(<kc>);`
|
||||
|
||||
`register_code` 関数と対応して、これは `<kc>` キーアップイベントをコンピュータに送信します。これを使わない場合、キーは送信されるまで押し続けられます。
|
||||
|
||||
### `tap_code(<kc>);`
|
||||
|
||||
これは `register_code(<kc>)` を送信し、その後 `unregister_code(<kc>)` を送信します。押下とリリースイベントの両方を送信する場合に便利です (押し続けるのではなく、キーを"タップ"する)。
|
||||
|
||||
タップの登録(解除)に問題がある場合、`config.h` ファイルで `#define TAP_CODE_DELAY 100` を設定することで、登録イベントと解除イベントの間に遅延を追加することができます。値はミリ秒です。
|
||||
|
||||
### `register_code16(<kc>);`、`unregister_code16(<kc>);`、`tap_code16(<kc>);`
|
||||
|
||||
これらの関数は対応する通常の関数と同様に機能しますが、修飾キーで修飾されたキーコードを使うことができます (Shift、Alt、Control、GUI を適用)。
|
||||
|
||||
例えば、修飾キーを押して(`register_code()`して)、キーコードを押す(`register_code()`する)代わりに、`register_code16(S(KC_5));` を使うことができます。
|
||||
|
||||
### `clear_keyboard();`
|
||||
|
||||
これは現在押されている全ての修飾キーとキーをクリアします。
|
||||
|
||||
### `clear_mods();`
|
||||
|
||||
これは現在押されている全ての修飾キーをクリアします。
|
||||
|
||||
### `clear_keyboard_but_mods();`
|
||||
|
||||
これは現在押されている修飾キー以外の全てのキーをクリアします。
|
||||
|
||||
## 高度な例:
|
||||
|
||||
### スーパー ALT↯TAB
|
||||
|
||||
このマクロは `KC_LALT` を登録し、`KC_TAB` をタップして、1000ms 待ちます。キーが再度タップされると、別の `KC_TAB` が送信されます; タップが無い場合、`KC_LALT` が登録解除され、ウィンドウを切り替えることができます。
|
||||
|
||||
```c
|
||||
bool is_alt_tab_active = false; // keymap.c の先頭付近にこれを追加します
|
||||
uint16_t alt_tab_timer = 0; // すぐにそれらを使います
|
||||
|
||||
enum custom_keycodes { // 素晴らしいキーコードを用意してください
|
||||
ALT_TAB = SAFE_RANGE,
|
||||
};
|
||||
|
||||
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
|
||||
switch (keycode) { // これはキーコードを利用したつまらない作業のほとんどを行います。
|
||||
case ALT_TAB:
|
||||
if (record->event.pressed) {
|
||||
if (!is_alt_tab_active) {
|
||||
is_alt_tab_active = true;
|
||||
register_code(KC_LALT);
|
||||
}
|
||||
alt_tab_timer = timer_read();
|
||||
register_code(KC_TAB);
|
||||
} else {
|
||||
unregister_code(KC_TAB);
|
||||
}
|
||||
break;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
void matrix_scan_user(void) { // とても重要なタイマー
|
||||
if (is_alt_tab_active) {
|
||||
if (timer_elapsed(alt_tab_timer) > 1000) {
|
||||
unregister_code(KC_LALT);
|
||||
is_alt_tab_active = false;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
@ -1,147 +0,0 @@
|
||||
# マウスキー
|
||||
|
||||
<!---
|
||||
original document: 0.9.44:docs/feature_mouse_keys.md
|
||||
git diff 0.9.44 HEAD -- docs/feature_mouse_keys.md | cat
|
||||
-->
|
||||
|
||||
マウスキーは、キーボードを使ってマウスをエミュレートできる機能です。様々な速度でポインタを移動し、5つのボタンを押し、8方向にスクロールすることができます。
|
||||
|
||||
## キーボードにマウスキーを追加
|
||||
|
||||
マウスキーを使うためには、少なくともマウスキーサポートを有効にし、マウスアクションをキーボードのキーにマップする必要があります。
|
||||
|
||||
### マウスキーを有効にする
|
||||
|
||||
マウスキーを有効にするには、キーマップの `rules.mk` に以下の行を追加します:
|
||||
|
||||
```c
|
||||
MOUSEKEY_ENABLE = yes
|
||||
```
|
||||
|
||||
### マウスアクションのマッピング
|
||||
|
||||
キーマップでキー押下をマウスアクションにマップするために、以下のキーコードを使うことができます:
|
||||
|
||||
| キー | エイリアス | 説明 |
|
||||
|----------------|---------|-----------------|
|
||||
| `KC_MS_UP` | `KC_MS_U` | カーソルを上に移動 |
|
||||
| `KC_MS_DOWN` | `KC_MS_D` | カーソルを下に移動 |
|
||||
| `KC_MS_LEFT` | `KC_MS_L` | カーソルを左に移動 |
|
||||
| `KC_MS_RIGHT` | `KC_MS_R` | カーソルを右に移動 |
|
||||
| `KC_MS_BTN1` | `KC_BTN1` | ボタン1を押す |
|
||||
| `KC_MS_BTN2` | `KC_BTN2` | ボタン2を押す |
|
||||
| `KC_MS_BTN3` | `KC_BTN3` | ボタン3を押す |
|
||||
| `KC_MS_BTN4` | `KC_BTN4` | ボタン4を押す |
|
||||
| `KC_MS_BTN5` | `KC_BTN5` | ボタン5を押す |
|
||||
| `KC_MS_BTN6` | `KC_BTN6` | ボタン6を押す |
|
||||
| `KC_MS_BTN7` | `KC_BTN7` | ボタン7を押す |
|
||||
| `KC_MS_BTN8` | `KC_BTN8` | ボタン8を押す |
|
||||
| `KC_MS_WH_UP` | `KC_WH_U` | ホイールを向こう側に回転 |
|
||||
| `KC_MS_WH_DOWN` | `KC_WH_D` | ホイールを手前側に回転 |
|
||||
| `KC_MS_WH_LEFT` | `KC_WH_L` | ホイールを左に倒す |
|
||||
| `KC_MS_WH_RIGHT` | `KC_WH_R` | ホイールを右に倒す |
|
||||
| `KC_MS_ACCEL0` | `KC_ACL0` | 速度を0に設定 |
|
||||
| `KC_MS_ACCEL1` | `KC_ACL1` | 速度を1に設定 |
|
||||
| `KC_MS_ACCEL2` | `KC_ACL2` | 速度を2に設定 |
|
||||
|
||||
## マウスキーの設定
|
||||
|
||||
マウスキーはカーソルを移動するための3つの異なるモードをサポートします:
|
||||
|
||||
* **加速 (デフォルト):** 移動キーを押したままにすると、カーソルが最大速度に達するまでカーソルを加速します。
|
||||
* **定速:** 移動キーを押したままにすると、カーソルを一定の速度で移動します。
|
||||
* **混合:** 移動キーを押したままにすると、カーソルが最大速度に達するまでカーソルを加速し、加速キーと移動キーを同時に押すとカーソルは一定の速度で移動します。
|
||||
|
||||
同じ原則がスクロールにも適用されます。
|
||||
|
||||
時間、間隔、遅延の設定オプションは、ミリ秒で指定されます。スクロール速度はデフォルトスクロールステップの倍数として渡されます。例えば、スクロール速度8は、各スクロールアクションがオペレーティングシステムまたはアプリケーションで定義されるデフォルトのスクロールステップの8倍の距離進むことを意味します。
|
||||
|
||||
### 加速モード
|
||||
|
||||
これはデフォルトのモードです。キーマップの `config.h` ファイルの以下の設定を使ってカーソルとスクロールの加速を調整することができます:
|
||||
|
||||
| 定義 | デフォルト | 説明 |
|
||||
|----------------------------|-------|---------------------------------------------------------|
|
||||
| `MOUSEKEY_DELAY` | 300 | 移動キーを押してからカーソルが移動するまでの遅延 |
|
||||
| `MOUSEKEY_INTERVAL` | 50 | カーソル移動間の時間 |
|
||||
| `MOUSEKEY_MAX_SPEED` | 10 | 加速が停止する最大のカーソル速度 |
|
||||
| `MOUSEKEY_TIME_TO_MAX` | 20 | 最大カーソル速度に達するまでの時間 |
|
||||
| `MOUSEKEY_WHEEL_DELAY` | 300 | ホイールキーを押してからホイールが動くまでの遅延 |
|
||||
| `MOUSEKEY_WHEEL_INTERVAL` | 100 | ホイールの動きの間の時間 |
|
||||
| `MOUSEKEY_WHEEL_MAX_SPEED` | 8 | スクロールアクションごとのスクロールステップの最大数 |
|
||||
| `MOUSEKEY_WHEEL_TIME_TO_MAX` | 40 | 最大スクロール速度に達するまでの時間 |
|
||||
|
||||
ヒント:
|
||||
|
||||
* `MOUSEKEY_DELAY` の設定が低すぎるとカーソルが応答しなくなります。設定が高すぎると小さな動きが難しくなります。
|
||||
* カーソルの動きをスムーズにするには、`MOUSEKEY_INTERVAL` の値を低くします。ディスプレイのリフレッシュレートが60Hzの場合、`16` (1/60) に設定することができます。これによりカーソルの速度が大幅に向上するため、`MOUSEKEY_MAX_SPEED` を下げた方が良いかもしれません。
|
||||
* `MOUSEKEY_TIME_TO_MAX` または `MOUSEKEY_WHEEL_TIME_TO_MAX` を `0` に設定すると、それぞれカーソルの速度またはスクロールの加速が無効になります。この方法では、一方を加速しながら他方を一定にすることができますが、これは定速モードでは不可能です。
|
||||
* `MOUSEKEY_WHEEL_INTERVAL` の設定が低すぎるとスクロールがとても速くなります。設定が高すぎるとホイールキーを押したままにした時にスクロールがとても遅くなります
|
||||
|
||||
カーソルの加速は、X Window System MouseKeysAccel 機能と同じアルゴリズムを使います。詳細については [Wikipedia](https://en.wikipedia.org/wiki/Mouse_keys) をご覧ください。
|
||||
|
||||
### 定速モード
|
||||
|
||||
このモードでは、カーソルおよびマウスホイールの両方について複数の異なる速度を定義することができます。加速はありません。`KC_ACL0`、`KC_ACL1` および `KC_ACL2` は、カーソルとスクロールの速度をそれぞれの設定に変更します。
|
||||
|
||||
速度の選択は、一時的とタップ選択のどちらかを選べます:
|
||||
|
||||
* **一時的:** 選択された速度は、それぞれのキーを押している間のみアクティブになります。キーを放すと、マウスキーは変更される前の速度に戻ります。
|
||||
* **タップ選択:** それぞれのキーを押すと選択された速度がアクティブになり、キーを放した後もアクティブのままになります。デフォルトの速度は `KC_ACL1` です。未変更の速度はありません。
|
||||
|
||||
最も遅い速度から最も速い速度までのデフォルトの速度は以下の通りです:
|
||||
|
||||
* **一時的:** `KC_ACL0` < `KC_ACL1` < *変更無し* < `KC_ACL2`
|
||||
* **タップ選択:** `KC_ACL0` < `KC_ACL1` < `KC_ACL2`
|
||||
|
||||
定速モードを使うには、少なくともキーマップの keymaps ディレクトリの `config.h` ファイルに `MK_3_SPEED` を定義する必要があります。
|
||||
|
||||
```c
|
||||
#define MK_3_SPEED
|
||||
```
|
||||
|
||||
一時的モードを有効にするには、`MK_MOMENTARY_ACCEL` も定義します:
|
||||
|
||||
```c
|
||||
#define MK_MOMENTARY_ACCEL
|
||||
```
|
||||
|
||||
カーソル移動あるいはスクロールを調整する場合は、以下の設定を使います:
|
||||
|
||||
| 定義 | デフォルト | 説明 |
|
||||
|---------------------|-------------|-------------------------------------------|
|
||||
| `MK_3_SPEED` | *定義なし* | 定速カーソルを有効にする |
|
||||
| `MK_MOMENTARY_ACCEL` | *定義なし* | 一時的モードを有効にする |
|
||||
| `MK_C_OFFSET_UNMOD` | 16 | 移動ごとのカーソルオフセット (変更無し) |
|
||||
| `MK_C_INTERVAL_UNMOD` | 16 | カーソルの移動間の時間 (変更無し) |
|
||||
| `MK_C_OFFSET_0` | 1 | 移動ごとのカーソルオフセット (`KC_ACL0`) |
|
||||
| `MK_C_INTERVAL_0` | 32 | カーソル移動間の時間 (`KC_ACL0`) |
|
||||
| `MK_C_OFFSET_1` | 4 | 移動ごとのカーソルオフセット (`KC_ACL1`) |
|
||||
| `MK_C_INTERVAL_1` | 16 | カーソル移動間の時間 (`KC_ACL1`) |
|
||||
| `MK_C_OFFSET_2` | 32 | 移動ごとのカーソルオフセット (`KC_ACL2`) |
|
||||
| `MK_C_INTERVAL_2` | 16 | カーソル移動間の時間 (`KC_ACL2`) |
|
||||
| `MK_W_OFFSET_UNMOD` | 1 | スクロールアクションごとのスクロールステップ (変更無し) |
|
||||
| `MK_W_INTERVAL_UNMOD` | 40 | スクロールステップ間の時間 (変更無し) |
|
||||
| `MK_W_OFFSET_0` | 1 | スクロールアクションごとのスクロールステップ (`KC_ACL0`) |
|
||||
| `MK_W_INTERVAL_0` | 360 | スクロールステップ間の時間 (`KC_ACL0`) |
|
||||
| `MK_W_OFFSET_1` | 1 | スクロールアクションごとのスクロールステップ (`KC_ACL1`) |
|
||||
| `MK_W_INTERVAL_1` | 120 | スクロールステップ間の時間 (`KC_ACL1`) |
|
||||
| `MK_W_OFFSET_2` | 1 | スクロールアクションごとのスクロールステップ (`KC_ACL2`) |
|
||||
| `MK_W_INTERVAL_2` | 20 | スクロールステップ間の時間 (`KC_ACL2`) |
|
||||
|
||||
### 混合モード
|
||||
|
||||
このモードは **加速** モードのように機能しますが、`KC_ACL0`、`KC_ACL1`、`KC_ACL2` を押したままにすることで
|
||||
一時的(押している間)にカーソルとスクロール速度を定速に設定できます。
|
||||
加速キーが押されていない場合、このモードは **加速** モードと同じで、関連する全ての設定を使って変更できます。
|
||||
|
||||
* **KC_ACL0:** この加速はカーソルをできるだけ遅い速度に設定します。これはカーソルを非常に小さく詳細に移動する場合に便利です。
|
||||
* **KC_ACL1:** この加速はカーソルを最大(ユーザ定義)速度の半分に設定します。
|
||||
* **KC_ACL2:** この加速はカーソルを最大(コンピュータ定義)速度に設定します。これは、正確性を多少犠牲にしてカーソルを大きく移動する場合に便利です。
|
||||
|
||||
混合モードを使うには、キーマップの `config.h` ファイルに少なくとも `MK_COMBINED` を定義しなければなりません:
|
||||
|
||||
```c
|
||||
#define MK_COMBINED
|
||||
```
|
||||
@ -1,58 +0,0 @@
|
||||
# ポインティングデバイス :id=pointing-device
|
||||
|
||||
<!---
|
||||
original document: 0.12.41:docs/feature_pointing_device.md
|
||||
git diff 0.12.41 HEAD -- docs/feature_pointing_device.md | cat
|
||||
-->
|
||||
|
||||
ポインティングデバイスは汎用的な機能の総称です: システムポインタを移動します。マウスキーのような他のオプションも確かにありますが、これは簡単に変更可能で軽量であることを目指しています。機能を制御するためにカスタムキーを実装したり、他の周辺機器から情報を収集してここに直接挿入したりできます - QMK に処理を任せてください。
|
||||
|
||||
ポインティングデバイスを有効にするには、rules.mk の以下の行のコメントを解除します:
|
||||
|
||||
```makefile
|
||||
POINTING_DEVICE_ENABLE = yes
|
||||
```
|
||||
|
||||
マウスレポートを操作するために、以下の関数を使うことができます:
|
||||
|
||||
* `pointing_device_get_report()` - ホストコンピュータに送信された情報を表す現在の report_mouse_t を返します。
|
||||
* `pointing_device_set_report(report_mouse_t mouse_report)` - ホストコンピュータに送信される report_mouse_t を上書き保存します。
|
||||
|
||||
report_mouse_t (ここでは "mouseReport") が以下のプロパティを持つことを覚えておいてください:
|
||||
|
||||
* `mouseReport.x` - これは、x軸の動き(+ 右へ、- 左へ)を表す -127 から 127 (128ではなく、USB HID 仕様で定義されています)の符号付き整数です。
|
||||
* `mouseReport.y` - これは、y軸の動き(+ 上へ、- 下へ)を表す -127 から 127 (128ではなく、USB HID 仕様で定義されています)の符号付き整数です。
|
||||
* `mouseReport.v` - これは、垂直スクロール(+ 上へ、- 下へ)を表す -127 から 127 (128ではなく、USB HID 仕様で定義されています)の符号付き整数です。
|
||||
* `mouseReport.h` - これは、水平スクロール(+ 右へ、- 左へ)を表す -127 から 127 (128ではなく、USB HID 仕様で定義されています)の符号付き整数です。
|
||||
* `mouseReport.buttons` - これは uint8_t で、8ビット全てを使っています。これらのビットはマウスボタンの状態を表します - ビット 0 はマウスボタン 1、ビット 7 はマウスボタン 8 です。
|
||||
|
||||
マウスレポートに必要な変更を行ったら、それを送信する必要があります:
|
||||
|
||||
* `pointing_device_send()` - マウスレポートをホストに送信し、レポートをゼロにします。
|
||||
|
||||
マウスレポートが送信されると、x、y、v、h のいずれの値も 0 に設定されます (これは `pointing_device_send()` で行われます。この挙動を回避するためにオーバーライドすることができます)。このように、ボタンの状態は持続しますが、動きは1度だけ起こります。さらにカスタマイズするために、`pointing_device_init` と `pointing_device_task` のどちらもオーバーライドすることができます。
|
||||
|
||||
さらに、デフォルトでは、`pointing_device_send()` はレポートが実際に変更された場合のみレポートを送信します。これにより、マウスレポートが継続的に送信されてホストシステムが起動されたままになることを防ぎます。この動作は、独自の `pointing_device_send()` 関数を作成することで変更できます。
|
||||
|
||||
また、`has_mouse_report_changed(new_report, old_report)` 関数を使って、レポートが変更されたかどうかを確認できます。(訳注：独自の `pointing_device_send()` 関数を作成する場合でも、その中で `has_mouse_report_changed(new_report, old_report)` 関数でチェックして、デフォルトの `pointing_device_send()` と類似の無駄なレポートの抑制をして、ホストシステムがスリープ状態に入れる余地を残すようにしておくのが良いでしょう。)
|
||||
|
||||
以下の例では、カスタムキーを使ってマウスをクリックし垂直および水平方向に127単位スクロールし、リリースされた時にそれを全て元に戻します - なぜならこれは完全に便利な機能だからです。いいですか、以下はひとつの例です:
|
||||
|
||||
```c
|
||||
case MS_SPECIAL:
|
||||
report_mouse_t currentReport = pointing_device_get_report();
|
||||
if (record->event.pressed) {
|
||||
currentReport.v = 127;
|
||||
currentReport.h = 127;
|
||||
currentReport.buttons |= MOUSE_BTN1; // this is defined in report.h
|
||||
} else {
|
||||
currentReport.v = -127;
|
||||
currentReport.h = -127;
|
||||
currentReport.buttons &= ~MOUSE_BTN1;
|
||||
}
|
||||
pointing_device_set_report(currentReport);
|
||||
pointing_device_send();
|
||||
break;
|
||||
```
|
||||
|
||||
マウスレポートは送信されるたびに 0 (ボタンを除く)に設定されることを思い出してください。そのため、スクロールはそれぞれの場合に1度だけ発生します。
|
||||
@ -1,288 +0,0 @@
|
||||
# PS/2 マウスサポート :id=ps2-mouse-support
|
||||
|
||||
<!---
|
||||
original document: 0.13.17:docs/feature_ps2_mouse.md
|
||||
git diff 0.13.17 HEAD -- docs/feature_ps2_mouse.md | cat
|
||||
-->
|
||||
|
||||
PS/2 マウス (例えばタッチパッドあるいはトラックポイント)を複合デバイスとしてキーボードに接続することができます。
|
||||
|
||||
トラックポイントを接続するには、トラックポイントモジュールを入手し (つまり、Thinkpad キーボードから部品を取って)、モジュールの各ピンの機能を特定し、コントローラとトラックポイントモジュールの間に必要な回路を作成する必要があります。詳細については、Deskthority Wiki の[トラックポイントハードウェア](https://deskthority.net/wiki/TrackPoint_Hardware)ページを参照してください。
|
||||
|
||||
PS/2 デバイスの接続は、USART(最善)、割り込み(次善)、 または busywait(非推奨)の3つのやり方が有ります。
|
||||
|
||||
## トラックポイントとコントローラ間の回路 :id=the-circuitry-between-trackpoint-and-controller
|
||||
|
||||
動作させるには、DATA と CLK のふたつのラインを 4.7k の抵抗で 5V にプルアップしてやる必要があります。
|
||||
|
||||
```
|
||||
DATA ----------+--------- PIN
|
||||
|
|
||||
4.7K
|
||||
|
|
||||
MODULE 5+ --------+--+--------- PWR CONTROLLER
|
||||
|
|
||||
4.7K
|
||||
|
|
||||
CLK ------+------------ PIN
|
||||
```
|
||||
|
||||
|
||||
## Busywait バージョン :id=busywait-version
|
||||
|
||||
注意: これは非推奨です。ギクシャクした動きや、未送信の入力が発生するかもしれません。可能であれば、割り込みまたは USART バージョンを使ってください。
|
||||
|
||||
rules.mk で:
|
||||
|
||||
```makefile
|
||||
PS2_MOUSE_ENABLE = yes
|
||||
PS2_ENABLE = yes
|
||||
PS2_DRIVER = busywait
|
||||
```
|
||||
|
||||
キーボードの config.h で:
|
||||
|
||||
```c
|
||||
#ifdef PS2_DRIVER_BUSYWAIT
|
||||
# define PS2_CLOCK_PIN D1
|
||||
# define PS2_DATA_PIN D2
|
||||
#endif
|
||||
```
|
||||
|
||||
## 割り込みバージョン :id=interrupt-version
|
||||
|
||||
以下の例はクロックのために D2 を、データのために D5 を使います。クロックには任意の INT あるいは PCINT ピンを、データには任意のピンを使うことができます。
|
||||
|
||||
rules.mk で:
|
||||
|
||||
```makefile
|
||||
PS2_MOUSE_ENABLE = yes
|
||||
PS2_ENABLE = yes
|
||||
PS2_DRIVER = interrupt
|
||||
```
|
||||
|
||||
キーボードの config.h で:
|
||||
|
||||
```c
|
||||
#ifdef PS2_DRIVER_INTERRUPT
|
||||
#define PS2_CLOCK_PIN D2
|
||||
#define PS2_DATA_PIN D5
|
||||
|
||||
#define PS2_INT_INIT() do { \
|
||||
EICRA |= ((1<<ISC21) | \
|
||||
(0<<ISC20)); \
|
||||
} while (0)
|
||||
#define PS2_INT_ON() do { \
|
||||
EIMSK |= (1<<INT2); \
|
||||
} while (0)
|
||||
#define PS2_INT_OFF() do { \
|
||||
EIMSK &= ~(1<<INT2); \
|
||||
} while (0)
|
||||
#define PS2_INT_VECT INT2_vect
|
||||
#endif
|
||||
```
|
||||
|
||||
## USART バージョン :id=usart-version
|
||||
|
||||
ATMega32u4 で USART を使うには、クロックのために PD5 を、データのために PD2 を使う必要があります。それらのいずれかが利用できない場合は、割り込みバージョンを使う必要があります。
|
||||
|
||||
rules.mk で:
|
||||
|
||||
```makefile
|
||||
PS2_MOUSE_ENABLE = yes
|
||||
PS2_ENABLE = yes
|
||||
PS2_DRIVER = usart
|
||||
```
|
||||
|
||||
キーボードの config.h で:
|
||||
|
||||
```c
|
||||
#ifdef PS2_DRIVER_USART
|
||||
#define PS2_CLOCK_PIN D5
|
||||
#define PS2_DATA_PIN D2
|
||||
|
||||
/* 同期、奇数パリティ、1-bit ストップ、8-bit データ、立ち下がりエッジでサンプル */
|
||||
/* CLOCK の DDR を入力としてスレーブに設定 */
|
||||
#define PS2_USART_INIT() do { \
|
||||
PS2_CLOCK_DDR &= ~(1<<PS2_CLOCK_BIT); \
|
||||
PS2_DATA_DDR &= ~(1<<PS2_DATA_BIT); \
|
||||
UCSR1C = ((1 << UMSEL10) | \
|
||||
(3 << UPM10) | \
|
||||
(0 << USBS1) | \
|
||||
(3 << UCSZ10) | \
|
||||
(0 << UCPOL1)); \
|
||||
UCSR1A = 0; \
|
||||
UBRR1H = 0; \
|
||||
UBRR1L = 0; \
|
||||
} while (0)
|
||||
#define PS2_USART_RX_INT_ON() do { \
|
||||
UCSR1B = ((1 << RXCIE1) | \
|
||||
(1 << RXEN1)); \
|
||||
} while (0)
|
||||
#define PS2_USART_RX_POLL_ON() do { \
|
||||
UCSR1B = (1 << RXEN1); \
|
||||
} while (0)
|
||||
#define PS2_USART_OFF() do { \
|
||||
UCSR1C = 0; \
|
||||
UCSR1B &= ~((1 << RXEN1) | \
|
||||
(1 << TXEN1)); \
|
||||
} while (0)
|
||||
#define PS2_USART_RX_READY (UCSR1A & (1<<RXC1))
|
||||
#define PS2_USART_RX_DATA UDR1
|
||||
#define PS2_USART_ERROR (UCSR1A & ((1<<FE1) | (1<<DOR1) | (1<<UPE1)))
|
||||
#define PS2_USART_RX_VECT USART1_RX_vect
|
||||
#endif
|
||||
```
|
||||
|
||||
## 追加の設定 :id=additional-settings
|
||||
|
||||
### PS/2 マウス機能 :id=ps2-mouse-features
|
||||
|
||||
以下の PS/2 マウスプロトコルによってサポートされる設定を有効にします。
|
||||
|
||||
```c
|
||||
/* デフォルトのストリームモードの代わりにリモートモードを使います (リンクを見てください) */
|
||||
#define PS2_MOUSE_USE_REMOTE_MODE
|
||||
|
||||
/* マウスあるいはタッチパッドでスクロールホイールあるいはスクロールジェスチャーを有効にします */
|
||||
#define PS2_MOUSE_ENABLE_SCROLLING
|
||||
|
||||
/* 一部のマウスでは、スクロールマスクを設定する必要があります。デフォルトは 0xFF です。*/
|
||||
#define PS2_MOUSE_SCROLL_MASK 0x0F
|
||||
|
||||
/* ホストに送信する前に、動きに変換を適用します (リンクを見てください) */
|
||||
#define PS2_MOUSE_USE_2_1_SCALING
|
||||
|
||||
/* ps2ホストを初期化した後の待機時間 */
|
||||
#define PS2_MOUSE_INIT_DELAY 1000 /* Default */
|
||||
```
|
||||
|
||||
ps2_mouse.h をインクルードして、以下の関数を呼び出すこともできます。
|
||||
|
||||
```c
|
||||
void ps2_mouse_disable_data_reporting(void);
|
||||
|
||||
void ps2_mouse_enable_data_reporting(void);
|
||||
|
||||
void ps2_mouse_set_remote_mode(void);
|
||||
|
||||
void ps2_mouse_set_stream_mode(void);
|
||||
|
||||
void ps2_mouse_set_scaling_2_1(void);
|
||||
|
||||
void ps2_mouse_set_scaling_1_1(void);
|
||||
|
||||
void ps2_mouse_set_resolution(ps2_mouse_resolution_t resolution);
|
||||
|
||||
void ps2_mouse_set_sample_rate(ps2_mouse_sample_rate_t sample_rate);
|
||||
```
|
||||
|
||||
### 細かい調整 :id=fine-control
|
||||
|
||||
マウスの感度と速度を変更するには以下の定義を使います。
|
||||
注意: 同じ効果のために `ps2_mouse_set_resolution` も使うことができます (ほとんどのタッチパッドではサポートされません)。
|
||||
|
||||
```c
|
||||
#define PS2_MOUSE_X_MULTIPLIER 3
|
||||
#define PS2_MOUSE_Y_MULTIPLIER 3
|
||||
#define PS2_MOUSE_V_MULTIPLIER 1
|
||||
```
|
||||
|
||||
### スクロールボタン :id=scroll-button
|
||||
|
||||
トラックポイントを使っている場合は、スクロールのためにそれを使えるようにしたいでしょう。
|
||||
押された時にマウスを移動させる代わりにスクロールさせる「スクロールボタン」を有効にすることができます。
|
||||
この機能を有効にするには、以下のようにスクロールボタンマスクを設定する必要があります:
|
||||
|
||||
```c
|
||||
#define PS2_MOUSE_SCROLL_BTN_MASK (1<<PS2_MOUSE_BTN_MIDDLE) /* Default */
|
||||
```
|
||||
|
||||
スクロールボタン機能を無効にするには:
|
||||
|
||||
```c
|
||||
#define PS2_MOUSE_SCROLL_BTN_MASK 0
|
||||
```
|
||||
|
||||
利用可能なボタンは:
|
||||
|
||||
```c
|
||||
#define PS2_MOUSE_BTN_LEFT 0
|
||||
#define PS2_MOUSE_BTN_RIGHT 1
|
||||
#define PS2_MOUSE_BTN_MIDDLE 2
|
||||
```
|
||||
|
||||
ボタン定数を `|` で結合したマスクでボタンを組み合わせることができます。
|
||||
|
||||
スクロールボタンマスクを設定したら、スクロールボタンの送信間隔を設定する必要があります。
|
||||
これは、スクロールボタンが離された場合に、スクロールボタンがホストに送信されるまでの間隔です。
|
||||
この時間が経過すると、マウスはスクロールして送信されなくなります。
|
||||
|
||||
```c
|
||||
#define PS2_MOUSE_SCROLL_BTN_SEND 300 /* Default */
|
||||
```
|
||||
|
||||
スクロールボタンの送信を無効にするには:
|
||||
|
||||
```c
|
||||
#define PS2_MOUSE_SCROLL_BTN_SEND 0
|
||||
```
|
||||
|
||||
以下の定義でスクロールの細かい制御がサポートされます:
|
||||
|
||||
```c
|
||||
#define PS2_MOUSE_SCROLL_DIVISOR_H 2
|
||||
#define PS2_MOUSE_SCROLL_DIVISOR_V 2
|
||||
```
|
||||
|
||||
### マウスとスクロールの軸の反転 :id=invert-mouse-and-scroll-axes
|
||||
|
||||
X 軸と Y 軸を反転するには、以下を config.h に配置します:
|
||||
|
||||
```c
|
||||
#define PS2_MOUSE_INVERT_X
|
||||
#define PS2_MOUSE_INVERT_Y
|
||||
```
|
||||
|
||||
スクロールの軸を逆にするには、以下を config.h に配置します:
|
||||
|
||||
```c
|
||||
#define PS2_MOUSE_INVERT_H
|
||||
#define PS2_MOUSE_INVERT_V
|
||||
```
|
||||
|
||||
### マウスの軸の回転 :id=rotate-mouse-axes
|
||||
|
||||
デバイスの出力を時計回りに 90 か 180 か 270 度変換します。
|
||||
|
||||
デバイスの向きを補正する場合は、出力を逆の方向に同じ量だけ回転します。例えば、通常のデバイスの向きが北向きの場合、以下のように補正します:
|
||||
|
||||
```c
|
||||
#define PS2_MOUSE_ROTATE 270 /* 東向きのデバイスの向きの補正*/
|
||||
```
|
||||
```c
|
||||
#define PS2_MOUSE_ROTATE 180 /* 南向きのデバイスの向きの補正*/
|
||||
```
|
||||
```c
|
||||
#define PS2_MOUSE_ROTATE 90 /* 西向きのデバイスの向きの補正*/
|
||||
```
|
||||
|
||||
### デバッグ設定 :id=debug-settings
|
||||
|
||||
マウスをデバッグするには、`debug_mouse = true` を追加するか、ブートマジックを使って有効にします。
|
||||
|
||||
```c
|
||||
/* マウスレポートをデバッグするには */
|
||||
#define PS2_MOUSE_DEBUG_HID
|
||||
#define PS2_MOUSE_DEBUG_RAW
|
||||
```
|
||||
|
||||
### 動作フック :id=movement-hook
|
||||
|
||||
ホストに送信される前にキーマップでマウスの動作を処理します。使用例として、
|
||||
ノイズのフィルタリング、加速の追加、レイヤーの自動アクティブ化が含まれます。
|
||||
使用するには、キーマップで次の関数を定義します:
|
||||
|
||||
```c
|
||||
void ps2_mouse_moved_user(report_mouse_t *mouse_report);
|
||||
```
|
||||
@ -1,74 +0,0 @@
|
||||
# Raw HID
|
||||
|
||||
<!---
|
||||
original document: 0.12.41:docs/feature_rawhid.md
|
||||
git diff 0.12.41 HEAD -- docs/feature_rawhid.md | cat
|
||||
-->
|
||||
|
||||
Raw HID は、HID インタフェースを介して QMK とホストコンピュータ間の双方向通信を可能にします。これには、キーマップをその場で切り替えたり、RGB LED の色とモードを変更したりなど、多くの潜在的な使用方法があります。
|
||||
|
||||
キーボードで raw HID を機能させるには、2つの主要なコンポーネントがあります。
|
||||
|
||||
## キーボードファームウェア
|
||||
|
||||
ファームウェアの実装はとても簡単です。
|
||||
`rules.mk` に以下を追加します:
|
||||
|
||||
```make
|
||||
RAW_ENABLE = yes
|
||||
```
|
||||
|
||||
`keymap.c` に `"raw_hid.h"` を include し、以下を実装します:
|
||||
|
||||
```C
|
||||
void raw_hid_receive(uint8_t *data, uint8_t length) {
|
||||
// ここにコードを書きます。data はホストから受信したパケットです。
|
||||
}
|
||||
```
|
||||
|
||||
`"raw_hid.h"` ヘッダは、キーボードからホストにパケットを送信できる `void raw_hid_send(uint8_t *data, uint8_t length);` も宣言します。例として、全てのデータをホストに返すことで、ホストアプリケーションを構築する時のデバッグに使うこともできます。
|
||||
|
||||
```C
|
||||
void raw_hid_receive(uint8_t *data, uint8_t length) {
|
||||
raw_hid_send(data, length);
|
||||
}
|
||||
```
|
||||
|
||||
これら2つの関数は、ホストとの間で長さ `RAW_EPSIZE` バイトのパケットを送受信します (LUFA/ChibiOS/V-USB では 32、ATSAM では 64)。
|
||||
|
||||
ホスト側での作業を進める前に、raw 対応のファームウェアを書き込むようにしてください。
|
||||
|
||||
## ホスト (Windows/macOS/Linux)
|
||||
|
||||
これは幾つかの掘り下げが必要になるため、より複雑な部分です。
|
||||
|
||||
ホストコンピュータを raw HID を使ってキーボードに接続するには、キーボードについての4つの情報が必要です。
|
||||
|
||||
1. Vendor ID
|
||||
2. Product ID
|
||||
3. Usage Page
|
||||
4. Usage
|
||||
|
||||
前半の2つは、キーボードのメインディレクトリにあるキーボードの `config.h` で、`VENDOR_ID` と `PRODUCT_ID` で簡単に見つかります。
|
||||
|
||||
後半の2つは、キーボードのメインディレクトリにあるキーボードの `config.h` で、値を再定義することで上書きすることができます: `#define RAW_USAGE_PAGE 0xFF60` と `#define RAW_USAGE_ID 0x61`。
|
||||
|
||||
デフォルトでは、**Usage Page** は `0xFF60` で、**Usage** は `0x61` です。
|
||||
|
||||
### ホストの構築
|
||||
|
||||
独自に作成したくない場合は、利用可能な HID 実装ライブラリがある任意の言語を使ってホストを構築することができます。人気のある言語でよく使われるライブラリは以下の通りです:
|
||||
|
||||
* Node: [node-hid](https://github.com/node-hid/node-hid)。
|
||||
* C: [hidapi](https://github.com/libusb/hidapi)。
|
||||
* Java: [purejavahidapi](https://github.com/nyholku/purejavahidapi) と [hid4java](https://github.com/gary-rowe/hid4java)。
|
||||
* Python: [pyhidapi](https://pypi.org/project/hid/)。
|
||||
|
||||
これは完全なクロスプラットフォームのリストではありませんが、最初に始めるのに十分なはずです。raw HID を使うための特別な要件は無いため、どの HID ライブラリでも動作するはずです。
|
||||
|
||||
これで、キーボードへの HID インタフェースを開くために必要な4つの情報全てが揃いました。必要なのは、ライブラリの利用可能な関数を使って ID パラメータを使ってデバイスを開くことだけです。
|
||||
|
||||
Vendor ID と Product ID はデバイスを開くために実際には必要ないことに注意してください。それらは接続した多くの HID デバイスから特定のデバイスをフィルターするためだけに使われます。多くのライブラリでは、代わりに製品名と製造元名を使ってデバイスを開くオプションがあります。`node-hid` が代表的な例です。これは USB ハブが組み込まれているデバイスや、同じ製品名または同じ製造元の複数のインタフェースがある特別な HID インタフェースで問題になります。Product ID と Vendor ID を合わせると単一のインタフェースの固有名を作成できるため、この問題を防げます。したがって、ライブラリで必要が無い場合でも、この問題を防ぐためにそれらを使うことをお勧めします。
|
||||
ただし、Vendor ID や Product ID と異なり、Usage Page と Usage は通信を成功させるために必要です。
|
||||
|
||||
言うまでもなく、使っているライブラリに関係なく、終了したらインタフェースを必ず閉じる必要があります。オペレーティングシステムと特定の環境によっては、明示的に接続が閉じられていない場合、後で他のクライアントまたは同じクライアントの他のインスタンスに接続しなおした時に問題が発生する可能性があります。
|
||||
@ -1,251 +0,0 @@
|
||||
# 分割キーボード
|
||||
|
||||
<!---
|
||||
original document:0.10.8:docs/feature_split_keyboard.md
|
||||
git diff 0.10.8 HEAD -- docs/feature_split_keyboard.md | cat
|
||||
-->
|
||||
|
||||
QMK ファームウェアリポジトリの多くのキーボードは、"分割"キーボードです。それらは2つのコントローラを使います — 1つは USB に接続し、もう1つは TRRS または同様のケーブルを介してシリアルまたは I<sup>2</sup>C 接続で接続します。
|
||||
|
||||
分割キーボードには多くの利点がありますが、有効にするには追加の作業が必要です。
|
||||
|
||||
QMK ファームウェアには、任意のキーボードで使用可能な一般的な実装と、多くのキーボード固有の実装があります。
|
||||
|
||||
このため、主に Let's Split とその他のキーボードで使われる一般的な実装について説明します。
|
||||
|
||||
!> ARM はまだ完全には分割キーボードをサポートしておらず、様々な制限があります。進捗はしていますが、機能の100%にはまだ達していません。
|
||||
|
||||
|
||||
## 互換性の概要
|
||||
|
||||
| Transport | AVR | ARM |
|
||||
|------------------------------|--------------------|--------------------|
|
||||
| ['serial'](ja/serial_driver.md) | :heavy_check_mark: | :white_check_mark: <sup>1</sup> |
|
||||
| I2C | :heavy_check_mark: | |
|
||||
|
||||
注意:
|
||||
|
||||
1. ハードウェアとソフトウェアの両方の制限は、[ドライバーのドキュメント](ja/serial_driver.md)の中で説明されます。
|
||||
|
||||
## ハードウェア設定
|
||||
|
||||
2つの Pro Micro 互換のコントローラを使っており、キーボードの左右を接続するために TRRS ジャックを使っていることを前提とします。
|
||||
|
||||
### ハードウェア要件
|
||||
|
||||
左右それぞれのキーボードマトリックスのためのダイオードとスイッチとは別に、2個の TRRS ソケットと 1本の TRRS ケーブルが必要です。
|
||||
|
||||
あるいは、少なくとも3本のワイヤがあるケーブルとソケットを使うことができます。
|
||||
|
||||
キーボードの左右間で通信するために I<sup>2</sup>C を使いたい場合は、少なくとも4本のワイヤを備えたケーブルと 2個の 4.7kΩ プルアップ抵抗が必要です。
|
||||
|
||||
#### 考慮事項
|
||||
|
||||
最も一般的に使われる接続は、TRRS ケーブルとジャックです。これらは4本のワイヤを提供し、分割キーボードに非常に有用で、簡単に見つけることができます。
|
||||
|
||||
ただし、ワイヤのうちの1本が Vcc を供給するため、キーボードはホットプラグ不可能です。TRRS ケーブルを抜き差しする前に、必ずキーボードのUSB接続をはずす必要があります。そうしなければ、コントローラを短絡させたり、もっと悪いことが起こるかもしれません。
|
||||
|
||||
別のオプションは電話ケーブルを使うことです (例えば、旧式の RJ-11/RJ-14 ケーブル)。実際に4本のワイヤ/レーンをサポートするものを使うようにしてください。
|
||||
|
||||
ただし、USB ケーブル、SATA ケーブル、そして単に4本の電線でもコントローラ間の通信に使用できることがわかっています。
|
||||
|
||||
!> コントローラ間の通信に USB ケーブルを使っても問題ありませんが、コネクタは通常の USB 接続と間違えられるかもしれず、配線方法によってはキーボードが短絡する可能性があります。このため、分割キーボードの接続のためにはお勧めできません。
|
||||
|
||||
### シリアル配線
|
||||
|
||||
2つの Pro Micro 間で GND、Vcc、D0/D1/D2/D3 (別名 PD0/PD1/PD2/PD3) を TRS/TRRS ケーブルの3本のワイヤで接続します。
|
||||
|
||||
?> ここで使われるピンは実際には以下の `SOFT_SERIAL_PIN` によって設定されることに注意してください。
|
||||
|
||||
<img alt="sk-pd0-connection-mono" src="https://user-images.githubusercontent.com/2170248/92296488-28e9ad80-ef70-11ea-98be-c40cb48a0319.JPG" width="48%"/>
|
||||
<img alt="sk-pd2-connection-mono" src="https://user-images.githubusercontent.com/2170248/92296490-2d15cb00-ef70-11ea-801f-5ace313013e6.JPG" width="48%"/>
|
||||
|
||||
### I<sup>2</sup>C 配線
|
||||
|
||||
2つの Pro Micro 間で GND、Vcc、さらに SCL と SDA (それぞれ 別名 PD0/ピン3 および PD1/ピン2) を TRRS ケーブルの4本のワイヤで接続します。
|
||||
|
||||
プルアップ抵抗はキーボードの左右どちら側にも配置することができます。もし各側を単独で使いたい場合は、4つの抵抗を使い、両側にプルアップ抵抗を配置することもできます。
|
||||
|
||||
<img alt="sk-i2c-connection-mono" src="https://user-images.githubusercontent.com/2170248/92297182-92b98580-ef77-11ea-9d7d-d6033914af43.JPG" width="50%"/>
|
||||
|
||||
## ファームウェア設定
|
||||
|
||||
分割キーボード機能を有効にするには、以下を `rules.mk` に追加してください:
|
||||
|
||||
```make
|
||||
SPLIT_KEYBOARD = yes
|
||||
```
|
||||
|
||||
カスタムトランスポート (通信メソッド)を使っている場合は、以下を追加する必要もあります:
|
||||
|
||||
```make
|
||||
SPLIT_TRANSPORT = custom
|
||||
```
|
||||
|
||||
### 左右の設定
|
||||
|
||||
デフォルトでは、ファームウェアはどちら側がどちらであるかを認識しません; 決定するには幾つかの助けが必要です。これを行うには幾つかの方法があり、以下に優先順に列挙します。
|
||||
|
||||
#### ピンによる左右の設定
|
||||
|
||||
左右を決定するためにコントローラ上のピンを読むようにファームウェアを設定することができます。これを行うには、以下を `config.h` ファイルに追加します:
|
||||
|
||||
```c
|
||||
#define SPLIT_HAND_PIN B7
|
||||
```
|
||||
|
||||
これは指定されたピンを読み込みます。high の場合、コントローラはそれを左側だと仮定し、low の場合、それは右側であると仮定します。
|
||||
|
||||
#### マトリックスピンによる左右の設定
|
||||
|
||||
左右を決定するためにコントローラのキーマトリックスピンを読むようにファームウェアを設定することができます。これを行うには、以下を `config.h` ファイルに追加します:
|
||||
|
||||
```c
|
||||
#define SPLIT_HAND_MATRIX_GRID D0, F1
|
||||
```
|
||||
|
||||
最初のピンは出力ピンで、2つ目は入力ピンです。
|
||||
|
||||
キーマトリックスに未使用の交点があるキーボードがあります。この設定は、左右の決定にこれらの未使用の交点の1つを使用します。
|
||||
|
||||
通常、ダイオードが交点に接続されている場合、左側と判断されます。次の定義を追加すると、右側と判断されます。
|
||||
|
||||
```c
|
||||
#define SPLIT_HAND_MATRIX_GRID_LOW_IS_RIGHT
|
||||
```
|
||||
|
||||
#### EEPROM による左右の設定
|
||||
|
||||
このメソッドは永続ストレージ(`EEPROM`)のフラグを設定することで、キーボードの左右を設定します。これはコントローラが最初に起動する時にチェックされ、キーボードのどちら側であるかとキーボードのレイアウトの向きを決定します。
|
||||
|
||||
|
||||
このメソッドを有効にするには、以下を `config.h` ファイルに追加します:
|
||||
|
||||
```c
|
||||
#define EE_HANDS
|
||||
```
|
||||
|
||||
ただし、各コントローラに正しい側の EEPROM ファイルを書き込む必要があります。これを手動で行うこともできますが、ファームウェアを書き込む時にこれを行う avrdude および dfu のターゲットが存在します。
|
||||
|
||||
* `:avrdude-split-left`
|
||||
* `:avrdude-split-right`
|
||||
* `:dfu-split-left`
|
||||
* `:dfu-split-right`
|
||||
* `:dfu-util-split-left`
|
||||
* `:dfu-util-split-right`
|
||||
|
||||
この設定は、`EEP_RST` キーや `eeconfig_init()` 関数を使って EEPROM を再初期化する時には変更されません。ただし、ファームウェアの組み込みオプション以外で EEPROM をリセット([QMK Toolbox]() の "Reset EEPROM" ボタンの動作のように、`EEPROM` を上書きするファイルを書きこむなど)した場合、`EEPROM` ファイルを再書き込みする必要があります。
|
||||
|
||||
`EEPROM` ファイルは、QMK ファームウェアのリポジトリ内の[ここ](https://github.com/qmk/qmk_firmware/tree/master/quantum/split_common)にあります。
|
||||
|
||||
#### `#define` による左右の設定
|
||||
|
||||
コンパイル時に左右を設定することができます。これは以下を `config.h` ファイルに追加することで行うことができます:
|
||||
|
||||
```c
|
||||
#define MASTER_RIGHT
|
||||
```
|
||||
|
||||
あるいは
|
||||
|
||||
```c
|
||||
#define MASTER_LEFT
|
||||
```
|
||||
|
||||
どちらも定義されていない場合、左右のデフォルトは `MASTER_LEFT` になります。
|
||||
|
||||
|
||||
### 通信オプション
|
||||
|
||||
全ての分割キーボードが同一であるとは限らないため、`config.h` ファイル内で設定することができる多くの追加のオプションがあります。
|
||||
|
||||
```c
|
||||
#define USE_I2C
|
||||
```
|
||||
|
||||
これは分割キーボードの I<sup>2</sup>C サポートを有効にします。これは厳密には通信用ではありませんが、OLED あるいは I<sup>2</sup>C ベースのデバイスに使うことができます。
|
||||
|
||||
```c
|
||||
#define SOFT_SERIAL_PIN D0
|
||||
```
|
||||
|
||||
これはシリアル通信用に使われるピンを設定します。シリアルを使っていない場合は、これを定義する必要はありません。
|
||||
|
||||
ただし、キーボード上でシリアルおよび I<sup>2</sup>C を使っている場合は、これを設定し、D0 および D1 以外の値に設定する必要があります (これらは I<sup>2</sup>C 通信のために使われます)。
|
||||
|
||||
```c
|
||||
#define SELECT_SOFT_SERIAL_SPEED {#}`
|
||||
```
|
||||
|
||||
シリアル通信に問題がある場合は、この値を変更して、シリアル用の通信速度を制御することができます。デフォルトは1で、可能な値は以下の通りです:
|
||||
|
||||
* **`0`**: 約189kbps (実験用途専用)
|
||||
* **`1`**: 約137kbps (デフォルト)
|
||||
* **`2`**: 約75kbps
|
||||
* **`3`**: 約39kbps
|
||||
* **`4`**: 約26kbps
|
||||
* **`5`**: 約20kbps
|
||||
|
||||
### ハードウェア設定オプション
|
||||
|
||||
ハードウェアのセットアップ方法に基づいて、設定する必要のある設定が幾つかあります。
|
||||
|
||||
```c
|
||||
#define MATRIX_ROW_PINS_RIGHT { <row pins> }
|
||||
#define MATRIX_COL_PINS_RIGHT { <col pins> }
|
||||
```
|
||||
|
||||
これにより、右側のマトリックスに異なるピンのセットを指定することができます。これは、左右の形が違うキーボード (Keebio の Quefrency など)で、左右で別の構成が必要な場合に便利です。
|
||||
|
||||
```c
|
||||
#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }
|
||||
```
|
||||
|
||||
これにより右側のための異なる直接ピンのセットを指定することができます。
|
||||
|
||||
```c
|
||||
#define ENCODERS_PAD_A_RIGHT { encoder1a, encoder2a }
|
||||
#define ENCODERS_PAD_B_RIGHT { encoder1b, encoder2b }
|
||||
```
|
||||
|
||||
これにより右側のための異なるエンコーダピンのセットを指定することができます。
|
||||
|
||||
```c
|
||||
#define RGBLIGHT_SPLIT
|
||||
```
|
||||
|
||||
このオプションは、分割キーボードのコントローラ間で RGB ライトモードの同期を有効にします。これはコントローラに直接配線されている RGB LED を持つキーボード用です (つまり、それらは TRRS ケーブルで "追加データ"オプションを使っていません)。
|
||||
|
||||
```c
|
||||
#define RGBLED_SPLIT { 6, 6 }
|
||||
```
|
||||
|
||||
これは各コントローラに直接接続されている LED の数を設定します。最初の数は左側、2番目の数は右側です。
|
||||
|
||||
?> この設定は `RGBLIGHT_SPLIT` が有効になっていることを意味し、有効になっていない場合は強制的に有効にします。
|
||||
|
||||
|
||||
```c
|
||||
#define SPLIT_USB_DETECT
|
||||
```
|
||||
このオプションは、スタートアップの挙動を変更して、マスタ/スレーブの決定時にアクティブな USB 接続を検出します。このオプションがタイムアウトになった場合、その片側はスレーブと見なされます。これは ARM のデフォルトの挙動で、AVR Teensy ボードに必要です (ハードウェアの制限のため)。
|
||||
|
||||
?> この設定はバッテリパックを使ったデモの機能を停止します。
|
||||
|
||||
```c
|
||||
#define SPLIT_USB_TIMEOUT 2000
|
||||
```
|
||||
これは、`SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合の最大タイムアウトを設定します。
|
||||
|
||||
```c
|
||||
#define SPLIT_USB_TIMEOUT_POLL 10
|
||||
```
|
||||
これは `SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合のポーリング頻度を設定します
|
||||
|
||||
## 追加のリソース(英語)
|
||||
|
||||
Nicinabox には Let's Split キーボードのための[非常に優れた詳細なガイド](https://github.com/nicinabox/lets-split-guide)があり、トラブルシューティング情報を含む知っておくべきほとんど全てをカバーします。
|
||||
|
||||
ただし、RGB ライトセクションは、RGB Split コードが QMK ファームウェアに追加されるずっと前に書かれたため、古くなっています。ガイドに従う代わりに、各 LED テーブ(訳注: LED strip とも呼びます)を直接コントローラに配線します。
|
||||
|
||||
<!-- I may port this information later, but for now ... it's very nice, and covers everything -->
|
||||
@ -1,135 +0,0 @@
|
||||
# QMK での速記 :id=stenography-in-qmk
|
||||
|
||||
<!---
|
||||
original document: 0.13.15:docs/feature_stenography.md
|
||||
git diff 0.13.15 HEAD -- docs/feature_stenography.md | cat
|
||||
-->
|
||||
|
||||
[速記](https://en.wikipedia.org/wiki/Stenotype)は裁判所のレポート、字幕および耳が不自由な人のためのリアルタイムの文字起こしで最もよく使われる記述方法です。速記では単語はスペル、音声およびショートカット(短い)ストロークが混在する音節ごとに音節化されます。プロの速記者は、標準的なタイピングで通常見られる負担を掛けずに、はるかに少ないエラー(99.9%より高い精度)で、200-300 WPM に到達できます。
|
||||
|
||||
[Open Steno Project](https://www.openstenoproject.org/)は、速記ストロークを単語とコマンドにリアルタイムに変換する Plover と呼ばれるオープンソースプログラムを構築しました。確立された辞書とサポートがあります。
|
||||
|
||||
## QWERTY キーボードを使った Plover :id=plover-with-qwerty-keyboard
|
||||
|
||||
Plover は全ての標準的な QWERTY キーボードで動作しますが、キーボードが NKRO (n-キーロールオーバー)をサポートする場合は Plover は一度に押された全てのキーが分かるためより効率的です。Plover 用のキーマップの例は `planck/keymaps/default` で見つかります。`PLOVER` レイヤーに切り替えると、数字バーをサポートするためにキーボードの位置が調整されます。
|
||||
|
||||
QMK で Plover を使うには、NKRO を有効にし、標準レイアウト以外のレイアウトの場合はオプションでレイアウトを調整します。複数のキーを押しやすくするために、なんらかの速記フレンドリなキーキャップを購入することもできます。
|
||||
|
||||
## 速記プロトコルを使った Plover :id=plover-with-steno-protocol
|
||||
|
||||
Plover は幾つかの速記マシンの言語も理解します。QMK はこれらの言語の内2つの言語、TX Bolt と GeminiPR を話すことができます。レイアウトの例は `planck/keymaps/steno` で見つけることができます。
|
||||
|
||||
QMKが steno プロトコルを使って Plover と話す場合は、Plover は入力としてキーボードを使いません。標準のキーボードと速記キーボードを行き来したり、あるいは Plover をアクティブ/非アクティブにする必要なく Plover と標準のレイヤーを行き来することができることを意味します。
|
||||
|
||||
このモードでは、Plover はシリアルポートを介して速記マシンと通信すると想定しているため、QMK はオペレーティングシステムに対してキーボードに加えて仮想シリアルポートとして存在しています。デフォルトでは、QMK は TX Bolt プロトコルを話しますが、GeminiPR に切り替えることができます; 最後に使われたプロトコルが不揮発性メモリに格納されるため QMK は再起動時に同じプロトコルを使います。
|
||||
|
||||
> 注意: ハードウェアの制限により、仮想シリアルポートとマウスエミュレーションの両方を同時に実行することができないかもしれません。
|
||||
|
||||
### TX Bolt :id=tx-bolt
|
||||
|
||||
TX Bolt は可変サイズ(1-5バイト)のパケットで非常に単純なプロトコルを介して24個のキーのステータスを通信します。
|
||||
|
||||
### GeminiPR :id=geminipr
|
||||
|
||||
GeminiPR は42個のキーを6バイトのパケットにエンコードします。TX Bolt は標準的な速記に必要な全てを含んでいますが、GeminiPR は英語以外の速記法のサポートを含む、より多くのオプションにも開け放たれています。
|
||||
|
||||
## 速記のための QMK の設定 :id=configuring-qmk-for-steno
|
||||
|
||||
最初にキーマップの Makefile で速記を有効にします。競合を避けるために、マウスキー、追加キーあるいはその他の USB エンドポイントを無効にする必要もあります。幾つかのプロセッサの内蔵の USB スタックは一定数の USB エンドポイントと仮想シリアルポートのみをサポートし、速記はそれらのうちの3つを使います。
|
||||
|
||||
```makefile
|
||||
STENO_ENABLE = yes
|
||||
MOUSEKEY_ENABLE = no
|
||||
```
|
||||
|
||||
キーマップで Plover 用の新しいレイヤーを作成します。`keymap_steno.h` をインクルードする必要があります。例については `planck/keymaps/steno/keymap.c` を見てください。レイヤーに切り替えるためのキーとレイヤーから抜けるためのキーを作成することを忘れないでください。その場でモードを切り替えたい場合は、キーコード `QK_STENO_BOLT` および `QK_STENO_GEMINI` を使うことができます。プロトコルのうちの1つのみを使う場合は、初期化関数の中でそれをセットアップすることができます:
|
||||
|
||||
```c
|
||||
void eeconfig_init_user() {
|
||||
steno_set_mode(STENO_MODE_GEMINI); // あるいは STENO_MODE_BOLT
|
||||
}
|
||||
```
|
||||
|
||||
キーボードを書き込んだら、Plover を起動します。'Configure...' ボタンをクリックします。'Machine' タブの中で目的のプロトコルに対応する速記マシンを選択します。このタブの 'Configure...' ボタンをクリックし、シリアルポートを入力するか 'Scan' をクリックします。ボーレートは 9600 で問題ありません (ただし、115200まで問題無く設定することができるはずです)。それ以外はデフォルトの設定(データビット長: 8、ストップビット長: 1、パリティチェック: なし、フロー制御なし)を使います。
|
||||
|
||||
ディスプレイタブで 'Open stroke display' をクリックします。Plover を無効にすると、キーボードのキーを押すとストローク表示ウィンドウにそれらが表示されるはずです。これを使ってキーマップが正しくセットアップされたことを確認してください。これで速記をする準備ができました！
|
||||
|
||||
## 速記の学習 :id=learning-stenography
|
||||
|
||||
* [Learn Plover!](https://sites.google.com/site/learnplover/)
|
||||
* [Steno Jig](https://joshuagrams.github.io/steno-jig/)
|
||||
* Plover [Learning Stenography](https://github.com/openstenoproject/plover/wiki/Learning-Stenography) wiki のより多くのリソース
|
||||
|
||||
## コードとのインターフェイス :id=interfacing-with-the-code
|
||||
|
||||
速記コードには3つの捕捉可能なフックがあります。これらの関数を定義した場合、処理の特定のポイントでそれらが呼び出されます; それらが true を返す場合処理が継続され、そうでなければあなたが物事を処理すると想定します。
|
||||
|
||||
```c
|
||||
bool send_steno_chord_user(steno_mode_t mode, uint8_t chord[6]);
|
||||
```
|
||||
|
||||
この関数はコードが送信されようとしている時に呼ばれます。モードは `STENO_MODE_BOLT` あるいは `STENO_MODE_GEMINI` のいずれかです。これはいずれかのプロトコルを介して送信される実際のコードを表します。提供されるコードを修正して送信されるものを変更することができます。通常の送信プロセスにしたい場合は true を返すのを忘れないでください。
|
||||
|
||||
```c
|
||||
bool process_steno_user(uint16_t keycode, keyrecord_t *record) { return true; }
|
||||
```
|
||||
|
||||
この関数はキーが押されるとキーが処理される前に呼び出されます。キーコードは `QK_STENO_BOLT`、`QK_STENO_GEMINI` あるいは `STN_*` キー値のいずれかでなければなりません。
|
||||
|
||||
```c
|
||||
bool post_process_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t mode, uint8_t chord[6], int8_t pressed);
|
||||
```
|
||||
|
||||
この関数はキーが処理された後、ただしコードを送信するかどうかを決める前に呼び出されます。`record->event.pressed` が false で、`pressed` が 0 または 1 の場合は、コードはまもなく送信されますが、まだ送信されてはいません。ここが速記コードあるいはキーのライブ表示などのフックを配置する場所です。
|
||||
|
||||
|
||||
## キーコードリファレンス :id=keycode-reference
|
||||
|
||||
`keymap_steno.h` で定義されています。
|
||||
|
||||
> 注意: TX Bolt はキーの完全なセットをサポートしません。QMK での TX Bolt の実装は、GeminiPR キーを最も近い TX Bolt キーにマップします。そのため1つのキーマップが両方で動作します。
|
||||
|
||||
| GeminiPR | TX Bolt | Steno Key |
|
||||
|--------|-------|-----------|
|
||||
| `STN_N1` | `STN_NUM` | Number bar #1 |
|
||||
| `STN_N2` | `STN_NUM` | Number bar #2 |
|
||||
| `STN_N3` | `STN_NUM` | Number bar #3 |
|
||||
| `STN_N4` | `STN_NUM` | Number bar #4 |
|
||||
| `STN_N5` | `STN_NUM` | Number bar #5 |
|
||||
| `STN_N6` | `STN_NUM` | Number bar #6 |
|
||||
| `STN_N7` | `STN_NUM` | Number bar #7 |
|
||||
| `STN_N8` | `STN_NUM` | Number bar #8 |
|
||||
| `STN_N9` | `STN_NUM` | Number bar #9 |
|
||||
| `STN_NA` | `STN_NUM` | Number bar #A |
|
||||
| `STN_NB` | `STN_NUM` | Number bar #B |
|
||||
| `STN_NC` | `STN_NUM` | Number bar #C |
|
||||
| `STN_S1` | `STN_SL` | `S-` upper |
|
||||
| `STN_S2` | `STN_SL` | `S-` lower |
|
||||
| `STN_TL` | `STN_TL` | `T-` |
|
||||
| `STN_KL` | `STN_KL` | `K-` |
|
||||
| `STN_PL` | `STN_PL` | `P-` |
|
||||
| `STN_WL` | `STN_WL` | `W-` |
|
||||
| `STN_HL` | `STN_HL` | `H-` |
|
||||
| `STN_RL` | `STN_RL` | `R-` |
|
||||
| `STN_A` | `STN_A` | `A` vowel |
|
||||
| `STN_O` | `STN_O` | `O` vowel |
|
||||
| `STN_ST1` | `STN_STR` | `*` upper-left |
|
||||
| `STN_ST2` | `STN_STR` | `*` lower-left |
|
||||
| `STN_ST3` | `STN_STR` | `*` upper-right |
|
||||
| `STN_ST4` | `STN_STR` | `*` lower-right |
|
||||
| `STN_E` | `STN_E` | `E` vowel |
|
||||
| `STN_U` | `STN_U` | `U` vowel |
|
||||
| `STN_FR` | `STN_FR` | `-F` |
|
||||
| `STN_PR` | `STN_PR` | `-P` |
|
||||
| `STN_RR` | `STN_RR` | `-R` |
|
||||
| `STN_BR` | `STN_BR` | `-B` |
|
||||
| `STN_LR` | `STN_LR` | `-L` |
|
||||
| `STN_GR` | `STN_GR` | `-G` |
|
||||
| `STN_TR` | `STN_TR` | `-T` |
|
||||
| `STN_SR` | `STN_SR` | `-S` |
|
||||
| `STN_DR` | `STN_DR` | `-D` |
|
||||
| `STN_ZR` | `STN_ZR` | `-Z` |
|
||||
| `STN_FN` | (GeminiPR のみ) |
|
||||
| `STN_RES1` | (GeminiPR のみ) |
|
||||
| `STN_RES2` | (GeminiPR のみ) |
|
||||
| `STN_PWR` | (GeminiPR のみ) |
|
||||
@ -1,36 +0,0 @@
|
||||
# スワップハンドアクション
|
||||
|
||||
<!---
|
||||
original document: 0.13.17:docs/feature_swap_hands.md
|
||||
git diff 0.13.17 HEAD -- docs/feature_swap_hands.md | cat
|
||||
-->
|
||||
|
||||
スワップハンドアクションにより、別のレイヤーを必要とせずに片手入力をサポートします。Makefile に `SWAP_HANDS_ENABLE` を設定し、キーマップに `hand_swap_config` エントリを定義します。これで `ACTION_SWAP_HANDS` コマンドキーが押されるたびにキーボードがミラーされます。例えば、QWERTY で "Hello, World" を入力するには、`^Ge^s^s^w^c W^wr^sd` を入力します。
|
||||
|
||||
## 設定
|
||||
|
||||
設定テーブルは列/行から新しい列/行にマップするための単純な2次元配列です。Planck の `hand_swap_config` の例:
|
||||
|
||||
```C
|
||||
const keypos_t PROGMEM hand_swap_config[MATRIX_ROWS][MATRIX_COLS] = {
|
||||
{{11, 0}, {10, 0}, {9, 0}, {8, 0}, {7, 0}, {6, 0}, {5, 0}, {4, 0}, {3, 0}, {2, 0}, {1, 0}, {0, 0}},
|
||||
{{11, 1}, {10, 1}, {9, 1}, {8, 1}, {7, 1}, {6, 1}, {5, 1}, {4, 1}, {3, 1}, {2, 1}, {1, 1}, {0, 1}},
|
||||
{{11, 2}, {10, 2}, {9, 2}, {8, 2}, {7, 2}, {6, 2}, {5, 2}, {4, 2}, {3, 2}, {2, 2}, {1, 2}, {0, 2}},
|
||||
{{11, 3}, {10, 3}, {9, 3}, {8, 3}, {7, 3}, {6, 3}, {5, 3}, {4, 3}, {3, 3}, {2, 3}, {1, 3}, {0, 3}},
|
||||
};
|
||||
```
|
||||
|
||||
配列のインデックスはマトリックスと同様に逆になり、値の型は `{col, row}` である `keypos_t` で、全ての値はゼロベースであることに注意してください。上の例では、`hand_swap_config[2][4]` (第3行, 第5列)は `{7, 2}` (第3行, 第8列) を返します。はい。紛らわしいです。
|
||||
|
||||
## キーコードの入れ替え
|
||||
|
||||
| キー | 説明 |
|
||||
|-----------|-------------------------------------------------------------------------|
|
||||
| `SH_T(key)` | タップで `key` を送信する。押している時の一時的な入れ替え。 |
|
||||
| `SH_ON` | 入れ替えをオンにして、そのままにする。 |
|
||||
| `SH_OFF` | 入れ替えをオフにして、そのままにする。既知の状態に戻るのに適しています。 |
|
||||
| `SH_MON` | 押すとスワップハンドし、放すと通常に戻る (一時的)。 |
|
||||
| `SH_MOFF` | 一時的に入れ替えをオフする。 |
|
||||
| `SH_TG` | キーを押すたびに入れ替えのオンとオフを切り替える。 |
|
||||
| `SH_TT` | タップで切り替える。押されている時の一時的なもの。 |
|
||||
| `SH_OS` | ワンショットスワップハンド: 押されている時あるいは次のキーを押すまで切り替える。 |
|
||||
@ -1,530 +0,0 @@
|
||||
# タップダンス: 1つのキーが3つ、5つまたは100の異なる動作をします
|
||||
|
||||
<!---
|
||||
original document: 0.13.15:docs/feature_tap_dance.md
|
||||
git diff 0.13.15 HEAD -- docs/feature_tap_dance.md | cat
|
||||
-->
|
||||
|
||||
## イントロダクション :id=introduction
|
||||
|
||||
セミコロンキーを1回叩くと、セミコロンが送信されます。2回素早く叩くと、コロンが送信されます。3回叩くと、あなたのキーボードのLEDが激しく踊るように明滅します。これは、タップダンスでできることの一例です。それは、コミュニティが提案したとても素敵なファームウェアの機能の1つで、[algernon](https://github.com/algernon) がプルリクエスト [#451](https://github.com/qmk/qmk_firmware/pull/451) で考えて作ったものです。algernon が述べる機能は次の通りです:
|
||||
|
||||
この機能を使うと、特定のキーが、タップした回数に基づいて異なる振る舞いをします。そして、割り込みがあった時は、割り込み前に上手く処理されます。
|
||||
|
||||
## タップダンスの使い方 :id=how-to-use
|
||||
最初に、あなたの `rules.mk` ファイルで `TAP_DANCE_ENABLE = yes` と設定する必要があります。なぜならば、デフォルトでは無効になっているからです。これでファームウェアのサイズが1キロバイトほど増加します。
|
||||
|
||||
オプションで、あなたの `config.h` ファイルに次のような設定を追加して、`TAPPING_TERM` の時間をカスタマイズしたほうが良いです。
|
||||
|
||||
```c
|
||||
#define TAPPING_TERM 175
|
||||
```
|
||||
|
||||
`TAPPING_TERM` の時間は、あなたのタップダンスのキーのタップとタップの間の時間として許可された最大の時間で、ミリ秒単位で計測されます。例えば、もし、あなたがこの上にある `#define` ステートメントを使い、1回タップすると `Space` が送信され、2回タップすると `Enter` が送信されるタップダンスキーをセットアップした場合、175ミリ秒以内に2回キーをタップすれば `ENT` だけが送信されるでしょう。もし、1回タップしてから175ミリ秒以上待ってからもう一度タップすると、`SPC SPC` が送信されます。
|
||||
|
||||
次に、いくつかのタップダンスのキーを定義するためには、`TD()` マクロを使うのが最も簡単です。これは数字を受け取り、この数字は後で `tap_dance_actions` 配列のインデックスとして使われます。
|
||||
|
||||
その後、`tap_dance_actions` 配列を使って、タップダンスキーを押した時のアクションを定義します。現在は、5つの可能なオプションがあります:
|
||||
|
||||
* `ACTION_TAP_DANCE_DOUBLE(kc1, kc2)`: 1回タップすると `kc1` キーコードを送信し、2回タップすると `kc2` キーコードを送信します。キーを押し続けているときは、適切なキーコードが登録されます: キーを押し続けた場合は `kc1`、一度タップしてから続けてもう一度キーを押してそのまま押し続けたときは、 `kc2` が登録されます。
|
||||
* `ACTION_TAP_DANCE_LAYER_MOVE(kc, layer)`: 1回タップすると `kc` キーコードが送信され、2回タップすると `layer` レイヤーに移動します(これは `TO` レイヤーキーコードのように機能します)。
|
||||
* `ACTION_TAP_DANCE_LAYER_TOGGLE(kc, layer)`: 1回タップすると `kc` キーコードが送信され、2回タップすると `layer` の状態をトグルします(これは `TG` レイヤーキーコードのように機能します)。
|
||||
* `ACTION_TAP_DANCE_FN(fn)`: ユーザーキーマップに定義した指定の関数が呼び出されます。タップダンス実行の回数分タップすると、最後の時点で呼び出されます。
|
||||
* `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn)`: タップする度にユーザーキーマップに定義した最初の関数が呼び出されます。タップダンスの実行が終わった時点で2番目の関数が呼び出され、タップダンスの実行をリセットするときに最後の関数が呼び出されます。
|
||||
* ~~`ACTION_TAP_DANCE_FN_ADVANCED_TIME(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn, tap_specific_tapping_term)`~~: これは `ACTION_TAP_DANCE_FN_ADVANCED` 関数と同じように機能します。しかし、`TAPPING_TERM` で事前に定義した時間の代わりに、カスタマイズしたタップ時間を使います。
|
||||
* [ここ](ja/custom_quantum_functions.md#Custom_Tapping_Term)で概説するように、これはキーごとのタッピング時間機能を優先して非推奨になりました。この特定のタップダンス機能を使う代わりに、使いたい特定の `TD()` マクロ(`TD(TD_ESC_CAPS)` のような)を確認する必要があります。
|
||||
|
||||
|
||||
最初のオプションで、1つのキーに2つの役割を持たせる大抵のケースには十分です。例えば、`ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT)` は、1回タップすると `Space` を送信し、2回タップすると `Enter` を送信します。
|
||||
|
||||
!> ここでは [基本的なキーコード](ja/keycodes_basic.md) だけがサポートされていることを覚えておいてください。カスタムキーコードはサポートされていません。
|
||||
|
||||
最初のオプションに似ていますが、2番目のオプションは単純なレイヤー切替のケースに適しています。
|
||||
|
||||
これ以上に複雑なケースの場合、3番目か4番目のオプションを使います。（以下でそれらの例を列挙します）
|
||||
|
||||
最後に、5番目のオプションは、もし、タップダンスキーをコードに追加した後、非タップダンスキーが奇妙な振る舞いを始めた時に特に役に立ちます。ありうる問題は、あなたがタップダンスキーを使いやすくするために `TAPPING_TERM` の時間を変更した結果、その他のキーが割り込みを処理する方法が変わってしまったというものです。
|
||||
|
||||
|
||||
## 実装の詳細 :id=implementation
|
||||
|
||||
さて、説明の大部分はここまでです！ 以下に挙げているいくつかの例に取り組むことができるようになり、あなた自身のタップダンスの機能を開発できるようになります。しかし、もし、あなたが裏側で起きていることをより深く理解したいのであれば、続けてそれが全てどのように機能するかの説明を読みましょう！
|
||||
|
||||
メインエントリーポイントは、`process_tap_dance()` で、`process_record_quantum()` から呼び出されます。これはキーを押すたびに実行され、ハンドラは早期に実行されます。この関数は、押されたキーがタップダンスキーがどうか確認します。
|
||||
もし、押されたキーがタップダンスキーではなく、かつ、タップダンスが実行されていたなら、最初にそれを処理し、新しく押されたキーをキューに格納します。
|
||||
もし、押されたキーがタップダンスキーであるなら、既にアクティブなタップダンスと同じキーか確認します（もしアクティブなものがある場合、それと）。
|
||||
異なる場合、まず、古いタップダンスを処理し、続いて新しいタップダンスを登録します。
|
||||
同じ場合、カウンタの値を増やし、タイマーをリセットします。
|
||||
|
||||
このことは、あなたは再びキーをタップするまでの時間として `TAPPING_TERM` の時間を持っていることを意味します。そのため、あなたは1つの `TAPPING_TERM` の時間内に全てのタップを行う必要はありません。これにより、キーの反応への影響を最小限に抑えながら、より長いタップ回数を可能にします。
|
||||
|
||||
次は `tap_dance_task()` です。この関数はタップダンスキーのタイムアウトを制御します。
|
||||
|
||||
柔軟性のために、タップダンスは、キーコードの組み合わせにも、ユーザー関数にもなることができます。後者は、より高度なタップ回数の制御や、LED を点滅させたり、バックライトをいじったり、等々の制御を可能にします。これは、1つの共用体と、いくつかの賢いマクロによって成し遂げられています。
|
||||
|
||||
## 実装例 :id=examples
|
||||
|
||||
### シンプルな実装例 :id=simple-example
|
||||
|
||||
ここに1つの定義のための簡単な例があります。
|
||||
|
||||
1. `rules.mk` に `TAP_DANCE_ENABLE = yes` を追加します。
|
||||
2. `config.h` ファイル（`qmk_firmware/keyboards/planck/config.h` からあなたのキーマップディレクトリにコピーできます）に `#define TAPPING_TERM 200` を追加します。
|
||||
3. `keymap.c` ファイルに変数とタップダンスの定義を定義し、それからキーマップに追加します。
|
||||
|
||||
```c
|
||||
// タップダンスの宣言
|
||||
enum {
|
||||
TD_ESC_CAPS,
|
||||
};
|
||||
|
||||
// タップダンスの定義
|
||||
qk_tap_dance_action_t tap_dance_actions[] = {
|
||||
// 1回タップすると Escape キー、2回タップすると Caps Lock。
|
||||
[TD_ESC_CAPS] = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS),
|
||||
};
|
||||
|
||||
// キーマップにキーコードの代わりにタップダンスの項目を追加します
|
||||
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
|
||||
// ...
|
||||
TD(TD_ESC_CAPS)
|
||||
// ...
|
||||
};
|
||||
```
|
||||
|
||||
### 複雑な実装例 :id=complex-examples
|
||||
|
||||
このセクションでは、いくつかの複雑なタップダンスの例を詳しく説明します。
|
||||
例で使われている全ての列挙型はこのように宣言します。
|
||||
|
||||
```c
|
||||
// 全ての例のための列挙型定義
|
||||
enum {
|
||||
CT_SE,
|
||||
CT_CLN,
|
||||
CT_EGG,
|
||||
CT_FLSH,
|
||||
X_TAP_DANCE
|
||||
};
|
||||
```
|
||||
#### 例1: 1回タップすると `:` を送信し、2回タップすると `;` を送信する :id=example-1
|
||||
|
||||
```c
|
||||
void dance_cln_finished(qk_tap_dance_state_t *state, void *user_data) {
|
||||
if (state->count == 1) {
|
||||
register_code16(KC_COLN);
|
||||
} else {
|
||||
register_code(KC_SCLN);
|
||||
}
|
||||
}
|
||||
|
||||
void dance_cln_reset(qk_tap_dance_state_t *state, void *user_data) {
|
||||
if (state->count == 1) {
|
||||
unregister_code16(KC_COLN);
|
||||
} else {
|
||||
unregister_code(KC_SCLN);
|
||||
}
|
||||
}
|
||||
|
||||
// 全てのタップダンス関数はここに定義します。ここでは1つだけ示します。
|
||||
qk_tap_dance_action_t tap_dance_actions[] = {
|
||||
[CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, dance_cln_finished, dance_cln_reset),
|
||||
};
|
||||
```
|
||||
|
||||
#### 例2: 100回タップした後に "Safety Dance!" を送信します :id=example-2
|
||||
|
||||
```c
|
||||
void dance_egg(qk_tap_dance_state_t *state, void *user_data) {
|
||||
if (state->count >= 100) {
|
||||
SEND_STRING("Safety dance!");
|
||||
reset_tap_dance(state);
|
||||
}
|
||||
}
|
||||
|
||||
qk_tap_dance_action_t tap_dance_actions[] = {
|
||||
[CT_EGG] = ACTION_TAP_DANCE_FN(dance_egg),
|
||||
};
|
||||
```
|
||||
|
||||
#### 例3: 1つずつ LED を点灯させてから消灯する :id=example-3
|
||||
|
||||
```c
|
||||
// タップする毎に、LED を右から左に点灯します。
|
||||
// 4回目のタップで、右から左に消灯します。
|
||||
void dance_flsh_each(qk_tap_dance_state_t *state, void *user_data) {
|
||||
switch (state->count) {
|
||||
case 1:
|
||||
ergodox_right_led_3_on();
|
||||
break;
|
||||
case 2:
|
||||
ergodox_right_led_2_on();
|
||||
break;
|
||||
case 3:
|
||||
ergodox_right_led_1_on();
|
||||
break;
|
||||
case 4:
|
||||
ergodox_right_led_3_off();
|
||||
wait_ms(50);
|
||||
ergodox_right_led_2_off();
|
||||
wait_ms(50);
|
||||
ergodox_right_led_1_off();
|
||||
}
|
||||
}
|
||||
|
||||
// 4回目のタップで、キーボードをフラッシュ状態にセットします。
|
||||
void dance_flsh_finished(qk_tap_dance_state_t *state, void *user_data) {
|
||||
if (state->count >= 4) {
|
||||
reset_keyboard();
|
||||
}
|
||||
}
|
||||
|
||||
// もしフラッシュ状態にならない場合、LED を左から右に消灯します。
|
||||
void dance_flsh_reset(qk_tap_dance_state_t *state, void *user_data) {
|
||||
ergodox_right_led_1_off();
|
||||
wait_ms(50);
|
||||
ergodox_right_led_2_off();
|
||||
wait_ms(50);
|
||||
ergodox_right_led_3_off();
|
||||
}
|
||||
|
||||
// 全てのタップダンス関数を一緒に表示しています。この例3は "CT_FLASH" です。
|
||||
qk_tap_dance_action_t tap_dance_actions[] = {
|
||||
[CT_SE] = ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT),
|
||||
[CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, dance_cln_finished, dance_cln_reset),
|
||||
[CT_EGG] = ACTION_TAP_DANCE_FN(dance_egg),
|
||||
[CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED(dance_flsh_each, dance_flsh_finished, dance_flsh_reset)
|
||||
};
|
||||
```
|
||||
|
||||
#### 例4: クアッドファンクションのタップダンス :id=example-4
|
||||
|
||||
[DanielGGordon](https://github.com/danielggordon) によるもの
|
||||
|
||||
キーを押す回数と、キーを押し続けるかタップするかによって、1つのキーに4つ（またはそれ以上）の機能を持たせることができるようになります。
|
||||
|
||||
以下に例をあげます:
|
||||
* 1回タップ = `x` を送信
|
||||
* 押し続ける = `Control` を送信
|
||||
* 2回タップ = `Escape` を送信
|
||||
* 2回タップして押し続ける = `Alt` を送信
|
||||
|
||||
'クアッドファンクションのタップダンス' を利用できるようにするには、いくつかのものが必要になります。
|
||||
|
||||
`keymap.c` ファイルの先頭、つまりキーマップの前に、以下のコードを追加します。
|
||||
|
||||
```c
|
||||
typedef enum {
|
||||
TD_NONE,
|
||||
TD_UNKNOWN,
|
||||
TD_SINGLE_TAP,
|
||||
TD_SINGLE_HOLD,
|
||||
TD_DOUBLE_TAP,
|
||||
TD_DOUBLE_HOLD,
|
||||
TD_DOUBLE_SINGLE_TAP, // Send two single taps
|
||||
TD_TRIPLE_TAP,
|
||||
TD_TRIPLE_HOLD
|
||||
} td_state_t;
|
||||
|
||||
typedef struct {
|
||||
bool is_press_action;
|
||||
td_state_t state;
|
||||
} td_tap_t;
|
||||
|
||||
// タップダンスの列挙型
|
||||
enum {
|
||||
X_CTL,
|
||||
SOME_OTHER_DANCE
|
||||
};
|
||||
|
||||
td_state_t cur_dance(qk_tap_dance_state_t *state);
|
||||
|
||||
// xタップダンスのための関数。キーマップで利用できるようにするため、ここに置きます。
|
||||
void x_finished(qk_tap_dance_state_t *state, void *user_data);
|
||||
void x_reset(qk_tap_dance_state_t *state, void *user_data);
|
||||
```
|
||||
|
||||
次に、`keymap.c` ファイルの末尾に、次のコードを追加する必要があります。
|
||||
|
||||
```c
|
||||
/* 実行されるタップダンスの種類に対応する整数を返します。
|
||||
*
|
||||
* タップダンスの状態を判別する方法: 割り込みと押下。
|
||||
*
|
||||
* 割り込み:
|
||||
* タップダンスの状態が「割り込み」の場合、他のキーがタップ時間中に押されたことを意味します。
|
||||
* これは通常、キーを「タップ」しようとしていることを示します。
|
||||
*
|
||||
* 押下:
|
||||
* キーがまだ押されているかどうか。この値が true の場合、タップ時間が終了したことを意味しますが、
|
||||
* キーはまだ押されたままです。これは通常、キーが「ホールド」されていることを意味します。
|
||||
*
|
||||
* タップダンスに関して、qmk ソフトウェアで現在不可能なことの1つは、"permissive hold" 機能を
|
||||
* 模倣することです。
|
||||
* 一般に、高度なタップダンスは一般的に入力される文字で使われた場合にうまく機能しません。
|
||||
* 例えば "A" の場合。タップダンスは文字の入力中に入力しない文字以外のキーで使うのが最適です。
|
||||
*
|
||||
* 高度なタップダンスを配置するのに適した場所:
|
||||
* z、q、x、j、k、v、b、ファンクションキー、home/end、コンマ、セミコロン
|
||||
*
|
||||
* タップダンスキーの「最適な配置場所」の基準:
|
||||
* 文章中で頻繁に入力するキーでないこと
|
||||
* ダブルタップに頻繁に使われるキーでないこと。例えば、'tab' はターミナルやウェブフォームで
|
||||
* しばしばダブルタップされます。そのため、タップダンスでは 'tab' は良い選択ではありません。
|
||||
* 一般的な単語で2回続けて使われる文字でないこと。例えば 'pepper' 中の 'p'。もしタップダンス機能が
|
||||
* 文字 'p' に存在する場合、'pepper' という単語は入力するのが非常にいらだたしいものになるでしょう。
|
||||
*
|
||||
* 3つ目の点については、'TD_DOUBLE_SINGLE_TAP' が存在しますが、これは完全にはテストされていません
|
||||
*
|
||||
*/
|
||||
td_state_t cur_dance(qk_tap_dance_state_t *state) {
|
||||
if (state->count == 1) {
|
||||
if (state->interrupted || !state->pressed) return TD_SINGLE_TAP;
|
||||
// キーは割り込まれていませんが、まだ押し続けられています。'HOLD' を送信することを意味します。
|
||||
else return TD_SINGLE_HOLD;
|
||||
} else if (state->count == 2) {
|
||||
// TD_DOUBLE_SINGLE_TAP は "pepper" と入力することと、'pp' と入力したときに実際に
|
||||
// ダブルタップしたい場合とを区別するためのものです。
|
||||
// この戻り値の推奨されるユースケースは、'ダブルタップ' 動作やマクロではなく、
|
||||
// そのキーの2つのキー入力を送信したい場合です。
|
||||
if (state->interrupted) return TD_DOUBLE_SINGLE_TAP;
|
||||
else if (state->pressed) return TD_DOUBLE_HOLD;
|
||||
else return TD_DOUBLE_TAP;
|
||||
}
|
||||
|
||||
// 誰も同じ文字を3回入力しようとしていないと仮定します(少なくとも高速には)。
|
||||
// タップダンスキーが 'KC_W' で、"www." と高速に入力したい場合、ここに例外を追加して
|
||||
// 'TD_TRIPLE_SINGLE_TAP' を返し、'TD_DOUBLE_SINGLE_TAP' のようにその列挙型を定義する必要があります。
|
||||
if (state->count == 3) {
|
||||
if (state->interrupted || !state->pressed) return TD_TRIPLE_TAP;
|
||||
else return TD_TRIPLE_HOLD;
|
||||
} else return TD_UNKNOWN;
|
||||
}
|
||||
|
||||
//'x' タップダンスの 'td_tap_t' のインスタンスを生成します。
|
||||
static td_tap_t xtap_state = {
|
||||
.is_press_action = true,
|
||||
.state = TD_NONE
|
||||
};
|
||||
|
||||
void x_finished(qk_tap_dance_state_t *state, void *user_data) {
|
||||
xtap_state.state = cur_dance(state);
|
||||
switch (xtap_state.state) {
|
||||
case TD_SINGLE_TAP: register_code(KC_X); break;
|
||||
case TD_SINGLE_HOLD: register_code(KC_LCTRL); break;
|
||||
case TD_DOUBLE_TAP: register_code(KC_ESC); break;
|
||||
case TD_DOUBLE_HOLD: register_code(KC_LALT); break;
|
||||
// 最後の case は高速入力用です。キーが `f` であると仮定します:
|
||||
// 例えば、`buffer` という単語を入力するとき、`Esc` ではなく `ff` を送信するようにします。
|
||||
// 高速入力時に `ff` と入力するには、次の文字は `TAPPING_TERM` 以内に入力する必要があります。
|
||||
// `TAPPING_TERM` はデフォルトでは 200ms です。
|
||||
case TD_DOUBLE_SINGLE_TAP: tap_code(KC_X); register_code(KC_X);
|
||||
}
|
||||
}
|
||||
|
||||
void x_reset(qk_tap_dance_state_t *state, void *user_data) {
|
||||
switch (xtap_state.state) {
|
||||
case TD_SINGLE_TAP: unregister_code(KC_X); break;
|
||||
case TD_SINGLE_HOLD: unregister_code(KC_LCTRL); break;
|
||||
case TD_DOUBLE_TAP: unregister_code(KC_ESC); break;
|
||||
case TD_DOUBLE_HOLD: unregister_code(KC_LALT);
|
||||
case TD_DOUBLE_SINGLE_TAP: unregister_code(KC_X);
|
||||
}
|
||||
xtap_state.state = TD_NONE;
|
||||
}
|
||||
|
||||
qk_tap_dance_action_t tap_dance_actions[] = {
|
||||
[X_CTL] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, x_finished, x_reset)
|
||||
};
|
||||
```
|
||||
|
||||
これで、キーマップのどこでも簡単に `TD(X_CTL)` マクロが使えます。
|
||||
|
||||
> この設定の "hold" は、タップダンスのタイムアウト（`ACTION_TAP_DANCE_FN_ADVANCED_TIME` 参照）の **後** に起こります。即座に "hold" を得るためには、条件から `state->interrupted` の確認を除きます。結果として、複数回のタップのための時間をより多く持つことで快適な長いタップの期限を使うことができ、そして、"hold" のために長く待たないようにすることができます(2倍の `TAPPING TERM` で開始してみてください)。
|
||||
|
||||
#### 例5: タップダンスを高度なモッドタップとレイヤータップキーに使う :id=example-5
|
||||
|
||||
タップダンスは、タップされたコードが基本的なキーコード以外の場合に、 `MT()` と `LT()` マクロをエミュレートするのに利用できます。これは、通常 `Shift` を必要とする '(' や '{' のようなキーや、`Control + X` のように他の修飾されたキーコードをタップされたキーコードとして送信することに役立ちます。
|
||||
|
||||
あなたのレイヤーとカスタムキーコードの下に、以下のコードを追加します。
|
||||
|
||||
```c
|
||||
// タップダンスのキーコード
|
||||
enum td_keycodes {
|
||||
ALT_LP // 例: 押していると `LALT`、タップすると `(`。それぞれのタップダンスの追加のキーコードを追加します
|
||||
};
|
||||
|
||||
// 必要な数のタップダンス状態を含むタイプを定義します
|
||||
typedef enum {
|
||||
TD_NONE,
|
||||
TD_UNKNOWN,
|
||||
TD_SINGLE_TAP,
|
||||
TD_SINGLE_HOLD,
|
||||
TD_DOUBLE_SINGLE_TAP
|
||||
} td_state_t;
|
||||
|
||||
// タップダンスの状態の型のグローバルインスタンスを作ります
|
||||
static td_state_t td_state;
|
||||
|
||||
// タップダンス関数を宣言します:
|
||||
|
||||
// 現在のタップダンスの状態を特定するための関数
|
||||
td_state_t cur_dance(qk_tap_dance_state_t *state);
|
||||
|
||||
// それぞれのタップダンスキーコードに適用する `finished` と `reset` 関数
|
||||
void altlp_finished(qk_tap_dance_state_t *state, void *user_data);
|
||||
void altlp_reset(qk_tap_dance_state_t *state, void *user_data);
|
||||
```
|
||||
|
||||
キーレイアウト（`LAYOUT`）の下に、タップダンスの関数を定義します。
|
||||
|
||||
```c
|
||||
// 返却するタップダンス状態を特定します
|
||||
td_state_t cur_dance(qk_tap_dance_state_t *state) {
|
||||
if (state->count == 1) {
|
||||
if (state->interrupted || !state->pressed) return TD_SINGLE_TAP;
|
||||
else return TD_SINGLE_HOLD;
|
||||
}
|
||||
|
||||
if (state->count == 2) return TD_DOUBLE_SINGLE_TAP;
|
||||
else return TD_UNKNOWN; // 上記で返却する最大の状態の値より大きい任意の数
|
||||
}
|
||||
|
||||
// 定義する各タップダンスキーコードのとりうる状態を制御します:
|
||||
|
||||
void altlp_finished(qk_tap_dance_state_t *state, void *user_data) {
|
||||
td_state = cur_dance(state);
|
||||
switch (td_state) {
|
||||
case TD_SINGLE_TAP:
|
||||
register_code16(KC_LPRN);
|
||||
break;
|
||||
case TD_SINGLE_HOLD:
|
||||
register_mods(MOD_BIT(KC_LALT)); // レイヤータップキーの場合、ここでは `layer_on(_MY_LAYER)` を使います
|
||||
break;
|
||||
case TD_DOUBLE_SINGLE_TAP: // タップ時間内に2つの括弧 `((` の入れ子を可能にします
|
||||
tap_code16(KC_LPRN);
|
||||
register_code16(KC_LPRN);
|
||||
}
|
||||
}
|
||||
|
||||
void altlp_reset(qk_tap_dance_state_t *state, void *user_data) {
|
||||
switch (td_state) {
|
||||
case TD_SINGLE_TAP:
|
||||
unregister_code16(KC_LPRN);
|
||||
break;
|
||||
case TD_SINGLE_HOLD:
|
||||
unregister_mods(MOD_BIT(KC_LALT)); // レイヤータップキーの場合、ここでは `layer_off(_MY_LAYER)` を使います
|
||||
break;
|
||||
case TD_DOUBLE_SINGLE_TAP:
|
||||
unregister_code16(KC_LPRN);
|
||||
}
|
||||
}
|
||||
|
||||
// 各タップダンスキーコードの `ACTION_TAP_DANCE_FN_ADVANCED()` を定義し、`finished` と `reset` 関数を渡します
|
||||
qk_tap_dance_action_t tap_dance_actions[] = {
|
||||
[ALT_LP] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, altlp_finished, altlp_reset)
|
||||
};
|
||||
```
|
||||
|
||||
それぞれのタップダンスキーコードをキーマップに含めるときは、`TD()` マクロでキーコードをラップします。例: `TD(ALT_LP)`
|
||||
|
||||
#### 例6: タップダンスを一時的なレイヤー切り替えとレイヤートグルキーに使う :id=example-6
|
||||
|
||||
タップダンスは、MO(layer) と TG(layer) 機能を模倣することにも使用できます。この例では、1回タップすると `KC_QUOT` 、1回押してそのまま押し続けたら `MO(_MY_LAYER)` 、2回タップしたときは `TG(_MY_LAYER)` として機能するキーを設定します。
|
||||
|
||||
最初のステップは、あなたの `keymap.c` ファイルの最初のあたりに以下のコードを追加することです。
|
||||
|
||||
```c
|
||||
// 必要な数のタップダンス状態のタイプを定義します
|
||||
typedef enum {
|
||||
TD_NONE,
|
||||
TD_UNKNOWN,
|
||||
TD_SINGLE_TAP,
|
||||
TD_SINGLE_HOLD,
|
||||
TD_DOUBLE_TAP
|
||||
} td_state_t;
|
||||
|
||||
typedef struct {
|
||||
bool is_press_action;
|
||||
td_state_t state;
|
||||
} td_tap_t;
|
||||
|
||||
enum {
|
||||
QUOT_LAYR, // カスタムタップダンスキー。他のタップダンスキーはこの列挙型に追加します
|
||||
};
|
||||
|
||||
// タップダンスキーで使われる関数を宣言します
|
||||
|
||||
// 全てのタップダンスに関連する関数
|
||||
td_state_t cur_dance(qk_tap_dance_state_t *state);
|
||||
|
||||
// 個別のタップダンスに関連する関数
|
||||
void ql_finished(qk_tap_dance_state_t *state, void *user_data);
|
||||
void ql_reset(qk_tap_dance_state_t *state, void *user_data);
|
||||
```
|
||||
|
||||
あなたの `keymap.c` ファイルの最後の方に以下のコードを追加します。
|
||||
|
||||
```c
|
||||
// 現在のタップダンスの状態を決定します
|
||||
td_state_t cur_dance(qk_tap_dance_state_t *state) {
|
||||
if (state->count == 1) {
|
||||
if (!state->pressed) return TD_SINGLE_TAP;
|
||||
else return TD_SINGLE_HOLD;
|
||||
} else if (state->count == 2) return TD_DOUBLE_TAP;
|
||||
else return TD_UNKNOWN;
|
||||
}
|
||||
|
||||
// この例のタップダンスキーに関連付けられた "tap" 構造体を初期化します
|
||||
static td_tap_t ql_tap_state = {
|
||||
.is_press_action = true,
|
||||
.state = TD_NONE
|
||||
};
|
||||
|
||||
// タップダンスキーの動作をコントロールする関数
|
||||
void ql_finished(qk_tap_dance_state_t *state, void *user_data) {
|
||||
ql_tap_state.state = cur_dance(state);
|
||||
switch (ql_tap_state.state) {
|
||||
case TD_SINGLE_TAP:
|
||||
tap_code(KC_QUOT);
|
||||
break;
|
||||
case TD_SINGLE_HOLD:
|
||||
layer_on(_MY_LAYER);
|
||||
break;
|
||||
case TD_DOUBLE_TAP:
|
||||
// レイヤーが既にセットされているか確認します
|
||||
if (layer_state_is(_MY_LAYER)) {
|
||||
// レイヤーが既にセットされていたら、オフにします。
|
||||
layer_off(_MY_LAYER);
|
||||
} else {
|
||||
// レイヤーがセットされていなかったら、オンにします。
|
||||
layer_on(_MY_LAYER);
|
||||
}
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
void ql_reset(qk_tap_dance_state_t *state, void *user_data) {
|
||||
// キーを押し続けていて今離したら、レイヤーをオフに切り替えます。
|
||||
if (ql_tap_state.state == TD_SINGLE_HOLD) {
|
||||
layer_off(_MY_LAYER);
|
||||
}
|
||||
ql_tap_state.state = TD_NONE;
|
||||
}
|
||||
|
||||
// タップダンスキーを機能に関連付けます
|
||||
qk_tap_dance_action_t tap_dance_actions[] = {
|
||||
[QUOT_LAYR] = ACTION_TAP_DANCE_FN_ADVANCED_TIME(NULL, ql_finished, ql_reset, 275)
|
||||
};
|
||||
```
|
||||
|
||||
上記のコードは、前の例で使われたコードに似ています。注意する1つのポイントは、必要に応じてレイヤーを切り替えられるように、どのレイヤーがアクティブになっているかいつでも確認できる必要があることです。これを実現するために、引数で与えられた `layer` がアクティブなら `true` を返す `layer_state_is(layer)` を使います。
|
||||
|
||||
`cur_dance()` と `ql_tap_state` の使い方は、上の例と似ています。
|
||||
|
||||
`ql_finished` 関数における `case: TD_SINGLE_TAP` は、上の例と似ています。`TD_SINGLE_HOLD` の case では、`ql_reset()` と連動してタップダンスキーを押している間 `_MY_LAYER` に切り替わり、キーを離した時に `_MY_LAYER` から離れます。これは、`MO(_MY_LAYER)` に似ています。`TD_DOUBLE_TAP` の case では、`_MY_LAYER` がアクティブレイヤーかどうかを確認することによって動きます。そして、その結果に基づいてレイヤーのオン・オフをトグルします。これは `TG(_MY_LAYER)` に似ています。
|
||||
|
||||
`tap_dance_actions[]` は、上の例に似ています。 `ACTION_TAP_DANCE_FN_ADVANCED()` の代わりに `ACTION_TAP_DANCE_FN_ADVANCED_TIME()` を使ったことに注意してください。
|
||||
この理由は、私は、非タップダンスキーを使うにあたり `TAPPING_TERM` が短い(175ミリ秒以内)方が好きなのですが、タップダンスのアクションを確実に完了させるには短すぎるとわかったからです——そのため、ここでは時間を275ミリ秒に増やしています。
|
||||
|
||||
最後に、このタップダンスキーを動かすため、忘れずに `TD(QUOT_LAYR)` を `keymaps[]` に加えてください。
|
||||
@ -1,15 +0,0 @@
|
||||
# 感熱式プリンタ
|
||||
|
||||
<!---
|
||||
original document: 0.8.147:docs/feature_thermal_printer.md
|
||||
git diff 0.8.147 HEAD -- docs/feature_thermal_printer.md | cat
|
||||
-->
|
||||
|
||||
<!-- FIXME: Describe thermal printers support here. -->
|
||||
|
||||
## 感熱式プリンタのキーコード
|
||||
|
||||
| キー | 説明 |
|
||||
|-----------|----------------------------------------|
|
||||
| `PRINT_ON` | ユーザが入力した全ての印刷を開始 |
|
||||
| `PRINT_OFF` | ユーザが入力した全ての印刷を停止 |
|
||||
@ -1,266 +0,0 @@
|
||||
# Unicode サポート
|
||||
|
||||
<!---
|
||||
original document: 0.10.53:docs/feature_unicode.md
|
||||
git diff 0.10.53 HEAD -- docs/feature_unicode.md | cat
|
||||
-->
|
||||
|
||||
Unicode 文字はキーボードから直接入力することができます！ただし幾つかの制限があります。
|
||||
|
||||
キーボードで Unicode サポートを有効にするには、以下の事をする必要があります:
|
||||
|
||||
1. サポートされている Unicode 実装のいずれかを選択します: [Basic Unicode](#basic-unicode)、[Unicode Map](#unicode-map)、[UCIS](#ucis)。
|
||||
2. オペレーティングシステムとセットアップに最適な[入力モード](#input-modes)を見つけます。
|
||||
3. コンフィギュレーションに適切な入力モード(または複数のモード)を[設定](#setting-the-input-mode)します。
|
||||
4. キーマップに Unicode キーコードを追加します。
|
||||
|
||||
|
||||
## 1. メソッド :id=methods
|
||||
|
||||
QMK は、Unicode 入力を有効にし、キーマップに Unicode 文字を追加するための3つの異なる方法をサポートします。それぞれに柔軟性と使いやすさの点で長所と短所があります。あなたの使い方に最適なものを選んでください。
|
||||
|
||||
ほとんどのユーザには Basic Unicode で十分です。ただし、サポートされる文字の範囲が広い(絵文字、珍しい記号など)ことが必要な場合には、Unicode Map を使う必要があります。
|
||||
|
||||
<br>
|
||||
|
||||
### 1.1. Basic Unicode :id=basic-unicode
|
||||
|
||||
多少制限はありますが、最も使いやすい方法です。Unicode 文字をキーコードとしてキーマップ自体に格納するため、`0x7FFF` までのコードポイントのみをサポートします。これは、ほとんどの現代言語(東アジアを含む)の文字と記号を対象としますが、絵文字は対象外です。
|
||||
|
||||
以下を `rules.mk` に追加します:
|
||||
|
||||
```make
|
||||
UNICODE_ENABLE = yes
|
||||
```
|
||||
|
||||
次に、`UC(c)` キーコードをキーマップに追加します。ここで、_c_ は目的の文字のコードポイントです (できれば16進数で最大4桁の長さが望ましいです)。例えば、`UC(0x40B)` は [Ћ](https://unicode-table.com/en/040B/) を出力し、`UC(0x30C4)` は [ツ](https://unicode-table.com/en/30C4) を出力します。
|
||||
|
||||
<br>
|
||||
|
||||
### 1.2. Unicode Map :id=unicode-map
|
||||
|
||||
このメソッドは、標準の文字の範囲に加えて、絵文字、古代文字、珍しい記号なども対象にしています。実際、可能な全てのコードポイント(`0x10FFFF`まで)がサポートされています。Unicode 文字は独立のマッピングテーブルに格納されています。キーマップファイルに `unicode_map` 配列を維持する必要があります。これには最大 16384 エントリを含めることができます。
|
||||
|
||||
以下を `rules.mk` に追加します:
|
||||
|
||||
```make
|
||||
UNICODEMAP_ENABLE = yes
|
||||
```
|
||||
|
||||
次に、`X(i)` キーコードをキーマップに追加します。ここで _i_ はマッピングテーブル内の目的の文字のインデックスです。これは数値にできますが、インデックスを列挙型に保持し、名前でアクセスすることをお勧めします。
|
||||
|
||||
```c
|
||||
enum unicode_names {
|
||||
BANG,
|
||||
IRONY,
|
||||
SNEK
|
||||
};
|
||||
|
||||
const uint32_t PROGMEM unicode_map[] = {
|
||||
[BANG] = 0x203D, // ‽
|
||||
[IRONY] = 0x2E2E, // ⸮
|
||||
[SNEK] = 0x1F40D, // 🐍
|
||||
};
|
||||
```
|
||||
|
||||
そして、キーマップで `X(BANG)`、`X(SNEK)` などを使うことができます。
|
||||
|
||||
#### 小文字と大文字
|
||||
|
||||
文字は å や Å のような小文字と大文字のペアで提供されることがあります。これらの文字を入力しやすくするために、キーマップで `XP(i, j)` を使うことができます。ここで、_i_ および _j_ はそれぞれ小文字と大文字のマッピングテーブルのインデックスです。キーを押した時に、シフトを押したままか Caps Lock をオンにしている場合は、2番目(大文字)の文字が挿入されます; そうでなければ最初(小文字)バージョンが出力されます。
|
||||
|
||||
これは特殊文字がある国際レイアウトのためのキーマップを作成している時に最も役立ちます。別々のキーに文字の小文字および大文字バージョンを置く代わりに、`XP()` を使ってそれら両方を同じキーに持つことができます。これは Unicode キーを通常のアルファベットと混ぜるのに役立ちます。
|
||||
|
||||
キーコードのサイズの制約により、_i_ と _j_ はそれぞれ `unicode_map` の最初の128文字のうち1つだけを参照できます。別の言い方をすると、0 ≤ _i_ ≤ 127 かつ 0 ≤ _j_ ≤ 127 です。これはほとんどのユースケースで十分ですが、インデックス計算をカスタマイズしたい場合は、[`unicodemap_index()`](https://github.com/qmk/qmk_firmware/blob/71f640d47ee12c862c798e1f56392853c7b1c1a8/quantum/process_keycode/process_unicodemap.c#L36) 関数をオーバーライドすることができます。これにより、例えば Shift/Caps の代わりに Ctrl をチェックすることもできます。
|
||||
|
||||
<br>
|
||||
|
||||
### 1.3. UCIS :id=ucis
|
||||
|
||||
この方法も全ての可能なコードポイントをサポートします。Unicode Map の方法と同様に、キーマップファイル内にマッピングテーブルを保持する必要があります。ただし、この機能のための組み込みのキーコードはありません — この機能を起動するカスタムキーコードあるいは関数を作成する必要があります。
|
||||
|
||||
以下を `rules.mk` に追加します:
|
||||
|
||||
```make
|
||||
UCIS_ENABLE = yes
|
||||
```
|
||||
|
||||
次に、キーマップファイルでこのようにテーブルを定義します:
|
||||
|
||||
```c
|
||||
const qk_ucis_symbol_t ucis_symbol_table[] = UCIS_TABLE(
|
||||
UCIS_SYM("poop", 0x1F4A9), // 💩
|
||||
UCIS_SYM("rofl", 0x1F923), // 🤣
|
||||
UCIS_SYM("cuba", 0x1F1E8, 0x1F1FA), // 🇨🇺
|
||||
UCIS_SYM("look", 0x0CA0, 0x005F, 0x0CA0), // ಠ_ಠ
|
||||
);
|
||||
```
|
||||
|
||||
デフォルトでは、各テーブルエントリの長さは、最大3コードポイントです。この番号は `#define UCIS_MAX_CODE_POINTS n` を `config.h` ファイルに追加することで変更できます。
|
||||
|
||||
UCIS 入力を使うには、`qk_ucis_start()` を呼び出します。次に、文字のニーモニック ("rofl" など) を入力し、Space か Enter か Esc を押します。QMK は "rofl" テキストを消去し、笑っている絵文字を挿入するはずです。
|
||||
|
||||
#### カスタマイズ
|
||||
|
||||
この機能をカスタマイズするためにキーマップで定義できる幾つかの関数があります。
|
||||
|
||||
* `void qk_ucis_start_user(void)` – これは "start" 関数を呼び出す時に実行され、フィードバックを提供するために使うことができます。デフォルトでは、キーボードの絵文字を入力します。
|
||||
* `void qk_ucis_success(uint8_t symbol_index)` – これは入力が何かに一致して完了した時に実行されます。デフォルトでは何もしません。
|
||||
* `void qk_ucis_symbol_fallback (void)` – これは入力が何にも一致しない時に実行されます。デフォルトでは、入力を Unicode コードとして試そうとします。
|
||||
|
||||
[`process_ucis.c`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_ucis.c) でこれらの関数のデフォルトの実装を見つけることができます。
|
||||
|
||||
|
||||
## 2. Input モード :id=input-modes
|
||||
|
||||
QMK での Unicode の入力は、マクロのように、OS への一連の文字列を入力することで動作します。残念ながら、これが行われる方法はプラットフォームによって異なります。特に各プラットフォームでは Unicode 入力を引き起こすために、異なるキーの組み合わせが必要です。従って、対応する入力モードが QMK で設定されなければなりません。
|
||||
|
||||
以下の入力モードが利用可能です:
|
||||
|
||||
* **`UC_MAC`**: macOS の組み込み Unicode 16進数入力。`0x10FFFF` までのコードポイント(全ての利用可能なコードポイント)をサポートします。
|
||||
|
||||
有効にするには、_システム環境設定 > キーボード > 入力ソース_ に移動し、(_その他_ の下の) _Unicode 16進数入力_ をリストに追加し、次にメニューバーの入力ドロップダウンからそれをアクティブにします。
|
||||
デフォルトでは、このモードは Unicode 入力のために左 Option キー (`KC_LALT`) を使いますが、これは他のキーで [`UNICODE_KEY_MAC`](#input-key-configuration) を定義することで変更できます。
|
||||
|
||||
!> _Unicode 16進数入力_ 入力ソースの使用は、Option + 左矢印および Option + 右矢印 のような、幾つかの Option ベースのショートカットを無効にするかもしれません。
|
||||
|
||||
!> `UC_OSX` は `UC_MAC` の非推奨のエイリアスで、QMK の将来のバージョンで削除されます。全ての新しいキーマップは、`UC_MAC` を使うべきです。
|
||||
|
||||
* **`UC_LNX`**: Linux の組み込み IBus Unicode 入力。`0x10FFFF` までのコードポイント(全ての利用可能なコードポイント)をサポートします。
|
||||
|
||||
デフォルトで有効になっていて、IBus が有効になったディストリビューションのほとんどどれでも動作します。IBus が無い場合、このモードは GTK アプリ下で動作しますが、他の場所ではほとんど動作しません。
|
||||
デフォルトでは、このモードは Unicode 入力を開始するために Ctrl+Shift+U (`LCTL(LSFT(KC_U))`) を使いますが、これは他のキーコードで [`UNICODE_KEY_LNX`](#input-key-configuration) を定義することで変更できます。これは、Ctrl+Shift+U の挙動が Ctrl+Shift+E に統合された IBus バージョン 1.5.15 以上を必要とするかもしれません。
|
||||
|
||||
* **`UC_WIN`**: _(非推奨)_ Windows の組み込み16進数テンキー Unicode 入力。`0xFFFF` までのコードポイントをサポートします。
|
||||
|
||||
有効にするには、`HKEY_CURRENT_USER\Control Panel\Input Method` の下に、`EnableHexNumpad` という名前の `REG_SZ` 型のレジストリキーを作成し、その値を `1` に設定します。これは、管理者権限でコマンドラインプロンプトから `reg add "HKCU\Control Panel\Input Method" -v EnableHexNumpad -t REG_SZ -d 1` を実行することでできます。その後再起動します。
|
||||
信頼性と互換性の問題から、このモードはお勧めできません; 代わりに `UC_WINC` モードを使ってください。
|
||||
|
||||
* **`UC_BSD`**: _(未実装)_ BSD での Unicode 入力。現時点では実装されていません。BSD ユーザでサポートを追加したい場合は、[GitHub で issue を開いて](https://github.com/qmk/qmk_firmware/issues)ください。
|
||||
|
||||
* **`UC_WINC`**: [WinCompose](https://github.com/samhocevar/wincompose) を使った Windows Unicode 入力。v0.9.0 の時点で、`0x10FFFF` までのコードポイント(全ての利用可能なコードポイント)をサポートします。
|
||||
|
||||
有効にするには、[最新のリリース](https://github.com/samhocevar/wincompose/releases/latest)をインストールします。インストールすると、起動時に WinCompose が自動的に実行されます。このモードはアプリがサポートする全てのバージョンの Windows で確実に動作します。
|
||||
デフォルトでは、このモードは Compose キーとして右 Alt (`KC_RALT`) を使いますが、これは WinCompose 設定と他のキーで [`UNICODE_KEY_WINC`](#input-key-configuration) を定義することで変更できます。
|
||||
|
||||
|
||||
## 3. 入力モードの設定 :id=setting-the-input-mode
|
||||
|
||||
目的の入力モードを設定するには、以下の定義を `config.h` に追加します:
|
||||
|
||||
```c
|
||||
#define UNICODE_SELECTED_MODES UC_LNX
|
||||
```
|
||||
|
||||
この例では、キーボードのデフォルトの入力モードを `UC_LNX` に設定します。これは、`UC_MAC` か `UC_WINC` か[上記](#input-modes)に列挙されている他のモードのいずれかに置き換えることができます。手動で別のモード([下記](#keycodes)を見てください)に切り替えない限り、キーボードは起動時に選択したモードを自動的に使います。
|
||||
|
||||
複数の入力モードを選択することもできます。これにより、`UC_MOD`/`UC_RMOD` キーコードを使ってそれらを簡単に切り替えることができます。
|
||||
|
||||
```c
|
||||
#define UNICODE_SELECTED_MODES UC_MAC, UC_LNX, UC_WINC
|
||||
```
|
||||
|
||||
値はカンマで区切られていることに注意してください。キーボードは最後に使われた入力モードを記憶し、次の電源投入時にそれを使い続けます。`config.h` に `#define UNICODE_CYCLE_PERSIST false` を追加することで、これを無効にして常にリストの最初のモードで開始するように強制できます。
|
||||
|
||||
#### キーコード
|
||||
|
||||
以下のキーコードを使って、いつでも入力モードを切り替えることができます。これらをキーマップに追加すると、`UNICODE_SELECTED_MODES` に列挙されていないモードを含む特定の入力モードに素早く切り替えることができます。
|
||||
|
||||
| キーコード |エイリアス | 入力モード | 説明 |
|
||||
|------------------------|-----------|--------------|--------------------------------------------------------------------|
|
||||
| `UNICODE_MODE_FORWARD` | `UC_MOD` | リストの次へ | 選択したモードを切り替えます。Shift が押された場合は逆方向 |
|
||||
| `UNICODE_MODE_REVERSE` | `UC_RMOD` | リストの前へ | 逆方向に選択したモードを切り替えます。Shift が押された場合は順方向 |
|
||||
| `UNICODE_MODE_MAC` | `UC_M_MA` | `UC_MAC` | macOS 入力に切り替え |
|
||||
| `UNICODE_MODE_LNX` | `UC_M_LN` | `UC_LNX` | Linux 入力に切り替え |
|
||||
| `UNICODE_MODE_WIN` | `UC_M_WI` | `UC_WIN` | Windows 入力に切り替え |
|
||||
| `UNICODE_MODE_BSD` | `UC_M_BS` | `UC_BSD` | BSD 入力に切り替え _(未実装)_ |
|
||||
| `UNICODE_MODE_WINC` | `UC_M_WC` | `UC_WINC` | WinCompose を使う Windows 入力に切り替え |
|
||||
|
||||
コード内で `set_unicode_input_mode(x)` を呼び出すことで、入力モードを切り替えることもできます。ここで、_x_ は上記の入力モード定数のいずれか (例えば、`UC_LNX`) です。
|
||||
|
||||
?> `matrix_init_user()` または同様の関数の中で `set_unicode_input_mode()` を呼び出すよりも、`UNICODE_SELECTED_MODES` を使うほうが望ましいです。Unicode システムとの統合性が高く、EEPROM への不要な書き込みを回避できるという利点があるからです。
|
||||
|
||||
#### オーディオフィードバック
|
||||
|
||||
キーボードで[オーディオ機能](ja/feature_audio.md)を有効にした場合、上記のキーを押したときにメロディーを再生するように設定できます。そのようにして、入力モードを切り替えた時になんらかのオーディオフィードバックを得ることができます。
|
||||
|
||||
例えば、`config.h` ファイルに下記の定義を追加することができます:
|
||||
|
||||
```c
|
||||
#define UNICODE_SONG_MAC AUDIO_ON_SOUND
|
||||
#define UNICODE_SONG_LNX UNICODE_LINUX
|
||||
#define UNICODE_SONG_BSD TERMINAL_SOUND
|
||||
#define UNICODE_SONG_WIN UNICODE_WINDOWS
|
||||
#define UNICODE_SONG_WINC UNICODE_WINDOWS
|
||||
```
|
||||
|
||||
|
||||
## 追加のカスタマイズ
|
||||
|
||||
Unicode は大規模で多目的な機能のため、システムでより適切に動作するようにカスタマイズできるオプションが幾つかあります。
|
||||
|
||||
### 入力関数の開始と終了
|
||||
|
||||
プラットフォームで Unicode 入力を開始および終了する機能は、ローカルで上書きできます。可能な用途には、デフォルトキーを使用しない場合の入力モードの挙動のカスタマイズ、あるいは Unicode 入力への視覚/音声フィードバックの追加があります。
|
||||
|
||||
* `void unicode_input_start(void)` – これはプラットフォームに Unicode 入力モードの入力を指示する初期シーケンスを送信します。例えば、Windows では左 Alt キーの後に Num+ を押したままにし、Linux では `UNICODE_KEY_LNX` の組み合わせ(デフォルト: Ctrl+Shift+U) を押します。
|
||||
* `void unicode_input_finish(void)` – これは、例えば Space を押すか Alt キーを放すなどして、Unicode 入力モードを終了するために呼ばれます。
|
||||
|
||||
[`process_unicode_common.c`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_unicode_common.c) でこれらの関数のデフォルトの実装を見つけることができます。
|
||||
|
||||
### 入力キーの設定
|
||||
|
||||
`config.h` に対応する定義を追加することで、macOS、Linux、WinCompose で Unicode 入力を引き起こすために使われるキーをカスタマイズできます。デフォルト値はプラットフォームのデフォルト設定に一致するため、Unicode 入力が動作しない、あるいは(例えば左あるいは右 Alt を解放するために)異なるキーを使いたい場合以外はこれを変更する必要はありません。
|
||||
|
||||
| 定義 | 型 | 既定値 | 例 |
|
||||
|--------------------|------------|--------------------|---------------------------------------------|
|
||||
| `UNICODE_KEY_MAC` | `uint8_t` | `KC_LALT` | `#define UNICODE_KEY_MAC KC_RALT` |
|
||||
| `UNICODE_KEY_LNX` | `uint16_t` | `LCTL(LSFT(KC_U))` | `#define UNICODE_KEY_LNX LCTL(LSFT(KC_E))` |
|
||||
| `UNICODE_KEY_WINC` | `uint8_t` | `KC_RALT` | `#define UNICODE_KEY_WINC KC_RGUI` |
|
||||
|
||||
|
||||
## Unicode 文字列の送信
|
||||
|
||||
QMK は、Unicode 入力をプログラムでホストに送信できるようにする幾つかの関数を提供します:
|
||||
|
||||
### `send_unicode_string()`
|
||||
|
||||
この関数は、`send_string()` によく似ていますが、UTF-8 文字を直接入力できます。選択された入力モードでもサポートされている場合は、全てのコードポイントをサポートします。`keymap.c` ファイルが UTF-8 エンコーディングを使ってフォーマットされていることを確認してください。
|
||||
|
||||
```c
|
||||
send_unicode_string("(ノಠ痊ಠ)ノ彡┻━┻");
|
||||
```
|
||||
|
||||
使用例には、[Macros](ja/feature_macros.md) で説明されているように、キーが押された時に Unicode 文字列を送信することが含まれます。
|
||||
|
||||
## 追加の言語サポート
|
||||
|
||||
`quantum/keymap_extras` には、様々な言語ファイルがあります — これらは Colemak または BÉPO のような代替レイアウトのファイルと同じように動作します。これらの言語ヘッダのいずれかを `#include` すると、その言語/国のレイアウトに固有のキーコードにアクセスできます。このようなキーコードは、2文字の国/言語コードの後に、アンダースコアとキーが対応する4文字の略語が続くことで定義されます。例えば、キーマップに `keymap_french.h` を含め、`FR_UGRV` を使うと、ネイティブのフランス語 AZERTY レイアウトを使うシステムで入力すると、`ù` が出力されます。
|
||||
|
||||
マシンで使うプライマリシステムレイアウトが US ANSI と異なる場合、これらの言語固有のキーコードを使うと、QMK キーマップが実際に画面に出力されるものとより一致するようになります。ただし、これらのキーコードは、内部の対応するデフォルトの US キーコードのエイリアスに過ぎず、キーボードで使われる HID プロトコル自体は本質的に US ANSI に基づいていることに注意してください。
|
||||
|
||||
|
||||
## Windows での国際文字
|
||||
|
||||
### AutoHotkey
|
||||
|
||||
この方法はキーボード自体で Unicode サポートを必要としませんが、代わりにバックグラウンドで [AutoHotkey](https://autohotkey.com) が実行されていることを当てにします。
|
||||
|
||||
最初にプログラムで使われていないモディファイアの組み合わせを選択する必要があります。
|
||||
Ctrl+Alt+Win はあまり広く使われていないため、これに最適なはずです。
|
||||
mod-tab コンボ `LCAG_T` 用に定義されたマクロがあります。
|
||||
この mod-tab マクロをキーボードのキーに追加します。例えば: `LCAG_T(KC_TAB)`。
|
||||
これにより、キーを押してすぐ放すとキーはタブキーのように振る舞いますが、他のキーと一緒に使うとモディファイアに変わります。
|
||||
|
||||
AutoHotkey のデフォルトのスクリプトで、カスタムホットキーを定義できます。
|
||||
|
||||
<^<!<#a::Send, ä
|
||||
<^<!<#<+a::Send, Ä
|
||||
|
||||
上のホットキーは、CtrlAltGui と CtrlAltGuiShift + 文字 a の組み合わせです。
|
||||
この組み合わせが押されると、AutoHotkey は `Send, ` の右側にあるテキストを挿入します。
|
||||
|
||||
### 米国インターナショナル
|
||||
|
||||
システム上で米国インターナショナルレイアウトを有効にすると、文字にアクセントをつけるために区切り文字を使います。例えば、"\`a" は à になります。
|
||||
これを有効にする方法は[ここ](https://support.microsoft.com/en-us/help/17424/windows-change-keyboard-layout)で見つかります。
|
||||
@ -1,260 +0,0 @@
|
||||
# ユーザスペース: キーマップ間でのコードの共有
|
||||
|
||||
<!---
|
||||
original document: 0.13.17:docs/feature_userspace.md
|
||||
git diff 0.13.17 HEAD -- docs/feature_userspace.md | cat
|
||||
-->
|
||||
|
||||
似たキーマップを複数のキーボードで使う場合、それらの間でコードを共有できるという利点が得られることがあります。`users/`に以下の構造でキーマップ(理想的には GitHub のユーザ名、`<name>`)と同じ名前の独自のフォルダを作成します:
|
||||
|
||||
* `/users/<name>/` (パスに自動的に追加されます)
|
||||
* `readme.md` (オプション、推奨)
|
||||
* `rules.mk` (自動的に含まれます)
|
||||
* `config.h` (自動的に含まれます)
|
||||
* `<name>.h` (オプション)
|
||||
* `<name>.c` (オプション)
|
||||
* `cool_rgb_stuff.c` (オプション)
|
||||
* `cool_rgb_stuff.h` (オプション)
|
||||
|
||||
|
||||
以下のように、`<name>` という名前のキーマップをビルドする時のみ、これが全て起きます:
|
||||
|
||||
make planck:<name>
|
||||
|
||||
例えば、
|
||||
|
||||
make planck:jack
|
||||
|
||||
は、`/users/jack/rules.mk` に加えて、パスに `/users/jack/` フォルダを含めます。
|
||||
|
||||
!> この `name` は必要に応じて[上書き](#override-default-userspace)することができます。
|
||||
|
||||
## `Rules.mk`
|
||||
|
||||
`rules.mk` は自動的に処理される2つファイルのうちの1つです。これにより、コンパイル時に追加のソースファイル( `<name>.c` など)を追加できます。
|
||||
|
||||
追加されるデフォルトのソースファイルとして `<name>.c` を使うことを強くお勧めします。それを追加するために、以下のように `rules.mk` に SRC を追加する必要があります:
|
||||
|
||||
SRC += <name>.c
|
||||
|
||||
追加のファイルも同じ方法で追加できます - ただし、`<name>`.c/.h という名前のファイルを最初に用意することをお勧めします。
|
||||
|
||||
ビルド時に `/users/<name>/rules.mk` ファイルはキーマップの `rules.mk` の_後_でインクルードされます。これにより、キーボードによっては利用できないことのある個々の QMK 機能を利用する機能をユーザスペース `rules.mk` に持つことができます。
|
||||
|
||||
例えば、RGB ライトをサポートする全てのキーボード間で RGB 制御機能を共有する場合、RGBLIGHT 機能が有効であればサポートを追加することができます:
|
||||
```make
|
||||
ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
|
||||
# ここにファンシーな rgb 関数のソースを含める
|
||||
SRC += cool_rgb_stuff.c
|
||||
endif
|
||||
```
|
||||
|
||||
別のやり方として、キーマップの `rules.mk` で `define RGB_ENABLE` と定義し、以下のようにユーザスペースの `rules.mk` で変数をチェックすることができます:
|
||||
```make
|
||||
ifdef RGB_ENABLE
|
||||
# ここにファンシーな rgb 関数のソースを含める
|
||||
SRC += cool_rgb_stuff.c
|
||||
endif
|
||||
```
|
||||
|
||||
### デフォルトのユーザスペースの上書き :id=override-default-userspace
|
||||
|
||||
デフォルトでは、使用されるユーザスペース名はキーマップ名と同じです。状況によってはこれは望ましくありません。例えば、[レイアウト](ja/feature_layouts.md)機能を使う場合、異なるキーマップに同じ名前 (例えば、ANSI および ISO) を使うことができません。レイアウトに `mylayout-ansi` や `mylayout-iso` という名前を付け、以下の行をレイアウトの `rules.mk` に追加します:
|
||||
|
||||
```
|
||||
USER_NAME := mylayout
|
||||
```
|
||||
|
||||
これは、基板上に物理的に異なる機能を備えた、複数の異なるキーボード(RGBライトを備えたキーボード、オーディオを備えたキーボード、LEDの数が異なる、コントローラ上の異なるPINに接続されているなど)がある場合にも役立ちます。
|
||||
|
||||
## 設定オプション (`config.h`)
|
||||
|
||||
さらに、ここにある `config.h` はキーマップフォルダ内の同名のファイルと同じように処理されます。これは `<name>.h` ファイルとは別個に処理されます。
|
||||
|
||||
この理由は、`<name>.h` は (`#define TAPPING_TERM 100` などのような)設定を追加する時には追加されず、`config.h` ファイル内の `<name.h>` ファイルを含めるとコンパイルの問題を引き起こすからです。
|
||||
|
||||
!>`config.h` は[設定オプション](ja/config_options.md)のために使い、`<name>.h` ファイルはユーザあるいは(レイヤーあるいはキーコードのための enum のような)キーマップ固有の設定のために使うべきです
|
||||
|
||||
|
||||
## Readme (`readme.md`)
|
||||
|
||||
作者情報 (あなたの名前、GitHub ユーザ名、eメール)およびオプションで[GPL 互換のライセンス](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses)を含めてください。
|
||||
|
||||
以下をテンプレートとして使うことができます:
|
||||
```
|
||||
Copyright <year> <name> <email> @<github_username>
|
||||
|
||||
This program is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU General Public License as published by
|
||||
the Free Software Foundation, either version 2 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||||
```
|
||||
|
||||
年、名前、eメールおよび GitHub ユーザ名をあなたの情報に置き換えます。
|
||||
|
||||
さらに、コードを他の人に共有したい場合、ここはコードを文章化するのに適した場所です。
|
||||
|
||||
## 特定のキーマップをサポートする全てのキーボードをビルドする
|
||||
|
||||
1つのコマンドで全てのキーマップのビルドを確認したいですか？以下で実行することができます:
|
||||
|
||||
make all:<name>
|
||||
|
||||
例えば、
|
||||
|
||||
make all:jack
|
||||
|
||||
これは、[_プルリクエスト_](https://github.com/qmk/qmk_firmware/pulls) を準備する時に全てが正常にコンパイルされることを確認したい場合に最適です。
|
||||
|
||||
## 例
|
||||
|
||||
簡単な例については、[`/users/_example/`](https://github.com/qmk/qmk_firmware/tree/master/users/_example) を調べてください。
|
||||
より複雑な例については、[`/users/drashna/`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna) のユーザスペースを調べてください。
|
||||
|
||||
|
||||
### カスタマイズされた関数 :id=customized-functions
|
||||
|
||||
QMK には、[`_quantum`、`_kb` および `_user` バージョン](ja/custom_quantum_functions.md#a-word-on-core-vs-keyboards-vs-keymap)を持つ使用可能な[関数](custom_quantum_functions.md)が山ほどあります。 ほとんどの場合、これらの関数のユーザバージョンを使う必要があります。しかし問題はそれらをユーザスペースで使う場合、キーマップで使うことができるバージョンが無いことです。
|
||||
|
||||
しかし、実際にはキーマップバージョンのサポートを追加し、ユーザスペースとキーマップの両方で使うことができます。
|
||||
|
||||
|
||||
例えば、`layer_state_set_user()` 関数を見てみましょう。全てのキーボードで [Tri Layer State](ja/ref_functions.md#olkb-tri-layers) 機能を有効にしながら、`keymap.c` ファイルで Tri Layer 機能を保持することができます。
|
||||
|
||||
`<name.c>` ファイル内で、以下を追加する必要があります:
|
||||
```c
|
||||
__attribute__ ((weak))
|
||||
layer_state_t layer_state_set_keymap (layer_state_t state) {
|
||||
return state;
|
||||
}
|
||||
|
||||
layer_state_t layer_state_set_user (layer_state_t state) {
|
||||
state = update_tri_layer_state(state, 2, 3, 5);
|
||||
return layer_state_set_keymap (state);
|
||||
}
|
||||
```
|
||||
`__attribute__ ((weak))` 部分は、コンパイラにこれが `keymap.c` 内のバージョンに置き換えられるプレースホルダ関数であることを伝えます。そうすれば、`keymap.c` に追加する必要はありませんが、追加しても関数が同じ名前を持つため競合することはありません。
|
||||
|
||||
ここでの `_keymap` 部分は重要では無く、`_quantum`、`_kb` あるいは `_user` は既に使われているため、それら以外のものである必要があります。`layer_state_set_mine`、`layer_state_set_fn` などを使うことができます。
|
||||
|
||||
[`users/drashna`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna) 内の [`template.c`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.c) でこのリストと他の一般的な関数を見つけることができます。
|
||||
|
||||
### カスタム機能
|
||||
|
||||
ユーザスペース機能は膨大な数のキーボードをサポートすることができるため、特定の機能は有効にしたいが、他のキーボードでは有効にしたくないかもしれません。そして実際に自分のユーザスペースで有効あるいは無効にすることができる「機能」を作成することができます。
|
||||
|
||||
例えば、(スペースを節約するために)特定のキーボードでのみたくさんのマクロを利用したい場合、それらを `#ifdef MACROS_ENABLED` して「見えないように」してから、キーボードごとに有効にすることができます。これを行うには、以下を rules.mk に追加します。
|
||||
```make
|
||||
ifeq ($(strip $(MACROS_ENABLED)), yes)
|
||||
OPT_DEFS += -DMACROS_ENABLED
|
||||
endif
|
||||
```
|
||||
`OPT_DEFS` 設定は `MACROS_ENABLED` がキーボード用に定義されるようにし(名前の前に `-D` があることに注意してください)、c/h ファイルで状態をチェックするために `#ifdef MACROS_ENABLED` を使うことができ、それに基づいてそのコードを処理します。
|
||||
|
||||
次にキーマップの `rules.mk` に `MACROS_ENABLED = yes` を追加し、ユーザスペースでこの機能とコードを有効にします。
|
||||
|
||||
そして `process_record_user` 関数の中で、以下のようなことを行います:
|
||||
```c
|
||||
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
|
||||
switch (keycode) {
|
||||
#ifdef MACROS_ENABLED
|
||||
case MACRO1:
|
||||
if (!record->event.pressed) {
|
||||
SEND_STRING("This is macro 1!");
|
||||
}
|
||||
break;
|
||||
case MACRO2:
|
||||
if (!record->event.pressed) {
|
||||
SEND_STRING("This is macro 2!");
|
||||
}
|
||||
break;
|
||||
#endif
|
||||
}
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### 結合マクロ
|
||||
|
||||
全てのキーマップについてユーザスペースにマクロやそのほかの関数を統合したい場合は、そうすることができます。これは上記の[カスタマイズ関数](#customized-functions)の例に基づいています。これは異なるキーボード間で共有される大量のマクロを維持し、キーボード固有のマクロも可能です。
|
||||
|
||||
最初に、全ての `keymap.c` ファイルを調べ、代わりに `process_record_user` を `process_record_keymap` に置き換えます。この方法では、これらのキーボードでキーボード固有のコードを使用でき、カスタムの "global" キーコードも使うことができます。また、`SAFE_RANGE` を `NEW_SAFE_RANGE` に置き換えて、キーコードが重複しないようにすることもできます。
|
||||
|
||||
次に、全ての keymap.c ファイルに `#include "<name>.h"` を追加します。これにより、各キーマップでそれらを再定義することなく新しいキーコードを使うことができます。
|
||||
|
||||
それが完了したら、必要なキーコードの定義を `<name>.h` ファイルに設定します。例えば:
|
||||
```c
|
||||
#pragma once
|
||||
|
||||
#include "quantum.h"
|
||||
#include "action.h"
|
||||
#include "version.h"
|
||||
|
||||
// 全てを定義
|
||||
enum custom_keycodes {
|
||||
KC_MAKE = SAFE_RANGE,
|
||||
NEW_SAFE_RANGE // キーマップ固有のコードについては "NEW_SAFE_RANGE" を使用
|
||||
};
|
||||
```
|
||||
|
||||
ここで、`<name>.c` ファイルを作成し、この内容をそれに追加します:
|
||||
|
||||
```c
|
||||
#include "<name>.h"
|
||||
|
||||
__attribute__ ((weak))
|
||||
bool process_record_keymap(uint16_t keycode, keyrecord_t *record) {
|
||||
return true;
|
||||
}
|
||||
|
||||
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
|
||||
switch (keycode) {
|
||||
case KC_MAKE: // ファームウェアをコンパイルし、キーボードのブートローダに基づく書き込みコマンドを追加します
|
||||
if (!record->event.pressed) {
|
||||
uint8_t temp_mod = get_mods();
|
||||
uint8_t temp_osm = get_oneshot_mods();
|
||||
clear_mods(); clear_oneshot_mods();
|
||||
SEND_STRING("make " QMK_KEYBOARD ":" QMK_KEYMAP);
|
||||
#ifndef FLASH_BOOTLOADER
|
||||
if ((temp_mod | temp_osm) & MOD_MASK_SHIFT)
|
||||
#endif
|
||||
{
|
||||
SEND_STRING(":flash");
|
||||
}
|
||||
if ((temp_mod | temp_osm) & MOD_MASK_CTRL) {
|
||||
SEND_STRING(" -j8 --output-sync");
|
||||
}
|
||||
tap_code(KC_ENT);
|
||||
set_mods(temp_mod);
|
||||
}
|
||||
break;
|
||||
|
||||
}
|
||||
return process_record_keymap(keycode, record);
|
||||
}
|
||||
```
|
||||
|
||||
(マクロパッドのような) Shift ボタンを持たないキーボードについては、ブートローダオプションを常に含める方法が必要です。これを行うには、以下をユーザスペースフォルダ内の `rules.mk` に追加します:
|
||||
|
||||
```make
|
||||
ifeq ($(strip $(FLASH_BOOTLOADER)), yes)
|
||||
OPT_DEFS += -DFLASH_BOOTLOADER
|
||||
endif
|
||||
```
|
||||
|
||||
これは任意のキーマップで使うことができる新しい `KC_MAKE` キーコードを追加します。そして、このキーコードは、`make <keyboard>:<keymap>` を出力するため、頻繁なコンパイルを簡単にします。そして、これは現在のキーボードの情報を出力するため、全てのキーボードとキーマップで動作します。そのため毎回これを入力する必要はありません。
|
||||
|
||||
また、Shift を押したままにすると書き込みの対象 (`:flash`) をコマンドに追加します。Control を押したままにすると、複数のファイルを一度に処理することでコンパイル時間を短縮する幾つかのコマンドを追加します。
|
||||
|
||||
そして Shift キーが無いキーボード、あるいは常に書き込みを試したいキーボードについては、キーマップの `rules.mk` に `FLASH_BOOTLOADER = yes` を追加することができます。
|
||||
|
||||
?> これはブートローダの設定に基づいて正しいユーティリティを使って新しくコンパイルされたファームウェアを自動的に書き込むはずです (あるいはデフォルトで HEX ファイルを生成するだけ)。ただし、これは全てのシステムで動作するわけではないことに注意してください。はっきり言うと、AVRDUDE は WSL では動作しません。そして、これは BootloadHID あるいは mdloader をサポートしません。
|
||||
@ -1,34 +0,0 @@
|
||||
# Velocikey
|
||||
|
||||
<!---
|
||||
original document: 0.8.147:docs/feature_velocikey.md
|
||||
git diff 0.8.147 HEAD -- docs/feature_velocikey.md | cat
|
||||
-->
|
||||
|
||||
Velocikey は入力の速度を使って(レインボー渦巻効果のような)ライト効果の速度を制御できる機能です。速く入力すればするほどライトが速くなります！
|
||||
|
||||
## 使用法
|
||||
Velocikey を使うためには、2つのステップがあります。最初に、キーボードをコンパイルする時に、`rules.mk` に `VELOCIKEY_ENABLE=yes` を設定する必要があります。例えば:
|
||||
|
||||
```
|
||||
MOUSEKEY_ENABLE = no
|
||||
STENO_ENABLE = no
|
||||
EXTRAKEY_ENABLE = yes
|
||||
VELOCIKEY_ENABLE = yes
|
||||
```
|
||||
|
||||
次に、キーボードの使用中に、VLK_TOG キーコードを使って Velocikey を有効にする必要もあります。これは機能をオンおよびオフにします。
|
||||
|
||||
以下の全てのライト効果が、Velocikey を有効にすることで制御されます:
|
||||
- RGB 明滅動作
|
||||
- RGB レインボームード
|
||||
- RGB レインボー渦巻
|
||||
- RGB スネーク
|
||||
- RGB ナイト
|
||||
|
||||
LED 明滅動作の効果のサポートは計画されていますがまだ利用できません。
|
||||
|
||||
Velocikey が有効になっている限り、現在オンになっている RGB ライトの他の全ての速度設定に関係なく、速度が制御されます。
|
||||
|
||||
## 設定
|
||||
Velocikey は現在のところキーボード設定を介したどのような設定もサポートしません。速度の増加あるいは減少率などを調整したい場合は、`velocikey.c` を編集し、そこで値を調整して、好みの速度を実現する必要があります。
|
||||
@ -1,24 +0,0 @@
|
||||
# Word Per Minute (WPM) の計算
|
||||
|
||||
<!---
|
||||
original document: 0.9.0:docs/feature_wpm.md
|
||||
git diff 0.9.0 HEAD -- docs/feature_wpm.md | cat
|
||||
-->
|
||||
|
||||
WPM 機能は、キーストローク間の時間から1分あたりの平均（移動平均）単語数を計算し、様々な用途で利用できるようにします。
|
||||
|
||||
`rules.mk` に以下を追加することで WPM システムを有効にします:
|
||||
|
||||
WPM_ENABLE = yes
|
||||
|
||||
ソフトシリアルを使っている分割キーボードについては、計算された WPM スコアがマスター側とスレーブ側で利用可能です。
|
||||
|
||||
## 公開関数
|
||||
|
||||
`uint8_t get_current_wpm(void);`
|
||||
この関数は符号なし整数で現在の WPM を返します。
|
||||
|
||||
|
||||
## WPM 計算のためのカスタマイズ化されたキー
|
||||
|
||||
デフォルトでは、WPM スコアは文字、空白、およびいくつかの句読点のみを含みます。WPM の計算に含むとみなす文字セットを変更したい場合は、`wpm_keycode_user(uint16_t keycode)` を実装し、計算に含めたい文字について true を返し、計算しない特定のキーコードに false を返すようにします。
|
||||
@ -1,247 +0,0 @@
|
||||
# 書き込みの手順とブートローダ情報
|
||||
|
||||
<!---
|
||||
original document: 0.10.33:docs/flashing.md
|
||||
git diff 0.10.33 HEAD -- docs/flashing.md | cat
|
||||
-->
|
||||
|
||||
キーボードが使用するブートローダにはかなり多くの種類があり、ほぼ全てが異なる書き込みの方法を使います。幸いなことに、[QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) のようなプロジェクトは、あまり深く考える必要無しに様々なタイプと互換性を持つことを目指していますが、この文章では様々なタイプのブートローダとそれらを書き込むために利用可能な方法について説明します。
|
||||
|
||||
`rules.mk` の `BOOTLOADER` 変数で選択されたブートローダがある場合、QMK は .hex ファイルがデバイスに書き込むのに適切なサイズかどうかを自動的に計算し、合計サイズをバイト単位で(最大値とともに)出力します。
|
||||
|
||||
## DFU
|
||||
|
||||
Atmel の DFU ブートローダはデフォルトで全ての atmega32u4 チップに搭載されており、PCB (旧 OLKB キーボード、Clueboard) に独自の IC を持つ多くのキーボードで使われています。一部のキーボードは、LUFA の DFU ブートローダ(または QMK のフォーク) (新しい OLKB キーボード)を使う場合もあり、そのハードウェアに固有の追加機能が追加されます。
|
||||
|
||||
DFU ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください(オプションとして代わりに `lufa-dfu` や `qmk-dfu` が使えます):
|
||||
|
||||
```make
|
||||
# Bootloader selection
|
||||
# Teensy halfkay
|
||||
# Pro Micro caterina
|
||||
# Atmel DFU atmel-dfu
|
||||
# LUFA DFU lufa-dfu
|
||||
# QMK DFU qmk-dfu
|
||||
# ATmega32A bootloadHID
|
||||
# ATmega328P USBasp
|
||||
BOOTLOADER = atmel-dfu
|
||||
```
|
||||
|
||||
互換性のあるフラッシャ:
|
||||
|
||||
* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI)
|
||||
* QMK の [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` (推奨のコマンドライン)
|
||||
|
||||
書き込み手順:
|
||||
|
||||
1. `QK_BOOT` キーコードを押すか、RESET ボタンをタップします(または RST を GND にショートします)。
|
||||
2. OS がデバイスを検知するのを待ちます。
|
||||
3. メモリを消去します(自動的に実行されるかもしれません)
|
||||
4. .hex ファイルを書き込みます
|
||||
5. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません)
|
||||
|
||||
あるいは:
|
||||
|
||||
make <keyboard>:<keymap>:dfu
|
||||
|
||||
### QMK DFU
|
||||
|
||||
QMK には LUFA DFU ブートローダのフォークがあり、ブートローダを終了してアプリケーションに戻る時に単純なマトリックススキャンを行うことができます。また、何かが起きた時に、LED を点滅したり、スピーカーでカチカチ音をたてたりします。これらの機能を有効にするには、`config.h` で以下のブロックを有効にします (ブートローダを終了するキーは、ここで定義された INPUT と OUTPUT に接続する必要があります):
|
||||
|
||||
#define QMK_ESC_OUTPUT F1 // 通常 COL
|
||||
#define QMK_ESC_INPUT D5 // 通常 ROW
|
||||
#define QMK_LED E6
|
||||
#define QMK_SPEAKER C6
|
||||
|
||||
製造元と製品名は `config.h` から自動的に取得され、製品に「Bootloader」が追加されます。
|
||||
|
||||
このブートローダを生成するには、`bootloader` ターゲット、例えば `make planck/rev4:default:bootloader` を使います。
|
||||
|
||||
実稼働対応の .hex ファイル(アプリケーションおよびブートローダを含む)を生成するには、`production` ターゲット、例えば `make planck/rev4:default:production` を使います。
|
||||
|
||||
### DFU コマンド
|
||||
|
||||
ファームウェアを DFU デバイスに書き込むために使用できる DFU コマンドがいくつかあります。
|
||||
|
||||
* `:dfu` - これが通常のオプションで、DFU デバイスが使用可能になるまで待機したのちファームウェアを書き込みます。5秒ごとに、DFU デバイスが存在するかチェックしています。
|
||||
* `:dfu-ee` - 通常の hex ファイルの代わりに `eep` ファイルを書き込みます。これを使用するのはまれです。
|
||||
* `:dfu-split-left` - デフォルトオプション (`:dfu`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROM ファイルも書き込まれます。_これは、Elite C ベースの分割キーボードに最適です。_
|
||||
* `:dfu-split-right` - デフォルトオプション (`:dfu`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」 EEPROM ファイルも書き込まれます。_これは、Elite C ベースの分割キーボードに最適です。_
|
||||
|
||||
## Caterina
|
||||
|
||||
Arduino ボードとそのクローンは [Caterina ブートローダ](https://github.com/arduino/ArduinoCore-avr/tree/master/bootloaders/caterina) (Pro Micro またはそのクローンで構築されたキーボード)を使用し、avr109 プロトコルを使って仮想シリアルを介して通信します。[A-Star](https://www.pololu.com/docs/0J61/9) のようなブートローダは Caterina に基づいています。
|
||||
|
||||
Caterina ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください:
|
||||
|
||||
```make
|
||||
# Bootloader selection
|
||||
# Teensy halfkay
|
||||
# Pro Micro caterina
|
||||
# Atmel DFU atmel-dfu
|
||||
# LUFA DFU lufa-dfu
|
||||
# QMK DFU qmk-dfu
|
||||
# ATmega32A bootloadHID
|
||||
# ATmega328P USBasp
|
||||
BOOTLOADER = caterina
|
||||
```
|
||||
|
||||
互換性のあるフラッシャ:
|
||||
|
||||
* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI)
|
||||
* avr109 を使った [avrdude](https://www.nongnu.org/avrdude/) / `:avrdude` (推奨のコマンドライン)
|
||||
* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)
|
||||
|
||||
書き込み手順:
|
||||
|
||||
1. `QK_BOOT` キーコードを押すか、RST をすばやく GND にショートします (入力後7秒で書き込みます)
|
||||
2. OS がデバイスを検知するのを待ちます。
|
||||
3. .hex ファイルを書き込みます
|
||||
4. デバイスが自動的にリセットされるのを待ちます
|
||||
|
||||
あるいは
|
||||
|
||||
make <keyboard>:<keymap>:avrdude
|
||||
|
||||
|
||||
### Caterina コマンド
|
||||
|
||||
ファームウェアを DFU デバイスに書き込むために使用できる DFU コマンドがいくつかあります。
|
||||
|
||||
* `:avrdude` - これが通常のオプションで、Caterina デバイスが(新しい COM ポートを検出して)使用可能になるまで待機し、ファームウェアを書き込みます。
|
||||
* `:avrdude-loop` - これは `:avrdude` と同じコマンドを実行します。ただし書き込みが終了すると再び Caterina デバイスの書き込み待ちに戻ります。これは何台ものデバイスへ書き込むのに便利です。_Ctrl+C を押して、手動でこの繰り返しを終了させる必要があります。_
|
||||
* `:avrdude-split-left` - デフォルトオプション (`:avrdude`) と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROM ファイルも書き込まれます。_これは、Pro Micro ベースの分割キーボードに最適です。_
|
||||
* `:avrdude-split-right` - デフォルトオプション (`:avrdude`) と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」 EEPROM ファイルも書き込まれます。_これは、Pro Micro ベースの分割キーボードに最適です。_
|
||||
|
||||
|
||||
|
||||
## Halfkay
|
||||
|
||||
Halfkay は PJRC によって開発された超スリムなプロトコルであり、HID を使用し、全ての Teensys (つまり 2.0)に搭載されています。
|
||||
|
||||
Halfkay ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください:
|
||||
|
||||
```make
|
||||
# Bootloader selection
|
||||
# Teensy halfkay
|
||||
# Pro Micro caterina
|
||||
# Atmel DFU atmel-dfu
|
||||
# LUFA DFU lufa-dfu
|
||||
# QMK DFU qmk-dfu
|
||||
# ATmega32A bootloadHID
|
||||
# ATmega328P USBasp
|
||||
BOOTLOADER = halfkay
|
||||
```
|
||||
|
||||
互換性のあるフラッシャ:
|
||||
|
||||
* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI)
|
||||
* [Teensy ローダー](https://www.pjrc.com/teensy/loader.html)
|
||||
* [Teensy ローダーコマンドライン](https://www.pjrc.com/teensy/loader_cli.html) (推奨のコマンドライン)
|
||||
|
||||
書き込み手順:
|
||||
|
||||
1. `QK_BOOT` キーコードを押すか、RST をすばやく GND にショートします (入力後7秒で書き込みます)
|
||||
2. OS がデバイスを検知するのを待ちます。
|
||||
3. .hex ファイルを書き込みます
|
||||
4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません)
|
||||
|
||||
## USBasploader
|
||||
|
||||
USBasploader は matrixstorm によって開発されたブートローダです。V-USB を実行する ATmega328P のような非 USB AVR チップで使われます。
|
||||
|
||||
USBasploader ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください:
|
||||
|
||||
```make
|
||||
# Bootloader selection
|
||||
# Teensy halfkay
|
||||
# Pro Micro caterina
|
||||
# Atmel DFU atmel-dfu
|
||||
# LUFA DFU lufa-dfu
|
||||
# QMK DFU qmk-dfu
|
||||
# ATmega32A bootloadHID
|
||||
# ATmega328P USBasp
|
||||
BOOTLOADER = USBasp
|
||||
```
|
||||
|
||||
互換性のあるフラッシャ:
|
||||
|
||||
* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI)
|
||||
* `usbasp` プログラマを使った [avrdude](https://www.nongnu.org/avrdude/)
|
||||
* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)
|
||||
|
||||
書き込み手順:
|
||||
|
||||
1. `QK_BOOT` キーコードを押すか、RST を GND にすばやくショートしながら、ブートピンを GND にショートしたままにします。
|
||||
2. OS がデバイスを検知するのを待ちます。
|
||||
3. .hex ファイルを書き込みます
|
||||
4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません)
|
||||
|
||||
## BootloadHID
|
||||
|
||||
BootloadHID は AVR マイクロコントローラ用の USB ブートローダです。アップローダーツールは Windows でカーネルレベルのドライバを必要としないため、DLL をインストールせずに実行することができます。
|
||||
|
||||
bootloadHID ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください:
|
||||
|
||||
```make
|
||||
# Bootloader selection
|
||||
# Teensy halfkay
|
||||
# Pro Micro caterina
|
||||
# Atmel DFU atmel-dfu
|
||||
# LUFA DFU lufa-dfu
|
||||
# QMK DFU qmk-dfu
|
||||
# ATmega32A bootloadHID
|
||||
# ATmega328P USBasp
|
||||
BOOTLOADER = bootloadHID
|
||||
```
|
||||
|
||||
互換性のあるフラッシャ:
|
||||
|
||||
* [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) (推奨の Windows GUI)
|
||||
* [bootloadhid コマンドライン](https://www.obdev.at/products/vusb/bootloadhid.html) / QMK の `:BootloadHID` (推奨のコマンドライン)
|
||||
|
||||
書き込み手順:
|
||||
|
||||
1. 以下のいずれかの方法を使ってブートローダに入ります:
|
||||
* `QK_BOOT` キーコードをタップします (全てのデバイスでは動作しないかもしれません)
|
||||
* キーボードを接続しながらソルトキーを押し続けます (通常はキーボードの readme に書かれています)
|
||||
2. OS がデバイスを検知するのを待ちます。
|
||||
3. .hex ファイルを書き込みます
|
||||
4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません)
|
||||
|
||||
あるいは:
|
||||
|
||||
make <keyboard>:<keymap>:bootloadHID
|
||||
|
||||
## STM32
|
||||
|
||||
全ての STM32 チップには、変更も削除もできない工場出荷時のブートローダがプリロードされています。一部の STM32 チップには USB プログラミングが付属していないブートローダがありますが(例えば STM32F103)、プロセスは同じです。
|
||||
|
||||
現時点では、STM32 の `rules.mk` には、`BOOTLOADER` 変数は不要です。
|
||||
|
||||
互換性のあるフラッシャ:
|
||||
|
||||
* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI)
|
||||
* [dfu-util](https://github.com/Stefan-Schmidt/dfu-util) / `:dfu-util` (推奨のコマンドライン)
|
||||
|
||||
書き込み手順:
|
||||
|
||||
1. 以下のいずれかの方法を使ってブートローダに入ります:
|
||||
* `QK_BOOT` キーコードをタップします (STM32F042 デバイスでは動作しないかもしれません)
|
||||
* リセット回路が存在する場合、RESET ボタンをタップします
|
||||
* それ以外の場合は、(BOOT0 ボタンあるいはブリッジ経由で)BOOT0 を VCC にブリッジし、(REEST ボタンあるいはブリッジ経由で)RESET を GND にショートし、BOOT0 ブリッジを放す必要があります。
|
||||
2. OS がデバイスを検知するのを待ちます。
|
||||
3. .bin ファイルを書き込みます
|
||||
* DFU 署名に関する警告が表示されます; 無視してください
|
||||
4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません)
|
||||
* コマンドラインからビルドする場合(例えば、`make planck/rev6:default:dfu-util`)、`rules.mk` の中で `:leave` が `DFU_ARGS` 変数に渡されるようにしてください (例えば、`DFU_ARGS = -d 0483:df11 -a 0 -s 0x08000000:leave`)。そうすれば、書き込みの後でデバイスがリセットされます
|
||||
|
||||
### STM32 コマンド
|
||||
|
||||
ファームウェアを STM32 デバイスに書き込むために使用できる DFU コマンドがいくつかあります。
|
||||
|
||||
* `:dfu-util` - STM32 デバイスに書き込むためのデフォルトコマンドで、STM32 ブートローダデバイスが見つかるまで待機します。
|
||||
* `:dfu-util-split-left` - デフォルトのオプション (`:dfu-util`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROM の設定も行われます。
|
||||
* `:dfu-util-split-right` - デフォルトのオプション (`:dfu-util`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」 EEPROM の設定も行われます。
|
||||
* `:st-link-cli` - dfu-util ではなく、ST-LINK の CLI ユーティリティを介してファームウェアを書き込めます。
|
||||
* `:st-flash` - dfu-util ではなく、[STLink Tools](https://github.com/stlink-org/stlink) の `st-flash` ユーティリティを介してファームウェアを書き込めます。
|
||||
@ -1,75 +0,0 @@
|
||||
# BootloadHID の書き込み手順とブートローダの情報
|
||||
|
||||
<!---
|
||||
original document: 0.9.32:docs/flashing_bootloadhid.md
|
||||
git diff 0.9.32 HEAD -- docs/flashing_bootloadhid.md | cat
|
||||
-->
|
||||
|
||||
ps2avr(GB) キーボードは ATmega32A マイクロコントローラを使い、異なるブートローダを使います。それは通常の QMK の方法を使って書き込むことができません。
|
||||
|
||||
一般的な書き込みシーケンス:
|
||||
|
||||
1. 以下のいずれかの方法を使ってブートローダに入ります:
|
||||
* `QK_BOOT` キーコードをタップします (全てのデバイスでは動作しないかもしれません)
|
||||
* ソルトキーを押し続けながらキーボードを接続します (通常はキーボードの readme に書かれています)
|
||||
2. OS がデバイスを検知するのを待ちます。
|
||||
3. .hex ファイルを書き込みます
|
||||
4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません)
|
||||
|
||||
## bootloadHID の書き込みターゲット
|
||||
|
||||
?> [こちら](ja/newbs_getting_started.md)で詳しく説明されている QMK インストールスクリプトを使うと、必要な bootloadHID ツールが自動的にインストールされます。
|
||||
|
||||
コマンドライン経由で書き込むには、以下のコマンドを実行してターゲット `:bootloadHID` を使います:
|
||||
|
||||
make <keyboard>:<keymap>:bootloadHID
|
||||
|
||||
## GUI 書き込み
|
||||
|
||||
### Windows
|
||||
1. [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) をダウンロードします。
|
||||
2. キーボードをリセットします。
|
||||
3. 設定された VendorID が `16c0` で、ProductID が `05df` であることを確認します
|
||||
4. `Find Device` ボタンを押し、キーボードが見つかることを確認します。
|
||||
5. `Open .hex File` ボタンを押し、作成した `.hex` ファイルを見つけます。
|
||||
6. `Flash Device` ボタンを押し、処理が完了するまで待ちます。
|
||||
|
||||
## コマンドライン書き込み
|
||||
|
||||
1. キーボードをリセットします。
|
||||
2. `bootloadHID -r` に続けて `.hex` ファイルへのパスを入力し、キーボードに書き込みます。
|
||||
|
||||
### Windows 手動インストール
|
||||
MSYS2の場合:
|
||||
1. https://www.obdev.at/downloads/vusb/bootloadHID.2012-12-08.tar.gz から BootloadHID ファームウェアパッケージをダウンロードします。
|
||||
2. 互換性のあるツール、例えば 7-Zip を使って内容を抽出します。
|
||||
3. 解凍された書庫から MSYS2 インストール先、通常 `C:\msys64\usr\bin` に `commandline/bootloadHID.exe` をコピーして、MSYS パスに追加します。
|
||||
|
||||
ネイティブの Windows 書き込みの場合、MSYS2 環境の外部で `bootloadHID.exe` を使うことができます。
|
||||
|
||||
### Linux 手動インストール
|
||||
1. libusb development の依存関係をインストールします:
|
||||
```bash
|
||||
# これは OS に依存します - Debian については以下で動作します
|
||||
sudo apt-get install libusb-dev
|
||||
```
|
||||
2. BootloadHID ファームウェアパッケージをダウンロードします:
|
||||
```
|
||||
wget https://www.obdev.at/downloads/vusb/bootloadHID.2012-12-08.tar.gz -O - | tar -xz -C /tmp
|
||||
```
|
||||
3. bootloadHID 実行可能ファイルをビルドします:
|
||||
```
|
||||
cd /tmp/bootloadHID.2012-12-08/commandline/
|
||||
make
|
||||
sudo cp bootloadHID /usr/local/bin
|
||||
```
|
||||
|
||||
### MacOS 手動インストール
|
||||
1. 以下を入力して Homebrew をインストールします:
|
||||
```
|
||||
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
|
||||
```
|
||||
2. 以下のパッケージをインストールします:
|
||||
```
|
||||
brew install --HEAD https://raw.githubusercontent.com/robertgzr/homebrew-tap/master/bootloadhid.rb
|
||||
```
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user