PNDriver用户编程接口说明之一

前言

本文源自西门子的技术文档《IO-Base User Programming Interface for PN Driver》，描述了PROFINET主站开发的基本方法，将作为PNDriver用户编程接口说明的第一篇笔记，主要为了方便同行查阅和参考。

1 快速入门

1.1 实现过程

用户按照以下步骤能快速高效地设计出基于IO-Base的控制器应用程序。

步骤	描述
1	熟悉PROFINET
2	熟悉IO-Base协议栈的函数接口及其数据结构
3	着重掌握使用接口函数的注意事项
4	研究IO-Base协议栈的示例代码
5	基于系统配置，确定控制器连接的设备，以及需要通信的过程、记录和报警数据
6	通过博图软件进行组态配置
7	用户可以在Test工程例子的基础上进行修改
8	修改bugs和测试

注意：用基于PNConfigLib库进行二次开发的组态工具软件可以代替博图软件进行总线配置

1.2 接口函数概述

1.2.1 控制器管理

• PNIO_controller_open
• PNIO_set_mode
• PNIO_device_activate
• PNIO_register_cbf
• PNIO_controller_close
• PNIO_iosystem_reconfig
• PNIO_interface_open
• PNIO_interface_register_cbf
• PNIO_interface_close
• PNIO_interface_set_ip_and_nos
• SERV_CP_init
• SERV_CP_undo_init
• SERV_CP_get_network_adapters
• SERV_CP_startup
• SERV_CP_shutdown
• SERV_CP_set_trace_level
• SERV_CP_set_trace_buffer

1.2.2 读写IO数据

• PNIO_data_read
• PNIO_data_write

1.2.3 读写记录数据

• PNIO_rec_read_req
• PNIO_interface_rec_read_req
• PNIO_rec_write_req
• PNIO_interface_rec_write_req

1.2.4 诊断

• PNIO_ctrl_diag_req

1.2.5 等时实时（IRT）

• PNIO_CP_register_cbf
• PNIO_CP_set_option

2 实时等级

IO-Base用户应用程序接口支持以下两种实时：

• RT
• IRT

2.1 实时和等时实时

RT
IRT
同步模式

3 IO-Base用户编程接口介绍

本节将介绍IO-Base控制器用户编程接口函数的基础知识，函数调用和数据访问在第四节函数和数据类型中详细介绍。

3.1 IO-Base用户编程接口函数的典型使用方法

下图显示了一个典型的PROFINET IO使用示例，一台工控机连接若干设备，使用PROFINET网络与通信。
PN Driver程序运行在基于工控机的IO-Base控制器程序中，也运行在嵌入式设备中，通过工业以太网与若干SIMATIC ET200SP设备进行通信，数据链路层使用PROFINET网络控制器或者一个标准以太网适配器。

3.2 软件架构

PROFINET I/O架构描述图

PROFINET IO控制器和设备用户程序（User Program）通过调用编程接口函数（IO-Base Interface）实现PROFINET通信功能，包括读写IO数据（R/W IO data）、读写记录数据(R/W data record)、接收警报和确认警报(Receive/Confirm alarms)等接口函数。

要在应用程序中正确调用IO-Base编程接口函数，需要在源文件中加入以下头文件。

文件类型	文件名	描述
头文件	pniobase.h	IO-Base基本数据结构和函数接口声明
头文件	pniousrx.h	IO-Base用户数据结构和用户函数接口声明
头文件	pnioerror.h	IO-Base错误码定义
头文件	pndriver_version	IO-Base版本信息
头文件	servusrx.h

3.3 IO-Base 控制器用户程序执行过程

IO-Base控制器有以下三种运行状态：

• 初始化
• 运行
• 停止

每个状态会执行一系列函数，函数的执行过程成为阶段。

3.3.1 初始化阶段

步骤	函数调用	描述
1	SERV_CP_init	PN协议栈初始化
2	SERV_CP_startup	PN协议栈配置和内部多任务启动
3	PNIO_controller_open	打开IO控制器
4	PNIO_register_cbf	输入参数为PNIO_CBE_MODE_IND，注册控制器工作模式切换的回调函数
5	PNIO_CP_register_cbf	如果需要支持等时实时通信，则需要注册两个事件回调函数
6	PNIO_set_mode	切换控制器工作模式
7	PNIO_CBE_MODE_IND	等待控制器工作模式切换事件，将会触发模式切换回调函数

3.3.2 控制器运行模式及其函数调用

步骤	函数调用	描述
1	PNIO_read_data	读过程数据
2	PNIO_write_data	写过程数据
3	PNIO_rec_read_req	读数据记录
4	PNIO_rec_write_req	写数据记录

3.3.3 控制器停机模式及其函数调用

