Skip to content

Commit b744f86

Browse files
committed
Cleared usage of identification properties
1 parent 67eb95a commit b744f86

File tree

1 file changed

+9
-1
lines changed

1 file changed

+9
-1
lines changed

docs/pluggable-discovery-specification.md

+9-1
Original file line numberDiff line numberDiff line change
@@ -312,7 +312,8 @@ The `properties` associated to a port can be used to identify the board attached
312312
"candidate" board attached to that port.
313313

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

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

396+
#### An important note about `vid` and `pid`
397+
398+
The board identification properties should be used only if they allows to match the board model beyond any doubt.
399+
Sometimes a board do not expose a unique vid/pid combination, this is the case for example if a USB-2-serial converter
400+
chip is used (like the omnipresent FT232 or CH340): those chips exposes their specific vid/pid that will be the same for
401+
all the other boards using the same chip. In such cases the board identification properties should NOT be used.
402+
395403
#### Identification of board options
396404

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

0 commit comments

Comments
 (0)