SLAM 导航服务接口

功能	C++	Python	C#	Java	ROS
开始建图	✔	✔	✔	✔	✔
停止建图	✔	✔	✔	✔	✔
加载地图	✔	✔	✔	✔	✔
获取地图列表	✔	✔	✔	✔	✔
上传地图	✔	✔	✔	✔
下载地图	✔	✔	✔	✔
获取定位状态	✔	✔	✔	✔	✔
获取当前位置	✔	✔	✔	✔	✔
重定位	✔	✔	✔	✔	✔
添加导航点位	✔	✔	✔	✔	✔
添加虚拟点位	✔	✔	✔	✔	✔
删除点位	✔	✔	✔	✔	✔
获取可用点位	✔	✔	✔	✔	✔
导航控制	✔	✔	✔	✔	✔
多参数导航控制	✔	✔	✔	✔	✔
取消导航	✔	✔	✔	✔	✔
获取导航事件	✔	✔	✔	✔	✔

注意事项！！！

地图要求：在使用导航接口前，需通过雷达设备扫描环境生成点云数据创建地图文件：
a. 外部雷达设备建图：使用手机或者手持雷达设备建图（格式：pcd点云文件，坐标系：右手坐标系，Z轴朝上）
b. 内部机器狗雷达建图：通过调用SDK接口或者使用SDK可视化面板工具建图启动/结束建图，建图过程中需遥控机器狗慢速移动，结束建图成功会将地图保存在机器狗内，可以选择是否加载地图使用。
c. 需要确保导航的区域进行完整的扫描生成点云信息
模式要求：启动导航控制需将机器人模式切换到导航模式，可通过配套手柄应用切换，或者在二次开发的程序中调用《高层运动服务接口》章节“设置控制模式”接口切换成导航模式。
导航使用流程：
a. 机器狗无地图或者需变更地图：建图 ---> 重定位成功 ---> 创建点位 ---> 执行导航（点位名称或坐标）
b. 机器狗有当前环境地图：重定位成功 ---> 获取点位 ---> 创建点位（可选） ---> 执行导航（点位名称或坐标）
当前导航支持直线行走，不支持自动绕障，在创建点位时需注意两个点位直线上不要有障碍物。

建图接口

Python接口

`Optional[Dict] start_mapping(timeout=10.0)`

功能说明\ 开始构建地图。

参数说明

参数名	类型	必填/默认值	说明
`timeout`	`float`	默认: 10.0	超时时间（秒）。

返回值

类型	说明
`Optional[Dict]`	包含以下字段： - `success (bool)`: 是否成功启动建图 - `message (str)`: 操作结果信息

调用示例

python

from daystar_sdk import WebSocketRobotClient
# 初始化客户端
with WebSocketRobotClient(host='localhost', port=5252) as client:
    result = await client.start_mapping()

`Optional[Dict] stop_mapping(map_name, auto_reload=True, timeout=10.0)`

功能说明
停止建图并保存。

参数说明

参数名	类型	必填/默认值	说明
`map_name`	`str`	必填	地图保存名称。
`auto_reload`	`bool`	默认: True	保存后是否自动加载该地图。
`timeout`	`float`	默认: 10.0	超时时间（秒）。

返回值

类型	说明
`Optional[Dict]`	包含以下字段： - `success (bool)`: 是否成功停止并保存 - `message (str)`: 操作结果信息

调用示例

python

from daystar_sdk import WebSocketRobotClient
# 初始化客户端
with WebSocketRobotClient(host='localhost', port=5252) as client:
    # 停止建图并保存为 'office_map'
    result = await client.stop_mapping("office_map", auto_reload=True)

C#接口

`(bool success, string message) StartMapping(int id = 209, int timeoutMs = 10000)`

功能说明
开始建图。

参数说明

参数名	类型	必填/默认值	说明
`id`	`int`	默认: 209	请求ID（可忽略）。
`timeoutMs`	`int`	默认: 10000	超时时间（毫秒）。

返回值

类型	说明
`(bool success, string message)`	操作结果元组。

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();

var result = _navigationClient.StartMapping();
if (result.success)
{
    Debug.Log("开始建图...");
}

`(bool success, string message) StopMapping(string mapName, bool autoReload = true, int id = 210, int timeoutMs = 10000)`

功能说明
停止建图并保存地图。

参数说明

参数名	类型	必填/默认值	说明
`mapName`	`string`	必填	地图保存名称。
`autoReload`	`bool`	默认: true	是否自动加载新地图。
`id`	`int`	默认: 210	请求ID（可忽略）。
`timeoutMs`	`int`	默认: 10000	超时时间（毫秒）。

返回值

类型	说明
`(bool success, string message)`	操作结果元组。

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();

var result = _navigationClient.StopMapping("office_v1");
if (result.success)
{
    Debug.Log("地图保存成功");
}

Java接口

`void StartMapping(String mapName)`

功能说明
开始建图。

参数说明

参数名	类型	必填/默认值	说明
`mapName`	`String`	必填	临时地图名称（通常传空或用于标识）。

返回值

类型	说明
`void`	无返回值。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;

// 开始建图
slamNaviClient.StartMapping("");

`void StopMapping(String mapName, boolean autoReload)`

功能说明
停止建图并保存。

参数说明

参数名	类型	必填/默认值	说明
`mapName`	`String`	必填	地图保存名称。
`autoReload`	`boolean`	必填	是否自动加载新地图。

返回值

类型	说明
`void`	无返回值。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;

// 停止建图
slamNaviClient.StopMapping("office_map", true);

C++接口

`CommReply startMapping()`

功能说明
开始建图。

参数说明

参数名	类型	必填/默认值	说明
-	-	-	无参数。

返回值

类型	说明
`CommReply`	包含 `success` (bool) 和 `message` (string)。

调用示例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();

if (sysb.connect()) {
    auto reply = sysb.startMapping();
    if (reply.success) {
        std::cout << "已启动建图模式" << std::endl;
    }
}

`CommReply stopMapping(const std::string &map_name, bool auto_reload = true)`

功能说明
停止建图。

参数说明

参数名	类型	必填/默认值	说明
`map_name`	`const std::string &`	必填	地图名称。
`auto_reload`	`bool`	默认: true	是否自动重新加载。

返回值

类型	说明
`CommReply`	包含 `success` (bool) 和 `message` (string)。

调用示例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();

if (sysb.connect()) {
    auto reply = sysb.stopMapping("office_floor1");
    if (reply.success) {
        std::cout << "建图完成并保存" << std::endl;
    }
}

ROS2接口

开始建图

该接口用于启动机器人建图模式。

服务名称	服务类型	角色
`/sdk/nav/start_mapping`	`api_msgs::srv::StartMapping`	服务端

请求结构（Request）

字段名称	类型	描述
（无字段）	-	无需传入参数。

响应结构（Response）

字段名称	类型	描述
`success`	`bool`	是否成功启动建图。
`message`	`string`	操作结果信息。

调用示例

bash

ros2 service call /sdk/nav/start_mapping api_msgs/srv/StartMapping '{}'

停止建图

该接口用于停止建图并保存地图。

服务名称	服务类型	角色
`/sdk/nav/stop_mapping`	`api_msgs::srv::StopMapping`	服务端

请求结构（Request）

字段名称	类型	描述
`map_name`	`string`	地图保存名称。
`auto_reload`	`bool`	保存后是否自动加载该地图。
`need_2d_map`	`bool`	是否生成2D地图。
`block`	`bool`	是否阻塞等待完成。
`timeout`	`int32`	超时时间（秒）。

响应结构（Response）

字段名称	类型	描述
`success`	`bool`	是否成功停止并保存。
`message`	`string`	操作结果信息。

调用示例

bash

ros2 service call /sdk/nav/stop_mapping api_msgs/srv/StopMapping '{map_name: "office_map", auto_reload: true, need_2d_map: false, block: true, timeout: 10}'

地图管理接口

Python接口

`Optional[Dict] load_map(map_name, auto_reload=False, timeout=15.0)`

功能说明
加载指定地图。

参数说明

参数名	类型	必填/默认值	说明
`map_name`	`str`	必填	地图名称。
`auto_reload`	`bool`	默认: False	是否设为默认地图(True:重启机器人后自动加载，False:仅当前加载)
`timeout`	`float`	默认: 15.0	超时时间。

返回值

类型	说明
`Optional[Dict]`	包含 `success` (bool) 和 `message` (str)。

调用示例

python

from daystar_sdk import WebSocketRobotClient
# 初始化客户端
with WebSocketRobotClient(host='localhost', port=5252) as client:
    result = await client.load_map("office_map")

`Optional[Dict] get_map_list(timeout=10.0)`

功能说明
获取可用地图列表。

参数说明

参数名	类型	必填/默认值	说明
`timeout`	`float`	默认: 10.0	超时时间。

返回值

类型	说明
`Optional[Dict]`	包含 `map_names` (List[str])。

调用示例

python

from daystar_sdk import WebSocketRobotClient
# 初始化客户端
with WebSocketRobotClient(host='localhost', port=5252) as client:
    res = await client.get_map_list()
    print(res.get('map_names', []))

`bool upload_map(map_name: str, map_data: bytes, progress_callback: Callable = None)`

功能说明
上传地图文件。

参数说明

参数名	类型	必填/默认值	说明
`map_name`	`str`	必填	地图名称。
`map_data`	`bytes`	必填	地图文件二进制数据。
`progress_callback`	`Callable`	默认: None	进度回调 (current, total, bytes)。

返回值

类型	说明
`bool`	是否上传成功。

调用示例

python

with open("office.pcd", "rb") as f:
    await client.upload_map("office", f.read())

`Optional[bytes] download_map(map_name: str, progress_callback: Callable = None)`

功能说明
下载地图文件。

参数说明

参数名	类型	必填/默认值	说明
`map_name`	`str`	必填	地图名称。
`progress_callback`	`Callable`	默认: None	进度回调。

返回值

类型	说明
`Optional[bytes]`	成功返回地图数据，失败返回 None。

调用示例

python

data = await client.download_map("office")
if data:
    with open("office.pcd", "wb") as f:
        f.write(data)

C#接口

`(bool success, string message) LoadMap(string mapName, bool autoReload = false, int id = 211, int timeoutMs = 10000)`

功能说明
加载地图。

参数说明

参数名	类型	必填/默认值	说明
`mapName`	`string`	必填	地图名称。
`autoReload`	`bool`	默认: false	是否设为默认地图(true:重启机器人后自动加载，false:仅当前加载)
`id`	`int`	默认: 211	请求ID（可忽略）。
`timeoutMs`	`int`	默认: 10000	超时时间。

返回值

类型	说明
`(bool success, string message)`	操作结果元组。

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();

_navigationClient.LoadMap("office_map");

`(bool success, string[] map_names, string message) GetMapList(int id = 213, int timeoutMs = 10000)`

功能说明
获取地图列表。

参数说明

参数名	类型	必填/默认值	说明
`id`	`int`	默认: 213	请求ID（可忽略）。
`timeoutMs`	`int`	默认: 10000	超时时间。

返回值

类型	说明
`(bool success, string[] map_names, string message)`	操作结果元组。

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();

