Skip to content

Autoware 接口设计#

摘要#

Autoware defines three categories of interfaces. The first one is Autoware AD API for operating the vehicle from outside the autonomous driving system such as the Fleet Management System (FMS) and Human Machine Interface (HMI) for operators or passengers. The second one is Autoware component interface for components to communicate with each other. The last one is the local interface used inside the component.

Autoware 定义了三类接口.第一个是 Autoware AD API,用于从自动驾驶系统外部作车辆,例如车队管理系统 (FMS) 和作员或乘客的人机界面 (HMI).第二个是 Autoware 组件接口,用于组件相互通信.最后一个是组件内部使用的本地接口.

概念#

  • Applications can operate multiple and various vehicles in a common way.

  • 应用程序可以以通用方式作多个和不同的车辆.

    统一访问

  • Applications are not affected by version updates and implementation changes.

  • 应用程序不受版本更新和实施更改的影响.

    吸收变化

  • Developers only need to know the interface to add new features and hardware.

  • 开发人员只需要了解界面即可添加新功能和硬件.

    新功能

要求#

目标:

  • AD API provides functionality to create the following applications:
    • Drive the vehicle on the route or drive to the requested positions in order.
    • Operate vehicle behavior such as starting and stopping.
    • Display or announce the vehicle status to operators, passengers, and people around.
    • Control vehicle devices such as doors.
    • Monitor the vehicle or drive it manually.
  • AD API provides stable and long-term specifications. This enables unified access to all vehicles.
  • AD API hides differences in version and implementation and absorbs the impact of changes.
  • AD API has a default implementation and can be applied to some simple ODDs with options.
  • The AD API implementation is extensible with the third-party components as long as it meets the specifications.
  • The component interface provides stable and medium-term specifications. This makes it easier to add components.
  • The component interface clarifies the public and private parts of a component and improves maintainability.
  • The component interface is extensible with the third-party design to improve the sub-components` reusability.
  • AD API 提供创建以下应用程序的功能：
    • 在路线上驾驶车辆或按顺序驾驶到请求的位置. -作车辆行为,例如启动和停止.
    • 向作员、乘客和周围的人显示或宣布车辆状态.
    • 控制车门等车辆设备.
    • 监控车辆或手动驾驶车辆.
  • AD API 提供稳定和长期的规范.这样就可以统一访问所有车辆.
  • AD API 隐藏了版本和实现的差异,并吸收了更改的影响.
  • AD API 具有默认实现,可以通过选项应用于一些简单的 ODD.
  • 只要 AD API 实现符合规范,就可以使用第三方组件进行扩展.
  • 组件接口提供稳定的中期规格.这使得添加组件变得更加容易.
  • 组件接口明确了组件的公有部分和私有部分,提高了可维护性.
  • 组件接口支持第三方设计扩展,提高子组件的复用性.

非目标:

  • AD API does not cover security. Use it with other reliable methods.
  • The component interface is just a specification, it does not include an implementation.
  • AD API 不涵盖安全性.将其与其他可靠的方法一起使用.
  • 组件接口只是一个规范,它不包括一个实现.

架构#

The components of Autoware are connected via the component interface. Each component uses the interface to provide functionality and to access other components. AD API implementation is also a component. Since the functional elements required for AD API are defined as the component interface, other components do not need to consider AD API directly. Tools for evaluation and debugging, such as simulators, access both AD API and the component interface.

Autoware 的组件通过组件接口连接. 每个组件都使用该接口来提供功能并访问其他组件. AD API 实现也是一个组件. 由于 AD API 所需的功能元被定义为组件接口,因此其他组件不需要直接考虑 AD API. 用于评估和调试的工具(如模拟器)可访问 AD API 和组件接口.

架构

The component interface has a hierarchical specification. The top-level architecture consists of some components. Each component has some options of the next-level architecture. Developers select one of them when implementing the component. The simplest next-level architecture is monolithic. This is an all-in-one and black box implementation, and is suitable for small group development, prototyping, and very complex functions. Others are arbitrary architecture consists of sub-components and have advantages for large group development. A sub-component can be combined with others that adopt the same architecture. Third parties can define and publish their own architecture and interface for open source development. It is desirable to propose them for standardization if they are sufficiently evaluated.

组件接口具有分层规范. 顶级体系结构由一些组件组成.每个组件都有一些 next level 体系结构的选项. 开发人员在实现组件时选择其中一个.最简单的下一级架构是整体式架构. 这是一个一体化的黑盒实现,适用于小组开发、原型设计和非常复杂的功能. 其他的则是任意架构,由子组件组成,具有大型群组开发的优势. 子组件可以与采用相同架构的其他组件组合. 第三方可以定义和发布自己的架构和接口,用于开源开发. 如果它们得到充分评估,建议将它们标准化是可取的.

组件

特征#

通信方式#

As shown in the table below, interfaces are classified into four communication methods to define their behavior. Function Call is a request-response communication and is used for processing that requires immediate results. The others are publish-subscribe communication. Notification is used to process data that changes with some event, typically a callback. Streams handle continuously changing data. Reliable Stream expects all data to arrive without loss, Realtime Stream expects the latest data to arrive with low delay.

如下表所示,接口分为四种通信方式来定义其行为. 函数调用是一种请求-响应通信,用于需要立即结果的处理.其他是发布-订阅通信. Notification 用于处理随某些事件(通常是回调)而变化的数据.Streams 处理不断变化的数据. Reliable Stream 期望所有数据无损到达,Realtime Stream 期望最新数据以低延迟到达.

通信方式 ROS 实现 可选实现
Function Call Service HTTP
Notification Topic (reliable, transient_local) MQTT (QoS=2, retain)
Reliable Stream Topic (reliable, volatile) MQTT (QoS=2)
Realtime Stream Topic (best_effort, volatile) MQTT (QoS=0)

These methods are provided as services or topics of ROS since Autoware is developed using ROS and mainly communicates with its packages. On the other hand, FMS and HMI are often implemented without ROS, Autoware is also expected to communicate with applications that do not use ROS. It is wasteful for each of these applications to have an adapter for Autoware, and a more suitable means of communication is required. HTTP and MQTT are suggested as additional options because these protocols are widely used and can substitute the behavior of services and topics. In that case, text formats such as JSON where field names are repeated in an array of objects, are inefficient and it is necessary to consider the serialization.

这些方法作为 ROS 的服务或主题提供,因为 Autoware 是使用 ROS 开发的,主要与它的包通信. 另一方面,FMS 和 HMI 通常在没有 ROS 的情况下实现,Autoware 也希望与不使用 ROS 的应用程序进行通信. 这些应用程序中的每一个都拥有 Autoware 的适配器是浪费的,并且需要更合适的通信方式. 建议将 HTTP 和 MQTT 作为附加选项,因为这些协议被广泛使用,并且可以替代服务和主题的行为. 在这种情况下,文本格式(如 JSON)在对象数组中字段名称重复,效率低下,因此有必要考虑序列化.

命名约定#

The name of the interface must be /<component name>/api/<interface name>, where <component name> is the name of the component. For an AD API component, omit this part and start with /api. The <interface name> is an arbitrary string separated by slashes. Note that this rule causes a restriction that the namespace api must not be used as a name other than AD API and the component interface.

接口名称必须为 /<component name>/api/<interface name>, 其中 <component name> 是组件的名称.对于 AD API 组件,请省略此部分并以 /api 开头. <interface name> 是一个用斜杠分隔的任意字符串. 请注意,此规则会导致命名空间 api 不得用作 AD API 和组件接口以外的名称的限制.

The following are examples of correct interface names for AD API and the component interface:

以下是 AD API 和组件接口的正确接口名称示例：

  • /api/autoware/state
  • /api/autoware/engage
  • /planning/api/route/set
  • /vehicle/api/status

The following are examples of incorrect interface names for AD API and the component interface:

以下是 AD API 和组件接口的接口名称不正确的示例：

  • /ad_api/autoware/state
  • /autoware/engage
  • /planning/route/set/api
  • /vehicle/my_api/status

日志#

It is recommended to log the interface for analysis of vehicle behavior. If logging is needed, rosbag is available for topics, and use logger in rclcpp or rclpy for services. Typically, create a wrapper for service and client classes that logs when a service is called.

建议记录界面以分析车辆行为. 如果需要日志记录,rosbag 可用于主题,并在 rclcpp 中使用 logger 或将 rclpy 用于服务. 通常,为 service 和 client 类创建一个包装器,以便在调用服务时进行记录.

限制#

For each API, consider the restrictions such as following and describe them if necessary.

对于每个 API,请考虑以下限制,并在必要时对其进行描述.

服务业:

  • response time
  • pre-condition
  • post-condition
  • execution order
  • concurrent execution
  • 响应时间
  • 前提条件
  • 后置条件
  • 执行顺序
  • 并发执行

主题:

  • recommended delay range
  • maximum delay
  • recommended frequency range
  • minimum frequency
  • default frequency
  • 建议的延迟范围
  • 最大延迟
  • 推荐频率范围
  • 最小频率
  • 默认频率

数据结构#

数据类型定义#

Do not share the types in AD API unless they are obviously the same to avoid changes in one API affecting another. Also, implementation-dependent types, including the component interface, should not be used in AD API for the same reason. Use the type in AD API in implementation, or create the same type and copy the data to convert the type.

请勿在 AD API 中共享类型,除非它们明显相同,以避免一个 API 中的更改影响另一个 API. 此外,出于同样的原因,不应在 AD API 中使用依赖于实现的类型(包括组件接口). 在实现中使用 AD API 中的类型,或创建相同的类型并复制数据以转换类型.

常量和枚举#

Since ROS don`t support enumeration, use constants instead. The default value of type such as zero and empty string should not be used to detect that a variable is unassigned. Alternatively, assign it a dedicated name to indicate that it is undefined. If one type has multiple enumerations, comment on the correspondence between constants and variables. Do not use enumeration values directly, as assignments are subject to change when the version is updated.

