Buy or Build

Buy one pre-assembled — R1,099 shipped in SA. You get the device in a 3D-printed enclosure, a USB-C cable, and the latest firmware pre-flashed. Available for free local pickup in Newcastle KZN.

Or build your own — source the parts and assemble it yourself:

• CYD: E32R28T from Robotics.org.za (R342.70 incl VAT) — or any ESP32-2432S028R / "Cheap Yellow Display". The E32R28T is pin-compatible with the standard CYD and works with all SudoDeck firmware
• Enclosure: 3D-printed shell — from NDE3D ~R170, or print your own from the open-source STL files
• USB cable: Any USB-C data cable (charge-only cables won't work for serial/flashing)

Total DIY cost: ~R515 + your time. Assembly takes about 10 minutes — slide the CYD into the enclosure, plug in the USB, done.

Flash the Firmware

If you bought a pre-assembled SudoDeck, the latest firmware is already installed — skip to step 3.

For DIY builds: your CYD comes with factory demo software. You need to replace it with SudoDeck by putting the board into flash mode:

1. Plug the CYD into your computer via USB
2. Hold the BOOT button (GPIO0, top-left edge of the board)
3. While holding BOOT, tap RESET (EN, top-right edge) — the screen goes blank
4. Release BOOT — the CYD is now in download mode, waiting for firmware
5. On the Configure page, click Connect for Flashing and select the CYD's serial port in the browser dialog
6. Choose your firmware variant — Standard (BLE) for Bluetooth or Wired (Serial) for USB keystroke injection — then pick a version and click Flash
7. Wait for the progress bar to reach 100% — the CYD reboots automatically and boots into SudoDeck

Connect & Configure

Once flashed, the CYD boots into SudoDeck. The display shows a grid of buttons (default 4×3) and a status bar. Leave it plugged into USB — this provides both power and a serial data connection to the config tool.

1. Open the Configure page in Chrome or Edge (Web Serial is not supported in Firefox or Safari)
2. Click Connect — your browser will show a list of serial devices. Select "USB Serial Device" or "CP2102/CH340" (the CYD's USB-serial chip)
3. Once connected, the badge switches from red DISCONNECTED to green CONNECTED
4. Click Read to pull the current layout from the device into the browser
5. Edit pages, place buttons, pick colors, and assign actions
6. Click Write to save your layout to the CYD's flash memory

The reset button (small hole) and USB-C port are on the back. The BOOT button is on the top edge inside the enclosure.

Wired Mode Setup ADVANCED

Instead of Bluetooth, you can use the CYD as a wired keyboard over USB. The CYD sends keystrokes over the serial connection, and a companion daemon (installed on your computer) injects them as if they came from a physical USB keyboard.

Choose this if your computer doesn't have Bluetooth, you want lower latency, or you prefer a single-cable setup.

1. Flash the Wired Firmware

You need the wired firmware variant on the CYD:

1. Put the CYD in flash mode (hold BOOT, tap RESET, release BOOT)
2. Open the Firmware Tool
3. Click Connect for Flashing and select the CYD's serial port
4. Select the Wired (Serial) variant using the radio buttons
5. Pick the latest wired firmware version from the dropdown and click Flash
6. Wait for the progress bar to reach 100% — the CYD reboots automatically

2. Install the Daemon

The daemon is a small background program that reads keystrokes from the CYD over USB and injects them into your OS.

Linux

# Download the latest release
curl -L -o sudodeckd https://github.com/sudobreakstuff/sudodeck/releases/latest/download/sudodeckd-linux-amd64
chmod +x sudodeckd

# Run it (stays open, Ctrl+C to stop)
./sudodeckd

# Install as a systemd user service (auto-start on login)
./sudodeckd --install

Windows

# Run as Administrator (required for SendInput API)
sudodeckd-windows-amd64.exe

# Install as a Windows service (auto-start on boot, run as Administrator)
sudodeckd-windows-amd64.exe --install

macOS

chmod +x sudodeckd-darwin-*

# Run it (foreground)
./sudodeckd-darwin-*

# Install as a LaunchAgent (auto-start on login)
./sudodeckd-darwin-* --install

macOS will ask for Accessibility permission on first run — grant it in System Settings → Privacy & Security → Accessibility. Without it, keystroke injection is blocked.

3. Plug and Play

1. Plug the CYD into USB — the daemon auto-discovers it within 5 seconds
2. The daemon logs show Device found: /dev/ttyUSB0 (SudoDeck) or similar
3. Tap any button on the CYD — the keystroke is injected into your OS immediately
4. The CYD's header shows USB instead of a Bluetooth icon, confirming wired mode is active

Configuring the CYD

You can still use the config tool to edit buttons while the daemon is running. The tool automatically coordinates with the daemon:

1. Open the Configure page as normal
2. Click Connect — the config tool tells the daemon to release the serial port first
3. Read, edit, and write your layout as usual
4. When you disconnect from the config tool, the daemon picks up the port again automatically

Pair via Bluetooth

Skip this step if you're using Wired Mode — wired and BLE are mutually exclusive. The CYD runs one firmware at a time.

The CYD announces itself as a Bluetooth keyboard. Pair it with your computer, phone, or tablet just like any other Bluetooth device.

1. Keep the CYD powered (USB plugged in) — there is no battery, it needs USB power to run
2. Open Bluetooth settings on your target device
3. Look for SudoDeck in the list of available devices and select it to pair
4. Some devices will show a confirmation code — confirm it
5. Once paired, the CYD's header shows a Bluetooth icon (macOS/iOS) or "BT" text (Windows/Android/Linux)

Pairing is stored on both sides — you only need to do it once. The CYD will auto-reconnect whenever it's in range and powered on.

Bluetooth Details

• Range: ~10 metres (33 feet) open air, less through walls
• Reconnection: automatic — when the CYD powers on and the paired device is in range, it connects within a few seconds
• Single device: BLE HID can only be connected to one device at a time. To switch devices, unpair from the current one and pair with the new one
• Standard HID: no drivers, no software, no configuration needed. Your OS sees it as a regular Bluetooth keyboard and mouse (keyboard only in the current firmware)
• Connection indicator: top-left of the CYD display — Bluetooth icon (Apple-style) when paired to macOS/iOS, "BT" text for anything else. No icon means BLE is initializing or failed

Use It

Once paired, every button press on the CYD sends the assigned action to the connected device — just like pressing keys on a keyboard.

Display Overview

• Top bar (status): shows Bluetooth connection icon, WiFi status, and current time. The bar is dark teal
• Grid area: your configured buttons, each with a background color and label. Buttons are rounded rectangles with the label centered
• Bottom bar (navigation): < and > arrows to move between pages. The center shows the current page name and a counter like 3/12

How Buttons Work

• Tap a button on the touchscreen — it flashes briefly (highlight color) then fires the action
• Labels longer than the button width are truncated with ... automatically — keep labels short (under ~12 characters for 4-column layouts)
• Empty buttons (no label, no action) appear dark and do nothing when tapped

Page Navigation

• Tap < (bottom-left) to go to the previous page
• Tap > (bottom-right) to go to the next page
• The page counter in the bottom bar shows your current position, e.g. 5/18
• The page name is editable in the config tool (double-click the page tab)

Display Sleep

• After the screensaver timeout (default 30s, configurable 5-600s), the screensaver activates
• After the sleep timeout (default 60s, configurable 0-600s, 0=off), the display backlight turns off entirely to save power
• Tap the touchscreen anywhere to wake from screensaver or sleep — the grid reappears instantly
• Sleep only affects the display — Bluetooth stays connected and buttons still work if pressed (but you can't see them until you wake the screen)

Action Types

Each button can be assigned one of six action types. Here's what they do and when to use them:

Key Name Reference

Use these exact key names in the config tool:

Modifier Keys (for Combos)

Available modifiers: CTRL, ALT, SHIFT, GUI (Windows key / Cmd), and combinations like CTRL_SHIFT, CTRL_ALT, CTRL_ALT_SHIFT, etc.

Macro Tips

• Macros execute each step sequentially. There is no hard step limit, but very long macros (>50 steps) may take several seconds to run
• Use Delay steps to wait for UI elements to appear before typing or pressing keys
• Example: open Task Manager: CTRL+SHIFT+ESC → delay 1000ms → ALT+T (focus details)
• Macro steps are edited in the config tool's action panel — add, remove, and reorder steps freely

App Launcher Notes

The App Launcher uses the OS search function:
Windows → Win key → type app name → Enter
macOS → Cmd+Space (Spotlight) → type app name → Enter
Linux → Super key (GNOME/KDE) → type app name → Enter

Use the exact display name of the app (e.g. "Visual Studio Code" not "code"). The paired device must be at its desktop or home screen — the launcher types into the OS search, not an already-open dialog.

Layouts: Pages, Grid & Backup

Your button layout is organised as a grid of pages. Each page has a configurable number of columns and rows, and each cell holds one button with a label, color, and action.

Layout Controls

Found at the bottom of the config tool:

• Columns: 1 to 6 (default 4)
• Rows: 1 to 5 (default 3)
• Pages: 1 to 18 (default 3)

Click Apply Layout to resize. Existing button data is preserved — when you shrink the grid (e.g. 4×3 → 3×2), extra buttons remain in memory and reappear if you expand again. No content is lost.

Page Tabs

• Page tabs run across the top of the grid area in the config tool
• Click a tab to switch to that page for editing
• Double-click a tab to rename the page

Editing a Button

• Click any button in the grid to select it — it highlights with a border
• The Edit Button panel opens below the grid
• Set the label (displayed on the CYD), color (hex value, or use the color picker), and action type with its parameters
• Click Apply to save changes to the current button, or Cancel to discard

Export, Import & Share

The config tool supports exporting and importing your entire layout as a JSON file. The buttons are at the top of the config section:

• Export — downloads a .json file with your full layout (all pages, buttons, colors, actions, WiFi, and screensaver settings)
• Import — loads a previously exported .json file back into the config tool. After importing, you must still click Write to send it to the device
• Share — exported JSON files can be sent to other SudoDeck users. They import the file and write it to their device. Build a library of layouts for different workflows

Screensaver & Live Widgets

When idle, the CYD displays a screensaver. Three modes are built in:

• Matrix Rain — falling green characters across the display. No WiFi needed. Classic look, runs entirely on-device
• F1 Standings — live Formula 1 race calendar, driver standings, and constructor standings — cycles through three views. Requires WiFi
• Custom Widgets — user-defined API endpoints displayed as live data cards that cycle every 10 seconds. Requires WiFi

Configure screensaver timeout, sleep timeout, and mode in the Screensaver section at the bottom of the config tool. Click Set to apply changes (then Write to save to the device).

Custom Widgets

Add one or more widget sources below the Screensaver section. Each widget has these fields:

Use the Test button on each widget to verify your URL and path before writing to the device. Widgets cycle every 10 seconds on the CYD display.

Widget Examples

Automations

Automations let you send keystrokes or sequences on a timer or schedule — no button press needed. Configure them in the app under the Automations panel.

Types

• Timer — runs an action every N seconds (e.g. press F5 every 10s to refresh a dashboard)
• Schedule — runs an action at a specific time (HH:MM) on selected days of the week (1=Sunday, 7=Saturday)

Enable / Disable

• Per-automation — each automation has an ON/OFF toggle button in its card in the Automations panel. Disabled automations are skipped.
• From the CYD — assign any button the Auto Toggle action type (in the button editor), then pick which automation it controls. The button shows green when the automation is ON and red when OFF. Tap it to toggle.

Actions

Each automation runs one action (key, combo, text, delay, or app launch) — the same set of action types available for buttons.

WiFi Setup

WiFi is optional but required for live data features (F1 standings, custom widgets). The CYD uses the ESP32's built-in 2.4GHz WiFi.

Configuration

1. In the config tool, enter your SSID and password in the fields below the layout controls
2. Click Write to save the layout to the device — WiFi credentials are saved as part of the config
3. On the next boot, the CYD attempts to connect to the WiFi network automatically
4. Connection status appears in the top-right of the CYD's display header

Status Indicators

• Connected — WiFi icon (arcs) shown in the header
• Connecting — shows "W:connecting"
• Failed — shows "W:OFF" with an error reason code (seen in the header after a failed attempt)
• No WiFi configured — header shows nothing related to WiFi

Important Notes

• 2.4GHz only — the ESP32 does not support 5GHz WiFi networks. Make sure your router isn't hiding the 2.4GHz band
• Auto-reconnect — the CYD retries connection every 30 seconds if the connection drops
• Special characters in SSID or password — most work, but very unusual characters (non-ASCII, emoji) may cause issues over the serial connection
• WiFi credentials are stored in the config JSON on the device's SPIFFS — they persist across reboots
• Flashing new firmware erases everything — save a copy of your config with Export

Firmware Updates

Updating the firmware is the same process as the initial flash. The firmware tool on the Configure page handles everything.

1. First, Export your current layout from the config tool (Config section) — flashing erases it
2. Put the CYD in flash mode (hold BOOT, tap RESET, release BOOT)
3. On the Configure page, click Connect for Flashing
4. Select the new version from the dropdown and click Flash
5. Wait for the progress bar to complete — the CYD reboots automatically
6. Reconnect via WebSerial (Connect → Read should show a default layout)
7. Import your exported .json backup, then Write it to the device

Full Flash Backup

The Backup Firmware button reads the entire 4MB flash and saves it as a .bin file. This captures both the firmware and your config. To restore it, use the Custom .bin option in the flash tool and select your backup file. This is useful if you want to revert to a previous firmware without re-configuring everything.

Factory Reset

Two ways to reset the device to its default 3-page layout (Main, Media, Studio):

Method 1 — Config tool Reset button: Click the red Reset button in the config tool. If connected via WebSerial, it sends a factory reset command to the device (clears the config, resets screensaver settings). Then it reads the fresh default config back into the browser. If not connected, it resets the browser's config to defaults only.

Method 2 — Re-flash firmware: Flashing the firmware .bin at address 0 overwrites the entire flash including the SPIFFS config partition. This gives you a completely clean slate — fresh firmware, default config.

Common Issues

Limits & Specifications

Layout Limits

Hardware Specifications

Software Limits

Compatibility