Blog on Failing Productively

Get Rich or Die TTYing – Part 3: The Console Class

Sun, 14 Jun 2026 00:00:00 +0000

This is the third post in a series where I explore everything you can (and perhaps sometimes shouldn’t) do with Rich – a Python library for styling terminal output. Oh, and everyone’s favourite mid-2000s rapper is along for the ride. My last two posts covered blinging up the REPL and console markup.

Today’s post is all about the Console class — the foundation for all the really interesting things you can do with Rich.

“People judge you by appearances, the image you project through your actions, words, and style.

— 50 Cent, The 50th Law

Overview

Much like 50 Cent’s limited edition Xbox released alongside his third-person shooter 50 Cent: Bulletproof, the Console isn’t the main event, but it underpins all the fun and games you see on screen.

To do this, it detects the size and capabilities of the terminal it’s running in and generates the necessary ANSI escape sequences to style any output. Typically, there will only be a single instance of this class.

Your program’s output will be made up renderables in Rich’s terminology. A renderable is just that – something that can be rendered for display. It could be a string, a column, a table, a markdown block, a progress bar, or any other built-in renderable Rich provides. Moreover, renderables can be nested, meaning you can do things like put styled text and syntax-highlighted code blocks in a table. It’s the Console object’s job to work out how these components fit together and tell your terminal emulator what to display.

When is it worth using `Console`?

For one-off scripts and small programs, it may not be necessary to create a Console object – using Rich’s print() function + console markup will probably be enough. But, as soon as you need anything more complicated – drawing tables, creating progress bars, justifying text – or you just want to modify the behaviour of print(), you’ll need a Console object.

Since I’ll be taking you to the eye-candy shop in future posts, I’ll limit the rest of this discussion to a couple of quality-of-life improvements you get once you start using a Console object to handle your output.

Customising `print()`

As alluded to above, sometimes you’ll find overloading Python’s built-in print() function a little limiting. While it’s great that Rich provides a drop-in replacement with the same function signature, Rich’s print() doesn’t always behave the way you want it to.

For example, Rich will automatically highlight patterns in text like numbers, booleans and collections. Normally, this is really handy. Sometimes, though, it’s distracting. Take the following:

from rich import print

print('"In da club" by 50 Cent')

Which produces:

Both the quoted string and the number in 50’s name have been highlighted in different colours, which is not what we want. Of course, it’s possible to specify the output colour of this line using console markup, but it’s a hassle and you would have to repeat the process every time you invoke this rap icon’s name.

Instead, we can use the print() method on our Console object, which allows for customisation.

from rich.console import Console

console = Console()

console.print('"In da club" by 50 Cent', highlight=False)

Output:

In fact, we can go further and disable it globally with console = Console(highlight=False), so that it needs to be explicitly enabled when printing.

Exporting terminal output

The Console object is also capable of exporting everything it prints/logs as HTML and SVG, which is great for when you want to share fancy terminal output with your crew. To do so, your Console object first needs to be initialised with record=True. Then, before your program exits, call either save_html() or save_svg().

To demonstrate, I’ve put together a slightly more involved example. The script export_songs.py queries the Genius API and prints a page of results¹ as a table, before saving the output as an SVG.

 1import json
 2import os
 3import requests
 4
 5from rich.console import Console
 6from rich.table import Table
 7
 8
 9def format_featured(featured: list[dict]) -> str | None:
10    """Return all featured artists as a comma separated string"""
11    if featured:
12        artists = [artist.get("name") for artist in featured]
13        return ", ".join(artists)
14    return None
15
16
17def main() -> None:
18    console = Console(record=True, highlight=False)
19    token = os.environ["GENIUS_TOKEN"]
20
21    # '108' is 50 Cent's artist id on Genius
22    url = "https://api.genius.com/artists/108/songs?page=10"
23    headers = {"Authorization": f"Bearer {token}"}
24    console.log("Retrieving song info for [i]50 Cent[/]")
25    r = requests.get(url, headers=headers)
26
27    songs = json.loads(r.text).get("response").get("songs")
28    table = Table(title="$10 worth of tracks")
29    column_names = ["Title", "Primary artist", "Featured artist(s)", "Year"]
30
31    for name in column_names:
32        table.add_column(name)
33
34    for song in songs:
35        table.add_row(
36            song.get("title"),
37            song.get("primary_artist_names"),
38            format_featured(song.get("featured_artists")),
39            song.get("release_date_for_display"),
40        )
41
42    console.print(table)
43    console.save_svg("ten-dollar-tracks.svg", title="export_songs.py")
44
45
46if __name__ == "__main__":
47    main()

Here’s the result:

(The same script using save_html() produces this instead.)

As you can see, the output from both console.log() and console.print() (lines 24 and 42, respectively) made its way into the export. Also note that print() was passed a renderable – the table – instead of a plain old string.

If writing the blog series has taught me anything, it’s that generating high quality visuals of terminal output is surprisingly hard. Screenshots look terrible and dedicated tools like freeze and vhs still require quite a bit of tweaking. So I’m grateful Rich supports export to multiple formats out of the box.

Conclusion

To sum up, a Console object acts as canvas for your application and abstracts away the weird, low-level details of drawing stuff to the terminal. This gives you more space to think of ways to P.I.M.P. up your output with Rich’s renderables. It also gives you complete control of the output itself, which can then be captured/exported if desired.

For a more detailed look at everything the Console class can do, refer to the Console API documentation – it’s more comprehensive but unfortunately makes no reference to 50 Cent (or even G-Unit) at all.

I picked the tenth page arbitrarily. ↩︎

Get Rich or Die TTYing – Part 2: Console markup

Sat, 31 Jan 2026 00:00:00 +0000

This is the second instalment in a series exploring everything you can (and perhaps sometimes shouldn’t) do with Rich – a Python library for styling terminal output. Oh, and everyone’s favourite mid-2000s rapper is along for the ride. My last post covered the blinging up the REPL.

