<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">} </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">os_variant_t</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span></code></pre></div><divclass="tip custom-block"><pclass="custom-block-title">TIP</p><p>Note that it takes some time after firmware is booted to detect the OS.</p></div><p>This time is quite short, probably hundreds of milliseconds, but this data may be not ready in keyboard and layout setup functions which run very early during firmware startup.</p><h2id="callbacks"tabindex="-1">Callbacks <aclass="header-anchor"href="#callbacks"aria-label="Permalink to "Callbacks {#callbacks}""></a></h2><p>If you want to perform custom actions when the OS is detected, then you can use the <code>process_detected_host_os_kb</code> function on the keyboard level source file, or <code>process_detected_host_os_user</code> function in the user <code>keymap.c</code>.</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">bool</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> process_detected_host_os_kb</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">os_variant_t</span><spanstyle="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> detected_os</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h2id="os-detection-stability"tabindex="-1">OS detection stability <aclass="header-anchor"href="#os-detection-stability"aria-label="Permalink to "OS detection stability""></a></h2><p>The OS detection is currently handled while the USB device descriptor is being assembled. The process is done in steps, generating a number of intermediate results until it stabilizes. We therefore resort to debouncing the result until it has been stable for a given amount of milliseconds. This amount can be configured, in case your board is not stable within the default debouncing time of 200ms.</p><h2id="configuration-options"tabindex="-1">Configuration Options <aclass="header-anchor"href="#configuration-options"aria-label="Permalink to "Configuration Options""></a></h2><ul><li><code>#define OS_DETECTION_DEBOUNCE 250</code><ul><li>defined the debounce time for OS detection, in milliseconds</li><li>defaults to 250ms</li></ul></li><li><code>#define OS_DETECTION_KEYBOARD_RESET</code><ul><li>enables the keyboard reset upon a USB device reinitilization</li><li>this setting may help with detection issues when switching between devices on some KVMs (see <ahref="#troubleshooting">Troubleshooting</a>)</li></ul></li><li><code>#define OS_DETECTION_SINGLE_REPORT</code><ul><li>allows the report callbacks to be called only once, when the OS detection result is considered stable</li><li>subsequent changes in the detection results, if any, are ignored</li><li>this setting may help with delayed stability issues when switching devices on some KVMs (see <ahref="#troubleshooting">Troubleshooting</a>)</li></ul></li></ul><h2id="troubleshooting"tabindex="-1">Troubleshooting <aclass="header-anchor"href="#troubleshooting"aria-label="Permalink to "Troubleshooting""></a></h2><p>Some KVMs and USB switches may cause issues when the OS detection is turned on. Here is a list of common issues and how to fix them:</p><ul><li><strong>Problem</strong>: <em>keyboard won't redetect the OS when switching between machines using a KVM</em><ul><li><strong>Explanation</strong>: some KVMs keep the USB controller powered on during the switch and OS detection happens when the USB device description is being assembled.</li><li><strong>Solution</strong>: use <code>OS_DETECTION_KEYBOARD_RESET</code> to force the keyboard to reset upon switching.</li></ul></li><li><strong>Problem</strong>: <em>keyboard OS detection callback gets invoked even minuted after startup</em><ul><li><strong>Explanation</strong>: some OSes, notably macOS on ARM-based Macs, may cause this behavior. The actual cause is not known at this time.'</li><li><strong>Solution</strong>: use <code>OS_DETECTION_SINGLE_REPORT</code> to suppress repeated callback invocations.</li></ul></li></ul><h2id="debug"tabindex="-1">Debug <aclass="header-anchor"href="#debug"aria-label="Permalink to "Debug""></a></h2><p>If OS is guessed incorrectly, you may want to collect data about USB setup packets to refine the detection logic.</p><p>To do so in your <code>config.h</code> add:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> OS_DETECTION_DEBUG_ENABLE</span></span></code></pre></div><p>And in your <code>rules.mk</code> add:</p><divclass="language-make vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">make</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">CONSOLE_ENABLE = yes</span></span></code></pre></div><p>And also include <code>"os_detection.h"</code> in your <code>keymap.c</code>.</p><p>Then you can define c
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Then please open an issue on Github with this information and tell what OS was not detected correctly and if you have any intermediate devices between keyboard and your computer.</p><h2id="credits"tabindex="-1">Credits <aclass="header-anchor"href="#credits"aria-label="Permalink to "Credits""></a></h2><p>Original idea is coming from <ahref="https://github.com/keyboardio/FingerprintUSBHost"target="_blank"rel="noreferrer">FingerprintUSBHost</a> project.</p></div></div></main><footerclass="VPDocFooter"data-v-39a288b8data-v-09de1c0f><!--[--><!--]--><divclass="edit-info"data-v-09de1c0f><divclass="edit-link"data-v-09de1c0f><aclass="VPLink link vp-external-link-icon no-icon edit-link-button"href="https://github.com/qmk/qmk_firmware/edit/master/docs/features/os_detection.md"target="_blank"rel="noreferrer"data-v-09de1c0f><!--[--><spanclass="vpi-square-pen edit-link-icon"data-v-09de1c0f></span> Edit this page<!--]--></a></div><!----></div><navclass="prev-next"data-v-09de1c0f><divclass="pager"data-v-09de1c0f><aclass="VPLink link pager-link prev"href="/one_shot_keys"data-v-09de1c0f><!--[--><spanclass="desc"data-v-09de1c0f>Previous page</span><spanclass="title"data-v-09de1c0f>One Shot Keys</span><!--]--></a></div><divclass="pager"data-v-09de1c0f><aclass="VPLink link pager-link next"href="/features/rawhid"data-v-09de1c0f><!--[--><spanclass="desc"data-v-09de1c0f>Next page</span><spanclass="title"data-v-09de1c0f>Raw HID</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
