From 7c6699ea84fd815269d3b187cf556a92f7919827 Mon Sep 17 00:00:00 2001 From: dido18 Date: Mon, 3 Nov 2025 16:16:44 +0100 Subject: [PATCH 1/4] feat: add Arduino App specification document --- docs/app-specification.md | 43 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 docs/app-specification.md diff --git a/docs/app-specification.md b/docs/app-specification.md new file mode 100644 index 00000000..885d4123 --- /dev/null +++ b/docs/app-specification.md @@ -0,0 +1,43 @@ +# Arduino App specification +This is the specification for the `Arduino App` (from now on called App) format to be used with `arduino-app-cli`. + +An App is a self-contained folder that includes the following components: + - `app.yaml` (mandatory) the file descriptor of the app in YAML format. + - `sketch` (optional) the folder containing an Arduino [Sketch](https://arduino.github.io/arduino-cli/1.3/sketch-specification/)) + - `python` (optional) the folde containin the Python code + +The App must be self-contained (it does not contain references to external files) because this means it can be exported, shared, or zipped easily. + +## Arduino App Folder structure +``` +myapp/ + app.yaml + sketch/ + sketch.ino + sketch.yaml + python/ + main.py + requirements.txt +``` + + +## App descriptor file +The `app.yaml` is the YAML specificaiotn of an APP. + +- `name` - the name of the app. +```yaml +name: My Arduino App +description: An example app showcasing what you can do +icon: 🍓 + +bricks: + - arduino/dbstorage: + variables: + ROOT_PASSWORD: ${secret.db_password} + PORT: 8080 + - arduino/text-generation: + model: gemma-1 + - arduino/objectdetection: + model: yolo + - arduino/mqtt +``` \ No newline at end of file From d13cf8aecb5c30562cf8603970cf2b1437666a14 Mon Sep 17 00:00:00 2001 From: dido18 Date: Mon, 3 Nov 2025 17:28:12 +0100 Subject: [PATCH 2/4] docs: update Arduino App specification for clarity and completeness --- docs/app-specification.md | 54 ++++++++++++++++++++++++++++++--------- 1 file changed, 42 insertions(+), 12 deletions(-) diff --git a/docs/app-specification.md b/docs/app-specification.md index 885d4123..4adf1372 100644 --- a/docs/app-specification.md +++ b/docs/app-specification.md @@ -1,34 +1,47 @@ # Arduino App specification -This is the specification for the `Arduino App` (from now on called App) format to be used with `arduino-app-cli`. +This is the specification for the `Arduino App` (from now on called App) format to be used with `arduino-app-cli` and `Arduino App Lab`. +## Arduino App Folder structure An App is a self-contained folder that includes the following components: - - `app.yaml` (mandatory) the file descriptor of the app in YAML format. - - `sketch` (optional) the folder containing an Arduino [Sketch](https://arduino.github.io/arduino-cli/1.3/sketch-specification/)) - - `python` (optional) the folde containin the Python code + - `app.yaml` (mandatory) the file descriptor of the app in YAML format. + - `sketch` (optional) the folder containing an Arduino [Sketch](https://arduino.github.io/arduino-cli/1.3/sketch-specification/)). + - `python` (optional) the folder containing the Python code. +At least one on `sketch` or `python` folder must be present. The App must be self-contained (it does not contain references to external files) because this means it can be exported, shared, or zipped easily. -## Arduino App Folder structure +Example of a `my-app` folder structure ``` -myapp/ +my-app/ + README.md app.yaml sketch/ sketch.ino sketch.yaml python/ main.py - requirements.txt ``` +## `README.md` file +An (optional) readme file in markdown. +The link to local resources must be in the same folder of the app. For example, a png inside the folder `myapp/docs/my-banner.png` can be referenced using ![My App](docs/my-banner.png) syntax. + +### `app.yaml` file descriptor +The `app.yaml` (or `app.yml`) is a YAML file that describes an App. -## App descriptor file -The `app.yaml` is the YAML specificaiotn of an APP. +- `name`: (optional) a short name of the app. +- `description`: (optional) a brief description of the app. +- `icon`: (optional) the emoji of the app +- `ports`: (optional) a list of ports to be exposed externally. If not given a random port is opened (if necessary). +- `bricks` (optional) a list of bricks used by the app with its variable definitions. -- `name` - the name of the app. +Example: ```yaml name: My Arduino App description: An example app showcasing what you can do icon: 🍓 +ports: + - 7000 bricks: - arduino/dbstorage: @@ -39,5 +52,22 @@ bricks: model: gemma-1 - arduino/objectdetection: model: yolo - - arduino/mqtt -``` \ No newline at end of file +``` + + +### `sketch` sub folder +The content of the `sketch` subfolder contains the Ardiuno skecth. +It must omply with the [Sketch specification](https://arduino.github.io/arduino-cli/1.3/sketch-specification/). + +If present it must contain the followign files: + - `sketch.ino` + - `sketch.yaml` that is compliant to the [Sketch project file](https://arduino.github.io/arduino-cli/1.3/sketch-project-file/) + +### `python` sub folder +The content of the `python` contains the python code. + +If present, it must contain the `main.py` with the python code of the main. +Optionally, a `requirements.txt` with additional python package dependencies to be installed. + +### Other +The folder can be added to the folder structure \ No newline at end of file From 189fcb90cb7f9108e639fd031406a5fafc920c46 Mon Sep 17 00:00:00 2001 From: dido18 Date: Mon, 3 Nov 2025 17:37:56 +0100 Subject: [PATCH 3/4] docs: clarify Arduino App folder structure and reserved names --- docs/app-specification.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/app-specification.md b/docs/app-specification.md index 4adf1372..a15d60e8 100644 --- a/docs/app-specification.md +++ b/docs/app-specification.md @@ -1,15 +1,19 @@ # Arduino App specification This is the specification for the `Arduino App` (from now on called App) format to be used with `arduino-app-cli` and `Arduino App Lab`. -## Arduino App Folder structure +# Arduino App Folder structure An App is a self-contained folder that includes the following components: - `app.yaml` (mandatory) the file descriptor of the app in YAML format. - `sketch` (optional) the folder containing an Arduino [Sketch](https://arduino.github.io/arduino-cli/1.3/sketch-specification/)). - `python` (optional) the folder containing the Python code. -At least one on `sketch` or `python` folder must be present. +At least one on `sketch` or `python` folder must be present. The App must be self-contained (it does not contain references to external files) because this means it can be exported, shared, or zipped easily. +The user-defined apps are saved into `/home/arduino/ArduinoApps` folder. +The builtin-apps are + + Example of a `my-app` folder structure ``` my-app/ @@ -70,4 +74,6 @@ If present, it must contain the `main.py` with the python code of the main. Optionally, a `requirements.txt` with additional python package dependencies to be installed. ### Other -The folder can be added to the folder structure \ No newline at end of file +Other sub-folders or files can be added to the app folder. +The reserved folder names are `sketch` and `python`. +The reserved file names are `app.yaml` and `sketch.yaml`. From 953a761789fa9b08c75ed05c71410ce0b0209918 Mon Sep 17 00:00:00 2001 From: dido18 Date: Mon, 3 Nov 2025 17:38:15 +0100 Subject: [PATCH 4/4] app --- docs/app-specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/app-specification.md b/docs/app-specification.md index a15d60e8..a37b588f 100644 --- a/docs/app-specification.md +++ b/docs/app-specification.md @@ -11,7 +11,7 @@ At least one on `sketch` or `python` folder must be present. The App must be self-contained (it does not contain references to external files) because this means it can be exported, shared, or zipped easily. The user-defined apps are saved into `/home/arduino/ArduinoApps` folder. -The builtin-apps are +The builtin-apps are stored into `home/arduino/.local/share/arduino-app-cli/examples` folder. Example of a `my-app` folder structure