完全常规Windows环境，构建一套完整的鸿蒙南北向鸿蒙南北向舵机掌上舵机遥控系统：上位机APP，HarmunyOSnext；下位机，Hi3861-HiSpark，OpenHarmuny-LiteOS，舵机。TCP通信。

1 Windows开发环境构建

安装以下工具软件：

1 DevEcoStudio--北向APP IDE

2 网络调试助手

3 Python3.7~3.9--南向编译基础依赖

2 整体方案规划设计

2.1 整体设计

南向Hi3861外挂SG90舵机，构成简易终端--HiSpark。

WiFi局域短距离无线组网，TCP通信。

纯血鸿蒙APP掌上监控。

C/S架构采集控制系统：APP--客户端C，终端--服务器S。

2.2 通信协约

1) 协议分层与帧格式

应用层协议采用“固定帧头 + 长度前缀 + 数据域 + 校验”的二进制结构，运行于 TCP 之上。所有多字节字段均为大端序（网络字节序）。

图 1 舵机监控项目的协议帧格式展示图

表1 舵机监控项目的协议帧字段说明列表

字段	长度	取值 / 说明
HEAD	2 B	固定 0xAA 0x55，用于帧同步
ADDR	1 B	设备地址，默认 0x01；预留多点组网（多舵机级联）
CMD	1 B	命令字
LEN	2 B	数据域字节数，大端序，取值范围 0 ~ 512
DATA	LEN B	数据负载，内容随 CMD 而定
CRC16	2 B	CRC16-MODBUS，校验范围 ADDR ~ DATA，大端序

表2 舵机监控项目的协议帧命令定义列表

方向	CMD	名称	数据域（DATA）	说明
APP→舵机	0x01	握手	空	链路确认，舵机回 ACK
APP→舵机	0x02	查询状态	空	舵机立即回送一帧状态上报
APP→舵机	0x03	设定角度	int16，单位 0.1°	设定目标角度，如 900 = 90.0°
APP→舵机	0x04	设定速度	uint16，单位 rpm	设定目标转速
APP→舵机	0x05	使能/停止	uint8：1=运行 0=停止	控制舵机输出使能
APP→舵机	0x06	标定	空	将当前位置设为零点
APP→舵机	0x07	设置模式	uint8：0=位置 1=速度 2=力矩	切换工作模式
APP→舵机	0x09	急停	空	立即停止输出
舵机→APP	0x81	状态上报	18 B	周期或应答上报
舵机→APP	0x82	应答	uint8 原CMD + uint8 结果码	结果码 0=成功，非 0=错误
舵机→APP	0x83	错误	uint8 错误码	异常上报

2) 状态数据域（0x81）

表3 舵机监控项目的协议帧状态位定义列表

位	名称	含义
bit0	运行	1 = 舵机处于运行状态
bit1	到位	1 = 当前角度已到达目标角度
bit2	过温	1 = 温度超过告警阈值
bit3	过流	1 = 电流超过告警阈值
bit4	堵转	1 = 检测到堵转
bit5	过压	1 = 母线电压过高
bit6	欠压	1 = 母线电压过低
bit7	综合故障	1 = 存在任一严重故障

3) CRC16-MODBUS校验

采用 CRC16-MODBUS：多项式 0xA001（对应 0x8005 反转），初值 0xFFFF，逐字节异或后右移 8 次，遇最低位为 1 则异或多项式。结果以高字节在前写入帧尾。该校验算法与主流「网络调试助手」及通用 CRC 计算器的 CRC16/MODBUS 结果一致，便于在调试助手侧核对。参考实现如下：

4) 典型报文示例

表4 舵机监控项目的典型报文示例列表

