3121 系列模组

软件开发指南
V1.0.03
 3121 系列模组软件开发指南

修改记录
文档版本 发布日期 发布人 修改说明
V1.0.00 2019.07.20 wayne 创建
V1.0.01 2019.07.21 wayne 修改部署方案介绍
V1.0.02 2020.02.27 wade 文档结构整理
V1.0.03 2020.04.20 wade 新增 NV 0xf 和 0x10 的描述

FN-LINK TECHNOLOGY LIMITED Proprietary & Confidential Information

 3121 系列模组软件开发指南

目录

1 概述 ............................................................................................................................. 1
1.1 PLC 简介 ............................................................................................................ 1
1.2 PLC 拓扑结构..................................................................................................... 1
2 开发方案 ...................................................................................................................... 2
2.1 应用场景 ............................................................................................................ 2
2.2 应用举例 ............................................................................................................ 2
3 系统调测 ...................................................................................................................... 2
3.1 HiAssitant 的使用 ............................................................................................... 3
3.1.1 连接.........................................................................................................3
3.1.2 网络拓扑 .................................................................................................4
3.1.3 全网命令收发..........................................................................................5
3.1.4 升级.........................................................................................................7
3.1.5 白名单管理 .............................................................................................7
3.1.6 全网写 NV ..............................................................................................8
3.1.7 点对点通信 ........................................................................................... 11
3.1.8 密码修改 ............................................................................................... 11
4 固件升级 .................................................................................................................... 12
4.1 OTA 升级.......................................................................................................... 12
4.1.1 HiAssitant 升级(uart1) ........................................................................... 12
4.1.2 OTATool 升级(uart0).............................................................................. 13

FN-LINK TECHNOLOGY LIMITED Proprietary & Confidential Information

 3121 系列模组软件开发指南

1 概述
3121 系列模块是由 FN-LINK 基于海思 Hi3921SV100 芯片开发的 PLC 通信模块，支持
交流 220V 和直流 12V PLC 通信。
本文档重点描述用户如何使用 3121 系列模组进行评估测试、软件系统集成开发。
本文档适用于：软件工程师、测试工程师、技术支持工程师。

1.1 PLC 简介

PLC 即电力线载波通信，在交流（如 AC 10KV，220V/380V）或直流（DC 12V/24V）

线路上加载载波信号传输数据。PLC 工作原理如下：

1.2 PLC 拓扑结构

 CCO：
（Concentrator）主节点模组
 STA：
（Station） 子节点模组
 PCO：（Proxy Coordinator） 代理子节点模组
3121 系列模组支持 CCO 和 STA 两种工作模式，可通过烧录不同软件实现。网络节点
之间支持自动快速组网，动态路由，多路径寻址等功能。网络节点之间采用 6 字节 MAC
地址寻址，支持广播和单播通信，一个网络中只允许一个 CCO 存在。PCO 是具备代理中

FN-LINK TECHNOLOGY LIMITED 1 Proprietary & Confidential Information

 3121 系列模组软件开发指南

继功能的 STA 设备， CCO 根据网络信号等情况自动选择 STA 充当 PCO 角色。CCO 模组

支持网络拓扑管理，如：白名单设置和拓扑信息查询。

2 开发方案

2.1 应用场景

目前开发方案适用于以下两种应用场景：
 应用场景 1

GPIO
STA
PWM
Host CCO

GPIO
?、 STA
Uart PWM
PLC
该方案支持 Host 从 CCO 的 UART0 串口控制和获取所有 STA 的 GPIO/PWM 状态，
STA 可支持设置模组 GPIO 的 0-5,19,20 为控制脚。其中 PIN0-5 可设置为 GPIO 电平模
式和 PWM 模式，PIN19 和 PIN20 只能设置为 GPIO 电平模式。
 应用场景 2

STA Mcu
Host CCO U

?、 STA Mcu
Uart
PLC U
该方案支持 CCO UART0 串口数据与 STA UART0 串口数据互相透传。在透传模式下支
持数据的广播通信，在 AT 指令下也可以实现 CCO 和 STA 之间点对点的通信。
以上两种应用场景的具体使用，请参考文档《FN-LINK 3121 系列模组 AT 指令集.pdf》。

2.2 应用举例

3 系统调测
用户可通过工具 HiAssitant 对模组进行系统调测。HiAssitant 作为开源工具，运行在 PC
端，可以方便客户通过 uart1 串口对 PLC 模组进行调测、模组评估及现场运维。可以开放

FN-LINK TECHNOLOGY LIMITED 2 Proprietary & Confidential Information

 3121 系列模组软件开发指南

软件代码对一些常用功能进行客制化开发。
下面主要介绍 HiAssitant 的基本使用方法。

3.1 HiAssitant 的使用

双击 HiAssitant 工具，主界面如下图所示：

由上图可以看到，软件界面可以分为四个区域：
 区域 1：快捷功能按钮区，连接，系统版本查询等快捷功能进入；
 区域 2：控制面板区，选择切换不同的功能，打开后可在功能操作区上方选择不同
