Free Guide
25 min read

i3 & Sway on the uConsole.

Maximize every pixel on your 5‑inch screen. Set up a tiling window manager that makes the ClockworkPi uConsole feel like a proper cyberdeck.

Beginner → ModerateDifficulty
CM4 & CM5Targets
Mar 2026Updated
In this guide
01Why tiling WMs are perfect for the uConsole
02Installing i3 (X11) and Sway (Wayland)
03Keybindings optimized for the uConsole keyboard
04Status bar — battery, WiFi, CPU temp
05Multi-workspace workflow
06Display scaling & resolution tweaks
07Companion tools — dmenu, rofi, ranger, tmux
08Common issues & uConsole-specific fixes
09Skip the setup — get the pre-configured Toolkit
01 — Why Tiling WMs
1

Why i3/Sway is perfect for the uConsole

easy
Impact

The uConsole's 5‑inch, 1280×720 display is beautiful — but every pixel counts. Traditional desktop environments like LXDE or XFCE waste precious screen real estate on title bars, taskbars, window decorations, and desktop panels. On a screen this small, that overhead is brutal.

Tiling window managers like i3 (X11) and Sway (Wayland) solve this completely:

Zero wasted space

No title bars, no decorations, no gaps by default. Every pixel is your app.

Keyboard-driven

Perfect for the uConsole's compact keyboard. No trackball gymnastics needed.

Minimal resource usage

i3 uses ~5MB RAM. More memory for your actual work on the CM4's limited 1–8GB.

Instant tiling

Windows auto-arrange. Split-screen is the default, not an afterthought.

The difference is dramatic. A typical LXDE desktop on the uConsole gives you roughly ~60–65% usable screen area after panels and decorations. With i3 or Sway, you get ~98% — the only overhead is a slim status bar.

┌─ i3 layout on uConsole (720×1280 portrait / 1280×720 landscape) ─┐
terminal[workspace 1]
browser[workspace 1]
▐ 1 ▐ 2 ▐ 3 ▐ 4 ▐ — i3bar: battery 87% │ wifi 72dBm │ cpu 42°C
└─ 100% screen utilization — no wasted pixels ──────────────────────┘

i3 vs Sway — which to choose?
i3 runs on X11 and is battle-tested with broad compatibility. Sway is the Wayland equivalent — same config format, better performance on modern GPUs, and native HiDPI support. For the uConsole's Mali GPU, Sway is recommended if you want smoother rendering, but i3 is the safer choice if you need specific X11 apps (like some older IDEs).

02 — Installation
2

Installing i3 and Sway

easy
Impact

The uConsole runs a Debian-based OS (Armbian or the official ClockworkPi image). Both i3 and Sway are available in the default repositories. Start by updating your package list:

terminal — update packages
sudo apt update && sudo apt upgrade -y

Option A: i3 (X11)

Best compatibility. Works with all X11 applications. Recommended if you use tools that don't support Wayland yet.

terminal — install i3
# Install i3 window manager with status bar and screen locker
sudo apt install -y i3 i3status i3lock dmenu

# Optional: install a compositor for transparency/effects
sudo apt install -y picom

After installing, log out and select "i3" from the session menu on the login screen. If using a display manager like LightDM, the option appears in the session dropdown.

terminal — start i3 without display manager
# If you prefer to launch from TTY without a display manager:
# Add to your ~/.xinitrc:
echo "exec i3" > ~/.xinitrc

# Then start X:
startx

Option B: Sway (Wayland)

Better performance and native scaling. Recommended for the uConsole's Mali GPU. Uses the same config syntax as i3.

terminal — install sway
# Install Sway with waybar (status bar) and app launcher
sudo apt install -y sway waybar wofi

# Install additional Wayland utilities
sudo apt install -y swaylock swayidle grim slurp wl-clipboard

# grim + slurp = screenshot tool
# wl-clipboard = clipboard manager for Wayland

Launch Sway directly from a TTY — no display manager needed:

terminal — launch sway
# From a TTY console (Ctrl+Alt+F2):
sway

# Or add to your shell profile for auto-start on login:
# Add to ~/.bash_profile or ~/.zprofile:
if [ -z "$WAYLAND_DISPLAY" ] && [ "$XDG_VTNR" -eq 1 ]; then
  exec sway
