头部关节

1.head_pos - 头部角度控制

方法： ctrl.head_pos(head_type, pos_deg)

参数：

• head_type：头部类型，HeadType 枚举
  • HeadType.kLower：下头（yaw），水平旋转
  • HeadType.kUpper：上头（pitch），俯仰
• pos_deg：目标角度，float 类型，单位：度 (°)。正值 = 前/上，负值 = 后/下。内部自动限幅：
  • HeadType.kLower (yaw)：-45° ~ +45°
  • HeadType.kUpper (pitch)：-15° ~ +25°

返回值：

• bool：操作结果
  • True：指令发送成功
  • False：指令发送失败

使用示例：

from fd_api import Control, HeadType

ctrl = Control()
ctrl.init({"node_name": "fd_api_control"})

# 下头（yaw）转到 30°
ctrl.head_pos(HeadType.kLower, 30.0)

# 上头（pitch）转到 10°
ctrl.head_pos(HeadType.kUpper, 10.0)

# 下头转到 -20°（向后）
ctrl.head_pos(HeadType.kLower, -20.0)

注意： 限幅范围由机型 robot_profile 的 head_upper_range / head_lower_range 配置决定，上表为默认机型范围；输入超限值会被自动钳位。

2.head_stop - 头部停止

方法： ctrl.head_stop(head_type)

参数：

• head_type：头部类型，HeadType 枚举
  • HeadType.kLower：停止下头（yaw）
  • HeadType.kUpper：停止上头（pitch）

返回值：

• bool：操作结果
  • True：指令发送成功
  • False：指令发送失败

使用示例：

from fd_api import Control, HeadType

ctrl = Control()
ctrl.init({"node_name": "fd_api_control"})

# 停止下头运动
ctrl.head_stop(HeadType.kLower)

# 停止上头运动
ctrl.head_stop(HeadType.kUpper)

3.head_get_current_pos - 获取头部当前位置（同步读取）

方法： state.head_get_current_pos(head_type)

参数：

• head_type：头部类型，HeadType 枚举
  • HeadType.kLower：读取下头（yaw）当前位置
  • HeadType.kUpper：读取上头（pitch）当前位置

返回值：

• float | None：当前头部角度，单位：度 (°)。尚无数据时可能返回 None，收到订阅数据后返回缓存值

使用示例：

from fd_api import State, HeadType

state = State()
state.init({"node_name": "fd_api_state"})

# 读取下头（yaw）当前位置
yaw = state.head_get_current_pos(HeadType.kLower)
if yaw is not None:
    print(f"下头（yaw）角度：{yaw:.1f}°")

# 读取上头（pitch）当前位置
pitch = state.head_get_current_pos(HeadType.kUpper)
if pitch is not None:
    print(f"上头（pitch）角度：{pitch:.1f}°")

4.head_sub_current_pos - 订阅头部位置（异步回调）

方法： state.head_sub_current_pos(callback)

参数：

• callback：回调函数，签名 callback(head_type, deg)
  • head_type：HeadType 类型，标识是下头还是上头
  • deg：float 类型，角度值，单位：度 (°)

返回值：

• SubscriptionId：订阅ID，类型为 int。可用于后续取消订阅；空回调返回 0

使用示例：

from fd_api import State, HeadType

state = State()
state.init({"node_name": "fd_api_state"})

# 定义回调函数
def on_head_pos(head_type, deg):
    name = "下头" if head_type == HeadType.kLower else "上头"
    print(f"{name}角度更新：{deg:.1f}°")

# 订阅头部位置（同时接收下头和上头的更新）
sub_id = state.head_sub_current_pos(on_head_pos)
print(f"订阅成功，订阅ID：{sub_id}")

# 取消订阅
state.unsubscribe(sub_id)
print("已取消头部位置订阅")

建议：

• 回调在线程池中执行，注意线程安全
• 无需接收位置更新时及时取消订阅，避免不必要的回调
• 可与 head_get_current_pos 同步读取配合使用