Transferring files over a serial connection

I had an internet connection that required a DSL modem to use, and so I looked at openwrt.org for their DSL compatible modems, and found the TP-Link TD-W8970 v1. After an extremely quick glance at top of the page, I saw that ADSL/VDSL works, and proceeded to purchase one since they were quite cheap.

Little did I know this router had a far greater obstacle than I expected…

• Transferring files over a serial connection
  • Flashing OpenWrt without opening the case
  • Unbricking the router
    • Alright! Now we have a shell again!
    • Transferring the new firmware over serial
      • The first problem
      • The second problem
      • The third problem

What I neglected to notice on the page for the TP-Link TD-W8970 v1 was how to install OpenWrt on the device. 😅

Turns out, it’s not as simple as other routers I’ve used in the past (you just download the upgrade package, and install it). Not all is bad though, this is what is listed in the Installation instructions:

There are two viable ways to install OpenWrt; the “classic” method using serial access, or the “web interface hack” which allows to flash the firmware without opening the case!

Well! That “web interface hack” sounds pretty good to me!

Flashing OpenWrt without opening the case

For what it’s worth, the process of flashing the device without opening the case is this:

1. First, download the 15.05 OpenWrt image for the router
2. Next, once you have a root shell via the StatPost approach, backup your router’s original firmware:

# Insert a USB or HDD into one of the USB ports of the router, it will be
# mounted at /var/usbdisk/*
cat /dev/mtd0 > /var/usbdisk/sda1/td-w8970/mtd0
cat /dev/mtd1 > /var/usbdisk/sda1/td-w8970/mtd1
cat /dev/mtd2 > /var/usbdisk/sda1/td-w8970/mtd2
cat /dev/mtd3 > /var/usbdisk/sda1/td-w8970/mtd3
cat /dev/mtd4 > /var/usbdisk/sda1/td-w8970/mtd4
cat /dev/mtd5 > /var/usbdisk/sda1/td-w8970/mtd5
cat /dev/mtd6 > /var/usbdisk/sda1/td-w8970/mtd6

3. Check the size of /dev/mtd1

# For my router, it's 1310720 bytes
ls -l /var/usbdisk/sda1/td-w8970/mtd1

4. Prepare the 15.05 OpenWrt image

# Split the install image into two parts. We do this since the image won't fit
# all into /dev/mtd1, and we will put the remaining into /dev/mtd2
dd if=openwrt-lantiq-xrx200-TDW8970-sysupgrade.image bs=1310720 skip=1 of=openwrt-lantiq-xrx200-TDW8970-sysupgrade-1.image

5. ⚠️ don’t be dumb like me ⚠️

This is the part I missed when reading the installation guide:

Rumours are that with the recent OpenWrt that you need to take care that the image you write to mtd2 needs to be extended with 0xff characters to the end of the partition

So, please don’t do what I did, and please ensure that you do this! 🙏

Get the length of mtd2:

# On my router, it's 6684672 bytes
ls -l /var/usbdisk/sda1/td-w8970/mtd2

And as the page suggests, let’s extend the image we’ll write to mtd2 with 0xff characters:

# Let's extend the second part that we created earlier
# First, we'll create a file full of 0xff bytes that's the right size
# (td uses octal, and 0xff in octal is \377)
dd if=/dev/zero bs=6684672 count=1 | tr "\000" "\377" > mtd2.image
# Now we insert the original file at the start of the image
# Note that `conv=notrunc` will make sure the file isn't truncated
dd if=openwrt-lantiq-xrx200-TDW8970-sysupgrade.image of=mtd2.image conv=notrunc
# And finally, we'll replace the original file with the padded one
mv mtd2.image openwrt-lantiq-xrx200-TDW8970-sysupgrade.image

6. Flash OpenWrt to the device

It’s crunch time. With the files we created on the computer, let’s move them to the USB device and proceed to flash the router.

cat /var/usbdisk/sda1/td-w8970/openwrt-lantiq-xrx200-TDW8970-sysupgrade.image > /dev/mtdblock1
cat /var/usbdisk/sda1/td-w8970/openwrt-lantiq-xrx200-TDW8970-sysupgrade-1.image > /dev/mtdblock2

It’s normal for the first cat command above to print:

cat: write error: No space left on device

since the original image is too large for mtd1. But that’s alright, since we write the remaining portion to mtd2.

Once you reboot (by power cycling the device) it should boot in OpenWrt!

…“should” being the key word there… as I mentioned above, I didn’t do these all correctly, and my device bricked. 🤦‍♂️

Unbricking the router

Sigh.

Alright, I guess I’m doing this the hard way since I missed that thing about padding the file and my router’s now bricked.

Looks like I need to get a USB to TTL Serial UART. I didn’t have one, so I purchased this one: https://core-electronics.com.au/usb-to-ttl-serial-uart-rs232-adaptor-pl2303hx.html

… a few days later …

Alright, here I am. Following the guide’s steps on connecting the adaptor to the TD-W8970 Serial interface. As noted in the guide, the ground pin was a little hard to get to, so I ended up using the alternative they suggested.

This was my result:

serial wires soldered onto router

serial wires soldered onto router (close up)

And yes, this was my first time soldering. And also yes, I did an awful job. But hey, the serial connection seems stable, and things are looking fine to me so far!

When I connect to the TTY (if you don’t know, OpenWrt has a good guide), I see this:

ROM VER: 1.1.4
CFG 01

ROM VER: 1.1.4
CFG 01

ROM VER: 1.1.4
CFG 01

... repeating endlessly forever ...

Hey! I’m actually receiving data that’s not completely corrupt - for a first time soldering, I’m just happy it seems to be working.

Well, the guide did mention that pressing t will interrupt the boot sequence, and apparently then I can login with admin/1234.

… presses t and waits …

Oh come on! Nothing’s happening. Was it my poor soldering?

Well, if it’s not my soldering, then I have to assume inputs are working… Though after mashing the keyboard, nothing seems to change, the characters I’m sending aren’t even printed to the TTY… So I’m not even sure.

