Development Workflows Board Programming With Foundries Builds

Board Programming with Foundries.io Builds

This guide shows how to program Dynamic Devices boards using builds downloaded directly from Foundries.io using the fio-program-board.sh script.

Overview

The fio-program-board.sh script provides a comprehensive solution for:

• 🎯 Auto-Latest Target Selection - Automatically finds and uses the latest successful build
• 🏭 Default Factory Support - Uses fioctl's default factory configuration
• ⚡ One-Command Programming - Download and program with --program flag (no interactive wait)
• 🔄 Continuous Programming - Program multiple boards in sequence with --continuous flag
• 💾 Intelligent Caching - Skips re-downloading existing files for instant re-runs
• ⏱️ Performance Timing - Real-time download and programming time tracking per board
• 🔧 i.MX93 Optimization - Uses correct bootloader to prevent "image too large" errors
• 📁 Auto-Organization - Creates clean downloads/target-X-machine/ structure
• 🔒 Authentication Management - Comprehensive fioctl authentication checking
• 📋 Complete Artifact Management - Downloads MFGTools, UUU executables, bootloaders, system images

Quick Start

1. Initial Setup (One-time)

# Configure factory and default machine
./scripts/fio-program-board.sh --configure

This interactive setup will:

• Prompt for your Foundries.io factory name
• Let you select your default board type
• Test factory access and save configuration
• Create persistent settings for future use

2. Download Latest Build

# Download latest build for configured machine
./scripts/fio-program-board.sh

# Or specify target and machine explicitly
./scripts/fio-program-board.sh --factory dynamic-devices --machine imx93-jaguar-eink 1975

3. Program Your Board

# Navigate to download directory
cd downloads/target-1975-imx93-jaguar-eink/

# Put board in download mode, connect USB, then program
sudo ./program-imx93-jaguar-eink.sh --flash

4. Continuous Programming Mode (Multiple Boards)

For production scenarios where you need to program multiple boards:

# Start continuous programming mode
./scripts/fio-program-board.sh --machine imx93-jaguar-eink --continuous

# The script will:
# 1. Download the build once (cached for subsequent boards)
# 2. Program boards in sequence: Board #1, #2, #3...
# 3. Show individual timing for each board
# 4. Prompt between boards: "Program another board? (y/N)"
# 5. Track total boards programmed

Continuous Mode Benefits:

• 🔄 Batch Processing: Program multiple boards without re-downloading
• 📊 Individual Tracking: Shows timing and status for each board
• 🛡️ Error Recovery: Continue with next board if one fails
• 📈 Production Ready: Ideal for manufacturing and testing workflows

Supported Boards

Board	Machine Name	Platform	Description
Edge AI	imx8mm-jaguar-sentai	i.MX8MM	AI audio STT/TTS platform
Edge EInk	imx93-jaguar-eink	i.MX93	Low-power e-ink controller
Edge EV	imx8mm-jaguar-phasora	i.MX8MM	Energy management
Edge GW	imx8mm-jaguar-inst	i.MX8MM	Communications gateway

Detailed Usage

Download Script Options

./scripts/fio-program-board.sh [OPTIONS] [target-number] [machine] [output-dir]

Options:

• -f, --factory FACTORY - Foundries.io factory name (required)
• -m, --machine MACHINE - Machine/hardware type to download
• -o, --output DIR - Output directory
• -l, --list-targets - List available targets and exit
• -c, --configure - Interactive configuration setup
• --program - Automatically program board after download
• --continuous - Continuous programming mode for multiple boards
• --mfgfolder DIR - Custom folder containing boot firmware files
• --force - Force re-download even if files exist locally
• -h, --help - Show help message

Examples:

# List available targets
./scripts/fio-program-board.sh --factory dynamic-devices --list-targets

# Download specific target
./scripts/fio-program-board.sh --factory dynamic-devices --machine imx8mm-jaguar-sentai 1451

# Use configured defaults
./scripts/fio-program-board.sh 1975

