Ize Compose

Repository moved

This repository is no longer updated. Future updates will be maintained at ize-studio/ize-compose.

Ize Compose is a community multilingual firmware project for the Zerowriter Ink (Inkplate 5 V2).

It explores Korean, UTF-8, and global text input on the ESP32-based Ink platform. Started as a Korean-input firmware, it now supports 92 keyboard layouts across dozens of scripts.

This is an independent personal/community firmware, not an official Zerowriter release.

Current release: v1.1.1

v1.1.1 improves Arabic-script connected glyph rendering and adds a clean install package layout under Ize-compose/.

Hardware scope warning

This repository is currently released for Zerowriter Ink only. Even if another device has an ESP32 and an e-ink display with matching or similar specifications, this code and firmware should not be treated as a general Inkplate/ESP32 writing firmware yet.

In particular, the keyboard input path is written for the current Zerowriter Ink hardware configuration. If the keyboard, keyboard controller, wiring, or input method changes, the input-handling code must be reviewed and modified before use.

---

Supported Device

• Zerowriter Ink (Inkplate 5 V2)
  • ESP32, 800×600 monochrome e-ink display
  • Requires SD card for non-Latin fonts and document storage

---

Features

Writing

• Plain-text editing with cursor navigation
• Phonetic Korean composition (cho/jung/jong jamo assembly)
• Latin accent cycling (e.g., a → á → â → ã → ...)
• Right-to-left (RTL) text mode for Arabic-script layouts
• Text search (Ctrl+F)
• Copy / paste (Ctrl+C / Ctrl+V)
• Word and character count (3 display modes)

Keyboard & Language

• 92 keyboard layouts selectable from the system menu
• Two independent layout slots: one for English (QWERTY or Dvorak), one for a second language
• 12 script composition engines: Korean, Arabic, Indic scripts, Thai, Myanmar, Khmer, Lao, Tibetan, Sinhala, Ethiopic, Japanese, Hebrew
• RTL layout support: Arabic, Hebrew, Kurdish (Arabic), Pashto, Persian, Urdu

Files

• Saves and loads .txt files on SD card (/ize_compose/)
• File browser (up to 65 files)
• WiFi (AP mode) for uploading/downloading text and firmware OTA via browser

Display

• Partial screen update for fast typing feedback
• Configurable full-refresh threshold
• Boot/sleep image loaded from /ize_compose/initial.png on SD card
• Sleep mode: Ctrl+L or sleep button; wake with wake button

Settings (system menu)

• Line spacing
• Typing speed (key repeat delay)
• Screen refresh limit
• Keyboard layout selection
• Font slot

---

Keyboard Layouts (92)

Dvorak, QWERTY, 한국어, Shqip, العربية, Հայերեն, Deutsch (AT/DE/CH), Azərbaycanca, Беларуская, Nederlands (BE/NL), বাংলা, Bosanski / Босански, Português (BR/PT), Български, Français (CA/FR/CH), Català, Hrvatski, Čeština, Dansk, देवनागरी, Eesti, ኢትዮጵያ, Føroyskt, Suomi, Georgian, Ελληνικά, ગુજરાતી, Hausa, עברית, Magyar, Íslenska, Gaeilge, Italiano, 日本語, ಕನ್ನಡ, Qazaq / Қазақ, ខ្មែរ, Kurdî / کوردی, Кыргызча, ລາວ, Español América, Latviešu, Lietuvių, Lëtzebuergesch, മലയാളം, Malti, Māori, Română (MD) / Молдовеняскэ, Монгол, Crnogorski / Црногорски, မြန်မာ, नेपाली, Македонски, Norsk, پښتو, فارسی, Polski, ਪੰਜਾਬੀ, Română, Русский, Srpski / Српски, සිංහල, Slovenčina, Slovenščina, Español, Kiswahili, Svenska, Тоҷикӣ, தமிழ், తెలుగు, ไทย, བོད་སྐད, Türkçe, Українська, English UK, اردو, Oʻzbek / Ўзбек, Tiếng Việt, Cymraeg

---

Font Files

The firmware has a built-in Latin fallback font. The full Latin font and all non-Latin script fonts are loaded from SD card at boot when the font files are present.

In the v1.1.1 install package, these files are already arranged under:

Ize-compose/sdcard/ize_compose/hwalja/

Copy the contents of Ize-compose/sdcard/ to the root of the SD card. The device expects the font files in /ize_compose/hwalja/.

File	Scripts covered
hwalja_hangul.bin	Korean (Hangul syllables)
hwalja_jamo.bin	Korean (Jamo, composition glyphs)
hwalja_latin.bin	Latin and Latin extended
hwalja_jp.bin	Japanese (Hiragana, Katakana)
hwalja_greek_cyrillic.bin	Greek, Cyrillic
hwalja_arabic.bin	Arabic, Persian, Urdu, Pashto, Kurdish Arabic
hwalja_indic.bin	Devanagari, Bengali, Gujarati, Kannada, Malayalam, Punjabi, Tamil, Telugu, Sinhala
hwalja_sea.bin	Thai, Khmer, Lao, Myanmar, Tibetan
hwalja_misc.bin	Ethiopic, Georgian, Armenian, and others

Without these files the device still works, but only the built-in Latin fallback font is available.

v1.1.1 Arabic font update

hwalja_arabic.bin was regenerated in v1.1.1 so Arabic presentation forms use the full 8-pixel cell width. This reduces unwanted left/right blank space and improves visual connection between glyphs that should join.

