mirror of
https://github.com/qmk/qmk_firmware.git
synced 2024-12-01 23:45:54 +00:00
32 lines
119 KiB
HTML
32 lines
119 KiB
HTML
|
<!DOCTYPE html>
|
|||
|
|
<html lang="en-US" dir="ltr">
|
|||
|
|
<head>
|
|||
|
|
<meta charset="utf-8">
|
|||
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
|||
|
|
<title>Stenography in QMK | QMK Firmware</title>
|
|||
|
|
<meta name="description" content="Documentation for QMK Firmware">
|
|||
|
|
<meta name="generator" content="VitePress v1.1.3">
|
|||
|
|
<link rel="preload stylesheet" href="/assets/style.No8zk9aC.css" as="style">
|
|||
|
|
|
|||
|
|
<script type="module" src="/assets/app.DQznqO_F.js"></script>
|
|||
|
|
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
|
|||
|
|
<link rel="modulepreload" href="/assets/chunks/framework.DyMmIvSC.js">
|
|||
|
|
<link rel="modulepreload" href="/assets/chunks/theme.BbG4GfFx.js">
|
|||
|
|
<link rel="modulepreload" href="/assets/features_stenography.md.Bb_IhUGl.lean.js">
|
|||
|
|
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
|
|||
|
|
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
|
|||
|
|
</head>
|
|||
|
|
<body>
|
|||
|
|
<div id="app"><div class="Layout" data-v-5d98c3a5><!--[--><!--]--><!--[--><span tabindex="-1" data-v-0f60ec36></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-0f60ec36> Skip to content </a><!--]--><!----><header class="VPNav" data-v-5d98c3a5 data-v-ae24b3ad><div class="VPNavBar has-sidebar top" data-v-ae24b3ad data-v-ccf7ddec><div class="wrapper" data-v-ccf7ddec><div class="container" data-v-ccf7ddec><div class="title" data-v-ccf7ddec><div class="VPNavBarTitle has-sidebar" data-v-ccf7ddec data-v-ab179fa1><a class="title" href="/" data-v-ab179fa1><!--[--><!--]--><!--[--><!--[--><!--[--><img class="VPImage dark logo" src="/qmk-logo-dark.svg" alt data-v-8426fc1a><!--]--><!--[--><img class="VPImage light logo" src="/qmk-logo-light.svg" alt data-v-8426fc1a><!--]--><!--]--><!--]--><span data-v-ab179fa1>QMK Firmware</span><!--[--><!--]--></a></div></div><div class="content" data-v-ccf7ddec><div class="content-body" data-v-ccf7ddec><!--[--><!--]--><div class="VPNavBarSearch search" data-v-ccf7ddec><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-ccf7ddec data-v-7f418b0f><span id="main-nav-aria-label" class="visually-hidden" data-v-7f418b0f>Main Navigation</span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="./" tabindex="0" data-v-7f418b0f data-v-9c663999><!--[--><span data-v-9c663999>Home</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-ccf7ddec data-v-e6aabb21><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title="Switch to dark theme" aria-checked="false" data-v-e6aabb21 data-v-d1f28634 data-v-1d5665e3><span class="check" data-v-1d5665e3><span class="icon" data-v-1d5665e3><!--[--><span class="vpi-sun sun" data-v-d1f28634></span><span class="vpi-moon moon" data-v-d1f28634></span><!--]--></span></span></button></div><div class="VPSocialLinks VPNavBarSocialLinks social-links" data-v-ccf7ddec data-v-0394ad82 data-v-7bc22406><!--[--><a class="VPSocialLink no-icon" href="https://reddit.com/r/olkb" aria-label target="_blank" rel="noopener" data-v-7bc22406 data-v-eee4e7cb><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 50 50" width="50px" height="50px"><path d="M 29 3 C 28.0625 3 27.164063 3.382813 26.5 4 C 25.835938 4.617188 25.363281 5.433594 25 6.40625 C 24.355469 8.140625 24.085938 10.394531 24.03125 13.03125 C 19.234375 13.179688 14.820313 14.421875 11.28125 16.46875 C 10.214844 15.46875 8.855469 14.96875 7.5 14.96875 C 6.089844 14.96875 4.675781 15.511719 3.59375 16.59375 C 1.425781 18.761719 1.425781 22.238281 3.59375 24.40625 L 3.84375 24.65625 C 3.3125 26.035156 3 27.488281 3 29 C 3 33.527344 5.566406 37.585938 9.5625 40.4375 C 13.558594 43.289063 19.007813 45 25 45 C 30.992188 45 36.441406 43.289063 40.4375 40.4375 C 44.433594 37.585938 47 33.527344 47 29 C 47 27.488281 46.6875 26.035156 46.15625 24.65625 L 46.40625 24.40625 C 48.574219 22.238281 48.574219 18.761719 46.40625 16.59375 C 45.324219 15.511719 43.910156 14.96875 42.5 14.96875 C 41.144531 14.96875 39.785156 15.46875 38.71875 16.46875 C 35.195313 14.433594 30.800781 13.191406 26.03125 13.03125 C 26.09375 10.546875 26.363281 8.46875 26.875 7.09375 C 27.164063 6.316406 27.527344 5.757813 27.875 5.4375 C 28.222656 5.117188 28.539063 5 29 5 C 29.460938 5 29.683594 5.125 30.03125 5.40625 C 30.378906 5.6875 30.785156 6.148438 31.3125 6.6875 C 32.253906 7.652344 33.695313 8.714844 36.09375 8.9375 C 36.539063 11.238281 38.574219 13 41 13 C 43.75 13 46 10.75 46 8 C 46 5.25 43.75 3 41 3 C 38.605469 3 36.574219 4.710938 36.09375 6.96875 C 34.3125 6.796875 33.527344 6.109375 32.75 5.3125 C 32.300781 4.851563 31.886719
|
|||
|
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">STENO_PROTOCOL = txbolt</span></span></code></pre></div><p>Each byte of the packet represents a different group of steno keys. Determining the group of a certain byte of the packet is done by checking the first two bits, the remaining bits are set if the corresponding steno key was pressed for the stroke. The last set of keys (as indicated by leading <code>11</code>) needs to keep track of less keys than there are bits so one of the bits is constantly 0.</p><p>The start of a new packet can be detected by comparing the group “ID” (the two MSBs) of the current byte to that of the previously received byte. If the group “ID” of the current byte is smaller or equal to that of the previous byte, it means that the current byte is the beginning of a new packet.</p><p>The format of TX Bolt packets is shown below.</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span>00HWPKTS 01UE*OAR 10GLBPRF 110#ZDST</span></span></code></pre></div><p>Examples of steno strokes and the associated packet:</p><ul><li><code>EUBG</code> = <code>01110000 10101000</code></li><li><code>WAZ</code> = <code>00010000 01000010 11001000</code></li><li><code>PHAPBGS</code> = <code>00101000 01000010 10101100 11000010</code></li></ul><h3 id="geminipr" tabindex="-1">GeminiPR <a class="header-anchor" href="#geminipr" aria-label="Permalink to "GeminiPR {#geminipr}""></a></h3><p>GeminiPR encodes 42 keys into a 6-byte packet. While TX Bolt contains everything that is necessary for standard stenography, GeminiPR opens up many more options, including differentiating between top and bottom <code>S-</code>, and supporting non-English theories.</p><p>To select GeminiPR, add the following lines to your <code>rules.mk</code>:</p><div class="language-make vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">make</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">STENO_ENABLE = yes</span></span>
|
|||
|
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">STENO_PROTOCOL = geminipr</span></span></code></pre></div><p>All packets in the GeminiPR protocol consist of exactly six bytes, used as bit-arrays for different groups of keys. The beginning of a packet is indicated by setting the most significant bit (MSB) to 1 while setting the MSB of the remaining five bytes to 0.</p><p>The format of GeminiPR packets is shown below.</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span>1 Fn #1 #2 #3 #4 #5 #6</span></span>
|
|||
|
|
<span class="line"><span>0 S1- S2- T- K- P- W- H-</span></span>
|
|||
|
|
<span class="line"><span>0 R- A- O- *1 *2 res1 res2</span></span>
|
|||
|
|
<span class="line"><span>0 pwr *3 *4 -E -U -F -R</span></span>
|
|||
|
|
<span class="line"><span>0 -P -B -L -G -T -S -D</span></span>
|
|||
|
|
<span class="line"><span>0 #7 #8 #9 #A #B #C -Z</span></span></code></pre></div><p>Examples of steno strokes and the associated packet:</p><ul><li><code>EUBG</code> = <code>10000000 00000000 00000000 00001100 00101000 00000000</code></li><li><code>WAZ</code> = <code>10000000 00000010 00100000 00000000 00000000 00000001</code></li><li><code>PHAPBGS</code> = <code>10000000 00000101 00100000 00000000 01101010 00000000</code></li></ul><h3 id="switching-protocols-on-the-fly" tabindex="-1">Switching protocols on the fly <a class="header-anchor" href="#switching-protocols-on-the-fly" aria-label="Permalink to "Switching protocols on the fly {#switching-protocols-on-the-fly}""></a></h3><p>If you wish to switch the serial protocol used to transfer the steno chords without having to recompile your keyboard firmware every time, you can press the <code>QK_STENO_BOLT</code> and <code>QK_STENO_GEMINI</code> keycodes in order to switch protocols on the fly.</p><p>To enable these special keycodes, add the following lines to your <code>rules.mk</code>:</p><div class="language-make vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">make</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">STENO_ENABLE = yes</span></span>
|
|||
|
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">STENO_PROTOCOL = all</span></span></code></pre></div><p>If you want to switch protocols programatically, as part of a custom macro for example, don't use <code>tap_code(QK_STENO_*)</code>, as <code>tap_code</code> only supports <a href="./../keycodes_basic">basic keycodes</a>. Instead, you should use <code>steno_set_mode(STENO_MODE_*)</code>, whose valid arguments are <code>STENO_MODE_BOLT</code> and <code>STENO_MODE_GEMINI</code>.</p><p>The default protocol is Gemini PR but the last protocol used is stored in non-volatile memory so QMK will remember your choice between reboots of your keyboard — assuming that your keyboard features (emulated) EEPROM.</p><p>Naturally, this option takes the most amount of firmware space as it needs to compile the code for all the available stenography protocols. In most cases, compiling a single stenography protocol is sufficient.</p><p>The default value for <code>STENO_PROTOCOL</code> is <code>all</code>.</p><h2 id="configuring-qmk-for-steno" tabindex="-1">Configuring QMK for Steno <a class="header-anchor" href="#configuring-qmk-for-steno" aria-label="Permalink to "Configuring QMK for Steno {#configuring-qmk-for-steno}""></a></h2><p>After enabling stenography and optionally selecting a protocol, you may also need disable mouse keys, extra keys, or another USB endpoint to prevent conflicts. The builtin USB stack for some processors only supports a certain number of USB endpoints and the virtual serial port needed for steno fills 3 of them.</p><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>If you had <em>explicitly</em> set <code>VIRSTER_ENABLE = no</code>, none of the serial stenography protocols (GeminiPR, TX Bolt) will work properly. You are expected to either set it to <code>yes</code>, remove the line from your <code>rules.mk</code> or send the steno chords yourself in an alternative way using the <a href="#interfacing-with-the-code">provided interceptable hooks</a>.</p></div><p>In your keymap, create a new layer for Plover, that you can fill in with the <a href="#keycode-reference">steno keycodes</a>. Remember to create a key to switch to the layer as well as a key for exiting the layer.</p><p>Once you have your keyboard flashed, launch Plover. Click the 'Configure...' button. In the 'Machine' tab, select the Stenotype Machine that corresponds to your desired protocol. Click the 'Configure...' button on this tab and enter the serial port or click 'Scan'. Baud rate is fine at 9600 (although you should be able to set as high as 115200 with no issues). Use the default settings for everything else (Data Bits: 8, Stop Bits: 1, Parity: N, no flow control).</p><p>To test your keymap, you can chord keys on your keyboard and either look at the output of the 'paper tape' (Tools > Paper Tape) or that of the 'layout display' (Tools > Layout Display). If your strokes correctly show up, you are now ready to steno!</p><h2 id="learning-stenography" tabindex="-1">Learning Stenography <a class="header-anchor" href="#learning-stenography" aria-label="Permalink to "Learning Stenography {#learning-stenography}""></a></h2><ul><li><a href="https://sites.google.com/site/learnplover/" target="_blank" rel="noreferrer">Learn Plover!</a></li><li><a href="https://joshuagrams.github.io/steno-jig/" target="_blank" rel="noreferrer">Steno Jig</a></li><li>More resources at the Plover <a href="https://github.com/openstenoproject/plover/wiki/Learning-Stenography" target="_blank" rel="noreferrer">Learning Stenography</a> wiki</li></ul><h2 id="interfacing-with-the-code" tabindex="-1">Interfacing with the code <a class="header-anchor" href="#interfacing-with-the-code" aria-label="Permalink to "Interfacing with the code {#interfacing-with-the-code}""></a></h2><p>The steno code has three interceptable hooks. If you define these functions, they will be called at certain points in processing; if they return true, processi
|
|||
|
|
<script>window.__VP_HASH_MAP__=JSON.parse("{\"changelog_20210529.md\":\"CR1YNfZX\",\"changelog_20190830.md\":\"Drtq3lMy\",\"changelog_20210227.md\":\"BWOtCaeS\",\"changelog_20220528.md\":\"BX3CCY1Z\",\"changelog_20201128.md\":\"7XXL02Bn\",\"changelog_20220226.md\":\"BWO5r_ec\",\"changelog_20200530.md\":\"Dk-vRpTQ\",\"changelog_20210828.md\":\"DNbHIuuM\",\"changelog_20211127.md\":\"ClUawWkq\",\"drivers_i2c.md\":\"Cuj87reB\",\"faq_misc.md\":\"qGrhOTu4\",\"cli_commands.md\":\"DGx-qNiE\",\"drivers_uart.md\":\"BNBs-m3h\",\"feature_advanced_keycodes.md\":\"CX8dJkY-\",\"api_overview.md\":\"0FPaUsMb\",\"arm_debugging.md\":\"BH-H2Ukz\",\"feature_layers.md\":\"8GwBUTZN\",\"features_mouse_keys.md\":\"C3P3pYuE\",\"features_oled_driver.md\":\"D9wJVdL1\",\"changelog_20200829.md\":\"CoqrOffn\",\"breaking_changes_instructions.md\":\"BAjIGeJb\",\"changelog_20230226.md\":\"Cg0AYxIn\",\"changelog_20240526.md\":\"iGLFD0SP\",\"changelog_20200229.md\":\"DNsowwM1\",\"breaking_changes_history.md\":\"CkzdD6x8\",\"changelog_20220827.md\":\"DjPthqDk\",\"cli.md\":\"BLzAdA6l\",\"platformdev_blackpill_f4x1.md\":\"DvObLRuk\",\"platformdev_proton_c.md\":\"CDRuJBvD\",\"squeezing_avr.md\":\"BmcLYKOr\",\"platformdev_rp2040.md\":\"CYKYMDfc\",\"cli_tab_complete.md\":\"ChaxfzYo\",\"platformdev_selecting_arm_mcu.md\":\"aF4DUsvb\",\"data_driven_config.md\":\"BvLQ7P20\",\"porting_your_keyboard_to_qmk.md\":\"CGlGdFj4\",\"other_eclipse.md\":\"C-zqyJO9\",\"features_rgb_matrix.md\":\"8PRlkGEq\",\"syllabus.md\":\"B_ARGkLg\",\"quantum_painter_rle.md\":\"B07V3m-n\",\"features_hd44780.md\":\"15K40o_e\",\"one_shot_keys.md\":\"QR09rSb-\",\"unit_testing.md\":\"u3fgbGUj\",\"features_secure.md\":\"BX7jFvW5\",\"features_rgblight.md\":\"DehQikiL\",\"features_send_string.md\":\"vM68un4v\",\"ref_functions.md\":\"BVI2uXSN\",\"flashing_bootloadhid.md\":\"aXGP0bN5\",\"getting_started_docker.md\":\"mz6HE4Bl\",\"getting_started_github.md\":\"OYq7IT7B\",\"getting_started_introduction.md\":\"BOJreqSs\",\"tap_hold.md\":\"DD8WTSla\",\"getting_started_make_guide.md\":\"BjUuEnSh\",\"hand_wire.md\":\"CcI1spCv\",\"understanding_qmk.md\":\"f-Bc_eHQ\",\"hardware_drivers.md\":\"BUnx48D9\",\"flashing.md\":\"BSZF2RCy\",\"index.md\":\"B4QYzvHE\",\"keycodes_magic.md\":\"CGO3hgMm\",\"hardware_keyboard_guidelines.md\":\"CJevsanE\",\"keycodes_basic.md\":\"CHIeCvwn\",\"keycodes_us_ansi_shifted.md\":\"Cs78SDfM\",\"reference_configurator_support.md\":\"FaBQzIj6\",\"mod_tap.md\":\"C7wRKLcf\",\"newbs.md\":\"-YYNd3dT\",\"api_development_overview.md\":\"Dcey4ntL\",\"capabilities_inc.md\":\"Ca9zpMce\",\"newbs_building_firmware.md\":\"DnVUK9it\",\"api_development_environment.md\":\"EhJClb9f\",\"keymap.md\":\"Y4Fei1Ty\",\"isp_flashing_guide.md\":\"BiuBpOKX\",\"newbs_building_firmware_workflow.md\":\"DpLVwA7x\",\"cli_development.md\":\"3xFA2OvS\",\"changelog_20231126.md\":\"D2Ok5QAf\",\"cli_configuration.md\":\"CGSB128P\",\"newbs_external_userspace.md\":\"pD9Lc-a5\",\"newbs_flashing.md\":\"B42m5Wln\",\"how_keyboards_work.md\":\"CB7z8ocb\",\"newbs_getting_started.md\":\"DD4a5qPC\",\"other_vscode.md\":\"Di3vOySR\",\"keycodes.md\":\"hkOkKJPh\",\"newbs_git_using_your_master_branch.md\":\"B9DxZCl8\",\"quantum_painter_lvgl.md\":\"DobNbSgA\",\"documentation_templates.md\":\"Bhkum0wD\",\"api_docs.md\":\"CRoD6CbL\",\"support.md\":\"CwJ_H6Qx\",\"driver_installation_zadig.md\":\"CX9-BACt\",\"changelog_20221126.md\":\"DpbrnXeC\",\"newbs_building_firmware_configurator.md\":\"yyo-1QDE\",\"newbs_learn_more_resources.md\":\"Dj1s2BDG\",\"breaking_changes.md\":\"BtdqWQlY\",\"drivers_serial.md\":\"qxjytVdM\",\"quantum_painter_qgf.md\":\"BJNSu2s0\",\"newbs_git_best_practices.md\":\"BI2-EVI5\",\"newbs_git_resolving_merge_conflicts.md\":\"72w3BRmm\",\"newbs_git_resynchronize_a_branch.md\":\"YGDefQFx\",\"drivers_apa102.md\":\"Qb-KXRpF\",\"reference_keymap_extras.md\":\"-n_bLm78\",\"features_wpm.md\":\"BYf-Xc1H\",\"drivers_gpio.md\":\"C5PvyJVh\",\"drivers_audio.md\":\"mqaz6p5N\",\"drivers_spi.md\":\"tJVeIT7e\",\"changelog_20240225.md\":\"B4-WrXj6\",\"features_sequencer.md\":\"DkgqNCsQ\",\"drivers_flash.md\":\"DhWcHp8S\",\"feature
|
|||
|
|
|
|||
|
|
</body>
|
|||
|
|
</html>
|