Today’s topic is Rich’s console markup.

So, taking inspiration from the words of Fiddy himself:

It ain’t my fault, I just reach for style
I’m hot, I breaks it down
It ain’t my fault, you can’t break it down
The way I break it down

— 50 Cent, God Gave Me Style

Overview

Rich uses a simple markup language for quickly annotating input passed to print(), log(), or anywhere else Rich accepts strings, e.g.:

from rich import print

print("[bold]G-Unit[/bold]")

The first set of square brackets contains the style (or styles) to be applied to all text until the closing set ([/bold] in this case).

Styled text can also be closed without specifying the style again, i.e. just with [/]. Further, you can omit the closing syntax entirely if you’d like the style to be applied until the end of the line. Therefore all of the following print statements produce the same output.

print("[underline]Get Rich or Die Tryin'[/underline]")
print("[underline]Get Rich or Die Tryin'[/]")
print("[underline]Get Rich or Die Tryin'")
# there's even a short name for this style
print("[u]Get Rich or Die Tryin'")

“Don’t care, didn’t ask,” I hear your atrophied attention span say.

I get it. We’d all rather be in da club, bottle full of bub’. But when you consider the alternative to the previous example relies on wrapping your string in ANSI escape sequences, i.e.

print("\x1b[4mGet Rich Die Tryin'\x1b[24m")

I think we can all agree Rich is a real timesaver for the modern hustler.

As an aside, I was interested to see that the markup language is loosely based on BBCode (“Bulletin Board Code”), since a similar markup language is also used by Spectre.Console, a dotnet package with close functionality to Rich.

Colour

Colour can be added to text in one of two ways:

Specifying one of the 256 named colours, either by name (magenta), or number (color(5))
Supplying a hex value, e.g. #bb2a25.

So,

print("[magenta]Go, shawty, it's your birthday[/]")
print("[color(6)]We gon' party like it's your birthday[/]")
print("[#e28cf8]We gon' sip Bacardí like it's your birthday[/]")

Produces:

It’s worth noting that the first 16 named colours, e.g. color(1)/red, are generally defined by a terminal’s colour scheme, rather than being an exact colour like #d70000. This is a good thing. With terminal-defined colours, although you lose precise control of the output, you know they’ll fit with the user’s theme and have reasonable contrast.

Styled text

Beyond colour, Rich can add styles like bold, underline and italics to your text. To illustrate, I’ve styled some heartfelt lines from 21 Questions.

Style	Result
`[bold]`/`[b]`
`[italic]`/`[i]`
`[dim]`/`[d]`
`[underline]`/`[u]`
`[underline2]`/`[uu]`
`[strike]`/`[s]`
`[reverse]`/`[r]`

The table above contains common styles supported by many – but not all – modern terminals like Ghostty, Kitty, WezTerm, Konsole and the like. On the left is the style (and abbreviated form); on the right is its corresponding output.

Weird stuff your terminal probably won’t support

Rich also allows for styles which are very seldom supported by modern terminals. I haven’t included images of output in this section, since all except [overline] are difficult to display.

[frame]: I have no idea what this is supposed to look like.
[encircle]: Same here.
[overline]: Like underline, but, you know, over.
[conceal]: Blanks out the text. Actually, this one is quite widely supported. I just don’t know why you would use it instead of, say, not printing.
[blink]: A slow blink (under 150 times per minute).
[blink2]: A fast blink (more than 150 times per minute). Of the handful of terminals I experimented with, only WezTerm supported both kinds of blinks.

Combining styles

Styles can be combined and nested within each other. To demonstrate,

print("[underline green on white]God give me style, God give me grace[/]")
print("[italic magenta]God put a [yellow]smile[/] on my face[/]")

Becomes:

Remember: blue, white and magenta are part of the 16 colours defined by your terminal’s theme (here, Rosé Pine Moon), so the snippet above will probably look different if you run it yourself.

Emoji

Emoji can be referred to via their name surrounded by colons:

print(":heavy_dollar_sign: :heavy_division_sign: :two:")

# is the equivalent of
print("💲 ➗ 2⃣")

For a complete list of available emoji names + examples, run python -m rich.emoji in your terminal.

Links

Lastly, you can add interactive links to your output too.

url = "https://web.archive.org/web/20060116005724/http://www.50cent.com/"
print(f"Here's 50's [link={url}]website back in 2006.[/]")

The caveat here is, again, as long as your terminal supports them.

There’s no real standard around how they’ll be displayed either. Some terminals will underline them. Some won’t. Others will only underline them on hover. Typically, you will need to Ctrl+Click to follow them too.

Conclusion

That’s a (w)rap! I encourage you to start adding some console markup to your scripts, new or existing. With minimal effort, you can add some swag to your print() and log() statements and generally make the terminal a more interesting place. Just don’t overdo it (or do!), and keep in mind that not all terminals are created equal.

Get Rich or Die TTYing – Part 1: The REPL

Fri, 09 Jan 2026 00:00:00 +0000

This is the first post in a series where I explore everything you can (and perhaps sometimes shouldn’t) do with Rich – a Python library for styling terminal output. Oh, and everyone’s favourite mid-2000s rapper is along for the ride.

Today’s post focuses on the REPL.

“Go ahead, switch the style up.”

— 50 Cent, In da Club

Rich offers a number of quality of life improvements for Python’s interactive interpreter, or REPL. Namely, pretty printed – and stylable – output, along with a helpful tool for inspecting objects.

Syntax highlighted data structures

While Python 3.14 introduced syntax highlighting in the REPL, this only applies to input – output remains unstyled.

The rich.pretty class can be used prettify output by invoking the install() method. For example:

There should have been a video here but your browser does not seem to support it.

IPython users can skip the pretty import and install() invocation and run the following command instead.

In [1]: %load_ext rich

Note that the styling provided by rich.pretty doesn’t apply to print() calls. For this you need rich.print.

