# RAE SDK

RAE Python SDK 包含一组 Python 类和函数，允许您与 RAE 机器人进行交互。 在底层，它使用 ROS2 接口与外设通信，以及 ROS 库。

## 要求

要在 Luxonis Hub 中使用 RAE SDK，您需要：

 * 将机器人的固件升级到最新版本 (Luxonis OS 1.14)。

> **Note**
> 固件更新后，您可能仍然会看到升级到最新版本的选项。这是一个已知问题，您可以安全地忽略它。只要您安装了 Luxonis OS 1.14 和 Agent 版本 23.223.1855，您就可以正常使用了。

 * 在 robotapp.toml 文件中指定正确的镜像。截至撰写本指南时，最新镜像为 `ghcr.io/luxonis/rae-ros:v0.2.2-humble`。

## 机器人

`Robot` 类是 SDK 的主要入口点。它提供对所有机器人组件的访问，并允许您 控制它们。 它包含以下属性（更多内容将在后续章节中介绍）：

 * ROS 接口
 * LED
 * 显示屏
 * 音频
 * 运动
 * 感知系统

初始化 Robot 类时，默认情况下还会启动外设和车轮的硬件驱动程序，除非在机器人选项中另有说明。

```python
from rae_sdk.robot import Robot

robot = Robot()
```

### 机器人选项

您可以将选项传递给 Robot 类以自定义其行为。以下示例显示了所有可用选项：

```python

from rae_sdk.robot import Robot, RobotOptions

options = RobotOptions(name='rae_sdk', namespace='', launch_controllers=True, start_hardware=True, launch_mock=False)

robot = Robot(options)
```

 * `name` - Robot 类将创建的 ROS 节点的名称。默认值：`rae_sdk`
 * `namespace` - Robot 类将创建的 ROS 节点的命名空间。默认值：`''`
 * `launch_controllers` - 是否初始化 SDK 组件，例如 LED、显示屏、音频、导航、状态。默认值：`True`
 * `launch_mock` - 是否启动模拟硬件驱动程序而不是真实的驱动程序，主要用于测试。默认值：`False`
 * `start_hardware` - 是否启动外设和车轮的硬件驱动程序。默认值：`True`

为确保机器人干净地关闭，您应该在程序结束时调用 `robot.stop()`。

## SDK 组件

有关 API 方法和属性的完整列表，请参阅 [API 参考](/hardware/rae/rae-sdk/api-reference.md)。

### LED

LED 类提供对机器人 LED 的访问。它允许您设置 LED 的颜色并将其打开和关闭。

```python
from rae_sdk.robot import Robot

robot = Robot()

robot.led.set_leds('#FF0000', 100, 'solid', 1)  # 将颜色设置为红色
```

您也可以直接使用 LEDControl 消息：

```python
from rae_sdk.robot import Robot
from rae_msgs.msg import LEDControl, ColorPeriod

robot = Robot()

led_control = LEDControl()

color_msg = ColorPeriod()
color_msg.frequency = 1.0
color_msg.color.a = 1.0
color_msg.color.r = 1.0
color_msg.color.g = 0.0
color_msg.color.b = 0.0
led_msg.data = [color_msg]

led_msg.control_type = LEDControl.CTRL_TYPE_ALL

robot.set_leds_from_msg(led_msg)
```

### 显示屏

Display 类提供对机器人显示屏的访问。它允许您在显示屏上显示文本和图像。

```python
import cv2
from rae_sdk.robot import Robot

robot = Robot()

img = cv2.imread('image.jpg')
robot.display.display_image(img)
```

### 音频

Audio 类提供对机器人音频系统的访问。它允许您播放音频文件和文本转语音。

```python
from rae_sdk.robot import Robot

robot = Robot()

robot.audio.play_audio_file('file.mp3')
```

### 导航

Navigation 类提供对机器人运动和导航系统的访问。它允许您控制机器人的车轮并读取其位置。

```python

from rae_sdk.robot import Robot

robot = Robot()

robot.navigation.move(0.5, 0.5)  # 以 0.5 米/秒的速度和 0.5 弧度/秒的角速度向前移动

position = robot.navigation.get_odom_position()
```

### 状态

State 类提供对机器人状态的访问。它允许您读取机器人的电池电量和充电状态。

```python

from rae_sdk.robot import Robot

robot = Robot()

battery_level = robot.state.battery_state.capacity
```

### ROS 接口

ROS 接口是一个类，它提供对 ROS2 接口的访问，用于与外设通信，以及 ROS 库。 它使用 `rclpy` 库来启动自己的执行器和节点，用于与 ROS2 通信。它还使用 ROS2 启动 系统来启动机器人节点。 它对用户是抽象的，但可以通过
`robot.ros_interface` 属性访问。例如， 让我们创建一个发布者，以 1 Hz 的频率向 `/test_topic` 主题发布消息：

```python
from rae_sdk.robot import Robot
from std_msgs.msg import String

robot = Robot()

def timer_callback():
    msg = String()
    msg.data = 'Hello world!'
    robot.ros_interface.publish('/test_topic', msg)

robot.ros_interface.create_publisher('/test_topic', String)
robot.ros_interface.create_timer(1.0, timer_callback)
```

您还可以创建一个订阅者来监听 `/test_topic` 主题：

```python
from rae_sdk.robot import Robot
from std_msgs.msg import String

def callback(msg):
    print(msg.data)

robot = Robot()

robot.ros_interface.create_subscription('/test_topic', String, callback)
```

创建服务客户端也很简单：

```python
from rae_sdk.robot import Robot
from std_srvs.srv import Trigger

robot = Robot()

robot.ros_interface.create_service_client('/test_service', Trigger)
robot.ros_interface.call_async_srv('/test_service', Trigger.Request())
```

同样对于动作客户端，如果您愿意，可以覆盖接受目标、处理反馈和处理结果的默认回调。您还可以取消目标：

```python

from rae_sdk.robot import Robot
from example_interfaces.action import Fibonacci

def feedback_callback(feedback_msg):
    print('收到反馈：', feedback_msg.feedback.sequence)

def result_callback(future):
    result = future.result().result
    print('收到结果：', result.sequence)

robot = Robot()

robot.ros_interface.create_action_client('/test_action', Fibonacci)
robot.ros_interface.call_async_action("/fibonacci", Fibonacci.Goal(order=10), None, self.result_cb, self.feedback_cb)

# 取消目标 robot.ros_interface.cancel_action("/fibonacci")
```

### 资源

我们还提供了一组示例资源，您可以在应用程序中使用。您可以在 SDK 的 `assets` 文件夹中找到它们。 目前，这些资源包括一组用于机器人的面部图像和一些可用于基本交互的示例音频文件。
