Johnny-Five Nodebot 实战指南:基于双舵机与 REPL 打造可命令行操控的轮式机器人
Johnny-Five Nodebot 实战指南:基于双舵机与 REPL 打造可命令行操控的轮式机器人
本篇指南围绕 docs/nodebot.md 展开,讲解如何在 Johnny-Five 框架下创建一个由左右两个舵机驱动的轮式机器人(Nodebot),并把控制接口注入 Node.js REPL,让你通过命令行直接完成前进、后退、转向、停止与原地转向等操作。读完本文,你将掌握 Nodebot 的完整初始化流程、全部运动控制 API(含 pivot 指令集)以及与之配套的源码级扩展写法。
一、运行前提:从示例文件开始
示例的完整可运行版本位于 eg/nodebot.js,从命令行执行:
node eg/nodebot.js
运行前需要满足两个前提:
- 安装 Johnny-Five 与 temporal:示例分别通过
require("johnny-five")与require("temporal")引入框架和时间调度工具。其中注释明确建议:任何基于时间的调度都应使用 temporal,而不是手工setTimeout/setInterval堆积回调。 - 确保开发板(如 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
});
从这段代码可以看出三个重要细节:
- 支持多板环境:
Nodebot构造函数与 Johnny-Five 其他类一样接受board选项,可以在five.Boards([...])多板启动时指定其所属板卡; - 方法返回自身,支持链式调用:
nodebot.stop()turn先停止再转向,说明stop()返回实例本身,left/right同样可链式执行; - 存在
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)这类指令即可驱动,无需重启程序,这也是该示例最适合用来验证舵机接线是否正确的原因。
八、延伸阅读
- 完整可运行源码:eg/nodebot.js(本篇主示例)、eg/whisker.js(Nodebot + 触须避障 + 摇杆控制进阶示例)
- 文档原文:docs/nodebot.md
- 板卡初始化与端口选择:docs/board.md、docs/board-with-port.md
- REPL 交互机制:docs/repl.md
- Johnny-Five 能力总览与更多示例索引:README.md