Pretty printing

Rich can overload Python’s native print() function with its own. Not only does this allow you to pretty print syntax-aware objects, you can also use Rich’s console markup to add colour, bold, italics, emoji and more to your print statements.

I’ll be covering console markup in depth in a future post, but for now I’ll leave you with this tasteful example.

There should have been a video here but your browser does not seem to support it.

Nicely formatted object inspection

The inspect() function prints a tidy summary of an object to the console. It’s useful for getting a quick overview of an object’s attributes (and methods, if needed).

Say you’re debugging and want to know more about gunit, an instance of the GUnit class. After importing inspect, a simple inspect(gunit, methods=True) should give you enough info to get started.

There should have been a video here but your browser does not seem to support it.

Like My Style?

If any of this bling appeals, I’d suggest adding Rich as a dev dependency to each of your projects.

uv add --dev rich

Then to ensure Rich is always imported in the REPL, create a ~/.startup.py file, e.g.:

from rich import pretty, print, inspect

pretty.install()

And point your PYTHONSTARTUP environment variable at it.

# in Bash
export PYTHONSTARTUP="$HOME/.startup.py"

# in Fish
set PYTHONSTARTUP "$HOME/.startup.py"

Conclusion

Hopefully this overview of Rich in the REPL has sparked your cursiosity and got you asking 21 Questions about what else the library can do. In future posts I’ll be exploring other features of Rich like logging, tables, live display, markdown and more. Until then, I’ll leave you Patiently Waiting.

Miryoku layout on the Glove80

Wed, 31 Dec 2025 00:00:00 +0000

I’ve been using the Glove80 as a daily driver in my home office for the past 8 months. It’s a fantastic board and very, very comfortable. When I received it, I toyed with the idea of learning a new layout and making use of all the extra keys, but thought better of it, since I still regularly use 36-key boards when going into the office/travelling.

Instead, I went with the tried and true Miryoku layout.

Physical layout

Overall, the keys used by the Miryoku layout on the Glove80 are sensible. Of course, 46 of them go to waste, but that’s unavoidable.

My one complaint is that the innermost thumb key is slightly too much of a stretch.

To get around this, I shifted the two innermost thumb cluster keys outwards and moved the outermost thumb key to the top row.

The resulting triangular cluster is much more comfortable.

I achieved this by making a small change to miryoku/mapping/80/glove80.h (you can see the thumb clusters in the centre of the bottom two lines), which leads me on to the next section…

#define MIRYOKU_LAYOUTMAPPING_GLOVE80( \
     K00, K01, K02, K03, K04,                                    K05, K06, K07, K08, K09, \
     K10, K11, K12, K13, K14,                                    K15, K16, K17, K18, K19, \
     K20, K21, K22, K23, K24,                                    K25, K26, K27, K28, K29, \
     N30, N31, K32, K33, K34,                                    K35, K36, K37, N38, N39 \
) \
XXX  XXX  XXX  XXX  XXX                                               XXX  XXX  XXX  XXX  XXX \
XXX  XXX  XXX  XXX  XXX  XXX                                     XXX  XXX  XXX  XXX  XXX  XXX \
XXX  K00  K01  K02  K03  K04                                     K05  K06  K07  K08  K09  XXX \
XXX  K10  K11  K12  K13  K14                                     K15  K16  K17  K18  K19  XXX \
XXX  K20  K21  K22  K23  K24  K32  XXX  XXX       XXX  XXX  K37  K25  K26  K27  K28  K29  XXX \
XXX  XXX  XXX  XXX  XXX       K33  K34  XXX       XXX  K35  K36       XXX  XXX  XXX  XXX  XXX

Building the firmware

Since the Glove80 is one of the Miryoku project’s supported keyboards, building the firmware is simple:

Fork the manna-harbour/miryoku_zmk repo.
Make any customisations necessary, like altering the layout file above. (Optional)
Build via the ‘Build Inputs’ workflow in the GitHub Actions tab. Because the Glove80 is a split board, you need to use the name glove80_lh,glove80_rh as the ‘board’ name to produce a firmware file for each half. I also specify some additional configuration in the ‘kconfig’ field (see below).

Important variables to set

CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_BASIC=y: disables some consumer keycodes, but improves OS compatibility. Useful when connecting the board to macOS/iOS/iPadOS.
CONFIG_ZMK_POINTING=y: enables mouse emulation.
CONFIG_ZMK_SLEEP=y: allows the board to go into a deep sleep state during periods of inactivity. Without enabling this, battery life is extremely short (no more than a day).

Each variable needs to be separated by a newline character, e.g. CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_BASIC=y\nCONFIG_ZMK_POINTING=y\nCONFIG_ZMK_SLEEP=y.

Preventing GitHub from disabling my scheduled certificate renewal workflow

Sun, 02 Mar 2025 00:00:00 +0000

Intro

In January, I set up a GitHub Actions workflow to renew the certificate on assets.michaelhoward.kiwi, the subdomain I use for object storage. Each month, the workflow uses David Coles’ acme-linode-objectstorage tool to request a new TLS certificate and handle the resulting ACME challenge.

The problem

It was all working suspiciously smoothly¹ until I received an email from GitHub saying the scheduled workflow was about to be disabled.

I was confused. What’s the point of scheduling a workflow that requires routine intervention?

It turns out this is intended behaviour (for public repositories, at least). As noted in the docs (emphasis mine):

To prevent unnecessary workflow runs, scheduled workflows may be disabled automatically. When a public repository is forked, scheduled workflows are disabled by default. In a public repository, scheduled workflows are automatically disabled when no repository activity has occurred in 60 days.

I’m not a fan of this, since manually re-enabling the workflow every 60 days largely defeats the purpose of the automation. Ideally, I’d be able to disable this behaviour, but alas.

Instead, I had two options:

Set up more automation to make regular dummy commits to the repo
Make the repo private

