马达与传感器

SPIKE 3 Python API 的实用手册，按模块组织，拿来即查。所有示例默认这个接线：左轮 A、右轮 E、附件马达 C、颜色传感器 F、距离传感器 D、力传感器 B。

本页是速查片段

带 await 的行不能直接贴在文件顶层运行——要包进 async def main(): 再 runloop.run(main())（骨架见 Python 环境入门）。页尾的完整示例演示了组装方式。

motor：单个马达

import motor
from hub import port

motor.run(port.C, 500)                          # 以 500 度/秒持续转(不阻塞)
motor.stop(port.C)                              # 停止
await motor.run_for_degrees(port.C, 180, 400)   # 转 180 度(await = 转完才继续)
await motor.run_for_time(port.C, 1000, 400)     # 转 1 秒
await motor.run_to_absolute_position(port.C, 0, 300)   # 转到刻度 0 位置
await motor.run_to_relative_position(port.C, 90, 300)  # 转到相对位置 90

motor.relative_position(port.C)                 # 读累计角度
motor.reset_relative_position(port.C, 0)        # 累计角度清零
motor.absolute_position(port.C)                 # 读绝对刻度(-180~179)
motor.velocity(port.C)                          # 读当前速度

• 速度单位是度/秒：大马达最高约 1050，中马达约 1110。日常用 300-800。
• 负速度或负度数 = 反转。
• 停止方式可传 stop=motor.BRAKE / motor.HOLD / motor.COAST，举重物的臂用 HOLD。

附件动作示例：抬臂 90 度再放下

import runloop, motor
from hub import port

async def main():
    await motor.run_for_degrees(port.C, 90, 300, stop=motor.HOLD)
    await runloop.sleep_ms(500)
    await motor.run_for_degrees(port.C, -90, 200)

runloop.run(main())

motor_pair：底盘

先配对，再移动。配对一次即可（写在 main 外面或程序开头）:

import motor_pair
from hub import port

motor_pair.pair(motor_pair.PAIR_1, port.A, port.E)   # 左, 右

# steering 风格:-100(原地左转)~ 0(直行)~ 100(原地右转)
motor_pair.move(motor_pair.PAIR_1, 0, velocity=400)              # 直行(不阻塞)
await motor_pair.move_for_degrees(motor_pair.PAIR_1, 720, 0, velocity=400)   # 走 720 度
await motor_pair.move_for_time(motor_pair.PAIR_1, 2000, 0, velocity=400)     # 走 2 秒

# tank 风格:分别指定左右轮速度,做精细控制/自己写巡线用它
motor_pair.move_tank(motor_pair.PAIR_1, 400, 300)                # 左快右慢 = 右弧线
await motor_pair.move_tank_for_degrees(motor_pair.PAIR_1, 360, 400, -400)    # 原地右转

motor_pair.stop(motor_pair.PAIR_1)

厘米换算自己做（API 只认度数）:

WHEEL_CM = 17.5                       # 轮周长,实测标定(直驱;有齿轮传动要计入齿轮比)
def cm_to_deg(cm):
    return int(cm / WHEEL_CM * 360)

await motor_pair.move_for_degrees(motor_pair.PAIR_1, cm_to_deg(50), 0, velocity=400)

color_sensor

import color_sensor, color
from hub import port

color_sensor.reflection(port.F)      # 反射光 0-100,巡线用
color_sensor.color(port.F)           # 返回 color.BLACK / color.RED / ... ,无颜色返回 -1
color_sensor.rgbi(port.F)            # (R, G, B, 强度) 原始值,进阶用

if color_sensor.color(port.F) == color.RED:
    ...

distance_sensor

import distance_sensor
from hub import port

d = distance_sensor.distance(port.D)    # 毫米;测不到返回 -1
if d != -1 and d < 80:                  # 8 cm 以内
    ...

永远先判 -1，否则"测不到"会被当成"距离超近"。

force_sensor

import force_sensor
from hub import port

force_sensor.pressed(port.B)     # True / False
force_sensor.force(port.B)       # 0-100,单位 0.1 N

hub 内置

import color
from hub import motion_sensor, light_matrix, button, sound, light

motion_sensor.reset_yaw(0)
yaw_raw = motion_sensor.tilt_angles()[0] / 10  # 原始 yaw:左转为正(与 Word Blocks 相反!)

await light_matrix.write("Go")                # 滚动文字
light_matrix.show_image(light_matrix.IMAGE_HAPPY)
light_matrix.clear()

button.pressed(button.LEFT)                   # 返回按住时长 ms,0 = 没按(可直接当条件用)
sound.beep(440, 200, 100)                     # 频率 Hz, 时长 ms, 音量
light.color(light.POWER, color.GREEN)         # 中央按钮灯变绿

组合示例：完整任务函数库

把 Word Blocks 时代的 My Blocks 翻译成 Python 函数，存成团队函数库：

import runloop, motor_pair, color_sensor, motor
from hub import port, motion_sensor

WHEEL_CM = 17.5
BLACK = 35

motor_pair.pair(motor_pair.PAIR_1, port.A, port.E)

def cm_to_deg(cm):
    return int(cm / WHEEL_CM * 360)

def yaw():
    # App 3 原始 yaw 左转为正;取负号,统一成 Word Blocks 的"右转为正"
    return -motion_sensor.tilt_angles()[0] / 10

async def straight(cm, velocity=400):
    await motor_pair.move_for_degrees(motor_pair.PAIR_1, cm_to_deg(cm), 0, velocity=velocity)

async def turn(angle, velocity=200):
    motion_sensor.reset_yaw(0)
    steering = 100 if angle > 0 else -100
    motor_pair.move(motor_pair.PAIR_1, steering, velocity=velocity)
    if angle > 0:
        await runloop.until(lambda: yaw() > angle - 2, 4000)   # 4 s 超时保底
    else:
        await runloop.until(lambda: yaw() < angle + 2, 4000)
    motor_pair.stop(motor_pair.PAIR_1)

async def main():
    await straight(50)
    await turn(90)
    await straight(30)
    await motor.run_for_degrees(port.C, 180, 300)   # 附件动作
    await straight(-60, velocity=700)               # 倒车回家

runloop.run(main())

下一课：进阶：async 与 PID，解释 await 背后的机制，并写出比赛级巡线。