[user-guide]: CLI configuration, aka. How to enable 3rd party board packages

[kittaakos]

CLI Configuration:

The Arduino Pro IDE is powered by the Arduino command-line interface.
From now on, you can adjust the default CLI configurations from the IDE. With this new feature, you can manage any 3rd party core packages conveniently. Here is a list of

This documentation gives you a short introduction on how to manage 3rd party core packages from the IDE by configuring the ESP8266 board. As a reference, you can check how does the Arduino CLI support the 3rd party cores.

1. Open the Pro IDE and select the ESP8266 board:
   

2. Check if ESP8266 is listed for any of the core packages from the Boards Manager view:
   

3. Configure the CLI with a custom, 3rd party URL:
   

You can use the Command Palette (Ctrl/⌘+Shift+P or F1) to open the CLI configuration. Or you can access the configuration from the File > Settings > Open CLI Configuration menu.

Note, you have full-blown language support for the CLI configuration. Whenever you make a mistake, you will see a validation error in the editor.

When you are confused and do not exactly know what are the possible CLI configuration properties, use the content assist (Ctrl+Space) in the editor.

Under the hood, the Pro IDE will create a configuration folder into your home folder (~/.arduinoProIDE/) and dumps the default CLI configuration into the arduino-cli.yaml YAML file. If something is not defined in the YAML file, the CLI falls back to its defaults. Whenever you edit the CLI configuration, we periodically check for modifications and try to update the CLI configuration. If you specify an invalid config, you will be notified and your changes will not be applied.

Now you know the basics of the CLI configuration, and how to adjust it, let's add a 3rd party core package URL and see what happens.

4. Install the core package for the ESP8266 board:
   

5. Handling invalid CLI configuration:
   As mentioned above, the CLI configuration is stored under the ~/.arduinoProIDE/arduino-cli.yaml location. Of course, you can edit the file outside of the Pro IDE and make it invalid. For instance, if you manually set the daemon.port to -1 and start the IDE, the following will happen.

Long story short, if you see the CLI Daemon Offline warning on the status bar, go to your CLI configuration, fix the invalid config, and the daemon will automatically recover.

