![de7e58fe122e88bc6d8574b892f60332.png](https://i-blog.csdnimg.cn/blog_migrate/f851ffa3d93dbad8816a775485b571fc.jpeg)
1 协议规范
1.1 基本设计
通讯协议规范要求:
1. 简单的命令协议使用http请求和响应,主要用于参数化和控制sensor.
2. 激光扫描数据通过TCP/IP,UDP/IP协议来接收.
激光数据输出规定:
1. 数据输出按TCP或UDP以太网帧大小相同的数据包分组执行.
2. 单个包总是仅仅包含单个连续扫描的数据. 每一次新扫描的数据输出总是以新的数据包开始.
3. 用户能够选择扫描数据详细信息级别类型,使用这种方式客户端能够灵活接收应用所需要的数据,减少流量.并且能够更容易的扩充数据.
4. sensor没有严格限制客户端连接活动数量和客户端请求的数据量.用户一般希望设计的客户端系统或应用方式是sensor能够处理大量请求数据而不超负荷.
1.2 HTTP命令协议
HTTP命令协议提供了简单的应用访问控制sensor的方法.HTTP命令用于配置sensor测量,读取和改变sensor参数.同时也提供了用于访问数据的TCP或UDP通道及端口.
1.2.1 发送命令
<scheme>:<authority>/<path>?<query>#<fragment>
sensor典型的http请求如下:
http://<sensor IP address>/cmd/<cmd_name>?<argument1=value>&<argument2=value>
Thus, in terms of an URI a valid HTTP command is composed of the following parts:
1. scheme总是'http://'
2. authority表示sensor的IP地址
3. path包含'cmd/'和请求命令名称('<cmd_name>')
4. query例出指定命令附加的参数
5. fragment当前没有使用-随后的hask mark将会被忽略
1.2.2 query参数编码
HTTP命令参数使用如下的规则:
key=value[;value][&key=value]
key参数接收一个或多个value, 单个key对应多个value通过;来分离.单个命令多个key=value使用&串接.
注意:跟URI特殊字符? = &相对字符需要过滤掉.
1.2.3 命令回应
当命令发送后,接收到的回复如下:
1. HTTP状态码
HTTP命令首先通过标准的HTTP状态码应答.这个code表明命令是否被接收和正确被接收.仅仅当URI无效或不能被处理是才返回错误code
2. 命令错误码
正常的HTTP状态code是'OK'.在这种情况下可以通过error_code和error_text两个返回值来确定命令处理结果. error_code包含了命令调用具体错误码, error_text 提供了错误码对应的描述信息. 所有的返回值都以JSON编码方式返回. 1.2.6章节提供了详细的命令错误码描述信息.
3. 命令回应数据
命令答复包含任意请求的负荷数据. 数据总是使用JSON编码方式传输, 大量数据可能基于ase64编码的JSON数组输出.
注意:R2000所有JSON编码命令答复的字符编码总是UTF-8
1.2.4 HTTP请求和答复-底层示例
本节展示一个例子, 如何在不适用web浏览器的情况下将HTTP请求传输到传感器. 假设如下的HTTP请求被发送:
http://<sensor IP address>/cmd/get_parameter?list=scan_frequency
这个请求被翻译成简单的字符串(本例使用HTTP/1.0):
GET /cmd/get_parameter?list=scan_frequency HTTP/1.0rnrn
该字符串作为TCP/IP分组的有效载荷数据被发送到传感器. 然后传感器返回TCP/IP分组的HTTP答复的有效载荷数据. HTTP请求能够被解析作为简单的文本字符串, 其内容如下:
HTTP/1.0 200 OKrn
Expires: -1rn
Pragma: no-cachern
Content-Type: text/plainrn
Connection: closern
rn
{rn
"scan_frequency":50,rn
"error_code":0,rn
"error_text":"success"rn
}rn
HTTP请求最重要的部分是第一行的HTTP错误码, 以及随后几行的封装在单个JSON编码的对象中,该对象由一对卷筒括号表示的请求信息.
注意:极力推荐使用第三方的HTTP库而不是新的自定义实现.符合标准的HTTP客户端实现广泛应用于大多数操作系统和硬件平台(如Libwww或libcURL).
1.2.5 HTTP状态码
设备使用的HTTP状态码在如下的表格中例出:
![36e8e3ae925de59e25535eef59bb345a.png](https://i-blog.csdnimg.cn/blog_migrate/dc8e7b4a92cf8c6123bc3c3f43f3b3ea.jpeg)
无效的查询将引起一个HTTP错误
![6682b8250f1807266bd5665740ff8795.png](https://i-blog.csdnimg.cn/blog_migrate/02aa79fd0b814de62bc050850578526d.jpeg)
1.2.6 sensor错误码
如下的表格例出了设备返回常用的错误码(error_code);
![0bc6392fc2070f344bc38d7963b81bc9.png](https://i-blog.csdnimg.cn/blog_migrate/919884d076d9a1c412296f2d917f447e.jpeg)
引发传感器错误代码的(无效)命令示例:
![4910482cc7c51bf641b54423b14f21fd.png](https://i-blog.csdnimg.cn/blog_migrate/4d2997c110aee65339821277a4938da5.jpeg)
1.2.7 协议信息(get_protocol_info)
以太网协议用户应该知道, 根据协议版本,一些命令可能不可用或可能表现出不同的行为. 为此,用户应用程序应该始终使用专用的检查协议版本的命令(get_protocol_info ), 它返回关于通信协议的基本版本信息:
![5b203abc5282a89421afc649b3090e1d.png](https://i-blog.csdnimg.cn/blog_migrate/c51810df22931b24382b3beaf667ba52.jpeg)
本文档参考1.02协议版本, R2000可能使用1.21和更新的版本.
注意:get_protocol_info 命令将返回上面每个sensor的信息-不管固件版本是多少. 所有的其它命令及其返回值可能会通过通信协议的更新而改变.因此强烈建议首先检查协议版本.
Example
Query: http://<sensor IP address>/cmd/get_protocol_info
Reply: {
"protocol_name":"pfsdp",
"version_major":1,
"version_minor":1,
"commands":[
"get_protocol_info",
"list_parameters",
"get_parameter",
"set_parameter",
"reboot_device",
"reset_parameter",
"request_handle_udp",
"request_handle_tcp",
"feed_watchdog",
"get_scanoutput_config",
"set_scanoutput_config",
"start_scanoutput",
"stop_scanoutput",
"release_handle"
],
"error_code":0,
"error_text":"success"
}
2 基于HTTP的传感器参数化
2.1 参数类型
sensor提供了不同类型的参数访问. 如下表格给出了相关类型的快速概述, 更信息的信息描述在子章节如下:
![a054d5ce039173de5e32ea5143c64204.png](https://i-blog.csdnimg.cn/blog_migrate/5fac1d70d150b628e61fdfaa516e3c94.jpeg)
每个参数类型是独立的,都具有如下如下访问组权限
![a37a6a90e6d2cc38083cb2220584c32a.png](https://i-blog.csdnimg.cn/blog_migrate/7ed4e0b4ba4d2bc0a7c7da8ab1d80578.jpeg)
许多传感器参数存在非易失性存储器中.在上电循环下参数不会丢失.
注意: 非易失性存储器仅仅有几个写入循环周期(> 10 cycles). 因此非易失性参数必须在必要时才写入
2.1.1 枚举值
2.1.2 布尔值
2.1.3 位域类型
2.1.4 整数类型
2.1.5 double类型
2.1.6 string类型
2.1.7 IPv4地址和子网掩码
2.1.8 NTP时间戳
2.1.9 二进制数据
2.2 sensor参数化命令
本节描述可用于操作全局传感器参数的所有命令。
2.2.1 list_parameters - ;例表参数
list_parameters命令返回所有可用的全局sensor参数
示例:
Query: http://<sensor IP address>/cmd/list_parameters
Reply: {
"parameters":[
"vendor",
"product",
"part",
"serial",
"revision_fw",
"revision_hw",
"max_connections",
"feature_flags",
"radial_range_min",
"radial_range_max",
"radial_resolution",
"angular_fov",
"angular_resolution",
"ip_mode",
"ip_address",
"subnet_mask",
"gateway",
"scan_frequency",
"scan_direction",
"samples_per_scan",
"scan_frequency_measured",
"status_flags",
"load_indication",
"device_family",
"mac_address",
"hmi_display_mode",
"hmi_language",
"hmi_button_lock",
"hmi_parameter_lock",
"ip_mode_current",
"ip_address_current",
"subnet_mask_current",
"gateway_current",
"system_time_raw",
"user_tag",
"user_notes",
"locator_indication",
],
"error_code":0,
"error_text":"success"
}
2.2.2 get_parameter - 读取参数
get_parameter命令读取当前全局sensor参数对应的数值:
http://<sensor IP address>/cmd/get_parameter?list=<param1>;<param2>
命令参数
list - 分号分隔的参数名称列表(可选)
如果list参数没有指定命令,将会返回所有可用参数的values
示例:
Query: http://<sensor IP address>/cmd/get_parameter?list=scan_frequency;scan_frequency_measured
Reply: {
"scan_frequency":50,
"scan_frequency_measured":49.900000,
"error_code":0,
"error_text":"success"
}
2.2.3 set_parameter - 改变参数
使用set_parameter设置任意全局变量的values:
http://<sensor IP address>/cmd/set_parameter?<param1>=<value>&<param2>=<value>
命令参数
<param1> = <value> – new <value> for parameter <param1>
<param2> = <value> – new <value> for parameter <param2>
. . .
注意: 如果任意指定的命令参数是未知或只读的,set_parameter命令返回一个error消息. error_code和error_text在这种情况返回对应的值
示例:
Query: http://<sensor IP address>/cmd/set_parameter?scan_frequency=50
Reply: {
"error_code":0,
"error_text":"success"
}
2.2.4 reset_parameter - 复位参数默认值
reset_parameter命令复位一个或更多全局sensor参数到他们默认的values:
http://<sensor IP address>/cmd/reset_parameter?list=<param1>;<param2>
命令参数:
list - 分号分隔的参数名称列表(可选)
注意:
1. 如果list参数没有指定命令,对于所有可写参数它使用set_parameter将加载默认values
2. 此命令适用于仅通过命令set_parameter 全局的R/W访问的参数. 如果List参数包含了一个未知或只读的参数,将会返回一个error信息
3. 复位参数到默认值可能要求重启设备生效.例如.所有的网络配置参数
示例:
Query: http://<sensor IP address>/cmd/reset_parameter?list=scan_frequency;scan_direction
Reply: {
"error_code":0,
"error_text":"success"
}
2.2.5 reboot_device - 重启sensor固件
reboot_device命令触发sensor固件软重启
http://<sensor IP address>/cmd/reboot_device
命令参数
该命令不接受额外的参数. HTTP reply发送后将会完成reboot.
注意:
1. 重启将会终止所有正在扫描数据输出.所有扫描数据句柄无效,重启后必须重新开始.(见3.4节)
2. 设备60s完成重启(依靠sensor的配置). 重启完成同时sensor会再次应答HTTP命令请求, 并且系统status flag初始化将被清除.
示例:
Query: http://<sensor IP address>/cmd/reboot_device
Reply: {
"error_code":0,
"error_text":"success"
}
2.2.6 factory_reset – 恢复默认出厂设置
1.01协议增加了factory_reset命令用于所有sensor完成恢复出厂设置并重启设备.跟调用reset_parameter命令类似不需要任意参数.
命令参数
命令不要额外附加参数. 当HTTP reply发送完成后设备恢复出厂设置并完成重启.
注意:
恢复出厂设置完成设备重启. 因为某些改变可能会在启动阶段对sensor产生影响(例如所有的网络配置参数-看2.5章节)
示例:
Query: http://<sensor IP address>/cmd/factory_reset
Reply: {
"error_code":0,
"error_text":"success"
}
2.3 基本sensor信息
所有sensor参数在本章节描述
2.3.1 参数概述
如下表格例出了很多提供基本的sensor信息参数(很多仅仅只读)
![eda6e2793fd8d42084af402918bcfe40.png](https://i-blog.csdnimg.cn/blog_migrate/aaff62718d8ddfb082be7ab3ac1a388e.jpeg)
这些条目与IO-Link设备上可用的通用信息相媲美.与IO-Link对比大多数string没有大小限制,因此每个参数能够使用get_parameter命令单独读取.
2.3.2 设备族 (device_family)
device_family参数能够用于验证设备兼容性. 单一的设备族定义为具有相同功能的设备组(关于以太网协议).这个标识符用来检查所连接的设备是否与客户端应用程序兼容(例如DTM用户接口).
当前的device_family定义如下的values:
![0f890328373cee5bffe501cb87246f2a.png](https://i-blog.csdnimg.cn/blog_migrate/5c3aa03f0ebba6656fb60de197b8f4ef.jpeg)
2.3.3 用户自定义string(user_tag, user_notes)
user_tag和user_notes参数是字符串. 可以由用户使用而不受限制(除了有效的UTF-8编码-参见第2.1节中类型字符串的定义). user_tag 默认value通常是段版本的产品名称(parameter product), user_notes 默认为空.
2.4 Sensor capabilities
2.4.1 参数概述
如下只读参数用于描述sensor capabilities:
![6412f39f95719f89151cf796aa263112.png](https://i-blog.csdnimg.cn/blog_migrate/155e76b17a923d79c13ce22d229ec2af.jpeg)
2.4.2 设备特征(feature_flags)
feature_flags参数返回一个JSON编码的可查询的设备特征例表. 当前有如下特征被定义:
![6c7f23bbebb3b3080f081a68ef7e2961.png](https://i-blog.csdnimg.cn/blog_migrate/75b5a42d95be53245aaa5c9d0210a194.jpeg)
如果一个特性可用,它的名称被列在feature_flags数组中.
2.4.3 Emitter type (emitter_type) 发射器类型
emitter_type参数用于确定特定传感器使用的激光发射器类型(aka transmitter). 目前对于R2000设备定义了如下发射器类型:
![b51b0176838b5551a2b7c66a4ccbdfac.png](https://i-blog.csdnimg.cn/blog_migrate/c211a5694c2ed09acecf44ad001d7aa5.jpeg)
2.5 以太网配置
2.5.1 参数概述
如下的参数允许改变以太网接口配置:
![8205b0c7c320880b323f753fb5fe29ce.png](https://i-blog.csdnimg.cn/blog_migrate/975b9fea963c82fe4aa985301a3fad49.jpeg)
ip_mode_current, ip_address_current, subnet_mask_current and gateway_curren只读参数提供了访问当前活动IP配置信息. 当通过DHCP或AutoIP时非常有用.
注意:
在系统重新启动之后,当系统reboot, 以太网配置(使用set_parameterh或reset_parameter)的任何更改将生效. 只有!命令reboot_device (see section 2.2.5) 可用于使用以太网协议启动重新启动。
2.5.2 IP地址模式(ip_mode)
ip_mode参数配置如下的其中一种IP地址模式:
static – 使用p_address, subnet_mask, gateway配置静态IP
autoip – 使用"Zero Configuration Networking" [14]自动配置IP
dhcp – 使用DHCP服务自动分配IP
注意:
使用DHCP或AutoIP自动配置IP参数ip_address_current and subnet_mask_current
可能会返回无效的 IP address 0.0.0.0如果没有有效的IP地址被分配给sensor (e.g. 没有DHCP被发现).
2.6 测试配置
2.6.1 参数预览
如下的global参数可用于基本测试配置:
![16d10f05fcf453d0a985291c016d0284.png](https://i-blog.csdnimg.cn/blog_migrate/9bd3d67857a531b304bca13f2cdf10c2.jpeg)
2.6.2 操作模式(operating_mode)
operating_mode参数控制sensor的操作模式. 当前有如下模式可以使用:
![2a57f11e162d1023ddcc0a9ae0bf030e.png](https://i-blog.csdnimg.cn/blog_migrate/5db129fb3bc1325742914e0bc4ed36f0.png)
模式测量指sensor正常的操作模式和默认上电以后. transmitter_off 模式允许用户停用激光发射器, 例如为避免其他光学设备的干扰. 如果连接正常但没有扫描数据,即所有的句柄都已被释放,则从测量切换到关掉发射器模式. 当操作模式被设置成关掉发射器时, 没有新的扫描数据连接句柄被请求(见第3.2节). status flag会被系统scan_output_muted (see section 2.8.2)
示例:
Query: http://<sensor IP address>/cmd/set_parameter?operating_mode=measure
Reply: {
"error_code":0,
"error_text":"success"
}
2.6.3 扫描频率(scan_frequency, scan_frequency_measured)
scan_frequency参数定义传感器头扫描定数对应的旋转速度,并确定每秒种扫描记录的点数(详情见第3.1节). 对于R2000有效值范围从10Hz到50Hz,1Hz的步进(默认是35Hz).非整数被自动舍入到整数值. scan_frequency_measured 参数读取传感器头的旋转速度的实际值(分辨率为0.1Hz)。该参数仅仅只读.
示例:
Query: http://<sensor IP address>/cmd/get_parameter?list=scan_frequency;scan_frequency_measured
Reply: {
"scan_frequency":35,
"scan_frequency_measured":34.900000,
"error_code":0,
"error_text":"success"
}