The solution

For the sake of simplicity, I opted for the latter. The repository’s visibility is now set to private, which is a shame because I’m sure there’s someone out there who’d want to do something similar.

While I understand GitHub doesn’t want the headache of millions of workflows in abandoned repos running indefinitely, it would be nice to set up personal automation like this and still keep it public.

In future, I’ll have to make sure that all of my scheduled workflows are in private repositories.

The workflow

For posterity, I’m including the workflow file at the end of this post.

For the action to run, BUCKET_NAME must be set to the custom domain used for the bucket, e.g. assets.michaelhoward.kiwi.

Additionally, two secrets need to be added to the repository:

ACCOUNT_KEY: a Let’s Encrypt account key generated locally with openssl genrsa 4096.
LINODE_TOKEN: a Linode API key with the object storage read/write permissions.

Note that it’s also possible to trigger the workflow manually through either GitHub’s web interface or command line client.

name: Renew certificate for Linode Object Storage

on:
  schedule:
    - cron: '0 0 1 * *'
  workflow_dispatch:


jobs:
  renew_cert:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          repository: dcoles/acme-linode-objectstorage
      - uses: actions/setup-python@v5
        with:
          python-version: '3.13'
      - name: Install Python deps and run cert update tool
        run: |
          echo -e "$ACCOUNT_KEY" > ./account_key.pem
          pip install -r requirements.txt
          python -m acme_linode_objectstorage -k ./account_key.pem --agree-to-terms-of-service "$BUCKET_NAME"
        env:
          BUCKET_NAME: ${{ vars.BUCKET_NAME }}
          LINODE_TOKEN: ${{ secrets.LINODE_TOKEN }}
          ACCOUNT_KEY: ${{ secrets.ACCOUNT_KEY }}

Certainly much more smoothly than waiting for a periodic email from Let’s Encrypt telling me the certificate was about to expire and then manually completing the ACME challenge to renew it. ↩︎

Cycling through command arguments with PowerShell

Wed, 08 Jan 2025 00:00:00 +0000

With the holiday season behind us, I’m sure we’re all sick of navigating arguments. However, I couldn’t resist sharing this neat PowerShell trick I learnt at the end of last year.

PowerShell uses PSReadLine to handle keyboard input. One excellent feature of PSReadLine is the SelectCommandArgument key handler. This selects the next argument on the command line and by default is bound to Alt+A.

I’ve never seen anything like this implemented in another shell (e.g. via GNU Readline or Reedline), but it’s super useful when running several long – but similar – commands in a row.

Here’s a quick example of SelectCommandArgument in action.

There should have been a video here but your browser does not seem to support it.

Extracting and de-minifying JavaScript from the Boox Mira AppImage

Sun, 05 Mar 2023 00:00:00 +0000

Boox have written an Electron app for controlling their Boox Mira and Boox Mira Pro displays. As mentioned in a previous post, I’m not a huge fan and have been working on reproducing its behaviour in a simple Python script - miractl.

Both miractl and its inspiration mira-js are made possible because the JavaScript from the manufacturer’s app can be extracted and inspected. What follows is a quick summary of how to do the same for yourself.

Getting the Boox Mira app

First, download the AppImage via Boox’s website.

wget https://static.send2boox.com/monitor-pc/linux/Mira-latest.AppImage

Then make it executable.

chmod +x ./Mira-latest.AppImage

Extracting content from the AppImage

Before continuing, it’s probably worth creating a directory to keep all the extracted files. Once created, move the AppImage inside and use this as your working directory for the ./Mira-latest.AppImage --appimage-extract command.

mkdir ~/boox-mira
mv Mira-latest.AppImage ~/boox-mira
cd ~/boox-mira && ./Mira-latest.AppImage --appimage-extract

This will create the folder ~/boox-mira/squashfs-root. Inside the resources folder is an archive file called app.asar, which contains the concatenated, minified source files for the app.

Getting to the JavaScript

Install asar.

npm install asar -g

Again, it’ll keep things tidier if you create a destination folder before extracting the contents of app.asar.

mkdir ~/boox-mira/app

Then extract the file into your newly created directory.

asar extract squashfs-root/resources/app.asar app/

Almost there! All that remains is de-minifying the JS to make it readable for mere mortals.

De-minifying

Inside app/js is the minified JS and its source map - app.5a0cfb40.js.map.

I used a tool (creatively) called source-map-unpack, but there are multiple ways of unpacking source maps.

npm install source-map-unpack -g
unpack unpacked app/js/app.5a0cfb40.js.map

This creates a folder called unpacked in your working directory and unpacks the JS there. And that’s it!

Your sweet JS prize awaits in unpacked/src.

Stopping Terry Pratchett sneaking into my HTTP headers

Sun, 26 Feb 2023 00:00:00 +0000

The other day I was testing whether curl was installed on my work machine, so I made a simple request to my site.

$ curl https://michaelhoward.kiwi

To my surprise, the late and prolific author of the Discworld series popped up in the response.

<!DOCTYPE html>
<html lang="en-NZ">
<head>
  <meta name="generator" content="Hugo 0.106.0">
  <meta http-equiv="X-Clacks-Overhead" content="GNU Terry Pratchett" />
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <link rel="shortcut icon" href="https://michaelhoward.kiwi/images/favicon.png" />
  <title>Failing Productively</title>
  <meta name="title" content="Failing Productively" />
  <meta name="description" content="Fail. Learn. Repeat. A personal blog by Michael Howard." />

(Just to be clear, I mean Terry Pratchett. At the time of writing I am neither dead nor the author of any Discworld novels.)

Not knowing what X-Clacks-Overhead meant, nor what Terry Pratchett had to do with them, I began sleuthing.

Where did he come from?

This blog uses the Hugo Bear theme, so that was an obvious place to look. A quick grep of the repo later and I’d found the culprit in hugo-bearblog/layouts/_default/baseof.html.

