Skip to content

Getting Started

Jump to bottom
bobberdolle1 edited this page Jan 7, 2026 · 7 revisions

Getting Started

🇷🇺 Русская версия

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

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

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

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

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

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

# 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

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:

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

pip install pyopenflash

Use in your scripts:

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:

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

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

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

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

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

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

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

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

Example production configuration:

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

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

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] }));

Clone this wiki locally