Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/arduino/arduino-cloud-cli


https://github.com/arduino/arduino-cloud-cli

ftweb

Last synced: 5 months ago
JSON representation

Awesome Lists containing this project

README 

        
# arduino-cloud-cli



arduino-cloud-cli is a command line tool that empowers users to access the major features of Arduino IoT Cloud from a terminal.



## License



This code is licensed under the terms of the GNU Affero General Public License v3.0. If you have questions about licensing or need a commercial license please contact us at [[email protected]](mailto:[email protected]).



## Setup



* Install [the latest release](https://github.com/arduino/arduino-cloud-cli/releases).

* A client ID and a secret ID, retrievable from the [cloud](https://cloud.arduino.cc/home/api-keys) by creating a new API key.

* Optional: the command `arduino-cloud-cli device create` requires the `arduino-cli` tool installed on the system. 

  So, if you plan to create a device on the Arduino Cloud via CLI, you need to install the `arduino-cli` following the instructions at [https://arduino.github.io/arduino-cli/latest/installation](https://arduino.github.io/arduino-cli/latest/installation)



## Usage



This tool follows a "quiet on success/verbose on error" behaviour. This means that when a command execution result is an error, such error is printed. On the other hand, when the command is successfully executed, there is no 'success' feedback on the output: the results of the command, if any, are directly printed without any other feedback. This strategy allows users to save the output of the command in a file.



However, if the verbose flag `-v` is used, then the behaviour will change: the logs will always be printed out, providing users with feedback on the execution of the command.



As an example, let's take the `device create` command. We want to save the information of the newly created device in a file.

So we simply lunch the command:



```bash

arduino-cloud-cli device create --name mydevice --format json > mydevice.json

```



The resulting mydevice.json will only contain device information in a json format.



Another example: let's say that the execution of the previous command results in an error. In that case, the json file will be empty and the terminal will print out the error. Now we want to execute the command again with the logs enabled in order to understand the issue. So we execute the following:



```bash

arduino-cloud-cli device create --name mydevice -v

```



### Authentication



arduino-cloud-cli needs a credentials file containing an Arduino IoT Cloud client ID and its corresponding secret.

Credentials can also include an optional organization ID that specifies the organization to use.

You can retrieve these credentials from the [cloud](https://cloud.arduino.cc/home/api-keys) by creating a new API key.



#### Init



Once you have the credentials, execute the following command and provide them:



```bash

arduino-cloud-cli credentials init

```



By default it will be created in the [Arduino data directory](https://support.arduino.cc/hc/en-us/articles/360018448279-Open-the-Arduino15-folder)

You can specify a different destination folder with the `--dest-dir` option:



```bash

arduino-cloud-cli credentials init --dest-dir 

```



arduino-cloud-cli looks for its credentials file in different directories in the following order: current working directory, parents of the current working directory, arduino15 default directory.



This gives you the possibility to use different credentials files depending on the project you are working on.



#### Reset



To reset an old credentials file, just overwrite it using this command:



```bash

arduino-cloud-cli credentials init --overwrite

```



#### JSON format



The credentials file is supported in two different formats: json and yaml. Use the `--file-format` to choose it. Default is yaml.



```bash

arduino-cloud-cli credentials init --file-format json

```



#### Using environment variables



It is also possible to specify credentials directly in `ARDUINO_CLOUD_CLIENT`, `ARDUINO_CLOUD_SECRET` and optionally `ARDUINO_CLOUD_ORGANIZATION` environment variables.



Credentials specified in environment variables have higher priority than the ones specified in credentials files.



Please note that credentials are correctly extracted from environment variables only if all the mandatory credentials parameters (client and secret) are found in environment variables. (think of it as another config file but with higher priority)



#### Find credentials



To have information about which credentials would be used in the current folder you can use the following command:



```bash

arduino-cloud-cli credentials find

```



## Device provisioning



When provisioning a device, you can optionally specify the port to which the device is connected and its [FQBN](https://arduino.github.io/arduino-cli/latest/FAQ/#whats-the-fqbn-string). If they are not given, then the first device found will be provisioned.



Use this command to provision a device:



```bash

arduino-cloud-cli device create --name  --port  --fqbn 

```



Here are the FQBNs of the Arduino boards that can be provisioned with this command:



* `arduino:samd:nano_33_iot`

* `arduino:samd:mkrwifi1010`

* `arduino:mbed_nano:nanorp2040connect`

* `arduino:mbed_portenta:envie_m7`

* `arduino:mbed_nicla:nicla_vision`

* `arduino:samd:mkr1000`

* `arduino:samd:mkrgsm1400`

* `arduino:samd:mkrnb1500`

* `arduino:mbed_opta:opta`

* `arduino:mbed_giga:giga`

* `arduino:esp32:nano_nora`

* `arduino:renesas_uno:unor4wifi`



If the device supports more than one connectivity type (Eg: WiFi and Ethernet) the --connection flag can be used to set the desired connectivity



```bash

arduino-cloud-cli device create --name  --port  --fqbn  --connection 

```



Here the list of available connection values:



* `wifi` to set WiFi connectivity

* `eth` to set Ethernet connectivity

* `wifiandsecret`

* `gsm` to set Gsm connectivity

* `nb` to set Narrowband connectivity

* `lora` to set Lora connectivity



### Devices with LoRaWAN connectivity



LoRaWAN devices should be provisioned using a specific command.

Parameters are the same except for the additional mandatory `--frequency-plan`:



```bash

arduino-cloud-cli device create-lora --name  --frequency-plan  --port  --fqbn 

```



Here are the FQBNs of the Arduino boards supporting LoRaWAN communication that can be provisioned with this command:



* `arduino:samd:mkrwan1310`

* `arduino:samd:mkrwan1300`



The list of supported LoRaWAN frequency plans can be retrieved with:



```bash

arduino-cloud-cli device list-frequency-plans

```



### Generic device



A generic device is like a virtual device that doesn't need to be attached to an actual physical board.

Any actual physical board can connect to Arduino IoT Cloud using the credentials of a generic device.

Generic devices can be created using a specific command.

An optional `--fqbn` flag can be passed to specify the FQBN of the device, otherwise it will be set to `generic:generic:generic`.



```bash

arduino-cloud-cli device create-generic --name  --fqbn 

```



The list of supported FQBN can be retrieved with:



```bash

arduino-cloud-cli device list-fqbn

```



## Device commands



### Delete a device



Devices can be deleted using the device delete command.



This command accepts two mutually exclusive flags: `--id` and `--tags`. Only one of them must be passed. When the `--id` is passed, the device having such ID gets deleted:



```bash

arduino-cloud-cli device delete --id 

```



When `--tags` is passed, the devices having all the specified tags get deleted:



```bash

arduino-cloud-cli device delete --tags =,=

```



### List devices



Devices currently present on Arduino IoT Cloud can be retrieved with:



```bash

arduino-cloud-cli device list

```



It has an optional `--tags` flag that allows to list only the devices having all the provided tags:



```bash

arduino-cloud-cli device list --tags =,=

```



### Tag devices



Add tags to a device. Tags should be passed as a comma-separated list of `=` items:



```bash

arduino-cloud-cli device create-tags --id  --tags =,=

```



### Untag devices



Delete specific tags of a device. The keys of the tags to delete should be passed in a comma-separated list of strings:



```bash

arduino-cloud-cli device delete-tags --id  --keys ,

```



## Thing commands



### Create thing



Create a thing from a thing template.



Supported template formats are JSON and YAML. The name parameter is optional. If it is provided, then it overrides the name retrieved from the template:



```bash

arduino-cloud-cli thing create --name  --template 

```



### Clone thing



Create a thing by cloning another thing.



Here the *name is mandatory*:



```bash

arduino-cloud-cli thing clone --name  --clone-id 

```



### List things



Things can be printed thanks to a list command.



Print a list of available things and their variables by using this command:



```bash

arduino-cloud-cli thing list --show-variables

```



Print a *filtered* list of available things, print only things belonging to the ids list:



```bash

arduino-cloud-cli thing list --ids ,

```



Print only the thing associated to the passed device:



```bash

arduino-cloud-cli thing list --device-id 

```



Print only the things that have all the passed tags:



```bash

arduino-cloud-cli thing list --tags =,=

```



### Delete things



Things can be deleted using the thing delete command.



This command accepts two mutually exclusive flags: `--id` and `--tags`. Only one of them must be passed. When the `--id` is passed, the thing having such ID gets deleted:



```bash

arduino-cloud-cli thing delete --id 

```



When `--tags` is passed, the things having all the specified tags get deleted:



```bash

arduino-cloud-cli thing delete --tags =,=

```



### Extract thing template



Extract a template from an existing thing.



The template is printed to stdout and its format depends on the global `--format` flag:



```bash

arduino-cloud-cli thing extract --id  --format 

```



### Bind thing to a device



Bind a thing to an existing device:



```bash

arduino-cloud-cli thing bind --id  --device-id 

```



#### Tag thing



Add tags to a thing. Tags should be passed as a comma-separated list of `=` items:



```bash

arduino-cloud-cli thing create-tags --id  --tags =,=

```



### Untag thing



Delete specific tags of a thing. The keys of the tags to delete should be passed in a comma-separated list of strings:



```bash

arduino-cloud-cli thing delete-tags --id  --keys ,

```



## OTA commands



### Upload



Perform an OTA firmware update.



Note that the binary file (`.bin`) should be compiled using an arduino core that supports the specified device (check [here](https://arduino.github.io/arduino-cli/0.27/commands/arduino-cli_compile/) how to compile a sketch using the `arduino-cli`): 



```bash

arduino-cloud-cli ota upload --device-id  --file 

```



This schedule a new OTA. Its ID is printed as output.

It is possible to check status for scheduled/executed OTAs using status command.



```bash

arduino-cloud-cli ota status --ota-id 

```



or by device



```bash

arduino-cloud-cli ota status --device-id 

```



### Mass upload



It is also possible to perform a mass ota upload through a specific command.

The fqbn is mandatory.



#### By device



```bash

arduino-cloud-cli ota mass-upload --fqbn  --device-ids  --file 

```



#### By tags



```bash

arduino-cloud-cli ota mass-upload --fqbn  --device-tags =,= --file 

```



## Dashboard commands



### List dashboards



Print a list of available dashboards and their widgets by using this command:



```bash

arduino-cloud-cli dashboard list --show-widgets

```



### Delete dashboards



Delete a dashboard with the following command:



```bash

arduino-cloud-cli dashboard delete --id 

```



### Extract dashboard template



Extract a template from an existing dashboard. The template is printed to stdout and its format depends on the global `--format` flag:



```bash

arduino-cloud-cli dashboard extract --id  --format 

```



### Create dashboard



Create a dashboard: dashboards can be created only starting from a template. Supported dashboard template formats are JSON and YAML. The name parameter is optional. If it is provided, then it overrides the name retrieved from the template. The `override` flag can be used to override the template `thing_id` placeholder with the actual ID of the thing to be used.



```bash

arduino-cloud-cli dashboard create --name  --template  --override =,=

```



## Custom templates



### List custom templates



Use following command to list available custom templates



```bash

arduino-cloud-cli template list

```



### Export custom template



Given list command, it is possible to get custom template ID. Given its ID, use following command to export it as '.tino' archive:



```bash

arduino-cloud-cli template export -t 

```



it is possible to specify output directory with '-d' flag



### Import custom template



To import a custom template, use command:



```bash

arduino-cloud-cli template import -f 

```



### Template apply



It is possible to apply a given template to a device. Apply will generate required resources. Configure device connectivity using '-n' option (see --help for further details).



```bash

arduino-cloud-cli template apply -d  -t  -p "" -n SECRET_SSID=,SECRET_OPTIONAL_PASS=

```