Input Architect — Open-Source Keyboard & Macropad Configurator for Framework Laptops

[ToySnail]

Hey everyone! I’ve been building a desktop configurator for the Framework 16 ANSI Keyboard and RGB Macropad, and it’s at a point where I’d love some testers to try it out and give feedback.

What is it?

Input Architect is a lightweight Windows app (2 MB, built with Tauri) that lets you remap keys and control RGB lighting on your Framework 16 input modules using the VIA protocol. If you flash nucleardog’s custom firmware, you also get full per-key RGB control — set individual key colors, save named configs, and restore them with one click.

Features:

• Key remapping — all 6 layers, 100+ QMK keycodes, live readback
• RGB lighting — brightness, effects, speed, color with real-time preview
• Per-key RGB — click individual keys to set their colors (requires nucleardog firmware)
• Smart key selection — Shift+click for ranges, Ctrl+click for multi-select, built-in presets (WASD, FPS Kit, F-Keys, etc.), plus save your own custom presets
• Config save & restore — saves to EEPROM + creates named snapshots you can swap between; restoring auto-selects all keys so you can immediately adjust brightness
• Full backup/restore — export your entire config (all 6 layers + RGB + per-key colors) as JSON
• Auto-reconnect — re-applies your RGB settings after sleep/wake
• Built-in firmware guide — one-click build script for nucleardog’s per-key RGB firmware, guided flash workflow
• Diagnostics — LED test sequence, health check, firmware probe, full HID command log

Supported devices:

Module	Per-Key RGB
Framework 16 ANSI Keyboard (0x0012)	With nucleardog firmware
Framework 16 RGB Macropad (0x0013)	With nucleardog firmware

Download & Source:

https://github.com/enkode/input-architect

The Windows installer is on the Releases page. You can also run it in the browser (Chrome/Edge) by cloning the repo and running npm run dev.

Looking for feedback on:

• Does it detect and connect to your keyboard/macropad correctly?
• Do per-key RGB colors work after flashing nucleardog firmware?
• Does config save/restore work reliably?
• Any crashes, UI issues, or things that feel unintuitive?
• Does auto-reconnect work after closing the lid and reopening?
• General Usability

The app communicates with the keyboard over WebHID using the VIA protocol, so it works alongside VIA — no conflicts. The RP2040 bootloader is permanent and immutable, so there’s zero risk of bricking your device if you try the custom firmware.

Update:

Linux users wanted! This release includes Linux builds — both an AppImage (runs anywhere) and a .deb package (Debian/Ubuntu). I’ve been developing and testing on Windows, so the Linux builds are untested on real hardware. If you’re running a Framework 16 on Linux, I’d especially love feedback on:

• Does the AppImage or .deb launch correctly on your distro?
• Does WebHID device access work? (You may need udev rules for HID device permissions — try adding a rule for the Framework VID 0x32AC)
• Does auto-reconnect work after suspend/resume?
• Any GTK/WebKitGTK rendering issues?

The app should work on any distro with WebKitGTK 4.1 installed. If you can’t get the desktop app working, you can always run it in Chrome/Edge with npm run dev from the cloned repo.

Happy to answer any questions. Thanks for testing!

[MJ1]

This is excellent!
Both window & linux too!

~edit~

Correction, I’m hiding the portion of my previous comment rather than deleting just to avoid breaking later references to my comment.

The risk of brick is much lower than I thought, see post #15. It does not seem much of a concern at all in light of how FW built one of their bootloader-mode triggers.

My previous comment:

---

@ToySnail

The RP2040 bootloader is permanent and immutable, so there’s zero risk of bricking your device if you try the custom firmware.

If I may, since the Framework keyboards lack a hardware bootloader-mode button, it might be possible to brick keyboards. If one gets unlucky enough.

