npm package: @nodalcli/cli
Description: AI copilot for building React web apps that control Arduino/ESP32 hardware - generates full-stack applications with React frontend, Node.js backend bridge, and firmware
Author: Gary Gao garygao@wharton.upenn.edu
Latest version: 1.15.0

# 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)

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
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
```bash
# Install arduino-cli (see Prerequisites section)
# Or set custom path in .env:
ARDUINO_CLI_PATH=/path/to/arduino-cli
```

### Port permission denied (Linux)
```bash
sudo usermod -a -G dialout $USER
# Then log out and log back in
```

### Compilation fails - core not installed
```bash
arduino-cli core update-index
arduino-cli core install arduino:avr  # or esp32:esp32, etc.
```

### Can't find serial port
```bash
# 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

```bash
# 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

```bash
# 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](https://github.com/anthropics/claude-code) - bringing AI-powered development to hardware.

Built with:
- [Ink](https://github.com/vadimdemedes/ink) - React for CLI
- [OpenAI](https://openai.com) - AI capabilities
- [Arduino CLI](https://arduino.github.io/arduino-cli/) - Hardware tooling
- [SerialPort](https://serialport.io/) - Serial communication