方向	含义	完整帧（HEX）
APP→舵机	握手	AA 55 01 01 00 00 18 50
APP→舵机	查询状态	AA 55 01 02 00 00 18 A0
APP→舵机	设定 90.0°	AA 55 01 03 00 02 03 84 99 E4
APP→舵机	设定 45.0°	AA 55 01 03 00 02 01 C2 0B 64
APP→舵机	设定 120 rpm	AA 55 01 04 00 02 00 78 E8 51
APP→舵机	使能运行	AA 55 01 05 00 01 01 5C D9
APP→舵机	停止	AA 55 01 05 00 01 00 9C 18
APP→舵机	标定	AA 55 01 06 00 00 D9 E1
APP→舵机	急停	AA 55 01 09 00 00 DA D1
舵机→APP	状态上报（运行）	AA 55 01 81 00 12 01 C2 03 84 00 78 03 52 01 A9 2E E0 03 01 00 00 B4 E4 22 98
舵机→APP	状态上报（过温+堵转）	AA 55 01 81 00 12 01 2C 03 84 00 00 0C 80 03 70 2E 18 94 00 00 00 B4 E5 D7 6D
舵机→APP	状态上报（停止到位）	AA 55 01 81 00 12 01 C2 01 C2 00 00 01 2C 01 9A 2F 12 02 00 00 00 B4 E6 C5 F7
舵机→APP	ACK（设定角度成功）	AA 55 01 82 00 02 03 00 E4 D8
舵机→APP	ACK（设定角度失败）	AA 55 01 82 00 02 03 02 25 59

以“状态上报（运行）”为例的解析结果：当前角度45.0°、目标角度90.0°、转速120 rpm、电流850 mA、温度42.5 ℃、电压12.000 V、状态位0x03（运行 + 到位）、模式 1（速度模式）。

5) 粘包 / 半包处理策略

TCP 面向字节流，不保证“一次回调对应一帧”。FrameParser 通过以下策略保证帧完整性：

1. 累积缓冲：把每次 on('message') 收到的字节追加到内部缓冲区。
2. 帧头同步：在缓冲区中查找 0xAA 0x55，丢弃帧头之前的无效字节。
3. 长度判定：读取 LEN 字段计算整帧长度；不足则等待后续数据（半包）。
4. CRC 校验：校验通过则取出该帧并从缓冲区移除；失败则丢弃 1 字节并重新同步。
5. 循环提取：重复上述过程，直到缓冲区中不再存在完整帧（一次回调可产出多帧）。

该策略可同时覆盖“单包多帧”、“多包一帧”、“含噪声”等场景。

3 北向鸿蒙APP开发调试

3.1 IMA-DeepSeek借力

咨询提示词：给出远程舵机监控的鸿蒙APP详细设计软件工程包和相应的设计说明及其测调试步骤：Windows下DevEco Studio26.0.0开发，TCP通信，网络调试助手代替远程舵机构成测试闭环。

图2 舵机监控项目北向开发的IMA-DS借力截图

3.2 总体设计

1) 设计原则

1. 分层解耦：协议层、通信层与界面层职责清晰，界面不直接操作Socket。
2. 单一数据源：通信状态与最新状态由ServoService单例统一维护，多页面订阅同一数据源。
3. 健壮通信：显式处理粘包、半包、CRC错误、连接中断等异常。
4. 可观测：全链路报文日志，便于联调与验收。
5. 可扩展：新增命令字仅需在协议层枚举与业务封装处扩展，界面可按需增量添加。

2) 技术选型

表5 舵机监控项目的技术选型列表

维度	选型	理由
应用模型	Stage 模型	HarmonyOS NEXT 推荐模型，支持完整的 Ability 能力
开发语言	ArkTS	鸿蒙原生语言，类型安全，支持声明式 UI
UI 框架	ArkUI（声明式）	状态驱动、组件化，适配多设备
网络能力	@kit.NetworkKit → socket.TCPSocket	系统内置，支持 TCP 长连接与事件回调
序列化	自定义二进制帧 + CRC16-MODBUS	紧凑、高效，便于设备端实现与手工调试
日志	@kit.PerformanceAnalysisKit → hilog	系统日志，可在 IDE 中按 TAG 过滤

3) 软件分层架构

