inav/AGENT.md

# AGENT.md - Guide for AI Agents Working with INAV

## Project Overview

**INAV** is a navigation-capable flight controller firmware for multirotor, fixed-wing, and other RC vehicles. It is a community-driven project written primarily in C (C99/C11 standard) with support for STM32 F4, F7, H7, and AT32 microcontrollers.

### Key Characteristics
- **Type**: Embedded firmware for flight controllers
- **Language**: C (C99/C11), with some C++ for unit tests
- **Build System**: CMake (version 3.13+)
- **License**: GNU GPL v3
- **Version**: 9.0.1 (as of this writing)
- **Codebase History**: Evolved from Cleanflight/Baseflight

## Architecture and Structure

### Core Components

The INAV codebase is organized into the following major subsystems:

1. **Flight Control (`fc/`)**: Core flight controller logic, initialization, MSP protocol handling
2. **Sensors (`sensors/`)**: Gyro, accelerometer, compass, barometer, GPS, rangefinder, pitot tube
3. **Flight (`flight/`)**: PID controllers, mixers, altitude hold, position hold, navigation
4. **Navigation (`navigation/`)**: Waypoint missions, RTH (Return to Home), position hold
5. **Drivers (`drivers/`)**: Hardware abstraction layer for MCU peripherals (SPI, I2C, UART, timers, etc.)
6. **IO (`io/`)**: Serial communication, OSD, LED strips, telemetry
7. **RX (`rx/`)**: Radio receiver protocols (CRSF, SBUS, IBUS, etc.)
8. **Scheduler (`scheduler/`)**: Real-time task scheduling
9. **Configuration (`config/`)**: Parameter groups, EEPROM storage, settings management
10. **MSP (`msp/`)**: MultiWii Serial Protocol implementation
11. **Telemetry (`telemetry/`)**: SmartPort, FPort, MAVLink, LTM, CRSF telemetry
12. **Blackbox (`blackbox/`)**: Flight data recorder
13. **Programming (`programming/`)**: Logic conditions and global functions for in-flight programming

### Directory Structure

```
/src/main/              - Main source code
  ├── build/            - Build configuration and macros
  ├── common/           - Common utilities (math, filters, utils)
  ├── config/           - Configuration system (parameter groups)
  ├── drivers/          - Hardware drivers (MCU-specific)
  ├── fc/               - Flight controller core
  ├── flight/           - Flight control algorithms
  ├── io/               - Input/output (serial, OSD, LED)
  ├── msp/              - MSP protocol
  ├── navigation/       - Navigation and autopilot
  ├── rx/               - Radio receiver protocols
  ├── sensors/          - Sensor drivers and processing
  ├── scheduler/        - Task scheduler
  ├── telemetry/        - Telemetry protocols
  └── target/           - Board-specific configurations

/docs/                  - Documentation
  └── development/      - Developer documentation

/cmake/                 - CMake build scripts
/lib/                   - External libraries
/tools/                 - Build and utility tools
```

## Coding Conventions

### Naming Conventions

1. **Types**: Use `_t` suffix for typedef'd types: `gyroConfig_t`, `pidController_t`
2. **Enums**: Use `_e` suffix for enum types: `portMode_e`, `cfTaskPriority_e`
3. **Functions**: Use camelCase with verb-phrase names: `gyroInit()`, `deleteAllPages()`
4. **Variables**: Use camelCase nouns, avoid noise words like "data" or "info"
5. **Booleans**: Question format: `isOkToArm()`, `canNavigate()`
6. **Constants**: Upper case with underscores: `MAX_GYRO_COUNT`
7. **Macros**: Upper case with underscores: `FASTRAM`, `STATIC_UNIT_TESTED`

### Code Style

- **Indentation**: 4 spaces (no tabs)
- **Braces**: K&R style (opening brace on same line, except for functions)
- **Line Length**: Keep reasonable (typically under 120 characters)
- **Comments**: Explain WHY, not WHAT. Document variables at declaration, not at extern usage
- **Header Guards**: Use `#pragma once` (modern convention used throughout codebase)

### Memory Attributes

INAV uses special memory attributes for performance-critical code on resource-constrained MCUs:

```c
FASTRAM                     // Fast RAM section (aligned)
EXTENDED_FASTRAM            // Extended fast RAM (STM32F4/F7 only)
DMA_RAM                     // DMA-accessible RAM (STM32H7, AT32F43x)
SLOW_RAM                    // Slower external RAM - deprecated, o not use
STATIC_FASTRAM              // Static variable in fast RAM
STATIC_FASTRAM_UNIT_TESTED  // Static fast RAM variable visible in unit tests
```

### Test Visibility Macros

```c
STATIC_UNIT_TESTED         // static in production, visible in unit tests
STATIC_INLINE_UNIT_TESTED  // static inline in production, visible in tests
INLINE_UNIT_TESTED         // inline in production, visible in tests
UNIT_TESTED                // Always visible (no storage class)
```

## Build System

### CMake Build Process

INAV uses CMake with custom target definition functions:

1. **Target Definition**: Each board has a `target.h` and optionally `CMakeLists.txt`
2. **Hardware Function**: `target_stm32f405xg(NAME optional_params)`
3. **Build Directory**: Always use out-of-source builds in `/build` directory

### Building a Target

```bash
# From workspace root
cd build
cmake ..
make MATEKF722SE     # Build specific target
make                 # Build all targets
```

### Target Configuration

Targets are defined in `/src/main/target/TARGETNAME/`:
- `target.h`: Hardware pin definitions, feature enables, MCU configuration
- `target.c`: Board-specific initialization code
- `CMakeLists.txt`: Build configuration (optional)

Example target definition:
```c
#define TARGET_BOARD_IDENTIFIER "MF7S"
#define LED0 PA14
#define BEEPER PC13
#define USE_SPI
#define USE_SPI_DEVICE_1
#define SPI1_SCK_PIN PA5
```

### Conditional Compilation

Feature flags control code inclusion:
```c
#ifdef USE_GPS
    // GPS code
#endif

#if defined(STM32F4)
    // F4-specific code
#elif defined(STM32F7)
    // F7-specific code
#endif
```

## Key Concepts

### Parameter Groups (PG)

INAV uses a sophisticated configuration system called "Parameter Groups" for persistent storage:

```c
// Define a configuration structure
typedef struct {
    uint8_t gyro_lpf_hz;
    uint16_t gyro_kalman_q;
    // ...
} gyroConfig_t;

// Register with reset template
PG_REGISTER_WITH_RESET_TEMPLATE(gyroConfig_t, gyroConfig, PG_GYRO_CONFIG, 12);

// Define default values
PG_RESET_TEMPLATE(gyroConfig_t, gyroConfig,
    .gyro_lpf_hz = 60,
    .gyro_kalman_q = 200,
    // ...
);

// Access in code
gyroConfig()->gyro_lpf_hz
```

**Key Functions:**
- `PG_REGISTER_WITH_RESET_TEMPLATE()`: Register with static defaults
- `PG_REGISTER_WITH_RESET_FN()`: Register with function-based initialization
- `PG_REGISTER_ARRAY()`: For arrays of configuration items
- Parameter group IDs are in `config/parameter_group_ids.h`

### Scheduler

INAV uses a priority-based cooperative task scheduler:

```c
typedef enum {
    TASK_PRIORITY_IDLE = 0,
    TASK_PRIORITY_LOW = 1,
    TASK_PRIORITY_MEDIUM = 3,
    TASK_PRIORITY_HIGH = 5,
    TASK_PRIORITY_REALTIME = 18,
} cfTaskPriority_e;
```

Tasks are defined in `fc/fc_tasks.c` with priority and desired execution period.

### Sensors and Calibration

Sensors use a common pattern:
1. **Detection**: Auto-detect hardware at boot (`gyroDetect()`, `baroDetect()`)
2. **Initialization**: Configure sensor parameters
3. **Calibration**: Zero-offset calibration (gyro, accelerometer)
4. **Data Processing**: Apply calibration, alignment, and filtering

### Flight Control Loop

The main control loop follows this pattern:
1. **Gyro Task** (highest priority): Read gyro, apply filters
2. **PID Task**: Calculate PID corrections
3. **RX Task**: Process radio input
4. **Other Tasks**: Sensors, telemetry, OSD, etc. (lower priority)

### MSP Protocol

MultiWii Serial Protocol is used for configuration and telemetry:
- Request/response model
- Message types defined in `msp/msp_protocol.h`
- Handlers in `fc/fc_msp.c`

## Common Patterns

### Hardware Abstraction

