Skip to content

Commit

Permalink
Deploying to gh-pages from @ 0115951 🚀
Browse files Browse the repository at this point in the history
  • Loading branch information
tzarc committed Nov 28, 2023
1 parent d50e31e commit 1586402
Show file tree
Hide file tree
Showing 34 changed files with 1,555 additions and 473 deletions.
336 changes: 336 additions & 0 deletions ChangeLog/20231126.md

Large diffs are not rendered by default.

6 changes: 3 additions & 3 deletions _summary.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
* [Building Your First Firmware](newbs_building_firmware.md)
* [Flashing Firmware](newbs_flashing.md)
* [Getting Help/Support](support.md)
* [Building With GitHub Userspace](newbs_building_firmware_workflow.md)
* [External Userspace](newbs_external_userspace.md)
* [Other Resources](newbs_learn_more_resources.md)
* [Syllabus](syllabus.md)

Expand Down Expand Up @@ -126,7 +126,6 @@
* [PS/2 Mouse](feature_ps2_mouse.md)
* [Split Keyboard](feature_split_keyboard.md)
* [Stenography](feature_stenography.md)
* [Velocikey](feature_velocikey.md)

* Keyboard Building
* [Easy Maker for One Offs](easy_maker.md)
Expand All @@ -139,7 +138,7 @@
* Breaking Changes
* [Overview](breaking_changes.md)
* [My Pull Request Was Flagged](breaking_changes_instructions.md)
* [Most Recent ChangeLog](ChangeLog/20230827.md "QMK v0.22.0 - 2023 Aug 27")
* [Most Recent ChangeLog](ChangeLog/20231126.md "QMK v0.23.0 - 2023 Nov 26")
* [Past Breaking Changes](breaking_changes_history.md)

* C Development
Expand All @@ -148,6 +147,7 @@
* [Compatible Microcontrollers](compatible_microcontrollers.md)
* [Drivers](hardware_drivers.md)
* [ADC Driver](adc_driver.md)
* [APA102 Driver](apa102_driver.md)
* [Audio Driver](audio_driver.md)
* [I2C Driver](i2c_driver.md)
* [SPI Driver](spi_driver.md)
Expand Down
2 changes: 1 addition & 1 deletion adc_driver.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ This driver currently supports both AVR and a limited selection of ARM devices.
To use this driver, add the following to your `rules.mk`:

```make
SRC += analog.c
ANALOG_DRIVER_REQUIRED = yes
```

Then place this include at the top of your code:
Expand Down
49 changes: 49 additions & 0 deletions apa102_driver.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# APA102 Driver :id=apa102-driver

This driver provides support for APA102 addressable RGB LEDs. They are similar to the [WS2812](ws2812_driver.md) LEDs, but have increased data and refresh rates.

## Usage :id=usage

In most cases, the APA102 driver code is automatically included if you are using either the [RGBLight](feature_rgblight.md) or [RGB Matrix](feature_rgb_matrix.md) feature with the `apa102` driver set, and you would use those APIs instead.

However, if you need to use the driver standalone, add the following to your `rules.mk`:

```make
APA102_DRIVER_REQUIRED = yes
```

You can then call the APA102 API by including `apa102.h` in your code.

## Basic Configuration :id=basic-configuration

Add the following to your `config.h`:

|Define |Default |Description |
|---------------------------|-------------|------------------------------------------------------------------|
|`APA102_DI_PIN` |*Not defined*|The GPIO pin connected to the DI pin of the first LED in the chain|
|`APA102_CI_PIN` |*Not defined*|The GPIO pin connected to the CI pin of the first LED in the chain|
|`APA102_DEFAULT_BRIGHTNESS`|`31` |The default global brightness level of the LEDs, from 0 to 31 |

## API :id=api

### `void apa102_setleds(rgb_led_t *start_led, uint16_t num_leds)`

Send RGB data to the APA102 LED chain.

#### Arguments :id=api-apa102-setleds-arguments

- `rgb_led_t *start_led`
A pointer to the LED array.
- `uint16_t num_leds`
The length of the LED array.

---

### `void apa102_set_brightness(uint8_t brightness)`

Set the global brightness.

#### Arguments :id=api-apa102-set-brightness-arguments

- `uint8_t brightness`
The brightness level to set, from 0 to 31.
20 changes: 10 additions & 10 deletions breaking_changes.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ Practically, this means QMK merges the `develop` branch into the `master` branch

## What has been included in past Breaking Changes?

