Skip to content

Commit 8ddcd1a

Browse files
JohnAZoidbergJohnAZoidberg
authored
Merge pull request #25 from FrameworkComputer/mp-doc
Document mass produced design
2 parents 9355f6e + 7e6b49c commit 8ddcd1a

File tree

2 files changed

+135
-36
lines changed

2 files changed

+135
-36
lines changed

‎Electrical/Keyboard/README.md‎

Lines changed: 65 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -59,48 +59,89 @@ I2C Addresses:
5959
- RGB Keyboard: 0x20 and 0x23
6060
- Macropad: 0x20
6161

62-
Below is the table describing how the LEDs are placed on the matrix
63-
and how they are wired up to the LED controller.
64-
65-
- X is the X location in the matrix (from left to right)
66-
- Y is the Y location in the matrix (from bottom to top)
67-
- ID is the numerical identifier of the LED
68-
- I2C is the address of the controller, either 0x20 or 0x23
69-
- Address and Page describe the memory location in the IS31FL3743A's registers
70-
- SW and CS are the pins
71-
7262
Please refer to the controller's datasheet for additional information about how to
7363
program it.
7464

7565
###### RGB Keyboard
7666

7767
Please refer to the reference code:
7868

79-
- [LED Mapping](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/ansi/ansi.c)
69+
- [LED Mapping](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/ansi/ansi.c)
70+
71+
Connected pins on both ICs:
72+
73+
- SW1-SW9
74+
- SW01-SW18
75+
76+
LEDs are arrange like this (Left Address 0x20, Right Address 0x23)
77+
78+
┌─────┬───┬───┬───┬───┬───┬───┬───┬ ┬───┬───┬───┬────┬───┬─────┐
79+
│43 31│20 │ 8 │ 2 │14 │26 │37 │49 │ │ 8 │14 │20 │2 38│32 │445 0│
80+
├───┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬ ┴─┬─┴─┬─┴─┬─┴─┬──┴┬──┴─────┤
81+
│42 │30 │19 │ 7 │ 1 │13 │25 │36 │48 │ │26 │25 │37 │31 │43 49 │
82+
├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴ ┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬──────┤
83+
│41 29│18 │ 6 │ 0 │12 │24 │35 │47 │ │ 7 │13 │19 │ 1 │36 │ 42 │
84+
├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴ ┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴──────┤
85+
│334522│10 │ 4 │16 │28 │39 │51 │ │ 6 │12 │18 │ 0 │24 │ 30 48 │
86+
├──────┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴ ┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─────────┤
87+
│32 21 9 │ 3 │15 │27 │38 │50 │ │ 9 │15 │21 │ 3 │27 │33 45 51 52│
88+
├────┬───┼───┼───┼───┴───┴───┴ ┬───┼ ┼───┴───┴───┴───┴───┼───┼───┼───┴┬───┬──────┤
89+
│ │ │ │ │ │ │ │ │ │ │ │39 │ │
90+
│44 5│ │11 │17 │ │ 5 │ │11 17 23 10 16 22│ 4 │28 │ 34 ├───┤ 46 │
91+
│ │ │ │ │ │ │ │ │ │ │ │40 │ │
92+
└────┴ ┴───┴───┴─ ┴───┴───┴───┴───────────────────┴───┴───┴────┴───┴──────┘
93+
94+
Most keys have one, large keys have multiple RGB LEDs.
95+
LED 0 is controlled by registers 0, 1, 2. LED 1 by 3, 4, 5 and so on.
96+
LED colors are arranged in the order: Blue, Green, Red.
97+
98+
###### Macropad
99+
100+
- [LED Mapping](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/macropad/macropad.c)
101+
102+
Connected pins:
103+
104+
- SW1-SW4
105+
- CS01-CS18
106+
107+
LEDs are arranged like this:
80108

81-
###### Macropad Keyboard
109+
┌──┬──┬──┬──┐
110+
│13│12│17│16│
111+
├──┼──┼──┼──┤
112+
│ 1│ 0│ 5│ 4│
113+
├──┼──┼──┼──┤
114+
│ 7│ 6│11│10│
115+
├──┼──┼──┼──┤
116+
│19│18│23│22│
117+
├──┼──┼──┼──┤
118+
│ 8│20│21│ 9│
119+
├──┼──┼──┼──┤
120+
│ 2│14│15│ 3│
121+
└──┴──┴──┴──┘
82122

83-
- [LED Mapping](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/macropad/macropad.c)
123+
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.
124+
LED colors are arranged in the order: Blue, Green, Red.
84125

85126
### Keyboard Matrix
86127

87128
Please refer to the reference code:
88129