var result = _navigationClient.GetMapList();
if (result.success)
{
    foreach(var name in result.map_names) Debug.Log(name);
}

`(string status, string message) UploadMap(string mapName, byte[] mapData, int requestId = 300, int timeoutMs = 30000)`

功能说明
上传地图文件。

参数说明

参数名	类型	必填/默认值	说明
`mapName`	`string`	必填	地图名称。
`mapData`	`byte[]`	必填	地图数据。
`requestId`	`int`	默认: 300	请求ID（可忽略）。
`timeoutMs`	`int`	默认: 30000	超时时间。

返回值

类型	说明
`(string status, string message)`	操作结果 ("success" / "error")。

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();

string localMapPath = "Assets/Maps/map.pcd";
byte[] mapData = System.IO.File.ReadAllBytes(localMapPath);

_navigationClient.RegisterUploadProgressCallback(OnUploadProgress); // 监听上传进度
_navigationClient.UploadMap("office", mapData);


void OnUploadProgress(AssetTransferProgress progress)
{
    try
    {

        string displayText = $"【上传进度】\n" +
                           $"请求ID: {progress.request_id}\n" +
                           $"分块: {progress.completed_chunks}/{progress.total_chunks}\n" +
                           $"字节: {FormatBytes(progress.transferred_bytes)}/{FormatBytes(progress.total_bytes)}\n" +
                           $"进度: {progress.progress_percentage:F1}%\n" +
                           $"状态: {progress.status}";
        
        if (progress.is_completed)
        {
            if (progress.status == "completed")
            {
                displayText += "\n✓ 上传完成！";
            }
            else if (progress.status == "failed")
            {
                displayText += $"\n✗ 上传失败: {progress.error_message}";
            }
        }
        
    }
    catch (Exception ex)
    {
        Debug.LogError($"Error in OnUploadProgress: {ex.Message}");
    }
}


_navigationClient.UnregisterUploadProgressCallback();

`void DownloadMap(string mapName, int requestId = 301)`

功能说明
下载地图文件（结果通过回调）。

参数说明

参数名	类型	必填/默认值	说明
`mapName`	`string`	必填	地图名称。
`requestId`	`int`	默认: 301	请求ID（可忽略）。

返回值

类型	说明
`void`	无返回值（需注册回调）。

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();

_navigationClient.RegisterDownloadProgressCallback(OnDownloadProgress); // 监听下载进度
_navigationClient.DownloadMap("office");

void OnDownloadProgress(AssetTransferProgress progress)
{
    try
    {
        string displayText = $"【下载进度】\n" +
                           $"请求ID: {progress.request_id}\n" +
                           $"分块: {progress.completed_chunks}/{progress.total_chunks}\n" +
                           $"字节: {FormatBytes(progress.transferred_bytes)}/{FormatBytes(progress.total_bytes)}\n" +
                           $"进度: {progress.progress_percentage:F1}%\n" +
                           $"状态: {progress.status}";
        Debug.Log($"[DownloadProgress] {progressText}");
        if (progress.is_completed)
        {
            if (progress.status == "completed")
            {
                displayText += "\n✓ 下载完成！";
            }
            else if (progress.status == "failed")
            {
                displayText += $"\n✗ 下载失败: {progress.error_message}";
            }
        }
        
    }
    catch (Exception ex)
    {
        Debug.LogError($"Error in OnDownloadProgress: {ex.Message}");
    }
}

_navigationClient.UnregisterDownloadProgressCallback();

Java接口

`ServiceOperationResponse LoadMap(String mapName, boolean auto_reload)`

功能说明
加载指定地图。

参数说明

参数名	类型	必填/默认值	说明
`mapName`	`String`	必填	地图名称。
`auto_reload`	`boolean`	必填	是否设为默认地图(true:重启机器人后自动加载，false:仅当前加载)

返回值

类型	说明
`ServiceOperationResponse`	包含 `isSuccess()` (boolean) 和 `getMessage()` (String)。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;

// 加载地图
slamNaviClient.LoadMap("office_map", true);

`List<String> GetMapList()`

功能说明
获取可用地图列表。

参数说明

参数名	类型	必填/默认值	说明
-	-	-	无参数。

返回值

类型	说明
`List<String>`	地图名称列表。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;
import java.util.List;

// 获取地图列表
List<String> maps = slamNaviClient.GetMapList();
for (String map : maps) {
    System.out.println("Found map: " + map);
}

`CompletableFuture<UploadResourceResponse> uploadMap(String mapName, byte[] data, int timeoutSeconds)`

功能说明
上传地图文件。

参数说明

参数名	类型	必填/默认值	说明
`mapName`	`String`	必填	地图名称。
`data`	`byte[]`	必填	地图文件二进制数据。
`timeoutSeconds`	`int`	必填	超时时间（秒）。

返回值

类型	说明
`CompletableFuture<UploadResourceResponse>`	异步上传结果，包含状态和消息。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;
import java.nio.file.Files;
import java.nio.file.Paths;

// 上传地图
byte[] mapData = Files.readAllBytes(Paths.get("office.pcd"));
slamNaviClient.uploadMap("office", mapData, 30).thenAccept(response -> {
    if (response.isSuccess()) {
        System.out.println("Upload success");
    }
});

`CompletableFuture<byte[]> downloadMap(String mapName, int timeoutSeconds)`

功能说明
下载地图文件。

参数说明

参数名	类型	必填/默认值	说明
`mapName`	`String`	必填	地图名称。
`timeoutSeconds`	`int`	必填	超时时间（秒）。

返回值

类型	说明
`CompletableFuture<byte[]>`	异步返回地图二进制数据。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;
import java.nio.file.Files;
import java.nio.file.Paths;

