.pr_agent_auto_best_practices

Pattern 1: Make headers self-contained by explicitly including the headers that define required macros/types and by adding proper header guards; do not rely on transitive includes or include order.

Example code before:

// foo_driver.h
// (no header guard)
#define FOO_REG CONCAT4(GPIO, A, _, MODER)   // CONCAT4 not defined here
extern pg_registry_t fooPg;                  // PG_DECLARE/pg types not included

Example code after:

// foo_driver.h
#pragma once
#include "common/utils.h"              // CONCAT4
#include "config/parameter_group.h"   // PG_DECLARE / pg types

#define FOO_REG CONCAT4(GPIO, A, _, MODER)
PG_DECLARE(fooPg);

Relevant past accepted suggestions:

---

Suggestion 1:

[reliability] Headers rely on transitive CONCAT4

---

Headers rely on transitive CONCAT4

The new bus_spi_stm32{h7,f7}xx.h headers use CONCAT4 but do not include the header that defines it, relying on current include order/transitive includes from other headers. This is a latent build fragility: a future refactor or reuse of these headers elsewhere can cause compile failures (e.g., CONCAT4 undefined).

Issue description

The new SPI AF lookup table headers use CONCAT4(...) but do not include the header that defines it (common/utils.h). They currently compile only due to transitive includes (via drivers/io.h → io_def.h → common/utils.h) and therefore are fragile to include-order changes or reuse.

Issue Context

This is a latent build fragility / maintainability issue: it may not break today, but it can break later during refactors or if another file includes these headers without including common/utils.h first.

Fix Focus Areas

• src/main/drivers/bus_spi_stm32h7xx.h[32-38]
• src/main/drivers/bus_spi_stm32f7xx.h[36-42]

---

Suggestion 2:

[correctness] dronecan.h missing deps

---

dronecan.h missing deps

`dronecan.h` uses `PG_DECLARE` but doesn’t include `config/parameter_group.h` (and lacks a header guard), making builds depend on include order. `fc_tasks.c` includes `dronecan.h` before any header that defines `PG_DECLARE`, which can cause compile failures.

Issue description

src/main/drivers/dronecan/dronecan.h is not self-contained: it uses PG_DECLARE but does not include the header that defines it (config/parameter_group.h). This creates brittle include-order dependencies and can break compilation in files that include dronecan.h early (e.g. fc_tasks.c).

Issue Context

PG_DECLARE is defined in src/main/config/parameter_group.h. Some compilation units include dronecan.h before any header that brings in parameter_group.h.

Fix Focus Areas

• src/main/drivers/dronecan/dronecan.h[1-19]
• src/main/fc/fc_tasks.c[18-43]
• src/main/config/parameter_group.h[104-110]

---

Suggestion 3:

Remove duplicate macro definition

The USE_OSD macro is defined twice in the file. This duplication is unnecessary and could lead to preprocessor warnings or confusion during compilation.

src/main/target/HUMMINGBIRD_FC305/target.h [81-161]

 #define USE_OSD
 #define USE_MAX7456
-MAX7456_SPI_BUS		    BUS_SPI3
+#define MAX7456_SPI_BUS		    BUS_SPI3
 #define MAX7456_CS_PIN          PC13
-...
-#define USE_OSD

---

Pattern 2: Validate external inputs (env vars, protocol payload sizes, computed frame lengths, indices) before use; fail deterministically or return an explicit error when invalid.

Example code before:

int pr = parseInt(getenv("PR_NUMBER"));   // NaN possible
uint8_t mode = buf[0];                   // assumes at least 1 byte
portCfg = portConfigs[idx];              // idx might be -1

Example code after:

const char *s = getenv("PR_NUMBER");
char *end = NULL;
long pr = s ? strtol(s, &end, 10) : -1;
if (pr <= 0 || end == s || *end != '\0') return error("bad PR_NUMBER");

if (len < 1) return PROTO_ERR_TRUNCATED;
if (idx < 0 || idx >= PORT_CONFIG_COUNT) return PROTO_ERR_RANGE;

Relevant past accepted suggestions:

---

Suggestion 1:

[reliability] `parseInt` result not validated

---

`parseInt` result not validated