89130
- ANSI
90-
- [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/ansi/info.json)
91-
- [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/ansi/keymaps/default/keymap.c)
131+
- [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/ansi/ansi.h)
132+
- [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/ansi/keymaps/default/keymap.c)
92133
- ISO
93-
- [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/iso/info.json)
94-
- [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/iso/keymaps/default/keymap.c)
134+
- [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/iso/iso.h)
135+
- [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/iso/keymaps/default/keymap.c)
95136
- JIS
96-
- [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/jis/info.json)
97-
- [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/jis/keymaps/default/keymap.c)
137+
- [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/jis/jis.h)
138+
- [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/jis/keymaps/default/keymap.c)
98139
- Numpad
99-
- [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/numpad/info.json)
100-
- [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/numpad/keymaps/default/keymap.c)
140+
- [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/numpad/numpad.h)
141+
- [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/numpad/keymaps/default/keymap.c)
101142
- Macropad
102-
- [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/macropad/info.json)
103-
- [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/lotus/keyboards/framework/laptop16/macropad/keymaps/default/keymap.c)
143+
- [Matrix](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/macropad/macropad.h)
144+
- [Keymap](https://github.com/FrameworkComputer/qmk_firmware/blob/v0.3.1/keyboards/framework/macropad/keymaps/default/keymap.c)
104145

105146
## License
106-
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/
147+
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/

‎README.md‎

Lines changed: 70 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,22 @@
11
# Framework Laptop 16 Input Modules
22
![InputModules](https://user-images.githubusercontent.com/28994301/226249081-ab193cfe-4da4-4c47-93ec-c6024edf4fbc.png)
33

4-
This repository includes mechanical and electrical documentation for the Input Module system in the
4+
This repository includes mechanical and electrical documentation for the Input Module system in the
55
Framework Laptop 16. Input Modules are hot-swappable USB 2.0-interfaced devices that enable deep
6-
customization of the input system on the Framework Laptop 16. It's also possible to use these as
6+
customization of the input system on the Framework Laptop 16. It's also possible to use these as
77
standalone USB 2.0 devices with a simple adapter for development purposes.
88

99
Input Modules come in three sizes, each of which has the same electrical interface:
1010
1. Keyboard-sized modules (283.16mm wide)
1111
2. Numpad-sized modules (67.85mm wide)
1212
3. Half-sized modules (33.825mm wide)
1313

14-
**Warning:** the documentation here is pretty early, so there may be minor adjustments in the mechanical or electrical designs
15-
before the Framework Laptop 16 launches. We'll let you know when the design is locked for production.
16-
14+
For reference firmware for different types of modules, check out these additional repositories:
15+
* [QMK firmware](https://github.com/frameworkcomputer/qmk_firmware) for the keyboard and numpad modules
16+
* [inputmodule-rs](https://github.com/FrameworkComputer/inputmodule-rs) firmware and application for other input modules
17+
1718
## License
18-
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/
19+
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/
1920

2021
## Firmware and Software
2122

@@ -27,11 +28,36 @@ Find the latest binary releases and source code in our [FrameworkComputer/qmk_fi
2728
To configure keybindings, use our hosted VIA fork, which has the right configurations built in at https://keyboard.frame.work.
2829
Or the [qmk_hid](https://github.com/FrameworkComputer/qmk_hid) native Python or Rust software GUI and console applications.
2930

31+
HALs for RTOS or baremetal environments:
32+
33+
- [rust-embedded](https://github.com/rp-rs/rp-hal-boards/tree/main/boards/framework16-keyboard)
34+
- [capslock Sample](https://github.com/rp-rs/rp-hal-boards/blob/main/boards/framework16-keyboard/examples/capslock.rs)
35+
- [white_backlight Sample](https://github.com/rp-rs/rp-hal-boards/blob/main/boards/framework16-keyboard/examples/white_backlight.rs)
36+
- [Zephyr](https://docs.zephyrproject.org/latest/boards/framework/laptop16_keyboard/doc/index.html)
37+
38+
IS31FL3743 LED Controller Drivers:
39+
40+
- [QMK](https://docs.qmk.fm/drivers/is31fl3743a)
41+
- [rust-embedded](https://docs.rs/is31fl3743a/latest/is31fl3743a/)
42+
- [CircuitPython](https://github.com/FrameworkComputer/CircuitPython_IS31FL3743)
43+
3044
### LED Matrix
3145

3246
Official firmware that ships with the modules is available in source and binary at [FrameworkComputer/inputmodule-rs](https://github.com/FrameworkComputer/inputmodule-rs).
3347
That same repository also contains a Rust commandline utility and Python scripts to control the matrix.
3448

49+
HALs for RTOS or baremetal environments:
50+
51+
- [rust-embedded](https://github.com/rp-rs/rp-hal-boards/tree/main/boards/framework-ledmatrix)
52+
- [ledtest Sample](https://github.com/rp-rs/rp-hal-boards/blob/main/boards/framework-ledmatrix/examples/ledtest.rs)
53+
- [Zephyr](https://docs.zephyrproject.org/latest/boards/framework/framework_ledmatrix/doc/index.html)
54+
55+
IS31FL3741 LED Controller Drivers:
56+
57+
- [QMK](https://docs.qmk.fm/drivers/is31fl3741)
58+
- [rust-embedded](https://docs.rs/is31fl3741/latest/is31fl3741)
59+
- [CircuitPython](https://github.com/adafruit/Adafruit_CircuitPython_IS31FL3741)
60+
3561
Third party applications that interact with the official firmware:
3662

3763
- [https://github.com/jpadgett314/led-matrix-vocab](jpadgett314/led-matrix-vocab) - A japanese vocab trainer
@@ -41,13 +67,26 @@ Third party firmware projects that run on the official hardware:
4167
- [https://github.com/sigroot/FW_LED_Matrix_Firmware](sigroot/FW_LED_Matrix_Firmware) - Arduino based firmware with an alternative host protocol
4268
- [https://github.com/vddCore/sparkle-fw16](vddCore/sparkle-fw16) - Pico SDK based firmware with an alternative host protocol
4369

70+
### CircuitPython
71+
72+
CircuitPython can run on all modules.
73+
74+
Sample Code:
75+
76+
- [github.com/FrameworkComputer/Framework_Inputmodule_CircuitPython](https://github.com/FrameworkComputer/Framework_Inputmodule_CircuitPython)
77+
78+
Libraries:
79+
80+
- [Keyboard RGB Controller Adafruit_CircuitPython_IS31FL3741](https://github.com/adafruit/Adafruit_CircuitPython_IS31FL3741)
81+
- [Keyboard RGB Controller - Framework CircuitPython_IS31FL3743](https://github.com/FrameworkComputer/CircuitPython_IS31FL3743)
82+
4483
## Mechanical
4584

4685
In the Mechanical folder, we have 2D drawings of the different Input Module sizes. Note that there are two version of each:
4786
1. A version with full mechanical structure with a separate interface PCB and brackets. This is what our production modules are based on.
4887
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.
4988
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
50-
the magnets in the system.
89+
the magnets in the system.
5190

5291
## Electrical
5392

@@ -97,13 +136,31 @@ The LED matrix and plastic spacers are both C size.
97136

98137
Each Input Module supports up to 500mA on the 5V rail and 100mA on the 3.3V rail when active.
99138

139+
The Framework Laptop 16 has a protection scheme in place to prevent Input Modules from powering on unless the input deck is fully populated.
140+
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.
141+
142+
System firmware expects that pogo connector where the module presents the board
143+
ID, is at the very left of the module. It uses this assumption to calculate
144+
size and position of modules and detect if the input deck is fully populated
145+
and all pogo pins are covered.
146+
147+
#### `SLEEP#` pin behavior
148+
149+
| Platform | BIOS | `SLEEP#` |
150+
|-----------------------|------|-----------------|
151+
| AMD Ryzen 7040 Series | 3.XX | Lid and Suspend |
152+
| AMD Ryzen 7040 Series | 4.XX | Lid state |
153+
| AMD AI 300 Series | Any | Lid state |
154+
155+
On the first generation Framework 16 with BIOS 3.XX the `SLEEP#` pin is low
156+
whenever the system is in S0ix (suspend) state or the lid is closed.
157+
158+
On the 2nd gen or 1st gen with BIOS 4.XX the `SLEEP#` pin is only low if the lid is closed.
159+
This change was made because the keyboard and touchpad firmware couldn't decide between
160+
100161
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
101162
system enters an S0ix state. In S3/S4/S5 or when the laptop lid is closed, the power rails will typically be off.
102163

103-
The Framework Laptop 16 has a protection scheme in place to prevent Input Modules from powering on unless the input deck is fully populated.
104-
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
105-
or modules.
106-
107164
F2 on boot > Setup Utility > Advanced > Force Power for Input Modules:
108165

109166
- Force Off: Power always off
@@ -115,6 +172,7 @@ In the case of Force On, there is a risk of damage when the pins are exposed and
115172
## Touchpad Module
116173

117174
This section describes the Touchpad Module connection on the **system** side, including the pin define and the pin map of the connector.
175+
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.
118176

119177
Pins on the connector have ESD protection to meet IEC 61000-4-2 Level 4 protection.
120178

@@ -134,7 +192,7 @@ Pins on the connector have ESD protection to meet IEC 61000-4-2 Level 4 protecti
134192
### Touchpad Module layout requirements
135193

136194
The contacts on the Touchpad should be designed so that the ground pins engage first when the Touchpad is sliding in.
137-
Pin 7 should be 0.5mm longer than the other pins to ensure it engages first.
195+
Pin 7 should be 0.5mm longer than the other pins to ensure it engages first.
138196

139197
The below picture for pads is shown in perspective. The view angle is on top of the PCB.
140198

0 commit comments

Comments
 (0)