Johnny-Five 社区 Nodebot 实战案例全解析:从 awesome.md 清单到可复现的机器人项目

原创2026-09-21 16:27:591,384 阅读
文章标签:IoT机器人嵌入式

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 演化史的一部分:社区先做出验证性实现,随后才被吸收进框架正式构造函数。

从信息组织方式看,这份清单的价值在于:

  1. 覆盖了 Johnny-Five 的核心组件面:Servo、Joystick、Nunchuk、LCD、ShiftRegister、LED、Proximity、Sensor 等;
  2. 展示真实硬件组合模式:如"摇杆 + 舵机""PS3 手柄 + 蓝牙 + 舵机""压力传感器 + 三色 LED""近距传感器 + 音调合成";
  3. 是入门者寻找"想复现的机器人"的第一手索引。

二、清单里的项目,仓库里都有对应代码:快速上手路径

awesome.md 中的大多数创意,都能在仓库 eg/ 示例目录里找到同主题的可运行代码;而组件的底层行为则在 lib/ 对应源文件中实现。上手路径如下:

  1. 克隆仓库并安装依赖:
git clone https://gitcode.com/gh_mirrors/jo/johnny-five
cd johnny-five
npm install
  1. 阅读 README.md 了解框架定位("The JavaScript Robotics Programming Framework")与 Board 初始化方式;
  2. 在 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 数据 → 浏览器"的双向通道:

  1. WebSocket + particles:传感器数据驱动网页粒子效果;
  2. WebSocket + CSS 变化:数据实时改变页面样式;
  3. 电位器 + 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 编程模型:

  1. 初始化 Board:new five.Board() 自动发现并连接 IO 板;
  2. 等待 ready 事件:硬件就绪后回调中创建组件实例;
  3. 组件即对象:Servo、Joystick、LCD、ShiftRegister、Sensor 等都是对底层引脚/总线协议的封装;
  4. 事件驱动:change、down/up/hold、read 等事件构成输入侧的主要交互方式;
  5. 工具函数: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

  1. 选型:从上面的表格里挑一个与手头硬件最匹配的项目(舵机类最易上手,Servo 只需一根 PWM 引脚);
  2. 接线:参考 eg/ 示例注释与 docs/breadboard 下的面包板图(*.fzz/*.png),如 docs/servo.md、docs/joystick.md;
  3. 运行:node eg/<示例名>.js,观察 REPL 与串口日志;
  4. 扩展:用 five.Fn.scale 把任意传感器输入映射到你想要的输出(角度、颜色、音量、频率),即复刻清单中 80% 项目的思路。

提示:无人机、蓝牙手柄、Leap Motion 等清单项目依赖框架之外的硬件链路,仓库内的示例主要覆盖其中 Johnny-Five 负责的"传感器/执行器"部分;复现时需自行准备对应外设并参考其厂商协议。

结语

awesome.md 表面是一份作品榜单,实质是 Johnny-Five 组件能力矩阵的社区实证:从 2012 年的手写 LCD 驱动到如今的一行 new five.LCD(),从单舵机抓爪到带运动学的机械臂,这份清单记录了"JavaScript 驱动真实硬件"从验证到工程化的完整轨迹。对照仓库的 eg/ 示例与 lib/ 源码,你可以在十分钟内复现清单中最经典的一类 Nodebot,并以此为基础构建自己的作品。

登录后查看全文
johnny-five