图3 舵机监控项目的软件分层架构图

4) 模块划分与职责

表6 舵机监控项目的模块划分与职责列表

层次	模块	主要职责
界面层	pages/Index.ets	应用主框架，底部导航组织四大功能区
	view/ConnectView.ets	连接参数配置、建立/断开连接、连接状态显示
	view/MonitorView.ets	状态可视化（角度环、指标、告警位）、轮询查询
	view/ControlView.ets	控制指令下发（角度/转速/模式/使能/标定/急停/自定义报文）
	view/LogView.ets	收发报文日志展示、清空、自动滚动
服务层	service/ServoService.ets	Socket 生命周期、指令封装、事件分发、日志缓存
	service/FrameParser.ets	字节流累积、帧头同步、长度判定、CRC 校验、逐帧提取
模型层	model/ServoFrame.ets	帧结构定义、编解码、命令字枚举
	model/ServoStatus.ets	状态数据解析、告警位判断、展示字段派生
能力层	common/Constants.ets	全局常量、连接状态、默认参数
	common/Logger.ets	hilog 日志封装
	common/ByteUtil.ets	字节 / HEX / ArrayBuffer / 整型 转换
	common/Crc16.ets	CRC16-MODBUS 校验算法
入口	entryability/EntryAbility.ets	应用生命周期、加载首页

5) 工程目录结构

图4 舵机监控项目的工程目录结构图

3.3 详细设计

1) 通用能力层

A．Constants（全局常量）

集中管理默认参数、连接状态与报文方向标识，避免魔法值散落。

表7 舵机监控项目的全局变量设计列表

常量	值	说明
DEFAULT_SERVER_IP	192.168.1.100	默认远端 IP
DEFAULT_SERVER_PORT	8899	默认远端端口
DEFAULT_LOCAL_PORT	0	本地端口，0 表示系统随机分配
CONNECT_TIMEOUT_MS	6000	连接超时时间
AUTO_QUERY_INTERVAL_MS	1000	自动轮询周期
MAX_LOG_ITEMS	500	日志环形缓存上限
STATE_IDLE / CONNECTING / CONNECTED / ERROR	idle / connecting / connected / error	连接状态
DIR_TX / DIR_RX	TX / RX	报文方向

B．Logger（日志封装）

封装hilog，统一DOMAIN(0x0001)与TAG(ServoMonitor)，提供debug/info/warn/error四个级别。开发期可在DevEco Studio的Log 窗口按TAG=ServoMonitor 过滤。

C．ByteUtil（字节工具）

表8 舵机监控项目的字节工具方法列表

方法	功能
arrayToBuffer / bufferToArray	number[] 与 ArrayBuffer 互转
toHex / hexToBytes	字节数组与 HEX 字符串互转
int16ToBytes / uint16ToBytes / uint32ToBytes	整型按大端转为字节数组
readInt16 / readUint16 / readUint32	从字节数组按大端读取整型
bytesToUtf8 / utf8ToBytes	UTF-8 字符串与字节互转（预留文本协议）

D．Crc16（校验算法）

提供 crc16Modbus(data: number[]): number 纯函数，无状态、可复用于收发两侧。

2) 数据模型层

A．ServoFrame（协议帧）

承载帧的地址、命令字与数据域，提供编码与解码能力。

表9 舵机监控项目的协议帧核心API列表

成员 / 方法	类型	说明
addr	number	设备地址，默认 0x01
cmd	number	命令字
data	number[]	数据域
encode()	ArrayBuffer	按协议封装为待发送字节
encodeBytes()	number[]	封装为字节数组（便于日志）
toHex()	string	输出大写 HEX 字符串
ServoFrame.decode(bytes)	ServoFrame | null	由完整帧字节解析出对象

帧编码核心逻辑如下：

B．ServoStatus（状态模型）

由 18 字节状态数据域解析而来，提供原始工程值与面向界面的派生方法。

表4-10 舵机监控项目的状态模型说明列表

