# Getting Started

**[🇷🇺 Русская версия](Getting-Started-RU.md)**

---

This guide will help you get OpenFlash up and running.

## Prerequisites

### Software
- Windows 10/11, macOS 10.15+, or Linux
- No additional drivers needed (uses native USB)

### Hardware (choose one)

**Microcontrollers:**
- **Raspberry Pi Pico** (RP2040) - Recommended for beginners, ~$4
- **Raspberry Pi Pico 2** (RP2350) - Enhanced performance, NV-DDR support, ~$5 (v2.3+)
- **STM32F4 Black Pill** (STM32F411) - Fastest MCU, ~$5 (v1.5+)
- **Arduino GIGA R1 WiFi** (STM32H747) - Enterprise features, WiFi, ~$60 (v2.3+)
- **Teensy 4.0/4.1** (NXP i.MX RT1062) - USB High Speed 480Mbps! ~$20-30 (v2.3.5+) ⚡
- **ESP32** - Wireless operation, ~$4 (v1.5+)
- **STM32F1 Blue Pill** (STM32F103) - Budget option, ~$2

**Single Board Computers (v2.3+):**
- **Raspberry Pi 3B+/4/5/Zero 2W** - Linux GPIO, headless server, ~$35-75
- **Orange Pi Zero 3/5** - Budget SBC option, ~$15-50
- **Banana Pi M2 Zero/M4 Berry/BPI-F3** - RPi alternative, RISC-V option! ~$15-35 (v2.3.5+) 🍌

### Flash Memory (supported types)
- **Parallel NAND** - Any ONFI-compliant chip, 8-bit data bus, 3.3V
- **SPI NAND** (v1.1+) - GigaDevice, Winbond, Macronix, Micron, Toshiba, XTX
- **eMMC** (v1.2+) - Samsung, Micron, SanDisk, Toshiba, Kingston

## Installation

### Option 1: Download Release (Recommended)

