Setting up my clockworkpi uConsole

Introduction

The goal of this post is to go through my current setup for my uConsole (by ClockworkPi) and everything I had to do to make it happen. I have the feeling it will be useful for my future self if something fails or possibly for my future Pilet if it end up being delivered at some point (the joy of kickstarter)… Or any other cyberdeck I end up using the most…

The tldr; is: Debian (Trixie), i3wm, lots of CLI/TUI applications and retroarch for playing my favorite JRPG games (Chrono Trigger, Final Fantasy VI, etc…). At the end, I’ll also give my opinion about this device.

OS installation and tweaks

Debian bookworm trixie

When I started to write this post, debian Trixie was not yet available and thus I installed Bookworm. But since Trixie came out and as said by Rex, the community member providing the best OS for the uConsole, the upgrade from Bookworm to Trixie doesn’t work (trust me I tried and failed - yay for backups!). Anyway, I’ve reinstall Trixie from scratch and redid everything. Hopefully I didn’t leave any mistake based on things done in Bookworm that isn’t compatible with Trixie.

As said above, I didn’t installed the official image, because according to a lot of things I read on the official forum, it was way better to use the version provided by a nice person called Rex. I found it on this thread and advise to use the same one. Rex also provides other distros and packages so check their profile. I used the full and not the lite version because I had issues with the keyboard using the lite version.

To install it, just copy the image on a SD card and then insert it in your uConsole and start it. To copy the image, I simply use dd:

sudo dd if=/path/to/image/file.img of=/dev/sdX status="progress" conv="fsync"

Don’t forget to update sdX with the right name of your disk.

Initial setup

First, run through the initial setup to provide your username, network connection, language, country, timezone, keyboard layout, etc… I kept the US layout so it matches what is written on the keyboard keys. I did that because the physical layout of the keyboard is not standard, so it would be too complicated to remember where special characters are as opposed to a real size keyboard where I don’t need to look at it.

Then I updated the system with sudo apt update && sudo apt upgrade and then launch sudo raspi-config. In the config screen, I:

• Made sure raspi-config was already up to date (Update)
• Changed the hostname (System → Hostname)
• Confirmed boot to desktop GUI and not Console (System → Boot)
• Disabled both auto login to CLI or GUI (System → Auto Login). I did this because of the encryption of the home directory that will be decrypted at login with the same password than my user. Read below for more.
• Enabled ssh server (Interface Options → SSH)
• Verified my localisation options (Locale en_US.utf8, Timezone, keyboard and WLAN country)

After all that, I rebooted to unsure everything was still running correctly and the system showed me the login screen at boot instead of the auto login by default.

Then I of course installed vim and tmux to edit any configuration files later on. Read below to see what else I installed but started with that first as I’m going to edit some config file very soon via ssh (hence tmux just in case of network drop).

Login and encryption

Next step was home directory encryption. I already wrote a dedicated post about all the details to do so with gocryptfs. As opposed to what I do on my laptop/desktop, it means I don’t encrypt the full disk which means I don’t decrypt the full disk at boot. I have to decrypt my home directory when I log in (hence disabling autologin earlier). As I wrote in that post, the decryption happen when I authenticate via PAM, either via the tty or via the login manager (lightdm). Doing so require that I must login manually and disable the autologin feature. Otherwise PAM would not have the password to decrypt my home. Read the dedicated post linked in this paragraph for more information.

Overclock

I decided to overclock the device a little. To do so, edit the /boot/firmware/config.txt file. Within the [pi4] section (or [pi5] if you have a raspberrypi 5 and not a 4), add the following:

over_voltage=5
arm_freq=2000
gpu_freq=750
gpu_mem=256

And reboot after saving the file.

After the reboot, test that the changes worked:

root@clockworkpi:~# vcgencmd measure_clock arm
frequency(48)=2000531200

Secure the device

If you haven’t, read my previous post where I explained how I encrypted my home directory.

To secure SSH, I did the usual: no root connection, no password connection (only with ssh key).

NOTA: if you do the same and limit your ssh connection to ssh keys and forbid password connection, then you MUST connect to your account on the uConsole first and then you’ll be able to connect via SSH. The reason for that is that you need first to decrypt your home (that contains the ~/.ssh/authorized_keys) to be able to connect with your ssh key. Otherwise you’ll see a failing message telling you the passkey is wrong.

Then secure the device with some firewall rules. First, install ufw and then:

ufw default deny incoming
ufw allow ssh
ufw enable

But I also disabled sshd by default:

sudo systemctl disable sshd.service

And I only start it when needed:

sudo systemctl start sshd.service

Replace start with stop to disable it after you’re done :).

Fake sleep / hibernation

Hibernation is not supported on a RaspberryPi (at least to my knowledge). I’ve seen “fake” sleep mode for the uConsole on their forum where it blocks the keyboard, switch off the screen, set the CPU to a low value, etc… But I haven’t set all that up at this time. Maybe I will, but for now I don’t care too much.

If you want to read more about this topic, I suggest looking at either this thread or this one.

Make the uConsole a CLI/TUI first device

i3wm to reduce the use of the shitty trackball