fi

Heads up: On first launch, i3 will ask you to choose a mod key (Super or Alt). On the uConsole's keyboard, Super (Fn+Tab on some layouts) can be awkward to reach. We recommend Alt as the mod key — we'll optimize the full keybinding layout in the next section.

03 — Keybindings
3

Keybindings for the uConsole keyboard

moderate
Impact

The uConsole's compact keyboard lacks dedicated function keys and has a non-standard layout. The default i3 keybindings assume a full-size keyboard and feel terrible here. Let's fix that.

Edit the config file at ~/.config/i3/config (or ~/.config/sway/config for Sway — the syntax is identical):

~/.config/i3/config — core keybindings
# ─── uConsole-optimized i3 config ─────────────────────
# Use Alt as the mod key (easier to reach on compact keyboard)
set $mod Mod1

# ─── LAUNCH ───────────────────────────────────────────
# Terminal
bindsym $mod+Return exec alacritty
# App launcher
bindsym $mod+d exec --no-startup-id dmenu_run -fn 'monospace:size=12'
# Kill focused window
bindsym $mod+Shift+q kill

# ─── FOCUS (vim-style — perfect for compact layout) ───
bindsym $mod+h focus left
bindsym $mod+j focus down
bindsym $mod+k focus up
bindsym $mod+l focus right

# ─── MOVE WINDOWS ─────────────────────────────────────
bindsym $mod+Shift+h move left
bindsym $mod+Shift+j move down
bindsym $mod+Shift+k move up
bindsym $mod+Shift+l move right

# ─── SPLITS ───────────────────────────────────────────
bindsym $mod+b split h
bindsym $mod+v split v
bindsym $mod+f fullscreen toggle

# ─── LAYOUT ───────────────────────────────────────────
bindsym $mod+s layout stacking
bindsym $mod+w layout tabbed
bindsym $mod+e layout toggle split

# ─── FLOATING ─────────────────────────────────────────
bindsym $mod+Shift+space floating toggle
bindsym $mod+space focus mode_toggle

# ─── WORKSPACES ───────────────────────────────────────
# Number keys on uConsole are directly accessible
bindsym $mod+1 workspace number 1
bindsym $mod+2 workspace number 2
bindsym $mod+3 workspace number 3
bindsym $mod+4 workspace number 4
bindsym $mod+5 workspace number 5

# Move container to workspace
bindsym $mod+Shift+1 move container to workspace number 1
bindsym $mod+Shift+2 move container to workspace number 2
bindsym $mod+Shift+3 move container to workspace number 3
bindsym $mod+Shift+4 move container to workspace number 4
bindsym $mod+Shift+5 move container to workspace number 5

# ─── RESIZE MODE ──────────────────────────────────────
mode "resize" {
  bindsym h resize shrink width 5 px or 5 ppt
  bindsym j resize grow height 5 px or 5 ppt
  bindsym k resize shrink height 5 px or 5 ppt
  bindsym l resize grow width 5 px or 5 ppt
  bindsym Return mode "default"
  bindsym Escape mode "default"
}
bindsym $mod+r mode "resize"

# ─── RELOAD / RESTART ────────────────────────────────
bindsym $mod+Shift+c reload
bindsym $mod+Shift+r restart
bindsym $mod+Shift+e exec "i3-nagbar -t warning -m 'Exit i3?' -B 'Yes' 'i3-msg exit'"

Pro tip: We limit workspaces to 5 instead of the default 10. On the uConsole, you rarely need more than 4–5 workspaces, and it keeps the keybindings within easy reach of the compact number row.

Essential appearance config

~/.config/i3/config — appearance (append to config)
# ─── APPEARANCE ───────────────────────────────────────
# Remove title bars completely (maximize screen space)
default_border pixel 1
default_floating_border pixel 1

# No gaps by default — every pixel matters on 5"
gaps inner 0
gaps outer 0

# Thin green border for focused window
# class                 border  bground text    indicator child_border
client.focused          #00ff41 #0a0f0a #d4d4d4 #00ff41   #00ff41
client.focused_inactive #1a1f1a #0a0f0a #808080 #1a1f1a   #1a1f1a
client.unfocused        #1a1f1a #060808 #404040 #1a1f1a   #1a1f1a

