mirror of
https://github.com/qmk/qmk_firmware.git
synced 2025-02-27 01:56:43 +00:00
17 lines
7.1 KiB
JavaScript
17 lines
7.1 KiB
JavaScript
import { _ as _export_sfc, c as createElementBlock, o as openBlock, a8 as createStaticVNode } from "./chunks/framework.DyMmIvSC.js";
|
||
const _imports_0 = "/assets/configurator_diagram.CbZon-ao.svg";
|
||
const __pageData = JSON.parse('{"title":"QMK Configurator Architecture","description":"","frontmatter":{},"headers":[],"relativePath":"configurator_architecture.md","filePath":"configurator_architecture.md"}');
|
||
const _sfc_main = { name: "configurator_architecture.md" };
|
||
const _hoisted_1 = /* @__PURE__ */ createStaticVNode('<h1 id="qmk-configurator-architecture" tabindex="-1">QMK Configurator Architecture <a class="header-anchor" href="#qmk-configurator-architecture" aria-label="Permalink to "QMK Configurator Architecture""></a></h1><p>This page describes the web architecture behind QMK Configurator at a high level. If you are interested in the architecture of the QMK Configurator code itself you should start at the <a href="https://github.com/qmk/qmk_configurator" target="_blank" rel="noreferrer">qmk_configurator</a> repository.</p><h1 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to "Overview""></a></h1><p><img src="' + _imports_0 + '" alt="QMK Configurator Architecture Diagram"></p><h1 id="detailed-description" tabindex="-1">Detailed Description <a class="header-anchor" href="#detailed-description" aria-label="Permalink to "Detailed Description""></a></h1><p>QMK Configurator is a <a href="https://en.wikipedia.org/wiki/Single-page_application" target="_blank" rel="noreferrer">Single Page Application</a> that allows users to create custom keymaps for their QMK-compatible keyboard. They can export JSON representation of their keymaps and compile firmware binaries that can be flashed to their keyboard using a tool like <a href="https://github.com/qmk/qmk_toolbox" target="_blank" rel="noreferrer">QMK Toolbox</a>.</p><p>Configurator gets metadata about keyboards from the Keyboard Metadata store and submits compile requests to the QMK API. The results of those compile requests will be made available on <a href="https://www.digitalocean.com/products/spaces/" target="_blank" rel="noreferrer">Digital Ocean Spaces</a>, an S3-compatible data store.</p><h2 id="configurator-frontend" tabindex="-1">Configurator Frontend <a class="header-anchor" href="#configurator-frontend" aria-label="Permalink to "Configurator Frontend""></a></h2><p>Address: <a href="https://config.qmk.fm" target="_blank" rel="noreferrer">https://config.qmk.fm</a></p><p>The <a href="https://config.qmk.fm" target="_blank" rel="noreferrer">Configurator Frontend</a> is compiled into a set of static files that are served by Github Pages. This action happens every time a commit is pushed to the <a href="https://github.com/qmk/qmk_configurator" target="_blank" rel="noreferrer">qmk_configurator <code>master</code></a> branch. You can view the status of these jobs on the <a href="https://github.com/qmk/qmk_configurator/actions/workflows/build.yml" target="_blank" rel="noreferrer">qmk_configurator actions tab</a>.</p><h2 id="keyboard-metadata" tabindex="-1">Keyboard Metadata <a class="header-anchor" href="#keyboard-metadata" aria-label="Permalink to "Keyboard Metadata""></a></h2><p>Address: <a href="https://keyboards.qmk.fm" target="_blank" rel="noreferrer">https://keyboards.qmk.fm</a></p><p>The Keyboard Metadata is generated every time a keyboard in <a href="https://github.com/qmk/qmk_firmware" target="_blank" rel="noreferrer">qmk_firmware</a> changes. The resulting JSON files are uploaded to Spaces and used by Configurator to generate UI for each keyboard. You can view the status of this job on the <a href="https://github.com/qmk/qmk_firmware/actions/workflows/api.yml" target="_blank" rel="noreferrer">qmk_firmware actions tab</a>. If you are a QMK Collaborator you can manually run this job using the <code>workflow_dispatch</code> event trigger.</p><h2 id="qmk-api" tabindex="-1">QMK API <a class="header-anchor" href="#qmk-api" aria-label="Permalink to "QMK API""></a></h2><p>Address: <a href="http://api.qmk.fm" target="_blank" rel="noreferrer">http://api.qmk.fm</a></p><p>The QMK API accepts <code>keymap.json</code> files for compilation. These are the same files you can use directly with <code>qmk compile</code> and <code>qmk flash</code>. When a <code>keymap.json</code> is submitted the browser will poll the status of the job periodically (every 2 seconds or longer, preferably) until the job has completed. The final status JSON will contain pointers to source and binary downloads for the keymap.</p><p>QMK API always presents the source and binary downloads side-by-side to comply with the GPL.</p><p>There are 3 non-error status responses from the API-</p><ol><li>Compile Job Queued</li><li>Compile Job Running</li><li>Compile Job Finished</li></ol><h3 id="compile-job-queued" tabindex="-1">Compile Job Queued <a class="header-anchor" href="#compile-job-queued" aria-label="Permalink to "Compile Job Queued""></a></h3><p>This status indicates that the job has not yet been picked up by a <a href="#qmk-compiler">QMK Compiler</a> node. Configurator shows this status as "Waiting for an oven".</p><h3 id="compile-job-running" tabindex="-1">Compile Job Running <a class="header-anchor" href="#compile-job-running" aria-label="Permalink to "Compile Job Running""></a></h3><p>This status indicates that the job has started compiling. Configurator shows this status as "Baking".</p><h3 id="compile-job-finished" tabindex="-1">Compile Job Finished <a class="header-anchor" href="#compile-job-finished" aria-label="Permalink to "Compile Job Finished""></a></h3><p>This status indicates that the job has completed. There will be keys in the status JSON for source and binary downloads.</p><h2 id="redis-rq" tabindex="-1">Redis/RQ <a class="header-anchor" href="#redis-rq" aria-label="Permalink to "Redis/RQ""></a></h2><p>QMK API uses RQ to distribute jobs to the available <a href="#qmk-compiler">QMK Compiler</a> nodes. When a <code>keymap.json</code> is received it's put into the RQ queue, where a <code>qmk_compiler</code> node will pick it up from.</p><h2 id="qmk-compiler" tabindex="-1">QMK Compiler <a class="header-anchor" href="#qmk-compiler" aria-label="Permalink to "QMK Compiler""></a></h2><p><a href="https://github.com/qmk/qmk_compiler" target="_blank" rel="noreferrer">QMK Compiler</a> is what actually performs the compilation of the <code>keymap.json</code>. It does so by checking out the requested <code>qmk_firmware</code> branch, running <code>qmk compile keymap.json</code>, and then uploading the resulting source and binary to Digital Ocean Spaces.</p><p>When users download their source/binary, API will redirect them to the authenticated Spaces download URL.</p>', 30);
|
||
const _hoisted_31 = [
|
||
_hoisted_1
|
||
];
|
||
function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
|
||
return openBlock(), createElementBlock("div", null, _hoisted_31);
|
||
}
|
||
const configurator_architecture = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]);
|
||
export {
|
||
__pageData,
|
||
configurator_architecture as default
|
||
};
|