Skip to content

Updated and refined documentation #2760

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Nov 27, 2024
Merged
Changes from 1 commit
Commits
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
Next Next commit
Cleared usage of identification properties
  • Loading branch information
cmaglie committed Nov 20, 2024
commit b744f863cb8effa706e0f56208ab54f38fcb890b
10 changes: 9 additions & 1 deletion docs/pluggable-discovery-specification.md
Original file line number Diff line number Diff line change
Expand Up @@ -312,7 +312,8 @@ The `properties` associated to a port can be used to identify the board attached
"candidate" board attached to that port.

Some port `properties` may not be precise enough to uniquely identify a board, in that case more boards may match the
same set of `properties`, that's why we called it "candidate".
same set of `properties`, that's why we called it "candidate". The board identification properties should be used only
if they allows to match the board model beyond any doubt.

Let's see an example to clarify things a bit, let's suppose that we have the following `properties` coming from the
serial discovery:
Expand Down Expand Up @@ -392,6 +393,13 @@ myboard.upload_port.1.apples=40
will match on both `pears=20, apples=30` and `pears=30, apples=40` but not `pears=20, apples=40`, in that sense each
"set" of identification properties is independent from each other and cannot be mixed for port matching.

#### An important note about `vid` and `pid`

The board identification properties should be used only if they allows to match the board model beyond any doubt.
Sometimes a board do not expose a unique vid/pid combination, this is the case for example if a USB-2-serial converter
chip is used (like the omnipresent FT232 or CH340): those chips exposes their specific vid/pid that will be the same for
all the other boards using the same chip. In such cases the board identification properties should NOT be used.

#### Identification of board options

[Custom board options](platform-specification.md#custom-board-options) can also be identified.
Expand Down