# Download and program automatically
./scripts/fio-program-board.sh --factory dynamic-devices --machine imx8mm-jaguar-sentai 1451 --program

# Use custom boot firmware files
./scripts/fio-program-board.sh --factory dynamic-devices --machine imx8mm-jaguar-sentai 1451 --program --mfgfolder ./custom-boot-files

# Continuous programming mode with custom boot files
./scripts/fio-program-board.sh --factory dynamic-devices --machine imx8mm-jaguar-sentai --continuous --mfgfolder ./custom-boot-files

Programming Script Options

The generated programming script supports two modes:

# Full image programming (default) - bootloader + filesystem
sudo ./program-<machine>.sh --flash

# Bootloader only programming
sudo ./program-<machine>.sh --bootloader-only

# Show help
./program-<machine>.sh --help

What Gets Downloaded

Each download includes a complete programming package:

Core Artifacts

• Main System Image: lmp-factory-image-<machine>.wic.gz (400-500MB)
• Production Bootloader: imx-boot-<machine> (~1.6MB)
• Production U-Boot: u-boot-<machine>.itb (~1.3MB)
• Device Tree: <machine>.dtb (~50KB)
• Build Manifest: manifest.xml (build information)

MFGTools Package (~29MB)

• UUU Executables: Linux, Windows, macOS (ARM & x86)
• Programming Scripts: full_image.uuu, bootloader.uuu
• Manufacturing Images: imx-boot-mfgtool, u-boot-mfgtool.itb
• Manufacturing Kernel: fitImage-<machine>-mfgtool

Generated Files

• Programming Script: program-<machine>.sh (auto-generated)
• Cache Info: Metadata for future caching (planned feature)

Board Programming Process

Prerequisites

1. Software Requirements:

   • fioctl installed and authenticated (fioctl login)
   • Access to Foundries.io factory
   • sudo access for USB device programming

2. Hardware Setup:

   • Board powered OFF
   • DIP switches set to download/recovery mode
   • USB cable connected between board and computer

Step-by-Step Programming

1. Download Build:

   ./scripts/fio-program-board.sh --factory dynamic-devices --machine imx93-jaguar-eink

2. Prepare Board:

   • Set board to download/recovery mode (see board-specific instructions below)
   • Connect USB-C cable to programming port
   • Power ON the board

3. Program Board:

   cd downloads/target-<number>-<machine>/
   sudo ./program-<machine>.sh --flash

4. Complete Setup:

   • Wait for programming to complete (~3-5 minutes)
   • Set board back to normal boot mode
   • Power cycle the board
   • Board should boot to login prompt

Board-Specific Download Mode Instructions

Edge AI (imx8mm-jaguar-sentai)

• Set DIP switch SW1 to download mode position
• Connect USB-C cable to J7 (programming port)
• Power on via J6 or J8

Edge EInk (imx93-jaguar-eink)

• Set boot mode switches to download position
• Connect USB-C cable to programming port
• Power on the board

Edge EV (imx8mm-jaguar-phasora)

• Set DIP switches to download mode
• Connect USB-C programming cable
• Apply power

Edge GW (imx8mm-jaguar-inst)

• Configure boot mode for download
• Connect USB programming interface
• Power cycle the board

Troubleshooting

Common Issues

"Failure open usb device"

• Ensure board is in download mode
• Check USB cable connection
• Try running with sudo
• Verify USB drivers are installed

"fioctl authentication failed"

• Run fioctl login to re-authenticate
• Check factory name spelling
• Verify factory access permissions

"Target not found"

• Use --list-targets to see available targets
• Check target number is correct
• Ensure target exists for specified machine

Programming hangs or fails

• Verify board is in correct download mode
• Try different USB cable or port
• Check board power supply
• Ensure no other UUU processes are running

Debug Information

Check UUU tool detection:

./program-<machine>.sh --help
# Should show "Using extracted MFGTools UUU tool"

Verify downloaded files:

ls -la downloads/target-<number>-<machine>/
# Should show all required files including mfgtool-files directory

Test UUU manually:

cd downloads/target-<number>-<machine>/mfgtool-files-<machine>/
sudo ./uuu full_image.uuu

Advanced Usage

Custom Boot Firmware Files (--mfgfolder)

The --mfgfolder option allows you to use custom boot firmware files instead of the default ones from Foundries.io. This is useful for:

• Board-specific optimizations: Custom bootloader configurations
• Development testing: Testing new bootloader versions
• Recovery scenarios: Using known-good bootloader files
• Hardware bring-up: Custom firmware for new board revisions

Required files in custom folder:

• imx-boot-mfgtool - Manufacturing/recovery bootloader
• u-boot-mfgtool.itb - Manufacturing U-Boot image

Example usage:

# Create custom boot files directory
mkdir -p custom-boot-files

# Copy your custom files (replace with actual custom files)
cp /path/to/your/imx-boot-mfgtool custom-boot-files/
cp /path/to/your/u-boot-mfgtool.itb custom-boot-files/

# Download and program with custom boot files
./scripts/fio-program-board.sh --factory dynamic-devices --machine imx8mm-jaguar-sentai 1451 --program --mfgfolder custom-boot-files

How it works:

1. Downloads the standard Foundries.io build artifacts
2. Extracts the mfgtool-files package
3. Copies your custom boot files to override the defaults
4. Programs using the original UUU scripts with your custom boot firmware
5. Preserves all other artifacts (system image, device tree, etc.)

Custom Output Directory

./scripts/fio-program-board.sh --factory dynamic-devices --machine imx93-jaguar-eink 1975 --output /tmp/my-build

Bootloader-Only Programming

sudo ./program-<machine>.sh --bootloader-only

Use this when you only need to update the bootloader without touching the filesystem.

Multiple Board Programming

The downloaded artifacts can be used to program multiple boards of the same type:

# Download once
./scripts/fio-program-board.sh --factory dynamic-devices --machine imx93-jaguar-eink 1975

# Program multiple boards
cd downloads/target-1975-imx93-jaguar-eink/
sudo ./program-imx93-jaguar-eink.sh --flash  # Board 1
# (swap boards)
sudo ./program-imx93-jaguar-eink.sh --flash  # Board 2
# etc.

Integration with Development Workflow

CI/CD Integration

The script can be integrated into automated testing workflows:

# Download latest successful build
LATEST_TARGET=$(./scripts/fio-program-board.sh --factory dynamic-devices --list-targets | grep imx93-jaguar-eink | tail -1 | awk '{print $1}')
./scripts/fio-program-board.sh --factory dynamic-devices --machine imx93-jaguar-eink $LATEST_TARGET

Quality Assurance

For production programming:

1. Always verify target number matches expected release
2. Check manifest.xml for build information
3. Test boot on at least one board before batch programming
4. Keep programming logs for traceability

Comparison with Local Builds

Aspect	Foundries.io Download	Local Build
Speed	~5 minutes download	30-60 minutes build
Consistency	Identical to CI builds	May vary by environment
Dependencies	Only fioctl required	Full Yocto environment
Storage	~500MB per target	~50GB build environment
Reliability	Tested in CI	Depends on local setup
Artifacts	Complete MFGTools package	Manual artifact collection

Security Considerations

• Factory Access: Ensure proper access controls on Foundries.io factory
• Build Verification: Verify target numbers and manifest information
• USB Security: Be cautious when using sudo for USB access
• Network Security: Downloads occur over HTTPS with authentication

Next Steps

After successful board programming:

1. Verify Boot: Ensure board boots to login prompt
2. Network Setup: Configure WiFi or Ethernet connectivity
3. Application Deployment: Use Foundries.io for OTA app deployment
4. Monitoring: Set up device monitoring and management

For ongoing development, consider:

• Setting up automated target notifications
• Implementing caching for frequently used builds
• Creating custom programming workflows for your specific needs

Related Documentation

• Foundries.io Platform Overview
• fioctl Documentation
• Hardware-Reference-Edge-EInk-Board
• UUU Programming Tool Documentation