In the guide there is a section on UART booting; looks like all we have to do is ground a resister called R255. Let’s try grounding that.

… an embarrassingly long amount of time later …

Alright, I swear I looked at every resister a hundred times and I couldn’t find the one mentioned on the page.

Don’t be thick like me. It’s on the bottom side of the board:

Underneath the Router

Location of R255

So grounding R255 before boot, during boot or after boot did… Nothing.

After a period of time that was far too long, I realised that those guides about pressing t, the admin/1234 login and grounding R255 are for the original router firmware. The original router firmware that I overwrote already with OpenWrt. So this isn’t TP-Link boot-looping, it’s OpenWrt!

After combing through some more OpenWrt forums, some archived, some for other routers, I figured out a way to get it out of it’s apparently bricked and boot-looping state:

As fast as you can after turning it on (you’ll see the ROM VER ... commands still printing) hit ctrl+C! This stops the boot process and drops me into a shell!

💪 Progress!

Alright! Now we have a shell again!

So we’ve got root access to a broken OpenWrt, let’s fix this router and unbrick it.

What tools do we have at our disposal?

• 🙁 The wireless doesn’t work and can’t be setup, or turned on
• 😟 The ethernet ports don’t work
• 😫 The USB ports don’t work
• 😩 The reset button doesn’t seem do anything
• 😢 In fact, this router doesn’t do anything except allow a serial connection, and print a bunch of errors about corrupted filesystems while it boots.

Well… Alright. I guess let’s just download the latest release of OpenWrt for the device, copy that onto it with the serial connection and then just sysupgrade from there. Easy, right?

No. Not so easy.

Apparently, copying binary files over a serial connection isn’t the simplest thing.

Especially when the device you’re copying to is a very bare-bones system.

Transferring the new firmware over serial

Let’s consider our constraints:

• No network access
• No USB access
• We only have ~29M of RAM on this device, mounted in /tmp
• The only way we can communicate is via our Serial UART interface
• We don’t have any tools for transferring data easily, in text format, or over serial connections installed on the router

Alright. Let’s do this the dumb way.

It may be dumb, but it’s simple, and it should work.

My plan is:

1. Download the latest (at this time 21.02.2) OpenWrt firmware for the device
2. Convert this file to ASCII (so it’s safe to send over the serial TTY)
3. Send the ASCII file over the serial connection
4. Rebuild the firmware file from its ASCII representation
5. Run sysupgrade openwrt.bin on the router and revive it

The first problem

The first thing I think of when converting a binary to ASCII is base64.

But, if the device doesn’t have base64, what options do we have?

I did find a base64 shell script but after some tests that thing totally died on files over a megabyte. The firmware image in its binary format is already 6.4M, and as base64 it’s over 9M. Sadly, this wasn’t an easy win.

With some more searching, I discovered someone had quite a similar issue to me, and solved it with lrzsz. Alas, I failed to find any lrzsz packages for the later versions of OpenWrt I was using, and even when I tried to use the older ones the router was missing the required libs to even run it. So, rather than transferring an entirely old OS over to the router one file at a time, I decided I’d take inspiration from this approach, but go down a slightly different route.

With that in mind, all I had to do was print every byte of the file in hexadecimal, and rebuild it later on. That’s easy enough:

# openwrt.bin is the new 21.02.2 image file
xxd -g1 openwrt.bin > openwrt.txt

# remove the prefix and suffix that `xxd` generates
sed -i 's/^\(.\)\{9\}//g' openwrt.txt
sed -i 's/\(.\)\{16\}$//g' openwrt.txt

Let’s test this can be converted back without xxd (since the router doesn’t have that):

# Rebuild it
for b in $(cat openwrt.txt); do printf "\x$b"; done > "openwrt_rebuilt.bin"

# Verify the hashes are the same
md5sum openwrt.bin openwrt_rebuilt.bin
# 38006b415517b27e9da650441e2edb89 openwrt.bin
# 38006b415517b27e9da650441e2edb89 openwrt_rebuilt.bin

Awesome! Moving on.

The second problem

How do we transmit the file over serial?

Remember I said it was the dumb way? Well now you can be the judge of that! Here’s a simple script to automate sending commands over the serial interface:

while read line || [[ $line ]]; do echo -e "echo \"$line\" >> openwrt.txt" > /dev/ttyUSB0; done < openwrt.txt

The read builtin in bash (by default) will read every line until the end of the file. If it encounters the end of the file it will return a non-zero exit code (which would end the loop in this case).

Each time it is called though it copies what it read into $line.

So, by adding || [[ $line ]] to our loop condition, if there was anything to read before EOF then it will be in $line and the loop block will be executed. And the next time read line is called there will be nothing to read, so read will be non-zero and also $line will be empty - so the loop will stop.

Whoa, hold on hold on! What’s happening in that serial console? Looks like a mess:

root@(none):/tmp# echo "d0 dd ab 00 b4 8a 09 20 4e 9d 61 81 8c 42 23 cc" >> openwrt.txt
o "4c be c6 c9 a7 7d 09 ec 51 0e 8f 0a a1 16 d2 0d" >> openwrt.txt
echo "39 2b ca 1e 72 8d a8 64 a6 a9 2a a4 d2 22 ae c8" >> openwrt.txt
echroot@(none):/tmp# echo "85 22 89 99 29 27 ae 6a 72 5c 42 0c e3 77 f6 26" >> openwrt.txt
root@(none):/tmp# echo "12 ac f0 77 ba bd 7a 7f 3e 36 3c a3 83 0b e8 7f" >> openwrt.txt
root@(none):/tmp# echo "ff af 4b 79 6a 92 44 4b 98 0e 57 82 bb ea 8e f7" >> openwrt.txt
root@(none):/tmp# echo "03 13 9d b5 08 a8 0e bf d0 5e 50 e1 08 fb bb 8c" >> openwrt.txt
... more lines of garbled output ...

Looks like we’re transmitting too fast - we’re sending the text for the next command before the previous has completed.

I played around with a few settings, and was able to get a stable speed of commands with sleep 0.005 in between each iteration:

while read line || [[ $line ]]; do echo -e "echo \"$line\" >> openwrt.txt" > /dev/ttyUSB0; sleep 0.005; done < openwrt.txt

Ahh, this looks much better:

root@(none):/tmp# echo "02 00 00 00 76 65 72 2e 20 31 2e 30 00 ff ff ff" >> openwrt.txt
root@(none):/tmp# echo "ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff" >> openwrt.txt
root@(none):/tmp# echo "ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff" >> openwrt.txt
root@(none):/tmp# echo "ff ff ff ff 89 70 00 01 00 00 00 01 00 00 00 00" >> openwrt.txt
root@(none):/tmp# echo "fe 9f 5e 8c 19 78 78 21 cc ee dc c5 fa a9 9b 75" >> openwrt.txt
root@(none):/tmp# echo "00 00 00 00 ff ff ff ff ff ff ff ff ff ff ff ff" >> openwrt.txt
root@(none):/tmp# echo "ff ff ff ff ff ff ff ff 80 00 20 00 80 00 20 00" >> openwrt.txt
root@(none):/tmp# echo "00 7a 00 00 00 00 02 00 00 25 d1 2c 00 25 d3 2c" >> openwrt.txt
root@(none):/tmp# echo "00 40 17 36 00 00 00 00 00 00 00 00 55 aa 01 00" >> openwrt.txt
root@(none):/tmp# echo "a5 00 00 00 ff ff ff ff ff ff ff ff ff ff ff ff" >> openwrt.txt
root@(none):/tmp# echo "ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff" >> openwrt.txt
root@(none):/tmp# echo "ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff" >> openwrt.txt
root@(none):/tmp# echo "ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff" >> openwrt.txt
root@(none):/tmp# echo "ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff" >> openwrt.txt
root@(none):/tmp# echo "ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff" >> openwrt.txt
... more lines ...

The third problem

The ASCII file we’ve generated sits just shy of 22M. Whenever I tried to rebuild it into its binary form, the router ran out of memory and was completely unusable until I either rebooted it, or deleted the openwrt.txt or openwrt.bin files.

We’re so close! I can feel it!

With a few tweaks, I whipped this up to split the file into smaller parts when we transmit it, and then rebuild it incrementally while cleaning up each part to save on memory:

# split ASCII file into 10 parts
split -n 10 openwrt.txt

# transfer the parts over serial (`date` is there to see overall timing and progress)
for f in x??; do echo $f $(date); while read line || [[ $line ]]; do echo -e "echo \"$line\" >> $f" > /dev/ttyUSB0; sleep 0.005; done < $f; done

This took around 10 minutes per file over my serial connection.

Excellent! So now we have xaa, xab, …, xaj on the router. Let’s rebuild them one by one:

# incrementally convert parts back to binary files, deleting them as we go
for f in x??; do echo $f; for b in $(cat $f); do printf "\x$b"; done > "${f}.bin"; rm $f; done;

# join binary files back together
cat x*.bin > openwrt.bin

# check that the file was transferred and rebuilt correctly
md5sum openwrt.bin
# 🎉 THE HASH MATCHES 🎉

# finally, upgrade the router
# `-v` is for verbose output
# optionally pass `-n` to start from a clean slate (all config files deleted)
sysupgrade -v openwrt.bin

Oh I am so ready for this to work now! Here we go:

root@(none):/tmp# sysupgrade -v -n ./openwrt.bin
killall: watchdog: no process killed
Sending TERM to remaining processes ... ubusd 
Sending KILL to remaining processes ... 
Switching to ramdisk...
Performing system upgrade...
Unlocking firmware ...

Writing from <stdin> to firmware ... [w]
Upgrade completed
Rebooting system...
[47068.832000] reboot: Re
ROM VER: 1.1.4
CFG 05

DDR autotuning Rev 1.0
DDR size from 0xa0000000 - 0xa3ffffff
DDR check ok... start booting...



U-Boot 2010.06-svn4806-LANTIQ-v-2.3.08 (Sep 18 2014 - 15:34:40)

CLOCK CPU 500M RAM 250M
DRAM:  64 MiB
Using default environment

In:    serial
Out:   serial
Err:   serial
Net:   Internal phy(GE) firmware version: 0x8434
vr9 Switch8192 KiB W25Q64 at 0:3 is now current device
MAC: c4-e9-84-b0-16-c4  


run "flash_flash" to bring up the kernel

Hit any key to stop autoboot:  0 
8192 KiB W25Q64 at 0:3 is now current device
8192 KiB W25Q64 at 0:3 is now current device
        Uncompressing ... 
Starting kernel ...

[    0.000000] Linux version 5.4.179 (builder@buildhost) (gcc version 8.4.0 (OpenWrt GCC 8.4.0 r16495-bf0c965af0
)) #0 SMP Wed Feb 16 20:29:10 2022

... more booting lines ...

OH YES.

OHHHH YESSSS. FINALLY. FANTASTIC.

After I let it boot, I hit <Enter> and this is the glory with which I’m presented:

BusyBox v1.33.2 (2022-02-16 20:29:10 UTC) built-in shell (ash)

  _______                     ________        __
 |       |.-----.-----.-----.|  |  |  |.----.|  |_
 |   -   ||  _  |  -__|     ||  |  |  ||   _||   _|
 |_______||   __|_____|__|__||________||__|  |____|
          |__| W I R E L E S S   F R E E D O M
 -----------------------------------------------------
 OpenWrt 21.02.2, r16495-bf0c965af0
 -----------------------------------------------------
=== WARNING! =====================================
There is no root password defined on this device!
Use the "passwd" command to set up a new password
in order to prevent unauthorized SSH logins.
--------------------------------------------------
root@OpenWrt:/#

What a journey.

The router is now unbricked, and has the latest OpenWrt installed. 🎉

Don’t be like me, read the whole guide before you even purchase a device! 😅

Running Diablo II Resurrected on Linux

Ahh… Fresh meat!

I had to do this twice and it bothered me to have to look a few things up again, so here it is for next time (if there is a next time, I reckon this will be fixed fairly soon in wine/proton/etc).

