# kk_oled

**Repository Path**: keysking/kk_oled

## Basic Information

- **Project Name**: kk_oled
- **Description**: 一套以 Agent Skills 的方式提供的 嵌入式单色 OLED 的轻量级图形库，提供图元、文字、位图、旋转以及阻塞、IT、DMA 刷新能力。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2026-09-04
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KK_OLED

KK_OLED 是一套面向嵌入式单色 OLED 的轻量级 C11 图形库，提供图元、文字、位图、旋转以及阻塞、IT、DMA 刷新能力。

KK_OLED 的本体由本仓库以 Agent Skills 的方式提供：编程 Agent 可以安装本仓库skills，根据目标工程的 MCU、SDK、总线、显示控制器和构建方式，添加一份可编辑的 KK_OLED 源码并完成移植、应用开发和验证。

KK_OLED 还可以与[波特律动取模助手](https://ledfont.botelvdong.com/)的在线 API 配合：`kk-oled-font` 会从工程收集字符、读取服务最新的 Agent API 说明、生成按需压缩字模并按用户要求集成。

## To 人类

你要做的只是告诉你的编程 Agent (Codex 或者 Trea等，都可以的) ：

> 将 https://gitee.com/keysking/kk_oled 中的 Skills 添加到当前工程，并根据实际情况为当前工程添加并移植 KK_OLED。

如果只需要完成某一类任务，也可以直接说明目标，例如移植 KK_OLED、实现显示界面，或者生成项目所需的字体子集。Agent 会选择对应的 Skill，并先检查当前工程中的实际代码和配置。

## To Agent

以下仅是建议，一切以用户的实际习惯与命令为准：

1. 首先下载或克隆本仓库
2. 从本仓库的 `skills/` 中复制任务所需的完整 Skill 文件夹到当前工程的skill目录中(通常是.agents/skills/)。
3. 按客户端要求重新加载 Agent、IDE 扩展或会话，使项目级 Skills 被重新发现。
4. 移植 KK_OLED 时，先使用 `kk-oled-port` skill 检查目标工程。工程已有 KK_OLED 时，以现有源码和本地修改为准；工程尚未接入时，才从该 Skill 的内置资产建立项目副本。
5. 根据实际任务继续使用 `kk-oled-use` 或 `kk-oled-font`。分别报告静态检查、构建、烧录、总线观测和实物显示结果，不把其中一个层级当作其他层级已经通过。

安装后的项目级 Skill 和 KK_OLED 源码副本都属于目标工程，可以由用户继续修改。不要把已安装 Skill 的资产目录直接作为目标工程的构建输入。

## 包含的 Skills

| Skill | 用途 | 运行条件 |
|---|---|---|
| `kk-oled-port` | 接入或迁移 KK_OLED，适配 MCU/SDK、I2C/SPI、显示控制器、具体 driver、参数和回调 | 可离线使用，内置完整 KK_OLED 运行时源码 |
| `kk-oled-use` | 实现或排查界面、图元、文字、位图、动画以及阻塞/IT/DMA 刷新 | 目标工程已经采用 KK_OLED |
| `kk-oled-font` | 收集界面字符、生成字体子集、解决缺字并优化字体 Flash 占用 | 字符分析可离线；生成字模需要 LEDFont 在线服务和网络 |

三个 Skill 只面向 KK_OLED。与 KK_OLED 无关的通用 OLED 或字体任务不应调用它们。

每个 Skill 的入口是其 `SKILL.md`，其中会按需引用 `references/` 和 `assets/`。`agents/openai.yaml` 是可选的 OpenAI 客户端元数据，其他 Agent 可以忽略；本仓库不依赖 Codex Plugin。

## KK_OLED 源码与移植范围

完整运行时源码位于：

```text
skills/kk-oled-port/assets/kk-oled-runtime/
```

其中包含公共头文件、图形核心和具体 driver。内置 driver 是经过验证的 STM32 HAL、I2C1 和 CH1116 参考实现，用于提供真实的移植起点，但其控制器、地址、句柄、分辨率、列偏移和初始化序列都不是其他工程的默认配置。

当前图形核心采用 1-bit 页式帧缓冲，每个字节对应同一列的 8 个像素。常规移植要求目标控制器能够按页和列区间写入显示数据；灰度屏、彩色屏或不同显存布局需要修改图形核心，不能只替换 driver。

KK_OLED 不规定目标工程必须采用固定的源码目录。Agent 应遵循目标工程现有的资源组织、模块边界和构建方式，并保留已有源码及本地修改。开始移植前，Agent 会先展示从工程和可靠资料中确认的硬件信息，只询问仍未知的关键项；屏幕控制器、总线地址/片选方式、分辨率和必要偏移等事实不能套用参考 driver 或常见模组参数。若 MCU 与 SDK 支持 IT/DMA，但工程尚未开启，Agent 会说明用途并询问是否启用，用户选择使用后负责完成配置、代码接线和验证。

## LEDFont 在线字模

`kk-oled-font` 已包含 KK_OLED 所需的字符收集、在线生成和工程集成流程。实际生成前，Agent 必须读取 LEDFont 最新的 [Agent API 说明](https://ledfont.botelvdong.com/agent-api.md)，以当前文档确定服务端点、参数、字体目录、限制和错误约定；无法完整读取时停止在线生成，不根据旧说明或示例猜测。生成得到的 C 字模可以随目标工程保存，后续编译不依赖在线服务。

## 版本与许可证

- 版本：`0.1.0`
- 许可证：MIT
- 版权主体：青岛波特律动科技有限公司（Qingdao BaudDance Technology Co., Ltd.）

本仓库中的第一方 Skill 内容和 KK_OLED 源码采用 MIT 许可证，仓库内不包含示例字体、生成字体或第三方字体数据。

LEDFont 生成的字模可能受到所选字体自身许可证约束，不因使用本仓库而转为 MIT 许可。服务未提供许可信息时，不应推断或承诺其许可范围。