功能标题快速切换；
 区域 3：功能操作区，对基本功能进行操作；
 区域 4：日志打印区，可以查看指令操作日志打印。

3.1.1 连接

 点击快捷功能按钮区红黑相间的按钮 ，弹出串口设置窗口，如下图所示：

FN-LINK TECHNOLOGY LIMITED 3 Proprietary & Confidential Information

 3121 系列模组软件开发指南

 选择正确的串口号，波特率默认设置为 115200，密码默认设置为 cih518@AMR；

 点击确认，若连接成功会出现如下图界面，软件标题变为已连接。

 点击绿黑相间的按钮 即可断开连接。

3.1.2 网络拓扑

 查询网络拓扑信息。点击控制面板区“网络拓扑信息”，在弹出的功能操作区网络拓扑
信息界面右键菜单，选择“刷新”，将出现如下界面：

FN-LINK TECHNOLOGY LIMITED 4 Proprietary & Confidential Information

 3121 系列模组软件开发指南

下面对一些基本拓扑网络信息进行介绍：
拓扑参数 功能
衰减
平均信噪比

 保存发现列表和拓扑列表。右键菜单，选择“保存发现列表”和“保存拓扑列表”，将
会在软件同级目录下生成.csv 文件。

 查看拓扑中任意站点的发现列表。双击目标 MAC 行的设备 MAC 地址列，将会自动刷

新目标 MAC 的发现列表。

3.1.3 全网命令收发

 点击控制面板区“全网命令收发”，功能操作区弹出全网命令收发面板，如下图所示：

 点击“读取节点” ，获取直连站点和下属所有节点的 MAC 地址。

 点击“命令 ID”下拉框，选择一条命令。其中小写的命令为所有可下发命令。大写命令
为 stat 所支持的结构体。例如 HI_DSID_MAC_NDM_STAT_INFO 的命令 ID 对应

FN-LINK TECHNOLOGY LIMITED 5 Proprietary & Confidential Information

 3121 系列模组软件开发指南

0xa392，则选中 stat 后需选择编辑命令，将其中的 id 行改成 0xa392 才可下发。

 选中要发送的站点，点击“发送命令”，若成功 VALUE 列会出现相应数值。

 双击 VALUE 列可详细查看结构体值。
 常用命令如下表所示：

FN-LINK TECHNOLOGY LIMITED 6 Proprietary & Confidential Information

 3121 系列模组软件开发指南

命令 功能
osmemshow 查看内存使用统计
ver 查看版本号
macTxstatics 查看发送统计量
macRxstatics 查看接收统计量
macNmAttr 查看本节点组网信息
macrejoin 查看重新入网原因
stat 统计量命令,参数需要填写单板支持的统计量 ID，目前仅
提供一个例子 0xa392，由客户自行开发其他统计量
PlcTestFrame 性能测试命令， 可设置并发数和报文长度，用以通信性能

3.1.4 升级

 点击控制面板区“升级”，功能操作区弹出升级面板，如下图所示：

 升级选项选择全网升级，单点升级或者列表升级。全网升级指对直连 CCO 所组成网络

的所有成员进行升级；单点升级指对直连站点(CCO 或 STA)进行升级；列表升级指对
列表中指定的站点进行升级。
 选择对应的升级文件，若全网升级则需要选择 STA 文件升级；若单点升级则需要选择
CCO 文件升级；若列表升级则需要选择列表指定站点类型的文件升级。
 设置合适的全网升级时间窗。即升级时间超过设定值时会自动结束升级。
 点击“开始升级”，等待升级状态变成升级验证中，重新连接设备。之后升级状态将刷
新成升级成功。

3.1.5 白名单管理

 点击控制面板区“白名单管理”，功能操作区弹出白名单管理面板，如下图所示：

FN-LINK TECHNOLOGY LIMITED 7 Proprietary & Confidential Information

 3121 系列模组软件开发指南

 点击“读取白名单”，会显示当前 CCO 中的有效白名单 MAC 地址。

 选择有效的白名单文件，格式如下如所示：

 点击“清空白名单”，即可清空 CCO 中保存的白名单信息。

 点击“下发白名单”，即可将选中的白名单文件下发到 CCO 中。
 点击“打开白名单”或者“关闭白名单”，可对白名单进行打开关闭操作。

3.1.6 全网写 NV

NV 是 CCO 和 STA 设备参数，可以根据实际需要修改相应设备的参数。

 点击控制面板区“全网写 NV”
，功能操作区弹出全网写 NV 面板，如下图所示：

 点击“读取节点”，获取直连站点和下属所有节点的 MAC 地址。

FN-LINK TECHNOLOGY LIMITED 8 Proprietary & Confidential Information

 3121 系列模组软件开发指南

 点击“NV ID”下拉框，选择一条 NV ID，例如 0x3。

 选中要读取的站点，点击“读取 NV”，若成功 VALUE 列会出现相应数值。

 双击 VALUE 列，会打开编辑框，如下图所示。双击 plc_mac 的 value 列修改 MAC 地