Please note

The following instructions are for Arch Linux, but they’ll be very similar for any other distribution.

Battle.net

Installing Battle.net on Linux is straightforward, I usually do it via Lutris:

Shell

$ pacman -S lutris

Once you’ve installed Lutris, install Battle.net as per its instructions.

Trouble logging in?

I found that I also had to install lib32-gnutls in order for the Battle.net login window to work properly. This package lives in the multilib repository, so make sure you’ve enabled that if you haven’t already.

Installing Diablo II Resurrected

Go ahead and install it the normal way from within Battle.net, by choosing the game and selecting “Install”.

If launching the game now crashes, ends up in a black screen or is otherwise terrible, then the fix for the issues I faced probably hasn’t been merged yet. If that’s the case, continue reading.

There’s a Pull Request here which details a fix for the initial crashes and rendering issues. To save you some time reading between the lines, here’s what you have to do.

Install a patched vkd3d-proton

Sometimes showing is easier than telling:

Shell

# Clone the fork that contains the fix
$ git clone [email protected]:K0bin/vkd3d-proton.git
$ cd vkd3d-proton
# Checkout the branch with the fix
$ git checkout disable-raster

# Build the package
$ ./package-release.sh master /tmp --no-package

# And, now install it into Lutris
$ cp /tmp/vkd3d-proton-master/x64/d3d12.dll ~/.local/share/lutris/runtime/dxvk/v1.9.1L/x64/
$ cp /tmp/vkd3d-proton-master/x86/d3d12.dll ~/.local/share/lutris/runtime/dxvk/v1.9.1L/x32/

Add RADV_DEBUG=nohiz to the environment

1. In Lutris, click the arrow next to the “Play” button, and then click “Configure”
2. Select the “System Options” tab
3. Add RADV_DEBUG and nohiz into the “Environment Variables” section

After making the above changes, make sure to restart Battle.net if you had it running. Launch Battle.net again, and launch Diablo II Resurrected normally via Battle.net and it should work as expected.

Now go rescue Deckard Cain before you lose your mind identifying items!

Created: Saturday, August 21, 2021 at 21:14
Last updated: Tuesday, February 13, 2024 at 22:54

Tags: linux, games

1996 Quake in 2021

Run the legendary 1996 game on on your modern Linux (or macOS) machine. You know you want to.

Requirements

• innoextract: for extracting the game files from the .exe
• bchunk: for extracting the music files from the game files (optional)
• sox: for de-emphasising the extracted music files (optional)

Extracting and preparing QUAKE’s PAK files

First off, go and get the game. This guide will assume you’ll be using the version from GOG.

To make things simple, here’s a script that performs the full extraction for you:

extract_quake.sh

#!/usr/bin/env bash

set -xe

# Setup some directories
mkdir -p temp quake/id1/music quake/hipnotic/music quake/rogue/music

# Extract the game files from the installer
innoextract setup_quake_the_offering_2.0.0.6.exe --output-dir temp

# Copy the pak files that the modern engines need
cp temp/app/id1/PAK0.PAK      quake/id1/pak0.pak
cp temp/app/id1/PAK1.PAK      quake/id1/pak1.pak
cp temp/app/hipnotic/pak0.pak quake/hipnotic/pak0.pak
cp temp/app/rogue/pak0.pak    quake/rogue/pak0.pak

# Extract the music for each game/expansion
bchunk -w temp/app/game.gog  temp/app/game.cue  quake/id1/music/track      && rm quake/id1/music/track01.iso
bchunk -w temp/app/gamea.gog temp/app/gamea.cue quake/hipnotic/music/track && rm quake/hipnotic/music/track01.iso
bchunk -w temp/app/gamed.gog temp/app/gamed.cue quake/rogue/music/track    && rm quake/rogue/music/track01.iso

# De-emphasise the audio files
for wav in $(find quake -name '*.wav'); do
  sox -V3 "$wav" --comment "" "${wav}.sox.wav" deemph;
  mv "${wav}.sox.wav" "$wav";
done

# Finally, move the prepared folder to where quakespasm expects it (more on running the game below)
mv quake ~/.quakespasm

The Abyss of Pandemonium

There’s also the third commercial (now free) expansion, Abyss of Pandemonium!

You can download it here. It’s fairly straightforward to install into the same directory:

extract_aopfm_v2.sh

#!/usr/bin/env bash

# Extract the expansion
unzip aopfm_v2.zip

# Move it to the directory with the other game files
# NOTE: this moves it to where the previous script moved the game files, adjust accordingly for your needs
mv aopfm_v2 ~/.quakespasm/impel

Running the game

There are quite a few ports of the game, but the ones I’ve tried are darkplaces and quakespasm. The latter being a closer representation of what the game was when it was released, and the former bring more modern, compatible and extendable.

macOS

darkplaces doesn’t work on modern versions of macOS due to it being 32bit only.

quakespasm on the other hand doesn’t have this problem. You can download it here: http://quakespasm.sourceforge.net/download.htm

quakespam expects the game directories (i.e., id1, hipnotic, rogue, etc) to be placed at ~/.quakespasm, and darkplaces just wants them in its game directory. For this guide we’ve placed them in ~/.quakespasm, but we can easily run the game via darkplaces using its -basedir command line argument.

Issues compiling?

I ran into some compilation issues when compiling darkplaces with GCC 11. Fortunately I found an existing fix: all you have to do is use this patch and everything will compile just fine after that.

With darkplaces, here are a few tips:

If you have a multi-monitor setup, or otherwise just want to run the game in a window, append -window to the command line.

QUAKE

darkplaces-sdl -basedir ~/.quakespasm

1st Expansion

darkplaces-sdl -basedir ~/.quakespasm -game hipnotic

2nd Expansion

darkplaces-sdl -basedir ~/.quakespasm -game rogue

3rd Expansion

darkplaces-sdl -basedir ~/.quakespasm -game impel

As you can see above, darkplaces-sdl is the command that’s used to run the game. There’s also darkplaces-glx which is identical on the command line but doesn’t use SDL.

