The Ryan D. Lewis Feed

🦑 The Modular Autonomous Discovery for Science (MADSci) Framework

2024-11-01T00:00:00Z

Project Link: https://github.com/AD-SDL/MADSci

Description: A modular, autonomous, and scalable framework for scientific discovery and experimentation.

About MADSci

MADSci is the spiritual successor to WEI, and is intended to provide a modular toolkit with which to assemble self driving labs from any combination of automated instruments, resources, and functionalities the user might need.

It's still very much a work in progress (we're aiming for an Alpha release in the next couple weeks¹), but I'm excited to take all the lessons we've learned from working on WEI and apply it to MADSci.

🧪 The Workflow Execution Interface (WEI)

2023-09-05T00:00:00Z

Project Link: https://github.com/AD-SDL/WEI

Description: The Workcell Execution Interface (WEI) for Autonomous Discovery/Self Driving Laboratories (AD/SDLs)

About WEI

When I returned to ANL in the fall of 2023, I started full time as a roboticist and software developer in the Rapid Prototyping Lab. In the time I had been away at UMich earning my MS in Robotics, the lab had been busy, primarily working on this project: the Workflow Execution Interface, or WEI.

The principal purpose of WEI is to act as an orchestrator and central planner for the various instruments we were automating as part of the Self Driving Labs effort. In the year after starting, I spent much of my time working on improving the functionality of WEI: adding better state management, dockerizing and packaging the software, adding better helpers for easily automating instruments, supporting administrative actions like pausing and safety stops, and various minor improvements.

As of the beginning of 2025, we've started working on a successor project to WEI, the Modular Autonomous Discovery for Science (MADSci) Framework, to leverage everything we learned building and improving WEI while creating a more scalable and approachable toolkit for lab automation and autonomous discovery.

How to Call a Service from a ROS2 Launch File

2022-09-03T00:00:00Z

This one is pretty straight forward, but took me a non-trivial amount of searching to find for myself. To call a ros2 service from a ros2 launch file, add the following to your launch file (see the official docs for more on launch files):

from launch.substitutions import FindExecutable
from launch.actions import ExecuteProcess

...

ld.add_action(
    ExecuteProcess(
        cmd=[[
            FindExecutable(name='ros2'),
            " service call ",
            "/namespace/service_to_call ",
            "example_msgs/srv/ExampleMsg ",
            '"{param_1: True, param_2: 0.0}"',
        ]],
        shell=True
    )
)

Note the following:

ld here is a variable containing an instance of LaunchDescription
/namespace/service_to_call is replaced with the service you're looking to call (don't forget any appropriate namespaces) and can be found with ros2 service list
example_msgs/srv/ExampleMsg is the message type used by that service, which you can get with ros2 service info /namespace/service_to_call
"{param_1: True, param_2: 0.0}" is the dictionary defining the message data. To find the parameters you need to set, you may need to consult the .srv file or documentation.

Don't forget to include the shell=True argument, as the command will fail with a confusing "File not found" error without it.

The Bandoleers Session 027

2022-06-25T00:00:00Z

DM's Log: Supplemental...Session 027

Date: 2022-06-01

Party: The Bandoleers

Kilomir, Minotaur Wild-Magic Barbarian
Faegwyn Suithrasas, High Elf School of Evocation Wizard
Ollie, Tiefling Way of the Long Death Monk
Mick Nichols, Rock Gnome Assassin Rogue
- Accompanied by his trusty sidekick/mount, a Giant Duck named Lumpy
Melisende, Cleric of Aelys and temporary Retainer accompanying the party

Session 027 Recap

We pick up at the beginning of the session exactly where we left off: immediately after the party fended off 12 hungry zombies and their Wight leader in the middle of the night. Though mostly unscathed, the party opted to finish their rest, and slept in.

Before resuming their journey, they searched the Zombie's corpses¹, before deciding to hide them far enough off the side of the road that they wouldn't be seen. They then set off to make the final day's trek to the keep. Along the way, they came across an abandoned camp, complete with weapons and armor, presumably from the zombified guards.

