Skip to content
This repository has been archived by the owner on Mar 17, 2021. It is now read-only.

UPstreaming a new port #654

Merged
merged 5 commits into from
Dec 2, 2018
Merged

UPstreaming a new port #654

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7d287f9
Add section on accepting boards
hamishwillee Nov 19, 2018
9aad894
Update text to be more friendly
hamishwillee Nov 20, 2018
c19081f
Fixes due to feedback from Ramon
hamishwillee Nov 20, 2018
2e5be0f
Add link to support forums
hamishwillee Nov 20, 2018
846a6f9
Update board acceptance following feedback
hamishwillee Dec 2, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions en/hardware/porting_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,3 +80,24 @@ It is generally recommended to connect RC via separate RX and TX pins to the mic
If however RX and TX are connected together, the UART has to be put into singlewire mode to prevent any contention.
This is done via board config and manifest files.
One example is [px4fmu-v5](https://github.com/PX4/Firmware/blob/master/src/drivers/boards/px4fmu-v5/manifest.c).


## Accepting a Board into PX4 Codelines
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure about the word "Codelines", I've been thinking about this and I think we should call it "Officially supported hardware", "How to get your port officially supported", where "official support" means:

  • Get your code in the PX4 repository
  • CI auto firmware builds
  • Accessible firmware builds from QGC
  • Compatibility with the rest of the ecosystem

Copy link
Collaborator Author

@hamishwillee hamishwillee Nov 21, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, how about (reorganised):

Officially Supported Hardware

The PX4 project supports and maintains the FMU standard reference hardware and any boards that are compatible with the standard.
This includes the Pixhawk-series (see the user guide for a full list of officially supported hardware).

Every officially supported board benefits from:

  • 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
  • Flight testing

We encourage board manufacturers to aim for full compatibility with the FMU spec.
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.

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).

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 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 [email protected] for guidance on where to ship hardware for testing).
  • The board must pass full test suite and flight testing.

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 Forums and Chat.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@hamishwillee

Port source code available in the PX4 repository

I do not know how to parse this sentence.

"Port: is an overloaded term in CS. The act of porting PX4 to new hardware is a "PX4 Port" to XYZ HW or a Port of PX4 to XYZ hardware.

Typically a Board Support Packages (BSP) is created to facilitate porting. PX4 does not use that term, but in essence that is what it is.

Is this what you are saying: Board Support source code available in the PX4 repository ?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@davids5 Actually that was Ramon's text, but I interpret it as "PX4 Port available in the PX4 repository" and have changed appropriately above.

Is it otherwise OK?

@mrpollo And is it OK for you. If so I can merge this into the PR and merge the PR. (Ie what else to happen?)

Note that some of this might need to be moved around/reused in future. The reason being that if we explain base porting in the context of the different types of porting you might want to do (ie what lets you remain compatible) then we may need to explain the benefits of compatibility earlier. We will see.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lets merge his 👍


Manufacturers may wish to contribute board ports to the PX4 project codeline in order more closely align with the project
(accepted boards are more regularly and rigorously tested as part of the regular flight testing and continuous build process, and any software compatibility issues are therefore discovered earlier).

> **Note** The sole responsibility for maintaining an accepted board lies with the manufacturer!
mrpollo marked this conversation as resolved.
Show resolved Hide resolved
Failure to maintain a board will lead to its removal from upstream support.

The PX4 project provides free support for the Pixhawk-series FMU standard reference hardware (and by extension, other boards that are 100% compatible with the standard).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Slight edit, let me know what you think

The PX4 project supports and maintains the FMU standard reference hardware and any boards that are compatible with the standard, this includes the Pixhawk-series (see our docs for a full list of supported hardware).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line got deleted anyway.The story we want to tell is not "what we support" but "what we want you go support" so I figured we could lose it.

If you disagree, add it back in. Note, is the FMU standard the correct name? Terminology a bit confused for me.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Terminology is confusing, but FMU is a standard, what other ways we have been calling it lately?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also like the note about PX4 supporting and maintaining the FMU standard, perhaps this should be in the FMU section

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll add it back in a second. I guess it is part of "what we do for you", but it makes things less succinct.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree with @mrpollo , the support is not "free", the engineering incurs on/absorbed by someone; the manufacturer should understand that.

We have many "standards" here, FMU is standard, Pixhawk is also standard, we need a better description of the inter-relationships of the standards.

We do not have resource for ongoing maintenance for deviations or other board variants.
Therefore, before being accepted into our codelines, manufacturers must commit to any recurring maintenance costs, including hardware testing.
mrpollo marked this conversation as resolved.
Show resolved Hide resolved

In order to be considered for acceptance, the board must be:
* Available in the market.
* Supplied to the PX4 dev/test team for testing (contact [email protected] for guidance on where to ship hardware).
* Pass full test suite and flight testing.
mrpollo marked this conversation as resolved.
Show resolved Hide resolved

The project reserves the right to refuse acceptance for boards, in particular if deviations from the FMU standard are too great.
The project will also remove boards that are not adequately maintained by their sponsor.
hamishwillee marked this conversation as resolved.
Show resolved Hide resolved