Module 0: The NHURO SDK & System Setup
Understanding the “Why” before the “How”
1. What is the NHURO SDK? (The Robot Brain Kit)
Think of the NHURO SDK as a “Starter Kit” for building a digital brain. Just like a smartphone has an SDK for building apps, our robot has an SDK for building human-like, autonomous behaviors.
- SDK (Software Development Kit): This is your toolbox. It contains pre-written code structures, ROS 2 nodes, and hardware wrappers needed to control the robot’s physical body without engineering low-level servo communication strings from scratch.
- Neuromorphic & Humanoid: “Humanoid” means the physical robot mimics a human shape. “Neuromorphic” means the computing system works like a biological brain—processing sensory events (like live voice streams) and acting on those events instantly.
Why do we use ROS 2? (The Social Network for Parts)
Imagine the robot’s hardware components as different people working in a laboratory room. ROS 2 (Robot Operating System 2) acts as their high-speed communication network or walkie-talkie channel:
- The Sensory Ear Bridge captures an audio chunk and broadcasts it.
- The Brain Node intercepts that audio stream and decodes the spoken word (“wave”).
- The Muscle Node catches the processed request and tells the physical arm to swing.
By using ROS 2, the robot becomes completely Modular—you can change or upgrade your sensory capture drivers without changing how your physical muscles move.
2. Navigating the Workspace (The Clean Golden Source Layout)
When you download the repository, it includes a clean repository root layout. To ensure local changes don’t cause clutter, strict .gitignore rules automatically block temporary logs, compilation cache folders, and large raw audio files from tracking.
Understanding your workspace folders is easy when you remember this rule:
- The Workshop (src/): This is where you sit and write code. You only care about modifying files inside this directory.
- The Factory (build/, install/, & log/): These are generated automatically by ROS 2 compilation tools. Never manually edit files here; your edits will be instantly overwritten the next time the workspace builds.
├── .gitignore ← Explicit rules file hiding build clutter and raw logs from Git
├── nhuro_prod_on ← Universal script to set up environment paths automatically
├── voice_bridge.py ← Local microphone audio streamer wrapper
└── nhuro_ws/ ← ROS 2 Workspace Directory
├── build/ & install/ & log/ ← IGNORE (Auto-generated by colcon)
└── src/ ← THE WORKSHOP (Your code lives here)
├── nhuro_interfaces/ ← Custom Interface Specification Package
│ ├── action/ Wave.action, Walk.action ← Target Action Goal Definitions
│ ├── CMakeLists.txt
│ └── package.xml
└── nhuro_driver/ ← Main Control Processing Package
├── setup.py
├── package.xml
└── nhuro_driver/
├── nhuro_unified_voice.py ← UNIFIED ENGINE (Asynchronous Brain & Muscle Hub)
├── voice_live_node.py
├── voice_parser_node.py
├── nhuro_action_node.py
└── nhuro/ (Low-Level Hardware Core Drivers)
├── robot.py ← Multi-joint movement sequencer
└── bus_servo.py ← TTL serial communication controller
3. The Single-Terminal Pipeline Architecture
While experimental testing allows isolating sensors, brains, and muscles across three separate terminals, production deployments utilize an asynchronous single-terminal infrastructure managed by nhuro_unified_voice.py. This approach provides robust multithreaded processing, prevents system dependency conflicts, and enables self-healing hardware channel discovery.
| Module Component | Thread / Processing Layer | Execution Logic & Safety Shielding |
|---|---|---|
| Sensory Audio Grabber | Main Execution Thread | Bypasses default routing and scans low-level sound architectures directly to locate and bind the physical string "USB Microphone". This circumvents application crashes if a temporary driver dropout occurs. |
| Brain NLP Engine | ROS 2 Executor Worker 1 | Intercepts incoming text data streams asynchronously via standard messaging topics. Translates raw strings into actionable structural meanings without blocking microphone capture tasks. |
| Muscle Action Server | ROS 2 Executor Worker 2 | Spun up inside an independent background worker loop. Manages serial timing to the physical servos. If an electrical surge or joint obstruction trips a servo, the muscle thread isolates the crash safely, keeping the audio listening loops up and alive for remote debugging. |
High-torque humanoid servo motors draw heavy current spikes when decelerating or locking positions. If the servos and the Raspberry Pi share common power traces, these spikes can trigger a brief voltage brownout, dropping your SSH connection or restarting the Pi. To guarantee uninterrupted runtimes during laboratory testing, always route power through an isolated dual-rail distribution circuit!
4. Getting the Code
Standard GitHub account passwords cannot be used for command-line authentication operations. Trying to clone with your password will result in an immediate
Invalid username or token error.
The Solution: You must log into your GitHub account via a web browser, go to Settings → Developer Settings → Personal Access Tokens (Classic), and generate a token with the repo checkbox selected. Use this generated token string as your terminal authentication key.
Method A: Online (Direct Lab GitHub Clone)
Use this method if your Raspberry Pi terminal is connected to the internet. Replace YOUR_PERSONAL_ACCESS_TOKEN with your copied token string.
git clone https://YOUR_PERSONAL_ACCESS_TOKEN@github.com/acsl-aizu/nhuro_project.git
Method B: Offline (Laboratory USB Deployment)
Use this method if working inside the isolated laboratory room with a pre-loaded USB flash drive.
5. Initializing, Building, and Running
To simplify compilation and environment configuration for students, the repository includes a universal activation script named nhuro_prod_on. This script automatically maps path layouts using universal variables, resolves package search rules, and loads the isolated compiler environment.
Follow these step-by-step commands in your terminal to initialize and execute the system pipeline:
-
Step 1: Enter the Project Folder
Navigate directly into your root repository project folder where the environmental scripts reside:cd ~/nhuro_project -
Step 2: Initialize Paths and Environment
Run the production onboarding utility script to automatically configure paths and load the isolated ROS 2 micromamba shell environment parameters:source ./nhuro_prod_on -
Step 3: Compile the Workspace
Move inside the ROS 2 workspace subdirectory and launch the colcon build engine with symlink mappings to compile your custom node modules:cd nhuro_ws
colcon build –symlink-install -
Step 4: Source Binaries and Execute the Unified System
Source your newly compiled installation environment setup file, and execute the core multithreaded unified voice control processing loop:source install/setup.zsh
python3 -m nhuro_driver.nhuro_unified_voice
Once started, the system will silence driver log spam, scan your USB bus, establish a live microphone stream, and stand by to parse spoken statements. Say the word “wave” into the microphone, and the muscle server will intercept your intent and trigger the physical arm movement sequences!