址，并点击确定。修改后的值会记录在表格中。

 点击“写入 NV”，会将表格各行的 VALUE 值写入到对应设备中去。

 常用 NV 如下表所示：
NV 名 功能
0x3 修改 MAC 和产品类型
0x89 网管初始化参数（包括初始频段和优选网络）
0x21 phy 层参数
0xf 用户参数。包括工作模式，UART0 串口参数等
0x10 硬件初始化 IO 参数
注意：NV 项不可随意修改，修改前请咨询 FN-LINK FAE，以免造成设备异常问题。
下面重点描述一下 NV 0xf 和 0x10 功能含义。
NV(0xf) 功能
hw_ver 硬件型号
0:通用硬件；1: 3121N_H；2: 3121N_HS；3: 3121N_IEA；

FN-LINK TECHNOLOGY LIMITED 9 Proprietary & Confidential Information

 3121 系列模组软件开发指南

4: 3121N_IEB；5: 3121N_ISC
硬件型号与某些功能有关联，不建议随意修改。
work_mode 工作模式
0:透传模式；1:协议模式(不建议使用)；2:AT 模式
multicast_mac 组播地址，暂不支持
baund_rate 串口参数，波特率
支持 2400,9600,38400,115200,380400,921600 等。
data_bits 串口参数，数据位
支持 6,7,8
stop_bits 串口参数，停止位
支持 1,2
parity 串口参数，校验位
0:无校验；1:奇校验；2:偶校验
sta_join_notity 入网通知
0:不开启；1:开启

NV(0x10) 功能
pin_num 引脚编号
可设置为 0-5,16-18,19,20。其中 0-5,16-18 可设置为 GPIO
电平模式和 PWM 模式，19,20 只能设置为 GPIO 电平模
式。
type 引脚类型
1：GPIO 电平模式；2：PWM 模式
state 引脚状态值
当 type 引脚类型为 GPIO 电平模式时，0：低电平；1：
高电平
当 type 引脚类型为 PWM 模式时，可设置 0-100
pwm_freq PWM 频率
 当<pwm_ctl_mode> 配置成实时 调频模式 时有效，
GPIO0 和 GPIO5 支 持 配 置 范 围 为 [3-200]KHz,
GPIO1-4 支持配置范围为[1,2,5,10]KHz
 当<pwm_ctl_mode>配置成线性渐变调频或对数渐变
调频模式，只支持 5Khz，修改<pwm_freq>无效
pwm_ctl_mode PWM 调频模式
0：实时调频，PWM 信号实时调节到<state>值
1：线性渐变调频，PWM 信号基于<pwm_adjust_time>时
间线性变化到<state>值

FN-LINK TECHNOLOGY LIMITED 10 Proprietary & Confidential Information

 3121 系列模组软件开发指南

2：对数渐变调频，PWM 信号基于<pwm_adjust_time>时
间对数变化到<state>值
pwm_adjust_time PWM 调频渐变时长
当<pwm_ctl_mode>配置成线性或对数调频模式时有效，
该时间表示<state>值从 0-100 渐变所用时间。
例如配置成 3 秒，当前值是 0，目标值是 100，则渐变时
长 3 秒；当前值是 50，目标值是 100，则渐变时长 1.5 秒。

3.1.7 点对点通信

 点击控制面板区“点对点通信”，功能操作区弹出点对点通信面板，如下图所示：

 在 MAC 地址栏填写需要通信的 MAC 地址，最多支持三跳。

 在发送报文内容中填写数据， 最长为 384 字节。
 点击发送，会在接收区收到回复的相同报文。

3.1.8 密码修改

 点击控制面板区“密码修改”，功能操作区弹出密码修改面板，如下图所示：

FN-LINK TECHNOLOGY LIMITED 11 Proprietary & Confidential Information

 3121 系列模组软件开发指南

 在原密码， 新密码处填写正确密码，密码有复杂度要求。
 点击“提交”，修改完成。

4 固件升级
固件升级有以下几种方式：
升级方法 升级工具 备注
全片烧写 Hiburn/HiburnMP(uart1) 更新目标文件包括 FlashBoot、工厂区
NV 和业务升级文件，一般用于工厂烧
录，烧录完后 NV 参数比如 MAC 地址
等会清除还原成默认值。用户必须要在
FN-LINK FAE 指导下烧录。
OTA 更新 HiAssitant(uart1) 更新目标文件为业务升级文件，用于用
OTATool(uart0) 户当模组出现业务增量更新或修改时更
新。
本文档主要描述两种 OTA 更新方式。

4.1 OTA 升级

4.1.1 HiAssitant 升级(uart1)

请参考 3.1.4 描述操作。

FN-LINK TECHNOLOGY LIMITED 12 Proprietary & Confidential Information

 3121 系列模组软件开发指南

4.1.2 OTATool 升级(uart0)

FN-LINK TECHNOLOGY LIMITED 13 Proprietary & Confidential Information