INAV abstracts hardware through resource allocation:

```c
// IO pins
IO_t pin = IOGetByTag(IO_TAG(PA5));
IOInit(pin, OWNER_SPI, RESOURCE_SPI_SCK, 1);

// Timers
const timerHardware_t *timer = timerGetByTag(IO_TAG(PA8), TIM_USE_ANY);

// DMA
dmaIdentifier_e dma = dmaGetIdentifier(DMA1_Stream0);
```

### Error Handling

INAV uses several approaches:
1. **Return codes**: Boolean success/failure or error enums
2. **Diagnostics**: `sensors/diagnostics.c` for sensor health
3. **Status indicators**: Beeper codes, LED patterns for user feedback
4. **Logging**: CLI-based logging system

### Filter Chains

Sensor data typically goes through multiple filtering stages:

```c
// Low-pass filters
gyroLpfApplyFn = lowpassFilterGetApplyFn(filterType);
gyroLpfApplyFn(&gyroLpfState[axis], sample);

// Notch filters (for dynamic filtering)
for (int i = 0; i < dynamicNotchCount; i++) {
    sample = biquadFilterApply(&notchFilter[i], sample);
}
```

### Board Alignment

All sensors go through board alignment transforms to correct for mounting orientation:

```c
// Apply board alignment rotation matrix
applySensorAlignment(gyroData, gyroData, gyroAlign);
```

### SITL (Software In The Loop)

INAV can be compiled for host system simulation:
```bash
cmake -DSITL=ON ..
make
```

## Development Workflow

### Branching Strategy

- **`maintenance-X.x`**: Current version development (e.g., `maintenance-9.x`)
- **`maintenance-Y.x`**: Next major version (e.g., `maintenance-10.x`)
- **`master`**: Tracks current version, receives merges from maintenance branches

### Pull Request Guidelines

1. **Target Branch**: 
   - Bug fixes and backward-compatible features → current maintenance branch
   - Breaking changes → next major version maintenance branch
   - **Never** target `master` directly

2. **Keep PRs Focused**: One feature/fix per PR

3. **Code Quality**:
   - Follow existing code style
   - Add unit tests where possible
   - Update documentation in `/docs`
   - Test on real hardware when possible

4. **Commit Messages**: Clear, descriptive messages

### Important Files to Check

Before making changes, review:
- `docs/development/Development.md` - Development principles
- `docs/development/Contributing.md` - Contribution guidelines
- Target-specific files in `/src/main/target/`

## Important Files and Directories

### Configuration Files

- `platform.h`: Platform-specific includes and defines
- `target.h`: Board-specific hardware configuration
- `config/parameter_group.h`: Parameter group system
- `config/parameter_group_ids.h`: PG ID definitions
- `fc/settings.yaml`: CLI settings definitions

### Core Flight Control

- `fc/fc_core.c`: Main flight control loop
- `fc/fc_init.c`: System initialization
- `fc/fc_tasks.c`: Task scheduler configuration
- `flight/pid.c`: PID controller implementation
- `flight/mixer.c`: Motor mixing

### Key Headers

- `build/build_config.h`: Build-time configuration macros
- `common/axis.h`: Axis definitions (X, Y, Z, ROLL, PITCH, YAW)
- `common/maths.h`: Math utilities and constants
- `common/filter.h`: Digital filter implementations
- `drivers/accgyro/accgyro.h`: Gyro/accelerometer interface

## AI Agent Guidelines

### When Adding Features

1. **Understand the Module**: Read related files in the same directory
2. **Check for Similar Code**: Search for similar features to maintain consistency
3. **Follow Parameter Group Pattern**: New settings should use PG system
4. **Add to Scheduler**: New periodic tasks go in `fc/fc_tasks.c`
5. **Update Documentation**: Add/update files in `/docs` 
6. **Consider Target Support**: Use `#ifdef USE_FEATURE` for optional features
7. **Generate CLI setting docs**: Remember to inform user to run `python src/utils/update_cli_docs.py`
8. **Follow conding standard**: Follow MISRA C rules
9. **Increase Paremeterer Group Version**: When changing PG structure, increase version corresponding in `PG_REGISTER`, `PG_REGISTER_WITH_RESET_FN`, `PG_REGISTER_WITH_RESET_TEMPLATE`, `PG_REGISTER_ARRAY` or `PG_REGISTER_ARRAY_WITH_RESET_FN`

