第 1 课 · 屏幕显示基础

这一课学什么？

这一课先不让 CoCube 到处移动，只做一件事：把代码运行结果直接显示在屏幕上。

屏幕是最直观的反馈窗口。
当你先学会把文字、颜色和图形稳定地显示出来，后面做运动、感知和任务控制时，就能更方便地把状态也显示出来。

屏幕课素材

学习目标

会初始化 CoCube 板载屏幕
会用默认中文字库显示文字和简单图形
会用变量刷新屏幕内容
能完成一个简单的“流水灯屏幕”挑战

用到的硬件和功能

这一课只需要 CoCube 本体，不需要额外接扩展模块。

会用到的接口主要有：

display.init()：初始化屏幕并返回 tft 对象。入门阶段直接空参调用即可；它也支持 rotation（朝向）、inversion（是否反色）、color_order（颜色顺序）这些参数。
display.write(text, x, y, color=display.WHITE, bg=display.BLACK, size="normal", auto_wrap=False)：显示文字。text 是字符串；x / y 是坐标；color 是字色；bg 是背景色；size 可选 small、normal、big。
display.measure(text, size="normal")：计算文字宽度，适合做居中排版。
tft.fill(color)：用一种颜色填满整个屏幕。color 一般传 display.BLACK、display.BLUE 这类颜色常量。
tft.fill_rect(x, y, w, h, color)：画实心矩形。x / y 是左上角坐标；w / h 是宽高；color 是填充颜色。
tft.fill_circle(x, y, r, color)：画实心圆。x / y 是圆心坐标；r 是半径；color 是填充颜色。

先认识这个能力

CoCube 的屏幕分辨率是 240 x 240。
写屏幕程序时，先记住下面这几个规则就够了：

左上角是坐标起点，也就是 (0, 0)
x 越大越往右，y 越大越往下
重新画新内容前，通常要先清屏，或者先把旧区域盖掉
当前固件已经准备好默认中文字库，直接用 display.write() 就能显示中文和英文

开始编程

1. 先显示一句话和一个图形

先跑通一个最小程序，确认屏幕可以正常显示。

import display

tft = display.init()
tft.fill(display.BLACK)
display.write("你好，CoCube", 24, 40, display.YELLOW, display.BLACK)
tft.fill_circle(120, 128, 24, display.CYAN)

这段程序做了三件事：

初始化屏幕
把背景清成黑色
显示一行文字，再画一个圆

2. 把静态画面变成会变化的状态卡

接下来把变量也放进屏幕里，让显示内容跟着程序变化。

import time
import display

tft = display.init()
tft.fill(display.BLACK)
display.write("计数器", 72, 30, display.GREEN, display.BLACK)

for count in range(1, 7):
    tft.fill_rect(24, 92, 192, 56, display.BLUE)
    text = f"第 {count} 次"
    x = (display.WIDTH - display.measure(text, size="big")) // 2
    display.write(text, x, 104, display.WHITE, display.BLUE, size="big")
    time.sleep_ms(500)

如果你想继续改，可以先试三件事：

把标题改成自己的名字或任务名
把背景色从 display.BLUE 改成别的颜色
把 range(6) 改大一点，观察计数变化

运行时观察什么

运行上面的程序时，重点看这几件事：

文字坐标一变，显示位置会马上变
背景颜色和文字颜色一起决定画面是否清楚
display.measure() 可以帮助你把变化内容摆到更合适的位置
每次重画矩形区域后，旧数字会被覆盖掉
如果不先盖掉旧区域，变化内容容易重叠在一起

常见问题 / 使用提醒

屏幕没有反应时，先检查有没有调用 display.init()
文字显示不完整时，先检查 x、y 坐标是不是太靠边
内容刷新有残影时，先清屏，或者先用 fill_rect() 盖掉旧区域
这一课先追求“显示稳定”，不用一开始就把画面做得很复杂

挑战一下：做一个“流水灯屏幕”

在 cocube-learn 的入门活动里，“流水灯”是很适合拿来练显示节奏的任务。
放到 CoCube MicroPython 里，可以把它理解成“屏幕上的 5 x 5 方格依次点亮”。

流水灯效果图

你可以按这个思路来做：

先画一个 5 x 5 的方格区
每次只点亮其中一个小方块
按从左到右、从上到下的顺序依次显示
到最后一格后重新开始

如果想继续往上加：

把等待时间调短，让“流动”更快
把颜色改成红、绿、蓝或者自定义颜色
在流水灯上方再加一行文字，做成状态提示条

参考代码

import time
import display

tft = display.init()

bg = display.BLACK
border = display.color565(240, 210, 80)
off = display.color565(20, 40, 20)
on = display.color565(80, 255, 40)

cols = 5
rows = 5
cell = 38
gap = 4
left = 12
top = 12
border_w = 4

grid_w = cols * cell + (cols - 1) * gap
grid_h = rows * cell + (rows - 1) * gap
frame_w = grid_w + 2 * border_w
frame_h = grid_h + 2 * border_w

def draw_board(active_index):
    
    tft.rect(left, top, frame_w, frame_h, border)
    tft.rect(left + 1, top + 1, frame_w - 2, frame_h - 2, border)

    for row in range(rows):
        for col in range(cols):
            x = left + border_w + col * (cell + gap)
            y = top + border_w + row * (cell + gap)
            index = row * cols + col
            color = on if index <= active_index else off
            tft.fill_rect(x, y, cell, cell, color)

while True:
    tft.fill(bg)
    for active in range(cols * rows):
        draw_board(active)
        time.sleep_ms(120)

快速参考

这一课最常用的写法是：

import display

tft = display.init()
tft.fill(display.BLACK)
display.write("你好", 20, 40, display.YELLOW, display.BLACK, size="big")

display.init()：初始化板载屏幕
tft.fill(color)：整屏填充背景色
display.write(...)：显示文字，直接支持中文
display.measure(...)：测量文字宽度，适合居中排版
tft.fill_rect(...)：画矩形，适合做底色或状态框
tft.fill_circle(...)：画圆形，适合做简单图标

如果需要更多接口，可以继续查看 display 模块快速参考。

这一课学什么？​

学习目标​

用到的硬件和功能​

先认识这个能力​

开始编程​

1. 先显示一句话和一个图形​

2. 把静态画面变成会变化的状态卡​

运行时观察什么​

常见问题 / 使用提醒​

挑战一下：做一个“流水灯屏幕”​

快速参考​