From b9b4eb5533389dd55cc0a36c43f1188fbe7e2b39 Mon Sep 17 00:00:00 2001 From: Charly Delay Date: Tue, 17 Oct 2023 21:20:02 +0900 Subject: [PATCH] Migrate pages from bastardkb/technical-docs --- _config.yml | 3 +- fw/charybdis-keymap.md | 115 +++++++++++++++++++++++++++++++++++++++++ fw/index.md | 7 +++ hw/index.md | 7 +++ hw/rp2040-community.md | 37 +++++++++++++ index.md | 2 + 6 files changed, 170 insertions(+), 1 deletion(-) create mode 100644 fw/charybdis-keymap.md create mode 100644 fw/index.md create mode 100644 hw/index.md create mode 100644 hw/rp2040-community.md diff --git a/_config.yml b/_config.yml index 7e92662..991b42e 100644 --- a/_config.yml +++ b/_config.yml @@ -1 +1,2 @@ -remote_theme: pmarsceill/just-the-docs \ No newline at end of file +markdown: kramdown +remote_theme: pmarsceill/just-the-docs diff --git a/fw/charybdis-keymap.md b/fw/charybdis-keymap.md new file mode 100644 index 0000000..c55d800 --- /dev/null +++ b/fw/charybdis-keymap.md @@ -0,0 +1,115 @@ +All the features listed below are available in the Charybdis stock keymaps (built from the `via` keymap source). + +The stock keymap aims at providing a consistent experience out of the box. Because some features can be mutually exclusives (e.g. [Auto sniping on layer](#auto-sniping-on-layer) and [Auto pointer layer](#auto-pointer-layer)), not all features are enabled by default. It may be necessary to rebuild the firmware to enable or disable some of the features listed below. + +# Charybdis features + +## Charybdis stock keymap + +The stock keymap is built off the `via` keymap: + +- [Charybdis (4x6) `via` keymap](https://github.com/Bastardkb/bastardkb-qmk/tree/bkb-master/keyboards/bastardkb/charybdis/4x6/keymaps/via#layout) +- [Charybdis Nano (3x5) `via` keymap](https://github.com/Bastardkb/bastardkb-qmk/tree/bkb-master/keyboards/bastardkb/charybdis/3x5/keymaps/via#layout) + +A visual reference layout is provided for each of these keymap at the links above. + +Those stock keymaps are compatible with [Via](https://www.caniusevia.com/) which enables on-the-fly configuration to a certain extent (i.e. keycodes, rotary encoders, RGB animations can be configured in just a few clicks from the UI). Some more advanced features, however, require manually updating the firmware. + +### Trackball related features + +There's 2 features that are related to pointing devices available in the Charybdis firmware: + +- **Sniping**: temporarily reduces the sensitivity of the pointer for a more precise control. +- **Drag-scroll**: temporarily changes the behavior of the trackball into a scrolling device (in any direction). + +### DPI + +DPI (i.e. dots per linear inch), a.k.a. mouse sensitivity, can be controlled by the firmware. The Charybdis keymap offers 2 different DPI settings: + +- **Default** DPI: the sensitivity of the pointer in normal (i.e. non-sniping) mode. +- **Sniping** DPI: the sensitivity of the pointer in sniping mode. + +For each mode, the firmware allows cycling through multiple pre-defined values: + +- Default mode: + - Default value: 400 DPI + - 16 steps available + - Increments of 200 DPI + - Total range from 400 to 3,400 (400 → 600 → 800 → … → 3,400) +- Sniping mode: + - Default value: 200 DPI + - 4 steps available + - Increments of 100 DPI + - Total range from 200 to 500 (200 → 300 → 400 → 500) + +The firmware _cycles_ through these values, which means that, for example, incrementing the sniping DPI of `500` by 1 step will loop back to `200`. + +These values can be changed by manually editing the firmware. See [Dynamic DPI scaling](#changing-dynamic-dpi-scaling-default-and-increment-values]. + +### Custom keycodes + +The Charybdis firmware comes with a number of custom keycodes related to features that are specific to this keyboard. These keycodes are: + +- Default DPI Increase (`DPI+`): increase the sensitivity of the pointer movement by one step (out of 16). +- Default DPI Decrease (`DPI-`): decrease the sensitivity of the pointer movement by one step (out of 16). +- Sniping DPI Increase (`Snp+`): increase the sensitivity of the pointer movement in sniping mode by one step (out of 4). +- Sniping DPI Decrease (`Snp-`): decrease the sensitivity of the pointer movement in sniping mode by one step (out of 4). +- Sniping Momentary (`Snp`): enable sniping mode as long as the key is pressed. +- Sniping Toggle (`SnpT`): toggle sniping mode on and off. +- Drag-scroll Momentary (`Drg`): enable drag-scroll mode as long as the key is pressed. +- Drag-scroll Toggle (`DrgT`): toggle drag-scroll mode on and off. + +### Charybdis 4x6 + +- 3x5: heavily inspired by Miryoku + - Base layer + - Numbers layer + - Symbols layer + - Function layer + - Navigation layer + - Media layer + - Pointer layer +- 4x6: inspired from OG dactyl + - Base layer + - Lower layer + - Raise layer + - Pointer layer + +## Firmware configuration + +> **Note**
+> This requires a firmware update. + +The following section explains how to update the firmware source code to fine-tune your experience. This requires a functional development environment for QMK (https://docs.qmk.fm/#/newbs) and, ideally, some prior experience in computer science and the C programming language. + +### Changing dynamic DPI scaling default and increment values + +> **Note**
+> This requires a firmware update. + +### Auto sniping on layer + +> **Note**
+> This requires a firmware update. + +### Auto pointer layer + +> **Note**
+> This requires a firmware update. + +### X/Y axis inversion + +> **Note**
+> This requires a firmware update. + +### Extended mouse reports + +> **Note**
+> This requires a firmware update. + +By default, QMK reports the pointing device movement using numbers between `-127` and `128`. + +### Configuration sync between each half + +> **Note**
+> This requires a firmware update. diff --git a/fw/index.md b/fw/index.md new file mode 100644 index 0000000..04e894f --- /dev/null +++ b/fw/index.md @@ -0,0 +1,7 @@ +--- +layout: default +title: Getting Started +nav_order: 1 +--- + +* TOC {:toc} diff --git a/hw/index.md b/hw/index.md new file mode 100644 index 0000000..04e894f --- /dev/null +++ b/hw/index.md @@ -0,0 +1,7 @@ +--- +layout: default +title: Getting Started +nav_order: 1 +--- + +* TOC {:toc} diff --git a/hw/rp2040-community.md b/hw/rp2040-community.md new file mode 100644 index 0000000..80f8331 --- /dev/null +++ b/hw/rp2040-community.md @@ -0,0 +1,37 @@ +## BKB standard + +The "BKB standard" is a standard pinout that was defined by a committee of designers on the BastardKB Discord server when the first RP2040 were created in 2022. + +![BKB standard pinout, on the Sea-picro](https://github.com/joshajohnson/sea-picro/raw/master/documentation/pinout/sea-picro-top-pinout-rory-render.png) + +These boards are designed to be a drop-in replacement for keyboards wanting an upgrade from ATmega32u4 based pro micros (_eg._ Elite-C). + +They are using the [RP2040 microcontroller chip](https://www.raspberrypi.com/products/rp2040/) designed by [Raspberry Pi](https://www.raspberrypi.com/), which features dual M0+ processors at up to 133MHz + +## Pinout compatibility + +Controller | Pin-compatible | Flash size | Vbus detection | Notes +---------- | -------------- | ---------- | -------------- | ----- +[0xB2 Splinky](https://github.com/plut0nium/0xB2/) | Yes | _varies_ (up to 16MB) | Yes | Included in [Bastard Keyboards](https://bastardkb.com) kits +[Elite-Pi](https://docs.keeb.io/elite-pi-guide) | Yes | 2MB | Yes | Optionally, 2 extra GPIO pins can be exposed by setting jumpers on the Elite-Pi for a total of 25 GPIO. +[Sea-Picro EXT](https://github.com/joshajohnson/sea-picro) | Yes | 8MB | Yes | [One-button Reset / Bootloader circuit](https://github.com/joshajohnson/sea-picro#one-button-reset--bootloader-circuit).
Has an extra 5V level-shifted pin (GPIO 25) broken out. +[Frood](https://github.com/piit79/Frood) | Yes | 2MB | Yes | +[0xCB Helios](https://github.com/0xCB-dev/0xCB-Helios) | Yes | 16MB | Yes | Has a One-button Reset / Bootloader circuit, and ESD protection.
Available at [Keeb Supply](https://keeb.supply/products/0xcb-helios).
Has an extra 5V level-shifted pin (GPIO 25) broken out. +[Liatris](https://splitkb.com/products/liatris) | Yes | 16MB | Yes | Available at [splitkb.com](https://splitkb.com/collections/featured-products/products/liatris). +[SparkFun Pro Micro - RP2040](https://www.sparkfun.com/products/18288) | No* | 16MB | No | Pinout matches, but no bottom row.
The reset buttons collide with pin headers when installed face-down.
USB-C receptacle is top-mounted. +[Adafruit KB2040 - RP2040 Kee Boar Driver](https://www.adafruit.com/product/5302) | No | 8MB | No | Different pinout, no bottom row.
USB-C receptacle is top-mounted. | +[Blok](https://peg.software/docs/blok) | No | 16MB | Unspecified | Different i2c pins, no bottom row. | + +## Firmware compatibility + +All controllers above marked as pin-compatible, and using the QMK default `W25Q080` second-stage bootloader, should be compatible out-of-the-box with the [Bastard Keyboard firmwares](https://github.com/bastardkb/bastardkb-qmk/releases) targeting the Splinky v3, _ie._ `splinky_3` firmwares. + +### Bootloader + +See [QMK's RP2040 second stage bootloader selection](https://qmk.github.io/qmk_docs_devel/#/platformdev_rp2040?id=rp2040-second-stage-bootloader-selection) documentation. + +## USB-C port compatibility + +For the USB-C port to align perfectly in the Bastard Keyboard cases, the controller needs to use a USB-C connector of specific dimensions, otherwise it might be slightly offset on the Z axis. + +The Splinky controller sold as part of the Bastard Keyboard kits are using a compatible port. If you are sourcing your own controller, make sure that the USB-C port dimensions are correct. diff --git a/index.md b/index.md index 4a1dd5a..04e894f 100644 --- a/index.md +++ b/index.md @@ -3,3 +3,5 @@ layout: default title: Getting Started nav_order: 1 --- + +* TOC {:toc}