由于 ROS 不支持枚举,因此请改用常量. type 的默认值(如 zero 和空 string)不应用于检测变量是否未分配. 或者,为其分配一个专用名称以指示它是 undefined. 如果一种类型有多个枚举,请对常量和变量之间的对应关系进行注释. 不要直接使用枚举值,因为当版本更新时,分配可能会发生变化.

时间戳#

Clarify what the timestamp indicates. for example, send time, measurement time, update time, etc. Consider having multiple timestamps if necessary. Use std_msgs/msg/Header when using ROS transform. Also consider whether the header is common to all data, independent for each data, or additional timestamp is required.

阐明时间戳的含义.例如,发送时间、测量时间、更新时间等.如有必要,请考虑使用多个时间戳. 使用 ROS 转换时使用 std_msgs/msg/Header. 还要考虑标头是所有数据通用的,还是每个数据独立,还是需要额外的时间戳.

请求标头#

Currently, there is no required header.

目前,没有必需的标头.

响应状态#

The interfaces whose communication method is Function Call use a common response status to unify the error format. These interfaces should include a variable of ResponseStatus with the name status in the response. See autoware_adapi_v1_msgs/msg/ResponseStatus for details.

通信方式为 Function Call 的接口使用通用的响应状态来统一错误格式. 这些接口应在响应中包含名称为 status 的 ResponseStatus 变量. 有关详细信息,请参见 autoware_adapi_v1_msgs/msg/ResponseStatus.

关注点、假设和限制#

  • The applications use the version information provided by AD API to check compatibility. Unknown versions are also treated as available as long as the major versions match (excluding major version 0). Compatibility between AD API and the component interface is assumed to be maintained by the version management system.
  • If an unintended behavior of AD API is detected, the application should take appropriate action. Autoware tries to keep working as long as possible, but it is not guaranteed to be safe. Safety should be considered for the entire system, including the applications.
  • 应用程序使用 AD API 提供的版本信息来检查兼容性. 只要主要版本匹配(不包括主要版本 0),未知版本也会被视为可用. 假定 AD API 与组件接口之间的兼容性由版本管理系统维护.
  • 如果检测到 AD API 的意外行为,应用程序应采取适当的措施. Autoware 会尝试尽可能长时间地保持工作状态,但不能保证它是安全的. 应考虑整个系统(包括应用)的安全性.