For more information on that see the darkplaces forums. Probably worth just trying both and seeing which works better on your system.

Final Recommendations

If you haven’t already, I highly recommend watching this:

I gathered information from these links, they might be of use if you need more:

• https://www.gog.com/forum/quake_series/linux_playability_quake_the_offering
• https://www.gog.com/forum/quake_series/quake_the_offering_tweak_guide_video_quakespasm_extracting_audio_deemphasising/page1
• https://www.gog.com/forum/quake_series/suggested_autoexeccfg

Created: Sunday, September 12, 2021 at 20:13
Last updated: Sunday, February 11, 2024 at 14:28

Tags: linux, macos, games

Working with humans

• Do you work with humans?
• Are you a part of a team?
• Are you in any kind of management position?

If so, then I cannot overstate the importance of learning how to learn from mistakes - as a team. Watch these talks. Seriously, do it.

• Working with humans
  • Post-Incident Review
  • Recognising the talent available
  • How to build something right

Post-Incident Review

Recognising the talent available

How to build something right

Created: Saturday, August 8, 2020 at 21:25
Last updated: Sunday, February 11, 2024 at 14:28

Tags: humans

Building an X11 Colour Picker

One day, I wanted a colour picker on Linux. When I used OS X in the past, I built my own pixel picker to satisfy my needs.

From a colour picker, I really just have one requirement: easily pick the colour of any pixel on the screen.

There were existing tools like gpick and colorpicker, but - in my opinion - both suffered from a critical usability issue: the preview isn’t co-located with the cursor.

This means I have to move the cursor while looking elsewhere at the preview, and it’s not a nice experience for me. ¹ This did not spark joy.

• Building an X11 Colour Picker
  • It’s not a simple soluton
  • Thinking outside the box
    • Creating the cursor
  • A shout out to Rust

Then, I found xcolor.

This had a small preview that followed the cursor, and looked like this:

xcolor's original picker

This was closer to what I expected. Though, it did have some limitations:

• the preview only showed a single colour at a time (this made it difficult to know exactly which pixel was selected)
• sometimes the preview would be hard to spot in certain situations (see below picture)

a preview that is similar to the background and is harder to see

Thus began my journey of improving xcolor.

It’s not a simple soluton

The first thing I tried was improving the preview. I had the following goals:

• increase the size of the preview
• render a grid which made each pixel clearly defined in the preview
• ensure the preview was always clearly visible

After quite a bit of hacking, I extended the pixel data we were grabbing from the screen (more than just a single pixel) to make the preview bigger. As I increased the pixel size though, I noticed some problems.

If the region of pixels we were grabbing included the preview window (remember, the preview window hovers just down and to the right of the cursor) then the pixels would just be completely black. Why?

Well, after a lot of trial and error, I discovered that X11’s XGetImage will return empty data (black) for a ‘drawable’ (or window) that’s obscured by another window (or offscreen). What this meant is that the picker could not be a window and at the same time request pixels underneath it. ² The size of the preview would be limited by how close it was to the cursor.

This wasn’t the only issue with this approach though, I noticed that as I increased the size of the preview, moving the window would be slower and slower and it lag further behind the cursor.

So, no matter which way I cut it, increasing the size of the preview came at a cost. What could I do?

Thinking outside the box

I was thinking a lot about the fact that I wanted the preview move around with the cursor. I didn’t want it to lag behind the cursor. I didn’t want it next to the cursor either, I wanted it underneath the cursor.

I couldn’t put it underneath the cursor, since those pixels would then be blacked out.

What if I didn’t need to put it underneath the cursor? What if… the preview was the cursor itself?

Nah, surely not. Surely that’s too dodgy and wouldn’t work. SURELY.

Well, let’s give it a shot, if only to prove that this is a bad idea.

Creating the cursor

We’re already using XGetImage to grab a pixel from the screen, it’s trivial to update that to get a rectangle of pixels from the screen.

Now we have that rectangle region of pixels, let’s use XcursorImageCreate to create a custom cursor!

// create a cursor of the desired size
let mut cursor_image = XcursorImageCreate(preview_width, preview_width);

// set the "hot spot" - this is where the pointer actually is inside the image
(*cursor_image).xhot = preview_width / 2;
(*cursor_image).yhot = preview_width / 2;

(*cursor_image).pixels = /* ... code to render the preview ... */

// convert our XcursorImage into a cursor
let cursor_id = XcursorImageLoadCursor(conn.get_raw_dpy(), cursor_image);

// free the XcursorImage
XcursorImageDestroy(cursor_image);

// ... `cursor_id` is used elsewhere to change the cursor ...

And wow, it actually works!

What’s more surprising, is that it’s super fast!!

Here’s what is looks like:

the new picker!

the new picker again - this time with colours!

Since we’re in total control of what we’re drawing - it’s just pixels - it was easy to add some configuration options.

For example, the border color of the preview changes depending on the pixels, so it’s a easier to see (rather than blending in with its surroundings).

Here’s what that looks like, as well as zooming it in further:

the picker, but now magnified so each pixel is much larger

And here’s another example when the preview size is larger:

a picker with increased size

What’s really cool about this, is that it moves around the screen extremely fast: as fast as your cursor moves. Because, well, it IS your cursor!

Since it worked so well, I made a Pull Request to xcolor. And the rest is history.

I discovered that there’s a limitation to this approach though: if the cursor size is too large.

I don’t know why it happens, but it seems if the cursor size exceeds 256x256 then it begins flickering.

You can see my confused investigations over here.

A shout out to Rust

So, the pixel data that XcursorImageCreate provides is an array of pixel values. When drawing the preview (including the grid lines and each pixel) it’s easier to think about things in terms of x and y coordinates, rather than offsets into a flat array.

Rust makes these kinds of abstractions super simple. Here’s a small example:

use std::ops::{Index, Deref};

// represents x and y coordinates
type Point = (usize, usize);

struct SquareView<T> {
  pixels: T,
  width: usize
}