* [2023 Nov 26](ChangeLog/20231126.md)
* [2023 Aug 27](ChangeLog/20230827.md)
* [2023 May 28](ChangeLog/20230528.md)
* [2023 Feb 26](ChangeLog/20230226.md)
* [Older Breaking Changes](breaking_changes_history.md)

## When is the next Breaking Change?
Expand All @@ -21,14 +21,14 @@ The next Breaking Change is scheduled for November 26, 2023.

### Important Dates

* 2023 Aug 27 - `develop` is tagged with a new release version. Each push to `master` is subsequently merged to `develop` by GitHub actions.
* 2023 Oct 29 - `develop` closed to new PRs.
* 2023 Oct 29 - Call for testers.
* 2023 Nov 5 - Last day for merges -- after this point `develop` is locked for testing and accepts only bugfixes
* 2023 Nov 19 - `develop` is locked, only critical bugfix PRs merged.
* 2023 Nov 23 - `master` is locked, no PRs merged.
* 2023 Nov 26 - Merge `develop` to `master`.
* 2023 Nov 26 - `master` is unlocked. PRs can be merged again.
* 2023 Nov 26 - `develop` is tagged with a new release version. Each push to `master` is subsequently merged to `develop` by GitHub actions.
* 2024 Jan 28 - `develop` closed to new PRs.
* 2024 Jan 28 - Call for testers.
* 2024 Feb 4 - Last day for merges -- after this point `develop` is locked for testing and accepts only bugfixes
* 2024 Feb 18 - `develop` is locked, only critical bugfix PRs merged.
* 2024 Feb 22 - `master` is locked, no PRs merged.
* 2024 Feb 25 - Merge `develop` to `master`.
* 2024 Feb 25 - `master` is unlocked. PRs can be merged again.

## What changes will be included?

Expand All @@ -48,7 +48,7 @@ Criteria for acceptance:

Strongly suggested:

* The PR has a ChangeLog file describing the changes under `<qmk_firmware>/docs/Changelog/20231126`.
* The PR has a ChangeLog file describing the changes under `<qmk_firmware>/docs/Changelog/20240225`.
* This should be in Markdown format, with a name in the format `PR12345.md`, substituting the digits for your PRs ID.
* One strong recommendation that the ChangeLog document matches the PR description on GitHub, so as to ensure traceability.

Expand Down
1 change: 1 addition & 0 deletions breaking_changes_history.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

This page links to all previous changelogs from the QMK Breaking Changes process.

* [2023 Nov 26](ChangeLog/20231126.md) - version 0.23.0
* [2023 Aug 27](ChangeLog/20230827.md) - version 0.22.0
* [2023 May 28](ChangeLog/20230528.md) - version 0.21.0
* [2023 Feb 26](ChangeLog/20230226.md) - version 0.20.0
Expand Down
125 changes: 125 additions & 0 deletions cli_commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -482,6 +482,131 @@ $ qmk import-kbfirmware ~/Downloads/gh62.json

---

# External Userspace Commands

## `qmk userspace-add`

This command adds a keyboard/keymap to the External Userspace build targets.

**Usage**:

```
qmk userspace-add [-h] [-km KEYMAP] [-kb KEYBOARD] [builds ...]
positional arguments:
builds List of builds in form <keyboard>:<keymap>, or path to a keymap JSON file.
options:
-h, --help show this help message and exit
-km KEYMAP, --keymap KEYMAP
The keymap to build a firmware for. Ignored when a configurator export is supplied.
-kb KEYBOARD, --keyboard KEYBOARD
The keyboard to build a firmware for. Ignored when a configurator export is supplied.
```

**Example**:

```
$ qmk userspace-add -kb planck/rev6 -km default
Ψ Added planck/rev6:default to userspace build targets
Ψ Saved userspace file to /home/you/qmk_userspace/qmk.json
```

## `qmk userspace-remove`

This command removes a keyboard/keymap from the External Userspace build targets.

**Usage**:

```
qmk userspace-remove [-h] [-km KEYMAP] [-kb KEYBOARD] [builds ...]
positional arguments:
builds List of builds in form <keyboard>:<keymap>, or path to a keymap JSON file.
options:
-h, --help show this help message and exit
-km KEYMAP, --keymap KEYMAP
The keymap to build a firmware for. Ignored when a configurator export is supplied.
-kb KEYBOARD, --keyboard KEYBOARD
The keyboard to build a firmware for. Ignored when a configurator export is supplied.
```

**Example**:

```
$ qmk userspace-remove -kb planck/rev6 -km default
Ψ Removed planck/rev6:default from userspace build targets
Ψ Saved userspace file to /home/you/qmk_userspace/qmk.json
```

## `qmk userspace-list`

This command lists the External Userspace build targets.

**Usage**:

```
qmk userspace-list [-h] [-e]
options:
-h, --help show this help message and exit
-e, --expand Expands any use of `all` for either keyboard or keymap.
```

**Example**:

```
$ qmk userspace-list
Ψ Current userspace build targets:
Ψ Keyboard: planck/rev6, keymap: you
Ψ Keyboard: clueboard/66/rev3, keymap: you
```

## `qmk userspace-compile`

This command compiles all the External Userspace build targets.

**Usage**:

```
qmk userspace-compile [-h] [-e ENV] [-n] [-c] [-j PARALLEL] [-t]
options:
-h, --help show this help message and exit
-e ENV, --env ENV Set a variable to be passed to make. May be passed multiple times.
-n, --dry-run Don't actually build, just show the commands to be run.
-c, --clean Remove object files before compiling.
-j PARALLEL, --parallel PARALLEL
Set the number of parallel make jobs; 0 means unlimited.
-t, --no-temp Remove temporary files during build.
```

**Example**:

```
$ qmk userspace-compile
Ψ Preparing target list...
Build planck/rev6:you [OK]
Build clueboard/66/rev3:you [OK]
```

## `qmk userspace-doctor`

This command examines your environment and alerts you to potential problems related to External Userspace.

**Example**:

```
% qmk userspace-doctor
Ψ QMK home: /home/you/qmk_userspace/qmk_firmware
Ψ Testing userspace candidate: /home/you/qmk_userspace -- Valid `qmk.json`
Ψ QMK userspace: /home/you/qmk_userspace
Ψ Userspace enabled: True
```

---

# Developer Commands

## `qmk format-text`
Expand Down
59 changes: 59 additions & 0 deletions custom_quantum_functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -283,6 +283,65 @@ void suspend_wakeup_init_user(void) {
* Keyboard/Revision: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)`
* Keymap: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)`
# Keyboard Shutdown/Reboot Code :id=keyboard-shutdown-reboot-code
This function gets called whenever the firmware is reset, whether it's a soft reset or reset to the bootloader. This is the spot to use for any sort of cleanup, as this happens right before the actual reset. And it can be useful for turning off different systems (such as RGB, onboard screens, etc).
Additionally, it differentiates between the soft reset (eg, rebooting back into the firmware) or jumping to the bootloader.
Certain tasks are performed during shutdown too. The keyboard is cleared, music and midi is stopped (if enabled), the shutdown chime is triggered (if audio is enabled), and haptic is stopped.
If `jump_to_bootloader` is set to `true`, this indicates that the board will be entering the bootloader for a new firmware flash, whereas `false` indicates that this is happening for a soft reset and will load the firmware agaim immediately (such as when using `QK_REBOOT` or `QK_CLEAR_EEPROM`).
As there is a keyboard and user level function, returning `false` for the user function will disable the keyboard level function, allowing for customization.
?> Bootmagic does not trigger `shutdown_*()` as it happens before most of the initialization process.
### Example `shutdown_kb()` Implementation
```c
bool shutdown_kb(bool jump_to_bootloader) {
if (!shutdown_user(jump_to_bootloader)) {
return false;
}
if (jump_to_bootloader) {
// red for bootloader
rgb_matrix_set_color_all(RGB_OFF);
} else {
// off for soft reset
rgb_matrix_set_color_all(RGB_GREEN);
}
// force flushing -- otherwise will never happen
rgb_matrix_update_pwm_buffers();
return true;
}
```

### Example `shutdown_user()` Implementation

```c
bool shutdown_user(bool jump_to_bootloader) {
if (jump_to_bootloader) {
// red for bootloader
rgb_matrix_set_color_all(RGB_RED);
} else {
// off for soft reset
rgb_matrix_set_color_all(RGB_OFF);
}
// force flushing -- otherwise will never happen
rgb_matrix_update_pwm_buffers();
// false to not process kb level
return false;
}
```
### Keyboard shutdown/reboot Function Documentation
* Keyboard/Revision: `bool shutdown_kb(bool jump_to_bootloader)`
* Keymap: `bool shutdown_user(bool jump_to_bootloader)`
# Deferred Execution :id=deferred-execution
QMK has the ability to execute a callback after a specified period of time, rather than having to manually manage timers. To enable this functionality, set `DEFERRED_EXEC_ENABLE = yes` in rules.mk.
Expand Down
20 changes: 14 additions & 6 deletions eeprom_driver.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,14 @@ Currently QMK supports 25xx-series chips over SPI. As such, requires a working s
`#define EXTERNAL_EEPROM_PAGE_SIZE` | `32` | Page size of the EEPROM in bytes, as specified in the datasheet
`#define EXTERNAL_EEPROM_ADDRESS_SIZE` | `2` | The number of bytes to transmit for the memory location within the EEPROM

