* docs(hardware): rewrite board support guide around real process
The board support guide described a theoretical category-first process that
no longer matches how board support actually happens. Manufacturers were
left unsure of the concrete steps, leading to repeated email requests for
guidance.
Restructure the guide around the actual GitHub-driven flow: build your own
firmware target, reserve a board ID via a PX4-Bootloader PR, provide a
unique USB VID/PID, demonstrate flight with logs, and open the PR. Keep the
support categories as a reference section that explains support
responsibility rather than process.
Spell out that QGroundControl uses the USB VID/PID to identify hardware, and
warn that reusing another vendor's pair causes misidentification. Promote
the ArduPilot board-ID alignment note and point it at the current hwdef
location. Demote VER/REV ID to a clearly-deprecated edge case: explain the
resistor/EEPROM mechanism and its original cross-vendor baseboard/FMU intent,
note the ecosystem has deviated from it, and that Dronecode no longer offers
standards validation. Update the Discord link to chat.dronecode.org.
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
* docs(hardware): align porting guide with board support guide
The porting guide's 'Officially Supported Hardware' section restated the
board support process and contradicted the rewritten board support guide.
It also told manufacturers to ship hardware to the dev team for port
validation, a service Dronecode no longer offers.
Replace that section with a short pointer to the board support guide, which
is now the single source of truth for the support process, and keep only the
high-level support benefits and maintenance expectations. The technical
porting content (architecture, file layout, host OS config, RC UART wiring)
is unchanged.
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
* docs(hardware): make board support guide discoverable for manufacturers
The board support guide was only reachable by navigating into the hardware
integration section. A manufacturer browsing the user-facing autopilot pages,
the exact audience, had no path to it, and one of those pages still stated
the obsolete 4-month compatibility commitment.
Add 'how to get your board supported' pointers from the manufacturer-supported
and experimental autopilot pages, the flight controller index, and the
development landing page. Remove the stale 4-month rule from the
manufacturer-supported page. Strengthen the guide's opening paragraph so the
phrases manufacturers actually search appear up front.
Word the links to avoid conflating the guide (how to get a board supported)
with the 'Manufacturer Supported' category (one of several support levels).
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
* docs(docs): Minor tweaks
---------
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
**Are you a manufacturer who wants to get a board supported by PX4?** See the [Manufacturer's Board Support Guide](../hardware/board_support_guide.md).
:::
::: tip
For more information about PX4 project autopilot board support levels see: [px4.io/autopilots/](https://px4.io/autopilots/).
Manufacturer-supported autopilots are maintained and supported by a board manufacturer (manufacturers commit to delivering compatibility with the current stable PX4 release within 4 months of the official release announcement).
Manufacturer-supported autopilots are maintained and supported by a board manufacturer, who owns support for the board and keeps it working across PX4 releases.
::: tip
**Are you a manufacturer who wants to get a board supported by PX4?** See the [Manufacturer's Board Support Guide](../hardware/board_support_guide.md). It covers the process for all support levels, not just this category.
:::
::: tip
For more information about PX4 project autopilot board support levels see: [px4.io/autopilots/](https://px4.io/autopilots/).
@@ -18,6 +18,10 @@ Information about how to choose a PX4-compatible flight controller and the avail
There may be other [Pixhawk Series](../flight_controller/pixhawk_series.md) compatible flight controllers and variants, including those [documented here on Github](https://github.com/PX4/PX4-Autopilot/#supported-hardware).
:::
::: tip
**Hardware manufacturers:** to get a new flight controller supported by PX4, see the [Manufacturer's Board Support Guide](../hardware/board_support_guide.md).
:::
## Flight Controller Mounting and Setup
Information about how to mount the flight controller, upload firmware (replacing an incompatible bootloader if needed), and configure its internal sensors and orientation:
The PX4 development and test teams fully support and maintain boards that are compliant with the [Pixhawk Standard](https://pixhawk.org/standards/).
Manufacturers who wish to deviate from the standard or create completely new boards can do so, but will need to support any resulting compatibility differences.
This guide explains how to get your hardware supported by PX4: added to the PX4 codebase, listed on the PX4 website, and available to users in QGroundControl.
If you are a hardware manufacturer looking to add a flight controller or peripheral to PX4, or to port PX4 to a new board, start here.
This guide outlines the [general requirements](#general_requirements) for board support, along with the additional requirements for the different [board support categories](#board-support-categories).
The process is **open and driven through GitHub**.
You do not need permission or a private agreement to start.
When your hardware works with PX4 and you can prove it, you open a pull request, and the maintainers review it in the open.
There is no application form and no waiting on an assignment before you can begin.
The path depends on what you are bringing to PX4:
- [Adding a Flight Controller](#flight-controllers) explains the steps for a **new board that runs PX4**.
- [Adding a Component](#components) explains how to get support for a **peripheral or component** (GPS/RTK receiver, compass, data link, distance sensor, etc.).
::: info
Boards that are not compliant with the requirements are [unsupported](#unsupported); they will not be listed on the PX4 website hardware list and will be removed from the codebase.
If you only want to know _what_ each support level commits the PX4 team to (versus what you maintain yourself), see [Support Categories](#support-categories) at the end.
:::
<a id="general_requirements"></a>
## Adding a Flight Controller {#flight-controllers}
## General Requirements
### 1. Build your own Firmware Target
The general requirements for all supported boards are:
The recommended approach for any new flight controller is to **maintain your own board build target based on PX4**, rather than trying to reuse an existing FMU target.
1. The hardware must be available in the market.
1. The boards may not have blocking hardware bugs or unacceptable quality that make it impossible or dangerous to use the board with PX4 on a UAV.
Board needs to pass acceptance criteria to ensure quality of parts and assembly.
1. A clear and easy way to contact customer support for customers.
One or more of the following is accepted:
- PX4 Discord server presence
- Support email
- Phone number
This applies even if your board is electrically close to an FMUv5X or FMUv6X design.
As soon as you change the sensor set, connectors, or other peripherals, you should have your own target.
It gives you a stable place to express your hardware's configuration and keeps you in control of your own board.
1. Point of contact (PoC) for the PX4 maintainers (direct email or available in Slack/Forum/Github)
1. The board needs to use the [PX4 bootloader protocol](https://github.com/PX4/PX4-Autopilot/tree/main/platforms/nuttx/src/bootloader).
For more information on bootloaders see: [PX4 Nuttx Porting Guide > Bootloader](../hardware/porting_guide_nuttx.md#bootloader).
1. Adequate documentation, which includes, but is not limited to:
- A complete pinout made available publicly that maps PX4 pin definitions to:
1. Microcontroller pins
2. Physical external connectors
- A block diagram or full schematic of the main components (sensors, power supply, etc.) that allows to infer software requirements and boot order
- A manual of the finished product detailing its use
Start by reading the porting guides:
1. There must be a dedicated webpage for the board with PX4, which lists the features and limitations for usage with PX4, and includes or links to the above described documentation.
Good real-world examples of manufacturer board targets to model yours on:
The board support categories are listed below. The autopilot boards in each category are listed at: [https://px4.io/autopilots/.](https://px4.io/autopilots/)
Manufacturer supported boards may be as well/better supported than Pixhawk boards (for example through economies of scale).
**If your board will also run ArduPilot, reserve the _same_ board ID in both bootloaders.**
Open a matching PR against [ArduPilot](https://github.com/ArduPilot/ardupilot) (board IDs live in the `hwdef` definitions under [`libraries/AP_HAL_ChibiOS/hwdef`](https://github.com/ArduPilot/ardupilot/tree/master/libraries/AP_HAL_ChibiOS/hwdef)) and use the identical board ID value there.
Keeping the two aligned avoids a class of confusing flashing and identification problems where the same physical board reports different IDs depending on which firmware it is running.
:::
## Pixhawk Standard
### 3. Sort Out your USB VID/PID
A Pixhawk board is one that conforms to the Pixhawk standards. These standards are laid out on [pixhawk.org](https://pixhawk.org/), but at high-level require that the board passes electrical tests mandated by the standard and the manufacturer has signed the Pixhawk adopter and trademark agreement.
If your board exposes USB, it needs a USB Vendor ID (VID) and Product ID (PID).
PX4 generally only supports boards that are commercially available, which typically means that board standards released within the last five years are supported.
The VID/PID pair is how QGroundControl recognizes your hardware over USB.
It is what lets QGC match the connected board to the right firmware and present it correctly to the user.
The pair must be unique to your product.
### VER and REV ID (Hardware Revision and Version Sensing) {#ver_rev_id}
FMUv5 and onwards have an electrical sensing mechanism.
This sensing coupled with optional configuration data will be used to define hardware’s configuration with respect to a mandatory device and power supply configuration. Manufacturers must obtain the VER and REV ID from PX4 board maintainers by issuing a PR to amend the [DS-018 Pixhawk standard](https://github.com/pixhawk/Pixhawk-Standards) for board versions and revisions.
Because these boards are 100% compliant with the Pixhawk standard, the values assigned for VER and REV ID are the defaults for that FMU Version.
## Manufacturer Supported
These boards are supported by the manufacturer.
To qualify for this category the board must work with the latest stable PX4 release within 4 months of that release.
- Manufacture owns the support
- Manufacturer must supply at least 2 boards to the core-dev team (for use on test rack and by test team)
:::tip
While there is no commitment from the PX4 maintainers and the flight test team to support and test boards in this category, we strongly recommended PX4 and manufacturer teams build close working relationships.
This will result in a better result for all parties.
::: warning
**Do not copy another manufacturer's VID/PID.** If your board reports a VID/PID that belongs to someone else's hardware, QGroundControl will misidentify it, associate it with the wrong board, and may offer or flash the wrong firmware.
Each board needs its own identity.
:::
::: info
These boards will be assigned [VER and REV ID](#ver_rev_id) based on compatibility.
A special assignment will be made by PX4 if the board is a variant of an FMU specification and capable of running the same binary, with minor differences supported by the manufacturer.
Contact the PX4 maintainer at [boards@px4.io](mailto:boards@px4.io) to request more information.
You have two ways to get a valid pair:
- **Provide your own.** As the hardware manufacturer, the VID/PID identify _your_ company and product, and you are expected to obtain them yourself.
- **Use the Dronecode VID.** [Dronecode Foundation members](https://dronecode.org/membership/) can request a PID allocated under the Dronecode USB VID.
This is one of the membership benefits, alongside access to the Pixhawk FMU reference schematics.
If you would like to use the Dronecode VID, [become a member](https://dronecode.org/membership/) first.
### 4. Fly it and Capture Logs
**Bench testing is not enough.** Before a flight controller is accepted, you must demonstrate stable flight on the current PX4 release with your hardware.
Capture flight logs from that testing and upload them to [logs.px4.io](https://logs.px4.io).
You will link these in your pull request so the maintainers can review the flight data alongside your code.
### 5. Open the Pull Request
Open a pull request against [PX4/PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) containing:
- Your board support code (the build target from step 1).
- Board documentation: a public pinout mapping PX4 pin definitions to the microcontroller pins and physical connectors, plus a block diagram or schematic of the main components (sensors, power supply) sufficient to understand boot order and software requirements.
- **Links to your flight logs** from step 4, in the PR description, as proof the hardware has actually been flown.
If you have never contributed via GitHub, follow the [documentation contribution guide](../contribute/docs.md) for the mechanics of forking, branching, and opening a PR.
::: tip
A clean, reviewable commit history makes a real difference.
Split your work into logical commits rather than one large dump, and engage early on Discord if you have questions.
The most common reasons first-time board PRs stall are incomplete documentation and missing or insufficient flight-test evidence.
:::
## Experimental
### 6. Maintain It {#maintain}
These boards are all boards that don't fall in the above categories, or don't fall in those categories _anymore_.
The following requirements apply:
Once your board is merged, you own it.
That means:
-The board must be working with at leastone PX4 release for a defined vehicle type, but not necessarily the latest release.
-Handling support questions from your own customers.
- Keeping your board target building and working as PX4 evolves across releases.
- Responding to issues and regressions specific to your hardware.
::: info
Experimental boards that were _previously_ Pixhawk or Manufacturer supported will have/retain their original IDs.
_New_ experimental boards are allocated [VER and REV IDs](#ver_rev_id) based on compatibility, in the same way as Manufacturer Supported boards.
You are not expected to fix unrelated PX4 bugs, but you are expected to maintain what you contribute.
Boards that fall out of maintenance and stop building may be moved to [experimental](#support-categories) or removed.
## Adding a Component {#components}
For peripherals that work _with_ a flight controller, GPS/RTK receivers, compasses, data links, distance sensors, and similar, the path is lighter.
There is no board ID or firmware target involved.
1.**Validate** that your product works with PX4.
A few simple flights are enough.
2.**Edit the relevant documentation page** to add your product, for example the [GPS & Compass](../gps_compass/index.md) or [RTK GPS](../gps_compass/rtk_gps.md) page for a GNSS product.
3.**Open a pull request** against [PX4/PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) with your documentation changes.
4.**Attach proof** of step 1 (flight logs, linked or uploaded to [logs.px4.io](https://logs.px4.io)) in the PR description, so the maintainers can review it alongside your edits.
New to GitHub? The [documentation contribution guide](../contribute/docs.md) covers the whole flow.
## Support Categories {#support-categories}
These categories describe **who is responsible for supporting a board**, the PX4 team or the manufacturer, and whether it is listed on the PX4 website.
They do not change the steps above.
The boards in each category are listed at [px4.io/autopilots](https://px4.io/autopilots/).
### Pixhawk Standard
Boards that conform to the [Pixhawk standards](https://pixhawk.org/standards/).
These are fully supported and maintained by the PX4 development and test teams.
Qualifying requires passing the electrical tests mandated by the standard and signing the Pixhawk adopter and trademark agreement.
PX4 generally supports standards released within the last few years, since those are what is commercially available.
For examples, see [Pixhawk Standard Autopilots](../flight_controller/autopilot_pixhawk_standard.md).
### Manufacturer Supported
Boards supported by the manufacturer, the category most new flight controllers fall into.
The manufacturer owns support and keeps the board working across PX4 releases, as described in [Maintain it](#maintain) above.
These boards can be as well supported as Pixhawk boards.
There is no formal support or test commitment from the PX4 team, but a close working relationship between the manufacturer and PX4 teams benefits everyone.
For examples, see [Manufacturer-Supported Autopilots](../flight_controller/autopilot_manufacturer_supported.md).
### Experimental
Boards that work with at least one PX4 release for a defined vehicle type, but not necessarily the latest, and are not actively maintained to either of the above standards.
Previously supported boards that fall out of active maintenance land here.
For examples, see [Experimental Autopilots](../flight_controller/autopilot_experimental.md).
### Unsupported
Boards that meet none of the above.
Typically: boards that would take minimal effort to reach "experimental" but that nobody, manufacturer or dev team, is currently pursuing; hardware whose owner has violated the [Code of Conduct](https://discuss.px4.io/t/px4-community-code-of-conduct/13655); designs whose required tools/libraries/drivers are blocked by incompatible licensing; or boards that do not meet the general requirements above.
Unsupported boards are not listed on the PX4 website and may be removed from the codebase.
**This path is no longer recommended.** New manufacturers should build their own firmware target ([step 1](#1-build-your-own-firmware-target)) instead.
This section is kept for context and for the few boards that still depend on the mechanism.
:::
## Unsupported
VER/REV ID is a sensing mechanism on FMUv5X and later.
The board encodes its version and revision either through resistor dividers read on dedicated sensing pins, or through values stored in an onboard EEPROM.
PX4 reads these at boot and uses them, together with the standard configuration, to determine the expected device and power-supply layout for that FMU version.
This category includes all boards that aren't supported by the PX4 project or a manufacturer, and that fall outside the"experimental" support.
It was originally designed to allow **cross-vendor compatibility between baseboards and FMU modules**: the idea being that a standard FMU module from one vendor could drop into a standard baseboard from another and run the same binary, with the VER/REV ID telling the firmware which hardware combination it was on.
The VER/REV ID values were coordinated centrally with the PX4 board maintainers (historically by a PR against the [DS-018 Pixhawk standard](https://github.com/pixhawk/Pixhawk-Standards)) so that assignments stayed unique across vendors.
- Board is somewhat compatible on paper with something we already support, and it would take minimal effort to raise it to "experimental", but neither the dev-team or the manufacturer are currently pursuing this
- Manufacturer/Owner of hardware violates our [Code of Conduct](https://discuss.px4.io/t/px4-community-code-of-conduct/13655)
- Closed source, where any of the necessary tools/libs/drivers/etc needed to add support for a board is deemed incompatible due to licensing restrictions
- Board doesn't meet minimum requirements outlined in the General requirements
In practice the ecosystem has **deviated from that model**.
Modern boards differ enough in sensors, connectors, and peripherals that the shared-binary, drop-in-module assumption rarely holds, and maintaining your own firmware target has become the cleaner and more reliable approach.
For that reason:
::: info
Unsupported boards will NOT be assigned [VER and REV ID](#ver_rev_id) (and cannot run PX4 FMUvX firmware).
:::
- We **no longer recommend** that manufacturers go through the VER/REV ID path.
Build your own firmware target ([step 1](#1-build-your-own-firmware-target)) instead.
It applies to nearly all new hardware, and is required as soon as you deviate from a published FMU sensor set in any way.
- The Dronecode team is **not currently offering validation services** to certify that a board meets the FMU standard for the purpose of obtaining a default VER/REV ID assignment.
## Release Process
## Getting Help
It is assumed that when a manufacturer declares that a board falls in a certain category, that the board is compliant with the requirements for that category and the general requirements.
The board support process improves over time, and contributions to the process itself are welcome.
When a new board is brought to market that falls into the manufacturer supported or experimental category, the manufacturer is responsible for updating the PX4 documentation and doing the board release process in PX4. We recommend the following steps:
- Ask the community on the PX4 [Discord](https://chat.dronecode.org) under the `Hardware` channels, or on the [discuss forum](https://discuss.px4.io/).
- Join the regular hardware call.
- Consultancy options are listed at [px4.io/community/consultants](https://px4.io/community/consultants/).
Contact PX4 board maintainers at [boards@px4.io](mailto:boards@px4.io) and request the following:
1. The assignment of a _board id_ for bootloader and firmware selection in QGC.
2. The assignment of REV and VER ID resistor values.
3. If the board supports USB: Either request the assignment of a USB VID and PID or provide the USB VID and PID.
Integrate the board according to the board porting release process described in the [porting guide](../hardware/porting_guide.md)
:::warning
The board support process may be changed and improved over time.
Hardware manufacturers are encouraged to contribute to this process through the regular hardware call, the Discuss forum or Discord.
:::
## Support
If parts of the board support guide/process are not clear:
- Ask the community for help on Discord channels under `Hardware` category, or on the discuss forum
- Attend the regular hardware call
- Consultancy options are listed here: [https://px4.io/community/consultants/](https://px4.io/community/consultants/)
If you need direct coordination that cannot happen in a pull request, for example sorting out a board ID conflict, you can reach the maintainers at [boards@px4.io](mailto:boards@px4.io). Use this as a last resort: anything that can happen in the open on GitHub should.
@@ -4,7 +4,8 @@ This topic is for developers who want to port PX4 to work with _new_ flight cont
## PX4 Architecture
PX4 consists of two main layers: The [board support and middleware layer](../middleware/index.md) on top of the host OS (NuttX, Linux or any other POSIX platform like Mac OS), and the applications (Flight Stack in [src/modules](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules)\). Please reference the [PX4 Architectural Overview](../concept/architecture.md) for more information.
PX4 consists of two main layers: The [board support and middleware layer](../middleware/index.md) on top of the host OS (NuttX, Linux or any other POSIX platform like Mac OS), and the applications (Flight Stack in [src/modules](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules)\).
Please reference the [PX4 Architectural Overview](../concept/architecture.md) for more information.
This guide is focused only on the host OS and middleware as the applications/flight stack will run on any board target.
@@ -54,39 +55,25 @@ If however RX and TX are connected together, the UART has to be put into singlew
This is done via board config and manifest files.
One example is [px4fmu-v5](https://github.com/PX4/PX4-Autopilot/blob/main/boards/px4/fmu-v5/src/manifest.c). <!-- NEED px4_version -->
## Officially Supported Hardware
## Getting Your Board Supported
The PX4 project supports and maintains the [FMU standard reference hardware](../hardware/reference_design.md) and any boards that are compatible with the standard.
This includes the [Pixhawk-series](../flight_controller/pixhawk_series.md) (see the user guide for a [full list of officially supported hardware](../flight_controller/index.md)).
This page covers the _technical_ work of porting PX4 to new hardware.
The _process_ for getting that port reviewed, merged, and listed on the PX4 website, including board IDs, USB VID/PID, flight-test evidence, and maintenance expectations, is documented separately:
Every officially supported board benefits from:
- [Manufacturer's PX4 Board Support Guide](../hardware/board_support_guide.md)
- PX4 Port available in the PX4 repository
- Automatic firmware builds that are accessible from _QGroundControl_
- Compatibility with the rest of the ecosystem
- Automated checks via CI - safety remains paramount to this community
In short: build your own firmware target based on PX4, demonstrate stable flight on the current release, and open a pull request with your board support code, documentation, and flight logs.
The board support guide explains each step.
We encourage board manufacturers to aim for full compatibility with the [FMU spec](https://pixhawk.org/).
With full compatibility you benefit from the ongoing day-to-day development of PX4, but have none of the maintenance costs that come from supporting deviations from the specification.
The PX4 project supports and maintains the [FMU standard reference hardware](../hardware/reference_design.md) and any boards compatible with the standard, including the [Pixhawk series](../flight_controller/pixhawk_series.md) (see the [full list of supported hardware](../flight_controller/index.md)). Boards merged into PX4 benefit from a port in the repository, firmware builds accessible from _QGroundControl_, compatibility with the rest of the ecosystem, and automated CI checks.
:::tip
Manufacturers should carefully consider the cost of maintenance before deviating from the specification (the cost to the manufacturer is proportional to the level of divergence).
The cost of maintaining a port is proportional to how far it diverges from the standard.
Consider that cost before deviating: staying close to the reference design lets you benefit from day-to-day PX4 development with minimal maintenance burden.
:::
We welcome any individual or company to submit their port for inclusion in our supported hardware, provided they are willing to follow our [Code of Conduct](https://github.com/PX4/PX4-Autopilot/blob/main/CODE_OF_CONDUCT.md) and work with the Dev Team to provide a safe and fulfilling PX4 experience to their customers.
It's also important to note that the PX4 dev team has a responsibility to release safe software, and as such we require any board manufacturer to commit any resources necessary to keep their port up-to-date, and in a working state.
If you want to have your board officially supported in PX4:
- Your hardware must be available in the market (i.e. it can be purchased by any developer without restriction).
- Hardware must be made available to the PX4 Dev Team so that they can validate the port (contact [lorenz@px4.io](mailto:lorenz@px4.io) for guidance on where to ship hardware for testing).
- The board must pass full [test suite](../test_and_ci/index.md) and [flight testing](../test_and_ci/test_flights.md).
**The PX4 project reserves the right to refuse acceptance of new ports (or remove current ports) for failure to meet the requirements set by the project.**
You can reach out to the core developer team and community on the [official support channels](../contribute/support.md).
Manufacturers are responsible for keeping their port up to date and working across PX4 releases.
The PX4 project reserves the right to refuse or remove ports that do not meet the project's requirements, and all contributors are expected to follow the [Code of Conduct](https://github.com/PX4/PX4-Autopilot/blob/main/CODE_OF_CONDUCT.md).
## Related Information
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Ramon Roche