PX4-Autopilot/.github/instructions/src.drivers.instructions.md

---
applyTo: "src/drivers/**"
---

# PX4 Driver Review Instructions

This file provides guidelines for reviewing driver files in the `src/drivers/` directory.

## Copyright Statements

### Required Files

All source files (`.cpp`, `.c`, `.hpp`, `.h`, `CMakeLists.txt`) MUST include a copyright statement at the top.

**Exceptions:** 
- `Kconfig` files
- `module.yaml` files

### Copyright Format

**For new files (created in 2026):**
```cpp
/****************************************************************************
 *
 *   Copyright (c) 2026 PX4 Development Team. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 * 3. Neither the name PX4 nor the names of its contributors may be
 *    used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 ****************************************************************************/
```

**For updated files (originally created in 2015, updated in 2026):**
```cpp
/****************************************************************************
 *
 *   Copyright (c) 2015-2026 PX4 Development Team. All rights reserved.
 *
 * [... rest of copyright text ...]
 *
 ****************************************************************************/
```

### Key Points
- First year should be the original creation year
- When updating an existing file, update the year range: `YYYY-2026`
- Use the current year (2026 in this case) for new files
- Maintain consistent formatting with other PX4 driver files

---

## Driver Self-Documentation

All drivers MUST be self-documenting through the `print_usage()` method.

### Required Implementation

Every driver `.cpp` file must implement a `print_usage()` method that includes:

1. **PRINT_MODULE_DESCRIPTION macro** - Contains markdown documentation
2. **Module identification** - Using PRINT_MODULE_USAGE_NAME and optionally PRINT_MODULE_USAGE_SUBCATEGORY
3. **Parameter documentation** - Relevant parameters, especially enablement parameters

### PRINT_MODULE_DESCRIPTION Structure

The description should follow this markdown format:

```cpp
PRINT_MODULE_DESCRIPTION(
    R"DESCR_STR(
### Description
[Clear description of what the driver does and its primary functionality]

### Implementation
[Optional: High-level overview of how the driver works]

### Examples
[Optional: CLI usage examples if non-trivial]
$ module_name start -d /dev/ttyS1
$ module_name stop

)DESCR_STR");
```

### Required Sections

#### 1. Description Section
- Brief explanation of the driver's purpose
- Key features/capabilities
- Important parameters (especially enable parameters like `SENS_XX_CFG`)

#### 2. Documentation Links
When applicable, include links to user documentation:
```cpp
Setup/usage information: https://docs.px4.io/main/en/sensor/[sensor-name].html
```

#### 3. Examples Section (when relevant)
Provide CLI usage examples for non-trivial commands:
```cpp
### Examples
Attempt to start driver on a specified serial device.
$ vectornav start -d /dev/ttyS1
Stop driver
$ vectornav stop
```

### Complete Example

```cpp
int MyDriver::print_usage(const char *reason)
{
    if (reason) {
        PX4_WARN("%s\n", reason);
    }

    PRINT_MODULE_DESCRIPTION(
        R"DESCR_STR(
### Description
This driver interfaces with the XYZ sensor via I2C/SPI. It provides
distance measurements and is automatically started when SENS_XYZ_CFG
is set to the appropriate value.

Key features:
- Distance range: 0.2m to 50m
- Update rate: up to 100Hz
- I2C and SPI support

Setup/usage information: https://docs.px4.io/main/en/sensor/xyz_sensor.html

### Examples
Start driver on I2C bus 1 with address 0x29:
$ xyz_sensor start -X -b 1 -a 0x29
)DESCR_STR");

    PRINT_MODULE_USAGE_NAME("xyz_sensor", "driver");
    PRINT_MODULE_USAGE_SUBCATEGORY("distance_sensor");
    PRINT_MODULE_USAGE_COMMAND("start");
    PRINT_MODULE_USAGE_PARAMS_I2C_SPI_DRIVER(true, true);
    PRINT_MODULE_USAGE_PARAMS_I2C_ADDRESS(0x29);
    PRINT_MODULE_USAGE_DEFAULT_COMMANDS();

    return 0;
}
```

### Common Patterns by Driver Type

**For UART/Serial Drivers:**
```cpp
PRINT_MODULE_USAGE_PARAM_STRING('d', "/dev/ttyS3", "<file:dev>", "Serial device", true);
```

**For I2C/SPI Drivers:**
```cpp
PRINT_MODULE_USAGE_PARAMS_I2C_SPI_DRIVER(true, true);
PRINT_MODULE_USAGE_PARAMS_I2C_ADDRESS(0x76);
```

**For Sensor Drivers:**
```cpp
PRINT_MODULE_USAGE_SUBCATEGORY("distance_sensor");  // or imu, magnetometer, etc.
```

---

## Review Checklist

When reviewing driver files, verify:

- [ ] Copyright header is present (except Kconfig and module.yaml)
- [ ] Copyright year is correct (current year for new files, year range for updates)
- [ ] `print_usage()` method exists
- [ ] `PRINT_MODULE_DESCRIPTION` macro is present with markdown content
- [ ] Description section explains driver purpose clearly
- [ ] Relevant parameters are documented (especially enable parameters)
- [ ] Documentation links are included when available
- [ ] Examples are provided for complex CLI usage
- [ ] Module name and category are correctly specified
- [ ] Standard commands (start, stop, status) are documented

---

## Additional Resources

- Driver template examples: `src/drivers/*/` (various sensor types)
- Module macros: `platforms/common/include/px4_platform_common/module.h`
- Similar drivers for reference patterns (DShot, VectorNav, CrsfRc, etc.)