The PR comment step uses `parseInt(process.env.PR_NUMBER)` without checking for `NaN` or enforcing base-10 parsing, which can lead to non-deterministic behavior if the env var is missing/malformed. This violates the requirement to validate external inputs and handle invalid values deterministically.

Issue description

The workflow parses PR_NUMBER from an environment variable using parseInt(...) and then uses it without checking for NaN (and without specifying radix 10). If the env var is missing or malformed, this can produce non-deterministic behavior (e.g., NaN in URLs / API params) instead of a clear, deterministic failure.

Issue Context

This job runs with elevated permissions (pull-requests: write) and should validate external inputs (including env vars derived from artifacts/outputs) before use.

Fix Focus Areas

• .github/workflows/pr-test-builds.yml[107-110] բավ

---

Suggestion 2:

Add payload size validation check

Add a payload size check in the MSP_OSD_CUSTOM_POSITION handler to ensure the incoming data is at least 3 bytes before reading from the buffer.

src/main/fc/fc_msp.c [2718-2731]

 case MSP_OSD_CUSTOM_POSITION: {
+    if (dataSize < 3) {
+        return MSP_RESULT_ERROR;
+    }
     uint8_t item;
     sbufReadU8Safe(&item, src);
     if (item < OSD_ITEM_COUNT){ // item == addr
         osdEraseCustomItem(item);
         osdLayoutsConfigMutable()->item_pos[0][item] = sbufReadU16(src) | (1 << 13);
         osdDrawCustomItem(item);
     }
     else{
         return MSP_RESULT_ERROR;
     }
 
     break;
 }

---

Suggestion 3:

[learned best practice] Validate `"$#"` before reading `$1` and print a short usage message on error so failures are deterministic and user-friendly.

---

Suggestion 4:

[possible issue] Add a check to ensure the index returned by `findSerialPortIndexByIdentifier` is valid (>= 0) before using it to access the `portConfigs` array to prevent potential crashes.

---

Suggestion 5:

[learned best practice] Before writing variable-length frames, validate the computed payload/frame length against `CRSF_FRAME_SIZE_MAX`/`CRSF_PAYLOAD_SIZE_MAX` (and remaining `sbuf` capacity) and clamp counts or abort if it won’t fit.

---

Pattern 3: Check return values and handle timeout conditions in hardware/IO control paths; if an operation fails (DMA disable, peripheral init, transmit, SD wait), propagate an error and avoid continuing with partially applied configuration.

Example code before:

disableDma(stream);
while (streamEnabled(stream) && --timeout) { }  // may time out
reconfigureDma(stream, cfg);                    // proceeds anyway

computeTimings(&t);                             // bool ignored
initPeripheral(&t);                             // uses possibly invalid timings

Example code after:

disableDma(stream);
while (streamEnabled(stream) && --timeout) { }
if (streamEnabled(stream)) return ERR_TIMEOUT;

if (!computeTimings(&t)) return ERR_BAD_TIMING;
if (initPeripheral(&t) != 0) return ERR_INIT_FAILED;

Relevant past accepted suggestions:

---

Suggestion 1:

[correctness] `canardSTM32ComputeTimings` unchecked

---

`canardSTM32ComputeTimings` unchecked

`canardSTM32ComputeTimings()` returns `bool` but its result is ignored and `out_timings` is used unconditionally to configure the peripheral. If timing computation fails, CAN may be initialized with invalid/uninitialized timing values without any error propagation.

Issue description

CAN timing computation failure is ignored, potentially configuring hardware with invalid values.

Issue Context

The timing helper explicitly returns false for invalid/unsatisfied configurations; initialization should not proceed on failure.

Fix Focus Areas

• src/main/drivers/dronecan/libcanard/canard_stm32h7xx_driver.c[162-168]

---

Suggestion 2:

[correctness] `canardSTM32CAN1_Init()` return ignored

---

`canardSTM32CAN1_Init()` return ignored

`canardSTM32CAN1_Init()` returns a status code but `dronecanInit()` ignores it and continues initialization. This can leave DroneCAN partially initialized and failing silently at runtime.

Issue description

DroneCAN initialization ignores CAN peripheral init failures.

Issue Context