// 下载地图
slamNaviClient.downloadMap("office", 30).thenAccept(data -> {
    if (data != null) {
        try {
            Files.write(Paths.get("office.pcd"), data);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
});

C++接口

`GetAvailableMapsReply getAvailableMaps()`

功能说明
获取所有可用的地图列表。

参数说明

参数名	类型	必填/默认值	说明
-	-	-	无参数。

返回值

类型	说明
`GetAvailableMapsReply`	包含 `success` 标志、`message` 消息和 `maps` 列表（`std::vector<std::string>`）。

调用示例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();
if (sysb.connect()) {
    auto reply = sysb.getAvailableMaps();
    for (const auto &map_name : reply.maps) {
        std::cout << "Found map: " << map_name << std::endl;
    }
}

`CommReply loadMap(const std::string &map_name, bool auto_reload = false)`

功能说明
加载指定地图。

参数说明

参数名	类型	必填/默认值	说明
`map_name`	`const std::string &`	必填	地图名称。
`auto_reload`	`bool`	默认: false	是否设为默认地图(true:重启机器人后自动加载，false:仅当前加载)

返回值

类型	说明
`CommReply`	包含 `success` 标志和 `message` 消息。

调用示例

cpp

Lenovo::Daystar::SDK sdk;
if (!sdk.isConnected()) {
    std::cerr << "Can not connect SDK server with default settings"
              << std::endl;
    return 1;
} else {
    std::cout << "Connected with default settings" << std::endl;
}
auto &sysb = sdk.getSYSB();
if (sysb.connect()) {
    sysb.loadMap("office_map");
}

`CommReply uploadMap(const std::string &map_name, const std::vector<uint8_t> &file_data)`

功能说明
上传地图文件。

参数说明

参数名	类型	必填/默认值	说明
`map_name`	`const std::string &`	必填	地图名称。
file_data	`const std::vector<uint_8> &`	必填	地图数据。

返回值

类型	说明
`CommReply`	包含 `success` 标志和 `message` 消息。

调用示例

cpp

// C++
Lenovo::Daystar::SDK sdk;

if (!sdk.isConnected()) {
    std::cerr << "Can not connect SDK server with default settings"
              << std::endl;
    return 1;
} else {
    std::cout << "Connected with default settings" << std::endl;
}
auto &sysb = sdk.getSYSB();
std::string name = getStringInput("输入上传地图文件的name: ");
std::string filepath = getStringInput("输入本地地图文件路径: ");
// 读取文件数据
std::ifstream file_stream(filepath, std::ios::binary);
if (!file_stream)
{
    std::cout << "✗ 无法打开文件: " << filepath << std::endl;
    break;
}
std::vector<uint8_t> file_data((std::istreambuf_iterator<char>(file_stream)), std::istreambuf_iterator<char>());
file_stream.close();

auto result = sysb.uploadMap(name, file_data);
if (result.success == true)
{
    std::cout << "✓ 地图文件上传成功: " << name << std::endl;
}
else
{
    std::cout << "✗ 地图文件上传失败: " << result.message << std::endl;
}

`CommReply downloadMap(const std::string &map_name, const std::vector<uint8_t> &file_data)`

功能说明
下载地图数据。

参数说明

参数名	类型	必填/默认值	说明
`map_name`	`const std::string &`	必填	地图名称。
`file_data`	`const std::vector<uint_8> &`	必填	地图数据。

返回值

类型	说明
`CommReply`	包含 `success` 标志和 `message` 消息。

调用示例

cpp

// C++
Lenovo::Daystar::SDK sdk;

if (!sdk.isConnected()) {
    std::cerr << "Can not connect SDK server with default settings"
              << std::endl;
    return 1;
} else {
    std::cout << "Connected with default settings" << std::endl;
}
auto &sysb = sdk.getSYSB();
std::string name = getStringInput("输入下载地图文件的name: ");
std::vector<uint8_t> file_data;

auto result = sysb.downloadMap(name, file_data);
if (result.success == true)
{
    // 地图文件保存为.pcd格式
    std::string filename = name;
    if (filename.find(".pcd") == std::string::npos) {
        filename += ".pcd";
    }
                    
    std::string download_dir = ensureDownloadDir();
    std::string save_path = download_dir + "/" + filename;
                    
    std::ofstream out_file(save_path, std::ios::binary);
    if (!out_file) {
        std::cout << "✗ 无法创建文件: " << save_path << std::endl;
        break;
    }
                    
    out_file.write(reinterpret_cast<const char *>(file_data.data()), file_data.size());
    out_file.close();
                    
    if (out_file.fail()) {
        std::cout << "✗ 文件写入失败: " << save_path << std::endl;
    } else {
        std::cout << "✓ 地图文件下载成功" << std::endl;
        std::cout << "  文件大小: " << (file_data.size() / 1024.0 / 1024.0) << " MB" << std::endl;
        std::cout << "  保存路径: " << save_path << std::endl;
    }
}
else
{
    std::cout << "✗ 地图文件下载失败: " << result.message << std::endl;
}

ROS2接口

加载地图

该接口用于加载指定地图。

服务名称	服务类型	角色
`/sdk/nav/load_map`	`api_msgs::srv::LoadMap`	服务端

请求结构（Request）

字段名称	类型	描述
`map_name`	`string`	地图名称。
`auto_reload`	`bool`	是否设为默认地图(true:重启机器人后自动加载，false:仅当前加载)

响应结构（Response）

字段名称	类型	描述
`success`	`bool`	是否成功加载。
`message`	`string`	操作结果信息。

调用示例

bash

ros2 service call /sdk/nav/load_map api_msgs/srv/LoadMap '{map_name: "office_map", auto_reload: true}'

获取地图列表

该接口用于获取机器人中所有可用地图的名称列表。

服务名称	服务类型	角色
`/sdk/nav/get_available_maps`	`api_msgs::srv::GetAvailableMaps`	服务端

请求结构（Request）

字段名称	类型	描述
（无字段）	-	无需传入参数。

响应结构（Response）

字段名称	类型	描述
`success`	`bool`	是否成功获取。
`map_names`	`string[]`	可用地图名称列表。
`message`	`string`	操作结果信息。

调用示例

bash

ros2 service call /sdk/nav/get_available_maps api_msgs/srv/GetAvailableMaps '{}'

定位接口

Python接口

`Optional[Dict] get_localization_state()`

功能说明
获取定位状态。

参数说明

参数名	类型	必填/默认值	说明
-	-	-	无参数。

返回值

类型	说明
`Optional[Dict]`	包含以下字段： - `success (bool)`: 是否获取成功 - `loc_state (int)`: 定位状态 - `0`: NORMAL (正常) - `1`: LACKDATA (数据不足) - `2`: LOST (定位丢失)

调用示例

python

from daystar_sdk.client import RobotClient
# 初始化客户端
with RobotClient(host='localhost', port=5252) as client:
    result = await client.get_localization_state()
    if result and result.get('success'):
        loc_state = result.get('loc_state')
        state_names = {0: "正常", 1: "数据不足", 2: "定位丢失"}
        print(f"定位状态: {state_names.get(loc_state, '未知')}")
    else:
        print(f"获取定位状态失败: {result.get('message') if result else 'Unknown error'}")

`Optional[Dict] get_current_pose()`

功能说明
获取当前位置。

参数说明

参数名	类型	必填/默认值	说明
-	-	-	无参数。

返回值

类型	说明
`Optional[Dict]`	包含以下字段： - `success (bool)`: 是否获取成功 - `message (str)`: 操作结果信息 - `location_pose (Dict)`: 位置姿态信息 - `position (Dict)`: 位置坐标 {x, y, z} - `orientation (Dict)`: 姿态四元数

调用示例

python

from daystar_sdk.client import RobotClient
# 初始化客户端
with RobotClient(host='localhost', port=5252) as client:
    # 位置获取
    result = await client.get_current_pose()
    if result and result.get('success'):
        pose = result.get('location_pose', {})
        position = pose.get('position', {})
        orientation = pose.get('orientation', {})
        print(f"当前位置: x={position.get('x')}, y={position.get('y')}, z={position.get('z')}")
        print(f"当前姿态: x={orientation.get('x')}, y={orientation.get('y')}, z={orientation.get('z')}, w={orientation.get('w')}")
    else:
        print(f"获取位置失败: {result.get('message') if result else 'Unknown error'}")

`Optional[Dict] relocalization(auto_relocalization, location_name="", location_pose=None, timeout=60.0)`

功能说明
重定位。

参数说明

参数名	类型	必填/默认值	说明
`auto_relocalization`	`bool`	必填	是否自动重定位。
`location_name`	`str`	默认: ""	位置点名称（可选）。
`location_pose`	`Dict`	默认: None	位置姿态（可选）。
`timeout`	`float`	默认: 60.0	超时时间（秒）。

返回值

类型	说明
`Optional[Dict]`	包含以下字段： - `success (bool)`: 是否重定位成功 - `message (str)`: 操作结果信息

调用示例

python

from daystar_sdk import WebSocketRobotClient
# 初始化客户端
with WebSocketRobotClient(host='localhost', port=5252) as client:
    # 自动重定位
    result = await client.relocalization(auto_relocalization=True)

C#接口

`(bool success, string message) Relocalization(bool autoRelocation, string locationName = null, PoseData locationPose = null, int id = 212, int timeoutMs = 10000)`

功能说明
重定位。

参数说明

参数名	类型	必填/默认值	说明
`autoRelocation`	`bool`	必填	是否自动重定位。
`locationName`	`string`	可选	位置点名称。
`locationPose`	`PoseData`	可选	位置姿态。
`id`	`int`	默认: 212	请求ID（可忽略）。
`timeoutMs`	`int`	默认: 10000	超时时间（毫秒）。

返回值

类型	说明
`(bool success, string message)`	操作结果元组。

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();

// 调用重定位
var (success, message) = _navigationClient.Relocalization(true);
if (success)
{
    Debug.Log($"✓ 重定位成功");
}

`PoseStamped? GetCurrentPose(int id = 207, int timeoutMs = 5000)`

功能说明
获取当前机器人位置（同步方法）。

参数说明

参数名	类型	必填/默认值	说明
`id`	`int`	默认: 207	请求ID（可忽略）。
`timeoutMs`	`int`	默认: 5000	超时时间（毫秒）。

返回值

类型	说明
`PoseStamped?`	机器人当前位置信息。失败返回 null。包含以下字段： - `header (Header)`: 消息头 - `stamp (string)`: 时间戳 - `frame_id (string)`: 坐标系ID - `pose (Pose3D)`: 姿态信息 - `position (Point3D)`: 位置 {x, y, z} - `orientation (Quaternion3D)`: 方向

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();

var pose = _navigationClient.GetCurrentPose();
if (pose.HasValue)
{
    var position = pose.Value.pose.position;
    Debug.Log($"位置: ({position.x}, {position.y}, {position.z})");
}

`(bool success, int loc_state)? GetLocalizationStateSync(int id = 208, int timeoutMs = 5000)`

功能说明
获取定位状态（同步方法）。

参数说明

参数名	类型	必填/默认值	说明
`id`	`int`	默认: 208	请求ID（可忽略）。
`timeoutMs`	`int`	默认: 5000	超时时间（毫秒）。

返回值

类型	说明
`(bool success, int loc_state)?`	定位状态元组，包含是否成功和状态值。失败返回 null。 `loc_state` 状态值说明： - `0`: NORMAL (正常) - `1`: LACKDATA (数据不足) - `2`: LOST (定位丢失)

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();

var result = _navigationClient.GetLocalizationStateSync(208, 5000);
if (result.HasValue)
{
    bool success = result.Value.success;
    int locState = result.Value.loc_state;
    Debug.Log($"Localization State: {locState}");
}

Java接口

`int GetLocalizationState()`

功能说明
获取当前定位状态。

参数说明

参数名	类型	必填/默认值	说明
-	-	-	无参数。

返回值

类型	说明
`int`	定位状态码。 - `0`: NORMAL (正常) - `1`: LACKDATA (数据不足) - `2`: LOST (定位丢失)

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;

// 获取定位状态
int state = slamNaviClient.GetLocalizationState();
String stateStr;
switch (state) {
    case 0: stateStr = "正常"; break;
    case 1: stateStr = "数据不足"; break;
    case 2: stateStr = "丢失"; break;
    default: stateStr = "未知(" + state + ")"; break;
}
System.out.println("定位状态: " + stateStr);

`LocationPose GetCurrentLocationPose()`

功能说明
获取机器人当前位置姿态（结构化对象形式）。

参数说明

参数名	类型	必填/默认值	说明
-	-	-	无参数。

返回值

类型	说明
`LocationPose`	当前位置姿态对象。包含以下字段： - `position (Point3D)`: 位置坐标 {x, y, z} - `orientation (Quaternion3D)`: 姿态四元数

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;
import com.lenovo.daystar_bot_sdk_client.DataEntities.LocationPose;

// 获取当前位姿
LocationPose pose = slamNaviClient.GetCurrentLocationPose();
String poseStr = String.format("位置: (%.3f, %.3f, %.3f)\n姿态: (%.3f, %.3f, %.3f, %.3f)",
    pose.position.x, pose.position.y, pose.position.z,
    pose.orientation.x, pose.orientation.y, pose.orientation.z, pose.orientation.w);
System.out.println(poseStr);

`void AutoRelocalization()`

功能说明
触发自动重定位。

参数说明

参数名	类型	必填/默认值	说明
-	-	-	无参数。

返回值

类型	说明
`void`	无返回值。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;

// 触发自动重定位
slamNaviClient.AutoRelocalization();
System.out.println("已触发自动重定位");

`void RelocateWithName(boolean autoRelocalize, String locationName)`

功能说明
使用命名位置点进行重定位。

参数说明

参数名	类型	必填/默认值	说明
`autoRelocalize`	`boolean`	必填	是否先尝试自动重定位。
`locationName`	`String`	必填	位置点名称。

返回值

类型	说明
`void`	无返回值。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;

// 使用已知点位重定位
slamNaviClient.RelocateWithName(true, "home_position");

`void RelocateWithPosition(boolean autoRelocalize, LocationPose poseData)`

功能说明
使用指定位姿进行重定位。

参数说明

参数名	类型	必填/默认值	说明
`autoRelocalize`	`boolean`	必填	是否先尝试自动重定位。
`poseData`	`LocationPose`	必填	目标位姿（包含位置和姿态）。

返回值

类型	说明
`void`	无返回值。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;
import com.lenovo.daystar_bot_sdk_client.DataEntities.LocationPose;

// 使用坐标位姿重定位
LocationPose pose = new LocationPose(/* args */);
slamNaviClient.RelocateWithPosition(true, pose);

C++接口

`bool getLocalizationState(int &loc_state)`

功能说明
获取定位系统状态。

参数说明

参数名	类型	必填/默认值	说明
`loc_state`	`int &`	必填	返回定位状态。

返回值

类型	说明
`bool`	`true` 成功，`false` 失败。

调用示例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();

if (sysb.connect()) {
    int loc_state;
    if (sysb.getLocalizationState(loc_state)) {
        std::cout << "定位状态: " << loc_state << std::endl;
    }
}

`bool getCurrentPose(Pose &current_pose)`

功能说明
获取机器人当前位置。

参数说明

参数名	类型	必填/默认值	说明
`current_pose`	`Pose &`	必填	返回当前位置信息。

返回值

类型	说明
`bool`	`true` 成功，`false` 失败。

调用示例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();

if (sysb.connect()) {
    Pose current_pose;
    if (sysb.getCurrentPose(current_pose)) {
        std::cout << "当前位置: ("
                  << current_pose.position.x << ", "
                  << current_pose.position.y << ", "
                  << current_pose.position.z << ")" << std::endl;
    }
}

`CommReply relocalization(bool auto_relocalization, const std::string &location_name, Pose location_pose, int timeout = 60)`

功能说明
重定位。

参数说明

参数名	类型	必填/默认值	说明
`auto_relocalization`	`bool`	必填	是否自动重定位，设为true时忽略后两个参数。
`location_name`	`const std::string &`	必填	位置点名称（可选，传空字符串）。
`location_pose`	`Pose`	必填	位置点坐标（可选，传默认`Pose()`）。
`timeout`	`int`	默认: 60	超时时间。

返回值

类型	说明
`CommReply`	包含 `success` 标志和 `message` 消息

调用示例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();

if (sysb.connect()) {
    // 自动重定位
    auto reply = sysb.relocalization(true, "", Pose());
    if (reply.success) {
        std::cout << "重定位指令已发送" << std::endl;
    }
}

ROS2接口

获取定位状态

该接口用于获取机器人当前的定位状态。

服务名称	服务类型	角色
`/sdk/nav/get_localization_state`	`api_msgs::srv::GetLocalizationState`	服务端

请求结构（Request）

字段名称	类型	描述
（无字段）	-	无需传入参数。

响应结构（Response）

字段名称	类型	描述
`success`	`bool`	是否成功获取。
`loc_state`	`uint8`	定位状态码。
`message`	`string`	操作结果信息。

定位状态码

值	描述
`0`	NORMAL（定位正常）
`1`	LACKDATA（数据不足）
`2`	LOST（定位丢失）

调用示例

bash

ros2 service call /sdk/nav/get_localization_state api_msgs/srv/GetLocalizationState '{}'

获取当前位置

该接口用于获取机器人当前在地图中的位置坐标（仅在定位状态正常时可用）。

服务名称	服务类型	角色
`/sdk/nav/get_current_pose`	`api_msgs::srv::GetCurrentPose`	服务端

请求结构（Request）

字段名称	类型	描述
（无字段）	-	无需传入参数。

响应结构（Response）

字段名称	类型	描述
`location_pose`	`geometry_msgs/Pose`	机器人当前位置和姿态。
`success`	`bool`	是否成功获取。
`message`	`string`	操作结果信息。

调用示例

bash

ros2 service call /sdk/nav/get_current_pose api_msgs/srv/GetCurrentPose '{}'

重定位

该接口用于触发机器人重定位，可指定自动重定位或手动指定位置。

服务名称	服务类型	角色
`/sdk/nav/set_localization`	`api_msgs::srv::SetLocalization`	服务端

请求结构（Request）

字段名称	类型	描述
`auto_relocation`	`bool`	是否自动重定位（true 时忽略后两个参数）。
`location_name`	`string`	指定重定位的点位名称（可选，传空字符串）。
`location_pose`	`geometry_msgs/Pose`	指定重定位的坐标（可选）。

响应结构（Response）

字段名称	类型	描述
`success`	`bool`	是否成功发送重定位指令。
`message`	`string`	操作结果信息。

调用示例

bash

# 自动重定位
ros2 service call /sdk/nav/set_localization api_msgs/srv/SetLocalization '{auto_relocation: true, location_name: ""}'

添加导航点位

Python接口

`Optional[Dict] add_location(location_name, timeout=30, use_virtual_pose=False, virtual_pose=None)`

功能说明
添加导航点位。

参数说明

参数名	类型	必填/默认值	说明
`location_name`	`str`	必填	位置点名称。
`timeout`	`int`	默认: 30	超时时间，单位秒。
`use_virtual_pose`	`bool`	默认: False (可选)	是否使用虚拟位姿（指定坐标添加点位）
`virtual_pose`	`Pose对象`	默认: None (可选)	虚拟位姿数据（当use_virtual_pose为True时必填）

返回值

类型	说明
`Optional[Dict]`	包含以下字段： - `success (bool)`: 是否添加成功 - `message (str)`: 操作结果信息 - `location_pose (Dict)`: 位置坐标信息 - `map_name (str)`: 地图名称

调用示例

python

from daystar_sdk import WebSocketRobotClient
# 初始化客户端
with WebSocketRobotClient(host='192.168.144.105', port=5252) as client:
    
    # 添加当前位置为导航点
    add_result = await client.add_location("home_position", timeout=30)
    if add_result and add_result.get('success'):
        print(f"成功添加导航点位: {location_name}")
        print(f"位置信息: {add_result}")
    else:
        print(f"添加导航点位失败: {add_result}")

    
    # 添加虚拟点位（使用指定坐标，无需机器人到达该位置）
    virtual_pose = Pose(
        position=Point(x=vx, y=vy, z=vz),
        orientation=Quaternion(x=qx, y=qy, z=qz, w=qw)
    )
    
    # 调用add_location方法，设置use_virtual_pose=True
    virtual_result = await client.add_location(
        "home_position",
        timeout=30,
        use_virtual_pose=True,
        virtual_pose=virtual_pose
    )

    if virtual_result and virtual_result.get('success'):
        print(f"成功添加虚拟点位: {virtual_location_name}")
        print(f"返回位置信息: {virtual_result.get('location_pose', {})}")
        print(f"所属地图: {virtual_result.get('map_name', 'unknown')}")
    else:
        print(f"添加虚拟点位失败: {virtual_result}")

C#接口

`(bool success, string message) AddLocation(string locationName, int timeout = 30, int id = 200)`

功能说明
添加当前位置为导航点位。

参数说明

参数名	类型	必填/默认值	说明
`locationName`	`string`	必填	位置点名称。
`timeout`	`int`	默认: 30	超时时间(秒)。
`id`	`int`	默认: 200	请求ID（可忽略）。

返回值

类型	说明
`(bool success, string message)`	操作结果元组。

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();

string locationName = $"Location_{System.DateTime.Now:yyyyMMdd_HHmmss}";
var result = _navigationClient.AddLocation(locationName);
if (result.success)
{
    Debug.Log($"Successfully added location '{locationName}'");
}

`(bool success, string message) AddLocation(string locationName, float x, float y, float z, float orientationX, float orientationY, float orientationZ, float orientationW, int timeout = 30, int id = 200, int timeoutMs = 5000)`

功能说明
使用指定坐标（虚拟点位）添加导航点位。

参数说明

参数名	类型	必填/默认值	说明
`locationName`	`string`	必填	位置点名称。
`x, y, z`	`float`	必填	位置坐标。
`orientationX-W`	`float`	必填	方向四元数。
`timeout`	`int`	默认: 30	超时时间。
`id`	`int`	默认: 200	请求ID（可忽略）。
`timeoutMs`	`int`	默认: 5000	响应超时时间。

返回值

类型	说明
`(bool success, string message)`	操作结果元组。

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();

// 添加虚拟点位
var result = _navigationClient.AddLocation("virtual_point", 1.0f, 0, 0, 0, 0, 0, 1.0f);
if (result.success)
{
    Debug.Log("Successfully added virtual location");
}

Java接口

`void AddLocation(String locationName, boolean use_virtual_pose, LocationPose virtual_pose)`

功能说明
添加一个命名位置点(站点/标记点)。

参数说明

参数名	类型	必填/默认值	说明
`locationName`	`String`	必填	位置点名称。
`use_virtual_pose`	`boolean`	必填	是否使用虚拟位姿，传false表示使用当前机器人位姿。
`virtual_pose`	`LocationPose`	可选	虚拟位姿，当use_virtual_pose为true时必须提供，否则传null。

返回值

类型	说明
`void`	无返回值。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;

// 添加当前位置为导航点位
String locationName = "home_position";
slamNaviClient.AddLocation(locationName, false, null);
System.out.println("✓ 添加位置成功: " + locationName);

C++接口

`AddLocationReply addLocation(const std::string &location_name, int timeout = 30, bool use_virtual_pose = false, Pose virtual_pose = Pose())`

功能说明
添加位置点。

参数说明

参数名	类型	必填/默认值	说明
`location_name`	`const std::string &`	必填	位置点名称。
`timeout`	`int`	默认: 30	超时时间(秒)。
`use_virtual_pose`	`bool`	默认: false	是否使用虚拟位姿。
`virtual_pose`	`Pose`	可选	虚拟位姿数据。

返回值

类型	说明
`AddLocationReply`	包含 `success` 标志、`message` 消息、`location_pose` 和 `map_name`。

调用示例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();

if (sysb.connect()) {
    if (sysb.addLocation("办公室入口", 30)) {
        std::cout << "位置点'办公室入口'添加成功" << std::endl;
    } else {
        std::cerr << "位置点添加失败" << std::endl;
    }
}

ROS2接口

添加导航点位

该接口用于在当前机器人位置或指定虚拟坐标处添加导航点位。

服务名称	服务类型	角色
`/sdk/nav/add_location`	`api_msgs::srv::AddLocation`	服务端

请求结构（Request）

字段名称	类型	描述
`location_name`	`string`	点位名称。
`timeout`	`int32`	超时时间（秒）。
`use_virtual_pose`	`bool`	是否使用虚拟坐标添加点位（true 时使用 `virtual_pose`）。
`virtual_pose`	`geometry_msgs/Pose`	虚拟点位坐标（`use_virtual_pose` 为 true 时有效）。

响应结构（Response）

字段名称	类型	描述
`location_pose`	`geometry_msgs/Pose`	实际保存的点位坐标。
`map_name`	`string`	所属地图名称。
`success`	`bool`	是否成功添加。
`message`	`string`	操作结果信息。

调用示例

bash

# 在当前位置添加点位
ros2 service call /sdk/nav/add_location api_msgs/srv/AddLocation '{location_name: "办公室入口", timeout: 30, use_virtual_pose: false}'

# 添加虚拟点位
ros2 service call /sdk/nav/add_location api_msgs/srv/AddLocation '{location_name: "虚拟点位A", timeout: 30, use_virtual_pose: true, virtual_pose: {position: {x: 1.0, y: 2.0, z: 0.0}, orientation: {x: 0.0, y: 0.0, z: 0.0, w: 1.0}}}'

删除点位接口

Python接口

`Optional[Dict] delete_location(location_name)`

功能说明
删除导航点位。

参数说明

参数名	类型	必填/默认值	说明
`location_name`	`str`	必填	要删除的位置点名称。

返回值

类型	说明
`Optional[Dict]`	包含以下字段： - `success (bool)`: 是否删除成功 - `message (str)`: 操作结果信息

调用示例

python

from daystar_sdk import WebSocketRobotClient
# 初始化客户端
with WebSocketRobotClient(host='localhost', port=5252) as client:
    result = client.delete_location("position")

C#接口

`(bool success, string message) DeleteLocation(string locationName, int id = 201, int timeoutMs = 5000)`

功能说明
删除指定的导航点位。

参数说明

参数名	类型	必填/默认值	说明
`locationName`	`string`	必填	要删除的位置点名称。
`id`	`int`	默认: 201	请求ID（可忽略）。
`timeoutMs`	`int`	默认: 5000	超时时间（毫秒）。

返回值

类型	说明
`(bool success, string message)`	操作结果元组。

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();

var result = _navigationClient.DeleteLocation("location_name");
if (result.success)
{
    Debug.Log("删除成功"); 
}

Java接口

`void DeleteLocation(String locationName)`

功能说明
删除一个命名位置点。

参数说明

参数名	类型	必填/默认值	说明
`locationName`	`String`	必填	要删除的位置点名称。

返回值

类型	说明
`void`	无返回值。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;

// 删除位置点
String locationName = "home_position";
slamNaviClient.DeleteLocation(locationName);
System.out.println("✓ 删除位置成功: " + locationName);

C++接口

`bool deleteLocation(const std::string &location_name)`

功能说明
删除位置点。

参数说明

参数名	类型	必填/默认值	说明
`location_name`	`const std::string &`	必填	位置点名称。

返回值

类型	说明
`bool`	`true` 成功，`false` 失败。

调用示例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();

if (sysb.connect()) {
    if (sysb.deleteLocation("办公室入口")) {
        std::cout << "位置点'办公室入口'删除成功" << std::endl;
    } else {
        std::cerr << "位置点删除失败" << std::endl;
    }
}

ROS2接口

删除点位

该接口用于删除指定名称的导航点位。

服务名称	服务类型	角色
`/sdk/nav/delete_location`	`api_msgs::srv::DeleteLocation`	服务端

请求结构（Request）

字段名称	类型	描述
`location_name`	`string`	要删除的点位名称。

响应结构（Response）

字段名称	类型	描述
`success`	`bool`	是否成功删除。
`message`	`string`	操作结果信息。

调用示例

bash

ros2 service call /sdk/nav/delete_location api_msgs/srv/DeleteLocation '{location_name: "办公室入口"}'

获取可用点位接口

Python接口

`Optional[Dict] get_available_locations()`

功能说明
获取现有点位。

参数说明

参数名	类型	必填/默认值	说明
-	-	-	无参数。

返回值

类型	说明
`Optional[Dict]`	包含以下字段： - `location_names (List[str])`: 位置点名称列表

调用示例

python

from daystar_sdk import WebSocketRobotClient
# 初始化客户端
with WebSocketRobotClient(host='localhost', port=5252) as client:
    result = client.get_available_locations()
    location_names = result.get('location_names', [])

C#接口

`List<string> GetAvailableLocations(int id = 202, int timeoutMs = 5000)`

功能说明
获取所有可用的导航点位（同步方法，直接返回位置列表）。

参数说明

参数名	类型	必填/默认值	说明
`id`	`int`	默认: 202	请求ID（可忽略）。
`timeoutMs`	`int`	默认: 5000	超时时间（毫秒）。

返回值

类型	说明
`List<string>`	位置名称列表，失败时返回空列表。

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();

var locations = _navigationClient.GetAvailableLocations();
if (locations.Count > 0)
{
    foreach (var loc in locations)
    {
        Debug.Log($"Location: {loc}");
    }
}

Java接口

`List<String> GetLocationList()`

功能说明
获取已保存的位置点名称列表。

参数说明

参数名	类型	必填/默认值	说明
-	-	-	无参数。

返回值

类型	说明
`List<String>`	位置点名称列表。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;
import java.util.List;

// 获取点位列表
List<String> locations = slamNaviClient.GetLocationList();
System.out.println("✓ 获取到 " + locations.size() + " 个点位:");
for (String loc : locations) {
    System.out.println("  - " + loc);
}

`LocationListDetails GetLocationListDetails()`

功能说明
获取已保存的位置点详细信息列表。

参数说明

参数名	类型	必填/默认值	说明
-	-	-	无参数。

返回值

类型	说明
`LocationListDetails`	包含详细位置点信息的对象。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;
import com.lenovo.daystar_bot_sdk_client.DataEntities.LocationListDetails;

LocationListDetails details = slamNaviClient.GetLocationListDetails();
// 处理 details 数据

C++接口

`bool getAvailableLocations(std::vector<std::string> &location_names, std::vector<Pose> &location_poses)`

功能说明
获取所有可用的位置点。

参数说明

参数名	类型	必填/默认值	说明
`location_names`	`std::vector<std::string> &`	必填	返回位置点名称列表。
`location_poses`	`std::vector<Pose> &`	必填	返回位置点坐标列表。

返回值

类型	说明
`bool`	`true` 成功，`false` 失败。

调用示例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();

if (sysb.connect()) {
    std::vector<std::string> names;
    std::vector<Pose> poses;
    
    if (sysb.getAvailableLocations(names, poses)) {
        std::cout << "可用位置点:" << std::endl;
        for (size_t i = 0; i < names.size(); ++i) {
            std::cout << "  " << names[i] << " - ("
                      << poses[i].position.x << ", "
                      << poses[i].position.y << ", "
                      << poses[i].position.z << ")" << std::endl;
        }
    }
}

ROS2接口

获取可用点位

该接口用于获取当前地图中所有已保存的导航点位列表。

服务名称	服务类型	角色
`/sdk/nav/get_available_locations`	`api_msgs::srv::GetAvailableLocations`	服务端

请求结构（Request）

字段名称	类型	描述
（无字段）	-	无需传入参数。

响应结构（Response）

字段名称	类型	描述
`success`	`bool`	是否成功获取。
`location_names`	`string[]`	点位名称列表。
`location_poses`	`geometry_msgs/Pose[]`	对应点位坐标列表。
`message`	`string`	操作结果信息。

调用示例

bash

ros2 service call /sdk/nav/get_available_locations api_msgs/srv/GetAvailableLocations '{}'

导航控制接口

在导航控制接口中，可通过 TravelParams 配置详细的导航行为。如果不需要自定义配置，可以忽略，系统会使用默认的导航参数。

导航详细参数说明

参数名	类型	说明	值域/备注
`speed_mode`	`int`	速度模式	0=低速, 1=中速, 2=高速。默认中速
`distance_tolerance`	`float`	到达精确度（位置容差）	目标点判定范围，单位：米默认0.3m
`gait`	`int`	步态模式	1=GAIT_AUTO(IS/GS默认MPC, MC/MX默认RL), 2=GAIT_TROT(对角小跑), 3=GAIT_CRAWL(爬行), 4=GAIT_AMBLE(缓行), 5=GAIT_SLOPE(斜坡), 6=GAIT_SENSE_STAIR(感知楼梯), 7=GAIT_NORMAL_STAIR(普通楼梯), 8=GAIT_STEEP_STAIR(陡峭楼梯), 9=GAIT_GRADUAL_STAIR(平缓楼梯), 10=GAIT_RL(强化学习步态)
`obstacle_params.disable_body_obstacle_avoidance`	`bool`	是否禁用停障	true=禁用, false=启用默认false
`obstacle_params.obstacle_avoidance_padding`	`float[]`	停障参数	默认[0.1, 0.1, 0.1, 0.1]
`ignore_final_yaw`	`bool`	是否忽略最终偏航角	true=忽略, false=不忽略默认false
`path_following_mode`	`int`	路径跟随模式	1=默认巡线模式(推荐), 2=关闭循线(自由导航模式), 3=自动选择(智能导航时用) 默认巡线模式
`direction_constraint`	`int`	方向约束	1=无限制, 2=禁止掉头, 3=正走, 4=倒走默认正走

Python接口

`Optional[Dict] navigate_to_location(location_name, timeout=60, travel_params=None)`

功能说明
导航到预设位置。可以通过 travel_params 指定详细导航参数。

参数说明

参数名	类型	必填/默认值	说明
`location_name`	`str`	必填	目标位置点名称。
`timeout`	`int`	默认: 60	导航超时时间，单位秒。
`travel_params`	`TravelParams`	默认: None（可选）	自定义导航参数对象。

返回值

类型	说明
`Optional[Dict]`	包含以下字段： - `success (bool)`: 是否启动成功 - `message (str)`: 操作结果信息

调用示例

python

from daystar_sdk import (WebSocketRobotClient, TravelParams)

# 初始化客户端
with WebSocketRobotClient(host='192.168.144.105', port=5252) as client:
    # 默认导航
    client.navigate_to_location("home_position")

    # === 速度模式 ===
    print("\n【速度模式】")
    print("  0=低速, 1=中速, 2=高速")
    speed_input = input("速度模式 (默认1中速): ").strip()
    speed_mode_val = int(speed_input) if speed_input else SpeedMode.MEDIUM_SPEED_MODE
    
    # === 路径跟踪模式 ===
    print("\n【路径跟踪模式】")
    print(" 1=默认巡线(推荐), 2=关闭循线, 3=自动选择")
    path_mode_input = input("路径跟踪模式 (默认1): ").strip()
    path_following_mode = int(path_mode_input) if path_mode_input else TravelParams.PATH_MODE_DEFAULT
    
    # === 方向约束 ===
    print("\n【方向约束】")
    print(" 1=无限制, 2=禁止掉头, 3=正走, 4=倒走")
    dir_input = input("方向约束 (默认3正走): ").strip()
    direction_constraint = int(dir_input) if dir_input else TravelParams.DIRECTION_CONSTRAINT_FORWARD
    
    # === 高度模式 ===
    print("\n【高度模式】")
    print(" 1=正常, 2=降低, 3=升高")
    height_input = input("高度模式 (默认1): ").strip()
    height = int(height_input) if height_input else TravelParams.HEIGHT_NORMAL
    
    # === 容差参数 ===
    print("\n【容差参数】")
    dist_input = input("距离容差 (m, 默认0.3): ").strip()
    distance_tolerance = float(dist_input) if dist_input else 0.3
    
    yaw_input = input("偏航角容差 (rad, 默认0.1): ").strip()
    yaw_angle_tolerance = float(yaw_input) if yaw_input else 0.1
    
    # === 航向控制 ===
    print("\n【航向控制】")
    ignore_yaw_input = input("忽略最终偏航角? (y/N, 默认不忽略): ").strip().lower()
    ignore_final_yaw = ignore_yaw_input in ['y', 'yes', '是']
    
    # === 障碍物避障 ===
    print("\n【障碍物避障】")
    disable_obs_input = input("禁用停障? (y/N, 默认不禁用): ").strip().lower()
    disable_body_obstacle_avoidance = disable_obs_input in ['y', 'yes', '是']
    
    # === 步态模式 ===
    print("\n【步态模式】")
    print(" 1=GAIT_AUTO(推荐), 2=GAIT_TROT, 3=GAIT_CRAWL, 等...")
    gait_input = input("步态模式 (默认1自动): ").strip()
    gait_mode = int(gait_input) if gait_input else Gait.GAIT_AUTO

    # 带参数导航
    travel_params = TravelParams(
        speed_mode=SpeedMode(value=speed_mode_val),
        distance_tolerance=distance_tolerance,
        yaw_angle_tolerance=yaw_angle_tolerance,
        gait=Gait(gait=gait_mode, gait_name="OrdinaryGait"),
        obstacle_params=ObstacleParams(
            disable_body_obstacle_avoidance=disable_body_obstacle_avoidance,
            obstacle_avoidance_padding=[0.1, 0.1, 0.1, 0.1]
        ),
        ignore_final_yaw=ignore_final_yaw,
        path_following_mode=path_following_mode,
        direction_constraint=direction_constraint,
        height=height,
        extra_info_fmt=extra_info_fmt,
        extra_info=extra_info
    )
    client.navigate_to_location("office", timeout=30, travel_params=travel_params)

`Optional[Dict] navigate_to_xyz(x, y, z, timeout=60, frame_id="map", travel_params=None)`

功能说明
导航到指定坐标。

参数说明

参数名	类型	必填/默认值	说明
`x`	`float`	必填	x坐标。
`y`	`float`	必填	y坐标。
`z`	`float`	必填	z坐标。
`timeout`	`int`	默认: 60	导航超时时间，单位秒。
`frame_id`	`str`	默认: "map"	坐标系名称。
`travel_params`	`TravelParams`	默认: None（可选）	自定义导航参数对象。

返回值

类型	说明
`Optional[Dict]`	包含以下字段： - `success (bool)`: 是否启动成功 - `message (str)`: 操作结果信息

调用示例

python

from daystar_sdk import (WebSocketRobotClient, TravelParams)

# 初始化客户端
with WebSocketRobotClient(host='192.168.144.105', port=5252) as client:
    client.navigate_to_xyz(x=5.0, y=3.0, z=0.0, timeout=30, travel_params=None)

C#接口

`void NavigateToLocation(string locationName, TravelParams travelParams, int timeout = 60, int id = 203)`

功能说明
导航到预设位置点（带详细导航参数）。

参数说明

参数名	类型	必填/默认值	说明
`locationName`	`string`	必填	目标位置点名称。
`travelParams`	`TravelParams`	必填	导航参数对象。
`timeout`	`int`	默认: 60	导航超时时间(秒)。
`id`	`int`	默认: 203	请求ID（可忽略）。

返回值

类型	说明
`void`	无返回值。

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();

var params = new TravelParams();
params.speed_mode = 2; // Low speed
_navigationClient.NavigateToLocation("location_name", params);

`void NavigateToPosition(float x, float y, float z, TravelParams travelParams, int timeout = 60, string frameId = "map", int id = 205)`

功能说明
导航到指定坐标位置（带详细导航参数）。

参数说明

参数名	类型	必填/默认值	说明
`x, y, z`	`float`	必填	目标坐标。
`travelParams`	`TravelParams`	必填	导航参数对象。
`timeout`	`int`	默认: 60	导航超时时间。
`frameId`	`string`	默认: "map"	坐标系。
`id`	`int`	默认: 205	请求ID（可忽略）。

返回值

类型	说明
`void`	无返回值。

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();

var params = new TravelParams();
params.path_following_mode = 1; // Default
_navigationClient.NavigateToPosition(1.0f, 0.0f, 0.0f, params);

`void NavigateToLocation(string locationName, int timeout = 60, int id = 203)`

功能说明
导航到预设位置点。

参数说明

参数名	类型	必填/默认值	说明
`locationName`	`string`	必填	目标位置点名称。
`timeout`	`int`	默认: 60	导航超时时间(秒)。
`id`	`int`	默认: 203	请求ID（可忽略）。

返回值

类型	说明
`void`	无返回值。

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();
_navigationClient.NavigateToLocation("location_name");

`void NavigateToPosition(float x, float y, float z, int timeout = 60, string frameId = "map", int id = 205)`

功能说明
导航到指定坐标位置（XYZ坐标）。

参数说明

参数名	类型	必填/默认值	说明
`x`	`float`	必填	x坐标。
`y`	`float`	必填	y坐标。
`z`	`float`	必填	z坐标。
`timeout`	`int`	默认: 60	导航超时时间(秒)。
`frameId`	`string`	默认: "map"	坐标系名称。
`id`	`int`	默认: 205	请求ID（可忽略）。

返回值

类型	说明
`void`	无返回值。

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();
_navigationClient.NavigateToPosition(1.0f, 0.0f, 0.0f);

Java接口

`void NavigateToLocation(String locationName, Optional<MsgTravelParams> params, int timeout)`

功能说明
导航到指定命名位置点。

参数说明

参数名	类型	必填/默认值	说明
`locationName`	`String`	必填	目标位置点名称。
`params`	`Optional<MsgTravelParams>`	必填	导航参数配置，传Optional.empty()使用默认参数。
`timeout`	`int`	必填	导航超时时间（单位：秒）。

返回值

类型	说明
`void`	无返回值。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;
import java.util.Optional;

// 导航到位置点
String locationName = "home_position";
int timeout = 60;
slamNaviClient.NavigateToLocation(locationName, Optional.empty(), timeout);
System.out.println("✓ 开始导航到位置: " + locationName);

`void NavigateToPosition(LocationPose pose, Optional<MsgTravelParams> params, int timeout, String frameId)`

功能说明
导航到指定坐标位姿。

参数说明

参数名	类型	必填/默认值	说明
`pose`	`LocationPose`	必填	目标位姿。
`params`	`Optional<MsgTravelParams>`	必填	导航参数配置，传Optional.empty()使用默认参数。
`timeout`	`int`	必填	导航超时时间（单位：秒）。
`frameId`	`String`	必填	坐标系标识（例如 "map"）。

返回值

类型	说明
`void`	无返回值。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;
import com.lenovo.daystar_bot_sdk_client.DataEntities.*;
import java.util.Optional;

// 导航到坐标位置
LocationPose pose = new LocationPose(
    new Point3D(1.0f, 0.0f, 0.0f),
    new Quaternion3D(0.0f, 0.0f, 0.0f, 1.0f)
);
slamNaviClient.NavigateToPosition(pose, Optional.empty(), 60, "map");
System.out.println("✓ 开始导航到坐标: (1.0, 0.0, 0.0)");

`void NavigateViaPoses(List<PoseStamped> exec_waypoints, Optional<MsgTravelParams> params, int execType)`

功能说明
通过一系列位姿点进行导航（路径导航）。

参数说明

参数名	类型	必填/默认值	说明
`exec_waypoints`	`List<PoseStamped>`	必填	途经点列表。
`params`	`Optional<MsgTravelParams>`	必填	导航参数。
`execType`	`int`	必填	执行类型。

返回值

类型	说明
`void`	无返回值。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;
import java.util.Collections;
import java.util.Optional;

// 路径导航示例
slamNaviClient.NavigateViaPoses(Collections.emptyList(), Optional.empty(), 0);

C++接口

`bool navigateToLocation(const std::string &location_name, int timeout = 60, const MsgTravelParams& travel_params = MsgTravelParams())`

功能说明
导航到指定位置点。

参数说明

参数名	类型	必填/默认值	说明
`location_name`	`const std::string &`	必填	目标位置点名称。
`timeout`	`int`	默认: 60	超时时间(秒)。
`travel_params`	`const MsgTravelParams &`	默认: 默认构造	导航参数对象。

返回值

类型	说明
`bool`	`true` 成功，`false` 失败。

调用示例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();

// 默认参数导航
if (sysb.connect()) {
    if (sysb.navigateToLocation("办公室入口", 60)) {
        std::cout << "开始导航到'办公室入口'" << std::endl;
    }
}

// 带参数导航
if (sysb.connect()) {
    MsgTravelParams params;
    params.speed_mode.value = 2; // LOW
    sysb.navigateToLocation("会议室", 60, params);
}

`bool navigateToPosition(const PoseStamped &target_pose, int timeout = 60, const MsgTravelParams& travel_params = MsgTravelParams())`

功能说明
导航到指定姿态。

参数说明

参数名	类型	必填/默认值	说明
`target_pose`	`const PoseStamped &`	必填	目标姿态。
`timeout`	`int`	默认: 60	超时时间(秒)。
`travel_params`	`const MsgTravelParams &`	默认: 默认构造	导航参数对象。

返回值

类型	说明
`bool`	`true` 成功，`false` 失败。

调用示例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();

if (sysb.connect()) {
    // 创建目标姿态
    auto target_pose = sysb.createPose(5.0f, 3.0f, 0.0f, 0.0f, 0.0f, 0.0f, 1.0f, "map");

    if (sysb.navigateToPosition(target_pose, 60)) {
        std::cout << "开始导航到指定姿态" << std::endl;
    } else {
        std::cerr << "导航启动失败" << std::endl;
    }
}

ROS2接口

导航到指定点位

该接口用于控制机器人导航到已保存的命名点位。

服务名称	服务类型	角色
`/sdk/nav/navigate_to_location`	`api_msgs::srv::NavigateToLocation`	服务端

请求结构（Request）

字段名称	类型	描述
`location_name`	`string`	目标点位名称。
`travel_params`	`api_msgs/TravelParams`	导航参数（可选，不填使用默认值）。
`timeout`	`int32`	超时时间（秒）。

响应结构（Response）

字段名称	类型	描述
`success`	`bool`	导航是否成功完成。
`message`	`string`	操作结果信息。

调用示例

bash

ros2 service call /sdk/nav/navigate_to_location api_msgs/srv/NavigateToLocation '{location_name: "办公室入口", timeout: 60}'

导航到指定坐标

该接口用于控制机器人导航到地图中的指定坐标位置。

服务名称	服务类型	角色
`/sdk/nav/navigate_to_position`	`api_msgs::srv::NavigateToPosition`	服务端

请求结构（Request）

字段名称	类型	描述
`target_pose`	`geometry_msgs/PoseStamped`	目标位置和姿态（包含 frame_id）。
`travel_params`	`api_msgs/TravelParams`	导航参数（可选，不填使用默认值）。
`timeout`	`int32`	超时时间（秒）。

响应结构（Response）

字段名称	类型	描述
`success`	`bool`	导航是否成功完成。
`message`	`string`	操作结果信息。

调用示例

bash

ros2 service call /sdk/nav/navigate_to_position api_msgs/srv/NavigateToPosition '{target_pose: {header: {frame_id: "map"}, pose: {position: {x: 5.0, y: 3.0, z: 0.0}, orientation: {x: 0.0, y: 0.0, z: 0.0, w: 1.0}}}, timeout: 60}'

多航点导航

该接口用于控制机器人按顺序经过多个航点完成导航。

服务名称	服务类型	角色
`/sdk/nav/navigation_via_poses`	`api_msgs::srv::NavigationViaPoses`	服务端

请求结构（Request）

字段名称	类型	描述
`exec_waypoints`	`geometry_msgs/PoseStamped[]`	航点列表（按顺序执行）。
`exec_type`	`uint8`	执行模式。
`travel_params`	`api_msgs/TravelParams`	导航参数（可选，不填使用默认值）。

exec_type 取值

值	描述
`1`	AUTONOMOUS（自主规划）
`2`	STRICTTRACK（严格跟踪）
`3`	FITTING_STRAIGHT（直线拟合）
`4`	FITTING_CIRCULAR（圆弧拟合）
`5`	FITTING_SINE（正弦曲线拟合）

响应结构（Response）

字段名称	类型	描述
`success`	`bool`	导航是否成功完成。
`message`	`string`	操作结果信息。

调用示例

bash

ros2 service call /sdk/nav/navigation_via_poses api_msgs/srv/NavigationViaPoses '{exec_type: 1, exec_waypoints: [{header: {frame_id: "map"}, pose: {position: {x: 1.0, y: 0.0, z: 0.0}, orientation: {w: 1.0}}}]}'

取消导航控制

Python接口

`Optional[Dict] cancel_navigation(task_id="")`

功能说明
取消导航控制。

参数说明

参数名	类型	必填/默认值	说明
`task_id`	`str`	默认: ""	任务 ID，空字符串表示取消当前任务。

返回值

类型	说明
`Optional[Dict]`	包含以下字段： - `success (bool)`: 是否取消成功 - `message (str)`: 操作结果信息

调用示例

python

from daystar_sdk import WebSocketRobotClient
# 初始化客户端
with WebSocketRobotClient(host='localhost', port=5252) as client:
    result = await client.cancel_navigation()
    if result and result.get('success'):
        print(f"取消导航成功: {result.get('message')}")
    else:
        print(f"取消导航失败: {result.get('message') if result else 'Unknown error'}")

C#接口

`void CancelNavigation(string taskId = "", int id = 206)`

功能说明
取消当前导航任务。

参数说明

参数名	类型	必填/默认值	说明
`taskId`	`string`	默认: ""	任务ID，空字符串表示取消当前任务。
`id`	`int`	默认: 206	请求ID（可忽略）。

返回值

类型	说明
`void`	无返回值。

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();

_navigationClient.CancelNavigation();

Java接口

`void CancelNavigation(String taskId)`

功能说明
取消导航任务。

参数说明

参数名	类型	必填/默认值	说明
`taskId`	`String`	必填	任务 ID，传空字符串 "" 表示取消当前任务。

返回值

类型	说明
`void`	无返回值。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;

// 取消当前导航任务
slamNaviClient.CancelNavigation("");
System.out.println("✓ 取消导航命令已发送");

C++接口

`bool cancelNavigation(const std::string &task_id = "")`

功能说明
取消当前导航任务。

参数说明

参数名	类型	必填/默认值	说明
`task_id`	`const std::string &`	默认: ""	任务ID (空字符串表示取消当前任务)。

返回值

类型	说明
`bool`	`true` 成功，`false` 失败。

调用示例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();

if (sysb.connect()) {
    // 开始导航
    sysb.navigateToLocation("办公室入口");
    
    // 等待5秒后取消导航
    std::this_thread::sleep_for(std::chrono::seconds(5));

    if (sysb.cancelNavigation()) {
        std::cout << "导航已取消" << std::endl;
    }
}

ROS2接口

取消导航

该接口用于取消当前正在执行的导航任务。

服务名称	服务类型	角色
`/sdk/nav/cancel_navigation`	`api_msgs::srv::CancelNavigation`	服务端

请求结构（Request）

字段名称	类型	描述
`task_id`	`string`	任务 ID（空字符串表示取消当前任务）。

响应结构（Response）

字段名称	类型	描述
`success`	`bool`	是否成功取消。
`message`	`string`	操作结果信息。

调用示例

bash

ros2 service call /sdk/nav/cancel_navigation api_msgs/srv/CancelNavigation '{task_id: ""}'

获取导航事件接口

Python接口

`bool register_navigation_result(callback)`

功能说明
注册导航结果事件回调。

参数说明

参数名	类型	必填/默认值	说明
`callback`	`function`	必填	回调函数，必须接收2个参数： - `result_type (str)`: 结果类型(complete/failed) - `data (Dict)`:事件数据

返回值

类型	说明
`bool`	注册成功返回 `True`，失败返回 `False`。

事件数据示例

json

{
    "location_name": "目标点A",
    "success": true,
    "message": "导航完成",
    "timestamp": 1693632000.123,
    "task_id": "nav_task_001"
}

调用示例

python

from daystar_sdk import WebSocketRobotClient

# 初始化客户端  
with WebSocketRobotClient(host='localhost', port=5252) as client:
    # 定义导航结果回调函数
    def on_navigation_result(result_type, data):
        if result_type == "complete":
            print(f"导航完成: {data}")
        elif result_type == "failed": 
            print(f"导航失败: {data}")
    
    # 注册导航结果回调
    success = await client.register_navigation_result(on_navigation_result)

`bool unregister_navigation_result()`

功能说明
取消注册导航结果回调。

参数说明

参数名	类型	必填/默认值	说明
-	-	-	无参数。

返回值

类型	说明
`bool`	取消成功返回 `True`，失败返回 `False`。

`bool register_navigation_feedback(callback)`

功能说明
注册导航反馈状态回调。

参数说明

参数名	类型	必填/默认值	说明
`callback`	`function`	必填	回调函数，接收1个参数： - `data (Dict)`: 导航反馈数据

返回值

类型	说明
`bool`	注册成功返回 `True`，失败返回 `False`。

反馈数据示例

json

{
    "status": "navigating",
    "current_pose": {
        "position": {"x": 1.23, "y": 4.56, "z": 0.0},
        "orientation": {"x": 0, "y": 0, "z": 0, "w": 1}
    },
    "target_pose": {
        "position": {"x": 5.0, "y": 8.0, "z": 0.0},
        "orientation": {"x": 0, "y": 0, "z": 0, "w": 1}
    },
    "progress": 0.75,
    "distance_to_goal": 1.2,
    "message": "正在前往目标点A",
    "timestamp": 1693632001.456
}

状态类型说明

navigating: 正在导航
paused: 导航暂停
idle: 空闲状态
planning: 路径规划中
recovering: 恢复中

调用示例

python

from daystar_sdk import WebSocketRobotClient

# 初始化客户端
with WebSocketRobotClient(host='localhost', port=5252) as client:
    # 定义导航反馈回调函数
    def on_navigation_feedback(data):
        print(f"导航状态: {data.get('status')}")
        print(f"当前位置: {data.get('current_pose')}")
        print(f"导航进度: {data.get('progress', 0)*100:.1f}%")
    
    # 注册导航反馈回调
    success = await client.register_navigation_feedback(on_navigation_feedback)

`bool unregister_navigation_feedback()`

功能说明
取消注册导航反馈回调。

参数说明

参数名	类型	必填/默认值	说明
-	-	-	无参数。

返回值

类型	说明
`bool`	取消成功返回 `True`，失败返回 `False`。

C#接口

`bool RegisterNavigationResultCallback(Action<string, object> callback)`

功能说明
注册导航结果事件回调。

参数说明

参数名	类型	必填/默认值	说明
`callback`	`Action<string, object>`	必填	回调函数，接收2个参数： - `result` (string): 结果类型 (如 "complete", "failed") - `data` (object): 事件数据

返回值

类型	说明
`bool`	注册成功返回 `true`，失败返回 `false`。

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();

_navigationClient.RegisterNavigationResultCallback((result, data) =>
{
    Debug.Log($"Navigation Result: {result}, Data: {data}");
});

`bool UnregisterNavigationResultCallback()`

功能说明
取消注册导航结果回调。

参数说明

参数名	类型	必填/默认值	说明
-	-	-	无参数。

返回值

类型	说明
`bool`	取消成功返回 `true`，失败返回 `false`。

调用示例

csharp

_navigationClient.UnregisterNavigationResultCallback();

`bool RegisterNavigationFeedbackCallback(Action<object> callback)`

功能说明
注册导航反馈状态回调。

参数说明

参数名	类型	必填/默认值	说明
`callback`	`Action<object>`	必填	回调函数，接收1个参数： - `feedback` (object): 导航反馈数据

返回值

类型	说明
`bool`	注册成功返回 `true`，失败返回 `false`。

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotNavigationClient _navigationClient;

_robotSDKManager = RobotSDKManager.Instance;
_navigationClient = _robotSDKManager.CreateRobotNavigationClient();

_navigationClient.RegisterNavigationFeedbackCallback((feedback) =>
{
    if (feedback is string jsonString)
    {
        Debug.Log($"Navigation Feedback (JSON): {jsonString}");
    }
    else
    {
        Debug.Log($"Navigation Feedback (Object): {feedback}");
    }
});

`bool UnregisterNavigationFeedbackCallback()`

功能说明
取消注册导航反馈回调。

参数说明

参数名	类型	必填/默认值	说明
-	-	-	无参数。

返回值

类型	说明
`bool`	取消成功返回 `true`，失败返回 `false`。

调用示例

csharp

_navigationClient.UnregisterNavigationFeedbackCallback();

Java接口

`void RegisterNavigationResultCallback(ServiceHandler<NavCompleteRequest, NavCompleteResponse> onComplete, ServiceHandler<NavFailedRequest, NavFailedResponse> onFailed)`

功能说明
注册导航结果回调。

参数说明

参数名	类型	必填/默认值	说明
`onComplete`	`ServiceHandler<NavCompleteRequest, NavCompleteResponse>`	必填	导航完成回调处理器。
`onFailed`	`ServiceHandler<NavFailedRequest, NavFailedResponse>`	必填	导航失败回调处理器。

返回值

类型	说明
`void`	无返回值。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;
import com.lenovo.daystar_bot_sdk_client.DataEntities.*;

// 注册导航结果回调
slamNaviClient.RegisterNavigationResultCallback(
    // 导航完成回调
    (request, response) -> {
        System.out.println("✓ 导航完成: " + request.location_name);
        return response;
    },
    // 导航失败回调
    (request, response) -> {
        System.out.println("✗ 导航失败: " + request.message);
        return response;
    }
);

`void RegisterNavigationFeedbackCallback(Consumer<NavigationFeedback> callback)`

功能说明
注册导航过程反馈回调。

参数说明

参数名	类型	必填/默认值	说明
`callback`	`Consumer<NavigationFeedback>`	必填	反馈回调，接收导航执行过程中的实时状态与进度信息。

返回值

类型	说明
`void`	无返回值。

调用示例

java

import com.lenovo.daystar_bot_sdk_client.client.SlamNaviClient;
import com.lenovo.daystar_bot_sdk_client.DataEntities.NavigationFeedback;

// 注册导航反馈回调
slamNaviClient.RegisterNavigationFeedbackCallback(feedback -> {
    System.out.println("导航状态: " + feedback.status);
    System.out.println("导航进度: " + (feedback.progress * 100) + "%");
});

`void RegisterNarrowRoadInfo(Consumer<NarrowRoadInfo> callback)`

功能说明
注册狭道智行信息回调。

参数说明

参数名	类型	必填/默认值	说明
`callback`	`Consumer<NarrowRoadInfo>`	必填	狭道信息回调。

返回值

类型	说明
`void`	无返回值。

`void UnregisterNarrowRoadInfo()`

功能说明
注销狭道智行信息回调。

参数说明

参数名	类型	必填/默认值	说明
-	-	-	无参数。

返回值

类型	说明
`void`	无返回值。

C++接口

`void setNavigationResultCallback(std::function<void(const std::string &, const std::string &)> callback)`

功能说明
设置导航结果回调。

参数说明

参数名	类型	必填/默认值	说明
`callback`	`std::function<void(const std::string &, const std::string &)>`	必填	回调函数，接收2个参数： - `task_id` (std::string): 任务ID - `result` (std::string): 导航结果数据(JSON字符串)

返回值

类型	说明
`void`	无返回值。

`bool registerNavigationResult()`

功能说明
注册导航结果事件。

参数说明

参数名	类型	必填/默认值	说明
-	-	-	无参数。

返回值

类型	说明
`bool`	成功返回 `true`，否则 `false`。

调用示例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();

// 设置导航结果回调
sysb.setNavigationResultCallback([](const std::string &task_id, const std::string &result) {
    std::cout << "导航任务 " << task_id << " 结果: " << result << std::endl;
});

if (sysb.connect()) {
    sysb.registerNavigationResult();
    sysb.navigateToLocation("办公室入口");
}

`void setNavigationFeedbackCallback(std::function<void(const std::string &)> callback)`

功能说明
设置导航反馈回调。

参数说明

参数名	类型	必填/默认值	说明
`callback`	`std::function<void(const std::string &)>`	必填	回调函数，接收1个参数： - `feedback` (std::string): 导航反馈数据(JSON字符串)

返回值

类型	说明
`void`	无返回值。

`bool registerNavigationFeedback()`

功能说明
注册导航反馈事件。

参数说明

参数名	类型	必填/默认值	说明
-	-	-	无参数。

返回值

类型	说明
`bool`	成功返回 `true`，否则 `false`。

调用示例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();

// 设置导航反馈回调
sysb.setNavigationFeedbackCallback([](const std::string &feedback) {
    std::cout << "导航反馈: " << feedback << std::endl;
});

if (sysb.connect()) {
    sysb.registerNavigationFeedback();
    sysb.navigateToLocation("办公室入口");
}

ROS2接口

导航进度反馈

该接口用于订阅导航过程中的实时进度信息。

Topic 名称	Topic 类型	角色
`/sdk/nav/feedback`	`api_msgs::msg::NavigationFeedback`	发布方

消息结构

字段名称	类型	描述
`task_id`	`string`	当前导航任务 ID。
`target_location`	`string`	目标点位名称。
`current_pose`	`geometry_msgs/Pose`	机器人当前位置。
`distance_remaining`	`float32`	剩余距离（米）。
`navigation_time`	`int32`	已导航时间（秒）。
`time_remaining`	`int32`	预计剩余时间（秒）。
`timestamp`	`string`	时间戳。
`current_state`	`uint8`	当前导航状态码。

current_state 取值

值	描述
`0`	UNKNOWN（未知）
`1`	STRAIGHT_LINE_NAV（直线导航中）
`2`	WAITING（等待中）
`3`	AUTO_PLANNING_NAV（自动规划导航中）

调用示例

bash

ros2 topic echo /sdk/nav/feedback

导航完成事件

导航成功完成时，SDK 服务节点会调用此服务通知上层应用。上层应用需实现该服务的服务端，以接收导航完成事件。

服务名称	服务类型	角色
`/sdk/nav/nav_complete_event`	`api_msgs::srv::NavCompleteEvent`	客户端（SDK 发起调用）

请求结构（Request）

字段名称	类型	描述
`task_id`	`string`	导航任务 ID。
`target_location`	`string`	目标点位名称。
`current_pose`	`geometry_msgs/Pose`	完成时机器人位置。
`navigation_time`	`int8`	导航耗时（秒）。
`timestamp`	`string`	完成时间戳。

响应结构（Response）

字段名称	类型	描述
`success`	`bool`	是否已接收处理。
`message`	`string`	处理结果信息。

导航失败事件

导航失败时，SDK 服务节点会调用此服务通知上层应用。上层应用需实现该服务的服务端，以接收导航失败事件。

服务名称	服务类型	角色
`/sdk/nav/nav_failed_event`	`api_msgs::srv::NavFailedEvent`	客户端（SDK 发起调用）

请求结构（Request）

字段名称	类型	描述
`task_id`	`string`	导航任务 ID。
`error_type`	`int8`	错误类型码。
`error_msg`	`string`	错误描述信息。
`current_pose`	`geometry_msgs/Pose`	失败时机器人位置。
`timestamp`	`string`	失败时间戳。
`target_location`	`string`	目标点位名称。

响应结构（Response）

字段名称	类型	描述
`success`	`bool`	是否已接收处理。
`message`	`string`	处理结果信息。

机器狗服务

通用任务服务接口

SLAM 导航服务接口 ​

建图接口 ​

Python接口 ​

Optional[Dict] start_mapping(timeout=10.0) ​

Optional[Dict] stop_mapping(map_name, auto_reload=True, timeout=10.0) ​

C#接口 ​

(bool success, string message) StartMapping(int id = 209, int timeoutMs = 10000) ​

(bool success, string message) StopMapping(string mapName, bool autoReload = true, int id = 210, int timeoutMs = 10000) ​

Java接口 ​

void StartMapping(String mapName) ​

void StopMapping(String mapName, boolean autoReload) ​

C++接口 ​

CommReply startMapping() ​

CommReply stopMapping(const std::string &map_name, bool auto_reload = true) ​

ROS2接口 ​

开始建图 ​

停止建图 ​

地图管理接口 ​

Python接口 ​

Optional[Dict] load_map(map_name, auto_reload=False, timeout=15.0) ​

Optional[Dict] get_map_list(timeout=10.0) ​

bool upload_map(map_name: str, map_data: bytes, progress_callback: Callable = None) ​

Optional[bytes] download_map(map_name: str, progress_callback: Callable = None) ​

C#接口 ​

(bool success, string message) LoadMap(string mapName, bool autoReload = false, int id = 211, int timeoutMs = 10000) ​

(bool success, string[] map_names, string message) GetMapList(int id = 213, int timeoutMs = 10000) ​

(string status, string message) UploadMap(string mapName, byte[] mapData, int requestId = 300, int timeoutMs = 30000) ​

void DownloadMap(string mapName, int requestId = 301) ​

Java接口 ​

ServiceOperationResponse LoadMap(String mapName, boolean auto_reload) ​

List<String> GetMapList() ​

CompletableFuture<UploadResourceResponse> uploadMap(String mapName, byte[] data, int timeoutSeconds) ​

CompletableFuture<byte[]> downloadMap(String mapName, int timeoutSeconds) ​

C++接口 ​

GetAvailableMapsReply getAvailableMaps() ​

CommReply loadMap(const std::string &map_name, bool auto_reload = false) ​

CommReply uploadMap(const std::string &map_name, const std::vector<uint8_t> &file_data) ​

CommReply downloadMap(const std::string &map_name, const std::vector<uint8_t> &file_data) ​

ROS2接口 ​

加载地图 ​

获取地图列表 ​

定位接口 ​

Python接口 ​

Optional[Dict] get_localization_state() ​

Optional[Dict] get_current_pose() ​

Optional[Dict] relocalization(auto_relocalization, location_name="", location_pose=None, timeout=60.0) ​

C#接口 ​

(bool success, string message) Relocalization(bool autoRelocation, string locationName = null, PoseData locationPose = null, int id = 212, int timeoutMs = 10000) ​

PoseStamped? GetCurrentPose(int id = 207, int timeoutMs = 5000) ​

(bool success, int loc_state)? GetLocalizationStateSync(int id = 208, int timeoutMs = 5000) ​

Java接口 ​

int GetLocalizationState() ​

LocationPose GetCurrentLocationPose() ​

void AutoRelocalization() ​

void RelocateWithName(boolean autoRelocalize, String locationName) ​

void RelocateWithPosition(boolean autoRelocalize, LocationPose poseData) ​

C++接口 ​

bool getLocalizationState(int &loc_state) ​

bool getCurrentPose(Pose &current_pose) ​

CommReply relocalization(bool auto_relocalization, const std::string &location_name, Pose location_pose, int timeout = 60) ​

ROS2接口 ​

获取定位状态 ​

获取当前位置 ​

重定位 ​

添加导航点位 ​

Python接口 ​

Optional[Dict] add_location(location_name, timeout=30, use_virtual_pose=False, virtual_pose=None) ​

C#接口 ​

(bool success, string message) AddLocation(string locationName, int timeout = 30, int id = 200) ​

(bool success, string message) AddLocation(string locationName, float x, float y, float z, float orientationX, float orientationY, float orientationZ, float orientationW, int timeout = 30, int id = 200, int timeoutMs = 5000) ​

Java接口 ​

void AddLocation(String locationName, boolean use_virtual_pose, LocationPose virtual_pose) ​

C++接口 ​

AddLocationReply addLocation(const std::string &location_name, int timeout = 30, bool use_virtual_pose = false, Pose virtual_pose = Pose()) ​

ROS2接口 ​

添加导航点位 ​

删除点位接口 ​

Python接口 ​

SLAM 导航服务接口

建图接口

Python接口

`Optional[Dict] start_mapping(timeout=10.0)`

`Optional[Dict] stop_mapping(map_name, auto_reload=True, timeout=10.0)`

C#接口

`(bool success, string message) StartMapping(int id = 209, int timeoutMs = 10000)`

`(bool success, string message) StopMapping(string mapName, bool autoReload = true, int id = 210, int timeoutMs = 10000)`

Java接口

`void StartMapping(String mapName)`

`void StopMapping(String mapName, boolean autoReload)`

C++接口

`CommReply startMapping()`

`CommReply stopMapping(const std::string &map_name, bool auto_reload = true)`

ROS2接口

开始建图

停止建图

地图管理接口

Python接口

`Optional[Dict] load_map(map_name, auto_reload=False, timeout=15.0)`

`Optional[Dict] get_map_list(timeout=10.0)`

`bool upload_map(map_name: str, map_data: bytes, progress_callback: Callable = None)`

`Optional[bytes] download_map(map_name: str, progress_callback: Callable = None)`

C#接口

`(bool success, string message) LoadMap(string mapName, bool autoReload = false, int id = 211, int timeoutMs = 10000)`

`(bool success, string[] map_names, string message) GetMapList(int id = 213, int timeoutMs = 10000)`

`(string status, string message) UploadMap(string mapName, byte[] mapData, int requestId = 300, int timeoutMs = 30000)`

`void DownloadMap(string mapName, int requestId = 301)`

Java接口

`ServiceOperationResponse LoadMap(String mapName, boolean auto_reload)`

`List<String> GetMapList()`

`CompletableFuture<UploadResourceResponse> uploadMap(String mapName, byte[] data, int timeoutSeconds)`

`CompletableFuture<byte[]> downloadMap(String mapName, int timeoutSeconds)`

C++接口

`GetAvailableMapsReply getAvailableMaps()`

`CommReply loadMap(const std::string &map_name, bool auto_reload = false)`

`CommReply uploadMap(const std::string &map_name, const std::vector<uint8_t> &file_data)`

`CommReply downloadMap(const std::string &map_name, const std::vector<uint8_t> &file_data)`

ROS2接口

加载地图

获取地图列表

定位接口

Python接口

`Optional[Dict] get_localization_state()`

`Optional[Dict] get_current_pose()`

`Optional[Dict] relocalization(auto_relocalization, location_name="", location_pose=None, timeout=60.0)`

C#接口

`(bool success, string message) Relocalization(bool autoRelocation, string locationName = null, PoseData locationPose = null, int id = 212, int timeoutMs = 10000)`

`PoseStamped? GetCurrentPose(int id = 207, int timeoutMs = 5000)`

`(bool success, int loc_state)? GetLocalizationStateSync(int id = 208, int timeoutMs = 5000)`

Java接口

`int GetLocalizationState()`

`LocationPose GetCurrentLocationPose()`

`void AutoRelocalization()`

`void RelocateWithName(boolean autoRelocalize, String locationName)`

`void RelocateWithPosition(boolean autoRelocalize, LocationPose poseData)`

C++接口

`bool getLocalizationState(int &loc_state)`

`bool getCurrentPose(Pose &current_pose)`

`CommReply relocalization(bool auto_relocalization, const std::string &location_name, Pose location_pose, int timeout = 60)`

ROS2接口

获取定位状态

获取当前位置

重定位

添加导航点位

Python接口

`Optional[Dict] add_location(location_name, timeout=30, use_virtual_pose=False, virtual_pose=None)`

C#接口

`(bool success, string message) AddLocation(string locationName, int timeout = 30, int id = 200)`

`(bool success, string message) AddLocation(string locationName, float x, float y, float z, float orientationX, float orientationY, float orientationZ, float orientationW, int timeout = 30, int id = 200, int timeoutMs = 5000)`

Java接口

`void AddLocation(String locationName, boolean use_virtual_pose, LocationPose virtual_pose)`

C++接口

`AddLocationReply addLocation(const std::string &location_name, int timeout = 30, bool use_virtual_pose = false, Pose virtual_pose = Pose())`

ROS2接口

添加导航点位

删除点位接口

Python接口

`Optional[Dict] delete_location(location_name)`

C#接口