简介：一套面向嵌入式开发者的物联网扩展板示例代码包，整合电子纸墨水屏显示、NB-IoT与GPRS蜂窝通信及HAT硬件抽象层标准，适合正在学习低功耗远程可视化设备的单片机工程师。代码基于C语言实现，覆盖墨水屏初始化与刷新、NB-IoT模块AT指令交互、GPRS网络接入、传感器数据上传等关键环节，可帮助透彻理解物联网设备从硬件驱动到协议栈调用的完整链路。包内共151个文件，以C源码（40个.c、40个.o）与头文件（34个.h）为主，另有32个不同尺寸墨水屏的BMP测试位图、Makefile构建脚本及ini配置文件，整体仅815KB，结构紧凑，便于按模块查阅与交叉对照。已有193人学习下载。通过研读该DEMO，可快速掌握HAT板引脚控制与多模块协作逻辑；同时借助随包位图资源，能按目标屏幕型号快速定位对应工程，减少驱动移植的排查成本，并直接复用底层通信代码，搭建自己的低功耗物联网显示终端。
1. 这块“墨水屏 + NB-IoT/GPRS HAT”到底能干什么
拿到 E-Paper_NB-IoT_GPRS_HAT_Demo_Code 这套工程的人，多半是想做一类东西：某块屏幕上显示温度、库存、车次、电表读数，屏幕背后没有路由器、没有网线，只有一张 SIM 卡。把树莓派扩展板（HAT）和墨水屏叠在一起，再接上 NB-IoT 或 GPRS 模块，就构成一个能放在走廊、配电房、农田里的低功耗信息终端。有人觉得奇怪：墨水屏刷新那么慢，为什么还要用它？恰恰因为慢，它才省电——刷新完成后不耗电也能保持画面，一块电池顶几个月。这篇文章就从方案选型、Demo 代码结构、参数设置和现场翻车点四个角度，把这条路走一遍。
2. 链路选型：为什么是墨水屏、NB-IoT、GPRS，以及 HAT 怎么统一它们
2.1 墨水屏的可替代性边界：双稳态不是白叫的
在物联网显示终端这个场景里，墨水屏的核心优势只有一个：刷新完成后像素靠双稳态维持，驱动电路完全断电，画面还在。这个特性直接决定了整机功耗曲线。TFT 屏幕哪怕显示静态画面也要持续刷帧，背光更是耗电大户；墨水屏只在“翻页”那一刻消耗能量，显示“当前温度 23.5℃”这样一个静态页面，功耗几乎可以归零。
换来的代价是刷新时间按秒算。7.5 寸三色墨水屏做一次全屏刷新，在 2MHz SPI 时钟下往往要 2 到 4 秒，这个过程里屏幕会闪两次（黑色闪、白色闪），观感像老式电子词典。所以它的适用场景非常明确：数据变化频率低、人不会一直盯着看、对“秒级出画面”没有要求。典型如仓库看板、会议室预约屏、农业大棚温湿度指示牌，都很适合。
Demo 代码里通常会给屏幕封装几个底层函数：初始化、清屏、局部刷新、整屏刷新。局部刷新是省时间的关键——如果只是温度从 23.5 变成 23.6，没必要把整屏全部重画，只更新数字所在区域即可。但局部刷新有副作用，下面避坑章节会详细说，这里先记住一个原则：局部刷新用多了，残影会累积。
2.2 NB-IoT 与 GPRS 的分工：低速率数传和存量网络怎么权衡
HAT 上同时引出 NB-IoT 和 GPRS 两种蜂窝接口，不是功能重复，而是应对两种现实。NB-IoT 走 LTE 窄带，单载波带宽只有 180kHz，上行峰值在 20kbps 左右，下行大约 60kbps，但它的覆盖半径大、穿墙能力强，在地下室、隧道这类环境里还能保持信号。代价是网络注册慢，从休眠唤醒到重新附着基站，现场经验上常常要 3 到 10 秒，而且运营商套餐大多限制每日流量。
GPRS 是 GSM 时代的 2.5G 技术，理论速率 85.6kbps，实际可用往往不到 20kbps。它的价值不在速率，而在“还有网络在路上”。不少海外市场、偏远地区的物联网卡仍然只支持 GSM 频段，国内某些行业设备也还挂在 GPRS 上没迁走。如果你做的是出口到特定区域的项目，板上留 GPRS 通道能救急。
选择逻辑我一般这样排：如果终端部署在信号弱、对速率无要求的固定位置，优先 NB-IoT；如果项目要兼容海外运营商且对方只有 GSM 网络，GPRS 是保底方案；如果数据量大、时延要求高，这两种都不合适，应该直接上 Cat.1 或 4G。Demo 代码里两个模块通常共用同一个串口和同一组 AT 指令框架，切换只需要改波特率和 APN，代码层不用大动。
2.3 HAT 板卡的硬件设计：40Pin、电平转换和电源裕量
HAT 的本意是“Hardware Attached on Top”，一块直接插在树莓派 40Pin 排针上的扩展板。标准 HAT 要求板载 EEPROM，里面存设备树 overlay 信息，插上后系统自动识别硬件。但市面上很多 Demo 板为了兼容旧内核和降低工序成本，并不焊接 EEPROM，靠手动加载设备树或直接在用户态驱动 GPIO 的方式工作。拿到代码后第一件事就是确认：板子上有没有焊 EEPROM，驱动是走/dev/spidev还是走用户态 GPIO 模拟 SPI。这两个模式的初始化脚本完全不同。
墨水屏排线接口一般由 HAT 板上的 FPC 座引出，通过 SPI 协议控制。注意电平匹配：树莓派 GPIO 是 3.3V 逻辑，墨水屏驱动板的逻辑电平通常也是 3.3V，可以直接连接；但如果你的 HAT 板兼容 5V 逻辑需要额外加电平转换芯片，插排线前最好拿万用表量一下 FPC 座子的逻辑引脚电压，翻车的大多数是这里。
电源是 HAT 最容易踩的坑。墨水屏刷新瞬间驱动板会拉出较大电流，NB-IoT 模块在发射时峰值电流甚至能到 2A 级别（非连续），树莓派本身的 5V 电源如果只有 2.5A 余量，容易被拖垮。常见做法是外部供电直接进 HAT，板载 DC-DC 再分出 5V 和 3.3V，树莓派从 HAT 取电；另外一个很有效的措施是在模块电源输入脚并一个大电容（470µF 起步），缓冲发射瞬间的电压跌落。Demo 代码里很少能在代码层面解决硬件供电问题，但固件日志里会暴露“模块掉线重启”的规律——如果每次发数据都掉电重启，先查电容和电源，不要怀疑代码。
3. 用 Demo Code 跑通“取数 → 上屏”的最小链路
3.1 准备清单和一遍过的基础配置
把板子装好之前，我习惯先列一张检查清单，避免通电后不知道问题出在哪一环。清单如下：树莓派系统刷好且能 SSH 登录；HAT 板插紧，FPC 排线方向正确（金手指朝外或朝内，看板子丝印，不要硬塞）；NB-IoT/GPRS 模块插上 SIM 卡，天线锁紧；墨水屏排线插到位。接着做系统侧配置：开启 SPI 接口、关闭蓝牙对串口的占用，让/dev/ttyAMA0或/dev/ttyS0留给蜂窝模块。
在/boot/config.txt里加两行然后重启，这是树莓派上启用 SPI 和串口的标准姿势：
# 启用 SPI 接口，给墨水屏控制用 dtparam=spi=on # 关闭蓝牙映射，让 UART 完整落在 ttyAMA0 dtoverlay=disable-bt重启后先确认外设是否就位。我一般用ls /dev/spidev*看 SPI 节点，用raspi-gpio get看默认引脚电平，再stty -F /dev/ttyAMA0 9600试探串口是否通。注意：ttyS0和ttyAMA0在不同内核配置下对应不同的物理串口，跑 Demo 前先查dmesg | grep tty，不然 AT 指令发错端口，很容易以为是模块坏了。
3.2 第一步：让墨水屏先把静态画面画出来
任何 Demo 调试都应该从“屏幕能画东西”开始，这样才能把问题域切干净。下面这段代码演示了最基础的屏幕初始化流程，常见的 Demo 工程里逻辑都类似：
import spidev import RPi.GPIO as GPIO import time # 以 7.5 寸三色屏为例，引脚编号按 HAT 板丝印定义调整 SPI_BUS = 0 SPI_DEVICE = 0 PIN_DC = 22 # 数据/命令选择 PIN_RST = 27 # 复位 PIN_BUSY = 17 # 忙检测 spi = spidev.SpiDev() spi.open(SPI_BUS, SPI_DEVICE) spi.max_speed_hz = 2000000 # 2MHz，墨水屏驱动板常见上限 spi.mode = 0b00 # SPI 模式 0，CPOL=0 CPHA=0 GPIO.setmode(GPIO.BCM) GPIO.setup([PIN_DC, PIN_RST], GPIO.OUT) GPIO.setup(PIN_BUSY, GPIO.IN, pull_up_down=GPIO.PUD_UP) def screen_reset(): GPIO.output(PIN_RST, GPIO.HIGH) time.sleep(0.05) GPIO.output(PIN_RST, GPIO.LOW) time.sleep(0.05) GPIO.output(PIN_RST, GPIO.HIGH) time.sleep(0.05) def wait_ready(timeout=10): # 大部分墨水屏控制器在 busy 拉低时表示忙，具体极性要看数据手册 start = time.time() while GPIO.input(PIN_BUSY) == GPIO.LOW and (time.time() - start < timeout): time.sleep(0.01) if time.time() - start >= timeout: print("busy 超时，检查复位与供电") def send_cmd(cmd, data=None): # 发命令时 DC 拉低，发数据时 DC 拉高 GPIO.output(PIN_DC, GPIO.LOW) spi.xfer2([cmd]) if data: GPIO.output(PIN_DC, GPIO.HIGH) spi.xfer2(data)这段代码把屏幕驱动抽象成四个操作：SPI 初始化、复位、忙检测、命令发送。参数说明上，max_speed_hz设 2MHz 是保守值，实测部分屏在 4MHz 下也能工作，但长排线或者劣质 FPC 会有信号完整性风险，速度太快时画面容易出现随机噪点。PIN_BUSY的极性各厂商定义不统一，有的是高电平表示忙，有的是低电平表示忙，拿到屏幕第一件事就是看数据手册确认极性，代码里那个== GPIO.LOW很可能要反过来。开发时宁可先跑通再调速度，不要一开始就追求刷屏快。
初始化完成后，发一帧纯色数据就能验证屏幕是否工作。如果出现画面只有一半、颜色错乱，马上检查 SPI 模式和发送顺序；如果完全不亮，优先怀疑排线没插到位，其次怀疑复位时序不对。
3.3 第二步：通过串口 AT 指令从蜂窝模块取数
屏幕画得出图之后，再把 NB-IoT/GPRS 链路加进来。蜂窝模块几乎都是串口加 AT 指令的操作方式，下面是连接模块并读取数据的最小 Python 流程：
import serial # 串口按 HAT 板实际连接调整，波特率看模块型号默认值 ser = serial.Serial('/dev/ttyAMA0', 9600, timeout=5) def send_at(command, expect='OK', wait=3): ser.reset_input_buffer() ser.write((command + '\r\n').encode()) end = time.time() + wait buf = b'' while time.time() < end: buf += ser.read(ser.in_waiting or 1) if expect.encode() in buf: return buf.decode(errors='ignore'), True return buf.decode(errors='ignore'), False # 关闭回显 send_at('ATE0') # 检查模块是否在线 resp, ok = send_at('AT') print('模块应答:', resp if ok else '超时') # 查询 SIM 卡状态和信号强度，CSQ 第二项是信号，99 表示无信号 resp, ok = send_at('AT+CSQ') print('信号质量:', resp) # 激活网络连接，APN 需要按卡商要求配置 send_at('AT+CGDCONT=1,"IP","cmnet"') # 以 cmnet 为例，换成你的卡实际 APN send_at('AT+CGACT=1,1', expect='OK', wait=10)send_at函数的三个要点分别是清空输入缓冲、超时控制、期望应答匹配。串口通信最怕的是上一条指令的延迟响应混进下一条的返回里，所以每条指令发送前先reset_input_buffer()，丢垃圾数据。timeout=5是串口层超时，wait=3是 AT 指令层超时，两者不同，网络激活这类操作耗时长，需要把 wait 放到 10 秒以上。
常见调试手顺是：先发AT看模块是否回OK，再查AT+CSQ的信号强度，最后激活 PDP 上下文。如果AT无应答，先确认串口设备和波特率对不对；如果CSQ返回 99，问题在射频侧：天线没接好、SIM 卡没识别、或者所处位置没信号。
3.4 合流：主循环、异常兜底和断电策略
屏幕能画、模块能通，就可以把两段逻辑串进主循环。一个 Demo 级的主循环大概长这样：
BASE_URL = 'http://your-lite-api/api/current-value' # 换成实际轻量接口 def fetch_remote_value(): # 这里省略通过 AT 指令建立 TCP 连接并发送 HTTP GET 的细节 # 核心是用 AT+HTTPCLIENT 或 AT+SOCKET 类指令请求，返回 JSON 字符串 return '23.5' def main_loop(): refresh_count = 0 while True: try: value = fetch_remote_value() draw_value(str(value)) # 直接用上一节的 SPI 函数渲染数字 refresh_count += 1 if refresh_count >= 10: # 每 10 次局部刷新做一次全屏清残影 full_refresh() refresh_count = 0 except Exception as e: print('链路异常，保留旧画面:', e) show_offline_page() # 显示“信号弱”占位页 # 休眠到下一次采集，NB-IoT 场景通常 5 到 15 分钟一次 time.sleep(600)这个主循环体现了三个落地习惯：异常时不重试轰炸而是保留旧画面，避免断网状态下疯狂重连导致耗电；局部刷新累积到一定次数后做全屏刷新清除残影；采集周期用time.sleep兜底，赶时间的项目后续会改成 RTC 定时唤醒。真正部署时，sleep阶段应该让树莓派进入深度休眠而不是空等，这个问题最后一章会展开。
4. 避坑指南：墨水屏与蜂窝模块最容易现场翻车的 5 个点
4.1 换画面后有残影或偏色：刷新序列不是随便改的
现象：同一块屏幕，整屏刷新完画面干净；连续做几次局部刷新后，旧数字的影子越来越明显，甚至局部区域底色发灰。原因有两层：墨水屏的电子墨水粒子靠电压驱动移动，局部刷新只改变指定像素的电压状态，相邻像素的粒子没完全归位；二是不少 Demo 代码为了省时间，把刷新 LUT（查找表）里的波形缩短了，粒子还没稳定就切画面。解决：局部刷新次数到 5～10 次就强制做一次全屏刷新；如果项目对局部刷新依赖很强，找屏幕厂商要“低残影局部刷新 LUT”，换一组波形参数。注意三色屏的红、黑、白驱动波形完全不同，定了刷新颜色就不能混用。
4.2 屏幕白屏，一点反应都没有：先查时序和共用引脚
现象：通电后屏幕背板没有电压，或者有电压但控制器不响应，连 busy 都不拉。原因多半不是屏幕坏了，而是引脚被复用。树莓派上 GPIO8、GPIO9、GPIO10、GPIO11 是 SPI0 的标准引脚，同时也是某些音频板卡、ADC 板卡的默认引脚，HAT 板如果没做引脚仲裁，驱动会因为设备树冲突直接失败。另一个常见原因是 FPC 排线插反或没有插到底，有些板的锁扣要先翻开再压入。解决：dmesg | tail看有没有 SPI 冲突报错，用万用表量复位引脚的电压是否随初始化代码跳变。注意别把 5V 供电的屏幕接到 3.3V 排针上——有些屏幕要求 5V 驱动，HAT 板上会有跳线帽切换，插错跳线就是白屏。
4.3 模块一直 AT+CSQ 返回 99：天线、SIM 卡、APN 三连排查
现象：AT 指令能收到 OK，证明串口正常、模块固件正常，但死活注册不上网络，CSQ永远 99。排查顺序不要跳：第一步确认天线物理连接，弹簧天线拧紧后要能感觉到扣位“咔哒”一声；第二步确认 SIM 卡是否被识别，AT+CPIN?返回READY才算过；第三步查 APN，很人误以为 APN 随便填，实际上运营商窄带卡默认的 APN 不对时，注册流程会卡在附着阶段。还有一个隐蔽问题：部分 NB-IoT 模块默认关闭了附着功能，需要用AT+CFUN=1打开射频功能。用模块厂商提供的测试软件对比信号值，可以快速判断是天线问题还是配置问题。
4.4 断网时屏幕卡在旧数据上：给数据链路加超时和兜底
现象：网络断开后，主循环里请求数据的函数一直阻塞，屏幕显示的还是几小时前的数值，用户看到这个界面会认为系统已经死了。原因：Demo 代码里如果用的是阻塞式 socket 或串口 read，没有设置连接超时，异常路径触发不了。解决：所有网络请求必须设两级超时——串口层timeout=5防止 read 卡死，业务层用signal.alarm或非阻塞 socket 设置 20 秒总超时；请求失败时不要重试超过两次，立即切换“信号弱”占位画面。另外一个有用的技巧：把最后一次成功获取的数据和获取时间写入本地文件，重连后先显示缓存数据，再在后台静默更新，用户感知会好很多。
4.5 HAT 板供电跌落导致模块反复重启：别忽略峰值电流
现象：模块能注册，但每次发起 TCP 连接时系统日志出现模块掉电重启，有时树莓派也卡死重启。原因：NB-IoT 与 GPRS 模块发射瞬间电流可能到 1.5A 甚至更高，而板载 3.3V 稳压器或直流电源余量不够，电压一跌落模块就复位。解决：优先在 HAT 板电源输入处并两个电容——470µF 电解电容加 100nF 高频瓷片电容；条件允许时用独立 5V/3A 电源给 HAT 供电，树莓派只负责控制，不负责输电。调试时用电流钳或万用表快速流峰值，确认模块发射时电压跌落幅度是否超过 5%。如果每条数据都伴随掉线重连，不要改代码，先把电源问题解决。
5. 把 Demo 改造成可部署方案：低功耗开关与整机验证
5.1 四个可以立刻用上的功耗优化开关
Demo 代码跑通只是起点，部署在电池供电的站房或电表箱里，功耗是绕不开的话题。第一个开关是调节采集周期。墨水屏终端按小时更新完全足够，把 sleep 从 10 分钟拉到 60 分钟，功耗直接降一个数量级。第二个开关是模块深度休眠。NB-IoT 模块在无操作时用AT+CPSMS=1开启 PSM 模式，GPRS 模块用AT+CFUN=0关闭射频，保留网络上下文，醒来后重新附着的时间会大幅缩短。第三个开关是树莓派休眠——但这块板子不是为深度睡眠设计的，常规做法是加一块外部 RTC 加 MOSFET 断掉树莓派的 5V 供电，定时唤醒取数据，取完立刻断电，这不是 Demo 代码能覆盖的，但架构上值得提前留接口。第四个开关是减少全屏刷新。全屏刷新比局部刷新多耗几十倍的能量，把全屏清残影的次数从每 10 次降到每 30 次，画面脏一点但电量能多撑半个月。
5.2 三步整机验证法：日志、功耗曲线、长时间挂机
改造完不要急着装到现场，我习惯按三步验收。第一步，打开 Demo 的日志开关，确认每次数据从请求到上屏的完整路径都有时间戳，日志格式包括：唤醒时间、网络注册时长、数据请求时长、屏幕刷新时长，这组数据能直接定位瓶颈在哪个环节。第二步，用功率分析仪或 USB 电流表测一个完整周期的功耗，注意把链路拆开：休眠期电流应该小于 0.5mA，唤醒后屏幕刷新和模块发射是峰值区，算一下平均功耗，再乘上电池容量，估算理论续航，如果理论续航和预期差太多，回到 5.1 调参数。第三步，连续挂机 72 小时以上，模拟弱网场景和不规律断电，让屏幕经历几十次完整刷新，确认没有残影累积和内存泄漏——墨水屏 Demo 最容易被忽视的问题是长时间运行后 busy 超时次数逐渐增多，这种情况往往是 SPI 时钟太接近信号完整性的极限。
最后附带一个我自己养成的习惯：每次发布新改动前，一定先把 Demo 原始代码备份一份，尤其是屏幕刷新序列和 AT 指令流程这两段，改坏了随时能回退。墨水屏和蜂窝模块的坑大多不在代码逻辑，而在时序和电气参数，有了干净基线，现场出问题时排查范围能缩小一半。希望帮到你。
本文还有配套的精品资源，点击获取