Proceeding after failed CAN init can cause confusing runtime behavior and make debugging difficult.

Fix Focus Areas

• src/main/drivers/dronecan/dronecan.c[404-440]

---

Suggestion 3:

[possible issue] In `SD_StartBlockTransfert`, check if the DMA disable loop timed out. If it did, set an error and return to avoid reconfiguring an active DMA stream, which could cause unpredictable behavior.

---

Suggestion 4:

[possible issue] In `SD_HighSpeed`, if the `swTimeout` is reached while waiting for SDIO status, return an error like `SD_TIMEOUT` instead of just breaking the loop to prevent processing incomplete data. [possible issue, importance: 7]

New proposed code:

---

Suggestion 5:

[possible issue] In `impl_timerPWMSetDMACircular`, add a check after the DMA disable wait loop to handle the timeout case. If the timeout is reached, abort the DMA reconfiguration to prevent potential instability.

---

Suggestion 6:

[possible issue] Fix the incorrect DMA timeout check by re-evaluating the stream status after the loop instead of checking if `timeout` is zero.

---

Suggestion 7:

[general] Add a timeout or retry counter to the polling loops in `STORAGE_Read` to prevent the system from hanging if the SD card becomes unresponsive.

---

Suggestion 8:

[possible issue] In `processCrsf`, check the return value of `crsfRpm` and only call `crsfFinalize` if data was successfully written to the buffer.

---

Pattern 4: Do not commit generated artifacts or environment-specific build outputs; generate them in the build directory, ignore them in VCS, and gate any “update baseline” files behind an explicit opt-in command/flag.

Example code before:

# CMakeLists.txt
add_custom_command(TARGET fw POST_BUILD
  COMMAND python gen_pg_sizes.py > ${CMAKE_SOURCE_DIR}/cmake/pg_struct_sizes.db)

# repo contains:
#   build/CMakeFiles/.../DependInfo.cmake
#   dsdlc_generated/*.c

Example code after:

# CMakeLists.txt
add_custom_command(TARGET fw POST_BUILD
  COMMAND python gen_pg_sizes.py > ${CMAKE_BINARY_DIR}/pg_struct_sizes.db
  COMMENT "Wrote updated sizes to build output; run --update-db to apply")

# .gitignore
CMakeFiles/
dsdlc_generated/
*.cmake

Relevant past accepted suggestions:

---

Suggestion 1:

[correctness] `dsdlc_generated` code committed

---

`dsdlc_generated` code committed

This PR adds `dsdlc_generated` DroneCAN DSDL outputs directly to the repo, which are generated artifacts and can make builds non-reproducible and the repo noisy. These files should be generated into the build directory (or updated via an explicit opt-in step) and excluded from normal source tracking.

Issue description

The PR commits DSDL-generated DroneCAN sources/headers under dsdlc_generated, which are generated artifacts.

Issue Context

Generated artifacts should be produced as part of the build (or via an explicit opt-in update command) and not be committed as normal source to keep the repository clean and reproducible.

Fix Focus Areas

• src/main/drivers/dronecan/dsdlc_generated/src/uavcan.equipment.air_data.Sideslip.c[1-8]
• cmake/main.cmake[2-12]

---

Suggestion 2:

Remove generated build file from repository

Remove the generated CMake build file from the repository. It contains user-specific absolute paths that will cause build failures for other developers and should be added to .gitignore.

src/src/main/target/AXISFLYINGF7PRO/CMakeFiles/AXISFLYINGF7PRO_for_bl.elf.dir/DependInfo.cmake [1-474]

-# Consider dependencies only in project.
-set(CMAKE_DEPENDS_IN_PROJECT_ONLY OFF)
+# This file should be removed from the repository.
 
