# Custom Hardware Definition (hwdef) Feature

## Overview
Support for aircraft-specific hardware modifications without forking ArduPilot.

## Main Features

### 1. Custom Hardware Definitions
Aircraft-specific hardware modifications without forking ArduPilot.

### 2. Git Version Management
Easy switching between stable releases, beta versions, and specific tags.

## Hardware Definition Files

### 1. **extra_hwdef_f4.dat / extra_hwdef_h7.dat**
   - **Purpose**: General feature stripping/adding for all boards of that MCU type
   - **Applies to**: All F4 or all H7/F7 boards
   - **Use case**: Flash optimization, common feature sets

### 2. **custom_hwdef_*.dat**
   - **Purpose**: Aircraft-specific one-off hardware modifications
   - **Applies to**: Single aircraft/use-case
   - **Use case**: Custom GPIO pins, unique sensor configs, per-aircraft hacks
   - **Naming**: `custom_hwdef_<aircraft>_<board>.dat`
   - **Example**: `custom_hwdef_cessna_matekf405.dat`

## Build Order
When building, hwdef files are applied in this order:
1. Base hwdef from ArduPilot repo (vanilla)
2. extra_hwdef (F4 or H7) - if selected
3. custom_hwdef - if specified

## Usage

### Method 1: Board List Files
Add custom hwdef to board entries in `my_boards_f4.txt` or `my_boards_h7.txt`:

```
# Standard entry (uses extra_hwdef only)
MatekF405-Wing-bdshot

# With custom hwdef for specific aircraft
MatekF405-Wing-bdshot:custom_hwdef_cessna_matekf405.dat
MatekF405-Wing-bdshot:custom_hwdef_easystar_matekf405.dat
```

Each line creates a separate build with different customizations.

### Method 2: Ad-hoc Build Mode
When using options 2-4 in the main menu:
1. Select boards
2. Choose extra hwdef (F4/H7/none)
3. **NEW**: Choose custom hwdef (or none)

The script will detect all `custom_hwdef_*.dat` files and offer them as options.

## Example

### Scenario
You have two aircraft with MatekF405-Wing-bdshot:
- Cessna: needs GPIO(90) on PA4 for camera trigger
- EasyGlider: needs GPIO(91) on PA4 for drop mechanism

### Solution

**custom_hwdef_cessna_matekf405.dat:**
```
# Cessna camera trigger
PA4 EXTERN_GPIO1 OUTPUT GPIO(90)
```

**custom_hwdef_easyglider_matekf405.dat:**
```
# Drop mechanism control
PA4 EXTERN_GPIO1 OUTPUT GPIO(91)
```

**my_boards_f4.txt:**
```
MatekF405-Wing-bdshot:custom_hwdef_cessna_matekf405.dat
MatekF405-Wing-bdshot:custom_hwdef_easyglider_matekf405.dat
```

Build option 1 now builds two firmware versions, each customized.

## Benefits
✅ Keep vanilla ArduPilot repo (no fork)
✅ No merge conflicts with upstream
✅ Track custom modifications per-aircraft
✅ Easy to maintain multiple aircraft configurations
✅ All custom files excluded from git via `.git/info/exclude`

## Files Ignored by Git
- `extra_hwdef*.dat`
- `custom_hwdef*.dat`
- `my_boards*.txt`
- `my_build.py`
- `build_logs/`
- `firmware_export/`

## Git Version Management

The build tool includes integrated git management for easy version switching.

### Main Menu Display
The main menu shows:
- Current git tag/branch
- Clean or dirty status (uncommitted changes)

### Git Management Menu (Option 7)

**Features:**
1. **Switch to latest stable** - Automatically finds and switches to newest stable release
2. **Switch to latest beta** - Switch to newest beta/RC version  
3. **List stable releases** - Browse the last 20 stable tags
4. **List beta releases** - Browse beta/RC versions
5. **Search & switch** - Search for specific tag patterns and switch
6. **Fetch tags** - Update tag list without switching

**Safety Features:**
- Warns if you have uncommitted changes before switching
- Auto-stashes changes if you proceed
- Updates submodules after switching
- Fetches latest tags before switching

**Example Workflow:**
```
Choice: 7                           # Enter git management

Current:
  Tag:    Copter-4.5.6             # Currently on stable
  Status: clean

Latest Available:
  Stable: Copter-4.5.7             # Newer version available
  Beta:   Copter-4.6.0-beta1

Options:
  1  Switch to latest stable       # Quick switch to 4.5.7
  2  Switch to latest beta         # Test 4.6.0-beta1
  ...
```

### Understanding ArduPilot Tags

**Tag Naming:**
- `Copter-4.5.6` - Release primarily for Copter (but works for all vehicles)
- `Plane-4.5.6` - Release primarily for Plane (but works for all vehicles)
- Tags are repo-wide: one tag covers all vehicle types

**Note:** Despite the vehicle name in the tag (Copter/Plane/Rover), you can build any vehicle type from any tag. The name just indicates which vehicle had the primary focus for that release.