01Overview & Capability Matrix概览与能力矩阵

02Installation安装

# On the robot (aarch64)
pip install wheels/ff_sdk-0.1.0a2-cp310-cp310-linux_aarch64.whl

# On a Linux dev machine (x86_64)
pip install wheels/ff_sdk-0.1.0a2-cp310-cp310-linux_x86_64.whl

python -c "import ff_sdk; print(ff_sdk.__version__)"

# 在机器人上（aarch64）
pip install wheels/ff_sdk-0.1.0a2-cp310-cp310-linux_aarch64.whl

# 在 Linux 开发机上（x86_64）
pip install wheels/ff_sdk-0.1.0a2-cp310-cp310-linux_x86_64.whl

python -c "import ff_sdk; print(ff_sdk.__version__)"

Navi talks to the robot over WebSocket; put your dev machine on the same LAN as the robot and you can control it —— this is the smoothest remote-development experience of the four platforms.

Navi 经 WebSocket 与机器人通信，开发机与机器人同一局域网即可控制 —— 这是四个平台里 远程开发体验最顺的一个。

03Quickstart快速开始

import asyncio, ff_sdk

async def main():
    async with await ff_sdk.connect("NV-DEMO") as dog:
        print(dog.diagnose())

        # —— standard capabilities (same code across platforms) ——
        await dog.motion.stand()                 # stand ready
        await asyncio.sleep(6)

        await dog.motion.cmd_vel(linear=0.2)     # move forward
        await asyncio.sleep(2)
        await dog.motion.stop()

        battery = await dog.state.battery()
        print(f"battery {battery.percent:.0%}")

        # —— Navi dedicated extensions ——
        nv = dog.navi
        actions = await nv.list_actions()        # all available extended actions
        await nv.do_action(20542)                # wave
        await nv.set_foot_height(0.08)           # raise foot height

        await dog.motion.damping()               # wrap up

asyncio.run(main())

import asyncio, ff_sdk

async def main():
    async with await ff_sdk.connect("NV-DEMO") as dog:
        print(dog.diagnose())

        # —— 标准能力（跨平台同一套写法）——
        await dog.motion.stand()                 # 站立就绪
        await asyncio.sleep(6)

        await dog.motion.cmd_vel(linear=0.2)     # 前进
        await asyncio.sleep(2)
        await dog.motion.stop()

        battery = await dog.state.battery()
        print(f"电量 {battery.percent:.0%}")

        # —— Navi 专属扩展 ——
        nv = dog.navi
        actions = await nv.list_actions()        # 全部可用扩展动作
        await nv.do_action(20542)                # 招手
        await nv.set_foot_height(0.08)           # 抬高抬脚

        await dog.motion.damping()               # 收尾

asyncio.run(main())

04Connect / Variants / Config连接 / 变体 / 配置

Variants & target prefix变体与 target 前缀

The Navi lineup has three variants with an identical API, selected by target prefix (or config):

Navi 产品线有三个变体，API 相同，通过 target 前缀（或配置）选择：

Environment variables环境变量

from ff_sdk import Config

cfg = Config.from_env()
cfg.extra["navi_host"] = "192.168.1.77"
cfg.extra["navi_variant"] = "a100_dev"     # a100_dev | devq | mini
dog = await ff_sdk.connect("NV-DEMO", config=cfg)

from ff_sdk import Config

cfg = Config.from_env()
cfg.extra["navi_host"] = "192.168.1.77"
cfg.extra["navi_variant"] = "a100_dev"     # a100_dev | devq | mini
dog = await ff_sdk.connect("NV-DEMO", config=cfg)

05Session & LifecycleSession 与生命周期

nv = dog.navi
if nv is None:
    print("this variant has no extended namespace (Mini / DevQ)")
else:
    await nv.do_action(20542)

nv = dog.navi
if nv is None:
    print("此变体不提供扩展命名空间（Mini / DevQ）")
else:
    await nv.do_action(20542)

06motion · Motion Control运动控制

import math

await dog.motion.stand()
await asyncio.sleep(6)

for _ in range(4):                              # walk a square
    await dog.motion.cmd_vel(linear=0.25)       # go straight
    await asyncio.sleep(3)
    await dog.motion.cmd_vel(angular=math.pi/4) # turn 90° in place
    await asyncio.sleep(2)

await dog.motion.stop()

import math

await dog.motion.stand()
await asyncio.sleep(6)

for _ in range(4):                              # 走一个正方形
    await dog.motion.cmd_vel(linear=0.25)       # 直行
    await asyncio.sleep(3)
    await dog.motion.cmd_vel(angular=math.pi/4) # 原地转 90°
    await asyncio.sleep(2)

await dog.motion.stop()

07state · State Telemetry状态遥测

08navi.do_action · Extended Action Library ★navi.do_action · 扩展动作库 ★

Navi ships 134 built-in extended actions (the library may grow or shrink with firmware updates). list_actions() returns the authoritative action list (ID + name) for this specific robot —— run it once before writing code. Needs roslibpy<2 (actionlib).