成员 / 方法	说明
curAngle / tgtAngle	当前 / 目标角度（度，已由 0.1° 换算）
speed / current	转速（rpm）/ 电流（mA）
temperature / voltage	温度（℃）/ 电压（mV）
statusBits / mode / timestamp	状态位 / 工作模式 / 舵机时间戳
isRunning() ... isFault()	各告警位布尔判断
statusText()	综合状态文案（运行中 / 过温告警 / 故障 等）
isHealthy()	是否处于健康状态（用于配色）
voltageV() / modeText()	电压换算为 V / 模式文案

3) 通信服务层

A．FrameParser（粘包 / 半包解析器）

表4-11 舵机监控项目的帧分析方法说明列表

方法	说明
push(chunk: number[])	压入新收到的字节，返回本次可解析出的全部完整帧
reset()	清空缓存与统计（重连时调用）
getTotalFrames() / getCrcErrors() / getBufferLength()	统计信息，便于测试与调试

B．ServoService（通信服务，单例）

全应用唯一的通信服务实例，向上屏蔽 Socket 细节。对外提供连接管理、指令封装、事件订阅与日志读取四类能力，并维护「最近一次状态」，使后进入的页面也能立即渲染。

表12 舵机监控项目的通信服务方法说明列表

分类	方法	说明
监听	addListener / removeListener	注册 / 注销事件监听（支持多订阅者）
状态	getConnState / isConnected	查询连接状态
	getLastStatus / hasStatusData	获取最近一次状态
	getLogs / clearLogs	读取 / 清空日志缓存
	setAutoReconnect	设置断线自动重连
连接	connect(ip, port, localPort)	绑定本地端口并连接远端
	disconnect()	主动断开并注销回调
发送	sendFrame(frame)	发送协议帧对象
	sendRawHex(hex)	发送自定义 HEX 报文（调试）
指令	hello / queryStatus	握手 / 查询状态
	setAngle / setSpeed / setMode	设定角度 / 转速 / 模式
	setEnable / calibrate / emergencyStop	使能停止 / 标定 / 急停
工具	buildStatusData / buildStatusFrameHex	构造状态帧（自测与模拟用）

事件监听接口编码如下：

4) 界面层

A．主框架 Index

采用 Tabs 组件构建底部导航，包含“连接 / 监控 / 控制 / 日志”四个TabContent。当前选中项高亮为品牌色，切换时更新currentIndex。

B．连接页ConnectView

表13 舵机监控项目的连接页面设计说明列表

区域	控件	说明
状态卡片	状态圆点 + 文案 + 详情	实时反映连接状态（未连接 / 连接中 / 已连接 / 异常）
参数配置	远端 IP / 端口 / 本地端口 输入框	支持默认值，本地端口 0 表示随机分配
	断线自动重连开关	开启后断线 3 秒自动重连
操作	连接 / 断开 按钮	按钮可用性随状态联动
提示	联调提示	引导用户用网络调试助手构建闭环

C．监控页 MonitorView

表14 舵机监控项目的监控页设计说明列表

区域	控件	说明
顶栏	在线指示 + 最后更新时间 + 查询按钮	手动触发一次状态查询
角度主视图	环形进度 + 大号角度值	环形颜色随健康状况变化（绿/橙/红）
关键指标	转速 / 电流 / 温度 / 电压	两行两列指标卡
状态位	状态文案 + 告警 Chip	运行/到位/过温/过流/堵转/过压/欠压/故障
轮询	自动轮询开关	默认开启，周期 1 秒

E．控制页ControlView

表15 舵机监控项目的控制页设计说明列表

区域	控件	说明
角度控制	滑块(0~360°) + 下发按钮	下发 0x03 设定角度
速度控制	滑块(0~500 rpm) + 下发按钮	下发 0x04 设定速度
工作模式	位置 / 速度 / 力矩 三选一	下发 0x07 设置模式
操作按钮	使能运行/停止/标定归零/急停	标定与急停二次确认后下发
自定义报文	HEX 输入框 + 发送	高级调试能力

