From 4a6ffd6bb09879d024428cb6ea8b075aabb5ffe2 Mon Sep 17 00:00:00 2001 From: MyBestFriendMe Date: Thu, 17 Oct 2024 12:03:06 -0500 Subject: [PATCH 1/3] info to keyboard documentation --- docs/_sidebar.json | 2 +- docs/config_options.md | 4 ++-- docs/reference_info_json.md | 8 ++++---- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/_sidebar.json b/docs/_sidebar.json index d691011d641f..9c61de1713b5 100644 --- a/docs/_sidebar.json +++ b/docs/_sidebar.json @@ -287,7 +287,7 @@ { "text": "Community Layouts", "link": "/feature_layouts" }, { "text": "Unit Testing", "link": "/unit_testing" }, { "text": "Useful Functions", "link": "/ref_functions" }, - { "text": "info.json Format", "link": "/reference_info_json" } + { "text": "keyboard.json Format", "link": "/reference_info_json" } ] }, diff --git a/docs/config_options.md b/docs/config_options.md index fec6b22b133c..1f145b3c1bb8 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -6,12 +6,12 @@ There are three main types of configuration files in QMK: * `config.h`, which contains various preprocessor directives (`#define`, `#ifdef`) * `rules.mk`, which contains additional variables -* `info.json`, which is utilized for [data-driven configuration](data_driven_config) +* `keyboard.json`, which is utilized for [data-driven configuration](data_driven_config) This page will only discuss the first two types, `config.h` and `rules.mk`. ::: tip -While not all settings have data-driven equivalents yet, keyboard makers are encouraged to utilize the `info.json` file to set the metadata for their boards when possible. See the [`info.json` Format](reference_info_json) page for more details. +While not all settings have data-driven equivalents yet, keyboard makers are encouraged to utilize the `keyboard.json` file to set the metadata for their boards when possible. See the [`keyboard.json` Format](reference_info_json) page for more details. ::: These files exist at various levels in QMK and all files of the same type are combined to build the final configuration. The levels, from lowest priority to highest priority, are: diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md index 82110537a9d3..c42474c7990a 100644 --- a/docs/reference_info_json.md +++ b/docs/reference_info_json.md @@ -1,8 +1,8 @@ -# `info.json` Reference {#info-json-reference} +# `keyboard.json` Reference {#keyboard-json-reference} -The information contained in `info.json` is combined with the `config.h` and `rules.mk` files, dynamically generating the necessary configuration for your keyboard at compile time. It is also used by the [QMK API](https://github.com/qmk/qmk_api), and contains the information [QMK Configurator](https://config.qmk.fm/) needs to display a representation of your keyboard. Its key/value pairs are ruled by the [`data/schemas/keyboard.jsonschema`](https://github.com/qmk/qmk_firmware/blob/master/data/schemas/keyboard.jsonschema) file. To learn more about the why and how of the schema file see the [Data Driven Configuration](data_driven_config) page. +The information contained in `keyboard.json` is combined with the `config.h` and `rules.mk` files, dynamically generating the necessary configuration for your keyboard at compile time. It is also used by the [QMK API](https://github.com/qmk/qmk_api), and contains the information [QMK Configurator](https://config.qmk.fm/) needs to display a representation of your keyboard. Its key/value pairs are ruled by the [`data/schemas/keyboard.jsonschema`](https://github.com/qmk/qmk_firmware/blob/master/data/schemas/keyboard.jsonschema) file. To learn more about the why and how of the schema file see the [Data Driven Configuration](data_driven_config) page. -You can create `info.json` files at every level under `qmk_firmware/keyboards/`. These files are combined, with more specific files overriding keys in less specific files. This means you do not need to duplicate your metadata information. For example, `qmk_firmware/keyboards/clueboard/info.json` specifies information common to all Clueboard products, such as `manufacturer` and `maintainer`, while `qmk_firmware/keyboards/clueboard/66/info.json` contains more specific information about Clueboard 66%. +You can create `keyboard.json` files at every level under `qmk_firmware/keyboards/`. These files are combined, with more specific files overriding keys in less specific files. This means you do not need to duplicate your metadata information. For example, `qmk_firmware/keyboards/clueboard/keyboard.json` specifies information common to all Clueboard products, such as `manufacturer` and `maintainer`, while `qmk_firmware/keyboards/clueboard/66/keyboard.json` contains more specific information about Clueboard 66%. ## General Metadata {#general-metadata} @@ -299,7 +299,7 @@ Each key dictionary in a layout describes the physical properties of a key. If y All key positions and rotations are specified in relation to the top-left corner of the keyboard, and the top-left corner of each key. -The ISO enter key is represented by a 1.25u×2uh key. Renderers which utilize info.json layout data (such as `qmk info -l` and the QMK Configurator) should display this key as expected. +The ISO enter key is represented by a 1.25u×2uh key. Renderers which utilize keyboard.json layout data (such as `qmk info -l` and the QMK Configurator) should display this key as expected. * `community_layouts` Array: String * A list of community layouts supported by the keyboard. From 39960e14e140f8a982d8eec3d74e5a919deeb2fe Mon Sep 17 00:00:00 2001 From: MyBestFriendMe Date: Thu, 17 Oct 2024 14:16:04 -0500 Subject: [PATCH 2/3] accuracy fixed added context based on changelog 20240526. --- docs/cli_commands.md | 18 +++++++++--------- docs/data_driven_config.md | 22 ++++++++++++---------- docs/drivers/ws2812.md | 2 +- docs/features/ps2_mouse.md | 4 ++-- docs/features/rawhid.md | 2 +- docs/flashing.md | 2 +- docs/hardware_keyboard_guidelines.md | 4 ++-- docs/porting_your_keyboard_to_qmk.md | 8 ++++---- docs/pr_checklist.md | 10 +++++----- docs/reference_configurator_support.md | 8 ++++---- docs/reference_info_json.md | 2 +- 11 files changed, 42 insertions(+), 40 deletions(-) diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 7d74d8e6177b..859096af1b4e 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -151,7 +151,7 @@ qmk cd ## `qmk find` -This command allows for searching through keyboard/keymap targets, filtering by specific criteria. `info.json` and `rules.mk` files contribute to the search data, as well as keymap configurations, and the results can be filtered using "dotty" syntax matching the overall `info.json` file format. +This command allows for searching through keyboard/keymap targets, filtering by specific criteria. `keyboard.json` and `rules.mk` files contribute to the search data, as well as keymap configurations, and the results can be filtered using "dotty" syntax matching the overall `keyboard.json` file format. For example, one could search for all keyboards using STM32F411: @@ -187,9 +187,9 @@ options: -km KEYMAP, --keymap KEYMAP The keymap name to build. Default is 'default'. -p PRINT, --print PRINT - For each matched target, print the value of the supplied info.json key. May be passed multiple times. + For each matched target, print the value of the supplied keyboard.json key. May be passed multiple times. -f FILTER, --filter FILTER - Filter the list of keyboards based on their info.json data. Accepts the formats key=value, function(key), or function(key,value), eg. 'features.rgblight=true'. Valid functions are 'absent', 'contains', 'exists' and 'length'. May be passed multiple times; all filters need to match. Value may include wildcards such as '*' and '?'. + Filter the list of keyboards based on their keyboard.json data. Accepts the formats key=value, function(key), or function(key,value), eg. 'features.rgblight=true'. Valid functions are 'absent', 'contains', 'exists' and 'length'. May be passed multiple times; all filters need to match. Value may include wildcards such as '*' and '?'. ``` ## `qmk console` @@ -272,7 +272,7 @@ qmk doctor -n ## `qmk format-json` -Formats a JSON file in a (mostly) human-friendly way. Will usually correctly detect the format of the JSON (info.json or keymap.json) but you can override this with `--format` if necessary. +Formats a JSON file in a (mostly) human-friendly way. Will usually correctly detect the format of the JSON (keyboard.json or keymap.json) but you can override this with `--format` if necessary. **Usage**: @@ -390,7 +390,7 @@ qmk list-keymaps -kb planck/ez ## `qmk migrate` -This command searches for legacy code that can be converted to the new `info.json` format and adds it to the specified keyboard's `info.json`. +This command searches for legacy code that can be converted to the new `keyboard.json` format and adds it to the specified keyboard's `keyboard.json`. **Usage**: @@ -451,7 +451,7 @@ $ qmk via2json -kb ai03/polaris -o polaris_keymap.json polaris_via_backup.json ## `qmk import-keyboard` -This command imports a data-driven `info.json` keyboard into the repo. +This command imports a data-driven `keyboard.json` keyboard into the repo. **Usage**: @@ -759,7 +759,7 @@ qmk generate-rgb-breathe-table [-q] [-o OUTPUT] [-m MAX] [-c CENTER] ## `qmk kle2json` -This command allows you to convert from raw KLE data to QMK Configurator JSON. It accepts either an absolute file path, or a file name in the current directory. By default it will not overwrite `info.json` if it is already present. Use the `-f` or `--force` flag to overwrite. +This command allows you to convert from raw KLE data to QMK Configurator JSON. It accepts either an absolute file path, or a file name in the current directory. By default it will not overwrite `keyboard.json` if it is already present. Use the `-f` or `--force` flag to overwrite. **Usage**: @@ -771,12 +771,12 @@ qmk kle2json [-f] ``` $ qmk kle2json kle.txt -☒ File info.json already exists, use -f or --force to overwrite. +☒ File keyboard.json already exists, use -f or --force to overwrite. ``` ``` $ qmk kle2json -f kle.txt -f -Ψ Wrote out to info.json +Ψ Wrote out to keyboard.json ``` ## `qmk format-python` diff --git a/docs/data_driven_config.md b/docs/data_driven_config.md index 2c1a56e004f8..34e4bc6d973a 100644 --- a/docs/data_driven_config.md +++ b/docs/data_driven_config.md @@ -6,9 +6,11 @@ This page describes how QMK's data driven JSON configuration system works. It is Historically QMK has been configured through a combination of two mechanisms- `rules.mk` and `config.h`. While this worked well when QMK was only a handful of keyboards we've grown to encompass nearly 4000 supported keyboards. That extrapolates out to 6000 configuration files under `keyboards/` alone! The freeform nature of these files and the unique patterns people have used to avoid duplication have made ongoing maintenance a challenge, and a large number of our keyboards follow patterns that are outdated and sometimes harder to understand. -We have also been working on bringing the power of QMK to people who aren't comformable with a CLI, and other projects such as VIA are working to make using QMK as easy as installing a program. These tools need information about how a keyboard is laid out or what pins and features are available so that users can take full advantage of QMK. We introduced `info.json` as a first step towards this. The QMK API is an effort to combine these 3 sources of information- `config.h`, `rules.mk`, and `info.json`- into a single source of truth that end-user tools can use. +We have also been working on bringing the power of QMK to people who aren't comfortable with a CLI, and other projects such as VIA are working to make using QMK as easy as installing a program. These tools need information about how a keyboard is laid out or what pins and features are available so that users can take full advantage of QMK. We introduced `info.json` as a first step towards this. We have now changed to using `keyboard.json`. However, `info.json` has been repurposed to only represent fragments of config that can be shared accross revisions. The QMK API is an effort to combine these 3 sources of information- `config.h`, `rules.mk`, and `keyboard.json` - into a single source of truth that end-user tools can use. -Now we have support for generating `rules.mk` and `config.h` values from `info.json`, allowing us to have a single source of truth. This will allow us to use automated tooling to maintain keyboards saving a lot of time and maintenance work. +We now have support for generating `rules.mk` and `config.h` values from `keyboard.json`, allowing us to have a single source of truth. This will allow us to use automated tooling to maintain keyboards saving a lot of time and maintenance work. + +You can use `info.json` as a parent on a keyboard with multiple versions. Any code that will be shared between different versions/revisions can be kept in `info.json` in the parent directory and all individual differences should be added to each revision's indivudual `keyboard.json`. ## Overview @@ -18,7 +20,7 @@ On the C side of things nothing changes. When you need to create a new rule or d 1. Set a default in the appropriate core file 1. Add your ifdef statements as needed -You will then need to add support for your new configuration to `info.json`. The basic process is: +You will then need to add support for your new configuration to `keyboard.json`. The basic process is: 1. Add it to the schema in `data/schemas/keyboards.jsonschema` 1. Add a mapping in `data/maps` @@ -27,13 +29,13 @@ You will then need to add support for your new configuration to `info.json`. The * `lib/python/qmk/cli/generate/config_h.py` * `lib/python/qmk/cli/generate/rules_mk.py` -## Adding an option to info.json +## Adding an option to keyboard.json -This section describes adding support for a `config.h`/`rules.mk` value to info.json. +This section describes adding support for a `config.h`/`rules.mk` value to keyboard.json. ### Add it to the schema -QMK maintains [jsonschema](https://json-schema.org/) files in `data/schemas`. The values that go into keyboard-specific `info.json` files are kept in `keyboard.jsonschema`. Any value you want to make available to end users to edit must go in here. +QMK maintains [jsonschema](https://json-schema.org/) files in `data/schemas`. The values that go into keyboard-specific `keyboard.json` files are kept in `keyboard.jsonschema`. Any value you want to make available to end users to edit must go in here. In some cases you can simply add a new top-level key. Some examples to follow are `keyboard_name`, `maintainer`, `processor`, and `url`. This is appropriate when your option is self-contained and not directly related to other options. @@ -43,15 +45,15 @@ In other cases you should group like options together in an `object`. This is pa In most cases you can add a simple mapping. These are maintained as JSON files in `data/mappings/info_config.hjson` and `data/mappings/info_rules.hjson`, and control mapping for `config.h` and `rules.mk`, respectively. Each mapping is keyed by the `config.h` or `rules.mk` variable, and the value is a hash with the following keys: -* `info_key`: (required) The location within `info.json` for this value. See below. +* `info_key`: (required) The location within `keyboard.json` for this value. See below. * `value_type`: (optional) Default `raw`. The format for this variable's value. See below. -* `to_json`: (optional) Default `true`. Set to `false` to exclude this mapping from info.json +* `to_json`: (optional) Default `true`. Set to `false` to exclude this mapping from keyboard.json * `to_c`: (optional) Default `true`. Set to `false` to exclude this mapping from config.h * `warn_duplicate`: (optional) Default `true`. Set to `false` to turn off warning when a value exists in both places #### Info Key -We use JSON dot notation to address variables within info.json. For example, to access `info_json["rgblight"]["split_count"]` I would specify `rgblight.split_count`. This allows you to address deeply nested keys with a simple string. +We use JSON dot notation to address variables within keyboard.json. For example, to access `info_json["rgblight"]["split_count"]` I would specify `rgblight.split_count`. This allows you to address deeply nested keys with a simple string. Under the hood we use [Dotty Dict](https://dotty-dict.readthedocs.io/en/latest/), you can refer to that documentation for how these strings are converted to object access. @@ -71,7 +73,7 @@ By default we treat all values as unquoted "raw" data. If your value is more com Most use cases can be solved by the mapping files described above. If yours can't you can instead write code to extract your config values. -Whenever QMK generates a complete `info.json` it extracts information from `config.h` and `rules.mk`. You will need to add code for your new config value to `lib/python/qmk/info.py`. Typically this means adding a new `_extract_()` function and then calling your function in either `_extract_config_h()` or `_extract_rules_mk()`. +Whenever QMK generates a complete `keyboard.json` it extracts information from `config.h` and `rules.mk`. You will need to add code for your new config value to `lib/python/qmk/info.py`. Typically this means adding a new `_extract_()` function and then calling your function in either `_extract_config_h()` or `_extract_rules_mk()`. If you are not sure how to edit this file or are not comfortable with Python [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and someone can help you with this part. diff --git a/docs/drivers/ws2812.md b/docs/drivers/ws2812.md index 61addf1917ed..d059682689ec 100644 --- a/docs/drivers/ws2812.md +++ b/docs/drivers/ws2812.md @@ -82,7 +82,7 @@ To enable RGBW conversion, add the following to your `config.h`: ## Driver Configuration {#driver-configuration} -Driver selection can be configured in `rules.mk` as `WS2812_DRIVER`, or in `info.json` as `ws2812.driver`. Valid values are `bitbang` (default), `i2c`, `spi`, `pwm`, `vendor`, or `custom`. See below for information on individual drivers. +Driver selection can be configured in `rules.mk` as `WS2812_DRIVER`, or in `keyboard.json` as `ws2812.driver`. Valid values are `bitbang` (default), `i2c`, `spi`, `pwm`, `vendor`, or `custom`. See below for information on individual drivers. ### Bitbang Driver {#bitbang-driver} diff --git a/docs/features/ps2_mouse.md b/docs/features/ps2_mouse.md index 90f4cca82757..2b0f200c1df6 100644 --- a/docs/features/ps2_mouse.md +++ b/docs/features/ps2_mouse.md @@ -159,14 +159,14 @@ In your keyboard config.h: The `PIO` subsystem is a Raspberry Pi RP2040 specific implementation, using the integrated PIO peripheral and is therefore only available on this MCU. -There are strict requirements for pin ordering but any pair of GPIO pins can be used. The GPIO used for clock must be directly after data, see the included info.json snippet for an example of correct order. +There are strict requirements for pin ordering but any pair of GPIO pins can be used. The GPIO used for clock must be directly after data, see the included keyboard.json snippet for an example of correct order. You may optionally switch the PIO peripheral used with the following define in config.h: ```c #define PS2_PIO_USE_PIO1 // Force the usage of PIO1 peripheral, by default the PS2 implementation uses the PIO0 peripheral ``` -Example info.json content: +Example keyboard.json content: ```json "ps2": { diff --git a/docs/features/rawhid.md b/docs/features/rawhid.md index c3ecfbe099dc..5ce010889769 100644 --- a/docs/features/rawhid.md +++ b/docs/features/rawhid.md @@ -32,7 +32,7 @@ To send data to the keyboard, you must first find a library for communicating wi Please refer to these libraries' own documentation for instructions on usage. Remember to close the device once you are finished with it! -Next, you will need to know the USB Vendor and Product IDs of the device. These can easily be found by looking at your keyboard's `info.json`, under the `usb` object (alternatively, you can also use Device Manager on Windows, System Information on macOS, or `lsusb` on Linux). For example, the Vendor ID for the Planck Rev 6 is `0x03A8`, and the Product ID is `0xA4F9`. +Next, you will need to know the USB Vendor and Product IDs of the device. These can easily be found by looking at your keyboard's `keyboard.json`, under the `usb` object (alternatively, you can also use Device Manager on Windows, System Information on macOS, or `lsusb` on Linux). For example, the Vendor ID for the Planck Rev 6 is `0x03A8`, and the Product ID is `0xA4F9`. It's also a good idea to narrow down the list of potential HID devices the library may give you by filtering on the usage page and usage ID, to avoid accidentally opening the interface on the same device for the keyboard, or mouse, or media keys, etc. diff --git a/docs/flashing.md b/docs/flashing.md index 2afb85886025..671b6f37605c 100644 --- a/docs/flashing.md +++ b/docs/flashing.md @@ -326,7 +326,7 @@ Flashing sequence: Some keyboards produced for several commercial brands (GMMK, Akko, MonsGeek, Inland) use this bootloader. The `wb32-dfu-updater` utility is bundled with [QMK MSYS](https://msys.qmk.fm/) and [Glorious's build of QMK Toolbox](https://www.gloriousgaming.com/blogs/guides-resources/gmmk-2-qmk-installation-guide). If neither of these flashing methods is available for your OS, you will likely need to [compile the CLI version from source](https://github.com/WestberryTech/wb32-dfu-updater). -The `info.json` setting for this bootloader is `wb32-dfu`. +The `keyboard.json` setting for this bootloader is `wb32-dfu`. Compatible flashers: diff --git a/docs/hardware_keyboard_guidelines.md b/docs/hardware_keyboard_guidelines.md index de67fa3bc399..bc3aed117c30 100644 --- a/docs/hardware_keyboard_guidelines.md +++ b/docs/hardware_keyboard_guidelines.md @@ -64,7 +64,7 @@ Clueboard uses sub-folders for both purposes, organization and keyboard revision Your keyboard should be located in `qmk_firmware/keyboards/` and the folder name should be your keyboard's name as described in the previous section. Inside this folder should be several files: * `readme.md` -* `info.json` +* `keyboard.json` * `config.h` * `rules.mk` * `.c` @@ -74,7 +74,7 @@ Your keyboard should be located in `qmk_firmware/keyboards/` and the folder name All projects need to have a `readme.md` file that explains what the keyboard is, who made it and where it's available. If applicable, it should also contain links to more information, such as the maker's website. Please follow the [published template](documentation_templates#keyboard-readmemd-template). -### `info.json` +### `keyboard.json` This file is used by the [QMK API](https://github.com/qmk/qmk_api). It contains the information [QMK Configurator](https://config.qmk.fm/) needs to display a representation of your keyboard. You can also set metadata here. For more information see the [reference page](reference_info_json). diff --git a/docs/porting_your_keyboard_to_qmk.md b/docs/porting_your_keyboard_to_qmk.md index e5a1f803f717..5b879277580f 100644 --- a/docs/porting_your_keyboard_to_qmk.md +++ b/docs/porting_your_keyboard_to_qmk.md @@ -58,13 +58,13 @@ This will create all the files needed to support your new keyboard, and populate This is where you'll describe your keyboard. Please follow the [Keyboard Readme Template](documentation_templates#keyboard-readmemd-template) when writing your `readme.md`. You're encouraged to place an image at the top of your `readme.md`, please use an external service such as [Imgur](https://imgur.com) to host the images. -## `info.json` +## `keyboard.json` -The `info.json` file is where you configure the hardware and feature set for your keyboard. There are a lot of options that can be placed in that file, too many to list here. For a complete overview of available options see the [Data Driven Configuration Options](reference_info_json) page. +The `keyboard.json` file is where you configure the hardware and feature set for your keyboard. There are a lot of options that can be placed in that file, too many to list here. For a complete overview of available options see the [Data Driven Configuration Options](reference_info_json) page. ### Hardware Configuration -At the top of the `info.json` you'll find USB related settings. These control how your keyboard appears to the Operating System. If you don't have a good reason to change you should leave the `usb.vid` as `0xFEED`. For the `usb.pid` you should pick a number that is not yet in use. +At the top of the `keyboard.json` you'll find USB related settings. These control how your keyboard appears to the Operating System. If you don't have a good reason to change you should leave the `usb.vid` as `0xFEED`. For the `usb.pid` you should pick a number that is not yet in use. Do change the `manufacturer` and `keyboard_name` lines to accurately reflect your keyboard. @@ -158,7 +158,7 @@ See also: [Split Keyboard Layout Macro](features/split_keyboard#layout-macro) an ## Additional Configuration -There are a lot of features that can be turned on or off, configured or tuned. Some of these have yet to be migrated over to [Data Driven Configuration](data_driven_config). The following sections cover the process for when an `info.json` option is unavailable. +There are a lot of features that can be turned on or off, configured or tuned. Some of these have yet to be migrated over to [Data Driven Configuration](data_driven_config). The following sections cover the process for when an `keyboard.json` option is unavailable. ### Configuration Options For available options for `config.h`, you should see the [Config Options](config_options#the-configh-file) page for more details. diff --git a/docs/pr_checklist.md b/docs/pr_checklist.md index 268e3b1b116a..d819d70bd181 100644 --- a/docs/pr_checklist.md +++ b/docs/pr_checklist.md @@ -62,9 +62,9 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard - `data/mappings/keyboard_aliases.hjson` must be updated to reflect the move, so users with pre-created configurator keymap.json files continue to detect the correct keyboard - keyboard updates and refactors (eg. to data driven) *must* go through `develop` to reduce `master` -> `develop` merge conflicts - PR submissions from a `kbfirmware` export (or equivalent) will not be accepted unless converted to new QMK standards -- try `qmk import-kbfirmware` first -- `info.json` - - With the move to [data driven](data_driven_config) keyboard configuration, we encourage contributors to utilise as many features as possible of the info.json [schema](https://github.com/qmk/qmk_firmware/blob/master/data/schemas/keyboard.jsonschema). - - the mandatory elements for a minimally complete `info.json` at present are: +- `keyboard.json` + - With the move to [data driven](data_driven_config) keyboard configuration, we encourage contributors to utilise as many features as possible of the keyboard.json [schema](https://github.com/qmk/qmk_firmware/blob/master/data/schemas/keyboard.jsonschema). + - the mandatory elements for a minimally complete `keyboard.json` at present are: - valid URL - valid maintainer - valid USB VID/PID and device version @@ -79,7 +79,7 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard - use alternate layout names for all other possible layouts, preferring community layout names if an equivalent is available (e.g. `LAYOUT_tkl_ansi`, `LAYOUT_ortho_4x4` etc.) - Microcontroller and bootloader - Diode Direction (if not using direct pins) - - the following are required to be configured in `info.json` if necessary + - the following are required to be configured in `keyboard.json` if necessary - Direct pin configuration - Backlight Configuration (where applicable) - Split keyboard configuration (where applicable) @@ -132,7 +132,7 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard - hardware that's enabled at the keyboard level and requires configuration such as OLED displays or encoders should have basic functionality implemented here - `.h` - `#include "quantum.h"` appears at the top - - `LAYOUT` macros are no longer accepted and should instead be moved to `info.json` + - `LAYOUT` macros are no longer accepted and should instead be moved to `keyboard.json` - keymap `config.h` - no duplication of `rules.mk` or `config.h` from keyboard - `keymaps/default/keymap.c` diff --git a/docs/reference_configurator_support.md b/docs/reference_configurator_support.md index dffed5c0c349..3c5a5a67e9f2 100644 --- a/docs/reference_configurator_support.md +++ b/docs/reference_configurator_support.md @@ -93,7 +93,7 @@ Once the layout is as desired, move to the Raw Data tab in KLE, and copy the con [{w:2},"0\nIns",".\nDel"] ``` -To convert this data into our JSON, go to the [QMK KLE-JSON Converter](https://qmk.fm/converter/), paste the Raw Data into the Input field, and click the Convert button. After a moment, our JSON data will appear in the Output field. Copy the contents to a new text document, and name the document `info.json`, saving it in the same folder that contains `numpad.h`. +To convert this data into our JSON, go to the [QMK KLE-JSON Converter](https://qmk.fm/converter/), paste the Raw Data into the Input field, and click the Convert button. After a moment, our JSON data will appear in the Output field. Copy the contents to a new text document, and name the document `keyboard.json`, saving it in the same folder that contains `numpad.h`. Use the `keyboard_name` object to set the name of the keyboard. For instruction purposes, we will put each key's object on its own line. This is only to make the file more human-readable, and does not affect the Configurator's functionality. @@ -148,7 +148,7 @@ The `layouts` object contains the data that represents the physical layout of th Some objects will also have `"w"` and `"h"` keys, which represent a key's width and height, respectively. ::: tip -For more on the `info.json` files, see [`info.json` Format](reference_info_json). +For more on the `keyboard.json` files, see [`keyboard.json` Format](reference_info_json). ::: @@ -176,12 +176,12 @@ k33 | {"label":"Enter", "x":3, "y":3, "h":2} k40 | {"label":"0", "x":0, "y":4, "w":2} k42 | {"label":".", "x":2, "y":4} -When a user selects the top-left key in the Configurator, and assigns Num Lock to it, the Configurator builds a keymap file with `KC_NUM` as the first key, and so on as the keymap is built. The `label` keys are not used; they are only for the user's reference in identifying specific keys when debugging the `info.json` file. +When a user selects the top-left key in the Configurator, and assigns Num Lock to it, the Configurator builds a keymap file with `KC_NUM` as the first key, and so on as the keymap is built. The `label` keys are not used; they are only for the user's reference in identifying specific keys when debugging the `keyboard.json` file. ## Issues and Hazards -Currently, the Configurator does not support key rotation or non-rectangular key shapes like ISO Enter. Additionally, keys that are vertically-offset from their "row" — the arrow keys on 1800-layouts like the [TKC1800](https://github.com/qmk/qmk_firmware/tree/4ac48a61a66206beaf2fdd5f2939d8bbedd0004c/keyboards/tkc1800/) being a prominent example — confuse the KLE-to-JSON Converter, if not adjusted for by the contributor of the `info.json` file. +Currently, the Configurator does not support key rotation or non-rectangular key shapes like ISO Enter. Additionally, keys that are vertically-offset from their "row" — the arrow keys on 1800-layouts like the [TKC1800](https://github.com/qmk/qmk_firmware/tree/4ac48a61a66206beaf2fdd5f2939d8bbedd0004c/keyboards/tkc1800/) being a prominent example — confuse the KLE-to-JSON Converter, if not adjusted for by the contributor of the `keyboard.json` file. ### Workarounds diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md index c42474c7990a..e798765464d9 100644 --- a/docs/reference_info_json.md +++ b/docs/reference_info_json.md @@ -2,7 +2,7 @@ The information contained in `keyboard.json` is combined with the `config.h` and `rules.mk` files, dynamically generating the necessary configuration for your keyboard at compile time. It is also used by the [QMK API](https://github.com/qmk/qmk_api), and contains the information [QMK Configurator](https://config.qmk.fm/) needs to display a representation of your keyboard. Its key/value pairs are ruled by the [`data/schemas/keyboard.jsonschema`](https://github.com/qmk/qmk_firmware/blob/master/data/schemas/keyboard.jsonschema) file. To learn more about the why and how of the schema file see the [Data Driven Configuration](data_driven_config) page. -You can create `keyboard.json` files at every level under `qmk_firmware/keyboards/`. These files are combined, with more specific files overriding keys in less specific files. This means you do not need to duplicate your metadata information. For example, `qmk_firmware/keyboards/clueboard/keyboard.json` specifies information common to all Clueboard products, such as `manufacturer` and `maintainer`, while `qmk_firmware/keyboards/clueboard/66/keyboard.json` contains more specific information about Clueboard 66%. +You can create `info.json` files at every level under `qmk_firmware/keyboards/` exept for the lowest level which needs to be `keyboard.json`. These files are combined, with more specific files overriding keys in less specific files. This means you do not need to duplicate your metadata information. For example, `qmk_firmware/keyboards/clueboard/info.json` specifies information common to all Clueboard products, such as `manufacturer` and `maintainer`, while `qmk_firmware/keyboards/clueboard/66/info.json` contains more specific information about Clueboard 66%. Going further, `qmk_firmware/keyboards/clueboard/66/rev1/keyboard.json` contains the most specific data on only `rev1` that overrides all keys above it. `info.json` represents a parent source of information while `keyboard.json` represents each individual revision or version endpoint. You will always need to have the final `*.json` file be listed as `keyboard.json` in order to properly compile. ## General Metadata {#general-metadata} From 6e445e3d356057ea0bdebc460703afda676069fe Mon Sep 17 00:00:00 2001 From: MyBestFriendMe Date: Thu, 17 Oct 2024 14:29:10 -0500 Subject: [PATCH 3/3] missed one I just forgot to save the document... --- docs/getting_started_introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started_introduction.md b/docs/getting_started_introduction.md index 9417351747f3..4469ae2a3dfd 100644 --- a/docs/getting_started_introduction.md +++ b/docs/getting_started_introduction.md @@ -17,7 +17,7 @@ Within the folder `keyboards`, its subfolder `handwired` and its vendor and manu * `keymaps/`: Different keymaps that can be built * `rules.mk`: The file that sets the default "make" options. Do not edit this file directly, instead use a keymap specific `rules.mk`. * `config.h`: The file that sets the default compile time options. Do not edit this file directly, instead use a keymap specific `config.h`. -* `info.json`: The file used for setting layout for QMK Configurator. See [Configurator Support](reference_configurator_support) for more information. +* `keyboard.json`: The file used for setting layout for QMK Configurator. See [Configurator Support](reference_configurator_support) for more information. * `readme.md`: A brief overview of the keyboard. * `.h`: This file is where the keyboard layout is defined against the keyboard's switch matrix. * `.c`: This file is where you can find custom code for the keyboard.