Johnny-Five Nodebot 实战指南:基于双舵机与 REPL 打造可命令行操控的轮式机器人

原创2026-09-22 20:51:161,643 阅读
文章标签:IoT机器人嵌入式

Johnny-Five Nodebot 实战指南:基于双舵机与 REPL 打造可命令行操控的轮式机器人

本篇指南围绕 docs/nodebot.md 展开,讲解如何在 Johnny-Five 框架下创建一个由左右两个舵机驱动的轮式机器人(Nodebot),并把控制接口注入 Node.js REPL,让你通过命令行直接完成前进、后退、转向、停止与原地转向等操作。读完本文,你将掌握 Nodebot 的完整初始化流程、全部运动控制 API(含 pivot 指令集)以及与之配套的源码级扩展写法。

典型 Nodebot 硬件构成(双舵机、控制板与扩展电路)

一、运行前提:从示例文件开始

示例的完整可运行版本位于 eg/nodebot.js,从命令行执行:

node eg/nodebot.js

运行前需要满足两个前提:

  1. 安装 Johnny-Five 与 temporal:示例分别通过 require("johnny-five") 与 require("temporal") 引入框架和时间调度工具。其中注释明确建议:任何基于时间的调度都应使用 temporal,而不是手工 setTimeout/setInterval 堆积回调。
  2. 确保开发板(如 Arduino)已通过串口连接并烧录 Firmata 固件:Johnny-Five 基于 Firmata 协议工作,程序必须先与板卡建立串口通信通道,然后才能执行任何硬件相关代码。

二、完整示例代码与运行效果

以下是文档给出的完整程序(与 eg/nodebot.js 一致):

var five, temporal, Nodebot;

five = require("johnny-five");
/**
 * Any time-based scheduling
 * should use temporal
 */
temporal = require("temporal");

/**
 * Programs MUST initialize a serial
 * communication "channel" with the board
 * before executing hardware-specific code
 */
five.Board().on("ready", function() {

  /**
   * Initialize an instance of Nodebot
   * with properties "right" and "left"
   * whose values must correspond to the
   * pin for each respective servo.
   */
  Nodebot = new five.Nodebot({
    right: 10,
    left: 11
  });

  /**
   * Inject Nodebot instance into REPL,
   * this will allow a user to navigate
   * and control the Nodebot via the
   * command line
   */
  this.repl.inject({
    n: Nodebot
  });
});

程序逻辑只有三步:初始化板卡、创建 Nodebot、把实例注入 REPL。运行后,你可以在终端中直接通过 n 对象控制机器人运动(详见下文 API 部分)。

三、逐段拆解:初始化、实例化与 REPL 注入

3.1 板卡初始化(串口通道是硬性前提)