### When Fixing Bugs

1. **Review Recent Changes**: Check git history for related modifications
2. **Test Signal Path**: For sensor issues, trace from hardware through filters to consumer
3. **Consider All Platforms**: STM32F4, F7, H7, and AT32 may behave differently
4. **Check Memory Usage**: Embedded system has limited RAM/flash

### When Refactoring

1. **Maintain API Compatibility**: Unless targeting next major version
2. **Preserve Unit Tests**: Update tests to match refactored code
3. **Update Documentation**: Keep docs synchronized with code changes
4. **Consider Performance**: Profile on target hardware, not just host compilation
5. **Check All Callers**: Use grep/search to find all usage sites

### Common Pitfalls to Avoid

1. **Don't Ignore Memory Attributes**: FASTRAM placement affects real-time performance
2. **Don't Break Parameter Groups**: Changing PG structure requires version bump
3. **Don't Assume Hardware**: Always check feature flags (`#ifdef USE_GPS`)
4. **Don't Break MSP**: Changes to MSP protocol affect configurator compatibility
5. **Don't Commit Wrong Branch**: Target maintenance branch, not master
6. **Don't Skip Documentation**: Code without docs increases support burden
7. **Don't Hardcode Values**: Use parameter groups for configurable values

### Searching the Codebase

**Find definitions:**
```bash
grep -r "typedef.*_t" src/main/  # Find all type definitions
grep -r "PG_REGISTER" src/main/  # Find parameter groups
grep -r "TASK_" src/main/        # Find scheduled tasks
```

**Find usage:**
```bash
grep -r "functionName" src/main/
grep -r "USE_GPS" src/main/target/  # Feature support by target
```

**Find similar code:**
- Look in the same directory first
- Check for similar sensor/peripheral implementations
- Review git history: `git log --all --oneline --grep="keyword"`

### Understanding Control Flow

1. **Startup**: `main.c` → `fc_init.c:init()` → `fc_tasks.c:tasksInit()`
2. **Main Loop**: `scheduler.c:scheduler()` executes tasks by priority
3. **Critical Path**: Gyro → PID → Mixer → Motors (highest priority)
4. **Configuration**: CLI/MSP → Parameter Groups → EEPROM

### Cross-Platform Considerations

Different MCU families have different characteristics:

- **STM32F4**: Most common, 84-168 MHz, FPU, no cache
- **STM32F7**: Faster, 216 MHz, FPU, I/D cache, requires cache management
- **STM32H7**: Fastest, 480 MHz, more RAM, complex memory architecture (DTCM, SRAM)
- **AT32F43x**: Chinese MCU, STM32F4-compatible, different peripherals

Always test on target or use `#if defined()` guards for MCU-specific code.

## Quick Reference

### File Naming Patterns

- `*_config.h`: Configuration structures (usually with PG)
- `*_impl.h`: Implementation headers (MCU-specific)
- `*_hal.h`: Hardware abstraction layer
- `accgyro_*.c`: Gyro/accelerometer drivers
- `bus_*.c`: Communication bus drivers (SPI, I2C)

### Common Abbreviations

- **FC**: Flight Controller
- **PG**: Parameter Group
- **MSP**: MultiWii Serial Protocol
- **CLI**: Command Line Interface
- **OSD**: On-Screen Display
- **RTH**: Return to Home
- **PID**: Proportional-Integral-Derivative (controller)
- **IMU**: Inertial Measurement Unit (gyro + accel)
- **AHRS**: Attitude and Heading Reference System
- **ESC**: Electronic Speed Controller
- **SITL**: Software In The Loop
- **HITL**: Hardware In The Loop

## Resources

- **Main Repository**: https://github.com/iNavFlight/inav
- **Configurator**: https://github.com/iNavFlight/inav-configurator
- **Discord**: https://discord.gg/peg2hhbYwN
- **Documentation**: https://github.com/iNavFlight/inav/wiki
- **Release Notes**: https://github.com/iNavFlight/inav/releases

## Version Information

This document is accurate for INAV 9.0.1. As the project evolves, some details may change. Always refer to the latest documentation and code for authoritative information.

---

**Remember**: INAV flies aircraft that people build and fly. Code quality, safety, and reliability are paramount. When in doubt, ask the community or maintainers for guidance.