search

AndunHH / spacemouse

Repository for a space mouse, which emulates a 3Dconnexion "Space Mouse Pro wireless". It is based on four joysticks with additional keys or an encoder
Other
83 stars 16 forks source link

Add protocol-explicit <action>.tool properties required for pluggable discovery compatibility #30

Closed per1234 closed 3 months ago

per1234 commented 3 months ago

Background

A new flexible and powerful "pluggable discovery" system was added to the Arduino boards platform framework. This system makes it easy for Arduino boards platform authors to use any arbitrary communication channel between the board and development tools.

Boards platform configurations that use the old property syntax are automatically translated to the new syntax by Arduino CLI:

https://arduino.github.io/arduino-cli/latest/platform-specification/#sketch-upload-configuration

For backward compatibility with IDE 1.8.15 and older the previous syntax is still supported

This translation is only done in platforms that use the old syntax exclusively. If pluggable_discovery properties are defined for the platform then the new pluggable discovery-style upload.tool.<protocol_name> and bootloader.tool.<protocol_name> properties must be defined for each board as well.

Explanation of Property 'upload.tool.serial' is undefined Errors

The project's instructions for macOS and Windows users specify modification of the "Arduino AVR Boards" platform. The "Arduino AVR Boards" platform uses the new pluggable discovery platform properties syntax (https://github.com/arduino/ArduinoCore-avr/commit/c34151f2342476c25146bb51dab67fc390a4524e), so the upload.tool.<protocol_name> and bootloader.tool.<protocol_name> properties are required.

The required properties are missing from the "SpaceMouse" board definition, which causes uploads to fail for users of the recent versions of Arduino IDE and Arduino CLI with the error message:

Error during Upload: Property 'upload.tool.serial' is undefined

Proposed Change

The solution is to add the missing properties to the board definition. I chose to use the default protocol specifier instead of the more specific serial protocol specifier for consistency with the other board definitions in the "Arduino AVR Boards" platform.

Relevance to Linux Users

Linux users will not experience the Property 'upload.tool.serial' is undefined error because, for unknown reasons, the project's instructions specify the modification of the "SparkFun AVR Boards" platform instead of the "Arduino AVR Boards" platform for users of that operating system. The "SparkFun AVR Boards" platform does not use the new pluggable discovery platform properties syntax.

However, even though they are not required, the definition of the upload.tool.default and bootloader.tool.default properties doesn't do any harm when the board definition is in that platform.

Backwards Compatibility

It is also important to provide compatibility with versions of Arduino development tools from before the introduction of the modern pluggable discovery system. For this reason, the old style upload.tool and bootloader.tool properties are retained. Old versions of the development tools will treat the upload.tool.default and bootloader.tool.default properties as an unused arbitrary user defined property with no special significance and the new versions of the development tools will do the same for the upload.tool.default and bootloader.tool.default properties.

Resolves https://github.com/AndunHH/spacemouse/issues/27

coliss86 commented 3 months ago

That makes sense, perfect !

AndunHH commented 3 months ago

Thanks for the good explanation!