Default values and extended descriptions can be found in `drivers/eeprom/eeprom_spi.h`.

Alternatively, there are pre-defined hardware configurations for available chips/modules:

Module | Equivalent `#define` | Source
-----------------|---------------------------------|------------------------------------------
MB85RS64V FRAM | `define EEPROM_SPI_MB85RS64V` | <https://www.adafruit.com/product/1897>

!> There's no way to determine if there is an SPI EEPROM actually responding. Generally, this will result in reads of nothing but zero.

## Transient Driver configuration :id=transient-eeprom-driver-configuration
Expand Down Expand Up @@ -105,11 +113,11 @@ Configurable options in your keyboard's `config.h`:

`config.h` override | Default | Description
-----------------------------------------|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`#define WEAR_LEVELING_EFL_FIRST_SECTOR` | _unset_ | The first sector on the MCU to use. By default this is not defined and calculated at runtime based on the MCU. However, different flash sizes on MCUs may require custom configuration.
`#define WEAR_LEVELING_EFL_FLASH_SIZE` | _unset_ | Allows overriding the flash size available for use for wear-leveling. Under normal circumstances this is automatically calculated and should not need to be overridden. Specifying a size larger than the amount actually available in flash will usually prevent the MCU from booting.
`#define WEAR_LEVELING_LOGICAL_SIZE` | `1024` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM.
`#define WEAR_LEVELING_BACKING_SIZE` | `2048` | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size.
`#define BACKING_STORE_WRITE_SIZE` | _automatic_ | The byte width of the underlying write used on the MCU, and is usually automatically determined from the selected MCU family. If an error occurs in the auto-detection, you'll need to consult the MCU's datasheet and determine this value, specifying it directly.
`#define WEAR_LEVELING_EFL_FIRST_SECTOR` | _unset_ | The first sector on the MCU to use. By default this is not defined and calculated at runtime based on the MCU. However, different flash sizes on MCUs may require custom configuration.
`#define WEAR_LEVELING_EFL_FLASH_SIZE` | _unset_ | Allows overriding the flash size available for use for wear-leveling. Under normal circumstances this is automatically calculated and should not need to be overridden. Specifying a size larger than the amount actually available in flash will usually prevent the MCU from booting.
`#define WEAR_LEVELING_LOGICAL_SIZE` | `(backing_size/2)` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM.
`#define WEAR_LEVELING_BACKING_SIZE` | `2048` | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size.
`#define BACKING_STORE_WRITE_SIZE` | _automatic_ | The byte width of the underlying write used on the MCU, and is usually automatically determined from the selected MCU family. If an error occurs in the auto-detection, you'll need to consult the MCU's datasheet and determine this value, specifying it directly.

!> If your MCU does not boot after swapping to the EFL wear-leveling driver, it's likely that the flash size is incorrectly detected, usually as an MCU with larger flash and may require overriding.

Expand Down Expand Up @@ -139,7 +147,7 @@ Configurable options in your keyboard's `config.h`:
------------------------------------------|----------------------------|--------------------------------------------------------------------------------------------------------------------------------
`#define WEAR_LEVELING_RP2040_FLASH_SIZE` | `PICO_FLASH_SIZE_BYTES` | Number of bytes of flash on the board.
`#define WEAR_LEVELING_RP2040_FLASH_BASE` | `(flash_size-sector_size)` | The byte-wise location that the backing storage should be located.
`#define WEAR_LEVELING_LOGICAL_SIZE` | `4096` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM.
`#define WEAR_LEVELING_LOGICAL_SIZE` | `(backing_size/2)` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM.
`#define WEAR_LEVELING_BACKING_SIZE` | `8192` | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size as well as the sector size.
`#define BACKING_STORE_WRITE_SIZE` | `2` | The write width used whenever a write is performed on the external flash peripheral.

Expand Down
Loading

0 comments on commit 1586402

Please sign in to comment.