However, the Hugo Bear theme is actually just a port of the theme used by the minimalist blogging platform Bear Blog. I guessed (rightly) that the first mention of Mr Pratchett would be there.

Still, knowing that my theme had inherited a cryptic message about a fantasy author didn’t help explain what the message meant.

Why was he there in the first place?

At last, the interesting bit! It turns out that following the death of Pratchett in 2015, the idea was floated on Reddit of giving him a lasting internet tribute inspired by his novel Going Postal.

The book describes an internet-like semaphore system called the Clacks. On losing a son, one of the characters keeps his boy’s name alive by sending it back and forth along the network in perpetuity. The protocol used by the Clacks allows you to specify what should be done with a message, similar to HTTP headers. Hence the ‘GNU’ in ‘GNU Terry Pratchett’ represents a fictional set of instructions for infinite transmission.

G: send the message on
N: do not log the message
U: turn the message around at the end of the line and send it back again

By getting people to insert the X-Clacks-Overhead message into their headers, Pratchett’s name could be memorialised on the modern internet in a similar way.

The idea caught on based the subsequent GNU Terry Pratchett website, and there are lots of ways of sticking the author’s name in your HTTP responses besides a blog theme – modifying your Nginx/Apache config, JavaScript etc.

Touching as this tribute is, I don’t think Pratchett’s name is in any danger of dying out – certainly not while his 41 Discworld novels are still in publication. And I think it’s a bit of a strange thing to keep in my blog’s theme, now that I know it’s there.

A quick fix

No prizes for guessing how to fix this one. Simply deleting the line in baseof.html did the job. I also took this as an opportunity to fork the theme and make a couple of minor changes.

Saturn60 keyboard build log

Thu, 19 Jan 2023 00:00:00 +0000

I’ve been building mechanical keyboards since 2020. And even though the number of weird and wonderful boards I’ve made is now in the double digits, I haven’t documented the process very well.

So, for my latest build – the 70s-inspired Saturn60 – the I decided to take some nice pictures and timelapses along the way.

Intro

I joined the group buy for the Saturn60 in October of 2020(!) and received it at the end of 2021. And if that wait wasn’t long enough, I dithered for most of 2022 working out what switches and keycaps I wanted to use. Eventually I plucked up the courage to build the thing after Christmas.

While I initially thought I would opt for a standard layout, I decided that nowadays I wouldn’t get much use out of the board unless it was ortholinear. Fortunately, the Saturn60 also accommodates a Boardwalk PCB and the runner of the group buy still had some matching plates in stock, well after the GB had finished.

Assembly

Building the Saturn60 is straightforward for the most part, but with a couple of fiddly/infuriating steps along the way. Fortunately, there is an excellent build guide.

I started by mounting my switches¹ onto their plate. Click to see the full timelapse in non-potato quality!

Following this, I soldered the switches to the PCB. As before, click for an equally boring, but much higher definition timelapse.

Next came the annoying part – sandwiching the plate/PCB in between the two halves of the case and screwing it all together. It sounds simple, but it’s fiendishly easy for the plate/PCB to get slightly wonky during this step. Once misaligned, not only will your keys look slightly off,² but you risk not having enough clearance between them and the case, causing some of the keys to scrape.

Still, it wasn’t too bad in the end.

Until I realised I made a terrible mistake – I’d forgotten to attach the serial number plate on the back of the case. As you need access to both sides of the back case to attach this plate, I was forced to take the whole keyboard apart.

(No doubt you can feel the rage emanating from this photo.)

But I got done. Again.

Keycaps

Adorning the assembled board is a set of SA SAIL keycaps. The set is based on a keyboard used in the Stanford Artificial Intelligence Lab in the early 70s. Everything about these keycaps is perfect. The colour, the mathematical symbols on the legends, the profile – everything.

The original SAIL keyboard. Image credit: Marcin Wichary, CC BY 2.0

For the past 18 months or so I’ve been trying to hunt down a set secondhand and finally lucked out. MyKeyboard.eu had some (new!) sets available and I couldn’t resist.³ Honestly, I’m not even sure how they ended up with these in stock. Not that I’m complaining, of course.

Details

Closing thoughts

I had a blast building this keyboard and am really happy with the result. It may have taken a few years, but the outcome more than justifies the wait!

Boba U4T 68g. ↩︎
Well, look slightly off to you. No one else would ever notice. ↩︎
Even the €40 shipping fee from Belgium couldn’t dissuade me. ↩︎

Logitech MX Master tweaks for an e-ink setup

Sun, 27 Nov 2022 00:00:00 +0000

While I prefer to use the keyboard where possible, I often find myself falling back on a mouse when browsing the web and reading articles/documentation. My mouse is an MX Master 3 which I love. However, one of it big drawcards – its buttery smooth scrollwheel – isn’t as useful with e-ink displays. Sure, you can scroll quickly, and your display will do its best to keep up, but it doesn’t look smooth and creates a lot of ghosting.

On the other hand, another great feature of the mouse is its reprogrammability. All of its additional buttons can be remapped¹. This makes it simple to replace scrolling with paging – Forward and Back become Page Up and Page Down.

Remapping the buttons is made possible on Linux with the logiops userspace driver. With this tool, you can customise the behaviour of Logitech [devices] using a (reasonably) straightforward config file.

In addition to mapping the Forward/Back buttons to Page Up/Page Down, I also set the thumb button to Alt+Shift+R – a shortcut I use to manually refresh my e-ink displays (a topic covered previously).

I did run into a small problem in writing my config though. Although the example in the repo sets the name as “Wireless Mouse MX Master”, my device didn’t like being called that, and refused to play ball until I changed the name to “Wireless Mouse MX Master 3”. Apart from that, and the squinting over braces and parentheses, setup was painless.

My /etc/logid.cfg can be found below.

