Verify and add missing HSE defines to these targets

[ot0tot]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Find all F4 and G4 MCU targets and check for SYSTEM_HSE_MHZ define

echo "=== Scanning all F4 and G4 MCU targets ==="
echo ""

# Find all config.h files in configs directory
for config_file in configs/*/config.h; do
    if [ -f "$config_file" ]; then
        # Extract target name from path
        target_name=$(echo "$config_file" | sed 's|configs/\(.*\)/config.h|\1|')
        
        # Check if it's an F4 or G4 MCU
        mcu_type=$(grep -E "^\s*#define\s+TARGET_MCU\s+" "$config_file" | awk '{print $3}')
        
        if [[ "$mcu_type" =~ STM32F4 ]] || [[ "$mcu_type" =~ STM32G4 ]]; then
            # Check if SYSTEM_HSE_MHZ is defined (case insensitive)
            has_hse=$(grep -i "^\s*#define\s\+SYSTEM_HSE_MHZ\s\+" "$config_file")
            
            if [ -z "$has_hse" ]; then
                echo "❌ MISSING: $target_name (MCU: $mcu_type)"
            else
                hse_value=$(echo "$has_hse" | awk '{print $3}')
                echo "✓ HAS: $target_name (MCU: $mcu_type, HSE: ${hse_value}MHz)"
            fi
        fi
    fi
done

echo ""
echo "=== Summary ==="
echo "Targets with F4/G4 MCUs missing SYSTEM_HSE_MHZ:"
for config_file in configs/*/config.h; do
    if [ -f "$config_file" ]; then
        target_name=$(echo "$config_file" | sed 's|configs/\(.*\)/config.h|\1|')
        mcu_type=$(grep -E "^\s*#define\s+TARGET_MCU\s+" "$config_file" | awk '{print $3}')
        
        if [[ "$mcu_type" =~ STM32F4 ]] || [[ "$mcu_type" =~ STM32G4 ]]; then
            has_hse=$(grep -i "^\s*#define\s\+SYSTEM_HSE_MHZ\s\+" "$config_file")
            
            if [ -z "$has_hse" ]; then
                echo "  - $target_name ($mcu_type)"
            fi
        fi
    fi
done

Length of output: 108

---

🏁 Script executed:

#!/bin/bash
# Let's see what MCU types are actually defined and check the pattern

echo "=== Checking all TARGET_MCU definitions ==="
echo ""

# Check all config.h files for TARGET_MCU
for config_file in configs/*/config.h; do
    if [ -f "$config_file" ]; then
        target_name=$(echo "$config_file" | sed 's|configs/\(.*\)/config.h|\1|')
        mcu_line=$(grep "define.*TARGET_MCU" "$config_file")
        if [ -n "$mcu_line" ]; then
            echo "$target_name: $mcu_line"
        fi
    fi
done | head -20

echo ""
echo "=== Checking BETAFPVG473_V2 specifically ==="
cat configs/BETAFPVG473_V2/config.h

echo ""
echo "=== Count of MCU types ==="
for config_file in configs/*/config.h; do
    if [ -f "$config_file" ]; then
        grep "define.*TARGET_MCU" "$config_file" | awk '{print $3}'
    fi
done | sort | uniq -c | sort -rn

Length of output: 4138

---

🏁 Script executed:

#!/bin/bash
# Find all F4 and G4 MCU targets and check for SYSTEM_HSE_MHZ define (corrected)

echo "=== Scanning F4 and G4 MCU targets for SYSTEM_HSE_MHZ ==="
echo ""

missing_targets=()
has_hse_targets=()

