From fcdbcf80bb57dedd4c463cc05d3322c5d3b90b98 Mon Sep 17 00:00:00 2001 From: Daniel Schaefer Date: Sun, 19 Oct 2025 16:10:01 +0800 Subject: [PATCH 1/6] WIP: Document locked design Signed-off-by: Daniel Schaefer --- README.md | 37 ++++++++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index cc98e70..ed6bcf0 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # Framework Laptop 16 Input Modules ![InputModules](https://user-images.githubusercontent.com/28994301/226249081-ab193cfe-4da4-4c47-93ec-c6024edf4fbc.png) -This repository includes mechanical and electrical documentation for the Input Module system in the +This repository includes mechanical and electrical documentation for the Input Module system in the Framework Laptop 16. Input Modules are hot-swappable USB 2.0-interfaced devices that enable deep -customization of the input system on the Framework Laptop 16. It's also possible to use these as +customization of the input system on the Framework Laptop 16. It's also possible to use these as standalone USB 2.0 devices with a simple adapter for development purposes. Input Modules come in three sizes, each of which has the same electrical interface: @@ -11,9 +11,10 @@ Input Modules come in three sizes, each of which has the same electrical interfa 2. Numpad-sized modules (67.85mm wide) 3. Half-sized modules (33.825mm wide) -**Warning:** the documentation here is pretty early, so there may be minor adjustments in the mechanical or electrical designs -before the Framework Laptop 16 launches. We'll let you know when the design is locked for production. - +For reference firmware for different types of modules, check out these additional repositories: + * [QMK firmware](https://github.com/frameworkcomputer/qmk_firmware) for the keyboard and numpad modules + * [inputmodule-rs](https://github.com/FrameworkComputer/inputmodule-rs) firmware and application for other input modules + ## License Input Modules © 2023 by Framework Computer Inc is licensed under CC BY 4.0. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/ @@ -47,7 +48,7 @@ In the Mechanical folder, we have 2D drawings of the different Input Module size 1. A version with full mechanical structure with a separate interface PCB and brackets. This is what our production modules are based on. 2. A simplified version that allows the PCB to be used as the mechanical structure of the module, making it much cheaper and easier to make. Note that to make the PCB attach securely in the system, you'll need to solder SMT nuts like Keystone 24929 or to adhere a steel plate to attract to - the magnets in the system. + the magnets in the system. ## Electrical @@ -95,16 +96,30 @@ Viewed from top: Each Input Module supports up to 500mA on the 5V rail and 100mA on the 3.3V rail when active. +The Framework Laptop 16 has a protection scheme in place to prevent Input Modules from powering on unless the input deck is fully populated. +Module detection is done using the `BOARD_ID` pin. It is possible to override this setting on the system through BIOS settings, but at the risk of shorting the system or modules. + +#### `SLEEP#` pin behavior + +| Platform | BIOS | `SLEEP#` | +|-----------------------|------|-----------------| +| AMD Ryzen 7040 Series | 3.XX | Lid and Suspend | +| AMD Ryzen 7040 Series | 4.XX | Lid state | +| AMD AI 300 Series | Any | Lid state | + +On the first generation Framework 16 with BIOS 3.XX the `SLEEP#` pin is low +whenever the system is in S0ix (suspend) state or the lid is closed. + +On the 2nd gen or 1st gen with BIOS 4.XX the `SLEEP#` pin is only low if the lid is closed. +This change was made because the keyboard and touchpad firmware couldn't decide between + When SLEEP# is low or USB is in Selective Suspend mode, modules should drop below 500uA on each rail. This will typically occur when the system enters an S0ix state. In S3/S4/S5 or when the laptop lid is closed, the power rails will typically be off. -The Framework Laptop 16 has a protection scheme in place to prevent Input Modules from powering on unless the input deck is fully populated. -Module detection is done using the BOARD_ID pin. It is possible to override this setting on the system, but at the risk of shorting the system -or modules. - ## Touchpad Module This section describes the Touchpad Module connection on the **system** side, including the pin define and the pin map of the connector. +There are three connectors for the touchpad, to allow moving it around. They are all shorted together on the same I2C bus with the same interrupt lines. Pins on the connector have ESD protection to meet IEC 61000-4-2 Level 4 protection. @@ -124,7 +139,7 @@ Pins on the connector have ESD protection to meet IEC 61000-4-2 Level 4 protecti ### Touchpad Module layout requirements The contacts on the Touchpad should be designed so that the ground pins engage first when the Touchpad is sliding in. -Pin 7 should be 0.5mm longer than the other pins to ensure it engages first. +Pin 7 should be 0.5mm longer than the other pins to ensure it engages first. The below picture for pads is shown in perspective. The view angle is on top of the PCB. From 4cf873fb872beb7da406501e8b3ac92c54824d12 Mon Sep 17 00:00:00 2001 From: Daniel Schaefer Date: Mon, 29 Dec 2025 21:22:52 +0800 Subject: [PATCH 2/6] Document for ways to run alternative firmware For experimenting :D Signed-off-by: Daniel Schaefer --- README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/README.md b/README.md index ed6bcf0..c16de75 100644 --- a/README.md +++ b/README.md @@ -28,11 +28,22 @@ Find the latest binary releases and source code in our [FrameworkComputer/qmk_fi To configure keybindings, use our hosted VIA fork, which has the right configurations built in at https://keyboard.frame.work. Or the [qmk_hid](https://github.com/FrameworkComputer/qmk_hid) native Python or Rust software GUI and console applications. +HALs for RTOS or baremetal environments: + +- [rust-embedded](https://github.com/rp-rs/rp-hal-boards/tree/main/boards/framework16-keyboard) + - [capslock Sample](https://github.com/rp-rs/rp-hal-boards/blob/main/boards/framework16-keyboard/examples/capslock.rs) + - [white_backlight Sample](https://github.com/rp-rs/rp-hal-boards/blob/main/boards/framework16-keyboard/examples/white_backlight.rs) + ### LED Matrix Official firmware that ships with the modules is available in source and binary at [FrameworkComputer/inputmodule-rs](https://github.com/FrameworkComputer/inputmodule-rs). That same repository also contains a Rust commandline utility and Python scripts to control the matrix. +HALs for RTOS or baremetal environments: + +- [rust-embedded](https://github.com/rp-rs/rp-hal-boards/tree/main/boards/framework-ledmatrix) + - [ledtest Sample](https://github.com/rp-rs/rp-hal-boards/blob/main/boards/framework-ledmatrix/examples/ledtest.rs) + Third party applications that interact with the official firmware: - [https://github.com/jpadgett314/led-matrix-vocab](jpadgett314/led-matrix-vocab) - A japanese vocab trainer @@ -42,6 +53,19 @@ Third party firmware projects that run on the official hardware: - [https://github.com/sigroot/FW_LED_Matrix_Firmware](sigroot/FW_LED_Matrix_Firmware) - Arduino based firmware with an alternative host protocol - [https://github.com/vddCore/sparkle-fw16](vddCore/sparkle-fw16) - Pico SDK based firmware with an alternative host protocol +### CircuitPython + +CircuitPython can run on all modules. + +Sample Code: + +- [github.com/FrameworkComputer/Framework_Inputmodule_CircuitPython](https://github.com/FrameworkComputer/Framework_Inputmodule_CircuitPython) + +Libraries: + +- [Keyboard RGB Controller Adafruit_CircuitPython_IS31FL3741](https://github.com/adafruit/Adafruit_CircuitPython_IS31FL3741) +- [Keyboard RGB Controller - Framework CircuitPython_IS31FL3743](https://github.com/FrameworkComputer/CircuitPython_IS31FL3743) + ## Mechanical In the Mechanical folder, we have 2D drawings of the different Input Module sizes. Note that there are two version of each: From 41939236cd77a138a3ff996ab3fc67123c6c17fa Mon Sep 17 00:00:00 2001 From: Daniel Schaefer Date: Mon, 5 Jan 2026 10:29:23 +0800 Subject: [PATCH 3/6] README: Mention LED matrix drivers Signed-off-by: Daniel Schaefer --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index c16de75..3d125d6 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,12 @@ HALs for RTOS or baremetal environments: - [capslock Sample](https://github.com/rp-rs/rp-hal-boards/blob/main/boards/framework16-keyboard/examples/capslock.rs) - [white_backlight Sample](https://github.com/rp-rs/rp-hal-boards/blob/main/boards/framework16-keyboard/examples/white_backlight.rs) +IS31FL3743 LED Controller Drivers: + +- [QMK](https://docs.qmk.fm/drivers/is31fl3743a) +- [rust-embedded](https://docs.rs/is31fl3743a/latest/is31fl3743a/) +- [CircuitPython](https://github.com/FrameworkComputer/CircuitPython_IS31FL3743) + ### LED Matrix Official firmware that ships with the modules is available in source and binary at [FrameworkComputer/inputmodule-rs](https://github.com/FrameworkComputer/inputmodule-rs). @@ -44,6 +50,12 @@ HALs for RTOS or baremetal environments: - [rust-embedded](https://github.com/rp-rs/rp-hal-boards/tree/main/boards/framework-ledmatrix) - [ledtest Sample](https://github.com/rp-rs/rp-hal-boards/blob/main/boards/framework-ledmatrix/examples/ledtest.rs) +IS31FL3741 LED Controller Drivers: + +- [QMK](https://docs.qmk.fm/drivers/is31fl3741) +- [rust-embedded](https://docs.rs/is31fl3741/latest/is31fl3741) +- [CircuitPython](https://github.com/adafruit/Adafruit_CircuitPython_IS31FL3741) + Third party applications that interact with the official firmware: - [https://github.com/jpadgett314/led-matrix-vocab](jpadgett314/led-matrix-vocab) - A japanese vocab trainer From 6277e02d67ecbbd4c8d6522e8f93da610e0cc6a6 Mon Sep 17 00:00:00 2001 From: Daniel Schaefer Date: Mon, 5 Jan 2026 10:32:10 +0800 Subject: [PATCH 4/6] Keyboard: Update QMK branch references with latest release The release tag is less likely to disappear than the branch. Also we have moved onto a different branch name. Signed-off-by: Daniel Schaefer --- Electrical/Keyboard/README.md | 36 +++++++++++++---------------------- 1 file changed, 13 insertions(+), 23 deletions(-) diff --git a/Electrical/Keyboard/README.md b/Electrical/Keyboard/README.md index c61bc52..d635e1c 100644 --- a/Electrical/Keyboard/README.md +++ b/Electrical/Keyboard/README.md @@ -59,16 +59,6 @@ I2C Addresses: - RGB Keyboard: 0x20 and 0x23 - Macropad: 0x20 -Below is the table describing how the LEDs are placed on the matrix -and how they are wired up to the LED controller. - -- X is the X location in the matrix (from left to right) -- Y is the Y location in the matrix (from bottom to top) -- ID is the numerical identifier of the LED -- I2C is the address of the controller, either 0x20 or 0x23 -- Address and Page describe the memory location in the IS31FL3743A's registers -- SW and CS are the pins - Please refer to the controller's datasheet for additional information about how to program it. @@ -76,31 +66,31 @@ program it. Please refer to the reference code: -- [LED Mapping](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/ansi/ansi.c) +- [LED Mapping](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/ansi/ansi.c) ###### Macropad Keyboard -- [LED Mapping](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/macropad/macropad.c) +- [LED Mapping](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/macropad/macropad.c) ### Keyboard Matrix Please refer to the reference code: - ANSI - - [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/ansi/info.json) - - [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/ansi/keymaps/default/keymap.c) + - [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/ansi/ansi.h) + - [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/ansi/keymaps/default/keymap.c) - ISO - - [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/iso/info.json) - - [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/iso/keymaps/default/keymap.c) + - [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/iso/iso.h) + - [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/iso/keymaps/default/keymap.c) - JIS - - [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/jis/info.json) - - [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/jis/keymaps/default/keymap.c) + - [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/jis/jis.h) + - [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/jis/keymaps/default/keymap.c) - Numpad - - [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/numpad/info.json) - - [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/numpad/keymaps/default/keymap.c) + - [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/numpad/numpad.h) + - [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/numpad/keymaps/default/keymap.c) - Macropad - - [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/macropad/info.json) - - [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/macropad/keymaps/default/keymap.c) + - [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/macropad/macropad.h) + - [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/macropad/keymaps/default/keymap.c) ## License -Input Modules © 2023 by Framework Computer Inc is licensed under CC BY 4.0. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/ +Input Modules © 2023-2026 by Framework Computer Inc is licensed under CC BY 4.0. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/ From 575225bfcbd2c1cdf5996736a8f7aa7b5fb66861 Mon Sep 17 00:00:00 2001 From: Daniel Schaefer Date: Mon, 5 Jan 2026 10:52:00 +0800 Subject: [PATCH 5/6] Document assumption that board ID is on the left of module Signed-off-by: Daniel Schaefer --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 3d125d6..d06f934 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ For reference firmware for different types of modules, check out these additiona * [inputmodule-rs](https://github.com/FrameworkComputer/inputmodule-rs) firmware and application for other input modules ## License -Input Modules © 2023 by Framework Computer Inc is licensed under CC BY 4.0. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/ +Input Modules © 2023-2026 by Framework Computer Inc is licensed under CC BY 4.0. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/ ## Firmware and Software @@ -135,6 +135,11 @@ Each Input Module supports up to 500mA on the 5V rail and 100mA on the 3.3V rail The Framework Laptop 16 has a protection scheme in place to prevent Input Modules from powering on unless the input deck is fully populated. Module detection is done using the `BOARD_ID` pin. It is possible to override this setting on the system through BIOS settings, but at the risk of shorting the system or modules. +System firmware expects that pogo connector where the module presents the board +ID, is at the very left of the module. It uses this assumption to calculate +size and position of modules and detect if the input deck is fully populated +and all pogo pins are covered. + #### `SLEEP#` pin behavior | Platform | BIOS | `SLEEP#` | From 9ce275a255ad5f27538743ed6f1eb77e6051bf12 Mon Sep 17 00:00:00 2001 From: Daniel Schaefer Date: Mon, 12 Jan 2026 00:46:09 +0800 Subject: [PATCH 6/6] Keyboard: Directly document led positions Signed-off-by: Daniel Schaefer --- Electrical/Keyboard/README.md | 53 ++++++++++++++++++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/Electrical/Keyboard/README.md b/Electrical/Keyboard/README.md index d635e1c..a66af6a 100644 --- a/Electrical/Keyboard/README.md +++ b/Electrical/Keyboard/README.md @@ -68,10 +68,61 @@ Please refer to the reference code: - [LED Mapping](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/ansi/ansi.c) -###### Macropad Keyboard +Connected pins on both ICs: + +- SW1-SW9 +- SW01-SW18 + +LEDs are arrange like this (Left Address 0x20, Right Address 0x23) + +┌─────┬───┬───┬───┬───┬───┬───┬───┬ ┬───┬───┬───┬────┬───┬─────┐ +│43 31│20 │ 8 │ 2 │14 │26 │37 │49 │ │ 8 │14 │20 │2 38│32 │445 0│ +├───┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬ ┴─┬─┴─┬─┴─┬─┴─┬──┴┬──┴─────┤ +│42 │30 │19 │ 7 │ 1 │13 │25 │36 │48 │ │26 │25 │37 │31 │43 49 │ +├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴ ┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬──────┤ +│41 29│18 │ 6 │ 0 │12 │24 │35 │47 │ │ 7 │13 │19 │ 1 │36 │ 42 │ +├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴ ┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴──────┤ +│334522│10 │ 4 │16 │28 │39 │51 │ │ 6 │12 │18 │ 0 │24 │ 30 48 │ +├──────┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴ ┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─────────┤ +│32 21 9 │ 3 │15 │27 │38 │50 │ │ 9 │15 │21 │ 3 │27 │33 45 51 52│ +├────┬───┼───┼───┼───┴───┴───┴ ┬───┼ ┼───┴───┴───┴───┴───┼───┼───┼───┴┬───┬──────┤ +│ │ │ │ │ │ │ │ │ │ │ │39 │ │ +│44 5│ │11 │17 │ │ 5 │ │11 17 23 10 16 22│ 4 │28 │ 34 ├───┤ 46 │ +│ │ │ │ │ │ │ │ │ │ │ │40 │ │ +└────┴ ┴───┴───┴─ ┴───┴───┴───┴───────────────────┴───┴───┴────┴───┴──────┘ + +Most keys have one, large keys have multiple RGB LEDs. +LED 0 is controlled by registers 0, 1, 2. LED 1 by 3, 4, 5 and so on. +LED colors are arranged in the order: Blue, Green, Red. + +###### Macropad - [LED Mapping](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/macropad/macropad.c) +Connected pins: + +- SW1-SW4 +- CS01-CS18 + +LEDs are arranged like this: + +┌──┬──┬──┬──┐ +│13│12│17│16│ +├──┼──┼──┼──┤ +│ 1│ 0│ 5│ 4│ +├──┼──┼──┼──┤ +│ 7│ 6│11│10│ +├──┼──┼──┼──┤ +│19│18│23│22│ +├──┼──┼──┼──┤ +│ 8│20│21│ 9│ +├──┼──┼──┼──┤ +│ 2│14│15│ 3│ +└──┴──┴──┴──┘ + +Each key has one RGB LED, so LED 0 is controlled by registers 0, 1, 2. LED 1 by 3, 4, 5 and so on. +LED colors are arranged in the order: Blue, Green, Red. + ### Keyboard Matrix Please refer to the reference code: