41 lcdseg-段式LCD驱动
一、概述
lcdseg 是 LuatOS 内核里的段式 LCD（段码屏）驱动库，走芯片内置的 LCD 控制器，不需要外部驱动芯片，直接由 COM/SEG 引脚驱动玻璃。适合电表、水表、温控器这类低功耗段码显示场景。
lcdseg 库主要功能：
1、初始化：配置偏置（bias）、占空比（duty）、驱动电压（vlcd）、COM 数量、刷新率；
2、使能：enable() 打开库功能，power() 打开段码输出；
3、按段控制：seg_set(com, seg, en) 精确点亮/熄灭某一个段。
注意事项：
1、编译开关是 LUAT_USE_LCDSEG，源码头部明确写了「本库当前没有任何主推模组是支持的」，也就是说要用它得先确认目标芯片有 LCD 控制器，并自行编译固件；
2、段码屏的点亮关系由玻璃的真值表决定，seg_set 的 com/seg 组合必须对着屏的真值表填，写错就是显示乱码而不是不亮；
3、vlcd 单位是 100mV，不是 V。
二、核心示例
-- 注意：需芯片带 LCD 控制器且固件打开 LUAT_USE_LCDSEG
-- 参数含义：1/3 bias、1/4 duty、3.3V、4 个 COM、60Hz 刷新
if lcdseg.setup(lcdseg.BIAS_ONETHIRD, lcdseg.DUTY_ONEFOURTH, 33, 4, 60) then
lcdseg.enable(1) -- 启用库功能
lcdseg.power(1) -- 打开段码输出，屏上才会真的有波形
-- 按真值表点亮指定的段：COM0 的第 1 位、COM2 的第 0 位、COM3 的第 31 位
lcdseg.seg_set(0, 1, 1)
lcdseg.seg_set(2, 0, 1)
lcdseg.seg_set(3, 31, 1)
else
log.info("lcdseg", "setup fail")
end
要关掉某一段就把最后一个参数改成 0；整屏熄灭可以 lcdseg.power(0)，功耗比逐段清零更低。
三、常量详解
3.1 偏置电压（bias）
| 常量 | 数值 | 含义 |
|---|---|---|
lcdseg.BIAS_STATIC |
0 | 无偏置（静态驱动） |
lcdseg.BIAS_ONEHALF |
2 | 1/2 偏置 |
lcdseg.BIAS_ONETHIRD |
3 | 1/3 偏置（最常用） |
lcdseg.BIAS_ONEFOURTH |
4 | 1/4 偏置 |
数值直接从 2 开始，没有 1；bias 与 duty 必须配对（一般 1/3 bias 配 1/4 duty、1/2 bias 配 1/2 duty 或静态），配错会出现「该亮的段发灰、不该亮的段微亮」的串影。
3.2 占空比（duty）
| 常量 | 数值 | 含义 |
|---|---|---|
lcdseg.DUTY_STATIC |
0 | 静态，100% 占空比 |
lcdseg.DUTY_ONEHALF |
2 | 1/2 占空比 |
lcdseg.DUTY_ONETHIRD |
3 | 1/3 占空比 |
lcdseg.DUTY_ONEFOURTH |
4 | 1/4 占空比 |
lcdseg.DUTY_ONEFIFTH |
5 | 1/5 占空比 |
lcdseg.DUTY_ONESIXTH |
6 | 1/6 占空比 |
lcdseg.DUTY_ONESEVENTH |
7 | 1/7 占空比 |
lcdseg.DUTY_ONEEIGHTH |
8 | 1/8 占空比 |
duty 决定用几个 COM：1/4 duty 就是 4 个 COM 分时扫描，com_number 要和它一致。
四、函数详解
4.1 lcdseg.setup(bias, duty, vlcd, com_number, fresh_rate, com_mark, seg_mark)
功能
初始化段式 LCD 控制器，配置偏置、占空比、驱动电压、COM 数量、刷新率，以及 COM/SEG 的启用掩码。
参数
bias
参数含义：偏置电压
数据类型：number
取值范围：lcdseg.BIAS_STATIC / ONEHALF / ONETHIRD / ONEFOURTH
是否必选：是
注意事项：按屏规格书选，常见 1/3 bias。
duty
参数含义：占空比
数据类型：number
取值范围：lcdseg.DUTY_STATIC ~ DUTY_ONEEIGHTH
是否必选：是
注意事项：要和 com_number 对得上，1/4 duty 配 4 个 COM。
vlcd
参数含义：LCD 驱动电压
数据类型：number
取值范围：单位 100mV，例如 2.7V 写 27、3.3V 写 33
是否必选：是
注意事项：按屏规格书的推荐值给，给太高会加快液晶老化、对比度过大；给低了对比度不足。
com_number
参数含义：COM 引脚数量
数据类型：number
取值范围：取决于具体芯片与屏
是否必选：是
注意事项：必须与实际接出的 COM 数一致。
fresh_rate
参数含义：刷新率
数据类型：number
取值范围：通常 60，单位 Hz
是否必选：是
注意事项：不能太低（低于 30Hz 会闪），也不能太高（功耗上升且可能超出控制器能力）。
com_mark
参数含义：COM 启用掩码
数据类型：number
取值范围：默认 0xFF（全部启用）；只启用 COM0/COM1 写 0x03
是否必选：否
注意事项：掩码位与 COM 序号一一对应，屏蔽掉的 COM 不再输出波形。
seg_mark
参数含义：SEG 启用掩码
数据类型：number
取值范围：默认 0xFFFFFFFF（全部启用）；只启用前 16 个写 0xFFFF
是否必选：否
注意事项：用不到的 SEG 屏蔽掉可以降低功耗与干扰。
返回值
bool：成功返回 true，失败返回 false。
示例
-- 1/3 bias、1/4 duty、3.3V、4 个 COM、60Hz，只启用前 2 个 COM
lcdseg.setup(lcdseg.BIAS_ONETHIRD, lcdseg.DUTY_ONEFOURTH, 33, 4, 60, 0x03)
注意事项
-
setup只做配置，屏上不会立刻有显示，还要enable(1)再power(1)； -
参数顺序不要和
ht1621.setup混淆，两者是完全不同的驱动方式（ht1621 走 SPI 类三线，lcdseg 走芯片内置 LCD 控制器）。
4.2 lcdseg.enable(en)
功能
启用或禁用 lcdseg 库功能（控制器层面的开与关）。
参数
en
参数含义：启用标志
数据类型：number
取值范围：1 启用，0 禁用
是否必选：是
注意事项：与 power() 分工不同，enable 管功能，power 管输出。
返回值
bool：成功返回 true，失败返回 false。
示例
lcdseg.enable(1)
4.3 lcdseg.power(en)
功能
启用或禁用段码输出。关掉后屏上内容会消失，但配置与段状态保留，重新打开即可恢复。
参数
en
参数含义：输出开关
数据类型：number
取值范围：1 启用，0 禁用
是否必选：是
注意事项：低功耗场景可以在不显示时 power(0)，比逐段清零更省电。
返回值
bool：成功返回 true，失败返回 false。
示例
lcdseg.power(1) -- 打开显示
sys.wait(3000)
lcdseg.power(0) -- 3 秒后熄灭
4.4 lcdseg.seg_set(com, seg, en)
功能
设置某一个段的状态（点亮或熄灭）。
参数
com
参数含义：COM 号
数据类型：number
取值范围：0 ~ com_number-1
是否必选：是
注意事项：从 0 开始编号。
seg
参数含义：段号，即该 COM 下要修改的位的索引
数据类型：number
取值范围：0 ~ (每 COM 的 SEG 数 - 1)
是否必选：是
注意事项：具体哪一位对应屏上的哪一段，必须查屏的真值表，不能凭感觉试。
en
参数含义：点亮标志
数据类型：number
取值范围：1 点亮，0 熄灭
是否必选：是
注意事项：只改这一位，不影响同 COM 下的其它段。
返回值
bool：成功返回 true，失败返回 false。
示例
-- 点亮 COM0 的第 1 段，熄灭 COM2 的第 0 段
lcdseg.seg_set(0, 1, 1)
lcdseg.seg_set(2, 0, 0)
注意事项
-
段码屏没有「写字符串」的接口，数字、图标都要自己按真值表把段组合算出来，再逐段
seg_set； -
刷一整屏时逐段调用会产生多次底层写，建议把需要变化的段集中处理，或者自己维护一份段状态表做差量更新。
五、产品支持说明
lcdseg 依赖芯片内置的 LCD 控制器，编译开关 LUAT_USE_LCDSEG。源码注释明确说明当前没有任何主推模组默认支持该库，使用前需要确认目标芯片具备 LCD 控制器能力，并自行编译固件或向 FAE 确认。
固件支持列表（确认是否包含本库）：