Navi 内置 134 个扩展动作（动作库随固件更新可能增减）。 list_actions() 返回当前这台机器的权威动作清单（ID + 名称）—— 写代码前先跑一次它。需 roslibpy<2（actionlib）。

Two real-machine notes (2026-06-28): (1) return_to_ready=True (default) auto-sends action_id 4 after the action so the dog returns to a neutral ready stance — without it an extended action holds its final pose indefinitely. (2) The list_actions() menu is not the complete set: some stunt IDs (e.g. 516 = punch) are reachable via do_action() but not advertised in the menu — the controller knows them.

两条真机说明（2026-06-28）：（1）return_to_ready=True（默认）会在动作后自动补发 action_id 4 让狗回到中性就绪姿态——不补的话扩展动作会一直保持最后姿势不收。（2）list_actions() 菜单并非全集：部分特技 ID（如 516 = 出拳）可经 do_action() 触发但不在菜单广播里——控制器认得它们。

Common action IDs常用动作 ID

actions = await dog.navi.list_actions()

def find_id(actions, keyword: str) -> int | None:
    for act in actions.items:          # (id, name) list
        if keyword in act.name:
            return act.id
    return None

wave_id = find_id(actions, "wave")
if wave_id is not None:
    result = await dog.navi.do_action(wave_id, hold_time=4.0)
    print(result)

actions = await dog.navi.list_actions()

def find_id(actions, keyword: str) -> int | None:
    for act in actions.items:          # (id, name) 列表
        if keyword in act.name:
            return act.id
    return None

wave_id = find_id(actions, "wave")
if wave_id is not None:
    result = await dog.navi.do_action(wave_id, hold_time=4.0)
    print(result)

Parameters参数

09navi.set_* · Motion Parameter Tuning ★navi.set_* · 运动参数调节 ★

Tune gait and motion style in real time —— this is the “playability” that sets Navi apart from the other platforms:

实时调节步态与运动风格 —— 这是 Navi 区别于其他平台的“可玩性”所在：

Advanced setters (note: pending real-robot regression confirmation)进阶 setter（标注：待真机回归确认）

The following parameter interfaces are defined; their message structures are under ongoing real-robot validation —— tune in small steps and observe: set_ground_model / set_free_leg / set_swing_traj_type / set_controller_type / set_model_scale / set_swaying_duration / set_swing_duration / set_velocity_decay / set_decelerate.

以下参数接口已定义，消息结构在持续真机验证中 —— 使用时建议小步调整并观察： set_ground_model / set_free_leg / set_swing_traj_type / set_controller_type / set_model_scale / set_swaying_duration / set_swing_duration / set_velocity_decay / set_decelerate。

set_raw —— the escape hatchset_raw —— 逃生口

Send raw messages directly to low-level interfaces the SDK doesn't yet wrap. Use only when you know the message structure exactly —— a wrong structure may be ignored by the underlying layer or cause unexpected behavior.

对 SDK 尚未封装的底层接口直接发原始消息。仅在你明确知道消息结构时使用， 错误结构可能被底层忽略或产生预期外行为。

# grass: raise feet + conservative speed
await dog.navi.set_foot_height(0.08)
await dog.navi.set_collision_protect(True)
await dog.motion.cmd_vel(linear=0.15)

# 草地：抬高脚 + 保守速度
await dog.navi.set_foot_height(0.08)
await dog.navi.set_collision_protect(True)
await dog.motion.cmd_vel(linear=0.15)

10navi Convenience Methods ★navi 便利方法 ★

nv = dog.navi
await nv.do_action(20542, hold_time=4.0)    # wave
await nv.do_action(20567, hold_time=8.0)    # shoulder dance
await nv.do_action(20510, hold_time=4.0)    # bow to close
await dog.motion.damping()

nv = dog.navi
await nv.do_action(20542, hold_time=4.0)    # 招手
await nv.do_action(20567, hold_time=8.0)    # 抖肩舞
await nv.do_action(20510, hold_time=4.0)    # 鞠躬谢幕
await dog.motion.damping()

11Cross-platform Skills跨平台 Skills

from ff_sdk import skills

await skills.wave(dog)        # auto-mapped to the "wave" extended action on Navi
await skills.bow(dog)         # → "bow" extended action
await skills.greet(dog, "friend")

from ff_sdk import skills

await skills.wave(dog)        # Navi 上自动映射为扩展动作“招手”
await skills.bow(dog)         # → 扩展动作“鞠躬”
await skills.greet(dog, "朋友")

On Navi, skills internally route through navi.do_action(), but the caller never needs to care —— the same line of code runs just as well on Aegis / Futurist.

skills 在 Navi 上内部走 navi.do_action()，但调用方完全不用关心 —— 同一行代码换到 Aegis / Futurist 照样跑。

12Errors & Diagnostics异常与诊断

report = dog.diagnose()
print(report)   # control-channel connectivity, variant detection result

report = dog.diagnose()
print(report)   # 控制通道连通性、变体识别结果

13Example Index示例索引

14FAQ / TroubleshootingFAQ / 排错