F．日志页LogView

以列表展示全部收发报文与状态变化记录，按方向着色（TX 蓝、RX 绿、系统灰、错误红），支持清空与自动滚动到底部。日志同时缓存于 ServoService，页面可随时拉取历史。

5) 应用入口与配置

A．EntryAbility

应用入口，负责生命周期回调；在 onWindowStageCreate 中加载 pages/Index 作为首页。

B．module.json5 权限声明

网络权限声明编码如下：

其中 ohos.permission.INTERNET 为必需项，未声明将导致 Socket 创建失败；GET_NETWORK_INFO / GET_WIFI_INFO 用于获取本机网络信息，便于诊断。

3.4 运行及其测调试

图5 舵机监控项目的IDE设计窗口界面A截图

图6 舵机监控项目的APP IDE设计窗口界面B截图

图7 舵机监控项目的APP IDE网络连接模拟调试组合截图

图8 舵机监控项目的APP IDE运行监视模拟调试[正常]组合截图

图9 舵机监控项目的APP IDE运行监视模拟调试[异常]组合截图

图10 舵机监控项目的APP IDE远程操控模拟调试组合截图

4 南向鸿蒙驱动应用开发调试

4.1 IMA-DeepSeek借力

咨询提示词：给出基于Hi3861及其HiSpark的底层鸿蒙南向舵机驱动编码设计及其受控动作的应用编码，包括整个工程目录结构与文件，能够配合该鸿蒙APP远程监控该舵机运行，使用这里制订的APP通信协约。

图11 舵机监控项目南向开发的IMA-DS借力截图

4.2 整体设计规划

远程舵机监控·设备端（Hi3861 / HiSpark）：基于OpenHarmony轻量系统（LiteOS-M）的南向舵机驱动与受控动作应用。设备以STA模式接入WiFi，并作为TCP Server监听8899端口。

1) 关键设计约束（必读）

Hi3861的硬件PWM无法输出50 Hz。设备终端时钟源：160 MHz（内部默认）与40 MHz（PWM_CLK_XTAL）。推导：硬件WM输出频率 = 时钟源 ÷ 分频系数，分频系数上限65535。另外 hi_timer 的 expire 参数单位为毫秒（Hi3861 系统 tick = 10 ms）， 同样无法产生 0.5–2.5 ms 的舵机脉宽。因此本工程默认采用软件PWM（GPIO位翻转 + hi_udelay 微秒级精确延时）， 由独立高优先级任务持续输出50 Hz 波形，详见 src/servo_hal.c。

2) 目录结构

servo_device/
├── BUILD.gn               构建脚本（static_library）
├── README.md
├── include/
│   ├── servo_config.h         全局配置：引脚 / WiFi / 端口 / 阈值（移植入口）
│   ├── servo_hal.h             舵机输出硬件抽象层
│   ├── servo_drv.h             舵机业务驱动（角度/脉宽/保护/状态机）
│   ├── servo_motion.h         受控动作（梯形规划 + 预置动作序列）
│   ├── servo_sensor.h         传感与状态估算
│   ├── device_proto.h         协议编解码
│   ├── frame_parser.h         TCP 流式拆包
│   ├── tcp_server.h            TCP 服务端
│   └── wifi_connect.h         WiFi STA 接入
└── src/
    ├── app_main.c             应用入口与任务编排
    ├── servo_hal.c             软件 PWM / 硬件 PWM 双后端
    ├── servo_drv.c             驱动实现
    ├── servo_motion.c         运动规划与动作序列
    ├── servo_sensor.c         传感采集 / 物理模型估算
    ├── device_proto.c         CRC16-MODBUS + 帧编解码
    ├── frame_parser.c         粘包/半包解析
    ├── tcp_server.c            TCP 服务、指令分发、周期上报
    └── wifi_connect.c         WiFi 接入与 DHCP

 

​         图12 舵机监控项目南向开发的软件分层与任务模型图

