🚧 Experimental. API and package structure may change.
ModGadget is a lightweight UI and device toolkit for building structured TinyGo applications on small embedded systems.
modgadget-demo.mp4
It provides text layout, multilingual bitmap-font support, viewports, scrolling, direct keyboard events, display integration, and audio support without requiring a full-screen framebuffer.
ModGadget is currently developed primarily for the M5Stack Cardputer ADV and the TinyGo m5stamp-s3a target.
This minimal Cardputer ADV application configures the display and renders one text Viewport:
//go:build tinygo
package main
import (
"time"
"github.com/rdon-key/modgadget"
"github.com/rdon-key/modgadget-fonts/efont16"
board "github.com/rdon-key/modgadget/device/cardputeradv"
)
func main() {
time.Sleep(3 * time.Second)
panel, err := board.ConfigureDisplay()
if err != nil {
panic(err)
}
gadget := modgadget.New(panel, modgadget.WithStyles(modgadget.StyleSet{
Default: modgadget.Style{
Font: efont16.Font,
Foreground: modgadget.ColorWhite,
Background: modgadget.ColorBlack,
},
}))
if err := gadget.Clear(); err != nil {
panic(err)
}
view := gadget.Viewport(modgadget.Bounds(0, 0, board.DisplayWidth, 16))
if err := view.SetText("Hello, ModGadget!"); err != nil {
panic(err)
}
if err := gadget.Render(); err != nil {
panic(err)
}
for {
time.Sleep(time.Second)
}
}From the application module containing this main.go, build with:
tinygo build -target=m5stamp-s3a .For complete standalone applications that consume ModGadget and ModGadget Fonts as external module dependencies, see ModGadget Examples.
Current functionality includes:
- RGB565 display output through a small
Displayinterface - ST7789 support for the Cardputer ADV
- Unicode text layout and drawing
- Public bitmap-font API
- Named text styles and simple markup
- Synthetic bold text
- Viewports with clipping
- Horizontal scrolling
- Direct keyboard events
- Cardputer ADV keyboard integration
- Cooperative audio playback
- Software volume control
- Small reusable rendering buffers instead of a full-screen framebuffer
For the current high-level API, see Public API.
For keyboard-event details, see Keyboard API.
Rdon Type 100 is a complete multilingual typing game for the M5Stack Cardputer ADV built entirely on ModGadget's public APIs.
It combines:
- Japanese, English, Simplified Chinese, and Korean text
- multilingual bitmap fonts
- styled text layout
- Viewports and scrolling
- direct keyboard input
- Cardputer ADV display integration
- cooperative audio playback
- software volume control
A prebuilt firmware image is available from the Rdon Type 100 Releases page.
Practical examples that demonstrate individual or combined ModGadget features are available in:
The examples cover multilingual text rendering, horizontal scrolling, application-level vertical document scrolling, audio, and keyboard-driven applications.
Small API-focused examples may also be kept in this repository when they are useful for documenting an individual API.
Generated fonts are distributed separately by:
Applications can import ready-to-use packages such as:
github.com/rdon-key/modgadget-fonts/efont16
github.com/rdon-key/modgadget-fonts/efont24
ModGadget provides the public Font API together with font validation, measurement, layout, and drawing.
Applications can:
- inspect character coverage with
Font.HasGlyph - inspect line metrics with
Font.Metrics - load embedded MGF data with
OpenMGF - combine fonts with
NewFontStack - measure styled text with
MeasureText
Glyph bitmaps and the internal font engine are intentionally not public APIs.
See the MGF1 file format for the binary font specification.
Font sources, provenance, generation, and validation are maintained separately in modgadget-font-assets.
A ModGadget application creates a Gadget around a display and optional device services.
Text is normally placed inside rectangular Viewport regions.
A Viewport can contain styled Unicode text and can either be drawn statically or configured for horizontal scrolling.
Gadget.Update advances time-dependent state and processes input. Gadget.Render draws Viewports that need updating.
This keeps the application loop explicit and suitable for small cooperative embedded systems.
ModGadget does not require a full-screen framebuffer.
Static content can be rendered directly to the display.
Operations that require buffering, such as scrolling Viewports, use buffers sized to the affected region rather than the entire screen.
For example, an RGB565 240×24 Viewport requires:
240 × 24 × 2 = 11,520 bytes
Reusable buffers are retained where practical to avoid repeated steady-state allocations.
See Public API for detailed rendering and memory behavior.
ModGadget provides generic display, text, input, and device abstractions, but the only complete board integration currently included is the M5Stack Cardputer ADV, based on the M5Stamp-S3A.
That integration covers:
- ST7789 240×135 display
- Cardputer ADV keyboard
- Cardputer ADV audio hardware
Hardware-specific integration is kept separate from the generic display, text, input, and audio APIs where practical. Other hardware may implement those interfaces, but ModGadget does not currently provide another complete board integration.
A TinyGo development build from the current dev branch is required for
Cardputer ADV applications. The m5stamp-s3a target is not yet included in a
stable TinyGo release.
Applications using ModGadget are built normally with TinyGo, for example:
tinygo build -target=m5stamp-s3a .
For working standalone programs, see ModGadget Examples.
For complete TinyGo setup, firmware build, and flashing instructions, see Rdon Type 100.
| Repository | Purpose |
|---|---|
| rdon-type100 | Complete multilingual Cardputer ADV application |
| modgadget | UI, display, input, and device toolkit |
| modgadget-fonts | Importable MGZ bitmap-font packages |
| modgadget-examples | Standalone ModGadget examples |
| modgadget-font-assets | Font sources, provenance, generation, and validation |
Possible future work includes:
- General UI widgets
- Touch and pointer input
- Focus and widget event propagation
- Z-index and composition
- Automatic vertical scrolling
- Viewport resizing and removal
- Text input and IME support
- Hardware scrolling
- Panel-specific color profiles
These are not required for the current ModGadget application model and may evolve as the API develops.
ModGadget is experimental. API compatibility between revisions is not yet guaranteed.
The goal is not to reproduce a desktop GUI framework. ModGadget focuses on small, explicit UI primitives suitable for resource-constrained TinyGo applications.
BSD 3-Clause.
Parts of the ST7789 implementation are derived from tinygo.org/x/drivers/st7789.
See LICENSES/tinygo-drivers-BSD-3-Clause.txt.