# Find all config.h files in configs directory
for config_file in configs/*/config.h; do
    if [ -f "$config_file" ]; then
        # Extract target name from path
        target_name=$(echo "$config_file" | sed 's|configs/\(.*\)/config.h|\1|')
        
        # Check if it's an F4 or G4 MCU (using FC_TARGET_MCU)
        mcu_type=$(grep "define.*FC_TARGET_MCU" "$config_file" | awk '{print $3}')
        
        if [[ "$mcu_type" =~ STM32F4 ]] || [[ "$mcu_type" =~ STM32G4 ]]; then
            # Check if SYSTEM_HSE_MHZ is defined
            has_hse=$(grep "^\s*#define\s\+SYSTEM_HSE_MHZ\s\+" "$config_file")
            
            if [ -z "$has_hse" ]; then
                echo "❌ MISSING: $target_name (MCU: $mcu_type)"
                missing_targets+=("$target_name ($mcu_type)")
            else
                hse_value=$(echo "$has_hse" | awk '{print $3}')
                has_hse_targets+=("$target_name ($mcu_type, HSE: ${hse_value}MHz)")
            fi
        fi
    fi
done

echo ""
echo "=== SUMMARY ==="
echo ""
echo "F4/G4 targets WITH SYSTEM_HSE_MHZ: ${#has_hse_targets[@]}"
echo "F4/G4 targets MISSING SYSTEM_HSE_MHZ: ${#missing_targets[@]}"
echo ""

if [ ${#missing_targets[@]} -gt 0 ]; then
    echo "Targets missing SYSTEM_HSE_MHZ define:"
    printf '%s\n' "${missing_targets[@]}"
fi

echo ""
echo "=== Sample of targets WITH HSE defined ==="
printf '%s\n' "${has_hse_targets[@]}" | head -10

Length of output: 3826

---

@ot0tot: I've completed a comprehensive scan of all F4 and G4 MCU targets in the repository. Here are the findings:

Summary

Total F4/G4 targets: 270

• ✅ With SYSTEM_HSE_MHZ defined: 221 targets
• ❌ Missing SYSTEM_HSE_MHZ: 49 targets

Targets Missing SYSTEM_HSE_MHZ

STM32G47X (G4) - 9 targets missing:

1. AIRBOTG4AIO
2. GEPRC_TAKER_G473AIO
3. KAKUTEG4AIO
4. LUXHDAIO-G4
5. LUXMICROAIO
6. MAMBAG4
7. NUCLEOG474
8. SUB250_REDFOX_G473AIO
9. TAKERG4AIO

STM32F405 (F4) - 28 targets missing:

ACCIF405, AIKONF4V2, ALIENFLIGHTF4, CADDXF4, CADDX_PROTOS_F4, CYCLONEF405_PRO, DAKEFPVF405, DREAMFLYF405, EAGLEF405, FF_RACEPIT, FF_RACEPIT_MINI, FLAOF405X8, FLYCOLORF4, HAKRCF405V2, HGLRCF405V2, MAMBAF405US, MAMBAF405US_I2C, MAMBAF405_2022A, MAMBAF405_2022B, NEUTRONRCF407, OMNIBUSF4NANOV7, RUSRACE_F4, SKYSTARSF405AIO, STELLARF4, STELLARF4V2, TCMM405V3, VGOODRCF405_DJI

STM32F411 (F4) - 11 targets missing:

ATOMRCF411, FLYWOOF411_5IN1_AIO, FOSSF4ELRS, GEELANGF411, GEPRCF411SX1280, HAKRCF411D, JHEF411HD, MAMBAF411, NEUTRONRCF411AIO, NEUTRONRCF411SX1280, TCMMF411, VGOODRCF411_DJI

STM32F446 (F4) - 1 target missing:

NUCLEOF446

Note

This PR correctly adds the SYSTEM_HSE_MHZ define to BETAFPVG473_V2. Would you like me to help track these other 48 missing targets by creating an issue for follow-up?

---

🧠 Learnings used

Learnt from: osirisinferi
Repo: betaflight/config PR: 0
File: :0-0
Timestamp: 2025-12-27T17:15:05.111Z
Learning: For Betaflight board configuration reviews, when analyzing TIMER_PIN_MAPPING definitions in config.h files, perform a comprehensive verification by: (1) Clone or access the betaflight/betaflight repository and look up each pin's timer definitions from the appropriate timer_stm32*.c file (e.g., timer_stm32h7xx.c for STM32H743, timer_stm32f4xx.c for STM32F405, etc.). (2) For each TIMER_PIN_MAP entry, verify that the timer occurrence index specified actually exists in the timer definition file for that pin. Non-existent occurrences will cause build or runtime errors. (3) Check if any timer occurrence being used is a complementary channel (ending in "N" like TIM1_CH2N, TIM8_CH3N). Complementary channels are not suitable for motor/servo control and must not be actively selected. (4) Verify that each timer channel uses a unique DMA index on MCUs with DMAMUX (like STM32H7). For MCUs without DMAMUX (like STM32F4/F7), verify non-conflicting DMA stream requests according to the appropriate DMA request mapping for that platform. Use sequential indices (0,1,2,3,4,5,6,7...) with -1 reserved only for pins that don't require DMA. (5) Verify that LED_STRIP_PIN has a valid DMA index (not -1) on platforms with DMAMUX, because WS2812/addressable LEDs require DMA for timing-critical operations. (6) Check that all defined CLKIN pins (like GYRO_1_CLKIN_PIN, GYRO_2_CLKIN_PIN) are included in the TIMER_PIN_MAPPING with appropriate timer occurrence and DMA -1. This systematic verification must be performed for all new or modified TIMER_PIN_MAPPING definitions before approval.

---

Learnt from: haslinghuis
Repo: betaflight/config PR: 0
File: :0-0
Timestamp: 2025-12-30T20:09:11.644Z
Learning: For Betaflight board configuration reviews, F411 MCU, SPI-based RX, and BMI270 gyro are deprecated platforms as of September 16, 2024. New target submissions using these should be flagged.

---

Learnt from: haslinghuis
Repo: betaflight/config PR: 0
File: :0-0
Timestamp: 2025-12-30T20:09:11.644Z
Learning: For Betaflight board configuration reviews, maintainer information must be included in target submissions according to the Requirements for Submission of New and Updated Targets.

---

Learnt from: haslinghuis
Repo: betaflight/config PR: 0
File: :0-0
Timestamp: 2025-12-30T20:09:11.644Z
Learning: For Betaflight board configuration reviews, the manufacturer must be registered in the Manufacturers.md file. Always verify that the MANUFACTURER_ID in config.h has a corresponding entry in Manufacturers.md.

---

Learnt from: osirisinferi
Repo: betaflight/config PR: 0
File: :0-0
Timestamp: 2025-12-30T21:01:01.473Z
Learning: For Betaflight board configuration reviews, when blocking issues are identified after an initial approval, immediately dismiss/withdraw the approval by using `gh pr review <PR_NUMBER> --repo betaflight/config --request-changes --body "<reason>"` to change the review state to CHANGES_REQUESTED. This actively manages approval status to ensure it accurately reflects the current mergability state of the PR.

---

Learnt from: osirisinferi
Repo: betaflight/config PR: 0
File: :0-0
Timestamp: 2025-12-30T21:03:53.169Z
Learning: For Betaflight board configuration reviews, schematics are mandatory for the overall review process according to the Config Target Guidance, but they do NOT need to be provided publicly in the GitHub PR itself. Schematics review is conducted through a separate/private channel. Do not flag "missing schematics in PR" as a blocking issue.

---

Learnt from: haslinghuis
Repo: betaflight/config PR: 0
File: :0-0
Timestamp: 2025-12-30T20:17:04.545Z
Learning: For Betaflight board configuration reviews, hardware design must follow the Manufacturer Design Guidelines: proper power regulation with good ground/power planes and decoupling, redundant solder pads or castellations for durability, oversized mounting holes for M3 stack robustness, clear silkscreen pin labels and revision marking, and high-speed signals routed away from noisy power traces.

---

Learnt from: haslinghuis
Repo: betaflight/config PR: 0
File: :0-0
Timestamp: 2025-12-30T20:09:11.644Z
Learning: For Betaflight board configuration reviews, schematics are mandatory for all new target submissions. Submissions without schematics for review should be rejected according to the Config Target Guidance.

---

Learnt from: haslinghuis
Repo: betaflight/config PR: 0
File: :0-0
Timestamp: 2025-12-30T20:09:11.644Z
Learning: For Betaflight board configuration reviews, STM32 F4 and F7 based designs with more than 4 motor outputs are not accepted for new submissions after December 3, 2024. This is an official timeline restriction from the Config Target Guidance.

---

Learnt from: haslinghuis
Repo: betaflight/config PR: 0
File: :0-0
Timestamp: 2025-12-30T20:09:11.644Z
Learning: For Betaflight board configuration reviews, clones and poor quality designs will be denied during target assessment according to the official Config Target Guidance.

Originally posted by @coderabbitai[bot] in #1007 (comment)

[haslinghuis]

@coderabbitai create a PR for F4xx and G47x targets missing the SYSTEM_HSE_MHZ define.

For consideration - should this be handled at target level in firmware instead ?

[ot0tot]

We need to confirm these FCs have an HSE before merging. I assume most do, but don't have the actual hardware to confirm.

Edit: Or we could just add it to all and revert if we get complaints 🤔

[coderabbitai]

Coding Plan

Approach

Investigate the 49 STM32F4 and STM32G4 targets missing SYSTEM_HSE_MHZ defines to determine if action is needed. SYSTEM_HSE_MHZ specifies the external oscillator frequency for clock configuration. However, firmware has fallback behavior, and evidence suggests some boards function correctly without explicit defines. Adopt a reactive approach: document best practices and only update configs with confirmed issues.

Observations

The betaflight/config repository stores per-target configuration files (config.h) that define hardware-specific settings for flight controller boards. Each config.h contains preprocessor defines including FC_TARGET_MCU (microcontroller type), peripheral pin assignments, sensor configurations, and clock settings like SYSTEM_HSE_MHZ. These configs integrate into the betaflight firmware build system where the defines control driver inclusion and hardware initialization. The repository contains 270+ F4/G4 targets, with 221 defining SYSTEM_HSE_MHZ (predominantly 8MHz), while 49 targets lack this define. User feedback indicates at least one target (AIRBOTG4AIO) functions correctly without the define.

Assumptions

Assumption 1: Should we proactively add SYSTEM_HSE_MHZ to all 49 missing targets or adopt a reactive approach?

Options Considered:

• Proactive: Add SYSTEM_HSE_MHZ to all 49 targets based on manufacturer patterns (original ticket approach)
• Reactive: Document best practices and only update targets with confirmed clock-related issues
• Hybrid: Add to high-risk targets (non-8MHz boards) only, document the rest
• Do nothing: Accept current state since firmware has fallback behavior

Chosen Option: 2

Rationale: Web search confirms firmware falls back to HAL defaults (typically 8MHz for F4, varies for G4) when SYSTEM_HSE_MHZ is undefined. Since 97% of existing configs use 8MHz and AIRBOTG4AIO works without the define, the fallback behavior likely matches most hardware. The risk of introducing incorrect values through assumptions is higher than the current state. Focus on documentation and targeted fixes for reported issues.

Assumption 2: How do we determine which targets actually need SYSTEM_HSE_MHZ added?

Options Considered:

• Add to all targets where manufacturer pattern suggests non-8MHz value
• Add only when users report clock-related issues (UART timing, system instability, boot failures)
• Add based on MCU family (G4 has wider HSE range, may need explicit values)
• Research each board's schematic/datasheet to verify actual HSE frequency

Chosen Option: 2

Rationale: Since firmware fallbacks work for most cases, only targets with confirmed problems need immediate action. This aligns with "fix it if issues arise" guidance and avoids potentially incorrect assumptions. Documentation will guide users on how to add SYSTEM_HSE_MHZ if they encounter clock issues.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Investigation and Assessment

Investigate whether any of the 49 missing targets have reported issues and understand firmware fallback behavior to inform the decision on which targets (if any) need updates.

Task 1: Survey for reported issues

Search for existing issue reports, discussions, or user complaints related to clock configuration problems on the 49 missing targets.

• Search betaflight/betaflight and betaflight/config GitHub issue trackers for mentions of the 49 target names combined with keywords: "clock", "HSE", "UART timing", "boot failure", "system instability"
• Check betaflight Discord, forum archives, or community channels for troubleshooting threads mentioning these targets
• Document any confirmed clock-related issues by target name, symptoms reported, and whether adding SYSTEM_HSE_MHZ resolved the issue
• If no issues found, document that absence as evidence the current state is acceptable

Task 2: Analyze firmware fallback behavior

Understand what happens in betaflight firmware when SYSTEM_HSE_MHZ is not defined for F4 and G4 targets.

• Review web search findings: firmware falls back to HAL defaults (HSE_VALUE, typically 8MHz for F4) or internal oscillator (HSI)
• Identify if fallback behavior differs between STM32F4xx and STM32G4xx families
• Document when fallback is safe (hardware HSE matches default) vs problematic (hardware HSE differs from default)
• Note that most boards use 8MHz HSE (97% from exploration), so 8MHz fallback likely matches most hardware
• Explain why AIRBOTG4AIO and similar targets work without explicit SYSTEM_HSE_MHZ define

Task 3: Categorize targets by risk level

Classify the 49 targets into risk categories to prioritize any necessary actions.

• Create risk categories: High (known non-8MHz boards from manufacturer patterns like AERO boards), Medium (G4 targets with wider HSE range), Low (F4 targets from manufacturers consistently using 8MHz)
• Use manufacturer pattern analysis from exploration (AERO→16MHz, BOTWING→24MHz are exceptions; most manufacturers→8MHz)
• Document: For each target, note manufacturer, likely HSE value based on patterns, risk level, and rationale
• Flag that most targets are likely low-risk since 8MHz fallback probably matches hardware

🤖 Prompt for AI agents

Phase 1: Investigate the 49 missing targets to determine if any require
immediate action by surveying for reported issues and understanding firmware
fallback behavior.

Survey for reported issues:
- Search betaflight GitHub issue trackers for the 49 target names with
clock-related keywords ("clock", "HSE", "UART timing", "boot failure", "system
instability")
- Check community channels (Discord, forums) for troubleshooting threads
- Document any confirmed clock-related issues with symptoms and resolutions
- Document absence of issues as evidence current state is acceptable

Analyze firmware fallback behavior:
- Review firmware HAL defaults (typically 8MHz for F4, varies for G4)
- Identify differences between STM32F4xx and STM32G4xx fallback behavior
- Document when fallback is safe vs problematic
- Explain why targets like AIRBOTG4AIO work without SYSTEM_HSE_MHZ

Categorize targets by risk:
- Create categories: High (non-8MHz boards), Medium (G4 with wider HSE range),
Low (F4 with 8MHz patterns)
- Use manufacturer patterns: AERO→16MHz, BOTWING→24MHz (exceptions); most→8MHz
- Document each target's manufacturer, likely HSE value, risk level, and
rationale

Phase 2: Decision and Strategy

Determine the appropriate action based on investigation findings—whether to update configs, focus on documentation, or maintain status quo.

Task 1: Create decision framework

Establish clear criteria for when SYSTEM_HSE_MHZ should be added to a target config.

• Define triggering conditions: (1) User reports clock-related issues on specific target, (2) Manufacturer pattern strongly indicates non-8MHz HSE (e.g., AERO boards), (3) New target submission with known non-standard HSE
• Document when it's acceptable to omit SYSTEM_HSE_MHZ: firmware fallback matches hardware HSE (typically 8MHz)
• Create troubleshooting workflow: user symptoms → suspect clock issue → verify HSE frequency → add SYSTEM_HSE_MHZ if mismatch
• Recommend adding SYSTEM_HSE_MHZ to new target submissions as best practice, even if fallback would work

Task 2: Identify targets requiring immediate action

Based on investigation, determine which (if any) of the 49 targets need config updates now vs later.

• List targets with confirmed reported issues from Task 1.1 (likely zero or very few)
• List high-risk targets from Task 1.3 with known non-8MHz patterns (e.g., any AERO-prefixed boards in the 49)
• For all other targets, recommend "wait and see" approach—document the gap but don't preemptively add values
• If investigation finds zero targets needing immediate action, document that conclusion and pivot fully to documentation-focused solution

🤖 Prompt for AI agents

Phase 2: Establish decision framework and identify which targets (if any) need
immediate config updates based on Phase 1 investigation.

Create decision framework:
- Define triggering conditions: user-reported issues, manufacturer patterns
indicating non-8MHz HSE, new submissions with non-standard HSE
- Document when omitting SYSTEM_HSE_MHZ is acceptable: firmware fallback matches
hardware (typically 8MHz)
- Create troubleshooting workflow: symptoms → suspect clock issue → verify HSE →
add define if mismatch
- Recommend adding SYSTEM_HSE_MHZ as best practice for new submissions

Identify targets needing immediate action:
- List targets with confirmed issues from Phase 1 survey
- List high-risk targets with non-8MHz patterns (e.g., AERO-prefixed boards)
- Recommend "wait and see" for remaining targets
- If zero targets need action, document conclusion and pivot to
documentation-only solution

Phase 3: Documentation and Guidance

Update repository documentation to explain SYSTEM_HSE_MHZ purpose, when it's required, and how to troubleshoot clock issues.

Task 1: Add SYSTEM_HSE_MHZ best practices section

Create comprehensive guidance in README.md explaining clock configuration.

• Add new section titled "Clock Configuration (SYSTEM_HSE_MHZ)" after existing "Target Pin Mappings" section
• Explain what SYSTEM_HSE_MHZ defines (external high-speed oscillator frequency in MHz)
• Document firmware fallback behavior: defaults to HAL HSE_VALUE (typically 8MHz for F4) when undefined
• Clarify when it MUST be defined: board uses non-8MHz HSE (16MHz, 24MHz, 25MHz)
• Clarify when it's OPTIONAL: board uses 8MHz HSE and can rely on firmware fallback (though explicit definition is better practice)
• List standard values: 8MHz (default/most common), 16MHz (some designs), 24-25MHz (rare high-performance boards)
• Explain how to determine correct value: check board schematic, verify crystal/oscillator marking, match manufacturer patterns from existing configs
• Warn about consequences of incorrect values: system instability, UART timing errors, peripheral malfunction, boot failures

Task 2: Add clock troubleshooting guide

Document how users should diagnose and fix clock-related issues.

• Create troubleshooting section in README.md under "Common Issues" or similar
• List symptoms of incorrect clock configuration: UART communication failures, erratic behavior, boot loops, peripheral timing issues
• Provide diagnostic steps: (1) Check if target has SYSTEM_HSE_MHZ defined, (2) Verify physical board crystal/oscillator markings, (3) Check manufacturer's other boards for HSE patterns
• Document fix procedure: Add #define SYSTEM_HSE_MHZ <value> to config.h with correct frequency
• Include reference to manufacturer pattern table (from Task 3.3)
• Note that most boards use 8MHz and firmware fallback often works, but explicit definition prevents ambiguity

Task 3: Document manufacturer HSE patterns

Add reference table showing manufacturer consistency in HSE usage.

• Create table in README.md showing common manufacturers and their typical HSE frequencies
• Include examples: GEPRC→8MHz, HGLRC→8MHz, MAMBA→8MHz, HAKRC→8MHz, NEUTRONRC→8MHz, AERO→16MHz, BOTWING→24MHz
• Note that manufacturer consistency is very strong (150+ manufacturers use single HSE value across all boards)
• Recommend checking existing configs from same manufacturer when adding new targets or troubleshooting issues
• Include the 49 missing targets as examples where fallback likely works due to 8MHz standard

🤖 Prompt for AI agents

Phase 3: Create comprehensive documentation for SYSTEM_HSE_MHZ configuration,
troubleshooting, and manufacturer patterns.

Add best practices section to README.md:
- Add "Clock Configuration (SYSTEM_HSE_MHZ)" section after "Target Pin Mappings"
- Define SYSTEM_HSE_MHZ: external high-speed oscillator frequency in MHz
- Document firmware fallback: defaults to HAL HSE_VALUE (typically 8MHz for F4)
- Clarify MUST define: non-8MHz HSE (16MHz, 24MHz, 25MHz)
- Clarify OPTIONAL: 8MHz HSE with fallback (explicit definition preferred)
- List standard values: 8MHz (default), 16MHz, 24-25MHz (rare)
- Explain determination methods: schematics, crystal markings, manufacturer
patterns
- Warn about incorrect value consequences: instability, timing errors,
malfunction, boot failures

Add troubleshooting guide:
- Create troubleshooting section in README.md
- List symptoms: UART failures, erratic behavior, boot loops, timing issues
- Provide diagnostic steps: check define, verify crystal markings, check
manufacturer patterns
- Document fix: Add `#define SYSTEM_HSE_MHZ <value>` with correct frequency
- Note firmware fallback works for most 8MHz boards but explicit definition
prevents ambiguity

Document manufacturer patterns:
- Create table with manufacturers and typical HSE frequencies
- Examples: GEPRC/HGLRC/MAMBA/HAKRC/NEUTRONRC→8MHz, AERO→16MHz, BOTWING→24MHz
- Note strong manufacturer consistency (150+ use single HSE)
- Recommend checking existing manufacturer configs
- Reference 49 missing targets where fallback likely works

Phase 4: Targeted Configuration Updates

Add SYSTEM_HSE_MHZ only to targets with confirmed issues or high-risk scenarios identified in Phase 2.

Task 1: Update configs for targets requiring immediate action

Add SYSTEM_HSE_MHZ defines only to targets identified as needing immediate attention in Phase 2 Task 2.2.

• If zero targets identified: Skip this task entirely and document decision in PR/issue
• If specific targets identified (e.g., high-risk non-8MHz boards): Add #define SYSTEM_HSE_MHZ <value> to those configs only
• Use manufacturer patterns and variant matching to determine correct HSE value for each target being updated
• Position the define consistently with existing F4/G4 targets (after FC_TARGET_MCU, before peripheral configurations)
• Document rationale for each updated target in commit message or PR description

Task 2: Validate targeted changes

Ensure correctness of any config updates made in Task 4.1.

• Verify #define SYSTEM_HSE_MHZ <value> syntax is correct (integer value without units)
• Confirm consistent positioning relative to other defines in each modified config.h
• Verify no duplicate SYSTEM_HSE_MHZ definitions exist
• Cross-check HSE values against manufacturer patterns and similar board variants
• If no configs were updated, validate that documentation changes are complete and accurate

🤖 Prompt for AI agents

Phase 4: Add SYSTEM_HSE_MHZ defines only to targets identified in Phase 2 as
requiring immediate action.

Update configs for targets requiring action:
- If zero targets identified: Skip updates, document decision in PR/issue
- If targets identified: Add `#define SYSTEM_HSE_MHZ <value>` to specific
configs only
- Use manufacturer patterns and variant matching for correct HSE values
- Position consistently: after FC_TARGET_MCU, before peripheral configurations
- Document rationale for each update in commit message

Validate changes:
- Verify correct syntax: integer values without units
- Check consistent positioning in each modified config.h
- Verify no duplicate definitions
- Cross-check values against manufacturer patterns and board variants
- If no updates made, validate documentation completeness and accuracy

Phase 5: Firmware Recommendations

Document potential firmware-level improvements for better handling of missing SYSTEM_HSE_MHZ defines.

Create firmware improvement recommendation

Document architectural suggestions for betaflight/betaflight repository.

• Create issue/comment documenting the gap: 49 targets work without SYSTEM_HSE_MHZ due to fallbacks, but relying on implicit behavior is fragile
• Recommend adding compile-time warning (not error) for F4/G4 targets without SYSTEM_HSE_MHZ: #ifndef SYSTEM_HSE_MHZ with #warning "SYSTEM_HSE_MHZ not defined, using default"
• Recommend documenting the fallback behavior in firmware comments so developers understand when explicit definition is needed
• Suggest adding SYSTEM_HSE_MHZ to target configuration templates/guidance in firmware docs
• Note that runtime detection is not feasible (STM32 hardware limitation) but better compile-time messaging would help
• Reference this investigation and conclusion that current fallback behavior works for most boards

🤖 Prompt for AI agents

Phase 5: Document firmware-level improvements for handling missing
SYSTEM_HSE_MHZ defines.

Create firmware improvement recommendation:
- Document gap: 49 targets work without SYSTEM_HSE_MHZ via fallbacks, but
implicit behavior is fragile
- Recommend compile-time warning (not error): `#ifndef SYSTEM_HSE_MHZ` with
warning message about using default
- Recommend documenting fallback behavior in firmware comments
- Suggest adding SYSTEM_HSE_MHZ to target configuration templates and firmware
docs
- Note runtime detection infeasibility but benefits of better compile-time
messaging
- Reference investigation findings showing current fallback works for most
boards

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Phase 1: Investigate the 49 missing targets to determine if any require
immediate action by surveying for reported issues and understanding firmware
fallback behavior.

Survey for reported issues:
- Search betaflight GitHub issue trackers for the 49 target names with
clock-related keywords ("clock", "HSE", "UART timing", "boot failure", "system
instability")
- Check community channels (Discord, forums) for troubleshooting threads
- Document any confirmed clock-related issues with symptoms and resolutions
- Document absence of issues as evidence current state is acceptable

Analyze firmware fallback behavior:
- Review firmware HAL defaults (typically 8MHz for F4, varies for G4)
- Identify differences between STM32F4xx and STM32G4xx fallback behavior
- Document when fallback is safe vs problematic
- Explain why targets like AIRBOTG4AIO work without SYSTEM_HSE_MHZ

Categorize targets by risk:
- Create categories: High (non-8MHz boards), Medium (G4 with wider HSE range),
Low (F4 with 8MHz patterns)
- Use manufacturer patterns: AERO→16MHz, BOTWING→24MHz (exceptions); most→8MHz
- Document each target's manufacturer, likely HSE value, risk level, and
rationale
===============================================================================

Task: 2

Phase 2: Establish decision framework and identify which targets (if any) need
immediate config updates based on Phase 1 investigation.

Create decision framework:
- Define triggering conditions: user-reported issues, manufacturer patterns
indicating non-8MHz HSE, new submissions with non-standard HSE
- Document when omitting SYSTEM_HSE_MHZ is acceptable: firmware fallback matches
hardware (typically 8MHz)
- Create troubleshooting workflow: symptoms → suspect clock issue → verify HSE →
add define if mismatch
- Recommend adding SYSTEM_HSE_MHZ as best practice for new submissions

Identify targets needing immediate action:
- List targets with confirmed issues from Phase 1 survey
- List high-risk targets with non-8MHz patterns (e.g., AERO-prefixed boards)
- Recommend "wait and see" for remaining targets
- If zero targets need action, document conclusion and pivot to
documentation-only solution
===============================================================================

Task: 3

Phase 3: Create comprehensive documentation for SYSTEM_HSE_MHZ configuration,
troubleshooting, and manufacturer patterns.

Add best practices section to README.md:
- Add "Clock Configuration (SYSTEM_HSE_MHZ)" section after "Target Pin Mappings"
- Define SYSTEM_HSE_MHZ: external high-speed oscillator frequency in MHz
- Document firmware fallback: defaults to HAL HSE_VALUE (typically 8MHz for F4)
- Clarify MUST define: non-8MHz HSE (16MHz, 24MHz, 25MHz)
- Clarify OPTIONAL: 8MHz HSE with fallback (explicit definition preferred)
- List standard values: 8MHz (default), 16MHz, 24-25MHz (rare)
- Explain determination methods: schematics, crystal markings, manufacturer
patterns
- Warn about incorrect value consequences: instability, timing errors,
malfunction, boot failures

Add troubleshooting guide:
- Create troubleshooting section in README.md
- List symptoms: UART failures, erratic behavior, boot loops, timing issues
- Provide diagnostic steps: check define, verify crystal markings, check
manufacturer patterns
- Document fix: Add `#define SYSTEM_HSE_MHZ <value>` with correct frequency
- Note firmware fallback works for most 8MHz boards but explicit definition
prevents ambiguity

Document manufacturer patterns:
- Create table with manufacturers and typical HSE frequencies
- Examples: GEPRC/HGLRC/MAMBA/HAKRC/NEUTRONRC→8MHz, AERO→16MHz, BOTWING→24MHz
- Note strong manufacturer consistency (150+ use single HSE)
- Recommend checking existing manufacturer configs
- Reference 49 missing targets where fallback likely works
===============================================================================

Task: 4

Phase 4: Add SYSTEM_HSE_MHZ defines only to targets identified in Phase 2 as
requiring immediate action.

Update configs for targets requiring action:
- If zero targets identified: Skip updates, document decision in PR/issue
- If targets identified: Add `#define SYSTEM_HSE_MHZ <value>` to specific
configs only
- Use manufacturer patterns and variant matching for correct HSE values
- Position consistently: after FC_TARGET_MCU, before peripheral configurations
- Document rationale for each update in commit message

Validate changes:
- Verify correct syntax: integer values without units
- Check consistent positioning in each modified config.h
- Verify no duplicate definitions
- Cross-check values against manufacturer patterns and board variants
- If no updates made, validate documentation completeness and accuracy
===============================================================================

Task: 5

Phase 5: Document firmware-level improvements for handling missing
SYSTEM_HSE_MHZ defines.

Create firmware improvement recommendation:
- Document gap: 49 targets work without SYSTEM_HSE_MHZ via fallbacks, but
implicit behavior is fragile
- Recommend compile-time warning (not error): `#ifndef SYSTEM_HSE_MHZ` with
warning message about using default
- Recommend documenting fallback behavior in firmware comments
- Suggest adding SYSTEM_HSE_MHZ to target configuration templates and firmware
docs
- Note runtime detection infeasibility but benefits of better compile-time
messaging
- Reference investigation findings showing current fallback works for most
boards

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[haslinghuis]

@ot0tot had no issues with AIRBOTG4AIO - so perhaps keep status quo - fix it if issues arise instead of proactive assuming it is needed

@coderabbitai please advice - see #1008 (comment)

[coderabbitai]

I've updated the plan above based on your feedback. Ready to proceed when you are!

[ot0tot]

@ot0tot had no issues with AIRBOTG4AIO - so perhaps keep status quo - fix it if issues arise instead of proactive assuming it is needed

HSI will work, but HSE should provide a much more stable clock signal if available. The default should be HSE.