Johnny-Five 社区 Nodebot 实战案例全解析:从 awesome.md 清单到可复现的机器人项目
Johnny-Five 社区 Nodebot 实战案例全解析:从 awesome.md 清单到可复现的机器人项目
导读
awesome.md 是 Johnny-Five 官方仓库中一份按作者组织、由新到旧排序的社区项目精选清单,记录了约 20 个基于 JavaScript + Arduino 的真实 Nodebot 作品,涵盖舵机机械臂、Wii Nunchuk 体感控制、LCD 显示屏、移位寄存器数码管、环境传感器与 WebSocket 可视化等多个方向。本文以该清单为骨架,逐条还原每个项目的硬件构成与核心思路,并将它们一一映射到本仓库 eg/ 目录下的可运行示例与 lib/ 目录下的源码实现,让你既能看懂"别人用 Johnny-Five 做了什么",也能直接在仓库里找到"自己该怎么复现和扩展"。
一、这份清单是什么:awesome.md 的结构与定位
awesome.md 位于仓库根目录,本质上是一个"精选集(Awesome List)",条目以贡献者(作者)为单位分组,每个条目包含:
- 项目名称与一句话功能描述;
- 作者 Twitter/社交账号;
- 配套的视频演示与代码仓库链接(原始链接见该文件正文)。
清单明确标注 Entries listed newest to oldest(按新→旧排列),早期条目(如 2012 年的 LCD Controller、Shift Register 计数器)甚至标注了"First successful implementation"或"Became the basis for the LCD constructor"这类历史注脚——这说明清单本身就是 Johnny-Five 组件 API 演化史的一部分:社区先做出验证性实现,随后才被吸收进框架正式构造函数。
从信息组织方式看,这份清单的价值在于:
- 覆盖了 Johnny-Five 的核心组件面:Servo、Joystick、Nunchuk、LCD、ShiftRegister、LED、Proximity、Sensor 等;
- 展示真实硬件组合模式:如"摇杆 + 舵机""PS3 手柄 + 蓝牙 + 舵机""压力传感器 + 三色 LED""近距传感器 + 音调合成";
- 是入门者寻找"想复现的机器人"的第一手索引。
二、清单里的项目,仓库里都有对应代码:快速上手路径
awesome.md 中的大多数创意,都能在仓库 eg/ 示例目录里找到同主题的可运行代码;而组件的底层行为则在 lib/ 对应源文件中实现。上手路径如下:
- 克隆仓库并安装依赖:
git clone https://gitcode.com/gh_mirrors/jo/johnny-five
cd johnny-five
npm install
- 阅读 README.md 了解框架定位("The JavaScript Robotics Programming Framework")与 Board 初始化方式;
- 在
eg/下挑选与你的硬件匹配的示例直接运行,例如:
node eg/servo-sweep.js # 舵机扫动
node eg/joystick.js # 摇杆读取
node eg/lcd-runner.js # LCD 文字跑马灯
node eg/shift-register-seven-segment.js # 七段数码管计数
注意:示例默认连接 Arduino(或其他受支持的 IO 板)并尝试自动检测串口;运行前需先烧录对应固件(见 firmwares/ 目录)并将硬件接线正确。
三、按技术主题深度解读清单项目
下面将清单中的约 20 个条目按"硬件/技术主题"归类,逐条还原其技术要点,并给出仓库内的对应实现证据。
3.1 舵机与机械臂:抓爪、机械臂、绘图机器人
这是清单中出现频率最高的主题,涉及 Servo 组件在机械结构上的直接应用。
Clawbot(Ricardo de Pena):一款带机械抓爪(claw)的蓝牙小车,用 PS3 手柄遥控。抓爪本质上是一个或两个舵机驱动的夹持机构,仓库中 eg/claw.js 展示了最朴素的控制方式——five.Servo(9) 驱动抓爪、five.Servo(10) 驱动机械臂,通过 board.loop(25, ...) 每 25ms 步进 10° 并做 0–180° 往返摆动:
var claw = new five.Servo(9);
var arm = five.Servo(10);
var degrees = 10;
var incrementer = 10;
this.loop(25, function() {
if (degrees >= 180 || degrees === 0) {
incrementer *= -1;
}
degrees += incrementer;
claw.to(degrees);
});
而 eg/joystick-claw.js 则把"手柄/摇杆 + 抓爪"的组合还原得更彻底:用 five.Joystick 的 Y 轴数值控制抓爪开合,并通过 five.Fn.scale(this.y, -1, 1, 0, 170) 把摇杆的 [-1, 1] 区间线性映射到舵机角度区间,同时用 range: [0, 170] 限制中型舵机的安全转角:
var claw = new five.Servo({ pin: 9, range: [0, 170] });
var joystick = new five.Joystick({ pins: ["A0", "A1"], freq: 250 });
claw.to(90); // 摇杆死区位置 = 抓爪半开
joystick.on("change", function() {
claw.to(five.Fn.scale(this.y, -1, 1, 0, 170));
});
底层原理:Servo 的默认控制器是 Standard,见 lib/servo.js——它把用户指定的角度(degreeRange,默认 0–180)通过 Fn.map 线性映射为脉宽微秒数(pwmRange,默认 0–180 对应约 600–2400µs),再交给 this.io.servoWrite(pin, microseconds) 输出 PWM 信号。因此"角度"只是对脉宽的语义化包装,这也解释了为何抓爪类项目都强调 range 参数(防止超出舵机机械行程)。
Missile Command(Andrew Homeyer、Matt Parrish、Nicholas Boll):橡皮筋发射器,击落一架 nodecopter。本质是多舵机精确瞄准 + 触发释放的组合,对应 Servo 的定点定位能力(servo.to(degrees))。
Manny the Manipulator(Raquel Vélez):二维串联机械臂,利用正/逆向运动学解算关节角度(配合 vektor 向量库)。这属于 Servo 的高阶用法——用运动学把末端位置换算成多个关节舵机的角度,仓库中 eg/servo-animation-leg.js、eg/servo-animation.js 提供了"多舵机协同 + 动画轨迹"的参考实现(Animation 类位于 lib/animation.js)。
Dorby the DoorBot(Francis Gulotta):开门机器人,使用舵机驱动门把手旋转,演示了舵机 + 机械结构的力矩/行程配合。
SCARA Drawbot(Ibnu Triyono):用 2 个 SG90 微型舵机搭建的 SCARA(平面关节)绘图机器人。SG90 是廉价标准舵机,直接对应 five.Servo 默认 Standard 控制路径,是"低成本复现"的典型。
主题小结:抓爪/机械臂类项目的共性模式 =
Servo+ 位置映射(Fn.scale/Fn.map)+ 循环调度(board.loop)。源码依据:lib/servo.js、lib/fn.js。
3.2 输入设备:手柄、摇杆、Nunchuk 与体感控制
Wii Nunchuk 控制 AR Drone(Irene Ros、Chris Williams):两人分别独立完成了"用 Wii 经典手柄的 Nunchuk 遥控 AR Drone 无人机"。仓库中 eg/nunchuk.js 是完整的 Nunchuk 示例,展示了 Johnny-Five 组件的事件 API:
nunchuk.joystick.on("change"):摇杆轴变化,事件含event.axis、event.direction;nunchuk.accelerometer.on("change"):加速度计轴变化;nunchuk.on("down"/"up"/"hold"):按键按下、抬起与长按(默认 500ms,可通过holdtime配置)。
nunchuk = new five.Wii.Nunchuk({ freq: 50 });
nunchuk.joystick.on("change", function(event) {
console.log("joystick " + event.axis, event.target[event.axis], event.direction);
});
Joystick 控制的 Google Maps Streetview(Cole Gillespie):把双轴摇杆映射为街景视角移动,对应 eg/joystick.js:
var joystick = new five.Joystick({ pins: ["A0", "A1"] });
joystick.on("change", function() {
console.log("x:", this.x, "y:", this.y);
});
Joystick 会把两路模拟输入归一化为 [-1, 1] 的 x/y,配合 five.Fn.scale 可驱动任何连续量(角度、音量、视角)。
Power Glove(Travis Thieman):用"动力手套"手势控制 macOS 音量,属于"模拟输入 → 系统级输出"的跨界集成,底层仍是对多路模拟输入(弯曲传感器/电位器)的连续读取。
Leap Motion 控制 LED 颜色(Yusuf Çakmak):用 Leap Motion 手势数据经 Arduino 改变 LED 颜色,是"外部数据源 → Johnny-Five 输出"的模式,对应仓库 eg/led-rgb.js(RGB LED 颜色控制)与 lib/led/rgb.js。
Typing Bot(Rahul Ravikumar、Bryan Hughes):打字机器人(nodebots/JSConf 展示),演示了高精度步进/舵机定位,与仓库 eg/stepper-sweep.js、eg/servo-diagnostic.js 属于同一技术面。
3.3 LED、显示屏与七段数码管
Tri-color LED 随压力传感器变色(Sara Gorecki):Sensor(FSR 压力传感器)读数 → 映射为三色 LED 颜色,仓库对应 eg/sensor-fsr.js、eg/led-rgb.js 与文档 docs/sensor-fsr.md。
CI 构建状态灯(Tim Walker,cilite):把持续集成(CI)构建结果映射为状态灯颜色,是最经典的"物理通知"应用,对应 LED.RGB 与 board 生命周期管理(参考 docs/led-rgb.md)。
Shift Register + LED 计数器(Rebecca Murphey):用移位寄存器驱动 LED 计数器显示。仓库中 eg/shift-register.js 以 74HC595 芯片为例,通过 data/clock/latch 三根线串行移位输出二进制图案:
const register = new ShiftRegister({ pins: { data: 2, clock: 3, latch: 4 } });
let value = 0b00000000;
let upper = 0b10001000;
let lower = 0b00010001;
function next() {
register.send(value = value > lower ? value >> 1 : upper);
setTimeout(next, 200);
}
next();
底层原理:ShiftRegister.send()(lib/shiftregister.js)的实现是先拉低 latch 引脚打开锁存、逐个 board.shiftOut(data, clock, true, value) 移入字节、再拉高 latch 提交数据——这正是"3 根线驱动无限多输出引脚"的经典串行扩展原理。七段数码管场景则用 display() 方法直接传数字或字符串,源码内部通过内置的共阴/共阳编码表(cathode: <a href="https://link.gitcode.com/i/e96916ae5acf297937a436dcba8438d0" target="_blank">63, 6, 91, ...]、anode: [64, 121, 36, ...])自动换算段码,见 [eg/shift-register-seven-segment.js。
LCD Controller(Andreas Haugstrup Pedersen):清单明确注明这是 LCD 构造函数的雏形(Became the basis for the LCD constructor!)。如今 LCD 已是 Johnny-Five 的一等组件,eg/lcd-runner.js 展示了 LCD 的完整用法——引脚映射、useChar() 载入自定义字符(runninga/runningb)、cursor(row, col).print() 定点输出、board.loop 实现动画:
var lcd = new five.LCD({ pins: [7, 8, 9, 10, 11, 12] }); // RS, EN, DB4-DB7
lcd.useChar("runninga");
lcd.useChar("runningb");
this.loop(300, function() {
lcd.clear().cursor(row, col).print(frames[frame ^= 1]);
});
底层原理:LCD 的实现位于 lib/lcd.js,源码中定义了一整套 HD44780 指令寄存器常量(REGISTER.DEFAULT),包括 CLEAR(0x01)、HOME(0x02)、ENTRY(0x04)、DISPLAY(0x08)、SETCGRAMADDR(0x40)、SETDDRAMADDR(0x80) 以及 4/8 位总线模式位(BITMODE)等——即对 LCD 控制器的底层命令封装,社区早期的手写实现正是被这套机制正式化。
Twitter 情感分析 LED(Sara Chipps):根据 Twitter 情感分析结果改变 LED 颜色,是"网络数据源 → 物理输出"的又一代表。
6WD Rover(Kelly Korevec):六轮小车,属于电机驱动主题,对应 docs/motor.md 与 eg/motor.js、eg/motobot.js(双电机差速小车)。
Medibot(Kelly Korevec):机器人作品,综合运用伺服与电机。
3.4 传感器与"机器 → 声/光"表达
Theremin(Tim Walker,sine5):用近距传感器 + JavaScript 合成实验性特雷门琴(距离 → 音高)。对应仓库 eg/proximity-hcsr04.js(超声波测距)与 eg/piezo-note-scale.js(音符/频率输出),把传感器读到的连续距离映射为可听频率——"感应 → 声音"的完整链路。
3.5 WebSocket 与可视化集成
Arduino + WebSocket + particles / CSS 变化(Jonathan Blanchet):三个子项目展示了"Arduino 数据 → 浏览器"的双向通道:
- WebSocket + particles:传感器数据驱动网页粒子效果;
- WebSocket + CSS 变化:数据实时改变页面样式;
- 电位器 + particles:电位器(电位器/旋转编码器)连续控制粒子系统。
对应仓库 eg/potentiometer.js(模拟量读取)。这类项目的共同点是以 Johnny-Five 为"硬件到 Node.js 的桥",再通过 WebSocket 把数据推给浏览器——参考仓库中的 eg/radar.js + eg/radar.html(浏览器端可视化)、eg/handclaw42.js + eg/handclaw42.html 等"Node + 网页"配对示例。
3.6 趣味游戏与活动项目
- Arduino Attack!(Richard Key):用 Arduino 制作的反应/射击游戏;
- Missile Command:见 3.1,物理发射器对战无人机;
- Typing Bot:见 3.2。
这些项目更强调"让代码跑在真实世界"的现场体验,是 Nodebots 社区文化(hackathon、JSConf、nodecopter 活动)的直接产物。
四、完整项目清单总表
以下按清单原顺序(新 → 旧)完整收录 awesome.md 的全部条目,并标注核心硬件/技术要素与仓库内对应示例:
| 作者 | 项目 | 核心硬件/技术要素 | 仓库对应示例 |
|---|---|---|---|
| Ricardo de Pena | Clawbot | 蓝牙小车 + 抓爪 + PS3 手柄 | eg/claw.js、eg/joystick-claw.js |
| Richard Key | Arduino Attack! | Arduino 游戏 | eg/button.js |
| Homeyer / Parrish / Boll | Missile Command | 舵机瞄准 + 橡皮筋发射器 | eg/servo-sweep.js |
| Sara Gorecki | Tri-color LED | 压力传感器 → RGB LED | eg/sensor-fsr.js、eg/led-rgb.js |
| Ravikumar / Hughes | Typing Bot | 高精度步进/舵机定位 | eg/stepper-sweep.js |
| Raquel Vélez | Manny the Manipulator | 二维串联机械臂 + 正逆运动学 | eg/servo-animation.js |
| Travis Thieman | Power Glove | 模拟手势输入 → 系统音量 | eg/sensor.js |
| Francis Gulotta | Dorby the DoorBot | 舵机驱动门把手 | eg/servo.js |
| Tim Walker | Theremin(sine5) | 近距传感器 → 音高 | eg/proximity-hcsr04.js |
| Tim Walker | CI 状态灯(cilite) | CI 结果 → RGB LED | docs/led-rgb.md |
| Kelly Korevec | Medibot | 伺服/电机综合 | eg/motobot.js |
| Irene Ros | Nunchuk 控制 AR Drone | Wii Nunchuk 摇杆 + 按键 | eg/nunchuk.js |
| Chris Williams | Nunchuk 控制 AR Drone | 同上(独立实现) | eg/nunchuk.js |
| Andreas Haugstrup Pedersen | LCD Controller | 首个 LCD 成功实现 → 成为 LCD 构造函数基础 | eg/lcd-runner.js、lib/lcd.js |
| Rebecca Murphey | Johnny-Five Projects / 移位寄存器 LED 计数器 | ShiftRegister + 七段/点阵显示 | eg/shift-register.js、eg/shift-register-seven-segment.js |
| Jonathan Blanchet | Arduino + WebSocket 系列 | WebSocket + particles / CSS / 电位器 | eg/radar.js、eg/potentiometer.js |
| Cole Gillespie | 摇杆控制街景 | Joystick → 浏览器地图视角 | eg/joystick.js |
| Kelly Korevec | 6WD Rover | 多电机驱动小车 | eg/motor.js |
| Sara Chipps | Twitter 情感 LED | 网络数据 → RGB LED | eg/led-rgb.js |
| Yusuf Çakmak | Leap Motion 控制 LED | 体感数据 → LED 颜色 | eg/led-rgb.js |
| Ibnu Triyono | SCARA Drawbot | 2 × SG90 舵机 + SCARA 机构 | eg/servo-animation-leg.js |
五、从清单反推 Johnny-Five 编程模型
把上面所有案例抽象掉硬件差异后,可以看到社区项目几乎都遵循同一套 Johnny-Five 编程模型:
- 初始化 Board:
new five.Board()自动发现并连接 IO 板; - 等待 ready 事件:硬件就绪后回调中创建组件实例;
- 组件即对象:
Servo、Joystick、LCD、ShiftRegister、Sensor等都是对底层引脚/总线协议的封装; - 事件驱动:
change、down/up/hold、read等事件构成输入侧的主要交互方式; - 工具函数:
five.Fn.scale / Fn.map承担"传感器区间 → 输出区间"的线性映射,是几乎所有案例共用的胶水。
从源码结构看,这套模型的组件层位于 lib/(如 lib/servo.js、lib/joystick.js、lib/lcd.js、lib/shiftregister.js、lib/sensor.js),入口统一从 lib/johnny-five.js 导出;测试方面,仓库 test/ 目录提供了组件行为验证(如 test/servo.js、test/lcd.js 等),可作为"组件 API 到底支持哪些参数与事件"的权威参考。
六、如何基于清单开始你的第一个 Nodebot
- 选型:从上面的表格里挑一个与手头硬件最匹配的项目(舵机类最易上手,
Servo只需一根 PWM 引脚); - 接线:参考
eg/示例注释与 docs/breadboard 下的面包板图(*.fzz/*.png),如 docs/servo.md、docs/joystick.md; - 运行:
node eg/<示例名>.js,观察 REPL 与串口日志; - 扩展:用
five.Fn.scale把任意传感器输入映射到你想要的输出(角度、颜色、音量、频率),即复刻清单中 80% 项目的思路。
提示:无人机、蓝牙手柄、Leap Motion 等清单项目依赖框架之外的硬件链路,仓库内的示例主要覆盖其中 Johnny-Five 负责的"传感器/执行器"部分;复现时需自行准备对应外设并参考其厂商协议。
结语
awesome.md 表面是一份作品榜单,实质是 Johnny-Five 组件能力矩阵的社区实证:从 2012 年的手写 LCD 驱动到如今的一行 new five.LCD(),从单舵机抓爪到带运动学的机械臂,这份清单记录了"JavaScript 驱动真实硬件"从验证到工程化的完整轨迹。对照仓库的 eg/ 示例与 lib/ 源码,你可以在十分钟内复现清单中最经典的一类 Nodebot,并以此为基础构建自己的作品。