If flashing gets interrupted at the wrong point it might be possible to lose the ability to use any of the software bootloader-mode options built into qmk. At which point many people would have a brick that they wouldn’t have the parts, experience, or steady enough hands to recover from. You’d need a Framework keyboard pogo pin adapter to allow you to connect the keyboard while upside-down, so you have access to carefully bridge the bootloader-mode test pad to gnd during power up.

[Per_Magnus_Tveten]

Hi, just installed the ‘NuclearDog’ firmware on my Macropad
and then downloaded and installed your software as well.. and yeah works as advertised!

easy to configure key binding with individual colours.

Now… I just need to motivate my self and actually go through and setup the keys how I had it with my custom setup lol

[Per_Magnus_Tveten]

Hmmmm I always use the key combo… where you hold down these while attaching it:

0000
0000
0000
000H
0H00
0000

For Macropads that is.. keyboards have some other 2 key combo..

can that be bricked as well ? I was thinking that was a hardwire thing..

[Per_Magnus_Tveten]

Hmmmm I must have missed something.. how does layers work..
I can’t seem to find something I can map a key to to active a different layers..
kinda expected to be able to map a button that say activate layer x

[MJ1]

Corrected by post #15

Summary (click to show)

@Per_Magnus_Tveten

For Macropads that is.. keyboards have some other 2 key combo..

can that be bricked as well ? I was thinking that was a hardwire thing..

You mean hardware bootloader-mode button? No, none of the Framework bootloader-mode options are an actual hardware bootloader-mode button. All of them are being triggered by the qmk firmware detecting what you are doing. Which requires at least that portion of the firmware to not be corrupted.

The RP2040 hardware bootloader-mode, aka bootsel, works by grounding the SPI CS pin on the flash chip, which causes the RP2040 fallback to bootloader-mode.

~edit~
Looks like Framework did build in a way to use the flash chip’s CS pin.

Quote from post #15

@ToySnail

So @MJ1 is correct that it’s not a traditional hardware button (like a Pi Pico’s BOOTSEL), but Framework designed it so the key detection happens at the hardware/electrical level, not in QMK firmware. That’s also why "bootmagic": false is set in Framework’s QMK config – they don’t use QMK’s firmware-level bootmagic at all.

Bottom line: even with totally corrupted firmware, holding those keys while reconnecting the module should still get you into bootloader mode. It’s a clever design on Framework’s part.

[MJ1]

There a few different options to trigger layer changes, https://docs.qmk.fm/feature_layers
MO(layer) momentarily changes the layer, while the key is held down.
TG(layer) toggles a layer.

[Per_Magnus_Tveten]

@MJ1

The RP2040 hardware bootloader-mode, aka bootsel, works by grounding the SPI CS pin on the flash chip, which causes the RP2040 fallback to bootloader-mode.

Yeah.. thats kinda what I naively thought the keyboard/macropad did on a hardware layer when you push those two keys… since the bootloader button only affects it when It’s powering on.. oh well.. good thing this is a laptop with keyboard so less likely to suddely loose power…

lol ok…was trying to edit my reply as professionally as MJ1 but failed..

Any way as he said post 15 has the corrections

[Per_Magnus_Tveten]

yeah in “my” custom firmware (can’t really call it mine.. was just modified from what I found til it did what I wanted lol)… I used the
’TO(layer) - activates layer and de-activates all other layers (except your default layer).’

to switch between layers.. (well each layer had that same button to take to the next layer.. and then loop to 1st)

But with this ‘input Architect’ I can not find how to do the layers the way I would like them to

[MJ1]

@Per_Magnus_Tveten

But with this ‘input Architect’ I can not find how to do the layers the way I would like them to

Are you on windows?
I tried to poke around to see if I could find the layer keys, but it’s not loading for me. Appimage & .deb both just come up black.

[Per_Magnus_Tveten]

yeah I’m on windows

[ToySnail]

Working on the layers!

[ToySnail]

@MJ1 – Great point, and I appreciate the correction. You’re right that I overstated it by saying “zero risk.” Let me update that.

