Build, run, inspect, and deploy robot behavior as typed visual workflows.
Blacknode connects robot hardware, perception, controllers, datasets, training, simulation, and deployment on one visual canvas. Start with a tested robot template, inspect live state, authorize a bounded action, and follow every result through run history and replay.
Workflows stay readable as systems grow: each node has typed ports, each connection is validated, and hardware-specific implementations remain behind stable robot capabilities.
A Blacknode robot workflow moves from task intent to physical hardware through explicit, replaceable layers:
Operator / application / agent
│
▼
Task skills and mission workflows
│
┌──────┴──────┐
▼ ▼
Perception Controllers + safety
│ │
└──────┬──────┘
▼
Robot profile, capabilities, calibration, and limits
│
▼
Transport adapters and ROS 2 integration
│
▼
Hardware drivers, cameras, buses, and the physical robot
│
└──────── live state and observations flow back up
| Layer | What it owns | Packages |
|---|---|---|
| Tasks and missions | Reusable robot skills, planning, confirmation, and orchestration | blacknode-skills, blacknode-agent |
| Perception | Cameras, tracking, VLMs, and spatial observations | blacknode-perception |
| Control and safety | Joint control, mobile bases, manipulation, policies, arbitration, limits, freshness checks, and stop paths | blacknode-controllers |
| Robot model | Robot profiles, capability contracts, calibration, discovery, and connection health | blacknode-robot |
| Integration | ROS 2 graph, topics, services, processes, native transport, and rosbridge | blacknode-ros2 |
| Hardware deployment | Runtime device contracts, capability inspection, safe device control, replaceable adapters, physical drivers, and firmware protocols | blacknode-hardware, blacknode-drivers |
| Learning and deployment | Episode recording, policy training, remote runtime, simulation, and accelerated compute | blacknode-dataset, blacknode-training, blacknode-runtime, blacknode-isaac, blacknode-cuda |
The workflow depends on stable capabilities such as a camera, joint controller, mobile base, or navigation interface. Robot profiles select the concrete providers, so compatible hardware or transport changes do not require mission logic to be rebuilt.
Typical graphs connect live robot state and camera observations to perception, task skills, bounded control, dataset recording, policy training, and deployment. Physical motion is disarmed by default and remains guarded by limits, freshness checks, explicit authorization, and safe shutdown paths.
Requires Python 3.11+ and Node.js 20.19+ or 22.12+.
git clone https://github.com/temiroff/Blacknode.git
cd Blacknode
.\start.bat # Windows./start.sh # macOS/Linux, from the cloned repositoryFirst run: Beginner Walkthrough · First robot: Project Lifecycle · SO-ARM101 Quickstart
Blacknode core provides the graph model, typed runtime, editor, package system, run replay, exports, and APIs. Robot capabilities live in focused extension packages with their own nodes, components, templates, and dependencies.
Install packages from the editor's Packages tab or the CLI:
blacknode packages install https://github.com/temiroff/blacknode-robot.gitTemplates declare required packages and Blacknode resolves missing capabilities. See Extension Packages.
For deployment on physical hardware, use
blacknode-hardware for
runtime hardware contracts, capability checks, safe device control, and
replaceable adapters. Add
blacknode-drivers for the
physical bus, firmware, or device protocol used by the robot.
On a new Raspberry Pi, Jetson, or Ubuntu device, install the complete hardware and deployment stack in one pass:
git clone https://github.com/temiroff/blacknode-runtime.git
cd blacknode-runtime
./install-device.shThis discovers every connected robot, asks for friendly names, installs the hardware services and shared runtime, configures active UFW rules, verifies the complete device, and prints the pairing checklist. Rerunning it preserves existing robot identities, calibrations, names, and the runtime token.
In the Blacknode editor, open Devices and select Add device. Automatic
SSH setup verifies the host key, authenticates only after confirmation, and
inspects the computer before changing it. The review shows the host OS and
Python, NVIDIA driver and CUDA toolkit, installed ROS 2 distributions, Docker
CLI/daemon state, existing Blacknode runtimes, and occupied runtime ports.
CUDA, ROS 2, and Docker system installations are preserved. Installation shows
live stage progress through package checks, download, isolated Python setup,
service installation, and pairing. If a Blacknode Runtime already exists,
choose to pair the healthy runtime, reinstall that instance, or install an
independent side-by-side instance. Side-by-side instances use separate
directories, state, pairing tokens, systemd services, and the next available
port from 8766 through 8865. The SSH installer upgrades older downloaded
service scripts in the new checkout when instance isolation support is needed
and verifies that runtimes and robot services which were already active remain
active after the side-by-side setup.
Runtime instances installed through the editor retain only their non-secret SSH management identity. Uninstall runtime asks for the SSH password again, removes the selected instance and its UFW rule, and leaves other runtime instances on the computer untouched. Remove from editor deletes only the local registration. Pause device first stops active deployments, stops and disarms attached robots, then stops that runtime service. Resume device starts the service and reconnects robot monitoring while keeping motion disarmed; previous deployments stay stopped until explicitly started again. Each lifecycle action shows stage progress. Each robot also has its own Pause robot and Resume robot controls. Robot Pause still sends the direct hardware stop when its deployment runtime is unavailable and reports that runtime address as a warning. The robot detail reports physical torque only when the hardware provider exposes it; otherwise it shows Not reported instead of inferring torque state from the motion-armed flag. For robots on SSH-managed computers, Restart robot service asks for the SSH password, resolves the exact hardware systemd unit from that robot's saved hardware port, and restarts only that unit. Restart is blocked while a deployment is active or the robot is armed. Blacknode then verifies that the same authenticated robot returned and keeps motion disarmed.
The installer detects each computer's current address; it does not hardcode a LAN IP. Use a router DHCP reservation or a resolvable hostname for robots that must keep a stable editor address.
Device records are local to the editor installation at
.blacknode/devices.json, which is excluded from Git. Pairing tokens remain in
the editor backend: API responses, workflows, and deployment artifacts refer to
the device ID and do not contain the token. Re-pair the same URL to replace a
rotated token or update the device name.
Plain HTTP protects access with the pairing token but does not encrypt network traffic. Use it only on a trusted local network; use HTTPS or a private VPN when the device is reachable through an untrusted network.
Open Deploy, select a paired device under Remote target, and select Check setup. It verifies the setup and, for a matching connected robot, activates the selected calibration while the device is disarmed. It does not start, arm, or move the robot. It checks:
- workflow structure and editor-side package resolution;
- authenticated device-service access and physical hardware connection;
- disarmed state;
- declared
metadata.required_capabilitiesagainst device capabilities; - calibration when a workflow declares the
joint_groupcapability; and - availability of the target runtime manifest.
Checks appear as pass, warning, failure, or pending. Install and start
blacknode-runtime on the target to validate its Python version, Blacknode
version, deployment features, required packages, and registered node types. If
preflight reports an indexed extension package as will install, staging
automatically clones it, installs its declared prerequisites, loads its nodes,
and verifies the target manifest before uploading the workflow.
When preflight reports Ready, choose:
- Stage to export and upload the workflow without starting it.
- Stage & run to upload it and explicitly start it on the device.
Blacknode hashes the exact validated graph. If the canvas changes before staging, the upload is rejected; select Validate again so a different graph cannot be deployed accidentally.
Remote deployments appear below the preflight report. Expand one to view its device log and use Run, Stop, Stage update, or Rollback. Stage update uploads the currently validated graph as another revision of that deployment. Rollback selects the previous revision without starting it; use Run after checking its state. A running deployment must be stopped before it can be updated or deleted. Every remote start rechecks that hardware is connected and disarmed.
The editor sends runtime requests through its backend, using the hardware and
runtime tokens stored in .blacknode/devices.json; the browser never receives
either token.
Existing Save local and Run local actions continue to operate on the
editor computer.
- Visual workflow editor: compose and inspect typed node graphs.
- Validated runtime: check ports, types, and graph structure before a run.
- Managed services: keep cameras, robot drivers, ROS processes, and controllers visible and stoppable.
- Replay and exports: inspect runs and save workflows as portable artifacts.
- Control APIs: operate workflows through MCP, HTTP, and WebSocket.
- Robot: SO-ARM101 · ROSBridge · Leader/follower · Datasets · Policy training
- Platform: Packages · Projects · Device deployment · Workflow schema · Custom nodes · MCP · Framework export
- Integrations: NVIDIA Agent Stack · CUDA · Docker · Python round-trip
- Development: Contributing · Repository guide
Blacknode is licensed under the Apache License 2.0. See LICENSE.