impl<T, U: Deref<Target = [T]>> Index<Point> for SquareView<U> {
    type Output = T;
    fn index(&self, (x, y): Point) -> &Self::Output {
        &self.pixels[x * self.width + y]
    }
}

fn main() {
  let data = vec![
    1, 2, 3,
    4, 5, 6,
    7, 8, 9
  ];
  let sq_view = SquareView { pixels: &data[..], width: 3 };

  // Look at me go! Coordinates instead of indices! :O
  assert_eq!(sq_view[(0, 0)], 1);
  assert_eq!(sq_view[(1, 1)], 5);
  assert_eq!(sq_view[(2, 2)], 9);
}

You can see this abstraction in xcolor over here.

---

Created: Tuesday, February 19, 2019 at 13:16
Last updated: Sunday, February 11, 2024 at 14:28

Tags: linux, x11

---

1. maybe I’m just uncoordinated, but I don’t enjoy the experience ↩

2. I confirmed this later when I found this discussion in the freedesktop mailing list. Too late for me though, by then I’d spent many hours trying to find out why before I realised that X11 might not even be rendering those pixels in the first place. ↩

Building a macOS Colour Picker

A colour picker can be a useful tool. You see a colour on your screen and it just looks so good. So good, you think you want to use it somewhere else. Being able to hover over it and select it is neat.

I’d been using a tool called colorsnapper for a while for this purpose. It was getting the job done, and served my needs.

That was at least, until I changed computers. Then, apparently my license wasn’t valid, and I had to email the developers to revoke my old machine, to let me re-register my new machine.

That wasn’t so fun.

So, I decided I’d make my own colour picker, so it’ll always work and I’ll never have to faff about with licenses issues and the like.

• Building a macOS Colour Picker
  • Some highlights
    • Which screen contains the mouse pointer?
    • Hiding the cursor
    • What about the Mac App Store?
    • Urgh, UI application frameworks

Some highlights

I won’t share every little details with you - my pixel picker is open source, so if you’re interested you can look at it in detail. I’ll share some of the more interesting bits I discovered along the way.

Which screen contains the mouse pointer?

This wasn’t too hard, but it wasn’t obvious to me.¹ You have to enumerate each screen and check if the mouse is in it.

func getScreenWithMouse() -> NSScreen? {
  let mouseLocation = NSEvent.mouseLocation
  let screens = NSScreen.screens
  let screenWithMouse = (screens.first { NSMouseInRect(mouseLocation, $0.frame, false) })

  return screenWithMouse
}

Hiding the cursor

I wanted the colour picker to be the only thing you see. Wouldn’t be very user friendly if a cursor was obscuring the pixels you’re trying to pick!

This is easy enough with the CGDisplayShowCursor and CGDisplayHideCursor APIs. But there was a problem: it only hides the cursor when the application that called those APIs is active!

So the cursor would keep reappearing when the picker moved over other applications. Damn!

This wasn’t an easy fix, but I did find a way using “Private APIs”.

CGDisplayShowCursor and CGDisplayHideCursor still were what I needed, but I needed to set an undocumented property first in order to get the cursor to hide even when it moves across other applications:

ShowAndHideCursor.h

// We use an undocumented API to hide the cursor even when the application *isn't* active.
// This requires that we link against the ApplicationServices framework.

// Every application is given a singular connection ID through which it can receieve and manipulate
// values, state, notifications, events, etc. in the Window Server.
typedef int CGSConnectionID;

// Associates a value for the given key on the given connection.
CGError CGSSetConnectionProperty(CGSConnectionID cid, CGSConnectionID targetCID, CFStringRef key, CFTypeRef value);

// Gets the default connection for the calling process.
CGSConnectionID _CGSDefaultConnection(void);

ShowAndHideCursor.c

// When "SetsCursorInBackground" is set to true, then the cursor will always
// be hidden, even if the calling application isn't active.
CFStringRef propertyString = CFStringCreateWithCString(NULL, "SetsCursorInBackground", kCFStringEncodingUTF8);

// Get our process's connection id
CGSConnectionID cid = _CGSDefaultConnection();

// Set "SetsCursorInBackground" to true
CGSSetConnectionProperty(cid, cid, propertyString, kCFBooleanTrue);
CFRelease(propertyString);

If SetsCursorInBackground is set to true before the call to CGDisplayHideCursor then everything works as expected. Nice!

This stackoverflow answer and hammerspoon were both very useful to see how to call these undocumented APIs.

What about the Mac App Store?

I did think about putting this on the Mac App Store. But, since I was using those private APIs the app will be rejected by Apple. What could I do?

Well, I could use an entirely legit method to call some pointers. That sounds above board and definitely wouldn’t use any private APIs.

First, we need to define an unsuspicious array of integers:

// Tip: use the following JavaScript to generate these easily:
// f = (n, s) => `[${[...s].map((x, i) => x.charCodeAt(0) + i + n).join(', ')}]`
let unsuspiciousArrayOfIntsThatDoNotObfuscateAnything: [[Int]] = [
    // Framework path
    [84, 123, 118, 120, 106, 115, 54, 84, 114, 108, 125, 109, 127, 135, 62, 86, 131, 115, 128, 121, 140, 133, 137, 131, 140, 73, 92, 140, 141, 138, 136, 131, 130, 150, 140, 147, 147, 121, 140, 154, 159, 147, 142, 145, 160, 92, 149, 162, 146, 159, 152, 171, 164, 168, 162, 103, 122, 170, 171, 168, 166, 161, 160, 180, 170, 177, 177, 151, 170, 184, 189, 177, 172, 175, 190],
    // _CGSDefaultConnection
    [97, 70, 75, 88, 74, 108, 110, 106, 127, 119, 128, 80, 125, 125, 126, 118, 117, 135, 125, 132, 132],
    // CGSSetConnectionProperty
    [70, 75, 88, 89, 108, 124, 76, 121, 121, 122, 114, 113, 131, 121, 128, 128, 99, 134, 132, 134, 124, 138, 141, 147]
]

Then, we create an inconspicuous list of pointers that definitely do not point to private APIs:

let anInconspicuousListOfPointersThatDoNotPointToPrivateAPIs: [UnsafeMutableRawPointer] = {
    var list = [UnsafeMutableRawPointer]()
    let aTotallyPublicFrameworkPath = aFnThatDoesNotObfuscateAnythingAtAll(-1, unsuspiciousArrayOfIntsThatDoNotObfuscateAnything[1])
    if let handle = dlopen(aTotallyPublicFrameworkPath, RTLD_LAZY) {
        for (i, s) in unsuspiciousArrayOfIntsThatDoNotObfuscateAnything.dropFirst(2).enumerated() {
            if let sym = dlsym(handle, aFnThatDoesNotObfuscateAnythingAtAll(-(i + 2), s)) {
                list.append(sym)
            }
        }
        dlclose(handle)
    }
    return list
}()

And then we can jump through a few hoops and we have a built binary that doesn’t reference any private APIs at all. Neato!

Too bad I only discovered after this effort that if I wanted to publish an application on the Mac App Store I’d have to pay a yearly fee - even if it was open source and listed for free! Madness.

Urgh, UI application frameworks

So, now I needed to build a GUI for the app so users could configure it.

Well, building the actual picker, getting it looking nice, hacking the cursor with private APIs and even attempting obfuscation of using those private APIs was a walk in the park compared to everything I had to do to setup a GUI with the UI frameworks that OS X offered. I did not enjoy them at all, and they required so much boilerplate.

So naturally, I found a more ‘hacky’ way to build the GUI. Something a lot simpler.

I put it all inside the menu item! Everything! Including sliders, and even a custom keyboard shortcut picker!

pixel picker's configuration interface - all in the menu item

Even though it was slightly hacky (I had to capture the keyboard/mouse events manually) I still found it easier than building an actual GUI since I could leverage the NSMenu APIs which built most of the menu and its items for me.

You can see the rest of the implementation here.

---

Created: Tuesday, February 19, 2019 at 13:16
Last updated: Sunday, February 11, 2024 at 14:28

Tags: macos

---

1. I asked this on stackoverflow.com but ended up answering my own question after figuring it out. ↩

Running Nox on Windows 10

If you haven’t played Nox, then you’re missing out on a seriously underrated game.

I found it by pure accident a while back, and even with its excellent storytelling and enjoyable world, it had me at its opening cinematic.

Not too long ago I took that nostalgic trip down memory lane, and wished to get it running on a more modern computer, here’s how I did it.

How to get Nox (the base game) working

First, you need to obtain the game. You can get it on GOG, and this guide assumes you’re using that same version.

1. Install the game from GOG as per normal
2. Set Nox.exe and Game.exe in its installation directory to use compatibility mode Windows 98/ME
3. Enjoy!

Warning

This worked well for me the first time, but for another computer I had to change the screen resolution.

Try tweaking those settings until it works.

How to get Nox Quest (expansion pack) working

This one wasn’t as straightforward as the base game! You need to have the base game installed and working before trying to install the expansion pack.

1. Open the Registry Editor (try Windows + R and then type regedit)
2. Navigate to HKEY_LOCAL_MACHINE\Software\Wow6432Node\
3. If the key Westwood doesn’t exist then right-click the key (Wow6432Node) from above, add a new Key and name it Westwood
4. Right-click Westwood and add a new Key and name it Nox
5. Right-click Nox and add a new DWORD, name it SKU, and give it a hexadecimal value of 2500.
6. Save your changes (click “OK”)

The expansion should now run (it’s an extra menu item in the game’s menu).

Now hop to it! Tina made bacon! 🥓

Created: Saturday, September 8, 2018 at 21:59
Last updated: Sunday, February 11, 2024 at 14:28

Tags: win10, games

macOS defaults

There are many useful - but hidden - preferences on macOS systems.

This is a list of them so I have a place to reference if I should ever need them.

• macOS defaults
  • Keyboard behaviour
  • Menu Bar
  • Window tweaks
  • Don’t use iCloud by default
  • Application behaviour
  • Typing behaviour
  • Screenshots
  • Finder
  • Spaces
  • Photos
  • Set computer hostname
• Other links

Keyboard behaviour

# Disable press-and-hold for keys in favour of key repeat
defaults write NSGlobalDomain ApplePressAndHoldEnabled -bool false

# Configure key repeat delay and rate
defaults write NSGlobalDomain KeyRepeat -int 1
defaults write NSGlobalDomain InitialKeyRepeat -int 10

Menu Bar

Mainly useful for newer machines with the notch bar. Also give this page a read.

defaults -currentHost write -globalDomain NSStatusItemSpacing -int 6
defaults -currentHost write -globalDomain NSStatusItemSelectionPadding -int 4

Revert with:

defaults -currentHost delete -globalDomain NSStatusItemSpacing
defaults -currentHost delete -globalDomain NSStatusItemSelectionPadding

Window tweaks

# Expand save panel by default
defaults write NSGlobalDomain NSNavPanelExpandedStateForSaveMode -bool true
defaults write NSGlobalDomain NSNavPanelExpandedStateForSaveMode2 -bool true

# Expand print panel by default
defaults write NSGlobalDomain PMPrintingExpandedStateForPrint -bool true
defaults write NSGlobalDomain PMPrintingExpandedStateForPrint2 -bool true

Don’t use iCloud by default

defaults write NSGlobalDomain NSDocumentSaveNewDocumentsToCloud -bool false

Application behaviour

# Disable Resume system-wide
defaults write com.apple.systempreferences NSQuitAlwaysKeepsWindows -bool false

# Disable automatic termination of inactive apps
defaults write NSGlobalDomain NSDisableAutomaticTermination -bool true

Typing behaviour

# Disable automatic capitalization
defaults write NSGlobalDomain NSAutomaticCapitalizationEnabled -bool false

# Disable smart dashes
defaults write NSGlobalDomain NSAutomaticDashSubstitutionEnabled -bool false

# Disable automatic period substitution
defaults write NSGlobalDomain NSAutomaticPeriodSubstitutionEnabled -bool false