As the above title said, the trackball of the uConsole is difficult to use at best, crap most of the time… So instead of relying on a Desktop Environment or a Window Manager requiring to use it for most things, I decided to use my beloved i3wm like everywhere else. The main issue is the lack of a “super” key (the windows key) without the use of Fn on the uConsole keyboard, so I had to update my configuration to use alt (called mod1 in i3wm configuration file) as my main “modifier” as opposed to my config on my desk/laptops where I use super.

First, install the required software used in my i3 config:

sudo apt install i3-wm i3blocks i3lock

As per debian’s documentation, the i3 package is a metapackage installating i3-wm, i3lock, i3status, dunst, and suckless-tools (not sure which ones). As I prefer using i3blocks, I installed all packages manually. Check the next paragraph (useful software) as a lot of my configuration relies on some of those software.

One issue I had was the lightdm configuration, installed by default with LXDE and that doesn’t allow to change the DE/WM on its start screen. To change the session started by lightdm, I edited its configuration file /etc/lightdm/lightdm.conf and changed:

user-session=LXDE-pi-labwc
autologin-session=LXDE-pi-labwc

To:

user-session=i3
autologin-session=i3

Now log in using lightdm and you should see i3wm starting.

Useful software

Here is a list of the software I installed (I may missed some):

apt install tmux neovim ffmpeg zsh git wget curl emacs syncthing ufw bat dunst rofi fonts-font-awesome scrot thunar imagemagick xbacklight blueman nm-tray tldr-py pavucontrol mpv light elinks golang syncthing htop dfc aerc emacs alacritty syncthing xsel

Then, I copied the relevant dotfiles from my other computer (for zsh, doom emacs, dunst, rofi, etc…).

Firefox is very slow, so while I still have it installed, I decided that maybe the uConsole was a good fit to try to learn how to use chawan, a TUI browser with CSS, inline image and JS support. I’m going to write a dedicated post about this because I had to compile both Nim language and Chawan from source so it would be too long to describe here.

For emails, I use aerc. I may write latter about my setup and configuration.

I decided to use Newsboat for reading RSS feeds. I do this to avoid opening Firefox to access my miniflux instance, as newsboat can connect to miniflux (so reading an article on newsboat will mark it as read in miniflux). It isn’t perfect as sometime I still need to open the full article in a browser (eg: news website I subscribe to that only provide an summary in their feeds).

I use Navidrome to manage my music library and listen to it anywhere. I use Tempo as an android client for my phone, but I use Termsonic, a TUI client on my computer, which works great on the uConsole too. To install it (you need golang installed):

cd ~/workspace/contrib
git clone https://git.sixfoisneuf.fr/termsonic && cd termsonic
go build ./cmd/termsonic/

Then put the binary in a directory that is in your path (eg: I use ~/bin and put it in my path).

To install a signal client and a matrix client, I need (unfortunately) to have rust installed. To do so:

sudo apt install rustup
rustup default stable

Then, to install gurk, a Signal TUI client:

sudo apt install clang libclang-dev cmake protobuf-compiler
cargo install --git https://github.com/boxdot/gurk-rs gurk

And then follow the documentation to connect your new device.

And to install iamb, a matrix TUI client:

cargo install --locked iamb

You’ll also need to add ~/.cargo/bin to your $PATH variable within your ~/.bashrc or ~/.zshrc or equivalent.

To share files between my other devices and the uConsole, I use syncthing. I didn’t installed the GTK client (maybe I should), so I used the web client to configure the other devices. It is really great to share files without manual intervention, like my password (managed with pass) or my org files.

I didn’t install any fediverse client yet, but maybe i’ll find a good TUI one that works correctly with GoToSocial. But I’m not sure if I want to have access to the fediverse on this device. We’ll see.

Thank you notes

I’d like to thank a lot of people from the uConsole forum that wrote many things that helped me during this setup. The most useful links anyone buying such a device should look at are:

• https://forum.clockworkpi.com/t/just-received-my-uconsole-now-what-a-list-of-links-of-interest/15322
• https://gist.github.com/selfawaresoup/b296f3b82167484a96e4502e74ed3602
• https://forum.clockworkpi.com/t/uconsole-software-tips-and-tricks-general-thread/12243
• https://github.com/cjstoddard/Clockworkpi-uConsole

And most probably others too!

Conclusion and thoughts on the uConsole.

The uConsole is a nice cyberdeck type of device. It is solid and has a good quality build. Except for the trackball that is crap! The keyboard is good enough, while not the best. But still better than typing on a touch screen. The weird physical layout forces me to use it in qwerty though which is a bit annoying and a lot of my “a” are displayed as “q”… But that is ok.

The arrows and gaming keys are great and allowed me to have a very nice time redoing chrono trigger entirely!

The main thing is it’s size. I would have hope for something a little smaller so I could have it with me all the time. Its size makes that difficult if you don’t have a bag or big cargo pants with huge pockets (which I don’t). Maybe with the weather getting colder, having it in my coat pockets will be a solution?

The more I think about it, my ideal size would be something like a large blackberry phone… The beepy seems nice but unfortunately it is out of stock at the moment and use a Pi Zero W which wouldn’t be powerful enough though.

Anyway, that post is long enough for now, so I’ll stop here, maybe it will be useful for others as well.