Description

What this device is
This is a touchscreen macropad that acts like a keyboard. You tap a button, it sends shortcuts or typed text to a computer.

USB vs Bluetooth

If plugged into a computer USB port (data), it behaves like a USB keyboard.
If only powered (charger / battery), it can behave like a Bluetooth keyboard (if Bluetooth is enabled in settings).
If Bluetooth is enabled but not connected, it won’t type anywhere.

Main screen

9 macro buttons
Bottom row:
- ◄ previous page (only if you have more than 1 page)
- ► next page
- SET enters configuration mode (turns on the settings Wi-Fi)

Pages
You can have up to 10 pages of macros. Arrows rotate through pages. With only one page, arrows appear “disabled” and do nothing.

SET mode (configuration mode)
Tap SET. The device will:

Create a Wi-Fi network for configuration
Show SSID / password / IP on screen
Provide a settings site at: http://192.168.4.1/

In the settings page you can:

Change the settings Wi-Fi SSID and password
Enable/disable Bluetooth keyboard mode
Set number of pages
Set button labels (1–3 characters)
Set button actions (what it types/presses)
Recalibrate touch
Forget previously paired Bluetooth devices

Leaving SET mode
On the SET screen:

Bottom center BACK returns to the macropad and turns off the settings Wi-Fi.

Emergency touch recalibration (hidden)
If touch is broken and you can’t reach settings:

Tap the screen 10 times quickly to trigger calibration.

Actions (macro language)
Actions support combos and scripted typing.

Combos:

CTRL+ALT+T
ALT+F4
CTRL+SHIFT+ESC
CTRL+C

Text:

TEXT hello

Special keys:

KEY ENTER, KEY TAB, KEY ESC
KEY UP/DOWN/LEFT/RIGHT
KEY HOME/END/PGUP/PGDN
KEY F1 … KEY F12

Timing:

DELAY 200 (milliseconds)

Example:

CTRL+ALT+T
DELAY 300
TEXT htop
KEY ENTER

Safety:
This is a keyboard. Don’t store passwords as macros.

– – – – – – – – – – – – – – –

Download link
(Version: 1.0.0)

ninefive
(example skin)

– – – – – – – – – – – – – – –

Instructions

Beginner build + upload guide (LILYGO T-HMI ESP32-S3)

What you need

A LILYGO T-HMI (ESP32-S3) board
A USB-C cable that supports data (not charge-only)
Windows + VS Code

Step-by-step (Windows, beginner mode)

A) Install the tools

Install VS Code
In VS Code, install the extension: “PlatformIO IDE”
Let PlatformIO finish its first-time setup (it downloads toolchains)

B) Get the project

Download and unzip the MacroFi source package
In VS Code: File → Open Folder… → select the unzipped project folder (the one that contains platformio.ini)

C) Build once (checks your setup)

In PlatformIO (left sidebar) → Project Tasks → Build
If Build succeeds, your environment is good.

D) Plug in the board

Connect the device by USB-C
Windows will assign it a COM port:
- Open Device Manager → Ports (COM & LPT)
- You’ll see something like “USB Serial Device (COM5)” or similar

E) Upload (flash) to the device
Option 1 (recommended): auto-detect the port

In platformio.ini, make sure there is NO upload_port = COMxx
Then PlatformIO → Project Tasks → Upload

Option 2: set the COM port explicitly (for people with issues)

In platformio.ini, add or edit these lines to match your port:

upload_port = COM5 monitor_port = COM5
Then Upload again

If upload fails (“port busy” / “not found”)

Close any Serial Monitor or other program using that COM port
Force bootloader mode:
1. Hold BOOT
2. Tap RESET
3. Release RESET
4. Release BOOT
5. Upload again

Skin / theme installation and customization

MicroSD format

FAT32 (MBR). Quick format is fine.
Images: BMP, 24-bit, uncompressed.

Folder structure
Create a theme folder like:

Image sizes (current landscape layout)

background.bmp and set_background.bmp: 320 × 240
All btn_*.bmp: 94 × 48
Optional /macro/0.bmp … 8.bmp: 94 × 48

Pressed/disabled visuals

Pressed images are shown briefly when you tap (click feedback).
Disabled controls are rendered in the “pressed/sunken” look.

Optional per-button art (first page only)
If you provide /macro/0.bmp … 8.bmp, those custom graphics only apply to page 1. Other pages use btn_macro.bmp so you don’t need to create endless per-page art.

Install steps

Format microSD FAT32
Copy your theme folder under /skins/
Insert microSD into the device
Enter SET mode and switch themes using the THEME button
Exit SET to return to macropad mode

Customize safely
If a file is missing or wrong format, the firmware falls back to the built-in UI automatically, so experimentation won’t break the device.

– – – – – – – – – – – – – – –