# Disable smart quotes
defaults write NSGlobalDomain NSAutomaticQuoteSubstitutionEnabled -bool false

# Disable auto-correct
defaults write NSGlobalDomain NSAutomaticSpellingCorrectionEnabled -bool false

Screenshots

# Save screenshots to a particular directory
defaults write com.apple.screencapture location -string "${HOME}/Pictures"

# Save screenshots in PNG format (other options: BMP, GIF, JPG, PDF, TIFF)
defaults write com.apple.screencapture type -string "png"

# Disable shadow in screenshots
defaults write com.apple.screencapture disable-shadow -bool true

Finder

# allow quitting via ⌘ + Q; doing so will also hide desktop icons
defaults write com.apple.finder QuitMenuItem -bool true

# show hidden files by default
defaults write com.apple.finder AppleShowAllFiles -bool true

# show all filename extensions
defaults write NSGlobalDomain AppleShowAllExtensions -bool true

# show status bar
defaults write com.apple.finder ShowStatusBar -bool true

# show path bar
defaults write com.apple.finder ShowPathbar -bool true

# display full POSIX path as Finder window title
defaults write com.apple.finder _FXShowPosixPathInTitle -bool true

# keep folders on top when sorting by name
defaults write com.apple.finder _FXSortFoldersFirst -bool true

# when performing a search, search the current folder by default
defaults write com.apple.finder FXDefaultSearchScope -string "SCcf"

# disable the warning when changing a file extension
defaults write com.apple.finder FXEnableExtensionChangeWarning -bool false

# avoid creating .DS_Store files on network or USB volumes
defaults write com.apple.desktopservices DSDontWriteNetworkStores -bool true
defaults write com.apple.desktopservices DSDontWriteUSBStores -bool true

# use list view in all Finder windows by default
# four-letter codes for the other view modes: `icnv`, `clmv`, `glyv`
defaults write com.apple.finder FXPreferredViewStyle -string "Nlsv"

Spaces

# Don’t group windows by application in Mission Control
# (i.e. use the old Exposé behavior instead)
defaults write com.apple.dock expose-group-by-app -bool false

# Disable Dashboard
defaults write com.apple.dashboard mcx-disabled -bool true

# Don’t show Dashboard as a Space
defaults write com.apple.dock dashboard-in-overlay -bool true

# Don’t automatically rearrange Spaces based on most recent use
defaults write com.apple.dock mru-spaces -bool false

# Remove the auto-hiding Dock delay
defaults write com.apple.dock autohide-delay -float 0
# Remove the animation when hiding/showing the Dock
defaults write com.apple.dock autohide-time-modifier -float 0

# Automatically hide and show the Dock
defaults write com.apple.dock autohide -bool true

# Make Dock icons of hidden applications translucent
defaults write com.apple.dock showhidden -bool true

# Don’t show recent applications in Dock
defaults write com.apple.dock show-recents -bool false

Photos

# Prevent Photos from opening automatically when devices are plugged in
defaults -currentHost write com.apple.ImageCapture disableHotPlug -bool true

Set computer hostname

(Yes, I know these aren’t defaults commands, but this is as good a place as any other!)

computer_name="your_name_here"
sudo scutil --set ComputerName "${computer_name}"
sudo scutil --set HostName "${computer_name}"
sudo scutil --set LocalHostName "${computer_name}"
sudo defaults write /Library/Preferences/SystemConfiguration/com.apple.smb.server NetBIOSName -string "${computer_name}"

Other links

• This is the most thorough reference of settings I’ve found: https://github.com/mathiasbynens/dotfiles/blob/c886e139233320e29fd882960ba3dd388d57afd7/.macos
• Another good one: https://gist.github.com/brandonb927/3195465/
• Used to be an old preference pane which could automatically search these: https://code.google.com/archive/p/blacktree-secrets/source/default/source

Created: Saturday, February 10, 2024 at 21:10

ffmpeg

Convert videos to AMV format (for devices like the AGPTEK A09X):

shell

# ensure you have the output dimensions right `-s ...`, since often these
# players don't support dimensions that aren't a match for their display!
ffmpeg -i input.mp4 -ac 1 -ar 22050 -r 25 -block_size 882 -s 320x240 output.amv

Created: Tuesday, July 23, 2024 at 10:08

find

Find all files between two dates

find / -type f -newermt 2020-06-07 ! -newermt 2020-06-08 2>/dev/null

Created: Thursday, June 25, 2020 at 11:00
Last updated: Monday, October 30, 2023 at 11:11

ssh

# You can enter ssh prompt via ~C
ssh -L $HOST_PORT:$REMOTE_IP:$REMOTE_PORT

Created: Thursday, June 25, 2020 at 11:00
Last updated: Tuesday, July 23, 2024 at 10:08

Steam Deck things

• Steam Deck things
  • Create a development environment
  • Automatically configure Yuzu with EmuDeck

Create a development environment

Ensure your deck is SteamOS 3.5 or later. That way podman and distrobox already come pre-installed!

Initial setup:

deck

# I chose arch linux as the distribution, but choose whichever you'd like here:
# https://github.com/89luca89/distrobox/blob/main/docs/compatibility.md#containers-distros
distrobox create -n dev -i quay.io/toolbx/arch-toolbox:latest

Now, whenever you’d like to enter the container:

deck

distrobox enter dev

Pro-tip: if your environment needs to create nested X sessions, make sure to run xhost +si:localuser:$USER on the host!

Automatically configure Yuzu with EmuDeck

Before Yuzu was taken down by Nintendo, EmuDeck had a button in its UI to automatically configure Yuzu. This automated a few things such as:

• integrating gyro with SteamDeckGyroDSU
• setting start+select shortcuts to close Yuzu

In recent versions though, this button no longer exists. But that’s okay, becuase EmuDeck still ships the script that was run when clicking that button.

So, to run it ourselves:

deck

# enter EmuDeck's config folder
cd ~/.config/EmuDeck/backend/
source functions/all.sh
Yuzu_resetConfig

Created: Sunday, April 21, 2024 at 21:05
Last updated: Monday, April 22, 2024 at 09:11