1. Go to [Releases](https://github.com/openflash/openflash/releases)
2. Download the installer for your OS:
   - Windows: `OpenFlash-x.x.x-setup.exe`
   - macOS: `OpenFlash-x.x.x.dmg`
   - Linux: `OpenFlash-x.x.x.AppImage` or `.deb`
3. Install and run

### Option 2: Build from Source

```bash
# Prerequisites
# - Rust 1.70+
# - Node.js 18+
# - Tauri prerequisites (see tauri.app)

git clone https://github.com/openflash/openflash.git
cd openflash/openflash/gui
npm install
cargo tauri build
```

## First Run (Without Hardware)

OpenFlash includes a mock device for testing:

1. Launch OpenFlash
2. Click **"Mock"** button
3. Select platform to simulate (RP2040, RP2350, STM32F4, Arduino GIGA, etc.)
4. Click **"Scan"** - you'll see "OpenFlash Mock Device"
5. Click **"Connect"**
6. Click **"Dump NAND"**
7. Explore the tabs: Hex View, Bitmap, Analysis, **AI**

## AI Analysis (v1.3+)

The new AI tab provides intelligent analysis of your dumps:

1. Load or dump data
2. Click the **"🤖 AI"** tab
3. View automatic analysis:
   - **Patterns** - Encrypted, compressed, executable, text regions
   - **Issues** - Bad blocks, bit errors, truncation warnings
   - **Recovery** - Suggested actions with success probability
   - **Tips** - Chip-specific recommendations

## Advanced Write Operations (v1.7+)

OpenFlash v1.7 adds full chip programming capabilities:

### Full Chip Programming
- Write entire chip with automatic verification
- Configurable retry count on failures
- Progress tracking with ETA

### Bad Block Management
- Automatic detection of factory bad blocks
- Runtime bad block tracking (erase/program failures)
- Transparent remapping to spare blocks
- Bad block table persistence

### Wear Leveling
- Per-block erase count tracking
- Remaining chip life estimation
- Hot/cold block identification
- Wear distribution statistics

### Incremental Backup
- Track only changed blocks since last backup
- Full and incremental backup chains
- Block-level checksums for change detection

### Chip Cloning
- Clone between compatible chips
- Three modes: Exact, Skip Bad Blocks, Wear-Aware
- Automatic block mapping with bad block handling

## Flashing Firmware

### Raspberry Pi Pico (RP2040)

1. Download `openflash-rp2040.uf2` from Releases
2. Hold BOOTSEL button on Pico
3. Connect USB while holding button
4. Pico appears as USB drive
5. Copy `.uf2` file to the drive
6. Pico reboots automatically

### STM32F4 (Black Pill) — v1.5+

1. Download `openflash-stm32f4.bin` from Releases
2. Flash using one of:
   - **DFU**: Hold BOOT0, connect USB, use `dfu-util`
   - **ST-Link**: Use `st-flash` or STM32CubeProgrammer
   - **probe-rs**: `probe-rs run --chip STM32F411CEUx`

### ESP32 — v1.5+

1. Download `openflash-esp32.bin` from Releases
2. Install `espflash`: `cargo install espflash`
3. Flash: `espflash flash openflash-esp32.bin`
4. For WiFi mode: connect to "OpenFlash-XXXX" AP

### STM32F103 (Blue Pill)

1. Download `openflash-stm32f1.bin` from Releases
2. Use ST-Link or USB-Serial adapter
3. Flash using `st-flash` or STM32CubeProgrammer

### Raspberry Pi Pico 2 (RP2350) — v2.3+

1. Download `openflash-rp2350.uf2` from Releases
2. Hold BOOTSEL button on Pico 2
3. Connect USB while holding button
4. Pico 2 appears as USB drive
5. Copy `.uf2` file to the drive
6. Pico 2 reboots automatically

### Arduino GIGA R1 WiFi (STM32H747) — v2.3+

1. Download `openflash-arduino-giga.bin` from Releases
2. Flash using one of:
   - **DFU**: Hold BOOT0, connect USB, use `dfu-util`
   - **probe-rs**: `probe-rs run --chip STM32H747XIHx`
   - **Arduino IDE**: Upload via USB (requires bootloader)
3. For WiFi mode: configure via USB serial or connect to "OpenFlash-GIGA" AP

### Raspberry Pi SBC — v2.3+

No firmware flashing needed - runs as Linux daemon:

```bash
# Install from crates.io
cargo install openflash-firmware-raspberry-pi

# Or build from source
cd openflash/firmware/raspberry_pi
cargo build --release

# Run as daemon (requires root for GPIO)
sudo ./target/release/openflash-gpio

# The daemon listens on Unix socket /tmp/openflash.sock
# Or TCP port 5000 for network access
```

### Orange Pi — v2.3+

Similar to Raspberry Pi:

```bash
# Install from crates.io
cargo install openflash-firmware-orange-pi

# Or build from source
cd openflash/firmware/orange_pi
cargo build --release

# Run as daemon (requires root for /dev/mem)
sudo ./target/release/openflash-gpio
```

### Teensy 4.0/4.1 — v2.3.5+ ⚡

The fastest option with USB High Speed (480 Mbit/s):

1. Download `openflash-teensy4.hex` from Releases
2. Install Teensy Loader from PJRC website
3. Press button on Teensy to enter bootloader
4. Use Teensy Loader to flash the firmware

Or via command line:
```bash
# Build firmware
cd openflash/firmware/teensy4
cargo build --release --target thumbv7em-none-eabihf --features teensy41

# Flash via teensy_loader_cli
teensy_loader_cli --mcu=TEENSY41 -w target/thumbv7em-none-eabihf/release/openflash-firmware-teensy4.hex
```

**Why Teensy 4.x?**
- 10-20x faster transfers (USB HS 480Mbps vs USB FS 12Mbps)
- 1GB dump in 3-5 minutes instead of 45 minutes!
- Teensy 4.1: SD card slot for autonomous operation

### Banana Pi — v2.3.5+ 🍌

Similar to Raspberry Pi and Orange Pi:

```bash
# Build from source
cd openflash/firmware/banana_pi
cargo build --release

# Run as daemon (requires root)
sudo ./target/release/openflash-gpio

# For network access
sudo ./target/release/openflash-gpio --tcp 0.0.0.0:5000
```

Supported boards:
- **M2 Zero** (Allwinner H3) - RPi Zero form factor
- **M4 Berry** (Allwinner H618) - RPi 4 alternative
- **BPI-F3** (SpacemiT K1) - RISC-V architecture!

## Network Devices (v2.3+)

Connect to SBC-based programmers (Raspberry Pi, Orange Pi, Banana Pi) over the network:

### Adding Network Device

1. Click **"Add Network Device"** button
2. Enter connection details:
   - **Name**: Friendly name (e.g., "Lab Pi 4", "Banana Pi F3")
   - **Address**: IP address or hostname
   - **Port**: Default 5000 for TCP
3. Click **"Add"**
4. Device appears in device list with network icon

### Connection Types

- **TCP**: `tcp://192.168.1.100:5000` - Standard network connection
- **Unix Socket**: `unix:///tmp/openflash.sock` - Local connection on same machine

### SBC Setup

On your Raspberry Pi, Orange Pi, or Banana Pi:

```bash
# Start daemon with network access
sudo openflash-gpio --tcp 0.0.0.0:5000

# Or Unix socket only (more secure)
sudo openflash-gpio --socket /tmp/openflash.sock
```



- [Hardware Setup](Hardware-Setup.md) - Wire up your NAND chip
- [Supported Chips](Supported-Chips.md) - Check if your chip is supported
- [Troubleshooting](Troubleshooting.md) - Common issues and solutions

## Scripting & Automation (v1.8+)

OpenFlash v1.8 adds powerful scripting and automation capabilities.

### Command-Line Interface (CLI)

Install the CLI tool and use OpenFlash from terminal:

```bash
# Scan for devices
openflash scan

# Detect connected chip
openflash detect

# Read full chip to file
openflash read -o dump.bin

# Write firmware with verification
openflash write -i firmware.bin --verify

# AI analysis with report export
openflash analyze dump.bin -o report.md

# Compare two dumps
openflash compare old.bin new.bin

# Batch processing
openflash batch jobs.toml

# List supported chips
openflash chips --interface spi-nand

# JSON output for scripting
openflash detect -f json
```

### Python API (pyopenflash)

Install the Python package:

```bash
pip install pyopenflash
```

Use in your scripts:

```python
import openflash

# Connect to device
device = openflash.connect()

# Detect chip
chip = device.detect()
print(f"Found: {chip.manufacturer} {chip.model} ({chip.capacity // 1024 // 1024}MB)")

# Read full dump
dump = device.read_full()
dump.save("dump.bin")

# AI analysis
analysis = openflash.ai.analyze(dump)
print(f"Quality: {analysis.quality_score:.0%}")
print(f"Patterns found: {len(analysis.patterns)}")

# Export report
analysis.export_report("report.md")

# Batch processing
batch = openflash.Batch()
read_id = batch.add_read("Read chip", "dump.bin")
analyze_id = batch.add_analyze("Analyze", read_id)
batch.add_report("Report", "report.md", analyze_id)
results = batch.run(device)
```

### Batch Processing

Create a TOML file for batch jobs:

```toml
# jobs.toml
[[jobs]]
name = "Read chip"
type = "read"
output = "dump.bin"

[[jobs]]
name = "Analyze dump"
type = "analyze"
depends_on = ["Read chip"]

[[jobs]]
name = "Export report"
type = "report"
output = "report.md"
depends_on = ["Analyze dump"]
```

Run with: `openflash batch jobs.toml`

### CI/CD Integration

Use OpenFlash in your CI pipelines:

```yaml
# GitHub Actions example
- name: Flash firmware
  run: |
    openflash write -i firmware.bin --verify
    openflash read -o verify.bin
    openflash compare firmware.bin verify.bin
```


## Multi-device & Enterprise (v2.0+)

OpenFlash v2.0 adds enterprise features for production environments.

### Server Mode

Start OpenFlash as a server for remote operation:

```bash
# Start server on default port 8080
openflash server start

# Start with custom configuration
openflash server start --host 0.0.0.0 --port 8080 --config server.toml

# Check server status
openflash server status --url http://localhost:8080
```

### Device Pool Management

Manage multiple OpenFlash devices:

```bash
# List all devices in pool
openflash device list

# Add a device to the pool
openflash device add --name "Programmer 1" --uri "serial:///dev/ttyUSB0" --platform RP2040

# Add device with tags
openflash device add --name "Production Line A" --uri "tcp://192.168.1.100:5000" --tags production,high-speed

# Remove device from pool
openflash device remove dev-001
```

### Job Queue

Submit and manage jobs across multiple devices:

```bash
# Submit a read job
openflash job submit read dump.bin

# Submit with specific device
openflash job submit write firmware.bin --device dev-002

# Submit with priority
openflash job submit analyze dump.bin --priority high

# Check job status
openflash job status 123

# List all jobs
openflash job list --status running

# Cancel a job
openflash job cancel 123
```

### Parallel Dumping

Use multiple devices for faster dumps:

```bash
# Parallel dump with 4 devices
openflash parallel-dump -o dumps/ --devices 4

# Custom chunk size
openflash parallel-dump -o dumps/ --devices 4 --chunk-size 64M

# Without merging (keep individual chunks)
openflash parallel-dump -o dumps/ --devices 4 --merge false
```

### Production Line Integration

Configure OpenFlash for production environments:

```bash
# Start production mode
openflash production start -c production.toml

# Check production status
openflash production status --line line-001
```

Example production configuration:

```toml
# production.toml
[line]
id = "line-001"
name = "Assembly Line A"
auto_start = true
verification = "full"

[[stations]]
id = "station-001"
name = "Flash Station"
device_id = "dev-001"

[[stations.operations]]
type = "detect_chip"
expected = "K9F1G08U0E"

[[stations.operations]]
type = "erase"
full = true

[[stations.operations]]
type = "program"
firmware_path = "/firmware/latest.bin"
verify = true

[pass_criteria]
max_bad_blocks = 20
max_ecc_corrections = 100
min_match_percent = 99.9
max_time_secs = 300

[logging]
enabled = true
log_dir = "./production_logs"
format = "json"
```

### REST API

Access OpenFlash via HTTP API:

```bash
# Get server status
curl http://localhost:8080/api/v1/status

# List devices
curl http://localhost:8080/api/v1/devices

# Submit job
curl -X POST http://localhost:8080/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{"name": "Read job", "job_type": "read", "params": {"output": "dump.bin"}}'

# Get job status
curl http://localhost:8080/api/v1/jobs/123
```

### WebSocket Real-time Updates

Connect to WebSocket for live updates:

```javascript
const ws = new WebSocket('ws://localhost:8080/ws');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'JobUpdate') {
    console.log(`Job ${msg.job_id}: ${msg.status} (${msg.progress}%)`);
  }
};

// Subscribe to job updates
ws.send(JSON.stringify({ type: 'Subscribe', job_ids: [123, 124] }));
```