A macOS menu bar app for the Modos Paper Dev Kit (the Glider board) — change display mode, contrast, lightness and auto-clear from your Mac instead of the on-screen menu.
Includes a small firmware patch, because the stock firmware doesn't expose these settings to a host at all.
Glider firmware 1.0 already stores everything the OSD controls:
int update_mode;
int lightness; // -3 … 3
int contrast; // -1 … 6
int autoclear_mode;
int autoclear_interval;
int autoclear_threshold;
int osd_scale_2x;…but none of it was added to the setcfg variable table in
fw/User/shell/shell_cmds.c, and the USB HID command set has no read command
of any kind. So on stock firmware a host cannot set these values, and cannot
even discover which mode the display is currently in.
The patch in firmware-patch/ adds:
- The missing settings to
setcfg, so a host can read and write them - An
act <name>command that posts an action into the UI task's queue - A
defaultscommand restoring stock 1.0 settings - Apply hooks so tone and mode changes take effect immediately
act doesn't reimplement anything. It posts into the queue that the UI task
drains, so the action is executed by execute_button_action() — the same
function a physical button press reaches. Mode index, config_save() and
reset_autoclear_state() all happen exactly as they do for a button, so the app
and the buttons cannot drift out of sync.
The on-screen popup is suppressed for host-initiated actions only; pressing the physical buttons still shows it.
- Display modes — Browsing, Watching, Typing, Reading, using the firmware's own names and values
- Live state readback — the panel shows the mode the device is actually in, including changes made with the physical buttons
- Per-mode contrast and lightness — each preset remembers its own tone settings, reapplied on switch, with a per-mode reset
- Auto clear — mode, interval and threshold
- Input selection — with confirmation and a 15-second automatic revert to Auto, so a dead input can't lock you out
- Global hotkeys, fully rebindable, with a shortcut editor
- Start at login
- Device info — firmware version, panel geometry, VCOM, power state, wake counters
Communication is over the board's USB serial shell, so no special permissions are needed.
- macOS 13 or later (Apple silicon)
- A Modos Paper Dev Kit (Glider board) running the patched firmware
- For building firmware:
dfu-utiland an ARM bare-metal toolchain (STM32CubeIDE is not required — see below)
Download GliderControl.app from the
latest release, unzip, and drag it to
/Applications. It is ad-hoc signed, so on first launch right-click the app and
choose Open.
Then flash the patched firmware, or the app will report "Stock firmware — limited control".
git clone https://github.com/ScreenSensitive/GliderControl.git
cd GliderControl
./build.sh
open GliderControl.appRequires the Swift toolchain from Xcode Command Line Tools. No Xcode project, no dependencies.
git clone --recursive https://gitlab.com/zephray/Glider.git
cd Glider
git checkout ed94ef7fd95a42cfdcdaf5e5da1dcdd709122763 # the 1.0 release
patch -p1 < /path/to/GliderControl/firmware-patch/host-control.patchUpstream builds the MCU firmware through STM32CubeIDE's headless Eclipse
builder. That's a multi-gigabyte install behind an ST account. A plain Makefile
derived from .cproject works instead:
# ARM GNU toolchain (needs newlib — Homebrew's arm-none-eabi-gcc lacks it)
curl -LO https://developer.arm.com/-/media/Files/downloads/gnu/14.3.rel1/binrel/arm-gnu-toolchain-14.3.rel1-darwin-arm64-arm-none-eabi.tar.xz
tar xf arm-gnu-toolchain-14.3.rel1-darwin-arm64-arm-none-eabi.tar.xz
export PATH="$PWD/arm-gnu-toolchain-14.3.rel1-darwin-arm64-arm-none-eabi/bin:$PATH"
cp /path/to/GliderControl/firmware-patch/Makefile fw/Makefile
cd fw && make -j8 # -> build/glider_ec_rtos.binEnter DFU: unplug, hold the button nearest the USB port, plug back in — connected directly to the host, not through a hub.
dfu-util -a 0 -i 0 -s 0x08000000:leave -D build/glider_ec_rtos.bindfu-util: Error during download get_status on leave is harmless; the board
reboots before the final status can be read.
The STM32's DFU bootloader is in ROM, so a bad build is always recoverable with the button. An MCU rebuild does not touch the FPGA bitstream or the SPIFFS filesystem.
dfu-util -a 0 -i 0 -s 0x08000000:leave -D glider_ec_rtos.bin # stock 1.0Back up your own board before flashing anything — the MCU image over DFU, and
config.bin / fpga.bit over the stock firmware's YMODEM send command.
act <name> next_mode prev_mode browsing watching typing reading
clear toggle_ac input_auto input_tmds input_dp
defaults reset settings to stock 1.0 values
help doesn't list them — there's a separate help table upstream that the patch
doesn't populate. They work regardless.
setcfg get <key>ignores the key and prints everything. Pre-existing upstream behaviour (argc < 4whereargcis 3).USBCMD_POWERDOWN/USBCMD_POWERUPare empty stubs upstream, so the app offers no sleep/wake.power offworks but has no reliable wake.- Contrast is a slope about the midpoint, so high values crush midtones enough that dithering visibly disappears. This is expected, not a bug.
- Changing mode does not redraw; existing pixels keep the previous waveform's drive history until a full refresh. The app refreshes automatically (toggleable).
- Built and tested against the 13.3" Modos Paper Dev Kit (1600x1200 mono). Not tested on the 6" dev kit, and not applicable to the Modos Flow, which is a different product with its own firmware.
See NOTES.md for protocol details, gotchas and open issues.
Use at your own risk. This software is provided "as is", without warranty of any kind.
This project modifies the firmware of your hardware. Although the STM32's DFU bootloader lives in ROM and a bad build is recoverable with the button, flashing firmware always carries risk. Neither the author nor Modos Labs is responsible for any damage, data loss, bricked hardware, voided warranty or other loss arising from use of this software, the patch or the prebuilt binaries.
Specifically:
- This is an unofficial project, not affiliated with or endorsed by Modos Labs. Do not ask them to support a board running this firmware.
- Flashing custom firmware may void your warranty.
- The prebuilt binary was built for a 13.3" 1600x1200 mono Modos Paper Dev Kit. Flashing it to different hardware is untested.
- Back up your board before flashing — the MCU image over DFU, and
config.bin/fpga.bitover the stock firmware's YMODEMsendcommand. Instructions are in NOTES.md. - Some settings, VCOM in particular, can degrade image quality or damage the panel if set incorrectly. The app deliberately does not expose VCOM.
By using this software you accept full responsibility for the outcome.
If this turned out to be a nice addition to your dev kit, you can buy me a coffee — entirely optional, and very much appreciated.
The Glider hardware, Caster gateware and Grimoire firmware are by Modos Labs / Wenting Zhang, MIT licensed. The firmware patch here is a small change on top of their 1.0 release; all credit for the underlying work is theirs.
MIT for this app and the patch, matching upstream.