Arriving at their destination at dusk, they prudently opted to make camp a safe distance away rather than approaching the keep at night. In the morning, Mick rode Lumpy up to survey their destination. He discovered the keep was dark, silent, and utterly absent of any sign of life, with the gate standing wide open and seemingly unprotected. Mick returned to the group with this news, and they concocted a plan: hide the wagon, approach on foot, sneak around back, and have Lumpy fly a rope attached to a grappling hook up to the top of the keep.

And so, a few good stealth rolls later, the party found themselves on the roof of the castle, inching down a dark staircase into the top floor of the keep. They poked around in a large dining area, noting the old food on the central table and investigating a couple statues around the perimeter of the room that Faegwyn determined were probably former Knights of the Westerwatch. Meanwhile, Mick got to work picking a locked door on one side of the room, and Kilomir kept a lookout.

Unfortunately, a very low perception roll meant that Kilomir was keeping an eye out for threats coming from outside the room, and failed to notice the 5 Boneless (undead remains lacking their skeletons) slithering out from beneath the large dining table in the center of the room.

The ambush led to a short but pitched battle, with the party successfully defeating the Boneless, though not before Mick was engulfed by one of the "Undead Murder Blankets" and nearly smothered to death. But Kilomir's Longsword of the Forgotten Paladin, with its extra Radiant Damage against Undead, Faegwyn's punishing Scorching Rays, and Ollie's onslaught of fists made quick work of their foes. The Party emerged from the fight a little battered, a little bruised, but ready to press deeper into the Westerwatch.

DM's Post Mortem

Okay, so two things stuck out to me about this session.

First, if you give one of your players a flying mount, assume they will use it for unconventional approaches to entering dungeons. I had a whole thing planned with a closing portcullis trap, which I've been itching to try out and was going to use with the entrance to the keep, and it was completely defanged just by them deciding to do an aerial insertion. Plus, now they're going through my encounter design backwards. Ah well.

Second, if you have a campaign that will heavily feature a certain type of enemy, don't give the low-level players a weapon that does 2d10 magical bonus damage against enemies of that type, especially if those enemies often have weaknesses to said type. Or at least, equally distribute that among the party. Otherwise you'll find yourself in a situation where one character consistently outpaces the rest of the party in ways that are hard to balance around. Obvious in retrospect, but I don't think I really considered how much extra damage 2d10 is on every attack.