# Font for window titles (only visible in stacking/tabbed mode)
font pango:monospace 10

# ─── AUTOSTART ────────────────────────────────────────
exec --no-startup-id nm-applet
exec_always --no-startup-id picom --backend glx

Sway-specific additions

If using Sway, add these Wayland-specific lines to ~/.config/sway/config:

~/.config/sway/config — wayland extras
# ─── SWAY-SPECIFIC ────────────────────────────────────
# Output configuration for uConsole display
output DSI-1 {
  resolution 1280x720
  scale 1
  position 0 0
}

# Input configuration for uConsole keyboard
input "type:keyboard" {
  xkb_options ctrl:nocaps
  repeat_delay 250
  repeat_rate 40
}

# Screen idle / lock
exec swayidle -w \
  timeout 300 'swaylock -f -c 060808' \
  timeout 600 'swaymsg "output * power off"' \
  resume 'swaymsg "output * power on"'

# Screenshot bindings
bindsym $mod+Print exec grim ~/screenshot-$(date +%Y%m%d-%H%M%S).png
bindsym $mod+Shift+Print exec grim -g "$(slurp)" ~/screenshot-$(date +%Y%m%d-%H%M%S).png
04 — Status Bar
4

Status bar — battery, WiFi, CPU temp

moderate
Impact

On a device you carry around, you need at-a-glance info: battery level, WiFi strength, and CPU temperature (the uConsole can throttle under load). Here's how to set up each bar.

i3status (for i3)

Lightweight and built-in. Add this bar block to your i3 config, then create the i3status config:

~/.config/i3/config — bar section
bar {
  status_command i3status --config ~/.config/i3status/config
  position bottom
  height 20
  font pango:monospace 9

  colors {
    background #060808
    statusline #d4d4d4
    separator  #1a1f1a

    focused_workspace  #00ff41 #0a0f0a #00ff41
    active_workspace   #1a1f1a #0a0f0a #808080
    inactive_workspace #1a1f1a #060808 #404040
    urgent_workspace   #ff5f56 #060808 #ff5f56
  }
}
~/.config/i3status/config
general {
  output_format = "i3bar"
  colors = true
  color_good = "#00ff41"
  color_degraded = "#ffb800"
  color_bad = "#ff5f56"
  interval = 5
}

# Battery — uConsole uses a single 18650 cell
order += "battery 0"
battery 0 {
  format = "BAT %status %percentage %remaining"
  format_down = "NO BAT"
  path = "/sys/class/power_supply/axp20x-battery/uevent"
  low_threshold = 20
  threshold_type = "percentage"
  status_chr = "⚡"
  status_bat = "🔋"
  status_full = "✓"
}

# WiFi signal strength
order += "wireless wlan0"
wireless wlan0 {
  format_up = "W: %essid %quality"
  format_down = "W: down"
}

# CPU temperature — critical for throttle monitoring
order += "cpu_temperature 0"
cpu_temperature 0 {
  format = "CPU %degrees°C"
  path = "/sys/class/thermal/thermal_zone0/temp"
  max_threshold = 75
}

# CPU usage
order += "cpu_usage"
cpu_usage {
  format = "CPU %usage"
}

# RAM
order += "memory"
memory {
  format = "MEM %used/%total"
  threshold_degraded = "256M"
  threshold_critical = "128M"
}

# Date/time
order += "tztime local"
tztime local {
  format = "%H:%M %m/%d"
}

Waybar (for Sway)

More customizable than i3status, with native Wayland support and CSS styling. Add this to your Sway config:

~/.config/sway/config — bar section
# Use waybar instead of swaybar
bar {
  swaybar_command waybar
}
~/.config/waybar/config
{
  "layer": "top",
  "position": "bottom",
  "height": 22,
  "modules-left": ["sway/workspaces", "sway/mode"],
  "modules-center": [],
  "modules-right": [
    "cpu",
    "temperature",
    "memory",
    "network",
    "battery",
    "clock"
  ],

  "sway/workspaces": {
    "format": "{index}"
  },

  "battery": {
    "bat": "axp20x-battery",
    "interval": 30,
    "format": "BAT {capacity}%",
    "format-charging": "⚡{capacity}%",
    "format-full": "✓ FULL",
    "states": {
      "warning": 30,
      "critical": 15
    }
  },

  "network": {
    "interface": "wlan0",
    "format-wifi": "W: {essid} {signalStrength}%",
    "format-disconnected": "W: OFF",
    "interval": 10
  },

  "temperature": {
    "thermal-zone": 0,
    "critical-threshold": 75,
    "format": "{temperatureC}°C"
  },

  "cpu": {
    "interval": 5,
    "format": "CPU {usage}%"
  },

  "memory": {
    "format": "MEM {used:0.1f}G"
  },

  "clock": {
    "format": "{:%H:%M %m/%d}"
  }
}
~/.config/waybar/style.css
* {
  font-family: monospace;
  font-size: 11px;
  color: #d4d4d4;
}

