.action文件定义接口¶

本文规定了来自ROS 1的文件格式，描述了ROS组件之间交换的数据结构，以便它们相互交互。

作者：Dirk Thomas¶

撰写日期：2019-03¶

最后修改：2021-02¶

范围¶

本文规定了来自ROS 1的文件格式，描述了用于组件间交换信息的数据结构。数据结构以不受编程语言限制的方式定义。该格式基于ROS 1中的.msg格式定义。

下面仅描述了映射到IDL类型的部分。请参见“接口定义和语言映射”文章，了解如何映射到特定于编程语言的类型和API。

概述¶

数据结构由一组字段定义。字段的顺序无关紧要。每个字段由类型和名称描述。

消息¶

单个数据结构称为消息。每个消息都有一个名称。结合包的名称，可以唯一地识别消息。

服务¶

对于请求/回复风格的通信，两个交换的数据结构是相关的。这些数据结构对称为服务。服务通过其名称和所在的包来识别。每个服务描述两个消息，一个用于请求数据结构，一个用于回复数据结构。

动作¶

对于带有进度反馈的长时间运行的请求/回复风格通信，交换的数据结构是相关的。这些数据结构的三元组称为动作。动作通过其名称和所在的包来识别。每个动作描述三个消息，一个用于目标数据结构，一个用于结果数据结构，一个用于反馈数据结构。

字段类型¶

字段的类型可以是原始类型或其他数据结构。这些可以是动态或静态大小的数组。

原始字段类型¶

定义了以下原始类型：

bool
byte
char
float32, float64
int8, uint8
int16, uint16
int32, uint32
int64, uint64
string

虽然在ROS 1中byte和char已弃用，但它们仍然是此定义的一部分，以便于迁移。

在ROS 1中，字符串未指定任何编码，传输对其不敏感。这意味着通常它只能包含ASCII。对于明确支持宽字符字符串，请考虑迁移到.idl文件，它定义了明确的类型。

非原始字段类型¶

除了原始类型，还可以引用其他消息来描述“复杂”字段的类型。复杂字段类型由包和消息名称识别。

静态大小数组¶

静态数组恰好有N个指定类型的元素。N必须大于0。

动态大小数组¶

动态数组可以有0到N个指定类型的元素。N可能没有上限，可能仅受内存或其他系统特定限制的限制。

上限¶

此功能在ROS 1中不可用。

字符串以及动态数组的大小可以通过上限限制。这使得可以为使用动态大小数据的数据结构预分配内存。

默认值¶

此功能在ROS 1中不可用。

字段可以可选地指定默认值。如果没有指定默认值，则使用通用默认值：

对于bool，它是false
对于数值类型，它是0值
对于字符串，它是一个空字符串
对于静态大小数组，它是一个N个元素的数组，其字段被零初始化
对于有界大小数组和动态大小数组，它是一个空数组 []

数组默认值¶

类型为数组的字段可以可选地指定默认值。

数组的默认值必须以开方括号([)开始并以闭方括号(])结束
数组中的每个值必须用逗号(,)分隔
数组中的所有值必须与字段的类型相同
数组的第一个值之前不能有逗号，
数组最后一个元素后的尾随逗号被忽略

字符串数组的额外规则：

字符串数组必须只包含遵循以下规则的字符串：

可以可选地用单引号(’)或双引号(”)引用的字符串值
双引号(”)的字符串（分别用单引号(’)）应该将任何内部双引号（分别用单引号）转义

常量¶

常量由原始类型、名称和固定值定义。如果原始类型是整数类型，固定值可以以以下方式之一指定：

十进制整数，例如1
二进制整数，例如0b01或0B01
八进制整数，例如0o01或0O01
十六进制整数，例如0x01或0X01

约定¶

消息和服务的命名¶

每个文件包含一个消息或服务。消息文件使用扩展名.msg，服务文件使用扩展名.srv。

文件名必须使用大驼峰命名法，并且只包含字母数字字符。

字段的命名¶

字段名称必须使用小写字母数字字符，用下划线分隔单词。它们必须以字母字符开头，不能以下划线结尾，并且不能有两个连续的下划线。

常量的命名¶

常量名称必须使用大写字母数字字符，用下划线分隔单词。它们必须以字母字符开头，不能以下划线结尾，并且不能有两个连续的下划线。

语法¶

消息和服务定义是文本文件。

注释¶

字符#开始一个注释，它在发生注释的行的末尾终止。

消息文件格式¶

一行可以包含字段定义或常量定义。单个空格是分隔标记的必须的，可以在标记之间插入额外的空格。

字段定义¶

字段定义具有以下结构：

<type> <name> <optional_default_value>

常量定义¶

常量定义具有以下结构：

<type> <name>=<value>

类型¶

<type>由其基础类型和可选的数组说明符定义。

基础类型可以是以下之一：

上述列表中的一个原始类型：例如int32
具有上限的字符串：string<=N以将字符串长度限制为N个字符
引用另一个消息的复杂类型：
- 消息的绝对引用：例如some_package/SomeMessage
- 同一包内消息的相对引用：例如OtherMessage

数组说明符可以是以下之一：

静态数组由后缀[N]描述，其中N是数组的固定大小
无界动态数组由后缀[]描述
有界动态数组由后缀[<=N]描述，其中N是数组的最大大小

值¶

根据类型，以下值是有效的：

bool：
- true, 1
- false, 0
byte：
- 在[0, 255]区间内的不透明8位数
char：
- 在[0, 255]区间内的无符号整数值
float32和float64：
- 使用点(.)作为整数部分和小数部分之间的分隔符的十进制数。
int8, int16, int32和int64：
- 在[- 2 ^ (N - 1), 2 ^ (N - 1) - 1]区间内的整数值，其中N是int后面的位数
uint8, uint16, uint32和uint64：
- 在[0, 2 ^ N - 1]区间内的无符号整数值，其中N是uint后面的位数
string：
- 可以可选地用单引号(’)或双引号(”)引用的字符串值

双引号(”)的字符串（分别用单引号(’)）应该将任何内部双引号（分别用单引号）转义：

string my_string “I heard “Hello”” 是有效的
string my_string “I heard “Hello”” 是无效的
string my_string “I heard ‘Hello’” 是有效的
string my_string ‘I heard ‘Hello’’ 是有效的
string my_string ‘I heard ‘Hello’’ 是无效的
string my_string ‘I heard “Hello”’ 是有效的

服务文件格式¶

服务文件包含两个消息定义，它们由只包含三个破折号的一行分隔：

转换为IDL¶

为定义的接口生成代码，以便不同的客户端库可以使用。使用上述格式描述的接口首先转换为IDL。代码生成使用生成的文件。

在上述格式中定义的结构可能是空的/不包含成员。在这种情况下，生成的.idl结构将有一个虚拟成员（uint8 structure_needs_at_least_one_member），以满足IDL的非空要求。

映射到IDL类型¶

字节的映射使用了与ROS 1不同的类型，同时仍然是一个不透明的8位数。ROS 1中的定义：已弃用的int8的别名。IDL (7.4.1.4.4.2.6)中的定义：一个不透明的8位数。

虽然字符的映射不太直观，但它保持了与ROS 1定义的兼容性：“已弃用的uint8的别名”。

ROS类型	IDL类型
静态数组	array
无界动态数组	sequence
有界动态数组	bounded sequence
有界字符串	bounded string