-# The set of languages for which implicit dependencies are needed:
-set(CMAKE_DEPENDS_LANGUAGES
-  "ASM"
-  )
-# The set of files for implicit dependencies of each language:
-set(CMAKE_DEPENDS_CHECK_ASM
-  "/Users/ahmed/Desktop/Projects/INAV-RPiOSD/inav/lib/main/CMSIS/DSP/Source/TransformFunctions/arm_bitreversal2.S" "/Users/ahmed/Desktop/Projects/INAV-RPiOSD/inav/src/src/main/target/AXISFLYINGF7PRO/CMakeFiles/AXISFLYINGF7PRO_for_bl.elf.dir/__/__/__/__/lib/main/CMSIS/DSP/Source/TransformFunctions/arm_bitreversal2.S.obj"
-  "/Users/ahmed/Desktop/Projects/INAV-RPiOSD/inav/src/main/startup/startup_stm32f722xx.s" "/Users/ahmed/Desktop/Projects/INAV-RPiOSD/inav/src/src/main/target/AXISFLYINGF7PRO/CMakeFiles/AXISFLYINGF7PRO_for_bl.elf.dir/__/__/startup/startup_stm32f722xx.s.obj"
-  )
-set(CMAKE_ASM_COMPILER_ID "GNU")
-
-# Preprocessor definitions for this target.
-set(CMAKE_TARGET_DEFINITIONS_ASM
-...
-
-# The include file search paths:
-set(CMAKE_ASM_TARGET_INCLUDE_PATH
-  "main/target/AXISFLYINGF7PRO"
-  "/Users/ahmed/Desktop/Projects/INAV-RPiOSD/inav/lib/main/STM32F7/Drivers/STM32F7xx_HAL_Driver/Inc"
-  "/Users/ahmed/Desktop/Projects/INAV-RPiOSD/inav/lib/main/STM32F7/Drivers/CMSIS/Device/ST/STM32F7xx/Include"
-...
-

---

Suggestion 3:

Remove generated file from version control

Remove the generated Makefile.cmake file from version control. This file is environment-specific and should be ignored by adding the CMakeFiles directory to .gitignore.

src/CMakeFiles/Makefile.cmake [1-9]

-# CMAKE generated file: DO NOT EDIT!
-# Generated by "Unix Makefiles" Generator, CMake Version 4.1
+# This file should be removed from the pull request and repository.
 
-# The generator used is:
-set(CMAKE_DEPENDS_GENERATOR "Unix Makefiles")
-
-# The top level Makefile was generated from the following files:
-set(CMAKE_MAKEFILE_DEPENDS
-  "CMakeCache.txt"
-...
-

---

Suggestion 4:

[learned best practice] Avoid mutating `cmake/pg_struct_sizes.db` in a POST_BUILD step; instead write an updated copy to a build output file (or gate updates behind an explicit `--update-db` flag) and print instructions to apply it.

---

Pattern 5: Avoid arithmetic/units pitfalls in control and telemetry code: guard against division-by-zero, ensure floating-point division where required, and keep calculations in consistent units until final conversion/normalization.

Example code before:

int airspeed = getAirspeed();
int scale = 36 / 100;                 // integer division -> 0
float tpa = (airspeed - ref) / ref;   // ref might be 0
int deg = (cd + 18000) / 100;         // mixes normalization and conversion repeatedly

Example code after:

const float scale = 36.0f / 100.0f;

if (ref <= 0) return fallback();
const float tpa = (airspeed - ref) / ref;

int32_t headingCd = cd + 18000;
while (headingCd < 0) headingCd += 36000;
while (headingCd >= 36000) headingCd -= 36000;
const int32_t headingDeg = headingCd / 100;

Relevant past accepted suggestions:

---

Suggestion 1:

Normalize angles in one unit

Keep all math in centidegrees until final conversion and normalize once; avoid redundant casts and flips that can introduce off-by-one errors.

src/main/programming/logic_condition.c [787-816]

-case LOGIC_CONDITION_OPERAND_FLIGHT_RELATIVE_WIND_OFFSET: // deg
+case LOGIC_CONDITION_OPERAND_FLIGHT_RELATIVE_WIND_OFFSET: // deg, signed [-180,180], 0 = headwind, left negative
 #ifdef USE_WIND_ESTIMATOR
     {
         if (isEstimatedWindSpeedValid()) {
-            uint16_t windAngle;
-            getEstimatedHorizontalWindSpeed(&windAngle);
-            gvSet(3, DECIDEGREES_TO_DEGREES(attitude.values.yaw));
-            int32_t relativeWindHeading = windAngle + 18000 - DECIDEGREES_TO_CENTIDEGREES(attitude.values.yaw);
-    
-            relativeWindHeading = (CENTIDEGREES_TO_DEGREES((int)relativeWindHeading));
-            while (relativeWindHeading < 0) {
-                relativeWindHeading += 360;
-            }
-            while (relativeWindHeading >= 360) {
-                relativeWindHeading -= 360;
-            }
-            
-            relativeWindHeading = -relativeWindHeading;
-            if (relativeWindHeading <= -180) {
-                relativeWindHeading = 180 + (relativeWindHeading + 180);
-            }
-
-            return relativeWindHeading;
-        } else
+            uint16_t windAngleCd;
+            getEstimatedHorizontalWindSpeed(&windAngleCd); // [0,36000)
+            // Convert wind vector angle (towards) to heading-from
+            int32_t windHeadingCd = (int32_t)windAngleCd + 18000; // centidegrees
+            // Normalize to [0,36000)
+            while (windHeadingCd < 0) windHeadingCd += 36000;
+            while (windHeadingCd >= 36000) windHeadingCd -= 36000;
+            // Aircraft yaw is in decidegrees; convert to centidegrees
+            int32_t yawCd = DECIDEGREES_TO_CENTIDEGREES(attitude.values.yaw);
+            // Relative offset: wind heading relative to aircraft nose (right positive)
+            int32_t relCd = windHeadingCd - yawCd; // centidegrees
+            // Normalize to (-18000, 18000]
+            while (relCd <= -18000) relCd += 36000;
+            while (relCd > 18000) relCd -= 36000;
+            // Convert to degrees with sign convention: left negative
+            int32_t relDeg = CENTIDEGREES_TO_DEGREES(relCd);
+            return relDeg;
+        } else {
             return 0;
+        }
     }
 #else
-        return 0;
+    return 0;
 #endif
-        break;
+    break;

---

Suggestion 2:

Prevent division by zero during normalization

Add a check to ensure vCoGlocal has a non-zero magnitude before normalization to prevent a potential division-by-zero error.

src/main/flight/imu.c [472-482]

-if (vectorNormSquared(&vHeadingEF) > 0.01f) {
+if (vectorNormSquared(&vHeadingEF) > 0.01f && vectorNormSquared(&vCoGlocal) > 0.01f) {
     // Normalize to unit vector
     vectorNormalize(&vHeadingEF, &vHeadingEF);
     vectorNormalize(&vCoGlocal, &vCoGlocal);
 
     // error is cross product between reference heading and estimated heading (calculated in EF)
     vectorCrossProduct(&vCoGErr, &vCoGlocal, &vHeadingEF);
 
     // Rotate error back into body frame
     quaternionRotateVector(&vCoGErr, &vCoGErr, &orientation);
 }

---

Suggestion 3:

Prevent division-by-zero in TPA calculation

Add a check to prevent division-by-zero when referenceAirspeed is zero in the tpaThrottle calculation, falling back to the standard throttle value if necessary.

src/main/flight/pid.c [501-502]

 const float referenceAirspeed = pidProfile()->fixedWingReferenceAirspeed; // in cm/s
-tpaThrottle = currentControlRateProfile->throttle.pa_breakpoint + (uint16_t)((airspeed - referenceAirspeed) / referenceAirspeed * (currentControlRateProfile->throttle.pa_breakpoint - getThrottleIdleValue()));
+if (referenceAirspeed > 0) {
+    tpaThrottle = currentControlRateProfile->throttle.pa_breakpoint + (uint16_t)((airspeed - referenceAirspeed) / referenceAirspeed * (currentControlRateProfile->throttle.pa_breakpoint - getThrottleIdleValue()));
+} else {
+    // Fallback to regular throttle if reference airspeed is not configured
+    tpaThrottle = rcCommand[THROTTLE];
+}

---

Suggestion 4:

[possible issue] Fix the airspeed calculation in `crsfFrameAirSpeedSensor` by using floating-point division (e.g., `36.0f / 100.0f`) to prevent the expression from evaluating to zero.

---

Suggestion 5:

[possible issue] Correct the current limit calculation formula. The formula should be `battery_capacity_mAh × C_rating / 100` to yield a result in deci-amps (dA), not amps.

---

[Auto-generated best practices - 2026-06-03]