devices: (
{
    name: "Wireless Mouse MX Master 3";

    smartshift:
    {
        on: true;
        threshold: 30;
    };

    hiresscroll:
    {
        hires: true;
        invert: false;
        target: false;
    };

    dpi: 1500;

    buttons: (
        // 'Forward' button
        {
            cid: 0x56;
            action =
            {
                type: "Keypress";
                keys: ["KEY_PAGEUP"];
            };
        },
        // 'Back' button
        {
            cid: 0x53;
            action =
            {
                type: "Keypress";
                keys: ["KEY_PAGEDOWN"];
            };
        },
        // Thumb button
        {
            cid: 0xc3;
            action = 
            {
                type: "Keypress";
                keys: [ "KEY_LEFTALT", "KEY_LEFTSHIFT", "KEY_R" ];
            };
        }
    );
}
);

What’s more, these can combined with mouse movements to create ‘gestures’. ↩︎

YubiKey CLI setup with ykman

Sun, 13 Nov 2022 00:00:00 +0000

I spent yesterday afternoon setting up a pair of YubiKeys – a primary key and a spare. Although I had to link them with a couple of dozen accounts, the process was surprisingly painless. Mostly thanks to their great CLI tool yubikey-manager.

Below are some notes on the process, mainly for my own reference. Even though setup is relatively simple, I find the acronym salad of two-factor hardware tokens overwhelming at the best of times, so this is also to remind myself that it isn’t rocket science.

Installation

On Debian/Ubuntu systems, the package can be found under the name yubikey-manager (though the ykman command is used to call the application).

sudo apt install yubikey-manager

You will also need the PC/SC Smart Card Daemon pcscd. In my case, this was already installed but the service needed to be enabled.

sudo systemctl enable pcscd.service

sudo systemctl start pcscd.service

Setting a FIDO pin

Set a pin with the following command.

ykman fido access change-pin

This is seldom used, but some services require one to be set. Make sure you use the same pin on your primary key and your backup.

Configuring TOTP slots

While many sites support WebAuthn (i.e. the fancy standard that lets your browser talk directly to the key), 6–8 digit, time-based one time passwords (TOTP) are more common.

To set these up, you need a secret provided by the site you’re logging into. Often, these are given in the form of a QR code, but an alphanumeric string or URI will also be available. URIs look something like this:

otpauth://...

The format for adding an account via a secret is ykman oath accounts add [OPTIONS] <name> <secret>. For example:

ykman oath accounts add geocities JBSWY3DPEHPK3PXP

However, if using a URI, add is replaced by uri and the name field is omitted:

ykman oath accounts uri otpauth://totp/Yahoo:michael@geocities.com?secret=JBSWY3DPEHPK3PXP&issuer=Yahoo

Important: Your backup key needs the same secret as your primary one. After adding the account to your primary key, remove the device and plug in the backup key. Then run the same command again.

Listing current TOTP slots

You can see a list of accounts you have set up TOTP authentication for with ykman oath accounts list.

$ ykman oath accounts list
geocities
ask-jeeves
alta-vista
napster
myspace

Generating TOTP codes

Codes can be generated with ykman oath accounts code <name>.

I found this a bit clunky, so I wrote a short Bash function which runs the command and copies the resulting code to the clipboard.

function yktotp () {
    ykman oath accounts code $1 | awk '{printf $NF}' | xclip -selection clipboard
}

The function is aliased to 2fa to help me remember. This lets me get TOTP codes with a simple 2fa <name>.

Refreshing multiple e-ink displays on Linux using Python

Mon, 07 Nov 2022 00:00:00 +0000

At my desk at home, I have a pair of e-ink displays – a Dasung Paperlike 253 and a Boox Mira 13.3".

In a previous post I covered a how I refresh these on the Windows machine I use for work. While a bit of a hack, it works in a pinch.

When using my own laptop, on the other hand, I have much greater freedom. A pair of Python scripts allow me to control either or both of the monitors.

Boox Mira

Boox have written their own Electron app for controlling Boox Mira and Boox Mira Pro displays. It’s hot garbage.

Fortunately, a simpler, less bloated alternative exists. ipodnerd3019 had the bright idea of inspecting the Javascript used by the app to send opcodes to the device. They then turned this into a neat CLI Javascript utility – mira-js.

Not being big on JS, I decided to reimplement some of this functionality in Python using pyusb. For now it’s just a couple of scripts: one for refreshing the display, the other for turning off the frontlight. I’ve created a repo, which I’ll be adding to when I get the time.

Dasung Paperlike 253

While communicating with the Paperlike is slightly more involved, the work had already been done for me. Philip Metzler has written a great Python script, which makes use of pyserial to control the monitor.

Unfortunately, getting the script to run for the first time was a learning experience, to say the least.

The script needs the monitor’s device file. Something like /dev/ttyUSB*, e.g.:

python ./dasung253.py --port /dev/ttyUSB0 --clear

Although I quickly identified the monitor could be found at /dev/ttyUSB0 when connected via USB, it would disconnect shortly after. Running sudo dmesg | grep tty confirmed this.

[ 2553.808793] usb 1-1.4.1: ch341-uart converter now attached to ttyUSB0
[ 2556.138673] ch341-uart ttyUSB0: ch341-uart converter now disconnected from ttyUSB0

After some very confused googling, I discovered the package brltty was interfering. Although it’s a package for driving refreshable braille displays, the daemon it runs in the background was (mis)identifying the Paperlike from the CH340 serial converter chip it uses. Based on this thread, it appears the CH340 is used by a specific Braille eReader and brltty therefore has conflicting udev rules for this device.

To solve this I had two options:

Remove the package completely with a simple sudo apt remove brltty.
Change the udev rules.

Since I’m not planning on using any braille screens anytime soon, I opted for the former.

As a final hurdle, I also hit a permissions error trying to access /dev/ttyUSB0. To access this device my user had to be added to the dialout group: sudo adduser cyclist dialout.

However, once I’d done that and rebooted, the script worked like a charm!