window#waybar {
  background-color: #060808;
  border-top: 1px solid #1a1f1a;
}

#workspaces button {
  padding: 0 6px;
  color: #404040;
  border: none;
  border-radius: 0;
  background: transparent;
}

#workspaces button.focused {
  color: #00ff41;
  background: rgba(0, 255, 65, 0.06);
}

#battery.warning { color: #ffb800; }
#battery.critical { color: #ff5f56; }
#temperature.critical { color: #ff5f56; }

#cpu, #memory, #temperature, #network, #battery, #clock {
  padding: 0 8px;
  border-left: 1px solid #1a1f1a;
}

Battery path note: The uConsole uses an AXP PMU. The battery path is /sys/class/power_supply/axp20x-battery/. If your device shows "NO BAT", check the exact path with ls /sys/class/power_supply/.

05 — Workspace Workflow
5

Multi-workspace workflow for the small screen

easy
Impact

On a 5‑inch screen, split-tiling two windows side by side can feel cramped. The real power move is using workspaces as virtual desktops — one app per workspace, fast-switching with Alt+number.

Recommended workspace layout

1TERMMain terminal (tmux session)
2WEBBrowser (Firefox/Chromium)
3CODEEditor (Neovim, VS Code, Helix)
4FILESFile manager (ranger or thunar)
5MISCComms, music, monitoring

Auto-assign apps to workspaces

~/.config/i3/config — workspace assignments
# Auto-assign applications to specific workspaces
assign [class="firefox"] 2
assign [class="Chromium"] 2
assign [class="Code"] 3
assign [app_id="code-url-handler"] 3
assign [class="Thunar"] 4
assign [app_id="thunar"] 4

# Sway uses app_id instead of class for native Wayland apps:
# assign [app_id="firefox"] 2
# assign [app_id="Alacritty"] 1

# Switch to workspace when app opens
for_window [class="firefox"] focus
for_window [class="Code"] focus

Quick-switch shortcuts

~/.config/i3/config — fast workspace switching
# Cycle workspaces with Alt+Tab style navigation
bindsym $mod+Tab workspace next
bindsym $mod+Shift+Tab workspace prev

# Toggle between last two workspaces (very useful on small screen)
bindsym $mod+grave workspace back_and_forth

# Scratchpad — a hidden floating workspace (great for quick notes)
bindsym $mod+Shift+minus move scratchpad
bindsym $mod+minus scratchpad show

Scratchpad tip: The scratchpad is a hidden floating workspace. Launch a small terminal, send it to scratchpad with $mod+Shift+-, then toggle it instantly with $mod+-. Perfect for a quick calculator, notes, or password manager on the small screen.

06 — Display Scaling
6

Screen resolution & scaling tweaks

moderate
Impact

The uConsole's 5‑inch display runs at 1280×720. At native resolution, text can be tiny. Here's how to make it comfortable without wasting pixels.

Terminal font sizing

For a terminal emulator like Alacritty, a font size of 11–13px hits the sweet spot between readability and screen density:

~/.config/alacritty/alacritty.toml
[font]
size = 12.0

[font.normal]
family = "JetBrains Mono"
# Or: "Hack", "Fira Code", "IBM Plex Mono"

[window]
padding.x = 2
padding.y = 2
# Minimal padding to maximize content area

GTK & Qt application scaling

~/.config/sway/config — or export in ~/.profile
# For Sway — set output scale
output DSI-1 scale 1

# For GTK apps (Firefox, Thunar, etc.)
# Add to ~/.profile or ~/.bash_profile:
export GDK_SCALE=1
export GDK_DPI_SCALE=1.0

