Keypad User Guide
ENไทยOpen the studioFirmware

Touch Macro Keypad

A 3.5" touchscreen macro keypad built on the Guition JC3248W535C, designed entirely from your browser.

Open Macro Keypad StudioInstall firmwareSource on GitHub

1. What it is

Types on your computerA USB keyboard when plugged into a PC or Mac; a Bluetooth keyboard when it runs on a charger or battery.
Designed in the browserPages, keycaps, icons, pictures, backgrounds, effects and macros - all in Macro Keypad Studio.
Updates with one clickNew firmware installs over USB from the studio; the keypad restarts by itself.
Click sound on the PCThe studio plays a key-click on your speakers every time you tap the keypad.

You need

  • A Guition JC3248W535C board (ESP32-S3, 3.5" 320×480 touchscreen).
  • A USB-C data cable (charge-only cables don't work).
  • Chrome or Edge on a computer (Windows, macOS, Linux, ChromeOS) - other browsers can't talk to USB/Bluetooth devices.

2. First-time install

  1. Plug the board into the computer.
  2. Open the Firmware page and click Install firmware.
  3. Pick the port called USB JTAG/serial debug unit and confirm. Installing takes about a minute.
  4. When it's done the keypad restarts and shows Macro Keypad v…, then the default layout.
"Failed to initialize"? The board isn't in install mode. Unplug it, hold the BOOT button (one of the two tiny buttons in the hole on the back), plug it back in, release BOOT, then try again. The screen stays dark in this mode - that's normal. Press RESET (or re-plug) after installing.

After the first install you never need the BOOT button again - see Updating firmware.

3. Connect

As a keyboard

  • USB: plug it into the computer - it types immediately. The keypad's top bar shows USB.
  • Bluetooth: power it from a charger or battery. The top bar shows BLE… while it waits; pair Macro Keypad in your computer's Bluetooth settings like any keyboard. Then it shows BLE.
  • --- means it isn't connected to anything, so taps can't type.

To the studio

  1. Open the studio in Chrome/Edge.
  2. Click USB (recommended) or Bluetooth at the top and choose the keypad.
  3. The chip turns green, e.g. USB · fw 1.4.0.

Bluetooth can save layouts and macros, but pictures, keycap designs and firmware updates need USB.

4. Design your keys

Click a key on the studio's screen to select it. Drag to move it, drag the white corner to resize. Try it (above the screen) lets you tap keys to preview effects and sounds.

Pages & layout

  • Pages (left panel): add, duplicate, reorder, rename. More than one page adds the < > bar at the bottom of the keypad.
  • Layout grid: set rows, columns, margin and gap, then Arrange keys in grid.
  • Background: a colour, a gradient or a picture (with fit and darken).
  • Screen orientation (Keypad tab): portrait, landscape (keypad turned left or right) or upside-down. The board has no tilt sensor, so you choose it here.

Keycap tab

  • Label: any text, any language, emoji. Font, size, weight, colour, position and text transparency (0 % solid - 100 % invisible).
  • Icon: click Choose icon… for a searchable table of 1,800+ free icons (search "copy", "volume", "mail"…). Choose colour, size and placement: above the label, left of it, or icon only.
  • Keycap style: flat, 3D, glass, outline, neon or picture; colour and corner rounding.
  • Picture: Choose picture… or simply drag a photo onto a key on the screen. Fit: fill, fit inside, or small icon above the label.
  • Picture across keys (left panel): one picture spread over all keys of a page - each key shows its part. A key's own picture wins.
  • Apply … to This page / All pages: copy the selected key's text & icon style, or its keycap & picture layout, to the other keys.

5. Actions & macros

The Action tab lists what a key types, top to bottom:

  • + Shortcut - modifier boxes (Ctrl, Shift, Alt, Win/Cmd) plus a key. Easiest: click Press keys… and press the shortcut.
  • + Text - types a piece of text.
  • + Pause - waits (up to 10 s).
  • ● Record keys - type on your keyboard, click Stop. Tidied into text and shortcuts, or tick Keep exact timing to replay precisely.
  • Drag steps (⋮⋮) or use ↑ ↓ to reorder; Run on keypad tests it.
On a Mac use Win/Cmd, not Ctrl: Copy = Cmd+C, Paste = Cmd+V. The built-in sample keys use Ctrl (Windows).
Text is typed with the US keyboard layout and plain characters (A–Z, digits, punctuation). Labels can use any language - only typed text is limited.

6. Motion, light & sound

  • Press motion: push, pop, sink, bounce or none.
  • Light: glow, ripple, flash or outline, with colour and speed. Apply … to whole page copies it.
  • Idle ambient light (Keypad tab): breathe, rainbow or wave after a few seconds without touches.
  • Brightness & dimming (Keypad tab): the screen dims after a while; the first touch only wakes it.
  • Click sound on PC (Keypad tab): pick a sound or upload your own. It plays while the studio is open (or installed as an app via the address bar) and connected.

7. Save to keypad vs. Update firmware

Save to keypadUpdate firmware
SendsYour design: pages, keys, pictures, icons, effects, macrosThe keypad's program
WhenAfter every design changeOnly when a new version is available
Keypad restarts?No - shows "Saved"Yes, by itself
Changes your layout?YesNo, it's kept

The Save to keypad button shows an orange dot when the keypad doesn't have your latest design, and Saved ✓ when it does.

8. Updating firmware

  1. Connect the studio over USB.
  2. Open the Keypad tab → Firmware. It shows the installed and latest version.
  3. Click Update to x.y.z. The keypad shows "Updating n %", restarts by itself and the studio reconnects. No buttons needed; your layout is kept.

Keypads older than 1.3.0 show Update … (one-time setup): the keypad switches itself into install mode and the Firmware page opens - click Install, pick USB JTAG/serial debug unit, then Save to keypad once (this one-time step clears the keypad's storage; your design stays in the browser).

To see which version a keypad runs: the small grey number in its top bar, the startup screen, or hold the top bar for 1.5 s.

9. Troubleshooting

Tapping a key does nothing
  • Look at the keypad's top bar: --- means it isn't connected - plug in USB or pair Bluetooth.
  • In the studio's Keypad tab, Typing via should say USB or BLE. Update the firmware if it says NONE on an old version.
  • On a Mac, Ctrl shortcuts do nothing in most apps - change them to Win/Cmd.
  • If the screen was dim, the first tap only wakes it.
No click soundThe studio must be open and connected, Play a click… ticked (Keypad tab), volume up, and the key's own sound not set to "No sound". Click anywhere in the studio once - browsers only allow sound after a click.
"Save failed: crc mismatch"Fixed in studio build 6515159 / firmware 1.3.2. Reload the studio (Cmd/Ctrl+Shift+R) and update the firmware.
Firmware page: "Failed to initialize" or stuck at "wrapping up"Use the studio's Update firmware button instead. If you must use the Firmware page: hold BOOT while plugging in, pick USB JTAG/serial debug unit; if it stays on "wrapping up" after 100 %, just close it and press RESET.
The studio page froze ("Page Unresponsive")Fixed in studio build 85d9c74. Reload with Cmd/Ctrl+Shift+R.
Pictures don't appear on the keypadPictures and keycap designs only transfer over USB. Connect over USB and Save again.
Landscape looks upside downChoose the other landscape option in the Keypad tab and Save.
Start overExport your design first (Export button). Then Load from keypad / Import, or use the Firmware page with Erase to wipe the keypad completely.

10. Credits & licences