That's all for this post! Life's been a bit hectic recently (that's why this post is almost a month late), so I've got a small backlog of sessions to post about, so stay tuned for those!

The Bandoleers Session 026

2022-05-18T00:00:00Z

DM's Log: Supplemental...Session 026

Date: 2022-05-12

Party: The Bandoleers

Kilomir, Minotaur Wild-Magic Barbarian
- The muscle of the group
- Trying to learn how to craft Dragonborn Plate Armor
Faegwyn Suithrasas, High Elf School of Evocation Wizard
- Resident grumpy old man
- Trying, with varying degrees of success, to expand the Wagonline business that he inherited after the unfortunate death of the previous proprietor at the vicious claws of a flock of cockatrice
Ollie, Tiefling Way of the Long Death Monk
- Mandatory party Edgelord
- Has the unique ability to see and speak with the Gods of Corithynn
Mick Nichols, Rock Gnome Assassin Rogue
- Accompanied by his trusty sidekick/mount, a Giant Duck named Lumpy

Session 026 Recap

In this session, The Bandoleers began their 3-day journey to the Westerwatch, a small keep nestled in the mountains west of the city of Dmittlock ¹ that recently stopped sending reports. They were joined by a cleric, Melisende, of the local deity Aelys.²

The route to the Westerwatch is along a fairly well-traveled and "safe" road, and so their first day of travel passed without incident. As nightfall approached, they reached a small hamlet, where they decided to try and find a place to stay. And so they made the acquaintance of an old one-legged Rock Gnome named Igden Umbodoben, who was sitting on his porch and enjoying the fresh air.

After some pleasantries, Igden graciously agreed to put the party up in his barn for the evening for a crisp 5 silver. He also answered some questions about their route and destination (including telling them that a patrol of 12 towns guard had passed through on their way to the keep recently, and not yet returned).

The party's resident Gnome, Mick, also had a private sidebar with Igden, connecting over the fact that they were both veterans of a recent civil war in their home city, Quarriton. There was an awkward verbal dance where they both tried to figure out which side the other fought on, until eventually Igden asked directly and it was revealed they were both Partisans.

After an evening's rest safely in the barn, the second day of the journey brought them out of the dense forest surrounding Dmittlock. Now they found themselves journeying across grasslands and sloping hills which I described to the players as having "Big Iowa Energy". And, just like driving across Iowa, this day of travel passed without anything of note occurring.

With no civilization in sight this time at the end of the day, the party decided to take their wagon off the side of the road ("31 feet", per Kilomir's player's request). At this point, the party has learned to keep a watch, and so Ollie was dutifully patrolling around the wagon when he heard ominous moaning coming from down the road.

Peering out into the darkness with his Tiefling Dark Vision, Ollie was able to detect a small group of figures shambling up the road. After waiting a beat to see what they did and realizing that they were getting closer and closer, he decided to wake the others. Unfortunately, his attempt to do so quietly was foiled when he rolled in the single digits on a Stealth check, and as a result was given away by a very squeaky hinge on the wagon's door.³

As soon as the figures heard Ollie's racket, they froze. The party gathered and readied themselves, and, as the unidentified group began moving again, Faegwyn's sharp elvish eyes (and high perception roll) immediately identified the shuffling gait of wretched Undead. With a cry to alert the others, initiative was rolled as the Zombies charged in!⁴

The battle was chaotic but not necessarily difficult for the party. Ollie, Mick, and Kilomir charged to the fore, while Melisende and Faegwyn stayed back by the wagon. As it transpired, the 12 zombies were joined by a Wight, who hung back and attempted (mostly unsuccessfully) to pepper Faegwyn with his longbow. The frontliners were able to clean up the Zombies without too much damage (Kilomir and Ollie came out entirely unscathed), and then chased down and dispatched the Wight when it attempted to flee.

And that's where we'll pick up next session!

DM's Post Mortem

Alright, so this session was...interesting...to try and run, because I made the mistake of trying to do it while sick.⁵ This meant that the session 1.) was shorter than I'd hoped, 2.) took me longer to prepare than usual, and 3.) was probably not my best work. I was determined to run, regardless of how miserable I felt, because scheduling is hard and it had already been awhile since our previous session and I didn't want to postpone again. But by the end of the night I was practically a zombie myself, and as soon as the Wight's HP hit 0 I was out.

But I did still get the opportunity to try some stuff I've been wanting to work in to the campaign, so let's talk about those things.

On Melisende and Retainers

There are many ways to run an NPC who's tagging along with a party of PCs.

Roll up a PC and run them yourself (often frowned upon)
Make a stat block and run them as another NPC (more work for the DM, action economy in shambles)
The Companion Rules from Tasha's Cauldron of Everything (haven't tried them yet)
MCDM's Retainers <--This is the one I went with

I've had MCDM's Strongholds and Followers for awhile now, but hadn't gotten a chance to use the Retainer system introduced in it just yet. This system provides an easy way to give your PCs loyal companions which the DM roleplays, but the player runs in combat. The system is suppose to enable competent, helpful, and easy to run companions who don't steal the show from the main characters: the PCs.

As it just so happens, MCDM just recently released the kickstarter for their next book, Flee, Mortals!, and with it a 26-page PDF preview. And that preview included some updated Retainer rules (most notably replacing a somewhat clunky health level system from the original), so I decided to give that a shot. I used a "Healer" Cleric retainer from the S&F book, updated with the new rules, made a little PDF handout of her stats to give to the player for reference, and that was that.

I gave combat control of her to Kilomir's player, who seemed to be able to pick up on what he could do with her with little issue and only a small amount of guidance from me as the DM. The addition of a Retainer didn't seem to slow the game down much, if at all, or terribly unbalance the encounter, which are really all you can ask for. Overall, very happy with the system so far!

