导航环境与运行时

导航任务执行前需要运动控制、定位扫描、导航容器及有效位姿。推荐先调用一键启动，再检查状态。导航和建图使用互斥的运行环境；切换前停止另一环境并确认停止完成。

5.1 POST /v1/api/nav/startup

同步准备环境。步骤为 motion → scan → nav_container → nav_params → set_pose。已经运行的服务可复用；失败不自动回滚之前成功的步骤。

请求字段	类型	必填 / 默认	说明
pose.x、pose.y、pose.theta	number	均必填	初始位姿；0 是合法值
nav_container.scene_name	string	必填	已存在的地图名称
nav_container.bringup_mode	string	可省略	常用 navigation；容器请求也支持 mapping，建图业务使用第 11 章专用入口
nav_container.use_relocalization	boolean	false	是否启用重定位
nav_container.use_sim_time	boolean	false	仿真时间
nav_container.use_online_map	boolean	false	在线地图
nav_container.use_foxglove_bridge	boolean	false	Foxglove 桥接
nav_container.runtime_version	string	自动选择	从本机运行时镜像目录选取
motion.adapter_type	string	可省略	运动服务未启动时，空值使用可用适配器列表的首项；列表为空则失败

{
  "motion":{"adapter_type":"adapter-from-device"},
  "pose":{"x":0.0,"y":0.0,"theta":0.0},
  "nav_container":{"scene_name":"office_1f","bringup_mode":"navigation","use_relocalization":true}
}

成功响应 data 示例：

{
  "steps_completed":["motion","scan","nav_container","nav_params","set_pose"],
  "motion":{"adapter_type":"adapter-from-device"},
  "pose":{"x":0.0,"y":0.0,"theta":0.0},
  "nav_container":{
    "scene_name":"office_1f","bringup_mode":"navigation",
    "use_relocalization":true,"use_sim_time":false,
    "use_online_map":false,"use_foxglove_bridge":false,
    "runtime_version":"version-from-device","runtime_image":"image-from-device","runtime_source":"config"
  },
  "environment_reused":false
}

runtime_* 字段取实际解析结果，可能省略；environment_reused=true 表示复用了运行中的环境，不保证请求中的所有容器选项重新生效。希望切换地图、运行时或启动选项时，应先停止并确认状态，再准备新环境。

超时与参数回放： 新启动时依次等待容器运行（最多 60 s）、导航 API 健康（最多 120 s）、参数 API 健康（最多 120 s），还需加下游调用耗时。客户端建议预留至少 360 s，并结合部署时延设置。已保存参数通过后台回放应用，steps_completed 包含 nav_params 不意味着每项参数都已验证成功；进一步查询 /nav/params/apply_status。

失败完整响应示例：

{"code":2001,"msg":"navigation container API is not ready","data":{"failed_step":"nav_container","steps_completed":["motion","scan"]}}

JSON/必填字段错误为 400/1001；步骤失败为 500/2001。失败消息仅示意，failed_step 和 steps_completed 用于恢复操作。

5.2 POST /v1/api/nav/container/start

仅启动导航容器，不替代运动控制、扫描和位姿准备。JSON 体可省略；业务接入应明确提供地图。

字段	类型	说明
scene_name	string	地图名
map_revision	string，可选	地图修订绑定
bringup_mode	string，可选	缺省由导航运行时处理，常用 navigation
use_relocalization、use_sim_time、use_online_map、use_foxglove_bridge	boolean	缺省 false
runtime_version	string，可选	期望运行时版本
runtime_image	string，可选	结构中存在的镜像字段；正常装配由运行时选择器解析，不作为任意拉取镜像入口

{"scene_name":"office_1f","bringup_mode":"navigation","use_relocalization":true}

响应 data：

{"runtime_version":"version-from-device","runtime_image":"image-from-device","source":"config","already_running":false}

source 是实际选择来源，常见为配置、保存默认值、请求或运行中环境；以返回字符串为准。成功后异步回放已保存参数。失败通常为 2001；下游调用错误可为 502/1005。

5.3 导航容器停止与状态

接口	请求	响应 data / 行为
POST /v1/api/nav/container/stop	无请求体	null；后台停止，错误记录在日志中，必须轮询确认
GET /v1/api/nav/container/status	无	ContainerState

ContainerState 主要字段：running: boolean、status: string、container_id: string、started_at（如可用）。status 为 running、stopped、not_found、unknown；附加运行元信息按设备返回。不要把 unknown 当成已停止。

{"running":true,"status":"running","container_id":"example-container-id","started_at":"2026-11-13T08:00:00Z"}

5.4 GET /v1/api/nav/runtime/images

列出本机可选运行时，不触发镜像下载。无参数。

字段	类型	说明
configured_image、configured_version	string	配置文件默认镜像、版本
default_image、default_version、default_available	string、string、boolean	当前保存的默认选择及可用性
images	ImageInfo[]	可选镜像目录
running	RunningInfo / null	当前运行环境
conflict	RunningInfo[]	冲突的运行环境

ImageInfo：version、image、source 为 string；available、configured_default、selected_default 为 boolean。RunningInfo：kind、container_name、version、image 为 string。

5.5 设置 / 清除默认运行时

接口	请求	响应 data
PUT /v1/api/nav/runtime/default	{"runtime_version":"version-from-images"}	与容器启动选择结果相同：runtime_version、runtime_image、source、already_running
DELETE /v1/api/nav/runtime/default	无	null，恢复配置默认值

设置默认值会检查版本在本机是否存在，但当前不会因已有容器运行而拒绝保存，也不会切换该容器。缺失/空白 runtime_version、版本不存在、Docker 查询或设置存储失败由此入口映射为 500/2001；JSON 解析失败为 400/1001。启动容器时的版本与互斥检查是另一个步骤。