Appendix (arduino/arduino-cli#587)

Proposal: JSON schema for the Arduino CLI configuration:

{
  "$id": "http://arduino.cc/arduino-cli.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Arduino CLI Configuration",
  "properties": {
    "board_manager": {
      "type": "object",
      "description": "Board Manager Configuration",
      "properties": {
        "additional_urls": {
          "type": "array",
          "description": "If your board requires 3rd party core packages to work, you can list the URLs to additional package indexes in the Arduino CLI configuration file.",
          "items": {
            "type": "string",
            "description": "URL pointing to the 3rd party core package index JSON.",
            "pattern": "^(.*)$"
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "daemon": {
      "type": "object",
      "description": "CLI Daemon Configuration",
      "properties": {
        "port": {
          "type": [
            "string",
            "number"
          ],
          "description": "The CLI daemon port where the gRPC clients can connect to.",
          "pattern": "^([0-9]{1,4}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5])$",
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "directories": {
      "type": "object",
      "description": "Directories Configuration",
      "properties": {
        "data": {
          "type": "string",
          "description": "Path to the the data folder where core packages will be stored.",
          "pattern": "^(.*)$"
        },
        "downloads": {
          "type": "string",
          "description": "Path to the staging folder.",
          "pattern": "^(.*)$"
        },
        "user": {
          "type": "string",
          "description": "Path to the sketchbooks.",
          "pattern": "^(.*)$"
        }
      },
      "additionalProperties": false
    },
    "logging": {
      "type": "object",
      "description": "Logging Configuration",
      "properties": {
        "file": {
          "type": "string",
          "description": "Path to the file where logs will be written.",
          "pattern": "^(.*)$"
        },
        "format": {
          "type": "string",
          "description": "The output format for the logs, can be 'text' or 'json'",
          "enum": [
            "text",
            "json"
          ]
        },
        "level": {
          "type": "string",
          "description": "Messages with this level and above will be logged.",
          "enum": [
            "trace",
            "debug",
            "info",
            "warning",
            "error",
            "fatal",
            "panic"
          ]
        }
      },
      "additionalProperties": false
    },
    "telemetry": {
      "type": "object",
      "description": "Telemetry Configuration",
      "properties": {
        "addr": {
          "type": "string",
          "description": "Address to the telemetry endpoint. Must be a full address with host, address, and port. For instance, ':9090' represents 'localhost:9090'",
          "pattern": "^(.*)$"
        },
        "enabled": {
          "type": "boolean",
          "description": "Whether the telemetry is enabled or not."
        },
        "additionalProperties": false
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

[kittaakos]

Add your remarks, we're happy to hear your feedback.

[csaba911]

Awesome tutorial, much more detailed what is needed but my clean fresh install of 0.0.6 works nothing like illustrated.
when searching for board -> not found, I mean

[MatteoTondelli]

Just tried on my PC and everything works fine.

OS: Win8.1 (64bit)
arduino-pro-ide: 0.0.6
arduino-cli.exe Version: 0.10.0 Commit: ec5c3ed

[csaba911]

Runa as admin, still same issue.
[INFO] panic:
[INFO] runtime error: invalid memory address or nil pointer dereference
[INFO] [signal 0xc0000005 code=0x0 addr=0x10 pc=0x7b0fc3]
what is the gPRC port should be ? 50051 ?

[csaba911]

Deleted app and and deleted config under AppData
Downloaded new copy, same result, I guess this is why not released yet, to many bug, functionality not even close "PRO".
Back to the old IDE or VSCode

Tanks anyway..

[kittaakos]

@csaba911, I created #255 just for you, I thought you log the additional info there.

Runa as admin, still same issue.
[INFO] panic:
[INFO] runtime error: invalid memory address or nil pointer dereference
[INFO] [signal 0xc0000005 code=0x0 addr=0x10 pc=0x7b0fc3]

Please share the entire error, it seems to be a go panic from the CLI. Do you have arduino-cli.exe on the $PATH?

what is the gPRC port should be ? 50051 ?

See here: #255 (comment)

[kittaakos]

arduino-cli.exe Version: 0.10.0 Commit: ec5c3ed

@MatteoTondelli, do you have 0.10.0 CLI on the $PATH? What does the About dialog show? (Help > About)

[csaba911]

Same as yours..

[MatteoTondelli]

@MatteoTondelli, do you have 0.10.0 CLI on the $PATH? What does the About dialog show? (Help > About)

@kittaakos here is my setup:

• Extracted all files in this directory C:\Program Files (x86)\Arduino Pro IDE\Arduino Pro IDE-v0.0.6-win.
• Placed the arduino-cli.exe in the upper folder C:\Program Files (x86)\Arduino Pro IDE.
• Added C:\Program Files (x86)\Arduino Pro IDE to $PATH.

Here is IDE about:

arduino-pro-ide 0.0.6
List of extensions
@theia/callhierarchy 0.17.0-next.f5433ece
@theia/console 0.17.0-next.f5433ece
@theia/core 0.17.0-next.f5433ece
@theia/cpp 0.16.0-next.db05c684
@theia/debug 0.17.0-next.f5433ece
@theia/file-search 0.17.0-next.f5433ece
@theia/filesystem 0.17.0-next.f5433ece
@theia/git 0.17.0-next.f5433ece
@theia/languages 0.17.0-next.f5433ece
@theia/markers 0.17.0-next.f5433ece
@theia/outline-view 0.17.0-next.f5433ece
@theia/output 0.17.0-next.f5433ece
@theia/plugin-ext 0.17.0-next.f5433ece
@theia/plugin-ext-vscode 0.17.0-next.f5433ece
@theia/process 0.17.0-next.f5433ece
@theia/scm 0.17.0-next.f5433ece
@theia/scm-extra 0.17.0-next.f5433ece
@theia/search-in-workspace 0.17.0-next.f5433ece
@theia/task 0.17.0-next.f5433ece
@theia/terminal 0.17.0-next.f5433ece
@theia/userstorage 0.17.0-next.f5433ece
@theia/variable-resolver 0.17.0-next.f5433ece
@theia/workspace 0.17.0-next.f5433ece
arduino-debugger-extension 0.0.6
arduino-ide-extension 0.0.6
arduino-cli.exe Version: 0.10.0 Commit: ec5c3ed

Hope this will help.

[kittaakos]

This is obsolete. The new settings UI is almost identical to the Java IDE. Configuring the 3rd party boards should be the same as in the Java IDE. Closing.