Nodal CLI

AI-Powered Hardware Development Assistant for Arduino & ESP32

Nodal CLI is like Claude Code, but for hardware. It's an intelligent terminal interface that helps you develop, debug, and deploy Arduino and ESP32 projects using AI.

╔╗╔┌─┐┌┬┐┌─┐┬
║║║│ │ ││├─┤│
╝╚╝└─┘─┴┘┴ ┴┴─┘

AI-Powered Hardware Development Assistant
Arduino • ESP32 • Serial Monitor

Features

• AI-Powered Code Generation: Generate and modify Arduino/ESP32 sketches with natural language
• Intelligent Debugging: Analyze serial output and suggest fixes automatically
• Full Hardware Workflow: Compile, upload, and monitor - all in one place
• Real-Time Serial Monitor: Live serial output monitoring with timestamp tracking
• File System Integration: Read and write project files seamlessly
• Multi-Board Support: Arduino Uno, Nano, Mega, ESP32 variants, and more

Prerequisites

Required

• Node.js 18+ - Check with node --version
• OpenAI API Key - Free to get! First $5 of usage is free for new accounts
  • Get yours at: https://platform.openai.com/api-keys
  • Takes 2 minutes to sign up

Auto-Installed on First Run

• Arduino CLI - Automatically installed when you run Nodal for the first time

Installation

Option 1: Install from npm (Recommended)

# Install globally
npm install -g @nodalcli/cli

# Run nodal - first-time setup wizard will guide you!
nodal

# The setup wizard will:
# 1. Ask you to get an OpenAI API key (free!)
# 2. Auto-install Arduino CLI if not present
# 3. Save your configuration
# 4. Start the AI assistant!

That's it! The interactive setup wizard makes it super easy.

Option 2: Install from Source

For development or if you want to contribute:

# Clone the repository
git clone https://github.com/yourusername/nodal-cli.git
cd nodal-cli

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env and add your OpenAI API key

# Build the project
npm run build

# Run locally
npm start

# Or link for global use
npm link

Usage

Starting Nodal

If installed via npm:

# Navigate to your Arduino project directory
cd your-arduino-project

# Make sure you have a .env file with your OpenAI API key
# (or set OPENAI_API_KEY environment variable)

# Start Nodal
nodal

If running from source:

cd your-arduino-project
npm start  # from the nodal-cli directory

Nodal will start in your current directory and can read/write files relative to that location.

Example Workflows

1. Create a New Blink Sketch

You: Create a simple LED blink sketch for pin 13

Nodal: [Creates blink.ino file]

You: I'm using an Arduino Uno on /dev/ttyUSB0. Compile and upload it.

Nodal: [Compiles and uploads the sketch]

2. Debug Serial Output

You: Connect to /dev/ttyUSB0 at 9600 baud

Nodal: [Opens serial monitor - live output appears in right pane]

You: The sensor readings look wrong. Can you check the code?

Nodal: [Reads serial output, analyzes code, suggests fixes]

3. Create an ESP32 WiFi Project

You: Create an ESP32 sketch that connects to WiFi and hosts a web server

Nodal: I'll create that for you. First, what's your WiFi SSID and password?

You: SSID is "MyNetwork", password is "mypassword"

Nodal: [Creates sketch with WiFi configuration]

You: Compile this for ESP32 and upload to /dev/ttyUSB0

Nodal: [Compiles for ESP32 and uploads]

4. Work with Existing Project

You: Look at my project structure

Nodal: [Lists directory contents]

You: Read main.ino and explain what it does

Nodal: [Analyzes and explains the code]

You: Add temperature sensor support on pin A0

Nodal: [Modifies the sketch to add sensor support]

Available Commands

The AI can use these tools automatically:

File System

• fs_read_file(path) - Read file contents
• fs_write_file(path, contents) - Write or create files
• fs_list_dir(path) - List directory contents

Serial Communication

• serial_list_ports() - List available serial ports
• serial_connect(port, baud) - Connect to a port
• serial_read(port, numLines) - Read recent serial output
• serial_write(port, data) - Send data to device
• serial_close(port) - Close connection

Hardware Operations

• hw_compile(boardType, sketchPath) - Compile sketch
• hw_upload(boardType, port, sketchPath) - Upload to board
• hw_set_state(boardType, port, baud) - Save hardware config

Supported Board Types

• uno - Arduino Uno
• nano - Arduino Nano
• mega - Arduino Mega
• leonardo - Arduino Leonardo
• esp32 - ESP32 (generic)
• esp32-s2 - ESP32-S2
• esp32-s3 - ESP32-S3
• esp32-c3 - ESP32-C3
• Or use full FQBN (e.g., arduino:avr:uno)

Tips

1. First-time setup: Tell Nodal your board type and port once, it will remember
2. Serial debugging: Connect to serial before uploading to see output immediately
3. Compilation errors: Nodal will read the errors and suggest fixes automatically
4. Project exploration: Ask Nodal to explore your codebase before making changes
5. Best practices: Nodal knows Arduino/ESP32 best practices and will apply them

Troubleshooting

Arduino CLI not found

# Install arduino-cli (see Prerequisites section)
# Or set custom path in .env:
ARDUINO_CLI_PATH=/path/to/arduino-cli

Port permission denied (Linux)

sudo usermod -a -G dialout $USER
# Then log out and log back in

Compilation fails - core not installed

arduino-cli core update-index
arduino-cli core install arduino:avr  # or esp32:esp32, etc.

Can't find serial port

# List all ports
arduino-cli board list

# Or check system:
ls /dev/tty*  # Linux/Mac
# Look for ttyUSB*, ttyACM*, or cu.usbserial*

Project Structure

nodal/
├── src/
│   ├── components/       # React Ink UI components
│   │   ├── Header.tsx    # ASCII logo header
│   │   ├── ChatPane.tsx  # Main chat interface
│   │   └── SerialPane.tsx # Serial monitor display
│   ├── tools/            # LLM tool implementations
│   │   ├── fsTools.ts    # File system operations
│   │   ├── serialTools.ts # Serial communication
│   │   ├── hardwareTools.ts # Arduino CLI integration
│   │   └── index.ts      # Tool registry
│   ├── llm/              # LLM client
│   │   ├── client.ts     # OpenAI integration
│   │   └── systemPrompt.ts # System instructions
│   ├── types.ts          # TypeScript types
│   ├── store.ts          # Global state management
│   ├── App.tsx           # Main application
│   └── index.tsx         # CLI entry point
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

Development

# Install dependencies
npm install

# Run in development mode (auto-reload)
npm run dev

# Build for production
npm run build

# Run built version
npm start

Environment Variables

# Required
OPENAI_API_KEY=sk-...

# Optional
OPENAI_MODEL=gpt-4-turbo  # or gpt-4, gpt-3.5-turbo
ARDUINO_CLI_PATH=/custom/path/to/arduino-cli

License

MIT

Contributing

Contributions welcome! This is an early-stage project with lots of room for improvement.

Ideas for future features:

• Support for more hardware platforms (Raspberry Pi Pico, STM32, etc.)
• Library management integration
• Schematic/wiring diagram generation
• Oscilloscope/logic analyzer integration
• Multi-file project support
• Testing and simulation
• Hardware debugging tools (JTAG, SWD)

Acknowledgments

Inspired by Claude Code - bringing AI-powered development to hardware.

Built with:

• Ink - React for CLI
• OpenAI - AI capabilities
• Arduino CLI - Hardware tooling
• SerialPort - Serial communication