Minions

From the same preview PDF, MCDM also introduced rules for Minions, in the style of 4th edition D&D, but revamped and revised for 5e. This was another thing I really wanted to try, and since I already had a zombie encounter planned and the PDF included a sample zombie minion, it seemed meant to be! These rules allow you to inundate your PCs with swarms of low-health enemies that are weak individually but dangerous in hordes.

Overall, I found the system worked pretty well, and definitely was faster than running 12 individual zombies with their own action, movement and bonus action. It has a nice system for bundling up multiple attacking minions into a single attack roll per target. The overkill mechanics are also nice.

I suspect the most challenging aspect of using these guys properly will ultimately be balancing encounters. This combat encounter wasn't meant to be brutally difficult, more just ominously foreshadowing, but I was a little surprised at how easily the party dispatched the horde. Part of that was because I made the mistake of starting the zombies too far away, giving the PCs ample time to hit them at range and thin the herd. But the other part was that I suspect the CR math overestimated the threat involved. But nobody has ever accused 5e's CR system of being infallible.

I did find the mechanics around spell saves unintuitive enough that I had to stop and look them up, which didn't feel great, but I understand the design decisions behind it and think the way it currently works is probably for the best. I imagine it'll be better once I can remember it off the cuff.

Conclusion

Maybe not my best session, but the players seemed to have fun and I got to try out some fun MCDM goodies I've been meaning to find an excuse to use. And hey, at least I can blame any problems that came up during the session on illness.

Introducing DM's Log: Supplemental

2022-05-05T00:00:00Z

DM's Log: Supplemental

Date: 2022-05-05.

Session: N/A

At last, I've discovered it! The nerdiest possible thing I could spend my time doing: writing about my Dungeons and Dragons games on the internet.

This will be the first in a series of logs recounting my experiences as an aggressively mediocre Dungeon Master attempting to run half decent games in between work and grad school.

Why?

A little experiment I'm trying. I want to practice writing more often (fun writing, not just code, emails, project reports, and academic papers). And I figure, what better way to do it than cataloging the shenanigans of my semi-regular D&D games?

I'm also hoping to include a little bit of reflection on each game, how I thought it went, and how I think I can improve. Hopefully, that will be useful for other DM's as well, but if nothing else it should help me.

What Games?

Currently, I'm DMing one game with plans to start a fairly ambitious project this summer. I may also write about some of the games I play in, if the mood strikes me, though I just wrapped up one game and the other I regularly play in is on indefinite hold.

The Bandoleers

A scrappy group of adventurers grappling with a mysterious outbreak of undead and plague, the many dangers of open road and claustrophobic dungeon, and the struggles of operating a small business; all set in the homebrew world of Corithynn.

Starring:

Kilomir, Minotaur Wild-Magic Barbarian
- The muscle of the group
- Trying to learn how to craft Dragonborn Plate Armor
Faegwyn Suithrasas, High Elf School of Evocation Wizard
- Resident grumpy old man
- Trying, with varying degrees of success, to expand the Wagonline business that he inherited after the unfortunate death of the previous proprietor at the vicious claws of a flock of cockatrice
Ollie, Tiefling Way of the Long Death Monk
- Mandatory party Edgelord
- Has the unique ability to see and speak with the Gods of Corithynn
Mick Nichols, Rock Gnome Assassin Rogue
- Accompanied by his trusty sidekick/mount, a Giant Duck named Lumpy

In the next session (Session 026), the Bandoleers are heading out from the relative safety of their current port of call, the Drunkard's City Dmittlock, and making a 3-day trek to an old fort called the Westerwatch that has stopped sending its regular reports.
With one patrol of the City Watch already sent to investigate and seemingly lost, they're expecting trouble.
They got this particular gig by striking a deal with the head of the Privy Council of Dmittlock to figure out what's going on in exchange for a hefty chunk of change and the opportunity to further some of their party goals.

Empyrea Lost

This is my secret summer project. More details to come!

How to Install and Use Docker in WSL2

2022-03-06T00:00:00Z