# For Qt apps:
export QT_AUTO_SCREEN_SCALE_FACTOR=1
export QT_SCALE_FACTOR=1

# Firefox-specific: enable Wayland native rendering
export MOZ_ENABLE_WAYLAND=1

X11 DPI settings (i3 only)

~/.Xresources
! Set DPI for X11 applications
! 96 = default, increase for larger UI elements
Xft.dpi: 108
Xft.autohint: 0
Xft.lcdfilter: lcddefault
Xft.hintstyle: hintfull
Xft.hinting: 1
Xft.antialias: 1
Xft.rgba: rgb
terminal — apply Xresources
# Apply changes
xrdb -merge ~/.Xresources

# Verify current DPI
xdpyinfo | grep "dots per inch"

Screen rotation

Some users prefer portrait orientation for reading or coding. Quick rotation commands:

terminal — rotate display
# Sway — rotate 90° (portrait mode)
swaymsg output DSI-1 transform 90

# Sway — back to landscape
swaymsg output DSI-1 transform 0

# i3/X11 — rotate with xrandr
xrandr --output DSI-1 --rotate right   # portrait
xrandr --output DSI-1 --rotate normal  # landscape

# Add a keybinding for quick toggle:
# In i3/sway config:
bindsym $mod+o exec swaymsg output DSI-1 transform 90
bindsym $mod+Shift+o exec swaymsg output DSI-1 transform 0

Scaling advice: Resist the urge to scale above 1×. On a 1280×720 display, scaling to 1.5× gives you an effective resolution of ~853×480 — you lose almost half your workspace. Instead, increase just the font size in your terminal and browser, and keep the WM at native 1×.

07 — Companion Tools
7

Recommended companion tools

easy
Impact

A tiling WM is just the foundation. These tools complete the keyboard-driven workflow and make the uConsole feel like a proper cyberdeck.

App Launchers — dmenu, rofi, wofi

dmenu is the classic minimal launcher (comes with i3). rofi is more powerful with window switching and custom menus. wofi is the Wayland-native equivalent for Sway.

terminal — install & configure
# rofi (X11 — works with i3)
sudo apt install -y rofi
# Replace dmenu in i3 config:
# bindsym $mod+d exec --no-startup-id rofi -show drun -theme gruvbox-dark

# wofi (Wayland — works with Sway)
sudo apt install -y wofi
# Replace dmenu in sway config:
# bindsym $mod+d exec wofi --show drun --width 400 --height 300

File Manager — ranger

A terminal-based file manager with vim keybindings. Three-pane layout with preview. Perfect for the uConsole — no GUI overhead.

terminal — install ranger
sudo apt install -y ranger
# Optional: image preview support
sudo apt install -y w3m-img

# Launch:
ranger

Terminal Multiplexer — tmux

Split a single terminal into panes — like i3 within your terminal. Essential for SSH sessions and persistent workflows. Sessions survive disconnects.

terminal — install & configure tmux
sudo apt install -y tmux

# Minimal ~/.tmux.conf for uConsole:
cat << 'TMUX' > ~/.tmux.conf
# Use Ctrl-a as prefix (easier than Ctrl-b on compact keyboard)
set -g prefix C-a
unbind C-b
bind C-a send-prefix

# Vim-style pane navigation
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# Split panes with | and -
bind | split-window -h
bind - split-window -v

# Minimal status bar
set -g status-style 'bg=#060808 fg=#404040'
set -g status-left '#[fg=#00ff41]#S '
set -g status-right '#[fg=#00ff41]%H:%M'

# Mouse support (for trackball)
set -g mouse on

# Start windows at 1
set -g base-index 1
TMUX

Other essentials

terminal — install the full companion stack
# All-in-one install for the essential toolkit:
sudo apt install -y \
  alacritty      \  # GPU-accelerated terminal
  brightnessctl  \  # Screen brightness from keybindings
  pamixer        \  # Volume control from keybindings
  dunst          \  # Lightweight notification daemon
  feh            \  # Wallpaper setter (i3)
  swaybg         \  # Wallpaper setter (Sway)
  htop           \  # System monitor
  neovim         \  # Terminal editor
  bat            \  # Better 'cat' with syntax highlighting
  fzf            \  # Fuzzy finder
  ripgrep           # Fast recursive search

