Documentation: Specification for sketch.json?

[obra]

[If this issue belongs in a different issue tracker, please let me know.]

I think there should be some sort of written spec for sketch.json, including what data is required as well as what data is allowed.

https://arduino.github.io/arduino-cli/latest/sketch-specification/#metadata is the only doc I can find for sketch.json.

It tells me that the two keys are 'included_libs' and 'cpu', but doesn't describe the formats of these two keys or whether any other keys are supported.

It's not clear whether additional data in sketch.json gets round-tripped when the file is written by arduino-cli or whether the expectation is that writes by arduino-cli board attach are destructive.

Grepping the source of arudino-cli, I think that cpu has 3 possible keys: fqbn, port, and name, with only fqbn being required. included_libs doesn't show up in the source anywhere.

Is there a more complete spec for sketch.json elsewhere that should be linked into the docs?

[per1234]

included_libs doesn't show up in the source anywhere.

It's not used by Arduino CLI, but it is used by Arduino Web Editor.

[obra]

It's not used by Arduino CLI, but it is used by Arduino Web Editor.

Yup. (That bit is mentioned in the little bit of spec I linked to.)

[plocher]

IMO docs/configuration.md feels like the best place to update:

Configuration methods

Arduino CLI may be configured in three ways:

Command line flags
Environment variables
Configuration file
If a configuration option is configured by multiple methods, the value set by the method highest on the above list overwrites the ones below it.

If a configuration option is not set, Arduino CLI uses a default value.

arduino-cli config dump displays the current configuration values.

I'd suggest adding a paragraph for sketch.json along the lines of

• A file named sketch.json may be placed in the sketch directory to specify the '-b' board type and '-p' port to be used by the arduino-cli program. Its format is a JSON dictionary of dictionaries
• { "cpu": { "fqbn":"arduino:avr:pro:cpu=16MHzatmega328", "port":"serial:///dev/cu.usbserial-FTE4L0KY" , "name":"Deek Robot Pro Mini"} }
• The Arduino Web Editor also uses this file to specify 'included_libs'

Note that arduino-cli board attach doesn't seem to work with generic USB interfaces (FTDI...) because there is no way to tell it both the port and FQDN found there. If you manually create the sketch.json file with the correct content, the arduino-cli compile and upload commands work as expected.

% arduino-cli board list                                                                           
Port                             Type              Board Name FQBN Core
/dev/cu.Bluetooth-Incoming-Port  Serial Port       Unknown             
/dev/cu.URT1                     Serial Port       Unknown             
/dev/cu.usbserial-FTE4L0KY       Serial Port (USB) Unknown     

% arduino-cli board attach "serial:///dev/cu.usbserial-FTE4L0KY"
Attach board error: no supported board found at serial:///dev/cu.usbserial-FTE4L0KY

% cat sketch.json                                                                                  
{
"cpu": { "fqbn":"arduino:avr:pro:cpu=16MHzatmega328", "port":"serial:///dev/cu.usbserial-FTE4L0KY", "name":"Robot3" }
}

% arduino-cli compile      
Sketch uses 1722 bytes (5%) of program storage space. Maximum is 30720 bytes.
Global variables use 80 bytes (3%) of dynamic memory, leaving 1968 bytes for local variables. Maximum is 2048 bytes.
% arduino-cli upload -v
"/Users/me/Library/Arduino15/packages/arduino/tools/avrdude/6.3.0-arduino17/bin/avrdude" "-C/Users/me/Library/Arduino15/packages/arduino/tools/avrdude/6.3.0-arduino17/etc/avrdude.conf" -v -V -patmega328p -carduino "-P/dev/cu.usbserial-FTE4L0KY" -b57600 -D "-Uflash:w:/var/folders/pb/wv1s4jx154l6r0xgrg7xps400000gp/T/arduino-sketch-8FC08DE6E0C3C1218A26A587F1DBF73E/test_robot.ino.hex:i"

...
avrdude: AVR device initialized and ready to accept instructions

Reading | ################################################## | 100% 0.00s

avrdude: Device signature = 0x1e950f (probably m328p)
avrdude: reading input file "/var/folders/pb/wv1s4jx154l6r0xgrg7xps400000gp/T/arduino-sketch-8FC08DE6E0C3C1218A26A587F1DBF73E/test_robot.ino.hex"
avrdude: writing flash (1722 bytes):

Writing | ################################################## | 100% 0.89s

avrdude: 1722 bytes of flash written

avrdude done.  Thank you.
% 

[per1234]

arduino-cli board attach doesn't seem to work with generic USB interfaces (FTDI...) because there is no way to tell it both the port and FQDN found there

There is an issue about this here: #1073

[plocher]

What is the name parameter for?
If it is the "generic board name", like "Arduino UNO", then why is this needed here, when it is presumably authoritatively defined elsewhere in the board manager subsystem and findable via the FQBN?

Where is it used? I put arbitrary values in it and nothing in arduino-cli seems to change...

The failure case I'm thinking of is when the FQBN and the NAME don't match as expected - which one is correct? Worse, if the NAME is never used now, things will break in the future if/when it starts being used...

[FStefanni]

Hi,

as a suggestion: a lot of tools allow to dump the "default config" into a file.
This is useful to have a guide to start to customize the options.
So it could be nice to perform this maybe with an option for arduino-cli sketch new,
or, if preferred, as a separate command.

Regards

[cmaglie]

We reworked the board attach command in #1930, now it accepts any combination of --fqbn, --port and --protocol, and it saves the configuration into the official Arduino CLI sketch project file sketch.yaml.

The previous file sketch.json was inherited from the Arduino Web Editor, and it contained preferences/fields specific to the Web Editor (for example the name or included_libs discussed above). That was an unfortunate choice, so to remove any ambiguity, we decided to not support any more sketch.json in the Arduino CLI in favor of the sketch.yaml.

We decide to do this braking change now in sight of the Arduino CLI 1.0 release.