步骤	函数调用	描述
1	PNIO_set_mode	切换控制器停机模式
2	OFFLINE事件	等待OFFLINE事件，将会触发模式切换回调函数
3	PNIO_controller_close	关闭控制器
4	SERV_CP_shutdown	内部任务终止并释放内存
5	SERV_CP_undo_init	控制器完成停机过程

3.4 基本数据交互

3.4.1 描述

IO-Base协议栈支持以下三种数据交互方式：

• 实时IO数据（RT）
  – 写RT数据
  – 读RT数据

• 等时实时IO数据（IRT）：读写功能与RT相同，但是额外规定了一个时间限制，读写数据必须在规定的时间内完成。

• 异步数据交互
  – 读写数据记录
  – 报警数据

有关更多信息，请参阅回调机制部分。

3.4.2 系统启动过程中的通信过程

3.5 过程数据通信（RT）

函数调用	描述
PNIO_data_read	读过程数据
PNIO_data_write	写过程数据

3.5.1 循环写数据及其数据状态

PNIO_data_write函数需要输出数据地址和本地数据状态作为参数。远程状态。

通信方向	变量
控制器到设备	输出数据+本地状态（输出数据的IOPS）
设备到控制器	远程状态（输出数据的IOCS）

3.5.2 循环读数据及其数据状态

通信方向	变量
设备到控制器	输入数据+IOPS
控制器到设备	本地状态（IOCS）

3.6 过程数据通信（IRT）的通信

本文暂时不对IRT的编程实现做深入描述

3.6.1 等时同步模式

3.6.2 访问IRT数据

3.7 PROFINET IO设备寻址

地址空间

3.8 回调机制

如何使用回调

需要在基于IO-Base控制器的用户程序中具体实现回调函数，请参考示例代码中的pnd_test_callback_function.cpp文件。
回调事件是由IO-Base接口产生的异步事件，触发事件将执行相应的回调函数，需要基于IO-Base控制器的应用程序的其他线程去执行，这需要用到多线程编程以及线程同步。

IO控制器事件及其回调函数

下表列出了IO控制器的回调事件和事件类型，只有注册了回调事件后，才会在事件产生后执行对应的回调函数。其中，有的事件及其回调函数在PNIO_controller_open中自动注册，有的则需要在程序中调用PNIO_register_cbf进行手动注册：

回调事件	事件	注册函数	事件发起方
有报录警	PNIO_CBE_ALARM_IND	PNIO_controller_open	IO设备
读记数据完成	PNIO_CBE_REC_READ_CONF	PNIO_controller_open	PNIO_rec_read_req
写记数据完成	PNIO_CBE_REC_WRITE_CONF	PNIO_controller_open	PNIO_rec_write_req
控制器工作模式切换	PNIO_CBE_MODE_IND	PNIO_register_cbf	PNIO_set_mode
IO设备通信连接状态有变化	PNIO_CBE_DEV_ACT_CONF	PNIO_register_cbf	PNIO_device_activate
诊断请求	PNIO_CBE_ALARM_IND	PNIO_register_cbf	PNIO_ctrl_diag_req
IO系统重新配置	PNIO_CBE_IOSYSTEM_RECONFIG	PNIO_CP_register_cbf	PNIO_iosystem_reconfig

网络适配器事件及其回调函数

下表列出了本地以太网接口上的回调事件和事件类型。其中，有的事件及其回调函数在PNIO_interface_open中注册，有的则需要在程序中调用PNIO_interface_register_cbf进行手动注册：

回调事件	事件	注册函数	事件发起方
IP地址设置	PNIO_CBE_IFC_SET_ADDR_CONF	PNIO_interface_register_cbf	PNIO_interface_set_ip_and_nos
修改外部存储数据	PNIO_CBE_REMA_READ_CONF	PNIO_interface_register_cbf
读记数据完成	PNIO_CBE_IFC_REC_READ_CONF	PNIO_interface_open	PNIO_interface_rec_read_req
写记数据完成	PNIO_CBE_IFC_REC_WRITE_CONF	PNIO_interface_open	PNIO_interface_rec_write_req
网络接口报警	PNIO_CBE_IFC_ALARM_IND	PNIO_interface_open	本地网卡设备
网络接口就绪	PNIO_CBE_IFC_APPL_READY	PNIO_interface_register_cbf	SERV_CP_startup

注意：编译应用程序时要注意libpthread库的版本，否则有可能会出现编译问题。
注意：要在回调函数中读写IO数据，只能调用以下函数，否则会导致不可预测的问题。
- PNIO_data_read
- PNIO_data_write
- PNIO_CP_set_opdone

PnDriver协议栈使用多线程实现，在应用程序主任务不能直接调用回调函数，回调函数执行将使用另一个线程，回调函数尽量快速返回，因此在回调函数中应当不要去执行那些需要太多时间的算法，这很像中断处理机制；而且多线程在读写共享资源时需要同步保护机制。

一个事件可以注册一个回调函数，也可以为若干事件注册一个回调函数。