Skip to content

Commit 32cd805

Browse files
BrainFromUkraineBrainFromUkraine
committed
micropython/bfu_ua_display: Add Ukrainian text library.
Add bfu_ua_display package for rendering Ukrainian text on MicroPython displays. Features: * Full Ukrainian alphabet support. * 5x7 bitmap font optimized for ESP32. * Works with displays supporting pixel() method. * Tested with SSD1306 OLED displays. Package provides ua_text, ua_text_center, and ua_text_scaled. Signed-off-by: Oleksandr Polishchuk <oleksandr.polishchuk@icloud.com>
1 parent 09a33ee commit 32cd805

7 files changed

Lines changed: 1015 additions & 0 deletions

File tree

‎micropython/bfu_ua_display/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 BFU Electronics
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎micropython/bfu_ua_display/README.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# BFU UA Display
2+
3+
Ukrainian text rendering library for MicroPython displays.
4+
5+
## Description
6+
7+
A lightweight library for rendering Ukrainian text on displays commonly used with ESP32 and MicroPython projects. Standard MicroPython display libraries do not include Ukrainian characters (А, Б, В, Г, Ґ, Д, Е, Є, Ж, З, И, І, Ї, Й, etc.), making it impossible to display Ukrainian text properly. This library solves that problem with a custom 5x7 bitmap font containing all 33 Ukrainian letters (uppercase and lowercase).
8+
9+
## Features
10+
11+
- **Full Ukrainian Alphabet Support** - All 33 Ukrainian letters (uppercase and lowercase)
12+
- **Lightweight** - Optimized for ESP32 memory constraints (~2-3 KB)
13+
- **Display Agnostic** - Works with any display supporting `pixel()` method
14+
- **Simple API** - Three main functions for text rendering
15+
- **5x7 Bitmap Font** - Compact and readable on small displays
16+
17+
## Installation
18+
19+
```python
20+
import mip
21+
mip.install("bfu_ua_display")
22+
```
23+
24+
Or using mpremote:
25+
26+
```bash
27+
mpremote connect COM3 mip install bfu_ua_display
28+
```
29+
30+
## Quick Start
31+
32+
```python
33+
from machine import I2C, Pin
34+
from ssd1306 import SSD1306_I2C
35+
from bfu_ua_display import ua_text, ua_text_center
36+
37+
# Initialize display
38+
i2c = I2C(0, scl=Pin(22), sda=Pin(21))
39+
oled = SSD1306_I2C(128, 64, i2c)
40+
41+
# Draw Ukrainian text
42+
ua_text(oled, "ПРИВІТ УКРАЇНО!", 0, 0)
43+
ua_text_center(oled, "BFU Electronics", 28)
44+
45+
# Update display
46+
oled.show()
47+
```
48+
49+
## API Reference
50+
51+
### ua_text(display, text, x, y, color=1, bg_color=0, clear_bg=False)
52+
53+
Render text at specified position with Ukrainian character support.
54+
55+
**Parameters:**
56+
- `display` - Display object with `pixel()` method
57+
- `text` - String to render (Ukrainian, English, numbers, symbols)
58+
- `x` - X coordinate (left edge)
59+
- `y` - Y coordinate (top edge)
60+
- `color` - Foreground color (default: 1)
61+
- `bg_color` - Background color (default: 0)
62+
- `clear_bg` - Clear background behind text (default: False)
63+
64+
**Returns:** Total width of rendered text in pixels
65+
66+
**Example:**
67+
```python
68+
ua_text(oled, "Температура: 25°C", 0, 0)
69+
```
70+
71+
---
72+
73+
### ua_text_center(display, text, y, color=1, bg_color=0, clear_bg=False, display_width=128)
74+
75+
Render text centered horizontally on the display.
76+
77+
**Parameters:**
78+
- `display` - Display object
79+
- `text` - String to render
80+
- `y` - Y coordinate (top edge)
81+
- `color` - Foreground color (default: 1)
82+
- `bg_color` - Background color (default: 0)
83+
- `clear_bg` - Clear background (default: False)
84+
- `display_width` - Display width in pixels (default: 128)
85+
86+
**Returns:** X coordinate where text was rendered
87+
88+
**Example:**
89+
```python
90+
ua_text_center(oled, "УКРАЇНА", 28)
91+
```
92+
93+
---
94+
95+
### ua_text_scaled(display, text, x, y, scale=2, color=1, bg_color=0, clear_bg=False)
96+
97+
Render text with scaling (2x, 3x, etc.).
98+
99+
**Parameters:**
100+
- `display` - Display object
101+
- `text` - String to render
102+
- `x` - X coordinate (left edge)
103+
- `y` - Y coordinate (top edge)
104+
- `scale` - Scaling factor (1=normal, 2=double, etc.)
105+
- `color` - Foreground color (default: 1)
106+
- `bg_color` - Background color (default: 0)
107+
- `clear_bg` - Clear background (default: False)
108+
109+
**Returns:** Total width of rendered text in pixels
110+
111+
**Example:**
112+
```python
113+
ua_text_scaled(oled, "ПРИВІТ", 0, 0, scale=2)
114+
```
115+
116+
## Supported Characters
117+
118+
- **Ukrainian Alphabet**: А Б В Г Ґ Д Е Є Ж З И І Ї Й К Л М Н О П Р С Т У Ф Х Ц Ч Ш Щ Ь Ю Я (uppercase and lowercase)
119+
- **English Alphabet**: A-Z, a-z
120+
- **Numbers**: 0-9
121+
- **Symbols**: Common punctuation and special characters
122+
123+
## Display Requirements
124+
125+
The library works with any display object that implements:
126+
127+
- `pixel(x, y, color)` - Set individual pixel (required)
128+
- `show()` - Update display (optional, for buffered displays)
129+
- `fill_rect(x, y, width, height, color)` - Fill rectangle (optional, for optimization)
130+
131+
## Compatibility
132+
133+
**Tested with:**
134+
- ESP32 with MicroPython v1.19+
135+
- SSD1306 OLED displays (128x64, 128x32) via I2C/SPI
136+
137+
**Compatible with:**
138+
- Any MicroPython-compatible board
139+
- Any display supporting the `pixel()` method
140+
141+
## Examples
142+
143+
### Multi-line Text
144+
145+
```python
146+
oled.fill(0)
147+
ua_text(oled, "Рядок 1", 0, 0)
148+
ua_text(oled, "Рядок 2", 0, 10)
149+
ua_text(oled, "Рядок 3", 0, 20)
150+
oled.show()
151+
```
152+
153+
### Scaled Text
154+
155+
```python
156+
oled.fill(0)
157+
ua_text_scaled(oled, "ВЕЛИКИЙ", 0, 0, scale=2)
158+
oled.show()
159+
```
160+
161+
### Centered Text
162+
163+
```python
164+
oled.fill(0)
165+
ua_text_center(oled, "УКРАЇНА", 10)
166+
ua_text_center(oled, "2026", 28)
167+
oled.show()
168+
```
169+
170+
## License
171+
172+
MIT License
173+
174+
## Documentation
175+
176+
For complete documentation, examples, and troubleshooting, visit:
177+
178+
**https://github.com/BrainFromUkraine/bfu_ua_display**
179+
180+
## Author
181+
182+
BFU Electronics

‎micropython/bfu_ua_display/bfu_ua_display/__init__.py‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
"""
2+
BFU UA Display - Ukrainian Text Rendering Library for MicroPython
3+
==================================================================
4+
5+
A professional, lightweight library for rendering Ukrainian text on displays
6+
commonly used with ESP32 and MicroPython projects.
7+
8+
Features:
9+
- Full Ukrainian alphabet support (33 letters)
10+
- Optimized for ESP32 memory constraints
11+
- Clean, modular architecture
12+
- Easy to use API
13+
- Extensible for multiple display types
14+
15+
Author: BFU Electronics
16+
License: MIT
17+
Version: 0.1.0
18+
"""
19+
20+
from .text_engine import ua_text, ua_text_center, ua_text_scaled
21+
22+
__version__ = "0.1.0"
23+
__author__ = "BFU Electronics"
24+
__all__ = ["ua_text", "ua_text_center", "ua_text_scaled"]

0 commit comments

Comments
 (0)