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.
Why i3/Sway is perfect for the uConsole
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:
No title bars, no decorations, no gaps by default. Every pixel is your app.
Perfect for the uConsole's compact keyboard. No trackball gymnastics needed.
i3 uses ~5MB RAM. More memory for your actual work on the CM4's limited 1–8GB.
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 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).
Installing i3 and Sway
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:
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.
# 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.
# 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.
# 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:
# 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.
Keybindings for the uConsole keyboard
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):
# ─── 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
# ─── 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:
# ─── 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).pngStatus bar — battery, WiFi, CPU temp
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:
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
}
}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:
# Use waybar instead of swaybar
bar {
swaybar_command waybar
}{
"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}"
}
}* {
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/.
Multi-workspace workflow for the small screen
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
Auto-assign apps to workspaces
# 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
# 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.
Screen resolution & scaling tweaks
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:
[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
# 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)
! 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
# 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:
# 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×.
Recommended companion tools
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.
# 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.
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.
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
# 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:
# 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
Common issues & uConsole-specific fixes
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.
# 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.
# 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.
# 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.
# 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:
# 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.
# 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-rightBattery Life Guide
i3/Sway use less power than full DEs — combine with these tweaks for even longer runtime.
Read guide →Retro Gaming & Emulation
A lightweight WM gives emulators more resources — set up RetroArch on your tiled desktop.
Read guide →Overclocking Guide
Push your CM4/A06 further for demanding workloads.
Read guide →Bluetooth Audio Setup
Get wireless audio working alongside your tiling WM setup.
Read guide →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.
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.