UPstreaming a new port #654
Conversation
|
@davids5 would be able to contribute here :) |
|
@hamishwillee - how about we have a call and I can share the Nuttx side from the bottom up and top down and you can distill it into what you feel best will communicate the requirements. |
|
Hey @davids5 lets have that meeting in a time zone that works for Hamish and invite @dagar, I think #651 started with the necessity to document our current process, in hopes of making it clear who we are and how we work, next up is to define that in more detail, your proposed meeting would be great. Next, we need to determine if we are happy with the current process and if there are any improvements we would like to make. |
There was a problem hiding this comment.
Overall your PR captures what @LorenzMeier covered on #651, while I agree with everything Lorenz said, I do believe there's room for misinterpretation, I think the changes I propose help set the right tone and clarify most of Lorenz points.
en/hardware/porting_guide.md
Outdated
| @@ -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 | |||
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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 ?
There was a problem hiding this comment.
@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.
en/hardware/porting_guide.md
Outdated
| > **Note** The sole responsibility for maintaining an accepted board lies with the manufacturer! | ||
| 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). |
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Terminology is confusing, but FMU is a standard, what other ways we have been calling it lately?
There was a problem hiding this comment.
I also like the note about PX4 supporting and maintaining the FMU standard, perhaps this should be in the FMU section
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
|
Thanks Ramon, that’s helpful - my comments were not intended to go into official documentation - the tone was way to colloquial and as you say, not welcoming enough in this context. |
|
All, I've included @mrpollo text and given a light subedit. Yes, a lot less intimidating :-). Please review.
@davids5 , that would be great. Yes, probably good to invite @dagar too. Most of his timeslots that work for me are at 8 am AEST (Melbourne/Sydney time). What times work for you/Where are you based now? |
|
Can you add a note towards the end on how to get in touch with the dev team, perhaps point them to where in the docs this is covered, discuss/slack/github, etc. Its important users know how to make the first contact with a maintainer. |
I disagree with this. We introduce the dev team on the very front page: http://dev.px4.io/en/#support |
|
You are overthinking this, just link to the Forums & Page section, no need to duplicate content, a simple link is enough.
|
No I am not. But it isn't worth my time to argue. |
|
I agree that you could argue the same for every other page, but I don't think that's a valid argument. For this page and section specifically I think it's needed, manufacturers are a different type of audience for the guide, they might not always employ in-house developers who would otherwise know how to look for these things. |
|
Unconvinced, but it does no particular harm. Is this the right place in the article for the content? I think so. |
|
response placement: I think so too, it flows naturally towards the end. |
|
OK, ready to merge then? |
|
Working on making it slightly easier - PX4/PX4-Autopilot#10875 |
|
@hamishwillee 8 am AEST is 2:00 PST which works for me. @dagar @mrpollo does that work for you? |
|
8:00 am AEST works tomorrow, 8:30 am AEST | 2:30 PST works better for me today. |
@hamishwillee @dagar I am fine with today or tomorrow at @mrpollo times. So whatever works best for you both, is good with me. |
|
I'm guessing it's going to be tomorrow since its too short notice for @hamishwillee, let us know if tomorrow works for you or some other day! |
|
@davids5 @dagar @mrpollo Yes, 8am tomorrow morning AEST works for me. Ramon, can you set up a zoom meeting and send out an invite? Agenda:
Basically, I would like to understand tasks need to be done to go from start to end.
Do we need to wait until PX4/PX4-Autopilot#10875 goes in - how much easier and different will things be after that is in place. |
|
@hamishwillee - we confirmed on the dev call today that we are confirmed for 2:00 PST / 8am AEST today, @mrpollo can you set up a zoom meeting and send out an invite? |
|
Thank you! @mrpollo |
|
FYI All, had a meeting with @davids5 @dagar today. Sent notes to @mrpollo and those guys. We're going to pause the docs work until PX4/PX4-Autopilot#10875 goes in and think a bit more about what can and cannot be done to improve the overall process. [A few things that are clear to me are that you don't have to go very far before you need to know quite a lot about NuttX, and that what is included in our ports as "configurable" is quite limited. It might be good if we included more common configuration options as part of the reference definition] An aside conversation we had was that many of the relevant docs in an FMU definition are in google docs/spreadsheets and are hence not properly versioned, linked or searchable. They are also cases where a non native speaker might misinterpret things (e.g. an instruction to do "either/or" might be taken as "both"). Upshot, it would be good if we can keep versions and all associated docs as a versioned copy (e.g. PDF, MSWord etc) in github, provide changelog as per the pinout legend for all docs, and ideally translate the docs for each revision (e.g. to Chinese). The "working" docs might still be a google doc, but that shouldn't be the official revision. |
|
What does this mean to this PR? |
Nothing. What needs to happen is for you to tell me if you are OK with my text in #654 (comment) , I put that into the PR properly, and then we merge. |
|
PX4/PX4-Autopilot#10875 is merged, is this one ready to PR and merge as well? |
|
OK, so I will merge the text in #654 (comment) By early next week. |
|
Done! Thanks all. |
This attempts to capture the information about upstreaming covered in #651.
@LorenzMeier