START_SYNC errors after command sequence indicated by pluggable discovery specification

[per1234]

Describe the bug

From the Pluggable Discovery Specification:

https://arduino.github.io/arduino-cli/dev/pluggable-discovery-specification/#start-command

The START command initializes and starts the discovery internal subroutines. This command must be called before LIST or START_SYNC.

To me, this indicates that in order to execute a START_SYNC, I should run the following sequence of commands:

1. HELLO
2. START
3. START_SYNC

🐛 The sequence of commands indicated by the specification results in an error from the START_SYNC command.

To Reproduce

$ git clone https://github.com/arduino/pluggable-discovery-protocol-handler

$ cd pluggable-discovery-protocol-handler/dummy-discovery/

$ go build

$ ./dummy-discovery
HELLO 1 "arduino-cli"
{
  "eventType": "hello",
  "message": "OK",     
  "protocolVersion": 1 
}
START
{
  "eventType": "start",
  "message": "OK"      
}
START_SYNC
{
  "eventType": "start_sync",
  "message": "Discovery already STARTed, cannot START_SYNC",
  "error": true
}

Expected behavior

Specification to be corrected if the behavior of the github.com/arduino/pluggable-discovery-protocol-handler/v2 module is what is intended, which would entail one of the following:

• Remove the statement that START is required before START_SYNC
• Specify that STOP must be called before START_SYNC

-OR-

The github.com/arduino/pluggable-discovery-protocol-handler/v2 module to support the command sequence indicated in the specification.

Desktop

• OS: Windows 10, Ubuntu 20.04
• github.com/arduino/pluggable-discovery-protocol-handler/v2@a0d87f340f91cef6454ea0601f55d1119a5a8bb7

[cmaglie]

Actually the discovery it's working correctly, this is an error in the specification (I think it's a leftover from the RFC).

The state machine here https://arduino.github.io/arduino-cli/dev/pluggable-discovery-specification/#state-machine shows the allowed state transitions and there is no direct transition from START to START_SYNC.

[per1234]

Thanks for taking a look Cristian. I transferred the issue to the Arduino CLI repo since it is now clear that the defect must be corrected in this repository.

[per1234]

We will also need to resolve the other instances of the error that propagated from the specification to the documentation of other projects:

• https://github.com/arduino/pluggable-discovery-protocol-handler/tree/main/dummy-discovery#start-command
• https://github.com/arduino/serial-discovery#start-command

I will propose that this be done by replacing the duplicate content in those repositories with a link to the Pluggable Discovery Specification document in order to avoid the need to maintain multiple copies.

[PaulStoffregen]

EDIT: deleted this comment and started a new issue #1654. It's really a different issue than the minor specification wording disagreement between the START command and State Machine portion of the spec.

[PaulStoffregen]

Also, if you're updating the spec, please consider the wording "A well behaved pluggable discovery tool must reflect the following state machine". Perhaps the word "must" really applies to the client which communicates with the discovery tool. The client is the entity which "must" obey this state machine (eg, only transmit START_SYNC while in the "Idling" state).