Compare commits
10 Commits
0d3a4b7bbb
...
308d6bce6e
| Author | SHA1 | Date | |
|---|---|---|---|
|
308d6bce6e | ||
|
|
2d96f469c8 | ||
|
|
2ee76be6fe | ||
|
|
f0b20c1c93 | ||
|
|
8f5c7bbfd4 | ||
|
|
7d1f84e3eb | ||
|
|
4dfc45d4ab | ||
|
|
2423136788 | ||
|
|
af908826cd | ||
|
|
d1ad34761a |
2
.github/workflows/pre-commit.yml
vendored
2
.github/workflows/pre-commit.yml
vendored
@ -12,4 +12,4 @@ jobs:
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: 3.x
|
||||
- uses: pre-commit/action@v3.0.0
|
||||
- uses: pre-commit/action@v3.0.1
|
||||
|
||||
@ -157,7 +157,7 @@ config ZMK_BLE_EXPERIMENTAL_CONN
|
||||
bool "Experimental BLE connection changes"
|
||||
help
|
||||
Enables a combination of settings that are planned to be default in future versions of ZMK
|
||||
to improve connection stability. This includes changes to timing on BLE pairing initation,
|
||||
to improve connection stability. This includes changes to timing on BLE pairing initiation,
|
||||
restores use of the updated/new LLCP implementation, and disables 2M PHY support.
|
||||
|
||||
config ZMK_BLE_EXPERIMENTAL_SEC
|
||||
@ -257,7 +257,7 @@ menu "Display/LED Options"
|
||||
rsource "src/display/Kconfig"
|
||||
|
||||
menuconfig ZMK_RGB_UNDERGLOW
|
||||
bool "RGB Adressable LED Underglow"
|
||||
bool "RGB Addressable LED Underglow"
|
||||
select LED_STRIP
|
||||
select ZMK_LOW_PRIORITY_WORK_QUEUE
|
||||
|
||||
|
||||
@ -88,7 +88,7 @@
|
||||
fuelgauge: bq274xx@55 {
|
||||
compatible = "ti,bq274xx";
|
||||
reg = <0x55>;
|
||||
design-voltage = <3700>; //Battery Design Volatge in mV
|
||||
design-voltage = <3700>; //Battery Design Voltage in mV
|
||||
design-capacity = <180>; //Battery Design Capacity in mAh
|
||||
taper-current = <2>; //Battery Taper current in mAh
|
||||
terminate-voltage = <2750>; //Battery Terminate Voltage in mV
|
||||
|
||||
@ -96,7 +96,7 @@
|
||||
fuelgauge: bq274xx@55 {
|
||||
compatible = "ti,bq274xx";
|
||||
reg = <0x55>;
|
||||
design-voltage = <3700>; //Battery Design Volatge in mV
|
||||
design-voltage = <3700>; //Battery Design Voltage in mV
|
||||
design-capacity = <180>; //Battery Design Capacity in mAh
|
||||
taper-current = <2>; //Battery Taper current in mAh 2.1
|
||||
terminate-voltage = <2750>; //Battery Terminate Voltage in mV
|
||||
|
||||
@ -4,6 +4,12 @@ config BOARD_ENABLE_DCDC
|
||||
default y
|
||||
depends on (BOARD_MIKOTO_520)
|
||||
|
||||
config BOARD_ENABLE_DCDC_HV
|
||||
bool "High voltage DCDC converter"
|
||||
select SOC_DCDC_NRF52X_HV
|
||||
default y
|
||||
depends on (BOARD_MIKOTO_520)
|
||||
|
||||
choice BOARD_MIKOTO_CHARGER_CURRENT
|
||||
prompt "Charge current to supply to attached batteries"
|
||||
depends on (BOARD_MIKOTO_520)
|
||||
|
||||
@ -5,3 +5,9 @@ config BOARD_ENABLE_DCDC
|
||||
select SOC_DCDC_NRF52X
|
||||
default y
|
||||
depends on (BOARD_NICE_NANO || BOARD_NICE_NANO_V2)
|
||||
|
||||
config BOARD_ENABLE_DCDC_HV
|
||||
bool "High voltage DCDC converter"
|
||||
select SOC_DCDC_NRF52X_HV
|
||||
default y
|
||||
depends on (BOARD_NICE_NANO_V2)
|
||||
|
||||
@ -5,7 +5,7 @@ type: interconnect
|
||||
url: https://wiki.seeedstudio.com/Seeeduino-XIAO/
|
||||
manufacturer: Seeed
|
||||
description: |
|
||||
The Seeed(uino) XIAO is a popular smaller format micro-controller, that has gained popularity as an alterative
|
||||
The Seeed(uino) XIAO is a popular smaller format micro-controller, that has gained popularity as an alternative
|
||||
to the SparkFun Pro Micro. Since its creation, several pin compatible controllers, such
|
||||
as the Seeeduino XIAO BLE, Adafruit QT Py and Adafruit QT Py RP2040, have become available.
|
||||
node_labels:
|
||||
|
||||
@ -125,9 +125,9 @@ nice_view_spi: &arduino_spi {
|
||||
toggle-mode;
|
||||
|
||||
input-gpios
|
||||
= <&arduino_header 4 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
|
||||
, <&arduino_header 3 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
|
||||
, <&arduino_header 2 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
|
||||
= <&arduino_header 4 GPIO_ACTIVE_LOW>
|
||||
, <&arduino_header 3 GPIO_ACTIVE_LOW>
|
||||
, <&arduino_header 2 GPIO_ACTIVE_LOW>
|
||||
;
|
||||
};
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@
|
||||
|
||||
/ {
|
||||
behaviors {
|
||||
/omit-if-no-ref/ soft_off: keymap_soft_off {
|
||||
/omit-if-no-ref/ soft_off: z_so_off {
|
||||
compatible = "zmk,behavior-soft-off";
|
||||
#binding-cells = <0>;
|
||||
split-peripheral-off-on-press;
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
* SPDX-License-Identifier: MIT
|
||||
*/
|
||||
|
||||
/* This provies a mapping from Arduino Uno to Arduino Pro Micro pins for development */
|
||||
/* This provides a mapping from Arduino Uno to Arduino Pro Micro pins for development */
|
||||
|
||||
/ {
|
||||
pro_micro_d: connector_d {
|
||||
|
||||
@ -23,12 +23,12 @@ int zmk_display_init(void);
|
||||
*
|
||||
* @param listener THe ZMK Event manager listener name.
|
||||
* @param state_type The struct/enum type used to store/transfer state.
|
||||
* @param cb The callback to invoke in the dispaly queue context to update the UI. Should be `void
|
||||
* @param cb The callback to invoke in the display queue context to update the UI. Should be `void
|
||||
* func(state_type)` signature.
|
||||
* @param state_func The callback function to invoke to fetch the updated state from ZMK core.
|
||||
* Should be `state type func(const zmk_event_t *eh)` signature.
|
||||
* @retval listner##_init Generates a function `listener##_init` that should be called by the widget
|
||||
* once ready to be updated.
|
||||
* @retval listener##_init Generates a function `listener##_init` that should be called by the
|
||||
* widget once ready to be updated.
|
||||
**/
|
||||
#define ZMK_DISPLAY_WIDGET_LISTENER(listener, state_type, cb, state_func) \
|
||||
K_MUTEX_DEFINE(listener##_mutex); \
|
||||
|
||||
@ -181,7 +181,7 @@ static void release_captured_events() {
|
||||
//
|
||||
// Events for different mod-tap instances are separated by a NULL pointer.
|
||||
//
|
||||
// The first event popped will never be catched by the next active hold-tap
|
||||
// The first event popped will never be caught by the next active hold-tap
|
||||
// because to start capturing a mod-tap-key-down event must first completely
|
||||
// go through the events queue.
|
||||
//
|
||||
|
||||
@ -57,6 +57,9 @@ static int on_keymap_binding_released(struct zmk_behavior_binding *binding,
|
||||
uint32_t hold_time = k_uptime_get() - data->press_start;
|
||||
|
||||
if (hold_time > config->hold_time_ms) {
|
||||
if (IS_ENABLED(CONFIG_ZMK_SPLIT) && IS_ENABLED(CONFIG_ZMK_SPLIT_ROLE_CENTRAL)) {
|
||||
k_sleep(K_MSEC(100));
|
||||
}
|
||||
zmk_pm_soft_off();
|
||||
} else {
|
||||
LOG_INF("Not triggering soft off: held for %d and hold time is %d", hold_time,
|
||||
|
||||
@ -162,7 +162,7 @@ static int setup_candidates_for_first_keypress(int32_t position, int64_t timesta
|
||||
|
||||
static int filter_candidates(int32_t position) {
|
||||
// this code iterates over candidates and the lookup together to filter in O(n)
|
||||
// assuming they are both sorted on key_position_len, virtal_key_position
|
||||
// assuming they are both sorted on key_position_len, virtual_key_position
|
||||
int matches = 0, lookup_idx = 0, candidate_idx = 0;
|
||||
while (lookup_idx < CONFIG_ZMK_COMBO_MAX_COMBOS_PER_KEY &&
|
||||
candidate_idx < CONFIG_ZMK_COMBO_MAX_COMBOS_PER_KEY) {
|
||||
|
||||
@ -173,7 +173,7 @@ static int ksbb_pm_action(const struct device *dev, enum pm_device_action action
|
||||
struct ksbb_data ksbb_data_##n = {}; \
|
||||
PM_DEVICE_DT_INST_DEFINE(n, ksbb_pm_action); \
|
||||
DEVICE_DT_INST_DEFINE(n, ksbb_init, PM_DEVICE_DT_INST_GET(n), &ksbb_data_##n, \
|
||||
&ksbb_config_##n, POST_KERNEL, \
|
||||
&ksbb_config_##n, APPLICATION, \
|
||||
CONFIG_ZMK_KSCAN_SIDEBAND_BEHAVIORS_INIT_PRIORITY, &ksbb_api);
|
||||
|
||||
DT_INST_FOREACH_STATUS_OKAY(KSBB_INST)
|
||||
|
||||
@ -24,7 +24,7 @@ config ZMK_SPLIT_PERIPHERAL_HID_INDICATORS
|
||||
bool "Peripheral HID Indicators"
|
||||
depends on ZMK_HID_INDICATORS
|
||||
help
|
||||
Enable propogating the HID (LED) Indicator state to the split peripheral(s).
|
||||
Enable propagating the HID (LED) Indicator state to the split peripheral(s).
|
||||
|
||||
#ZMK_SPLIT
|
||||
endif
|
||||
|
||||
@ -585,7 +585,7 @@ static bool split_central_eir_found(const bt_addr_le_t *addr) {
|
||||
return false;
|
||||
}
|
||||
|
||||
LOG_DBG("Initiating new connnection");
|
||||
LOG_DBG("Initiating new connection");
|
||||
struct bt_le_conn_param *param =
|
||||
BT_LE_CONN_PARAM(CONFIG_ZMK_SPLIT_BLE_PREF_INT, CONFIG_ZMK_SPLIT_BLE_PREF_INT,
|
||||
CONFIG_ZMK_SPLIT_BLE_PREF_LATENCY, CONFIG_ZMK_SPLIT_BLE_PREF_TIMEOUT);
|
||||
|
||||
@ -7,7 +7,7 @@
|
||||
mod_morph: mod_morph {
|
||||
compatible = "zmk,behavior-mod-morph";
|
||||
#binding-cells = <0>;
|
||||
bindings = <&kp A>, <&kp LS(B)>; // implict mod overwrite
|
||||
bindings = <&kp A>, <&kp LS(B)>; // implicit mod overwrite
|
||||
mods = <(MOD_LSFT|MOD_RSFT)>;
|
||||
};
|
||||
};
|
||||
|
||||
@ -19,7 +19,7 @@ There's been lots of various activity in ZMK land!
|
||||
- Tons of [documentation](/docs) work.
|
||||
- Refactoring ([#73](https://github.com/zmkfirmware/zmk/pull/73), [#74](https://github.com/zmkfirmware/zmk/pull/74)) of [keymaps](/docs/features/keymaps) to make them simpler for users.
|
||||
- Mod-Tap Behavior (docs coming!) is much improved ([#69](https://github.com/zmkfirmware/zmk/pull/69)) and usable now.
|
||||
- An initial [`setup.sh`](http://localhost:3000/docs/user-setup#user-config-setup-script) script was created, allowing users to quickly bootstrap a "user config" setup and push it to GitHub, where GitHub Actions will build the firmware for you.
|
||||
- An initial [`setup.sh`](/docs/user-setup#user-config-setup-script) script was created, allowing users to quickly bootstrap a "user config" setup and push it to GitHub, where GitHub Actions will build the firmware for you.
|
||||
- Corne shield ([#80](https://github.com/zmkfirmware/zmk/pull/80)) shield definition was added.
|
||||
- Initial [encoder](/docs/features/encoders) support ([#61](https://github.com/zmkfirmware/zmk/pull/61)) was added.
|
||||
|
||||
|
||||
@ -61,7 +61,7 @@ Once the container has rebuilt, VS Code will be running the 2.5 Docker image.
|
||||
|
||||
The following steps will get you building ZMK locally against Zephyr 2.5:
|
||||
|
||||
- Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
|
||||
- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
|
||||
- pull the latest ZMK `main` with `git pull` for your ZMK checkout
|
||||
- run `west update` to pull the updated Zephyr version and its dependencies
|
||||
|
||||
|
||||
@ -62,7 +62,7 @@ Once the container has rebuilt, VS Code will be running the 3.0 Docker image.
|
||||
|
||||
The following steps will get you building ZMK locally against Zephyr 3.0:
|
||||
|
||||
- Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
|
||||
- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
|
||||
- pull the latest ZMK `main` with `git pull` for your ZMK checkout
|
||||
- run `west update` to pull the updated Zephyr version and its dependencies
|
||||
|
||||
|
||||
@ -132,7 +132,7 @@ Another persistent bug that Apple users experienced was related to crashes and p
|
||||
The long awaited locality enhancement was finally merged by [petejohanson] in [#547](https://github.com/zmkfirmware/zmk/pull/547), allowing more fine grained control of where certain behaviors are invoked. Some key improvements thanks to the changes:
|
||||
|
||||
- [RGB Underglow](/docs/features/underglow) behaviors now run globally, so enabling/disabling RGB, changing the color, animation, etc. applies to both sides of a split properly.
|
||||
- [Reset](/docs/behaviors/reset#reset)/[Bootloader](/docs/behaviors/reset#bootloader) behaviors now run wherever the key was pressed. For example, adding a `&bootloader` reference to the peripheral side of a split will now put that side of the split into the bootloader when pressed.
|
||||
- [Reset](/docs/behaviors/reset#reset)/[Bootloader](/docs/behaviors/reset#bootloader-reset) behaviors now run wherever the key was pressed. For example, adding a `&bootloader` reference to the peripheral side of a split will now put that side of the split into the bootloader when pressed.
|
||||
|
||||
#### Split Connections
|
||||
|
||||
|
||||
@ -57,7 +57,7 @@ and then update it as appropriate to build the right shields/boards for your con
|
||||
|
||||
### Upgrade a manual script
|
||||
|
||||
If you have a custom GitHub Actions workflow you need to maintain for some reason, you can update the workflow to to use the `stable` Docker image tag for the build:
|
||||
If you have a custom GitHub Actions workflow you need to maintain for some reason, you can update the workflow to use the `stable` Docker image tag for the build:
|
||||
|
||||
- Open `.github/workflows/build.yml` in your editor/IDE
|
||||
- Change `zmkfirmware/zmk-build-arm:2.5` to `zmkfirmware/zmk-build-arm:stable` wherever it is found
|
||||
@ -87,7 +87,7 @@ Once the container has rebuilt, VS Code will be running the 3.2 Docker image.
|
||||
|
||||
The following steps will get you building ZMK locally against Zephyr 3.2:
|
||||
|
||||
- Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
|
||||
- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
|
||||
- Install the latest version of `west` by running `pip3 install --user --update west`.
|
||||
- pull the latest ZMK `main` with `git pull` for your ZMK checkout
|
||||
- run `west update` to pull the updated Zephyr version and its dependencies
|
||||
|
||||
@ -145,7 +145,7 @@ I should note that, as a native English speaker and typer, I don't use any of th
|
||||
|
||||
## Keyboard Latency Testing
|
||||
|
||||
The last project I want to mention is a tool for testing keyboard latency. It requires only a Rasbperry Pi, an optocoupler IC, a resistor, and some wire. If you've ever wondered how ZMK's latency compares to other keyboards, you can [check the results here](https://github.com/joelspadin/keyboard-latency-tester/blob/main/results/chart.ipynb)!
|
||||
The last project I want to mention is a tool for testing keyboard latency. It requires only a Raspberry Pi, an optocoupler IC, a resistor, and some wire. If you've ever wondered how ZMK's latency compares to other keyboards, you can [check the results here](https://github.com/joelspadin/keyboard-latency-tester/blob/main/results/chart.ipynb)!
|
||||
|
||||
I don't have a very large collection of keyboards though, so the data is pretty limited so far. If you want to try it on your own keyboard, see the instructions on the [keyboard latency tester README](https://github.com/joelspadin/keyboard-latency-tester), and please send me a PR with your results!
|
||||
|
||||
|
||||
@ -70,7 +70,7 @@ Once the container has rebuilt, VS Code will be running the 3.5 Docker image.
|
||||
|
||||
The following steps will get you building ZMK locally against Zephyr 3.5:
|
||||
|
||||
- Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
|
||||
- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
|
||||
- Install the latest version of `west` by running `pip3 install --user --update west`.
|
||||
- Pull the latest ZMK `main` with `git pull` for your ZMK checkout
|
||||
- Run `west update` to pull the updated Zephyr version and its dependencies
|
||||
|
||||
@ -7,7 +7,7 @@ sidebar_label: Caps Word
|
||||
|
||||
The caps word behavior behaves similar to a caps lock, but will automatically deactivate when any key not in a continue list is pressed, or if the caps word key is pressed again. For smaller keyboards using [mod-taps](/docs/behaviors/mod-tap), this can help avoid repeated alternating holds when typing words in all caps.
|
||||
|
||||
The modifiers are applied only to to the alphabetic (`A` to `Z`) keycodes, to avoid automatically applying them to numeric values, etc.
|
||||
The modifiers are applied only to the alphabetic (`A` to `Z`) keycodes, to avoid automatically applying them to numeric values, etc.
|
||||
|
||||
### Behavior Binding
|
||||
|
||||
|
||||
@ -46,10 +46,10 @@ Below is a summary of pre-defined behavior bindings and user-definable behaviors
|
||||
|
||||
## Reset behaviors
|
||||
|
||||
| Binding | Behavior | Description |
|
||||
| ------------- | --------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| `&sys_reset` | [Reset](reset.md#reset) | Resets the keyboard and re-runs the firmware flashed to the device |
|
||||
| `&bootloader` | [Bootloader](reset.md#bootloader) | Resets the keyboard and puts it into bootloader mode, allowing you to flash new firmware |
|
||||
| Binding | Behavior | Description |
|
||||
| ------------- | --------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| `&sys_reset` | [Reset](reset.md#reset) | Resets the keyboard and re-runs the firmware flashed to the device |
|
||||
| `&bootloader` | [Bootloader](reset.md#bootloader-reset) | Resets the keyboard and puts it into bootloader mode, allowing you to flash new firmware |
|
||||
|
||||
## Output selection behaviors
|
||||
|
||||
|
||||
@ -18,7 +18,7 @@ Definition file: [zmk/app/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/
|
||||
|
||||
:::note[Default setting]
|
||||
|
||||
While `CONFIG_ZMK_BATTERY_REPORTING` is disabled by default it is implied by `CONFIG_ZMK_BLE`, thus any board with BLE enabled will have this automatically enabled unless explicitly overriden.
|
||||
While `CONFIG_ZMK_BATTERY_REPORTING` is disabled by default it is implied by `CONFIG_ZMK_BLE`, thus any board with BLE enabled will have this automatically enabled unless explicitly overridden.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
@ -9,10 +9,10 @@ See [Configuration Overview](index.md) for instructions on how to change these s
|
||||
|
||||
## Kconfig
|
||||
|
||||
| Option | Type | Description | Default |
|
||||
| -------------------------------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
||||
| `CONFIG_ZMK_BLE_EXPERIMENTAL_CONN` | bool | Enables a combination of settings that are planned to be default in future versions of ZMK to improve connection stability. This includes changes to timing on BLE pairing initation, restores use of the updated/new LLCP implementation, and disables 2M PHY support. | n |
|
||||
| `CONFIG_ZMK_BLE_EXPERIMENTAL_SEC` | bool | Enables a combination of settings that are planned to be officially supported in the future. This includes enabling BT Secure Connection passkey entry, and allows overwrite of keys from previously paired hosts. | n |
|
||||
| `CONFIG_ZMK_BLE_EXPERIMENTAL_FEATURES` | bool | Aggregate config that enables both `CONFIG_ZMK_BLE_EXPERIMENTAL_CONN` and `CONFIG_ZMK_BLE_EXPERIMENTAL_SEC`. | n |
|
||||
| `CONFIG_ZMK_BLE_PASSKEY_ENTRY` | bool | Enable passkey entry during pairing for enhanced security. (Note: After enabling this, you will need to re-pair all previously paired hosts.) | n |
|
||||
| `CONFIG_BT_GATT_ENFORCE_SUBSCRIPTION` | bool | Low level setting for GATT subscriptions. Set to `n` to work around an annoying Windows bug with battery notifications. | y |
|
||||
| Option | Type | Description | Default |
|
||||
| -------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
|
||||
| `CONFIG_ZMK_BLE_EXPERIMENTAL_CONN` | bool | Enables a combination of settings that are planned to be default in future versions of ZMK to improve connection stability. This includes changes to timing on BLE pairing initiation, restores use of the updated/new LLCP implementation, and disables 2M PHY support. | n |
|
||||
| `CONFIG_ZMK_BLE_EXPERIMENTAL_SEC` | bool | Enables a combination of settings that are planned to be officially supported in the future. This includes enabling BT Secure Connection passkey entry, and allows overwrite of keys from previously paired hosts. | n |
|
||||
| `CONFIG_ZMK_BLE_EXPERIMENTAL_FEATURES` | bool | Aggregate config that enables both `CONFIG_ZMK_BLE_EXPERIMENTAL_CONN` and `CONFIG_ZMK_BLE_EXPERIMENTAL_SEC`. | n |
|
||||
| `CONFIG_ZMK_BLE_PASSKEY_ENTRY` | bool | Enable passkey entry during pairing for enhanced security. (Note: After enabling this, you will need to re-pair all previously paired hosts.) | n |
|
||||
| `CONFIG_BT_GATT_ENFORCE_SUBSCRIPTION` | bool | Low level setting for GATT subscriptions. Set to `n` to work around an annoying Windows bug with battery notifications. | y |
|
||||
|
||||
@ -81,10 +81,6 @@ Definition file: [zmk/app/module/dts/bindings/kscan/zmk,kscan-gpio-direct.yaml](
|
||||
| `toggle-mode` | bool | Use toggle switch mode. | n |
|
||||
| `wakeup-source` | bool | Mark this kscan instance as able to wake the keyboard from deep sleep | n |
|
||||
|
||||
By default, a switch will drain current through the internal pull up/down resistor whenever it is pressed. This is not ideal for a toggle switch, where the switch may be left in the "pressed" state for a long time. Enabling `toggle-mode` will make the driver flip between pull up and down as the switch is toggled to optimize for power.
|
||||
|
||||
`toggle-mode` applies to all switches handled by the instance of the driver. To use a toggle switch with other, non-toggle, direct GPIO switches, create two instances of the direct GPIO driver, one with `toggle-mode` and the other without. Then, use a [composite driver](#composite-driver) to combine them.
|
||||
|
||||
Assuming the switches connect each GPIO pin to the ground, the [GPIO flags](https://docs.zephyrproject.org/3.5.0/hardware/peripherals/gpio.html#api-reference) for the elements in `input-gpios` should be `(GPIO_ACTIVE_LOW | GPIO_PULL_UP)`:
|
||||
|
||||
```dts
|
||||
@ -98,6 +94,25 @@ Assuming the switches connect each GPIO pin to the ground, the [GPIO flags](http
|
||||
};
|
||||
```
|
||||
|
||||
By default, a switch will drain current through the internal pull up/down resistor whenever it is pressed. This is not ideal for a toggle switch, where the switch may be left in the "pressed" state for a long time. Enabling `toggle-mode` will make the driver enable and disable the internal pull up/down resistor as needed when the switch is toggled to minimise power draw. For `toggle-mode` to work correctly each pole of the switch needs a dedicated GPIO pin.
|
||||
|
||||
`toggle-mode` applies to all switches handled by the instance of the driver. To use a toggle switch with other, non-toggle, direct GPIO switches, create two instances of the direct GPIO driver, one with `toggle-mode` and the other without. Then, use a [composite driver](#composite-driver) to combine them. The state of the switch is read on power on, so if the switch is moved whilst the board is off this will get correctly interpreted by the driver.
|
||||
|
||||
When using `toggle-mode` the pull resistors get automatically set by the driver and should not be set in the devicetree via GPIO flags. Assuming the common pole of the switch is connected to ground with an SP3T switch:
|
||||
|
||||
```dts
|
||||
kscan_sp3t_toggle: kscan_sp3t_toggle {
|
||||
compatible = "zmk,kscan-gpio-direct";
|
||||
toggle-mode;
|
||||
|
||||
input-gpios
|
||||
= <&pro_micro 4 GPIO_ACTIVE_LOW>
|
||||
, <&pro_micro 3 GPIO_ACTIVE_LOW>
|
||||
, <&pro_micro 2 GPIO_ACTIVE_LOW>
|
||||
;
|
||||
};
|
||||
```
|
||||
|
||||
## Matrix Driver
|
||||
|
||||
Keyboard scan driver where keys are arranged on a matrix with one GPIO per row and column.
|
||||
|
||||
@ -31,7 +31,7 @@ Making changes to any of the settings in this section modifies the HID report de
|
||||
|
||||
| Config | Type | Description | Default |
|
||||
| ------------------------------------- | ---- | -------------------------------------------------------------- | ------- |
|
||||
| `CONFIG_ZMK_HID_INDICATORS` | bool | Enable reciept of HID/LED indicator state from connected hosts | n |
|
||||
| `CONFIG_ZMK_HID_INDICATORS` | bool | Enable receipt of HID/LED indicator state from connected hosts | n |
|
||||
| `CONFIG_ZMK_HID_CONSUMER_REPORT_SIZE` | int | Number of consumer keys simultaneously reportable | 6 |
|
||||
|
||||
Exactly zero or one of the following options may be set to `y`. The first is used if none are set.
|
||||
|
||||
@ -40,7 +40,7 @@ If you need to, a review of [Learn The Basics Of Git In Under 10 Minutes](https:
|
||||
:::
|
||||
|
||||
:::note
|
||||
It is also possible to build firmware locally on your computer by following the [toolchain setup](development/setup.mdx) and
|
||||
It is also possible to build firmware locally on your computer by following the [toolchain setup](development/setup/index.md) and
|
||||
[building instructions](development/build-flash.mdx), which includes pointers to
|
||||
[building using your `zmk-config` folder](development/build-flash.mdx#building-from-zmk-config-folder).
|
||||
:::
|
||||
|
||||
@ -554,7 +554,7 @@ Add additional bindings as necessary to match the default number of encoders on
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
Using GitHub Actions to build your new firmware can save you from doing any local [development setup](./setup.mdx),
|
||||
Using GitHub Actions to build your new firmware can save you from doing any local [development setup](./setup/index.md),
|
||||
at the expense of a longer feedback loop if there are issues. To push your changes and trigger a build:
|
||||
|
||||
- Add all your pending changes with `git add .`
|
||||
@ -566,7 +566,7 @@ Once pushed, click on the "Actions" tab of the repo you created in the first ste
|
||||
### Local Build
|
||||
|
||||
:::note
|
||||
To build locally, be sure you've followed the [development setup](./setup.mdx) guide first.
|
||||
To build locally, be sure you've followed the [development setup](./setup/index.md) guide first.
|
||||
:::
|
||||
|
||||
Once you've fully created the new keyboard shield definition,
|
||||
|
||||
@ -1,322 +0,0 @@
|
||||
---
|
||||
title: Toolchain Setup
|
||||
sidebar_label: Toolchain Setup
|
||||
---
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
export const OsTabs = (props) => (
|
||||
<Tabs
|
||||
groupId="operating-systems"
|
||||
defaultValue="debian"
|
||||
values={[
|
||||
{ label: "VS Code & Docker", value: "docker" },
|
||||
{ label: "Debian/Ubuntu", value: "debian" },
|
||||
{ label: "Windows", value: "win" },
|
||||
{ label: "macOS", value: "mac" },
|
||||
{ label: "Raspberry OS", value: "raspberryos" },
|
||||
{ label: "Fedora", value: "fedora" },
|
||||
]}
|
||||
>
|
||||
{/* eslint-disable-next-line */}
|
||||
{props.children}
|
||||
</Tabs>
|
||||
);
|
||||
|
||||
This guide will show you how to set up a development environment for building ZMK locally.
|
||||
|
||||
## Install Dependencies
|
||||
|
||||
Click the operating system you are using. (The VS Code & Docker option can be used on any OS.)
|
||||
|
||||
<OsTabs>
|
||||
<TabItem value="docker">
|
||||
|
||||
This option use the same [Docker image which is used by the GitHub action](https://github.com/zmkfirmware/zmk-docker) for local development. Beyond the benefits of [dev/prod parity](https://12factor.net/dev-prod-parity), this approach is also the easiest to set up. No toolchain or dependencies are necessary when using Docker; the container image you'll be using already has the toolchain installed and set up to use.
|
||||
|
||||
1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for your operating system.
|
||||
2. Install [Visual Studio Code](https://code.visualstudio.com/)
|
||||
3. Install the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
|
||||
|
||||
:::info
|
||||
The docker container already includes `west`. Skip past the following section to [Get Source Code](#get-source-code).
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="debian">
|
||||
|
||||
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections:
|
||||
|
||||
- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
|
||||
- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
|
||||
- [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk)
|
||||
|
||||
Return to this guide once you are finished with each section.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="win">
|
||||
|
||||
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections:
|
||||
|
||||
- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
|
||||
- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
|
||||
- [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk)
|
||||
|
||||
Return to this guide once you are finished with each section.
|
||||
|
||||
`dfu-util` is required to flash devices that use DFU, but there is currently no maintained package for it on Chocolatey. [QMK Toolbox](https://github.com/qmk/qmk_toolbox) contains a working version of it though.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="mac">
|
||||
|
||||
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections:
|
||||
|
||||
- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
|
||||
- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
|
||||
- [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk)
|
||||
|
||||
Return to this guide once you are finished with each section.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="raspberryos">
|
||||
|
||||
#### Install Base Dependencies
|
||||
|
||||
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions for Ubuntu under these sections:
|
||||
|
||||
- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
|
||||
- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
|
||||
|
||||
Return to this guide once you are finished with each section.
|
||||
|
||||
#### Install Cross-Compile Toolchain
|
||||
|
||||
Because Raspberry OS runs on the same architecture (but different ABI) as ARM keyboard MCUs, the operating system's installed [cross compilers](https://docs.zephyrproject.org/3.5.0/develop/toolchains/other_x_compilers.html) can be used to target the different ABI. Building for non-ARM MCUs has not been tested.
|
||||
|
||||
First, the cross compiler should be installed:
|
||||
|
||||
```sh
|
||||
sudo apt install gcc-arm-none-eabi
|
||||
```
|
||||
|
||||
Next, we'll configure Zephyr with some [environment variables](https://docs.zephyrproject.org/3.5.0/develop/env_vars.html#env-vars) needed to find the cross compiler. Create a file named `~/.zephyrrc` if it doesn't exist, and add these lines to it:
|
||||
|
||||
```sh
|
||||
export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
|
||||
export CROSS_COMPILE=/usr/bin/arm-none-eabi-
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fedora">
|
||||
|
||||
Follow Zephyr's [Install Linux Host Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/installation_linux.html) documentation for Fedora.
|
||||
|
||||
</TabItem>
|
||||
</OsTabs>
|
||||
|
||||
### Install West
|
||||
|
||||
`west` is the [Zephyr® Project's meta-tool](https://docs.zephyrproject.org/3.5.0/develop/west/index.html) used to configure and build Zephyr OS applications.
|
||||
|
||||
West can be installed by using the `pip` python package manager. The [Zephyr™ instructions](https://docs.zephyrproject.org/3.5.0/develop/west/install.html) are summarized here:
|
||||
|
||||
<Tabs
|
||||
defaultValue="linux"
|
||||
groupId="python-os"
|
||||
values={[
|
||||
{label: 'Linux', value: 'linux'},
|
||||
{label: 'Windows', value: 'win'},
|
||||
{label: 'macOS', value: 'mac'},
|
||||
]}>
|
||||
<TabItem value="linux">
|
||||
|
||||
Install west:
|
||||
|
||||
```sh
|
||||
pip3 install --user -U west
|
||||
```
|
||||
|
||||
Verify that west is installed:
|
||||
|
||||
```sh
|
||||
west --version
|
||||
```
|
||||
|
||||
This should print a message like "West version: v0.14.0". If it prints an error instead, make sure `~/.local/bin` is on your `PATH` environment variable. You can add it with these commands:
|
||||
|
||||
```sh
|
||||
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="win">
|
||||
|
||||
Install west:
|
||||
|
||||
```sh
|
||||
pip3 install -U west
|
||||
```
|
||||
|
||||
Verify that west is installed:
|
||||
|
||||
```sh
|
||||
west --version
|
||||
```
|
||||
|
||||
This should print a message like "West version: v0.14.0". If it prints an error instead, make sure that the Python scripts directory is on your `PATH` environment variable. You can add it by opening a PowerShell window and running the following commands:
|
||||
|
||||
```powershell
|
||||
$Scripts = python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
|
||||
$Path = [Environment]::GetEnvironmentVariable('PATH', 'User')
|
||||
[Environment]::SetEnvironmentVariable('PATH', "$Path;$Scripts", 'User')
|
||||
$env:PATH += ";$Scripts"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="mac">
|
||||
|
||||
Install west:
|
||||
|
||||
```sh
|
||||
pip3 install -U west
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Get Source Code
|
||||
|
||||
Next, you'll need to clone the ZMK source repository if you haven't already. Navigate to the folder you would like to place your `zmk` directory in and run the following command:
|
||||
|
||||
```
|
||||
git clone https://github.com/zmkfirmware/zmk.git
|
||||
```
|
||||
|
||||
## Initialize & Update Zephyr Workspace
|
||||
|
||||
Since ZMK is built as a Zephyr™ application, the next step is
|
||||
to use `west` to initialize and update your workspace. The ZMK
|
||||
Zephyr™ application is in the `app/` source directory:
|
||||
|
||||
### Step into the repository
|
||||
|
||||
<OsTabs>
|
||||
<TabItem value="debian">
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="raspberryos">
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fedora">
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="mac">
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="win">
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="docker">
|
||||
|
||||
Open the `zmk` checkout folder in VS Code. The repository includes a configuration for containerized development, so an alert will pop up:
|
||||
|
||||
|
||||
|
||||
Click `Reopen in Container` in order to reopen the VS Code with the running container.
|
||||
|
||||
The first time you do this on your machine, it will pull the docker image down from the registry and build the container. Subsequent launches are much faster!
|
||||
|
||||
:::warning
|
||||
All subsequent steps must be performed from the VS Code terminal _inside_ the container.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
</OsTabs>
|
||||
|
||||
### Initialize the Application
|
||||
|
||||
```sh
|
||||
west init -l app/
|
||||
```
|
||||
|
||||
### Update to Fetch Modules
|
||||
|
||||
```sh
|
||||
west update
|
||||
```
|
||||
|
||||
:::tip
|
||||
This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can take 10-15 minutes even on a good internet connection!
|
||||
:::
|
||||
|
||||
:::info
|
||||
If you're using Docker, you're done with setup! You must restart the container at this point. The easiest way to do so is to close the VS Code window, verify that the container has stopped in Docker Dashboard, and reopen the container with VS Code.
|
||||
|
||||
Once your container is restarted, proceed to [Building and Flashing](development/build-flash.mdx).
|
||||
:::
|
||||
|
||||
### Export Zephyr CMake package
|
||||
|
||||
This allows CMake to load the code needed to build ZMK.
|
||||
|
||||
```sh
|
||||
west zephyr-export
|
||||
```
|
||||
|
||||
### Install Zephyr Python Dependencies
|
||||
|
||||
Some additional Python dependencies are listed in Zephyr's `scripts/requirements.txt` file.
|
||||
|
||||
<Tabs
|
||||
defaultValue="linux"
|
||||
groupId="python-os"
|
||||
values={[
|
||||
{label: 'Linux', value: 'linux'},
|
||||
{label: 'Windows', value: 'win'},
|
||||
{label: 'macOS', value: 'mac'},
|
||||
]}>
|
||||
<TabItem value="linux">
|
||||
|
||||
```sh
|
||||
pip3 install --user -r zephyr/scripts/requirements.txt
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="win">
|
||||
|
||||
```sh
|
||||
pip3 install -r zephyr/scripts/requirements.txt
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="mac">
|
||||
|
||||
```sh
|
||||
pip3 install -r zephyr/scripts/requirements.txt
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
53
docs/docs/development/setup/docker.md
Normal file
53
docs/docs/development/setup/docker.md
Normal file
@ -0,0 +1,53 @@
|
||||
---
|
||||
title: Docker
|
||||
sidebar_label: Docker
|
||||
---
|
||||
|
||||
:::note
|
||||
Currently the Docker approach is only documented for [VS Code](https://github.com/microsoft/vscode) (not [Code OSS](https://github.com/microsoft/vscode/wiki/Differences-between-the-repository-and-Visual-Studio-Code)). While it can be replicated using [devcontainers](https://containers.dev/) this is not documented yet - contributions are welcome!
|
||||
:::
|
||||
|
||||
### Source Code
|
||||
|
||||
First, you'll need to clone the ZMK source repository if you haven't already. Open a terminal and navigate to the folder you would like to place your `zmk` directory in, then run the following command:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/zmkfirmware/zmk.git
|
||||
```
|
||||
|
||||
### Installing Development Tools
|
||||
|
||||
1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for your operating system.
|
||||
2. Install [VS Code](https://code.visualstudio.com/).
|
||||
3. Install the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
|
||||
|
||||
### Initialize & Update Zephyr Workspace
|
||||
|
||||
Open the `zmk` checkout folder in VS Code. The repository includes a configuration for containerized development, so an alert will pop up:
|
||||
|
||||
|
||||
|
||||
Click `Reopen in Container` in order to reopen the VS Code with the running container. If the alert fails to pop up or you accidentally close it, you can perform the same action by pressing `ctrl+shift+p` and selecting `Remote: Show Remote Menu`.
|
||||
|
||||
The first time you do this on your machine, it will pull the docker image down from the registry and build the container. Subsequent launches are much faster!
|
||||
|
||||
:::caution
|
||||
The following step and any future [build commands](../build-flash.mdx) must be executed from the VS Code terminal _inside_ the container.
|
||||
:::
|
||||
|
||||
Initialize the application and update to fetch modules, including Zephyr:
|
||||
|
||||
```sh
|
||||
west init -l app/
|
||||
west update
|
||||
```
|
||||
|
||||
:::tip
|
||||
This step pulls down quite a bit of tooling, be patient!
|
||||
:::
|
||||
|
||||
:::info
|
||||
You must restart the container at this point. The easiest way to do so is to close the VS Code window, verify that the container has stopped in Docker Dashboard, and reopen the container with VS Code.
|
||||
|
||||
Your setup is complete once your container has restarted.
|
||||
:::
|
||||
20
docs/docs/development/setup/index.md
Normal file
20
docs/docs/development/setup/index.md
Normal file
@ -0,0 +1,20 @@
|
||||
---
|
||||
title: Getting Started
|
||||
sidebar_label: Getting Started
|
||||
---
|
||||
|
||||
:::tip
|
||||
We recommend reading through the setup process before following it step by step, to ensure that you are happy with installing the required dependencies.
|
||||
:::
|
||||
|
||||
## Environment Setup
|
||||
|
||||
There are two ways to set up the ZMK development environment:
|
||||
|
||||
- [Docker](/docs/development/setup/docker): \
|
||||
A self-contained development environment. It uses the same [Docker image which is used by the GitHub action](https://github.com/zmkfirmware/zmk-docker) for local development. Beyond the benefits of [dev/prod parity](https://12factor.net/dev-prod-parity), this approach may be easier to set up for some operating systems. No toolchain or dependencies are necessary when using Docker; the container image has the toolchain installed and set up to use.
|
||||
|
||||
- [Native](/docs/development/setup/native):\
|
||||
This uses your operating system directly. Usually runs slightly faster than the Docker approach, and can be preferable for users who already have the dependencies on their system.
|
||||
|
||||
Please see the [Docker](/docs/development/setup/docker) instructions or [native](/docs/development/setup/native) instructions to continue setup.
|
||||
353
docs/docs/development/setup/native.mdx
Normal file
353
docs/docs/development/setup/native.mdx
Normal file
@ -0,0 +1,353 @@
|
||||
---
|
||||
title: Native Setup
|
||||
sidebar_label: Native
|
||||
---
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
export const OsTabs = (props) => (
|
||||
<Tabs
|
||||
groupId="operating-system"
|
||||
defaultValue="ubuntu"
|
||||
values={[
|
||||
{ label: "Ubuntu", value: "ubuntu" },
|
||||
{ label: "Windows", value: "win" },
|
||||
{ label: "Mac OS", value: "mac" }
|
||||
]}
|
||||
>
|
||||
{/* eslint-disable-next-line */}
|
||||
{props.children}
|
||||
</Tabs>
|
||||
|
||||
);
|
||||
|
||||
export const OsNoteTabs = (props) => (
|
||||
<Tabs
|
||||
groupId="operating-system"
|
||||
defaultValue="win"
|
||||
values={[
|
||||
{ label: "Windows", value: "win" },
|
||||
{ label: "Raspberry OS", value: "raspberryos" },
|
||||
]}
|
||||
>
|
||||
{/* eslint-disable-next-line */}
|
||||
{props.children}
|
||||
</Tabs>
|
||||
|
||||
);
|
||||
|
||||
export const EnvTabs = (props) => (
|
||||
<Tabs
|
||||
groupId="python-environment"
|
||||
defaultValue="venv"
|
||||
values={[
|
||||
{ label: "Install within Virtual Environment", value: "venv" },
|
||||
{ label: "Install globally", value: "glob" },
|
||||
]}
|
||||
>
|
||||
{/* eslint-disable-next-line */}
|
||||
{props.children}
|
||||
</Tabs>
|
||||
|
||||
);
|
||||
|
||||
export const WinTermTabs = (props) => (
|
||||
<Tabs
|
||||
groupId="windows-terminal-choice"
|
||||
defaultValue="cmd"
|
||||
values={[
|
||||
{ label: "Command Prompt", value: "cmd" },
|
||||
{ label: "Powershell", value: "ps" },
|
||||
]}
|
||||
>
|
||||
{/* eslint-disable-next-line */}
|
||||
{props.children}
|
||||
</Tabs>
|
||||
|
||||
);
|
||||
|
||||
## 1. Install Zephyr Dependencies
|
||||
|
||||
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections:
|
||||
|
||||
- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
|
||||
- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
|
||||
|
||||
:::info
|
||||
Zephyr's [Install Linux Host Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/installation_linux.html) page may be of use for users of Linux distributions which are not based on Ubuntu.
|
||||
:::
|
||||
|
||||
## 2. Source Code
|
||||
|
||||
Next, you'll need to clone the ZMK source repository if you haven't already. Open a terminal and navigate to the folder you would like to place your `zmk` directory in, then run the following command:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/zmkfirmware/zmk.git
|
||||
```
|
||||
|
||||
Then step into the repository.
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
## 3. Get Zephyr and install Python dependencies
|
||||
|
||||
:::note
|
||||
These steps are very similar to Zephyr's [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies) instructions, but specialized for ZMK.
|
||||
:::
|
||||
|
||||
<EnvTabs>
|
||||
<TabItem value="venv">
|
||||
<Tabs groupId="operating-systems" defaultValue="ubuntu">
|
||||
<TabItem value="ubuntu" label="Ubuntu">
|
||||
|
||||
1. Use `apt` to install Python `venv` package:
|
||||
|
||||
```sh
|
||||
sudo apt install python3-venv
|
||||
```
|
||||
|
||||
2. Create a new virtual environment and activate it:
|
||||
|
||||
```sh
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="win" label="Windows">
|
||||
1. Create a new virtual environment:
|
||||
|
||||
```sh
|
||||
python -m venv .venv
|
||||
```
|
||||
|
||||
2. Activate the virtual environment:
|
||||
|
||||
<WinTermTabs>
|
||||
<TabItem value="cmd">
|
||||
|
||||
```sh
|
||||
.venv\Scripts\activate.bat
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="ps">
|
||||
|
||||
```powershell
|
||||
.venv\Scripts\Activate.ps1
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
</WinTermTabs>
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="mac" label="Mac OS">
|
||||
|
||||
1. Create a new virtual environment:
|
||||
|
||||
```sh
|
||||
python3 -m venv .venv
|
||||
```
|
||||
|
||||
2. Activate the virtual environment:
|
||||
|
||||
```sh
|
||||
source .venv/bin/activate
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
Once activated your shell will be prefixed with `(.venv)`. The virtual environment can be deactivated at any time by running `deactivate`.
|
||||
|
||||
:::note
|
||||
Remember to activate the virtual environment every time you start working.
|
||||
:::
|
||||
|
||||
4. Install west:
|
||||
|
||||
```sh
|
||||
pip install west
|
||||
```
|
||||
|
||||
5. Initialize the application and update to fetch modules, including Zephyr:
|
||||
|
||||
```sh
|
||||
west init -l app/
|
||||
west update
|
||||
```
|
||||
|
||||
:::tip
|
||||
This step pulls down quite a bit of tooling, be patient!
|
||||
:::
|
||||
|
||||
6. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
|
||||
|
||||
```sh
|
||||
west zephyr-export
|
||||
```
|
||||
|
||||
7. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
|
||||
|
||||
```sh
|
||||
pip install -r zephyr/scripts/requirements-base.txt
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="glob">
|
||||
<Tabs groupId="operating-systems" defaultValue="ubuntu">
|
||||
<TabItem value="ubuntu" label="Ubuntu">
|
||||
1. Install `west`:
|
||||
|
||||
```sh
|
||||
pip3 install --user -U west
|
||||
```
|
||||
|
||||
:::note
|
||||
You need `~/.local/bin` to be on your `PATH` environment variable; verify that it is by running
|
||||
|
||||
```sh
|
||||
west --version
|
||||
```
|
||||
|
||||
If this prints an error rather than a `west` version number, then add `~/.local/bin` to your `PATH`:
|
||||
|
||||
```sh
|
||||
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="win" label="Windows">
|
||||
1. Install `west`:
|
||||
|
||||
```sh
|
||||
pip install -U west
|
||||
```
|
||||
|
||||
:::note
|
||||
You need the Python scripts directory to be on your PATH environment variable; verify that it is by running
|
||||
|
||||
```sh
|
||||
west --version
|
||||
```
|
||||
|
||||
If this prints an error rather than a `west` version number, then add said directory to your `PATH` with PowerShell:
|
||||
|
||||
```powershell
|
||||
$Scripts = python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
|
||||
$Path = [Environment]::GetEnvironmentVariable('PATH', 'User')
|
||||
[Environment]::SetEnvironmentVariable('PATH', "$Path;$Scripts", 'User')
|
||||
$env:PATH += ";$Scripts"
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="mac" label="Mac OS">
|
||||
|
||||
1. Install `west`:
|
||||
|
||||
```sh
|
||||
pip3 install -U west
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
2. Initialize the application and update to fetch modules, including Zephyr:
|
||||
|
||||
```sh
|
||||
west init -l app/
|
||||
west update
|
||||
```
|
||||
|
||||
:::tip
|
||||
This step pulls down quite a bit of tooling, be patient!
|
||||
:::
|
||||
|
||||
3. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
|
||||
|
||||
```sh
|
||||
west zephyr-export
|
||||
```
|
||||
|
||||
<Tabs groupId="operating-systems" defaultValue="ubuntu" className="secrettabs">
|
||||
<TabItem value="ubuntu" label="Ubuntu">
|
||||
|
||||
4. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
|
||||
|
||||
```sh
|
||||
pip3 install --user -r zephyr/scripts/requirements-base.txt
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="win" label="Windows">
|
||||
|
||||
4. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
|
||||
|
||||
```sh
|
||||
pip install -r zephyr/scripts/requirements-base.txt
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="mac" label="Mac OS">
|
||||
4. Install the additional dependencies found in Zephyr's `requirements-base.txt`.
|
||||
|
||||
```sh
|
||||
pip3 install -r zephyr/scripts/requirements-base.txt
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
</TabItem>
|
||||
</EnvTabs>
|
||||
|
||||
## 4. Install Zephyr SDK
|
||||
|
||||
Return to Zephyr's Getting Started Guide and [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk).
|
||||
|
||||
### OS specific notes
|
||||
|
||||
<OsNoteTabs>
|
||||
<TabItem value="win">
|
||||
`dfu-util` is required to flash devices that use DFU, but there is currently
|
||||
no maintained package for it on Chocolatey. [QMK
|
||||
Toolbox](https://github.com/qmk/qmk_toolbox) contains a working version of it
|
||||
though.
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="raspberryos">
|
||||
#### Install Cross-Compile Toolchain
|
||||
|
||||
Because Raspberry OS runs on the same architecture (but different ABI) as ARM keyboard MCUs, the operating system's installed [cross compilers](https://docs.zephyrproject.org/3.5.0/develop/toolchains/other_x_compilers.html) can be used to target the different ABI. Building for non-ARM MCUs has not been tested.
|
||||
|
||||
First, the cross compiler should be installed:
|
||||
|
||||
```sh
|
||||
sudo apt install gcc-arm-none-eabi
|
||||
```
|
||||
|
||||
Next, we'll configure Zephyr with some [environment variables](https://docs.zephyrproject.org/3.5.0/develop/env_vars.html#env-vars) needed to find the cross compiler. Create a file named `~/.zephyrrc` if it doesn't exist, and add these lines to it:
|
||||
|
||||
```sh
|
||||
export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
|
||||
export CROSS_COMPILE=/usr/bin/arm-none-eabi-
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</OsNoteTabs>
|
||||
|
||||
Your setup is now complete.
|
||||
@ -58,7 +58,7 @@ config LED_PWM
|
||||
endif # ZMK_BACKLIGHT
|
||||
```
|
||||
|
||||
Create a `<board>-pinctrl.dtsi` file if it does not already exist, and include it at the beginning of the `<board>.dts` file. `CONFIG_PINCTRL=y` must be added to to `<board>_defconfig` if it isn't already enabled.
|
||||
Create a `<board>-pinctrl.dtsi` file if it does not already exist, and include it at the beginning of the `<board>.dts` file. `CONFIG_PINCTRL=y` must be added to `<board>_defconfig` if it isn't already enabled.
|
||||
|
||||
The pinctrl file has a `&pinctrl` node that encompasses all pinctrl settings, including I2C or SPI peripherals (e.g. WS2812 LEDs, Battery fuel gauges):
|
||||
|
||||
|
||||
@ -34,7 +34,7 @@ macOS 14.x (Sonoma) Finder may report an "Error code -36" when copying `<firmwar
|
||||
### CMake Error
|
||||
|
||||
An error along the lines of `CMake Error at (zmk directory)/zephyr/cmake/generic_toolchain.cmake:64 (include): include could not find load file:` during firmware compilation indicates that the Zephyr Environment Variables are not properly defined.
|
||||
For more information, see [toolchain setup documentation](../docs/development/setup.mdx).
|
||||
For more information, see [Zephyr's CMake Package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html).
|
||||
|
||||
### West Build Errors
|
||||
|
||||
|
||||
@ -31,6 +31,7 @@ module.exports = {
|
||||
"linker-script",
|
||||
"log",
|
||||
"powershell",
|
||||
"diff",
|
||||
],
|
||||
theme,
|
||||
darkTheme,
|
||||
@ -79,7 +80,7 @@ module.exports = {
|
||||
},
|
||||
{
|
||||
label: "Development",
|
||||
to: "docs/development/setup/",
|
||||
to: "docs/development/setup",
|
||||
},
|
||||
],
|
||||
},
|
||||
|
||||
@ -76,7 +76,16 @@ module.exports = {
|
||||
"development/clean-room",
|
||||
"development/pre-commit",
|
||||
"development/documentation",
|
||||
"development/setup",
|
||||
{
|
||||
type: "category",
|
||||
label: "Setup",
|
||||
collapsed: true,
|
||||
items: [
|
||||
"development/setup/index",
|
||||
"development/setup/docker",
|
||||
"development/setup/native",
|
||||
],
|
||||
},
|
||||
"development/build-flash",
|
||||
"development/boards-shields-keymaps",
|
||||
"development/posix-board",
|
||||
|
||||
@ -46,3 +46,7 @@
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
}
|
||||
|
||||
.secrettabs {
|
||||
display: none;
|
||||
}
|
||||
|
||||
@ -308,6 +308,6 @@ if ($github_repo -ne "") {
|
||||
|
||||
if ($github_repo -imatch "https") {
|
||||
$actions = "$($github_repo.substring(0, $github_repo.length - 4))/actions"
|
||||
Write-Host "Your firmware should be availalbe from GitHub Actions shortly: $actions"
|
||||
Write-Host "Your firmware should be available from GitHub Actions shortly: $actions"
|
||||
}
|
||||
}
|
||||
|
||||
@ -297,7 +297,7 @@ if [ -n "$github_repo" ]; then
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# TODO: Support determing the actions URL when non-https:// repo URL is used.
|
||||
# TODO: Support determining the actions URL when non-https:// repo URL is used.
|
||||
if [ "${github_repo}" != "${github_repo#https://}" ]; then
|
||||
echo "Your firmware should be available from GitHub Actions shortly: ${github_repo%.git}/actions"
|
||||
fi
|
||||
|
||||
Loading…
Reference in New Issue
Block a user