five.Board().on("ready", function() {

Johnny-Five 的所有硬件程序都必须先初始化一个与板卡之间的串口通信"通道",再执行硬件相关代码。five.Board() 默认自动探测串口端口,ready 事件触发即代表板卡连接成功、可以安全地创建硬件实例。更精细的端口选择方式可参考 docs/board.md 与 docs/board-with-port.md。

3.2 创建 Nodebot 实例

Nodebot = new five.Nodebot({
  right: 10,
  left: 11
});

构造参数中 right 与 left 的值必须对应左右两个舵机的信号引脚号。本示例中右舵机接引脚 10,左舵机接引脚 11。文档并未规定 Nodebot 构造器内部的具体实现,但从 eg/whisker.js 的用法可以推断,它本质上是对两个舵机的组合封装,并对外暴露统一的运动控制接口。

3.3 注入 REPL,获得命令行控制能力

this.repl.inject({
  n: Nodebot
});

this.repl.inject() 把 Nodebot 实例以键名 n 注入到 Johnny-Five 启动的交互式 REPL 中。注入之后,你不再需要编写额外代码,就可以在命令行里实时输入 n.fwd(3)、n.left(1000) 等指令指挥机器人,非常适合做硬件调试与交互式演示。

四、Nodebot 控制 API 全解

文档明确列出了可通过 REPL 中 n 对象调用的全部运动方法,整理如下:

方法 参数 行为
n.fwd(speed) speed:1~5 以指定速度前进
n.rev(speed) speed:1~5 以指定速度后退
n.left(time = 500) time:毫秒 左转指定时长,默认 500ms
n.right(time = 500) time:毫秒 右转指定时长,默认 500ms
n.stop() 无 停止机器人
n.pivot(instruction) 指令字符串 按指令原地转向(见下文)

4.1 speed:速度等级 1~5

speed 是一个 1 到 5 的数字:1 最慢,5 最快。fwd 与 rev 都需要传入该速度值;转向方法 left/right 则只接受时长参数(毫秒),不指定时默认 500ms。

4.2 pivot:原地转向指令

pivot(instruction) 通过指令字符串决定转向方式,支持以下四种写法(含缩写):

  • "forward-right" 或 "f-r":右前原地转向
  • "forward-left" 或 "f-l":左前原地转向
  • "reverse-right" 或 "r-r":右后原地转向
  • "reverse-left" 或 "r-l":左后原地转向

五、源码级佐证:从 whisker 示例看 Nodebot 的接口契约

虽然 docs/nodebot.md 只给出了最精简的用法,但仓库中的 eg/whisker.js 对 Nodebot 的接口进行了更充分的组合使用,可以交叉印证其底层行为:

nodebot = new five.Nodebot({
  board: boards.nodebot,   // 支持多板场景,指定 Nodebot 所在的板
  right: 10,
  left: 11
});

从这段代码可以看出三个重要细节:

  1. 支持多板环境:Nodebot 构造函数与 Johnny-Five 其他类一样接受 board 选项,可以在 five.Boards([...]) 多板启动时指定其所属板卡;
  2. 方法返回自身,支持链式调用:nodebot.stop()turn 先停止再转向,说明 stop() 返回实例本身,left/right 同样可链式执行;
  3. 存在 speed 与 motion 两个运行时状态属性:nodebot.speed = value 可动态更新速度等级,nodebot.motion !== "stop" 则暴露当前运动状态(例如 "fwd"、"rev"、"stop"),修改速度后可通过 nodebot[nodebot.motion]() 重新下发指令让新速度生效。

在 whisker 示例中,这套接口被进一步编排成完整的"触须避障 + 摇杆控制"机器人:左右触须(five.Pin)检测碰撞后调用 nodebot.stop()turn 反向回避,X/Y 摇杆(five.Sensor)映射为 left/right/rev/fwd 指令,第三个传感器则动态调节 nodebot.speed。

六、关于 five.Nodebot 实现位置的说明

需要特别指出:查看当前仓库 lib/johnny-five.js 的导出列表(第 3~41 行)可以发现,官方框架本体的导出项中并不包含 Nodebot——它只出现在文档与示例中。因此,new five.Nodebot(...) 所指向的实现需要由使用者按上述接口契约自行提供(例如以两个 five.Servo 为底层、封装出 fwd/rev/left/right/stop/pivot/speed/motion 接口的驱动类),文档与示例的作用是定义这套稳定、可复用的运动控制约定。

七、常见问题与注意事项

  • 必须在 ready 回调内创建实例:串口通道未建立前操作硬件会失败,这是 Johnny-Five 的通用约束,Nodebot 也不例外。
  • 引脚必须与接线一致:right: 10, left: 11 中的数字是舵机信号线所接的引脚,实际接线变化时务必同步修改。
  • 转向时长有默认值:left()/right() 不传参时默认转向 500ms;若需要精确转角,请显式传入毫秒数。
  • 时间相关的调度优先使用 temporal:文档注释明确建议,涉及"定时动作序列"(如前进 2 秒后左转)时使用 temporal 包组织时间逻辑,避免回调嵌套失控。
  • REPL 注入后即可交互:启动后直接输入 n.fwd(3) 这类指令即可驱动,无需重启程序,这也是该示例最适合用来验证舵机接线是否正确的原因。

八、延伸阅读

登录后查看全文
johnny-five