---

Build Environment

Platform / Board / Framework

Item	Value
Platform	espressif32
Board	esp32dev + Inkplate 5 V2 build flags
Framework	Arduino
CPU clock	240 MHz
Upload / monitor speed	921600 baud

board = esp32dev is used with manual build flags rather than a dedicated Inkplate board definition. This firmware will not work on a generic ESP32 dev board. The flags, PSRAM assumptions, display path, and keyboard input code are specific to the Zerowriter Ink / Inkplate 5 V2 hardware.

Libraries

Library	Version	Source
InkplateLibrary	11.0.0	lib/ (local, no separate install needed)
SdFat	2.3.1	PlatformIO registry
U8g2_for_Adafruit_GFX	1.8.0	PlatformIO registry
ESP32 BLE Keyboard	0.3.2	PlatformIO registry
Adafruit GFX Library	1.12.6	PlatformIO registry
Adafruit BusIO	—	PlatformIO registry

Build flags

Flag	Purpose
-DARDUINO_INKPLATE5V2	Board identification
-DINKPLATE_5V2	Enables correct code path inside InkplateLibrary
-DBOARD_HAS_PSRAM	Declares PSRAM presence to ESP-IDF
-mfix-esp32-psram-cache-issue	Workaround for ESP32 PSRAM cache bug (older silicon)
-DSCREEN_WIDTH=800 / -DSCREEN_HEIGHT=600	Display resolution constants
-Os	Size optimization for OTA-safe firmware size
-D CORE_DEBUG_LEVEL=0	Suppresses all serial debug output

Flash / partition settings

Item	Value
Partition table	min_spiffs.csv
Flash speed	80 MHz
Flash mode	QIO (quad I/O)

The clean v1.1.1 package includes min_spiffs.csv at the project root so the build does not depend on a hidden PlatformIO package path.

---

Installation

Requirements

• PlatformIO (VS Code extension or CLI)
• Zerowriter Ink (Inkplate 5 V2) with SD card

Recommended release install

Download or open the Ize-compose/ package.

1. Upload Ize-compose/firmware/izefirmware.bin as the firmware image.
2. Copy the contents of Ize-compose/sdcard/ to the SD card root.
3. Confirm that the SD card contains /ize_compose/initial.png and /ize_compose/hwalja/*.bin.

Build and flash from source

git clone <this repo>
cd <repo>
pio run --target upload

SD card setup

1. Format SD card as FAT32.
2. Copy the contents of Ize-compose/sdcard/ to the SD card root, or manually create /ize_compose/hwalja/.
3. Copy the hwalja_*.bin font files into /ize_compose/hwalja/.
4. Place initial.png (800×600 PNG) in /ize_compose/ for the sleep/boot image.

Firmware OTA update (WiFi)

1. Open the system menu → Network → WiFi.
2. Connect to the IZE_COMPOSE access point from a PC or phone.
3. Navigate to 192.168.4.1 in a browser.
4. Upload a new .bin firmware file.

---

Keyboard Shortcuts

Shortcut	Action
Ctrl+Space	Toggle Korean / English mode
Ctrl+L	Sleep (shows boot image)
Ctrl+F	Text search
Ctrl+C	Copy all text to clipboard
Ctrl+V	Paste clipboard
Space (accent cycling)	Cycle diacritic variants for last character

---

Repository Structure

Ize-compose/
  firmware/
    izefirmware.bin      — release firmware image
  sdcard/
    ize_compose/
      initial.png        — boot/sleep image
      hwalja/
        hwalja_*.bin     — font files to copy to SD card
  src/                   — clean PlatformIO firmware source
  lib/InkplateLibrary/   — local Inkplate driver required for build
  others/                — font sources and helper tools, not compiled
  INSTALL.md             — install/build notes
  RELEASE_1.1.1.md       — v1.1.1 release notes

src/
  IZEcompose.ino        — main firmware
  jado.h                — keyboard layout definitions and keymaps (92 layouts)
  jeong_eum.h           — Korean composition engine and script engine types
  insoe.h               — text rendering, font selection
  PsramAssets.h         — PSRAM asset loading helpers

lib/
  InkplateLibrary/      — Inkplate driver (local copy)

tools/
  make_fonts.py         — script used to build hwalja_*.bin from font sources
  u8g2/bdfconv.exe      — BDF font converter (used by make_fonts.py)

build/
  fontbuild*/           — intermediate font build artifacts
  noto_fonts/           — source Noto font TTFs used for font building

others/
  *.ttf                 — original/reference font files
  reference-headers/    — unused generated/reference headers, not compiled

platformio.ini          — PlatformIO build config

---

Current Limitations

• Supports only Inkplate 5 V2 (800×600). Other Inkplate boards are not tested.
• Korean cursor movement during mid-syllable composition is not supported.
• Only .txt files; no formatting.
• Single document open at a time.
• WiFi and BLE cannot be active simultaneously.
• The sleep image must be exactly 800×600 pixels; other sizes are not handled.

---

Credits

• Inkplate Arduino Library — Soldered Electronics
• U8g2_for_Adafruit_GFX — Oliver Kraus
• ESP32 BLE Keyboard — T-vK
• SdFat — Bill Greiman
• Noto Fonts — Google (used for font building; license: SIL OFL 1.1)
• Zerowriter Ink — original hardware