任务优先级（CMSIS-RTOS2）：

1. ServoPwmTask osPriorityRealtime--50Hz波形生成（软件PWM）
2. ServoCtrlTask osPriorityAboveNormal--20ms运动规划与状态评估
3. TcpServerTask osPriorityNormal--连接、收包、指令分发
4. ReportTask   osPriorityNormal--1s周期状态上报

4.3 编制、进行及其测调试

图13 舵机监控项目的硬件驱动与应用添加组合截图

图14 舵机监控项目南向开发的硬软件开发组合截图

图15 南向软件体系编译过程组合截图

图16 南向软件体系烧录过程截图

1) 接线提示

表16 舵机监控项目南向开发的硬件接线列表

项目	说明
信号线	舵机信号线（橙/黄）接 servo_config.h 中 SERVO_GPIO_ID（默认 GPIO7）
电源	舵机必须独立 5V 供电，切勿从 Hi3861 取电，否则电机电流会拉垮系统
共地	舵机电源地与 Hi3861 地必须共地（GND 相连）
去耦	舵机电源并 470–1000 µF 电解电容可显著减少复位与抖动
电平	Hi3861 GPIO 为 3.3V，多数舵机 3.3V 逻辑可正常识别；不放心可加电平转换

2) 快速使用

# a) 拷入源码树
cp -r servo_device <OH_ROOT>/applications/sample/wifi-iot/app/​
# b) 注册模块：修改 app/BUILD.gn，features 中加入 "servo_device:servo_device"
# c) 追加编译开关：usr_config.mk 中加入 CONFIG_PWM_SUPPORT=y
# d) 修改 include/servo_config.h 中的 WiFi 账号密码与舵机引脚​
# e) 编译
cd <OH_ROOT> && hb set && hb build -f
# f) 用 HiBurn 烧录 out/hi3861/.../wifiiot_app_allinone.bin

烧录后串口（115200）会打印本机 IP，把它填进鸿蒙 APP 的“连接”页即可。

表17 舵机监控项目南向开发的目录映射关系列表

本交付包路径	OpenHarmony源码树目标路径
servo_device/	applications/sample/wifi-iot/app/servo_device/
integration/app_BUILD.gn	applications/sample/wifi-iot/app/BUILD.gn（覆盖或按内容合并）
integration/usr_config.mk.append	vendor/hisi/hi3861/hi3861/build/config/usr_config.mk（追加）

3) app/BUILD.gn 合并示例

若原有的 app/BUILD.gn 里已有别的模块，不要整体覆盖，只需把新增项加进 features：

4) 联调与自测

5) 协议兼容性

设备侧与 APP 侧逐字节一致，已通过主机端自动化测试验证（30 项全部通过）：

表18 舵机监控项目南向开发的通信协议兼容测试列表

命令	方向	说明
0x01	APP→设备	握手，回 ACK
0x02	APP→设备	查询状态，直接回 0x81 状态帧（不回 ACK）
0x03	APP→设备	设定角度（int16，0.1°）
0x04	APP→设备	设定转速（uint16，rpm）
0x05	APP→设备	使能/停止（uint8）
0x06	APP→设备	标定归零
0x07	APP→设备	设置模式（0 位置 / 1 速度 / 2 力矩）
0x09	APP→设备	急停
0x0A	APP→设备	播放预置动作序列（本工程扩展）
0x81	设备→APP	状态上报（18 字节）
0x82	设备→APP	应答（原命令字 + 结果码）
0x83	设备→APP	错误

状态上报 18 字节：当前角度(0.1°) / 目标角度(0.1°) / 转速(rpm) / 电流(mA) / 温度(0.1℃) / 电压(mV) / 状态位 / 工作模式 / 时间戳(ms)。

6) 验证编译是否生效

编译成功后，串口应能看到如下日志片段：

若未出现[app]日志，说明模块未参与编译，可检查app/BUILD.gn的features。

5 南北向系统联合调试完善

图17 舵机监控项目南北向联合调试组合截图