The RP2040’s mask ROM bootloader is indeed immutable (baked into silicon at fabrication), so a completely corrupted flash will cause the ROM to fail the boot2 checksum and automatically fall back to USB mass storage mode – that part is accurate.

However, you raise a valid edge case: if a flash gets interrupted at exactly the wrong point, it’s theoretically possible to end up in a state where the QMK firmware is partially functional – enough to pass the boot2 checksum but not enough to handle the bootloader-mode key combos. At that point recovery would require grounding the SPI CS pin (flash chip-select) manually during power-up, which, as you mentioned, isn’t trivial on a laptop keyboard module without the right tools.

That said, in practice the risk is extremely low for a couple reasons:

• UF2 flashing on the RP2040 is handled by the ROM bootloader itself (the device appears as a USB mass storage drive), so even if you yank the cable mid-flash, the ROM bootloader will still run on the next boot and you’ll get the RPI-RP2 drive again

• The flash chip is external to the RP2040, and a partial write that corrupts boot2 will fail the ROM’s CRC check, triggering automatic fallback to USB boot

I’ll update the wording in the post to say something like “extremely low risk” rather than “zero risk,” and note that the hardware key combos are firmware-triggered, not true hardware buttons. Thanks for keeping it accurate.

[ToySnail]

@Per_Magnus_Tveten – Awesome, glad to hear it’s working! That’s exactly the feedback I was hoping for. Looking forward to seeing what you set up on your macropad once you get around to it.

[ToySnail]

@Per_Magnus_Tveten – Good question. After digging into Framework’s QMK source code, it turns out the two-key combo is actually closer to hardware-level than MJ1 initially suggested, though it’s a bit nuanced.

Looking at Framework’s framework.c, there’s this comment:

// Before this, when holding down both alt keys QSPI_SS is pulled low
// to put the RP2040 in bootloader mode during reset.

The keyboard PCB has a hardware circuit that detects when both Alt keys (or keys 2+6 on macropad) are held during power-up and physically pulls the QSPI_SS (flash chip-select) line low. This happens before any firmware runs – it’s an electrical circuit on the PCB itself. The firmware’s only involvement is signaling “boot is complete” afterward via a GPIO pin (BOOT_DONE), which tells the hardware circuit to release the CS line.

So @MJ1 is correct that it’s not a traditional hardware button (like a Pi Pico’s BOOTSEL), but Framework designed it so the key detection happens at the hardware/electrical level, not in QMK firmware. That’s also why "bootmagic": false is set in Framework’s QMK config – they don’t use QMK’s firmware-level bootmagic at all.

Bottom line: even with totally corrupted firmware, holding those keys while reconnecting the module should still get you into bootloader mode. It’s a clever design on Framework’s part.

[ToySnail]

@MJ1 – Thanks for testing the Linux builds! The black screen is a known issue with Tauri apps on Linux, caused by WebKitGTK’s GPU-accelerated rendering being incompatible with certain graphics configurations.

Quick fix – try launching with these environment variables:

WEBKIT_DISABLE_COMPOSITING_MODE=1 ./input-architect

or if that doesn’t work:

WEBKIT_DISABLE_DMABUF_RENDERER=1 ./input-architect

or both:

WEBKIT_DISABLE_COMPOSITING_MODE=1 WEBKIT_DISABLE_DMABUF_RENDERER=1 ./input-architect

This is especially common with:

• NVIDIA GPUs (proprietary drivers)
• Tiling window managers (i3, sway, bspwm)
• Wayland sessions

Can you let me know your distro, GPU, display server (X11 or Wayland), and desktop environment? That’ll help me narrow down which fix to bake into the next release so it works out of the box.

In the meantime, if the desktop app won’t cooperate, you can always clone the repo and run npm run dev in Chrome/Edge – the WebHID functionality works the same way in the browser.

I’m planning to add the workaround directly into the app’s startup code for the next release so nobody has to set environment variables manually.

[ToySnail]