Edit: It's come to my attention that, since I figured out this workaround back when WSL2 and thus Docker's WSL2 backend were new, Docker Desktop for Windows has added support for using Docker from within your WSL2 distro. This obviates the need to install Docker within a WSL2 distro in most cases. But if you find yourself in a position where you can't or don't want to use the Docker Desktop support, read on.

Say you want to run a Linux environment on a Windows machine, and in that environment one of the things you want to do is make use of docker containers. Here's the quick and dirty way to get that set up:

Install WSL

Nowadays, this should be as simple as Win+X, selecting <Command Prompt/Powershell/Windows Terminal> (Admin), and running wsl --install.

If that doesn't work, or you want to fiddle/customize/use a non-default distro, check out Microsoft's guide here. Make sure you install a WSL2 distro.

For the rest of this, I'm assuming you've installed the default Ubuntu Distro, steps might be slightly different for other distros.

Verify and Setup WSL

Make sure that the distro you just installed is a WSL2 distro, as you can't run docker in WSL1.

# Set the default version to 2
wsl --set-default-version 2
# Check that the distro you installed is version 2
wsl -l -v
# Upgrade a v1 distro to v2
wsl --set-version <distro-name> 2

If you're having trouble upgrading the distro, see here for help.

Now, open the "Ubuntu" application that you just got installed, and set your username and password. Do package updates, install whatever tools and packages you want, and just generally make yourself at home.

Install Docker

Follow these setup instructions (if you chose to install a distro other than Ubuntu, find the appropriate install guide on the left of that page).

Stop before running sudo docker run hello-world.

Configuring Docker on WSL2

Using Docker Without Invoking Root

Don't want to have to run docker commands with sudo all the time? Follow this guide to add yourself to the docker group.

Starting the Docker Daemon

One hiccup with docker in WSL2 is that it doesn't automatically start the Docker service. The simple but annoying solution is to run sudo service docker start whenever you want to use Docker.

If you don't want to have to remember and invoke that command every time, you can add the following to your "~/.profile", or your shell configuration file like "~/.bashrc":

if [ -n "`service docker status | grep not`" ]; then
    sudo /usr/sbin/service docker start
fi

Now this has the annoying side effect of making you have to type out your sudo password whenever you start WSL2 for the first time.

To fix this, you can run sudo visudo -f /etc/sudoers.d/passwordless_docker_start, add the following to the file (replacing username with your Linux username), save and close. (See here to learn more about the intricacies and nuances of sudoer files)

username        ALL = (root) NOPASSWD: /usr/sbin/service docker start

Now, the docker service automatically starts in WSL2 without requiring authentication, and you can use it more or less exactly like you would use Docker on a regular Linux install.

Cover Photo by Tom Fisk from Pexels.

How to Communicate with an Arduino from Docker

2021-03-14T00:00:00Z

Something I learned this weekend. Let's say you have an Arduino, and you want to communicate with it via serial from a Linux device, like a Jetson Nano. But not from that device's host operating system. No, that'd be too easy.

Instead, you want to talk with this Arduino from an application running in an unprivileged Docker container. How would you do that?

How To Bring an Arduino inside Docker

It turns out it's actually quite simple! When connected to a Linux device via a USB cable, most Arduino's show up as a device in the form /dev/ttyAMCx where x is replaced with an integer counter, starting from 0. So the first Arduino you connect is /dev/ttyAMC0, the second is /dev/ttyAMC1 and so on.

To access that from Docker, all you need is the docker --device flag. Include it in the docker run command as docker run <other options> --device="/dev/ttyACM0" <more options, image name, etc> and you're all set. You can access the Arduino in the container at /dev/ttyACMx just like you would on the host, say with the pyserial package in Python.

Words of Warning

Couple quick notes:

You need to have the device connected before you launch your docker container with that flag. Otherwise, you'll get an error.
You may run into issues if the device is disconnected and reconnected while the container is running.
Serial over wires (for instance, with jumper cables connecting pins on the arduino to GPIO on a Jetson or Raspberry Pi) rather than via the USB port will probably have a different device file handle, but will function the same way (pass the device file handle into the container with --devices.

⌨ MCK142Pro.ahk

2021-02-28T00:00:00Z

Project Link: https://gist.github.com/LuckierDodge/2ed678e035306d7f3cd935a40b3b0028

Description: An AutoHotKey script that I use to extend the functionality of an MCK142Pro programmable mechanical keyboard.

I wrote a whole post about this project! In short, I took a thrift store mechanical keyboard from the 90s and figured out how to make it a budget Stream Deck for the 2020s.

Extending an Old-school Programmable Keyboard with AutoHotKey

2021-02-23T00:00:00Z

So it Begins...

Our tale begins in December of 2020 with a message from my friend, roommate, and a notorious thrifter/dumpster diver extraordinaire, Jorge (name changed to protect the innocent) asking if I was interested in an old mechanical keyboard from the thrift store, still in the original packaging.
The message came with a picture of the front of the box, from which little information could be gleaned except the words "TWENTY-FOUR PROGRAMMABLE KEYS".
Like any good computer nerd, I said "Absolutely!".
So he picked up two, one for himself and one for me, for a crisp $3 USD each.

When he returned with his loot, I quickly set to figuring out what, exactly, we had on our hands.
These were brand-new in the box keyboards, and the box said MCK-142 Pro...and not much else.
Not even a manufacturer.
But a name's as good a place to start as any, and I turned to the internet and my search engine of choice to look for clues.

And that's where I found http://www.mck142.com/, a lovely little time capsule/memorial devoted to this keyboard specifically.
I encourage you to click through and appreciate this website for a moment (it doesn't take too long to read in its entirety, and it's such a lovingly crafted little webpage).

Getting to Know the MCK-142 Pro

For those of you who didn't click through, I'll give you a quick rundown of this keyboard's features

Satisfyingly Clicky Mechanical Switches
Two sets of Function Keys: the standard top row and a "Left-handed" column on the left side of the main keyboard
8-directional arrow keys (that's right, this thing can move the cursor diagonally with a single keypress)
Coiled PS2 cable
A Fast Repeat Key. According to the manual, this bumps the keyboard from a default of 10 Characters Per Second (CPS) when a key is held, to a crisp 20 CPS with the Fast Repeat Key.
24 Programmable Keys
8K (as in, Kilobytes) of Onboard CMOS SRAM Memory, maintained by a set of 4(!) AA batteries (not included, thankfully. Otherwise they'd be a corroded mess by now)
A floppy disk with software for programming the aformentioned Programmable Keys

Some of this functionality has been rendered obsolete by the passage of time, of course.
The "Fast Repeat" key, which would allow the user to more quickly enter the same key when holding it down, is superseded by the host operating system's settings on key repeats and associated delays these days.
The floppy disk with included software for programming may still be usable on some IBM PC's from the 90s, but I wasn't about to try and find out.

Notably, it does not feature a Windows Key, because it wasn't really intended for use with Windows NT-based computers, but PowerToys' key remapping utility solves that (in my case, I remapped the Caps Lock key, a key which I ONLY press accidentally).

The keyboard itself very much reminds me of the old Gateway family PC we had when I was growing up, with the same solid square body, weighty heft, and lightly textured beige ABS with gray accents.
I've never had too much nostalgia for that era of computing (I mostly remember that PC for being slow, noisy, and prone to crashes), but it's well-built, if nothing else.

Programming the Programmable Keyboard

Now, I had to figure out how to program this beauty.
At first, I was concerned that, without the software working (aka, without an IBM PC or some sort of emulator), I'd be unable to actually program the keyboard.
Not the end of the world, but disappointing to relinquish such unique functionality.

Thankfully, a detailed reading of the manual revealed that this was not the case!
In addition to the 24 Programmable Keys, the keyboard has a "Select" key and two LEDs: "Menu" and "Prog".
As it turns out, that key could be used to program each of the 24 keys, with the following steps (taken word for word out of the manual):

Press the SELECT Key twice within a second, the PROG LED indicator in YELLOW will turn on.
Press one PF Key, e.g. any one of PF1 to PF24, to start data entry.
Type strings or commands you want to save in any one of PF keys by using keyboard typewriter keys. The keystrokes of every PF key is limited within 320 keystrokes.
Press the SELECT Key once to save the data to the chosen PF Key, the PROG LED indicator in YELLOW will flash once.
Repeat the action from 2. to 4. for defining others or redefining any PF keys.
Press the SELECT Key one more time to complete data entry, the PROG LED indicator in YELLOW will turn off.

So, for instance, if I wanted to map the PF1 key to something like Ctrl+Shift+V, I could do that by:

Pressing SELECT twice, pressing PF1, typing Ctrl+Shift+V, pressing the SELECT key, and then pressing the SELECT key again to exit.

Now, the manual did forget to mention something: how to actually use the PF keys.
After programming one of the keys, I found that pressing it didn't actually do anything.
Perplexing.

With the quest teetering on the edge of disaster, I set out to find a solution.
After some experimentation, I discovered that I needed to press the SELECT key once to activate the PF keys. When I did that, the Menu LED lit up green and the PF keys would work.
Without it, no dice.
Moreover, this needed to be done anytime the computer was restarted or the keyboard was disconnected.
Easy enough, but strangely, not mentioned anywhere in the manual.
I can't help but think the software might automatically handle that functionality, but without it the keys have to be manually toggled.

Extending with AutoHotKey

Now at this point, I can program the keys to do essentially anything I can do on my keyboard (with 320 keystrokes, at least).
This includes both entering hotkeys and typing text (or a mix of both), which is neat, but I wanted to push it further.
After all, I could already use hotkeys by...pressing the hotkey.

Naturally, the first thing I did once I got programming working was program it to type The Tragedy of Darth Plagueis the Wise at the press of a button.
There are rules, after all.

But how to make this actually useful?
The use cases suggested by the keyboard were things like passwords, email signatures, and other text you have to repeat often.
But I've found that most of these scenarios have been solved by password managers, built-in email signatures, and other software approaches.
Plus programming passwords or other sensitive information into a keyboard really sets my security spider-senses atingling.

What I really wanted to do with this keyboard, was configure it such that I could essentially trigger an arbitrary action on my computer with each button.
And I wanted to be able to easily change what each PF key would do (typing out the whole Tragedy of Darth Plagueis takes awhile, after all).

Enter AutoHotKey

To do that, I turned to AutoHotKey, the self-proclaimed "ultimate automation scripting language for Windows".
It's a powerful tool, capable of a great many things, but for our purposes, it provides us with a way to create custom hot keys that can trigger a wide range of things: run one or more programs, manage which windows are open and active, type text, make decisions based on whats happening on the computer, and more.
Moreover, these hotkeys and outcomes are laid out in a script, which can be quickly modified and restarted to change the effect of a given hotkey.

One wrinkle quickly presents itself, however.
AutoHotKey works by intercepting values from the keyboard.
For instance, if I type Ctrl+Shift+J, and I have an AutoHotKey script with that hotkey programmed as a trigger, the corresponding actions will be run when Ctrl+Shift+J is detected.
But the PF keys aren't really keys, at least, not from the Operating System's perspective.
When a PF key is pressed, the only keys the computer sees are whatever strokes the key was programmed to type.
So I can't have an AutoHotKey script listen for the PF keys directly, I have to have it listen for a special hot key which I program into each PF key.

Since I don't want the AutoHotKey hooks to trigger when I press something other than a PF key, these can't be hotkeys I need to use regularly.
And I don't want the AutoHotKey functionality to mask actual functionality, either.

So I set out to find a set of 24 hotkeys not used anywhere else on my computer.
And I almost succeeded.
The closest I got was with the pattern Ctrl+Alt+Shift+Fx, where Fx corresponds to PFx, i.e. PF1:F1, PF2:F2, etc.
Now, you'll quickly realize there's a problem here: I have 24 programmable keys, but only 12 function keys.
Not to fear, as it turns out AutoHotKey can differentiate between left and right modifier keys! So I set the first 12 PF keys to use the left control key, and the last 12 to use the right control key.

Unfortunately, exactly one of these shortcuts (the F7 combo, I think) is actually already mapped to some obscure function of Nvidia's GeForce Experience software.
But since I had never used that functionality or key combo before in my life, I decided that was okay.
This specific pattern of hotkeys may not work for everyone, but it worked for my purposes.

Notably, this approach confers another advantage: even without this particular keyboard, I can still use my AutoHotKey setup, because they just correspond to (awkward, inconvenient) hotkeys.
The Programmable keyboard provides a simple, clean interface from which I can trigger whatever functionality I want with the press of a single button now.

The AutoHotKey Script

So what does the script look like, and what am I actually doing with it?
Here's a Gist of the full version, but I'll break it down below.

We start with some opening configuration, which are pretty much the defaults for a new AutoHotKey script:

#NoEnv  ; Recommended for performance and compatibility with future AutoHotkey releases.
; #Warn  ; Enable warnings to assist with detecting common errors.
SendMode Input  ; Recommended for new scripts due to its superior speed and reliability.
SetWorkingDir %A_ScriptDir%  ; Ensures a consistent starting directory.

Then, we add 24 of the following, slightly modified to match each PF key:

; PF1
<^!+F1::
Run, wt
return

The first line is a comment identifying the programmable key I'm creating a hotkey for (AutoHotKey uses semicolons for its comment character).
The second is declaring the hotkey, broken up as follows:

< indicates that we want the "left" version of the next modifier key
^ corresponds to the control key in AutoHotKey parlance.
! corresponds to the alt key
+ corresponds to the shift key
F1 corresponds to the first function key
:: indicates the end of our hotkey, with everything after it corresponding to what should happen after the hotkey is detected.

This brings us to the third line Run, wt which, as the name implies, runs a program.
In this case, its running the wt shortcut, which opens the Windows Terminal, but you could replace that with any shortcut name or path to an application.
Basically, it works the same as the Windows Run dialog accessed with Win+r.

But we're not limited to running just a single command. Consider,

; PF2
<^!+F2::
Run, outlook
Run, "C:\Users\Ryan Lewis\AppData\Local\Microsoft\Teams\Update.exe" --processStart "Teams.exe"
Run, "C:\Users\Ryan Lewis\AppData\Local\slack\slack.exe"
Run, "C:\Users\Ryan Lewis\AppData\Local\Discord\Update.exe" --processStart Discord.exe
return

which opens all of my various communications applications. I just switch to an empty virtual desktop, press PF2, and it opens Outlook, Teams, Slack, and Discord. With PowerToys' Fancy Zones, it even nicely positions them in the same grid pattern every time.

Last but not least, my proudest creation so far:

; PF3
<^!+F3::
WinHTTP := ComObjCreate("WinHTTP.WinHttpRequest.5.1")
WinHTTP.Open("GET", "https://wttr.in/12345?nFATQ")
WinHttp.Send()
response := WinHTTP.ResponseText
Gui, New,, Weather Report
Gui, Color, 111111
Gui, Font, s14 cWhite, Cascadia Mono
Gui, Add, Text,, % response
Gui, Show
return

Which sends an HTTP request to the wonderful wttr.in weather API, and displays the results in a helpful dialog.
I won't bore you with the details of how it works, but I think it's a simple example of some of the powerful potential here: anything I can hook up to an API endpoint, I can run with the press of a button.

Denouement

To summarize, I took an old programmable mechanical keyboard, combined it with the power of AutoHotKey, and found a needlessly complicated way to create a budget Stream Deck.
Compared to the $150 price tag for one of those, $3 and some elbow grease doesn't seem half bad.
And, more importantly, it was pretty fun to figure out!

I'm not done with this project just yet: I hope to find some more useful shortcuts to map, as well as integrating into my homelab/self hosting.
Once I get Home Assistant setup, for instance, it would be fun to hook up buttons to some automations.
Of course, I'll update the Gist as I go.

Got any suggestions, questions, or thoughts? What would you map these buttons to? Let me know! Otherwise, support open source projects, and be nice to each other out there!