Useful keybindings to add:

~/.config/i3/config — media & brightness keys
# Volume control (uses pamixer)
bindsym XF86AudioRaiseVolume exec pamixer -i 5
bindsym XF86AudioLowerVolume exec pamixer -d 5
bindsym XF86AudioMute exec pamixer -t

# Brightness control (uses brightnessctl)
bindsym XF86MonBrightnessUp exec brightnessctl set +10%
bindsym XF86MonBrightnessDown exec brightnessctl set 10%-

# Lock screen
bindsym $mod+Escape exec i3lock -c 060808
# Or for Sway:
# bindsym $mod+Escape exec swaylock -f -c 060808
08 — Troubleshooting
8

Common issues & uConsole-specific fixes

moderate
Impact

Sway won't start — "failed to open DRM device"

The Mali GPU needs the correct DRM driver. This usually means the user isn't in the video group.

terminal — fix DRM access
# Add yourself to the video and render groups:
sudo usermod -aG video,render $USER

# Log out and back in, then try again:
sway

# If still failing, check which DRM device is available:
ls -la /dev/dri/
# You should see card0 and renderD128

Screen is blank / wrong resolution on boot

The uConsole's DSI panel sometimes isn't detected correctly.

terminal — force resolution
# For Sway — explicitly set output in config:
# ~/.config/sway/config
output DSI-1 mode 1280x720@60Hz

# For i3/X11 — add to ~/.xinitrc before exec i3:
xrandr --output DSI-1 --mode 1280x720 --rate 60

# If DSI-1 isn't the right name, find it:
swaymsg -t get_outputs  # Sway
xrandr                  # X11

Mod key (Super) doesn't work or is inconsistent

The uConsole keyboard maps Super through an Fn layer, which can cause intermittent detection issues.

terminal — debug & fix
# Test which key codes your keyboard sends:
xev  # X11
wev  # Wayland (install: sudo apt install wev)

# If Super is unreliable, switch to Alt (Mod1):
# In i3/sway config, change:
set $mod Mod1  # Alt key — always reliable on uConsole

# Check current modifier mapping:
xmodmap -pm

Battery indicator shows "NO BAT" or wrong percentage

The AXP PMU exposes battery info at a non-standard path.

terminal — find correct battery path
# List all power supply devices:
ls /sys/class/power_supply/

# Common uConsole paths:
# axp20x-battery (most common)
# axp20x-ac

# Check battery info manually:
cat /sys/class/power_supply/axp20x-battery/capacity
cat /sys/class/power_supply/axp20x-battery/status

# Update i3status config with the correct path:
# path = "/sys/class/power_supply/axp20x-battery/uevent"

Screen tearing in i3 (X11)

X11 doesn't have built-in vsync. Use picom as a compositor:

~/.config/picom/picom.conf
# Minimal picom config for uConsole
backend = "glx";
vsync = true;
glx-no-stencil = true;
glx-no-rebind-pixmap = true;

# Disable all effects (we just want vsync)
shadow = false;
fading = false;
inactive-opacity = 1;
frame-opacity = 1;

Sway doesn't have this issue — Wayland handles compositing natively.

WiFi/Bluetooth tray icons missing

i3 doesn't run system tray applets by default.

~/.config/i3/config — enable system tray
# Add nm-applet for network management:
exec --no-startup-id nm-applet

# For Bluetooth:
exec --no-startup-id blueman-applet

# Make sure tray is enabled in bar config:
bar {
  # ... existing config ...
  tray_output primary
  tray_padding 2
}

# Sway equivalent — use tray protocol:
# In waybar config, add "tray" to modules-right
09 — Skip the Setup

Skip the setup — get i3/Sway pre‑configured.

The Pocket Forge Toolkit ships with i3 and Sway pre-installed, tuned for the uConsole's keyboard and display. Status bars configured, keybindings optimized, companion tools included. Flash the SD card and you're tiling in 15 minutes.

i3 + Sway readyWaybar configuredOptimized keybindstmux + ranger30+ packages

Not ready to buy?.

Join the waitlist for Pocket Forge updates — new guides, i3/Sway config tweaks, and early pricing. No spam, just signal.

>

Your email is stored securely. Unsubscribe anytime.