v0.15.0 Update — Layer Switching, Linux Fix, and More

Hey everyone, quick update — v0.15.0 is live with the features and fixes discussed in this thread.

Layer Switching Keycodes

This was the big one. Go to the Mapping tab, select a key, and you’ll see a new Layers category with all the QMK layer functions:

Function	What it does
MO(layer)	Momentary — active while held (this is what the Fn key uses)
TG(layer)	Toggle — press once to activate, press again to deactivate
TO(layer)	Turn On — switches to that layer and deactivates all others
OSL(layer)	One-Shot — activates the layer for one keypress, then returns
TT(layer)	Tap-Toggle — hold for momentary, multi-tap to toggle permanently
DF(layer)	Default Layer — changes which layer is the always-active base

All 10 firmware layers (0-9) are supported. For example, @Per_Magnus_Tveten’s setup where each layer cycles to the next with TO() — just assign TO(1) on a key in layer 0, TO(2) on the same key in layer 1, and so on, with TO(0) on the last layer to loop back.

Any existing layer keycodes already on your keyboard (like the Fn key’s MO(1)) will now display properly on the virtual keyboard instead of showing as hex values.

Linux Black Screen Fix

@MJ1 — the WebKitGTK rendering workaround is now baked directly into the app. It automatically sets WEBKIT_DISABLE_COMPOSITING_MODE and WEBKIT_DISABLE_DMABUF_RENDERER before the window opens, so no more manual environment variables. This should fix black screens on NVIDIA, Wayland, and tiling window managers. Let me know if it works on your setup.

Safety Documentation

Updated the bricking risk language per @MJ1’s feedback. The README and in-app safety banner now explain the actual recovery mechanisms — the RP2040’s mask ROM bootloader, automatic USB fallback on checksum failure, and Framework’s hardware-level two-key bootloader entry. Practical risk is extremely low, but “impossible” was too strong a claim.

Download: Release v0.15.0 — Layer Switching, Linux Fix, Tester Credits · enkode/input-architect · GitHub

Windows installer is on the release page. Linux builds (.deb and .AppImage) are building via GitHub Actions and should be available from the CI artifacts shortly.

Thanks again to @MJ1 and @Per_Magnus_Tveten for being the first testers — your feedback directly shaped this release. Keep it coming!

[ToySnail]

Update: Layer Mapping UX Simplified

Quick follow-up — the layer keycodes I added to the Mapping tab’s key picker grid were a quick fix that didn’t really make sense (too many steps to do something simple). I’ve replaced it with a much more intuitive flow directly in the Layer Selector dropdown:

1. Open the Layer Selector (bottom-left, Mapping tab)
2. Click Map next to the layer you want a key to switch to
3. Pick the type: MO (hold to activate), TG (toggle on/off), or TO (switch and stay)
4. Click the key on your keyboard — done, keycode assigned instantly

A banner shows what you’re about to map, and you can press Escape to cancel. The layer keycodes in the key picker grid are still there if you want fine-grained control, but the Map button is the way to go for most users.

@Per_Magnus_Tveten — for your layer cycling setup, just click Map → TO next to each layer, then click the key you want. Do that on each layer (switching layers in the dropdown as you go) with the next layer number, and TO(0) on the last one to loop back. Much simpler than hunting through the key picker.

Same release link: Release v0.15.0 — Layer Switching, Linux Fix, Tester Credits · enkode/input-architect · GitHub

[Kieran_Levin]

Just to clarify, both the keyboard and numpad/macropad support entering the RP2040 hardware bootloader through a 2 key combo.

Eg on the keyboard:

1. Slide touchpad down, until the input deck powers off (you can see the backlights turning off).
2. Hold left and right ALT keys pressed, while sliding the touchpad back up again to enter the hardware bootloader.

For numpad/macropad hold down keys 1 and 6.

[Per_Magnus_Tveten]

Hmmm pretty sure it’s 2 & 6

( bit hard to tell on macro pad as no key stickers )