Bringing it all together

To refresh both displays (near) simultaneously. I call them both with a Bash script.

#!/usr/bin/env bash

/home/cyclist/scripts/mira-refresh.py
python /home/cyclist/scripts/dasung253.py --port /dev/ttyUSB0 --clear

I then bind this to a shortcut in Gnome Settings: Settings > Keyboard > Keyboard Shortcuts > View and customise shortcuts. I’ve chosen to bind this to Shift+Alt+R (for refresh)

Calling the scripts individually

There are also times where I only want to refresh one of the displays. After all, I generally don’t have the same windows open on both screens and therefore I may only want to clear ghosting/sharpen the image on one of them.

For this, I’ve used the same technique as above, but this time each shortcut calls its respective refresh script.

Paperlike 253 = Shift+Alt+P
Boox Mira = Shift+Alt+B

Notice that I’ve used the initial letter from each monitor’s name to help me remember the shortcut.

Conveniently, because I use the Miryoku layout on all my keyboards, P and B are right next to each other. They’re also in the same configuration as my physical monitors – Paperlike on the left, Boox Mira on the right.

Conclusion

I’m pretty stoked at how simple it is to control these displays with just a few lines of Python! Having these shortcuts set up has made a world of difference in usability. Next up I’d like to expand what my scripts can do with the Boox Mira (i.e. controlling contrast, refresh rate, etc.) and making my Bash script a little smarter, so that it can handle when new monitors are plugged in/unplugged and the device files change.

Initial impressions – AirPods Max feat. a very stupid engraving

Sun, 16 Oct 2022 00:00:00 +0000

I recently made the somewhat frivolous decision to buy a pair of AirPods Max headphones. Frivolous, in that my decision was partly motivated by the fact you can customise them with an engraving.

The minimalist in me wanted something understated, like my initials. The anarchic hacker in me wanted a clever, nerdy joke. In the end, I compromised.

As you can see, instead of engraving a boring MH, I used the Unicode code points for the characters:

LATIN CAPITAL LETTER M U+004D
LATIN CAPITAL LETTER H U+0048

I’m expecting this to be extremely useful if I ever lose my headphones at a Unicode Technical Committee meeting. Or a linguistics conference.

Refreshing e-ink displays on Windows

Sun, 28 Aug 2022 00:00:00 +0000

One of the pain points with e-ink/e-paper displays is having to manually refresh the screen to clear ghosting. While e-ink monitors like the Boox Mira and Dasung Paperlike 253 all have a dedicated hardware refresh button, it’s inconvenient to have to reach for your monitor(s) all day. Although this problem is a relatively simple software fix, either by using a manufacturer’s (janky) client application, or by using scripts to communicate over serial, it becomes difficult when using locked-down Windows device like my work machine.

Fortunately, it’s possible to set up a pseudo-shortcut on Windows which approximates a refresh.

What does refreshing an e-ink display actually mean?

Since this isn’t a post on how e-ink/e-paper technology works, I’ll be brief.

Whenever you use an e-ink display ghosting occurs. This is where a faint outline of previously displayed text/images sticks around. After a while, the ectoplasm builds up and you’re left with an ugly, spectral mess. To clear this, you can briefly turn the display black and then redraw the contents of the screen.

Blanking your screen on Windows

By far, the easiest way to turn your display(s) black for split second is using an AutoHotkey script like this one. But in my case, I need a built-in Windows utility to do the same job.

As it turns out, the built-in screensaver is pretty good for this! Thanks to a helpful Superuser discussion I learnt the following command enables the screensaver (without locking the session).

cmd /c scrnsave.scr /s

Provided the current screensaver isn’t set to an image or bright colour, running this command is an effective way of turning all connected displays black. But the gotcha here is that you have to move the mouse or press a key to return to your work.

Usability wise, the real issue is not having a convenient shortcut. Having to switch to a console window every time you need to refresh the screen is about as annoying as pressing a button on the device.

Enter the pseudo-shortcut

At this point, I realised that I could bypass the console altogether by using the Run command window. Pressing Win + R opens the Run dialog which can be used to start the scrnsave.scr command.

Note that only the scrnsave.scr part of the command is necessary. Hitting Enter will then turn on the screensaver and hitting it again will disable it.

What’s more, the Run dialog remembers your last command. So if you’re like me and don’t use Run for much else, you’ll never need to retype the command after the first time. This means the shortcut Win + R Enter Enter is now always available.

While far from a perfect solution, I’ve been quite happy with this hack. It works well enough most of the time and has the added benefit of working with any e-ink display, regardless of manufacturer.

Dipping my toes into Nushell

Mon, 11 Apr 2022 00:00:00 +0000

Nushell came to my attention a couple of weeks back, following its 0.6 release and immediately piqued my interest. ‘What’s so nu about this shell?’ I thought.

Simply, Nushell is a Unix-style shell that works with structured data instead of raw text. In this way, it bears a lot of similarity with PowerShell, which I use heavily at my current job. Since I’m already used to working with an object-based shell for work, I thought it would be interesting to try one out on my personal machine.

To be honest, I don’t do much shell scripting for personal projects. Yes, it would make my life easier. Yes, being familiar enough with Bash/Fish/Zsh to pull out sick one-liners is cool. But I’m lazy and generally can’t convince myself it’s worth the effort.

Enter Nushell! Something cool enough to get me started, but familiar enough that it doesn’t feel like too much work to learn.

Starting slow, I decided to rewrite the small Fish function I mentioned in my last post. To recap, I wanted a function that takes a path to a local file, uploads that file to Linode object storage and then copies the resulting URL to the clipboard.

The original:

function send2obj
    linode-cli obj put --acl-public $argv michaelhoward
    set filename (basename $argv)
    echo -n "https://michaelhoward.ap-south-1.linodeobjects.com/$filename" | tee /dev/tty | xclip -selection clipboard

And in Nushell:

# A command to send a file to Linode object storage, copying the resulting URL to the clipboard
def send-to-object-storage [
    filepath # The local path of the file to upload, e.g. ~/images/screenshot.png
] {
    if ($filepath | path exists) {
        linode-cli obj put --acl-public $filepath michaelhoward
        echo $"https://michaelhoward.ap-south-1.linodeobjects.com/($filepath | path basename)" | tee /dev/tty | xclip -selection clipboard
    } else {
         echo "File not found. Please check the path is correct."
    }

}

## Aliases ##

alias s2o = send-to-object-storage

As you can see, I got a little carried away. But essentially it does the same thing. Just better.

On a practical level, it’s an improvement in that it checks the path to the file is valid before doing anything else. Though what I really prefer about the rewrite is the help message it displays.

I can now type send-to-object-storage --help or s2o -h to see the following.

A command to send a file to Linode object storage, copying the resulting URL to the clipboard

Usage:
  > send-to-object-storage <filepath> 

Flags:
  -h, --help
      Display this help message

Parameters:
  filepath: The local path of the file to upload, e.g. ~/images/screenshot.png

While this example doesn’t show off any of Nushell’s killer features, it was simple to put together and has me excited about experimenting further. Time to hit the docs!

How this blog works

Sat, 19 Feb 2022 00:00:00 +0000

Intro

As is customary for websites like this, the following post details how I run my blog.

There are three main components:

Hugo, a static site generator
Sourcehut Pages, a tool for hosting static sites
Linode Object Storage, S3-compatible object storage (used here for hosting images)

Hugo

Hugo is my go-to static site generator. It’s fast, intuitive and there are lots of great themes out there. I’ve used it for several sites now and I’m always amazed at just how quickly I can get something up and running.

For this blog, I decided to go with a barebones theme – Hugo Bear Blog. Bearbones, if you will.

Sourcehut Pages

The blog is hosted using Sourcehut Pages. Those of you who have used GitHub/GitLab Pages will be familiar with the idea – create a Git repo with all the files for your static site and it will be built and served automatically. Every time you make a commit (like adding a new post), the site will be rebuilt.

Linode Object Storage

While Sourcehut Pages is an excellent, straightforward way to host a blog, there is one downside – the repo can’t be larger than 1GB. Although this isn’t a huge problem, it does mean that it isn’t wise to keep lots of large images inside the repo.

To get around this restriction, I’ve chosen to host my full size images using Linode’s object storage¹. This gives me a massive 250GB for $5 USD per month. That’s overkill, of course, but does let me upload as many high quality photos of my projects as I like. No doubt I’ll find other uses for all this storage as time goes on.

Object storage is ideal for a couple of reasons. Firstly, I don’t need to set up an Nginx server (at which point I may as well be hosting my own blog). And secondly, it means I can use Linode’s CLI tool to upload my images.

Uploading an image is a single command.

linode-cli obj put --acl-public /path/to/image.png mybucketname

Once uploaded, the image can be found at a simply structured URL.

https://mybucketname.serverregion.linodeobjects.com/filename.png

So that I don’t have to remember this pattern each time, I wrote a Fish shell function to upload the image and send the resulting URL to the clipboard.

function send2obj
    linode-cli obj put --acl-public $argv michaelhoward
    set filename (basename $argv)
    echo -n "https://michaelhoward.ap-south-1.linodeobjects.com/$filename" | tee /dev/tty | xclip -selection clipboard

That way I can add unnecessary images to posts in seconds!

Conclusion

All in all, I’m really satisfied with the workflow for this blog. My goal was to keep things simple and completely manageable from within Emacs or a terminal. Something I think I’ve achieved tidily.

Now time to write some more posts!

In fact, if I wanted to, I could host my entire blog this way. Linode has a great guide on this. However, I like managing my site through a Git repo and enjoy the convenience of automatic builds. ↩︎

First Post

Sun, 12 Sep 2021 00:00:00 +0000

This blog’s first post (of many). I hope you stick around 😉

Blog on Failing Productively

Get Rich or Die TTYing – Part 3: The Console Class

Overview

When is it worth using Console?

Customising print()

Exporting terminal output

Conclusion

Get Rich or Die TTYing – Part 2: Console markup

Overview

Colour

Styled text

Weird stuff your terminal probably won’t support

Combining styles

Emoji

Links

Conclusion

Get Rich or Die TTYing – Part 1: The REPL

Syntax highlighted data structures

Pretty printing

Nicely formatted object inspection

Like My Style?

Conclusion

Miryoku layout on the Glove80

Physical layout

Building the firmware

Important variables to set

Preventing GitHub from disabling my scheduled certificate renewal workflow

Intro

The problem

The solution

The workflow

Cycling through command arguments with PowerShell

Extracting and de-minifying JavaScript from the Boox Mira AppImage

Getting the Boox Mira app

Extracting content from the AppImage

Getting to the JavaScript

De-minifying

Stopping Terry Pratchett sneaking into my HTTP headers

Where did he come from?

Why was he there in the first place?

A quick fix

Saturn60 keyboard build log

Intro

Assembly

Keycaps

Details

Closing thoughts

Logitech MX Master tweaks for an e-ink setup

YubiKey CLI setup with ykman

Installation

Setting a FIDO pin

Configuring TOTP slots

Listing current TOTP slots

Generating TOTP codes

Refreshing multiple e-ink displays on Linux using Python

Boox Mira

Dasung Paperlike 253

Bringing it all together

Calling the scripts individually

Conclusion

Initial impressions – AirPods Max feat. a very stupid engraving

Refreshing e-ink displays on Windows

What does refreshing an e-ink display actually mean?

Blanking your screen on Windows

Enter the pseudo-shortcut

Dipping my toes into Nushell

How this blog works

Intro

Hugo

Sourcehut Pages

Linode Object Storage

Conclusion

First Post

When is it worth using `Console`?

Customising `print()`