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

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

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

import asyncio, ff_sdk

async def main():
    dog = await ff_sdk.connect("D1-DEMO")
    try:
        report = dog.diagnose()                      # health check first
        print(report)

        await dog.motion.stand()                     # stand up
        await asyncio.sleep(4)

        await dog.motion.cmd_vel(linear=0.3)         # move forward 0.3 m/s
        await asyncio.sleep(2)
        await dog.motion.stop()

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

        await dog.motion.do_preset("shake_hand")     # shake-hand stunt
        await asyncio.sleep(dog.motion.preset_timeout("shake_hand"))

        await dog.motion.damping()                   # finish: damping (soft e-stop)
    finally:
        await dog.close()

asyncio.run(main())

import ff_sdk
from ff_sdk import Config

# Option 1: all defaults / env vars
dog = await ff_sdk.connect("D1-DEMO")

# Option 2: explicit Config (platform-specific items go in extra)
cfg = Config.from_env()
cfg.extra["d1_host"] = "192.168.1.100"
cfg.extra["d1_variant"] = "zsl-1"
dog = await ff_sdk.connect("D1-DEMO", config=cfg)

# Option 3: pure-code construction
cfg = Config(transport_timeout=5.0, dry_run=False,
             extra={"d1_variant": "zsl-1"})
dog = await ff_sdk.connect("D1-DEMO", config=cfg)

async with await ff_sdk.connect("D1-DEMO") as dog:
    await dog.motion.stand()
    ...
# leaving the with block auto-closes; exceptions won't leak the connection

print(dog.capabilities())
# {'motion', 'state', ...}

if "motion" in dog.capabilities():
    await dog.motion.stand()

if not hasattr(robot.motion, "attitude_control"):
    print("attitude_control is D1 (quadruped) only")
    return

# enter in-place (STAY) mode first, then drive the 4 velocity terms
await robot.motion.attitude_control(pitch_vel=-0.3)               # nod down
await robot.motion.attitude_control(yaw_vel=0.3)                  # turn head left
await robot.motion.attitude_control(roll_vel=0.4, height_vel=0.3) # peek + raise
await robot.motion.attitude_control()                            # back to neutral

res = await dog.motion.do_preset("shake_hand")
# wait the suggested duration for the action to finish before sending the next command
await asyncio.sleep(dog.motion.preset_timeout("shake_hand"))

print(dog.motion.known_presets())   # all action names supported by the current variant

from ff_sdk.core.exceptions import CapabilityNotSupported

try:
    joints = await dog.state.joint_states()
    print(f"{len(joints.names)} joints")
    for name, pos in zip(joints.names, joints.positions):
        print(f"  {name}: {pos:+.3f} rad")
except CapabilityNotSupported as e:
    # some wheeled-foot factory firmware doesn't support joint telemetry (motion control unaffected)
    print(f"this variant/firmware doesn't support joint telemetry: {e}")

# Option 1: env var (recommended, no code change)
export FF_SDK_D1_VARIANT=zsl-1      # point-foot / EDU / Ultra
export FF_SDK_D1_VARIANT=zsl-1w     # wheeled-foot (default when unset)

cfg = Config.from_env()
cfg.extra["d1_variant"] = "zsl-1"
dog = await ff_sdk.connect("D1-DEMO", config=cfg)

from ff_sdk import skills

result = await skills.wave(dog)              # auto-mapped to shake-hand on Aegis
result = await skills.bow(dog)               # auto-mapped to a nod
result = await skills.greet(dog, "friend")   # wave + (on platforms with audio) greeting
print(result)   # {"ok": True, "message": "...", "platform": "..."}

import ff_sdk
from ff_sdk.core.exceptions import (
    CapabilityNotSupported, EStopActiveError, StateError)

try:
    await dog.motion.stand()
except CapabilityNotSupported as e:
    print(f"this variant doesn't support: {e}")
except EStopActiveError:
    print("e-stop active; clear the hazard before resetting")
except StateError as e:
    print(f"current state disallows: {e}")   # e.g. charging

report = dog.diagnose()
print(report)
# online status of every link (control / telemetry / motion backend) at a glance
# always the first debugging step — look here, don't guess