diff --git a/content/hardware/04.pro/boards/portenta-x8/tutorials/04.python-arduino-data-exchange/content.md b/content/hardware/04.pro/boards/portenta-x8/tutorials/04.python-arduino-data-exchange/content.md index bbcf9b798e..af2bfe3dcd 100644 --- a/content/hardware/04.pro/boards/portenta-x8/tutorials/04.python-arduino-data-exchange/content.md +++ b/content/hardware/04.pro/boards/portenta-x8/tutorials/04.python-arduino-data-exchange/content.md @@ -12,11 +12,11 @@ hardware: ## Overview -The container infrastructure provided by Arduino contains a pre-built Python® image that you can use to run Python® applications on the Portenta X8. In this tutorial, we're going to build a container based on a provided one. +The container infrastructure provided by Arduino contains a pre-built Python® image that you can use to run Python® applications on the Portenta X8. In this tutorial, we are going to build a container based on a provided one. While all the peripherals are accessible from the iMX8 processor running the Linux environment, it can be useful to let the onboard microcontroller take care of certain peripheral handling and exchange only the required data between the microcontroller and the Python® application. -Thus you will learn how to do that. If you haven't done so, read through the [user manual](https://docs.arduino.cc/tutorials/portenta-x8/user-manual) to understand the fundamental concepts of the X8 and the provided infrastructure. +You will be guided on how to achieve this setup. It is recommendable to familiarize yourself with the foundational elements of the Portenta X8 and its infrastructure by reading the [user manual](https://docs.arduino.cc/tutorials/portenta-x8/user-manual) if you have not already done so. ## Goals @@ -27,9 +27,9 @@ Thus you will learn how to do that. If you haven't done so, read through the [us ### Required Hardware and Software -- [Portenta X8](https://store.arduino.cc/products/portenta-x8) board -- [Portenta breakout](https://docs.arduino.cc/hardware/portenta-breakout) board -- Any sensor (in this example, we'll use an [BME680](https://www.bosch-sensortec.com/products/environmental-sensors/gas-sensors/bme680/) I2C module) +- [Portenta X8](https://store.arduino.cc/products/portenta-x8) +- [Portenta breakout](https://docs.arduino.cc/hardware/portenta-breakout) +- Any sensor (in this example, we will use an [BME680](https://www.bosch-sensortec.com/products/environmental-sensors/gas-sensors/bme680/) I2C module) - [Arduino IDE 1.8.10+](https://www.arduino.cc/en/software), [Arduino IDE 2](https://www.arduino.cc/en/software), or [Arduino Web Editor](https://create.arduino.cc/editor) ## Python® on the X8 @@ -40,9 +40,21 @@ Python® is a modern and powerful scripting language used for a wide range of ap The Python® script will run on the Linux side and therefore on the iMX8 processor. The Arduino sketch, on the other hand, will run on the STM32H747 microcontroller. It allows for real-time processing on the Arduino side while running a fully-fledged operating system on iMX8. -However, the two processors need a communication mechanism to exchange data with one another. RPC (Remote Procedure Call) is the communication mechanism for this task. To facilitate communication, the M7 core on the STM32H747 microcontroller is used to hand over any data/request to the M4 core. That means your Arduino sketch will solely run on the M4 core. Dual-core processing on the Arduino side is currently not supported. +However, the two processors need a communication mechanism to exchange data with one another. **RPC (Remote Procedure Call)** is the communication mechanism for this task. To establish communication, the M7 core on the STM32H747 microcontroller is used to hand over any data/request to the M4 core. That means your Arduino sketch will solely run on the M4 core. Dual-core processing on the Arduino side is currently not supported. -On the Linux side, there is a service that takes care of sending data between the two worlds. It's called `m4-proxy`. You can check if the service is running by logging into the X8 via `adb shell` and then executing `sudo journalctl -fu m4-proxy`. If the service has stopped unexpectedly, you can restart it with `sudo systemctl restart m4-proxy`. +On the Linux side, there is a service that takes care of sending data between the two worlds. It is called **`m4-proxy`**. + +You can check if the service is running by logging into the X8 via `adb shell` and then executing the next command: + +```bash +sudo journalctl -fu m4-proxy +``` + +If the service has stopped unexpectedly, you can restart it with the following command: + +```bash +sudo systemctl restart m4-proxy +``` ## The Arduino Sketch @@ -63,25 +75,61 @@ Two additional header files need to be included to enable the RPC mechanism on P #include ``` -The `RPC.bind()` method makes the data available via the specified name e.g. "temperature". In our example, an anonymous function is created to return the corresponding sensor property whenever requested. Alternatively, you could bind the name to an existing, named function instead. The data can then easily be requested using that name (e.g. "humidity") by querying the `m4-proxy` service. Once data is requested, it is packaged as a message and sent over SPI to the iMX8. +The `RPC.bind()` method makes the data available via the specified name e.g. "temperature". In our example, an anonymous function is created to return the corresponding sensor property whenever requested. + +Alternatively, you could bind the name to an existing, named function instead. The data can then easily be requested using that name (e.g. "humidity") by querying the `m4-proxy` service. Once data is requested, it is packaged as a message and sent over SPI to the iMX8. ![The iMX8 and the STM32H747 processor communicate via SPI](assets/component-placement.svg) -You can find the sketch in the software package [here](assets/python-sensor-rpc.zip). You may need to change the sketch depending on the choice of the sensor to read from. If you're using an I2C sensor, you can connect SCL to **PWM6** and SDA to **PWM8** on the Portenta breakout. That's because the labeled I2C pins on the Portenta Breakout are only available on the Linux side. If you're using an analog sensor, you can connect it to any analog pin. Please refer to the pinout diagram on the Portenta Breakout [documentation page](/hardware/portenta-breakout). +You can find the sketch in the software package [here](assets/python-sensor-rpc.zip). You may need to change the sketch depending on the choice of the sensor to read from. If you're using an I2C sensor, you can connect SCL to **PWM6** and SDA to **PWM8** on the Portenta breakout. + +That is because the labeled I2C pins on the Portenta Breakout are only available on the Linux side. If you are using an analog sensor, you can connect it to any analog pin. Please refer to the pinout diagram on the Portenta Breakout [documentation page](/hardware/portenta-breakout). ![Wiring diagram of an I2C sensor attached to the X8 via Portenta Breakout](assets/sensor-wiring-breakout.svg) -Make sure you have installed the "Arduino Mbed OS Portenta Boards" core and upload the sketch to the X8 in the Arduino IDE or via Arduino CLI. +Make sure you have installed the **Arduino Mbed OS Portenta Boards** core and upload the sketch to the X8 in the Arduino IDE or via Arduino CLI. ### Debugging the Arduino Sketch -To check if the Arduino sketch is working correctly, you may want to read the messages from the `Serial.println` statements. You cannot currently read them directly in the serial monitor of the Arduino IDE. Instead, you can use a simple service called `py-serialrpc`, which listens for those messages and prints them to the console. +To check if the Arduino sketch is working correctly, you may want to read the messages from the `Serial.println` statements. You cannot currently read them directly in the serial monitor of the Arduino IDE. Instead, you can use a simple service called **`py-serialrpc`**, which listens for those messages and prints them to the console. + +This service needs to run on the Linux side of the X8. You can get the files [here](assets/py-serialrpc.zip). The compressed file will have every file needed to build a container as the docker compose app. From the command prompt of your local machine, navigate to the adb tool folder and upload the files to the X8 with command: + +```bash +adb push /py-serialrpc /home/fio +``` + +Log into the X8 shell with `adb shell` and navigate into the `serialrpc` folder. Build the container using + +```bash +sudo docker build . -t py-serialrpc` +``` + +The `-t` flag assigns a tag to the container. Then run the container by executing `cd..` and then: + +```bash +sudo docker compose up -d +``` + +The `-d` flag detaches the container so it runs in the background. Note that this will run the docker compose app and have the container built persistently across reboots by registering it as a systemd service. -This service needs to run on the Linux side of the X8. You can get the files [here](assets/py-serialrpc.zip). From the command prompt of your local machine, navigate to the adb tool folder and upload the files to the X8 with `adb push /py-serialrpc /home/fio`. +To stop the container, run: -Log into the X8 shell with `adb shell` and navigate into the `serialrpc` folder. Build the container using `sudo docker build . -t py-serialrpc`. The `-t` flag assigns a tag to the container. Then run the container by executing `cd..` and then `sudo docker-compose up -d`. The `-d` flag detaches the container so it runs in the background. Note that this will run the docker container persistently across reboots by registering it as a systemd service. To stop the container, run `sudo docker-compose stop`. +```bash +sudo docker compose stop +``` -Check if the container is running by executing `sudo docker ps`. You can then access the log of this service at any time by executing `sudo docker-compose logs -f --tail 20` from the **same directory**. +Check if the container is running by executing: + +```bash +sudo docker ps +``` + +You can then access the log of its service at any time by using following command from the **same directory**: + +```bash +sudo docker compose logs -f --tail 20 +``` If you do not wish to run the container in the background, skip the `-d` flag, you will get the console output directly in the executing shell. Once the container is running, you will see the messages being sent from the M4. @@ -97,7 +145,25 @@ rpc_client = RpcClient(rpc_address) temperature = rpc_client.call('temperature') ``` -The complete Python® application files are in the same package as the Arduino sketch (see above). Like in the previous step, upload the `python-sensor-rpc` folder to the X8 via `adb push /python-sensor-rpc /home/fio`. Log into the X8 via `adb shell`. Then navigate into the `python-sensor-rpc` folder and execute `sudo docker build . -t python-sensor-rpc`. When it is finished, you can run the container with `sudo docker-compose up`. After a few seconds, you should see the output from the Python application featuring the sensor readings on the M4 that exchanges through the RPC mechanism. The output should look similar to the following: +The complete Python® application files are in the same package as the Arduino sketch (see above). Like in the previous step, upload the `python-sensor-rpc` folder to the Portenta X8 via: + +```bash +adb push /python-sensor-rpc /home/fio +``` + +Log into the X8 via `adb shell`. Then navigate into the `python-sensor-rpc` folder and execute: + +```bash +sudo docker build . -t python-sensor-rpc +``` + +When it has finished, you can run the container with: + +```bash +sudo docker compose up +``` + +After a few seconds, you should see the output from the Python application featuring the sensor readings on the M4 that exchanges through the RPC mechanism. The output should look similar to the following: ```bash python-sensor-rpc_1 | ============================================ @@ -111,7 +177,7 @@ python-sensor-rpc_1 | Gas: 136.496 python-sensor-rpc_1 | Altitude: 311.0769348144531 ``` -Whenever you change anything in the Python® script on your computer, you will have to sync it back to the X8 and re-build the container. Following command sequence will help you to do this process: +Whenever you change anything in the Python® script on your computer, you will have to resync and push the new script to the Portenta X8 and rebuild the container. Following command sequence will help you to do this process: ```bash # On your computer @@ -119,13 +185,27 @@ adb push python-sensor-rpc /home/fio ``` ```bash -# On X8 -sudo docker-compose down +# On the Portenta X8 +sudo docker compose down +``` + +```bash +# On the Portenta X8 sudo docker build . -t python-sensor-rpc -sudo docker-compose up ``` -Alternatively, you could modify the files directly on the X8 using an editor such as VIM, so you don't need to upload the files every time. Re-building the container will be necessary in any case though. If you wonder how to specify the Python® script that is executed when running a container, have a look at the `Dockerfile` file. There you'll find the `ENTRYPOINT` command that takes multiple arguments. In our example: `ENTRYPOINT [ "python3", "m4_to_python.py"]`. +```bash +# On the Portenta X8 +sudo docker compose up +``` + +Alternatively, you could modify the files directly on the X8 using an editor such as **VIM**, so you do not need to upload the files every time. Rebuilding the container will be necessary in any case though. + +If you wonder how to specify the Python® script that is executed when running a container, have a look at the `Dockerfile` file. There you will find the `ENTRYPOINT` command that takes multiple arguments. In our example: + +```python +ENTRYPOINT [ "python3", "m4_to_python.py"]` +``` ## Conclusion @@ -133,5 +213,5 @@ In this tutorial, you learned how to use the docker infrastructure to build a co ### Next Steps -- You may now further process the data that you receive from the Arduino sketch and e.g. upload it to a Cloud service or similar. +- You may further process the data you receive from the Arduino sketch and, e.g., upload it to a Cloud service or similar. - Familiarize yourself with Docker commands to adjust the docker configuration to your needs. diff --git a/content/hardware/04.pro/boards/portenta-x8/tutorials/05.docker-container/content.md b/content/hardware/04.pro/boards/portenta-x8/tutorials/05.docker-container/content.md index 2d840c52db..0d04ac3177 100644 --- a/content/hardware/04.pro/boards/portenta-x8/tutorials/05.docker-container/content.md +++ b/content/hardware/04.pro/boards/portenta-x8/tutorials/05.docker-container/content.md @@ -16,11 +16,11 @@ hardware: ## Overview -[Docker](http://docker.com) is a platform full of applications, called containers. Containers are isolated solutions, thus they don't have to depend on your environment. Making them portable and consistent throughout development, testing, and production. +[Docker](http://docker.com) is a platform full of applications called containers. Containers are isolated solutions; thus, they do not have to depend on your environment, making them portable and consistent throughout development, testing, and production. You can download, install, use, and share applications in the form of containers. You can find all the available container images on the [hub.docker.com](https://hub.docker.com) page. -In this tutorial, we will go through the steps of how to install, run and remove Docker's official [Hello-World image](https://hub.docker.com/_/hello-world) +In this tutorial, we will go through the steps of how to install, run, and remove Docker's official [Hello-World image](https://hub.docker.com/_/hello-world). ## Goals @@ -31,7 +31,7 @@ In this tutorial, we will go through the steps of how to install, run and remove ### Hardware and Software Requirements -- [Arduino® Portenta X8](https://store.arduino.cc/products/portenta-x8) +- [Portenta X8](https://store.arduino.cc/products/portenta-x8) - USB-C® cable (either USB-C® to USB-A or USB-C® to USB-C®) - Wi-Fi® Access Point with Internet Access - ADB: [Check how to connect to your Portenta X8](https://docs.arduino.cc/tutorials/portenta-x8/user-manual#out-of-the-box-experience) @@ -41,17 +41,23 @@ In this tutorial, we will go through the steps of how to install, run and remove ## Using Docker -The Portenta X8 provides Docker CLI by default. The following command will help you verify if it is installed correctly: +The Portenta X8 provides Docker CLI by default. To verify its correct installation, use the following command: ```bash docker -v ``` +Or as well: + +```bash +docker --version +``` + ***To use this tool, you will need to connect to your device first. Check [how to connect using adb/ssh](https://docs.arduino.cc/tutorials/portenta-x8/user-manual#out-of-the-box-experience).*** -You can check Docker's reference documentation, which covers all the features of the tool in depth at [docs.docker.com](https://docs.docker.com/). +You can explore Docker's comprehensive reference documentation, covering all tool features in depth, at [docs.docker.com](https://docs.docker.com/). -The following steps will show how to install, run and uninstall the "Hello World" container. +The following steps will show how to pull the **"Hello World"** image from Docker Hub, run the container, and view its status. To avoid a lack of permissions while launching ```adb shell```, you may type the following: ```newgrp - docker```. @@ -61,7 +67,7 @@ The previous command and other important info about Linux on your Portenta are d First, you will need to search for ["Hello World" container image](https://hub.docker.com/_/hello-world). The container image can be found within the Docker hub, where you will be able to find a variety of readily-available container images. It will be used to verify docker is working as intended with the Portenta X8. -The following command must be used to pull the `hello-world` image. The Docker hub page for images has the instructions to pull the image and deploy the container. +The following command is used to pull the `hello-world` image. The Docker hub page for images has the instructions to pull the image and deploy the container. ```bash docker pull hello-world @@ -71,7 +77,7 @@ docker pull hello-world ### Run The Installed Container -This is the command to begin the container instance. +Use this command to begin a container from the `hello-world` image: ```bash docker run hello-world @@ -79,9 +85,9 @@ docker run hello-world ![Docker CLI running Hello World app](assets/docker-run.png) -***To be able to see an active container with `docker ps -a`, you will need to run it at least once with `docker run`*** +***To see a list of active and exited containers, `docker ps -a` should be used after running a container at least once with `docker run`*** -### Listing The Installed Packages +### Listing Active Containers And Available Docker Images The following command will display the active containers and will show the `hello-world` container if it was able to run successfully. The `STATUS` message will let you know if the container is active or has finished operation depending on its purpose. @@ -99,17 +105,25 @@ docker images ![Docker CLI images](assets/docker-images.png) -### How to Uninstall A Container +### How to Remove A Container + +You will need to obtain an assigned `CONTAINER ID` to remove a container of your choice. This can be found by listing all containers, including inactive ones: -You will need to obtain an assigned `CONTAINER ID` to be able to remove a container of your choice. The list of active containers provides this information. The remove (`rm`) command is then used with the desired container identifier to proceed with the removal process. +```bash +docker ps -a +``` + +The remove (`rm`) command is then used with the desired container identifier to proceed with the removal process. ```bash docker container rm ``` -For this example, the command `docker ps -a` will show the `CONTAINER ID` of the `hello-world` container designated as: `c44ba77b65cb`. If you encounter an error stating that the container cannot be removed, it may mean that the container has an actively ongoing operation which can be checked with `STATUS` message. +For this example, the command `docker ps -a` will show the `CONTAINER ID` of the `hello-world` container designated as: **`c44ba77b65cb`**. + +If you encounter an error stating that the container cannot be removed, it may mean that the container has an ongoing operation that can be checked with a `STATUS` message. -Granted that this is the case, you will need to stop the container and verify with `STATUS` message that it has exited successfully. To do this, the following command is used: +If this is the case, you will need to stop the container and verify with a `STATUS` message that it has exited successfully. To do this, the following command is used: ```bash docker stop diff --git a/content/hardware/04.pro/boards/portenta-x8/tutorials/07.custom-container/content.md b/content/hardware/04.pro/boards/portenta-x8/tutorials/07.custom-container/content.md index 2ea2c6d1aa..0a503142b8 100644 --- a/content/hardware/04.pro/boards/portenta-x8/tutorials/07.custom-container/content.md +++ b/content/hardware/04.pro/boards/portenta-x8/tutorials/07.custom-container/content.md @@ -12,53 +12,51 @@ software: ## Overview -In this tutorial, we will create a simple container and upload it to the Arduino Portenta X8 with its manager. A container consists of an image file and all its dependencies if required. This tutorial will go through the needed files to create a container and its functions. Building this container locally and then uploading it to a Portenta X8. Using docker with ADB to build, run and attach our container to the Portenta X8. +In this tutorial, we will create a Docker container for the Arduino Portenta X8. We will start by building a Docker image, which includes all necessary code and dependencies. Then, we will show how to deploy this image to the Portenta X8 and run it as a container. This process involves using ADB for device communication to manage containers on the Portenta X8. ## Goals -- Learn how to create a container for use with the Portenta X8 -- Learn how to upload a container to the Portenta X8 +- Learn how to create and understand Docker images for the Portenta X8 +- Learn how to deploy and run containers on the Portenta X8 ### Required Hardware and Software - [Portenta X8](https://store.arduino.cc/portenta-x8) - ADB: [Check how to connect to your Portenta X8](https://docs.arduino.cc/tutorials/portenta-x8/user-manual#out-of-the-box-experience) - USB-C® cable (either USB-C® to USB-A or USB-C® to USB-C®) -- Arduino Pro Cloud Subscription [Learn more about the Pro Cloud](https://cloud.arduino.cc/) +- [Arduino Cloud Subscription](https://cloud.arduino.cc/) - [Arduino IDE 1.8.10+](https://www.arduino.cc/en/software), [Arduino IDE 2](https://www.arduino.cc/en/software), or [Arduino Web Editor](https://create.arduino.cc/editor) ## Instructions -An active container uses an isolated filesystem. The container image provides its custom filesystem. Since the image contains the container’s filesystem, it must have everything required to run an application - all dependencies, configuration, scripts, binaries, etc. The image also contains further configurations for the container, such as environment variables, a default command to run, and other metadata. +A Docker container operates with an isolated filesystem derived from its image. The container's image acts as a blueprint, providing a custom filesystem containing all necessary components, such as dependencies, configurations, scripts, and binaries. It also includes settings like environment variables, default commands, and other metadata to ensure the container runs as intended. ## Container File Structure -To create the container, we need to collect the necessary files. Creating a folder called **x8-custom-test**, the following files need to be in the folder: +Organize the essential files within a directory named **x8-custom-test** to prepare for container creation. This directory should include: -- docker-build.conf -- docker-compose.yml -- Dockerfile -- requirements.txt -- src folder -- main.py (This file should be inside the src folder) +- **docker-build.conf**: Configuration for build specifics, including tests to verify the container's functionality. +- **docker-compose.yml**: YAML file for defining and running multi-container Docker applications. +- **Dockerfile**: A script with commands to assemble the image. +- **requirements.txt**: A list of Python® packages required for the application. +- **src folder**: A directory for source code. +- **main.py**: The main Python® script, located inside the src folder. -The complete folder will look like this: +This organization eases a structured approach to building the Docker container. The complete folder should look as the following structure: ![Folder structure for container](assets/custom-container-folder.png) -Let us go through what these files contain and do. +### Docker-build.conf -### Container File: Docker-build.conf - -A file containing the minimal "unit test" command is to be executed on the container to prove it's working. Our file will make our containers minimal unit test a test of the Python3 help command. +This file specifies commands for basic validation tests within the container. Our setup defines a simple test to ensure the container's Python® environment is operational: ```python TEST_CMD="python3 --help" ``` -### Container File: Docker-compose.yml +### Docker-compose.yml -This file defines the app name through the Factory, permissions, and settings for the involved containers. The argument in the image tag will make it, so our image file builds locally. +The **docker-compose.yml** file stages the configuration of your application's services. This example defines a single service named **x8-custom-test**, configuring it with specific runtime properties such as restart policy, user permissions, and system settings. The image tag specifies the Docker image to use, in this case, *blob-opera:latest*, which will be built locally if it does not exist in the Docker registry. ```python version: '3.6' @@ -77,9 +75,11 @@ services: - /tmp ``` -### Container File: Dockerfile +### Dockerfile + +The **Dockerfile** is a blueprint for building a Docker image, containing all the instructions (`FROM`, `COPY`, `COMMAND`, `ENTRYPOINT`, etc.) and detailing all steps from the base to the final image. It specifies the base image to use, the working directory, dependencies to install, and the command to run on container startup. -This is used to build the container. A Dockerfile is a text file that contains all the instructions (FROM, COPY, COMMAND, ENTRYPOINT, etc.) that a user can use from the command line to create different image layers. Although the final image can be created using the docker `build` command, the dockerfile serves just as an image definition. +It sets up a Python® environment, installs dependencies from *requirements.txt*, and ensures the *main.py* script runs when the container is created. ```python FROM python:3-alpine3.15 @@ -103,18 +103,20 @@ ENV UDEV=1 CMD ["python","-u","main.py"] ``` -### Container File: Requirements.txt +### Requirements.txt -The requirements text file defines needed dependencies. These dependencies serves as useful tools to build the application of the container. +This file lists the Python® packages required by your application, ensuring all dependencies are installed during the image build process. For this example, *Flask* is the required dependency, pinned to a specific version for consistency, reliability, or preference. ```python Flask==0.12.3 ``` -### Container File: Source +### Source Here we will keep the source code of the app you want to run in the container or a startup script. We will create a **main.py** file in this folder. This script will print "Hello World!" in the CLI window. +This section is dedicated to the application's source code or startup script for container execution. In the *src* folder, we will create a file named *main.py*. This script, using *Flask*, will display `"Hello World!"` in the CLI window. + ```python from flask import Flask app = Flask(__name__) @@ -129,9 +131,9 @@ if __name__ == '__main__': ## Uploading the Container Folder -First, you will need to set up your board to a Factory setting, as shown in the Portenta X8 [Out-of-the-box experience from the User Manual](https://docs.arduino.cc/tutorials/portenta-x8/user-manual#out-of-the-box-experience). +Begin by resetting your board to its Factory settings as outlined in the Portenta X8 [Out-of-the-box experience from the User Manual](https://docs.arduino.cc/tutorials/portenta-x8/user-manual#out-of-the-box-experience). -Once finished, we will push our folder to a repository within the Factory. Let us place our folder "x8-custom-test" inside the "containers.git" repository. You can find this repository inside your Factory page under "Source". Then, on "container.git", the page URL will be used in the following command. +Next, upload the **x8-custom-test folder** to a repository within the Factory environment. This repository, typically named *containers.git*, can be found on your Factory page under *Source*. Use the repository's URL for the following operations. ![Source on Foundries.io Factory page](assets/custom-factory-page.png) @@ -139,87 +141,97 @@ Once finished, we will push our folder to a repository within the Factory. Let u ![Container.git page](assets/custom-git.png) -To pull or push repositories, you have to generate an API key. This is done by going to the user settings on the Factory page. Click on the user drop-down menu, go into the tokens page and follow the steps of creating a new API key. When creating the API key, please make sure to select the "Use for source code access" option and the correct Factory that you want to use the key for. This token will be used as the password for all git operations while the username can be anything, except an empty string. +To pull or push repositories, you have to generate an API key. This is done by going to the user settings on the Factory page. Click on the user drop-down menu, enter the tokens page, and follow the steps to create a new API key. When creating the API key, please select the *Use for source code access* option and the correct Factory for which you want to use the key. + +This token will be the password for all git operations, while the username can be anything except an empty string. ![User settings on your Factory page](assets/factory-user-settings.png) ![Token creation section in Foundries.io](assets/token-creation-page.png) -Use the following command in git on your machine. To get the repository on your machine, replace "YOUR_FACTORY" with the name of your Factory. The "-b" parameter specifies a branch to checkout after cloning the repository. Running this command will get the container repository, where we will put our folder. +Use the following command in git on your machine. To get the repository on your machine, replace *YOUR_FACTORY* with the name of your Factory. After cloning the repository, the *-b* parameter specifies a branch to checkout. Running this command will get the container repository, where we will put our folder. ```bash git clone https://source.foundries.io/factories/YOUR_FACTORY/containers.git -b devel ``` -Put the "x8-custom-test" folder in the repository and push it with git. When you have put the folder into the git folder, use `git status` to see the changed files in the folder, it will show the unadded changes in red, then use `git add` to add the changes you want to your git commit. Then use `git commit` and `git push` to finally push the changes to the repo. If you push the commit to "containers.git" a new target will automatically build on your FoundriesFactory, you can inspect it on the "Targets" page. +After cloning, add the **x8-custom-test** folder to this repository and push it with git. + +When you have put the folder into the git folder, use *`git status`* to review changes; it will show the unadded changes in red. Then use *`git add`* to add the changes you want to your *`git commit`*. Then use *`git commit`* and *`git push`* to finally push the changes to the repository. Successfully pushing to "containers.git" triggers a new build in your FoundriesFactory, visible on the *Targets* page. ### Building and Running the Container -After the build finishes, it can take up to 10 minutes for your device to update over-the-air to this new version. You can inspect it via the "Devices" tab of your FoundriesFactory. After your device takes the update, navigate into the "x8-custom-test" folder, which should be located on your board now. This allows us to build our container with a simple command. Using ```docker build``` with a ```--tag``` will let us give the container a tag so we can easily keep track of what version of the build this is. +Once the build process is complete, it may take up to 10 minutes for your device to receive and apply the update over-the-air. You can monitor the update's progress through the *Devices* tab in your FoundriesFactory interface. After the update, the **x8-custom-test** folder will be on your device, ready for the next steps. + +To build the container, use the *`docker build`* command in your Dockerfile's directory. The *`--tag`* option allows us to assign a version or name to the build, providing easier management of different container versions. ```bash docker build --tag "x8-custom-test:latest" . ``` -Now that it is built, we can run it with ```docker run```, finding it with the tag that we chose to give to the build we want to run. Here we need to enter the user information into the --user tag. This information is found inside the "docker-compose.yml" file. +You can start the container using *`docker run`* with the built container image. Here, the *`--user`* flag is used to set the user identity (UID) for the container's process, as specified in the *docker-compose.yml* file. ```bash docker run -it --rm --user "63" x8-custom-test:latest ``` -### Using Docker-Compose +This command starts the container interactively (*`-it`*), removes it after exit (*`--rm`*), and runs it under the specified user. The container will run with the settings and application defined in your *Dockerfile* and *Docker-compose* configurations. -An option for testing an app or container is to use "docker-compose". It is helpful when we have a lot of settings in our "docker-compose.yml" file since we don't have to use those settings in the run argument with this method. First, navigate into the container folder. +### Using Docker Compose + +For scenarios involving complex configurations, *`docker compose`* offers a streamlined approach to managing containerized applications. It removes the need for extensive command-line arguments using the settings defined in the *`docker-compose.yml`* file. Begin by navigating to the container's directory: ```bash cd /home/fio/x8-custom-test ``` -This docker-compose command will start your application and register it as a systemd service that will persist even when a reboot occurs. So at the next boot, your docker-compose app will run automatically. +Using *`docker compose`*, the following command starts your application and sets it up as a `systemd` service, ensuring its persistence across reboots. As a result, your application will automatically start upon system startup: ```bash -docker-compose up --detach +docker compose up --detach ``` -To stop the docker-compose app from running, use the following command: +To stop the *`docker compose`* application, use the command below: ```bash -docker-compose stop +docker compose stop ``` ## Deploying with Docker Hub -An alternative method to deploy the custom container is by using the Docker Hub platform. For this, it needs a [Docker Hub account](https://hub.docker.com/) to have your own repository to have the custom container uploaded. When you have the repository ready, the following command will let you upload the custom container image. +Docker Hub provides an alternative deployment method by hosting your container images on its platform. Start by creating a [Docker Hub account](https://hub.docker.com/) and setting up a repository for your container. Once your repository is ready, use the following command to upload your container image: ```bash docker push HUB_USERNAME/x8-custom-test ``` -The custom container image can now be found within `HUB_USERNAME` Docker Hub repository. The image can be accessed whenever any connectivity type grants access to the container image. To pull the image and deploy the container, you will need to connect the Portenta X8 via ADB and use following commands in sequence: +Your custom container image will be available in your Docker Hub repository and accessible from any location with internet connectivity. To deploy this image to your Portenta X8, connect the device via ADB and execute the following commands. First, enter the device's shell: ```bash adb shell ``` +Then, pull and deploy the container image: + ```bash docker pull x8-custom-test ``` -It will pull the container image and deploy the container on your Portenta X8. +This command retrieves the container image, allowing you to deploy and run the container on your Portenta X8. -***To know more about how to create and manage repositories on Docker Hub to manage your custom containers for Portenta X8, check out [here](https://docs.docker.com/docker-hub/repos/#:~:text=To%20push%20an%20image%20to,docs%2Fbase%3Atesting%20).)*** +***For detailed instructions on creating and managing Docker Hub repositories for your custom Portenta X8 containers, refer to the official [Docker Hub Documentation](https://docs.docker.com/docker-hub/repos/#:~:text=To%20push%20an%20image%20to,docs%2Fbase%3Atesting%20).)*** ## Conclusion -This tutorial covered what goes into a container, how the folder should be structured, and what files it should contain. It then explained the purpose of each file and what they should have for this example. Then we went through how this relates to the Factory, and how Foundries.io makes the whole process easier for us. We then showed how to build the container and run it on the Portenta X8. Lastly, we showed a useful testing feature with docker-compose, letting us test our container with a faster process. +In this tutorial, we have outlined how to structure a Docker container for the Portenta X8, describing the necessary files and their purposes. We demonstrated integrating with Foundries.io's Factory for streamlined deployment and highlighted building and running the container on the device. Lastly, we introduced docker compose as a tool for testing containers, emphasizing speed and convenience. ### Next Steps -To get a better understanding of how to manage containers with Docker, take a look at our [Managing Containers with Docker on Portenta X8](https://docs.arduino.cc/tutorials/portenta-x8/docker-container). This tutorial will show some useful commands to use with the docker service and ADB or SSH. +To get a better understanding of how to manage containers with Docker, take a look at our [Managing Containers with Docker on Portenta X8](https://docs.arduino.cc/tutorials/portenta-x8/docker-container). This tutorial will show some useful commands for the docker service and ADB or SSH. ## Troubleshooting Here are some errors that might occur in the process of this tutorial: -- Make sure you have followed our other tutorials that shows how to set up the Portenta X8 with [Out-of-the-box experience from the User Manual](https://docs.arduino.cc/tutorials/portenta-x8/user-manual#out-of-the-box-experience) +- Make sure you have followed our other tutorials that show how to set up the Portenta X8 with [Out-of-the-box experience from the User Manual](https://docs.arduino.cc/tutorials/portenta-x8/user-manual#out-of-the-box-experience) - If you are having issues with the adb shell, don't forget to try and use `sudo` and `su` diff --git a/content/hardware/04.pro/boards/portenta-x8/tutorials/08.image-building/content.md b/content/hardware/04.pro/boards/portenta-x8/tutorials/08.image-building/content.md index adca8dcac1..00a32bc6b5 100644 --- a/content/hardware/04.pro/boards/portenta-x8/tutorials/08.image-building/content.md +++ b/content/hardware/04.pro/boards/portenta-x8/tutorials/08.image-building/content.md @@ -14,7 +14,7 @@ hardware: ## Overview -In this tutorial, you will learn how to build an image for the Portenta X8 with the source code provided at our [GitHub repository for lmp-manifest](https://github.com/arduino/lmp-manifest). Building your image locally can help debug several aspects of the system, such as the bootloader or kernel support. +In this tutorial, you will learn how to build an image for the Portenta X8 with the source code provided at our [GitHub repository for lmp-manifest](https://github.com/arduino/lmp-manifest). It is an ideal approach for debugging system elements like the bootloader or kernel support by building images locally. ***Images built locally cannot register with FoundriesFactory and will not be OTA compatible, but this is a good alternative for those who do not have a FoundriesFactory subscription.*** @@ -30,9 +30,9 @@ This tutorial targets customers that are not FoundriesFactory subscribers, but s ### Required Hardware and Software -- [Arduino Portenta X8](https://store.arduino.cc/products/portenta-x8) +- [Portenta X8](https://store.arduino.cc/products/portenta-x8) - [Docker Engine](https://docs.docker.com/engine/install/) -- ~60GB available space on your machine's drive +- ~60GB of available storage space on your machine ## Instructions @@ -40,9 +40,9 @@ This tutorial targets customers that are not FoundriesFactory subscribers, but s #### Build the Docker Image -You will create a Docker image that has the dependencies needed to build your device image. To do so, you will need to clone our [lmp-manifest repository](https://github.com/arduino/lmp-manifest). The following steps will guide you through the process: +You will start by creating a Docker image with the necessary dependencies to build your device image. This involves cloning the [lmp-manifest repository](https://github.com/arduino/lmp-manifest) from Arduino's GitHub. Follow these steps: -First, clone the lmp-manifest repository with the following command: +Clone the [lmp-manifest repository](https://github.com/arduino/lmp-manifest) using the command below: ```bash git clone https://github.com/arduino/lmp-manifest.git @@ -50,33 +50,35 @@ git clone https://github.com/arduino/lmp-manifest.git ![Cloning lmp-manifest repository](assets/git_clone_lmp-manifest.png) -After cloning the lmp-manifest repository successfully, we will proceed to build the Docker Image using following command sequence: +After successfully cloning the repository, navigate to the lmp-manifest directory: ```bash cd lmp-manifest ``` +Build the Docker image with the following command: + ```bash docker build -t yocto-build ./lmp-manifest ``` ![Building a Docker Image](assets/docker_build.png) -You will be able to see similar result if everything went successfully. +You will see a confirmation message indicating the image's readiness if the build completes successfully. #### Run The Docker Image (Builder) -Once the *Docker Image* is ready, we will run the image with the `-v` argument to mount a volume. This allows you to use a host directory inside the Docker image, so you can store all the data and build artifacts safely. +After preparing the Docker image, it is time to run it with the *`-v`* option to mount a host directory as a volume inside the container. This step is important for preserving data and build artifacts beyond the container's lifecycle. -***If you do not use a volume while running the image, you will lose the data when the image stops*** +***Skipping the volume mount (`-v`) will result in data loss once the container has stopped.*** -Run the `yocto-build` builder image with following command: +To run the *`yocto-build`* image and begin an interactive session, use the following command, replacing *``* with your host directory path: ```bash docker run -v :/dockerVolume -it yocto-build bash ``` -We need to switch to the `builder` user with the following command after the previous process, and the password is **builder**: +Once inside the container, switch to the *`builder`* user to proceed with the build process. The password for the builder user is **builder**: ```bash su builder @@ -90,25 +92,31 @@ su builder Now that you are running inside the Docker Image, you can use tools like **git-repo**, which is already installed. -First, configure git with your credentials. They don't need to be the real ones but are required by `git-repo` to pull. The following commands can be used for this example: +Begin by configuring git with any credentials, as *`git-repo`* requires this for operations. Use the following commands as placeholders: ```bash git config --global user.email "you@example.com" +``` + +```bash git config --global user.name "Your Name" ``` ![Adding credentials to git config](assets/git_config.png) -Change to the home directory, and initialize the repository using **repo**: +Next, navigate to the mounted volume directory and initialize the repository using **repo**: ```bash cd /dockerVolume +``` + +```bash repo init -u https://github.com/arduino/lmp-manifest.git -m arduino.xml -b release ``` ![Git-repo initialization](assets/repo_init.png) -Then pull the needed files with: +Proceed to download the necessary files by synchronizing the repositories: ```bash repo sync @@ -116,41 +124,41 @@ repo sync ![Git-repo pulling all the repositories](assets/repo_sync.png) -After completion, it should look like the following image: +Upon successful synchronization, your directory should resemble the following: ![Git-repo finished sync](assets/repo_sync_finished.png) -***NOTE: If you are a FoundriesFactory subscriber and want to build your Factory sources locally, please use the manifest link for your Factory as below. This is not recommended as images built locally cannot register to the Factory and receive OTAs.*** +***If you are a FoundriesFactory subscriber and want to build your Factory sources locally, please use the manifest link for your Factory as below. This is not recommended as images built locally cannot register to the Factory and receive OTAs.*** #### Set Up the Portenta X8 Distribution -It is recommendable to set `DISTRO` to either: +For the Portenta X8, you have options for the **DISTRO** setting, each designed for different needs: -- `lmp-base`: insecure image without ostree, developer-friendly, not OTA compatible -- `lmp`: secure image without xwayland -- `lmp-xwayland`: secure image with xwayland support +- **`lmp-base`**: A developer-friendly, insecure image without OSTree that is unsuitable for OTA updates. +- **`lmp`**: A secure image, streamlined without xwayland. +- **`lmp-xwayland`**: A secure image that includes xwayland support. -It will help to classify the image if it follows any of the previous characteristics and with the following command: +Choose the appropriate distribution with the command below: ```bash DISTRO=lmp-xwayland MACHINE=portenta-x8 . setup-environment ``` -***`lmp-partner-arduino-image` will be better supported soon.*** +***Support for `lmp-partner-arduino-image` is anticipated to improve continuously.*** -It will then switch automatically to a new folder. Continuing, you can now proceed to accept the EULA using the following command: +Following the environment setup, the process will navigate to a new directory. Here, accept the EULA with: ```bash echo "ACCEPT_FSL_EULA = \"1\"" >> conf/local.conf ``` -You will be able to see similar output as following after the previous steps: +The setup completion should resemble the output shown here: ![Setup Portenta X8 DISTRO](assets/x8_distro_setup.png) #### Build an Image With Bitbake -To start building the image, following command is used: +Start the image build with Bitbake using: ```bash bitbake lmp-partner-arduino-image @@ -160,22 +168,18 @@ bitbake lmp-partner-arduino-image ![Compile Portenta X8 image](assets/x8_build.png) -If you want to use your computer while it builds, it is recommendable to lower the threads used since it takes a lot of resources and time. Do so by opening `conf/local.conf` and lowering the values of the following variables: - -- `BB_NUMBER_PARSE_THREADS = "4"` -- `BB_NUMBER_THREADS = "4"` - -And add: +To maintain system responsiveness during the build, consider adjusting resource usage by editing *`conf/local.conf`*: -- `PARALLEL_MAKE = "-j 4"` +- Reduce `BB_NUMBER_PARSE_THREADS` and `BB_NUMBER_THREADS` to `"4"` +- Set `PARALLEL_MAKE` to `"-j 4"` -If possible, it is a good practice to understand the available threads of your computer used for this process, to optimize the resources accordingly for optimal balance between build performance and side tasks while waiting for the build. Once it finishes you will see something similar to: +Assessing and adjusting according to your system's thread availability can help balance the build process and other activities. Upon completion, the output should be similar to this: ![Portenta X8 Image finished compilation](assets/x8_build_finished.png) #### Setup Manufacturing Tools -To flash your board, you will need to compile **lmp-mfgtool distro** to get additional tools. First, go into your home folder and change `DISTRO` following the command sequence: +To flash your board, you will need to compile **lmp-mfgtool distro** to get additional tools. First, go into your home folder and change **DISTRO** following the command sequence: ```bash cd .. @@ -184,13 +188,13 @@ echo "ACCEPT_FSL_EULA = \"1\"" >> conf/local.conf echo "MFGTOOL_FLASH_IMAGE = \"lmp-partner-arduino-image\"" >> conf/local.conf ``` -You should be able to see similar results as following image when successful: +You should be able to see similar results as the following image when successful: ![Flashing tools DISTRO setup](assets/tools_distro_setup.png) #### Build Manufacturing Tools: Flash The Board -To compile and get the tools required, we will use following command: +To compile and get the tools required, we will use the following command: ```bash bitbake mfgtool-files @@ -202,7 +206,7 @@ After completion: ![Tools compilation finished](assets/tools_finished.png) -***This process may take ~2 hours depending on your build host*** +***This process may take ~2 hours, depending on your build host*** #### Save Your Image For Flashing @@ -231,12 +235,12 @@ You will be able to see the copied files in your OS file explorer. ## Conclusion -In this tutorial, you have learned how to build a "builder" Docker image, get its required files, configure the build settings, build the image,a and to save the needed files for flashing. Now you have all the required files to flash the image you built onto the device. +In this tutorial, you have learned how to build a "builder" Docker image, get its required files, configure the build settings, build the image, and save the needed files for flashing. Now, you have all the files necessary to flash the image you built onto the device. ## Next Steps -Please follow the [Flashing tutorial](https://docs.arduino.cc/tutorials/portenta-x8/image-flashing/) to flash your device with your custom image. You can use the files provided from this build to flash the Portenta X8 following the tutorial's steps. +Please follow the [Flashing tutorial](https://docs.arduino.cc/tutorials/portenta-x8/image-flashing/) to flash your device with your custom image. Following the tutorial's steps, you can use the files from this build to flash the Portenta X8. ## Troubleshooting -- If you are having `do_fetch` issues, try to check your system's and virtual machine's DNS settings. +- If you are having `do_fetch` issues, check your system's and virtual machine's DNS settings. diff --git a/content/hardware/04.pro/boards/portenta-x8/tutorials/11.display-output-webgl/content.md b/content/hardware/04.pro/boards/portenta-x8/tutorials/11.display-output-webgl/content.md index d4402b52f0..dd420f963c 100644 --- a/content/hardware/04.pro/boards/portenta-x8/tutorials/11.display-output-webgl/content.md +++ b/content/hardware/04.pro/boards/portenta-x8/tutorials/11.display-output-webgl/content.md @@ -19,7 +19,7 @@ hardware: The Arduino Portenta X8's processor **NXP® i.MX 8M Mini Processor** is capable of 3D rendering by using OpenGL to process the 3D-related calculations, allowing us to display 3D content on a screen or video output. -In this tutorial, we will render web content from the internet using WebGL and display it on a screen, using a USB Hub. We will go through the steps to set up, install and modify the video output. +In this tutorial, we will render web content from the internet using WebGL and display it on a screen using a USB Hub. We will go through the steps to set up, install, and modify the video output. ## Goals @@ -30,7 +30,7 @@ In this tutorial, we will render web content from the internet using WebGL and d ### Required Hardware and Software -- [Arduino Portenta X8](https://store.arduino.cc/products/portenta-x8) +- [Portenta X8](https://store.arduino.cc/products/portenta-x8) - USB-C® cable (either USB-C® to USB-A or USB-C® to USB-C®) - USB-C® hub with HDMI - External monitor @@ -40,7 +40,7 @@ In this tutorial, we will render web content from the internet using WebGL and d ### Install The Container -There are two ways to get the container, either through `foundriesFactories` or downloading the container from [portenta-containers repository](https://github.com/arduino/portenta-containers). +There are two ways to get the container: through `foundriesFactories` or downloading the container from [portenta-containers repository](https://github.com/arduino/portenta-containers). **With Foundries.io:** @@ -53,7 +53,7 @@ fioctl devices config updates --apps "x-kiosk-imx8-webgl" -f -f -//If you are getting issues doing so, make sure you are logged correctly with your token +//If you are having issues doing so, make sure you are logged correctly with your token //You can logout: fioctl logout @@ -61,15 +61,15 @@ fioctl logout fioctl login ``` -You will now see the home screen for a few seconds and then it will fade out and open the Aquarium 3D from [WebGL samples - Aquarium](https://webglsamples.org/aquarium/aquarium.html). +You will see the home screen for a few seconds, and then it will fade. Open the Aquarium 3D from [WebGL samples - Aquarium](https://webglsamples.org/aquarium/aquarium.html). **With downloaded repository:** -If you downloaded the [portenta-containers repository](https://github.com/arduino/portenta-containers), you will need to connect your board directly to your computer and run the `adb shell`, then push the container to your Portenta X8. +If you downloaded the [portenta-containers repository](https://github.com/arduino/portenta-containers), you would need to connect your board directly to your computer and run the `adb shell,` then push the container to your Portenta X8. ### Connect to a Wi-Fi® -Check the available Wi-Fi® access points by using the `nmcli de wifi` command. You will be able to see an output laying out `BSSID`, `SSID`, and its other elements. +Check the available Wi-Fi® access points using the `nmcli de wifi` command. You will be able to see an output laying out `BSSID`, `SSID`, and its other elements. ```bash nmcli de wifi @@ -94,7 +94,7 @@ nmcli con down nmcli c delete ``` -If the LED is illuminating Green, then we know it has been correctly connected. If you want to check it in your terminal, you can use the following commands: +If the LED is illuminating Green, we know it has been correctly connected. If you want to check it in your terminal, you can use the following commands: ```bash nmcli de @@ -107,7 +107,7 @@ wlan0 wifi connected docker0 bridge connected (externally) docker0 ``` -The output table will display information regarding active connections as well as the Wi-Fi® connection in which we are interested. +The output table will display information regarding active connections and the Wi-Fi® connection we are interested in. ### Get Your Board's IP @@ -121,13 +121,13 @@ wlan0: flags=4163 mtu 1500 inet netmask 255.255.255.0 broadcast ``` -Test your IP connection by exiting the `adb shell`, you can use **CTRL+Z** or type `exit`, then try to connect through **SSH** using following command: +Test your IP connection by exiting the `adb shell`, you can use **CTRL+Z** or type `exit`, then try to connect through **SSH** using the following command: ```bash ssh fio@ ``` -***To connect through SSH it will request the user's password, which is "fio". If you have trouble connecting with the SSH, please check the troubleshooting section at the end of this tutorial.*** +***To connect through SSH, the user's password, "fio," will be requested. If you have trouble connecting with the SSH, please check the troubleshooting section at the end of this tutorial.*** ### Copy/Push the Docker-Compose.yml @@ -139,25 +139,25 @@ scp fio@: ### Video Output Setup -Now we need a USB Hub that has an available video output connector, for example, an HDMI cable. Connect the Portenta X8 to the USB Hub as a Host, the video connector to a display, and the power supply USB to your computer. It is optional but we could also connect a USB mouse to the hub. The setup should look like as follows: +Now, we need a USB Hub with an available video output connector, such as an HDMI cable. Connect the Portenta X8 to the USB Hub as a Host, the video connector to a display, and the power supply USB to your computer. It is optional, but we could connect a USB mouse to the hub. The setup should look like as follows: ![X8 usb hub setup](assets/portentaX8_hub_screen.svg) ***As a reference, a list of validated USB-C® to HDMI hubs that you can use are: [TPX00145](https://store.arduino.cc/products/usb-c-to-hdmi-multiport-adapter-with-ethernet-and-usb-hub) and [TPX00146](https://store.arduino.cc/products/usb-c-to-hdmi-multiport-adapter-4k-usb-hub-pd-pass-through).*** -By default, if you connect the board to a display, you will see the "home screen" with the `Arduino PRO` background wallpaper, and a bottom bar with a real-time clock. +By default, if you connect the board to a display, you will see the "home screen" with the `Arduino PRO` background wallpaper and a bottom bar with a real-time clock. ***You can interact with the interface by plugging USB devices into your hub, like a mouse or a keyboard.*** ![X8 home-screen](assets/portentaX8-home-screen.png) -If you need to change the resolution of your display/monitor to improve the video output quality, you need to add a specific resolution to the configuration file of the graphical server (Weston on Portenta X8). To do so, you need to generate the right **Modeline**, i.e. a row that specifies a custom mode for the graphical interface to correctly drive the display. +Suppose you need to change the resolution of your display/monitor to improve the video output quality. In that case, you need to add a specific resolution to the configuration file of the graphical server (Weston on Portenta X8). To do so, you need to generate the right **Modeline**, i.e., a row that specifies a custom mode for the graphical interface to drive the display correctly. In the next steps, we provide an example of a 1600 x 758 display running at 60Hz. If you need to modify the modeline and generate a new one, you can use `cvt` command, which is already installed in the Linux image running on your Portenta X8 (see [here](https://wiki.ubuntu.com/X/Config/Resolution#Adding_undetected_resolutions) to get more information). To get started in modifying the resolution of your display, connect to your Portenta X8 through ADB (check [this link](https://docs.arduino.cc/tutorials/portenta-x8/user-manual#working-with-linux) to learn how to do it). -At this point, you are ready to modify the `/etc/xdg/weston/weston.ini` file with `Vim` command as follows: +At this point, you are ready to modify the `/etc/xdg/weston/weston.ini` file with the `Vim` command as follows: ```bash sudo vim /etc/xdg/weston/weston.ini @@ -170,13 +170,13 @@ You can now add the following lines to the `weston.ini` file: name=DP-1 mode=98.00 1600 1680 1840 2080 758 761 771 787 -hsync +vsync ``` -Save the file and exit. To see the changes in place, you have to reboot your Portenta X8 by using the command `sudo systemctl reboot`. When the board gets started again, you will be able to see your display with the right resolution. +Save the file and exit. To see the changes in place, you have to reboot your Portenta X8 using the command `sudo systemctl reboot`. When the board gets started again, you will be able to see your display with the right resolution. ### Running The Image If you obtained the app descriptor, structured through *docker-compose.yml*, from **Foundries.io**, it will run automatically after a few seconds. -On the other hand, if you copied from the repository, you will need to initialize with **docker** by accessing your Portenta X8 through SSH, going to the directory where you have copied it, and running it from that directory using following commands: +On the other hand, if you copied from the repository, you will need to initialize with **docker** by accessing your Portenta X8 through SSH, going to the directory where you have copied it, and running it from that directory using the following commands: ```bash //Connect to your device @@ -194,7 +194,7 @@ docker compose stop ### Edit The Output -It is possible to change the web output URL by editing the `docker-compose.yml` file, using the following commands: +It is possible to change the web output URL by editing the `docker-compose.yml` file using the following commands: ```bash //Connect to your device @@ -207,15 +207,15 @@ cd vim docker-compose.yml ``` -Once you are inside the **VIM** editor, to edit the file you will need to press **insert** and replace the URL as shown in the screenshot. +Once inside the **VIM** editor, you will need to press **insert** and replace the URL as shown in the screenshot to edit the file. ![VIM editing docker-compose.yml](assets/vim-edit-dockerCompose.png) -To save the changes, press the **ESC** key and type `:wq`. This will write and quit the **VIM** editor. After editing the file, you will need to compose the container again to make the changes take effect. +Press the **ESC** key to save the changes and type `:wq`. This will write and quit the **VIM** editor. After editing the file, you will need to compose the container again to make the changes take effect. ## Conclusion -In this tutorial, we went through how to connect the board and display something on a screen. Using a container from FoundriesFactories or by downloading it and uploading it to your Portenta X8. Lastly, we showed how to edit the video output by editing the container. +In this tutorial, we went through how to connect the board and display something on a screen. Using a container from FoundriesFactories or downloading it and uploading it to your Portenta X8. Lastly, we showed how to edit the video output by editing the container. ### Next Steps diff --git a/content/hardware/04.pro/boards/portenta-x8/tutorials/13.wordpress-webserver/content.md b/content/hardware/04.pro/boards/portenta-x8/tutorials/13.wordpress-webserver/content.md index b56e05fabe..dbaacb4c77 100644 --- a/content/hardware/04.pro/boards/portenta-x8/tutorials/13.wordpress-webserver/content.md +++ b/content/hardware/04.pro/boards/portenta-x8/tutorials/13.wordpress-webserver/content.md @@ -16,31 +16,33 @@ hardware: ## Overview -The Arduino Portenta X8 is a powerful board that has many features that can be easily utilized with the help of Docker containers. In this tutorial, we will be using the Portenta X8 to host a web server and run WordPress using containers. This is a simple way to configure and run your own database server container and WordPress page. We can then access the WordPress site on the X8 through our web browser and begin setting it up. +The Arduino Portenta X8's robust features are ideally complemented by Docker containers, simplifying various applications. This tutorial demonstrates how to deploy a WordPress web server on the Portenta X8, leveraging containers for web service and database management. + +You will learn to set up and access a WordPress site hosted on the X8 via a web browser. ## Goals -- Create the file to install docker containers -- Install and run the containers -- Connect to the WordPress container running on the Portenta X8 +- Prepare the necessary files for Docker container deployment +- Deploy and activate the Docker containers on the Portenta X8 +- Access and configure the WordPress site hosted on the Portenta X8 ### Required Hardware and Software -- [Arduino Portenta X8](https://store.arduino.cc/products/portenta-x8) +- [Portenta X8](https://store.arduino.cc/products/portenta-x8) - USB-C® cable (either USB-C® to USB-A or USB-C® to USB-C®) - The [docker-compose.yml](assets/docker-compose.rar) file used in this tutorial ## Instructions -First, make sure your Portenta X8 is set up correctly by following the [User Manual's Out-of-the-Box Experience](https://docs.arduino.cc/tutorials/portenta-x8/user-manual#out-of-the-box-experience). +Begin by ensuring your Portenta X8 is ready for use, following the setup guide in the [User Manual's Out-of-the-Box Experience](https://docs.arduino.cc/tutorials/portenta-x8/user-manual#out-of-the-box-experience). ### Creating the **docker-compose.yml** File -The WordPress container we use is a multi-container application, which also requires a database server container. The WordPress multi-container application uses Apache as its web server. It is required to make the service operational and comes included within the container. We will be using MariaDB as our database server as a container instance. +Our WordPress setup involves a multi-container approach, integrating both the WordPress and a MariaDB database server containers. The WordPress container uses Apache as the web server, merged within the container for easy deployment. -This container can run on the Portenta X8's architecture. To start using these containers is to build a docker-compose.yml file. This file contains information regarding what image we want to install and important configuration details, such as the username for the database, password, timezone, and database name. The same goes for the WordPress container: it will include the password and username. We will also enter the database hostname and which container will be used as the database. We recommend changing the default passwords to more secure ones by replacing the default password defined in the file below. +To direct this setup, we will craft a docker-compose.yml file describing the configurations for both WordPress and MariaDB containers, including essential settings like usernames, passwords, time zones, and database names. For security, ensure the default passwords are substituted with stronger alternatives in the provided configuration template. -### The Complete **docker-compose.yml** File +### Complete **docker-compose.yml** File In this section, you can find the complete **docker-compose.yml** file that we will be using for this tutorial. @@ -82,13 +84,13 @@ volumes: db_data: {} ``` -Now let's create a directory on our X8 and put this **docker-compose.yml** file on our device. You can download the file by clicking [here](assets/docker-compose.rar). +Now, let's prepare our Portenta X8 by creating a directory for our **docker-compose.yml** file, which can be downloaded [here](assets/docker-compose.rar). ### Installing The Containers -First, we create a directory where we want to add our **docker-compose.yml** file. Using the `mkdir` command we will create a directory named "wordpress-test". Navigate into this directory with a simple `cd` command. Either copy the docker-compose.yml file into this directory or create it directly here. +Begin by creating a directory for the Docker setup, naming it **wordpress-test**. Navigate into this directory and either copy the *docker-compose.yml* file into it or create the file directly within. -To create the file, we can use `cat > docker-compose.yml`, this will create the file, so you can copy the content of the file from above and paste it. Push enter once to go to a new line and press `ctrl C` to exit the file editor. To copy the file from your computer onto the device use: +To create the file on the device, use *`cat > docker-compose.yml`*, paste the contents, and exit with `CTRL + C`. To transfer the file from your computer, use the following command, making sure to replace *``* with the actual file path: ```bash adb push /home/fio/wordpress-test @@ -96,72 +98,95 @@ adb push /home/fio/wordpress-test Alternatively, you could place the `docker-compose.yml` file inside the `wordpress-test` directory and push the file using the following command: +Alternatively, if the *docker-compose.yml* is already inside the **wordpress-test** directory on your computer, use: + ```bash adb push .\wordpress-test\ /home/fio ``` -Both options work fine and depend on how you would like to handle the file. +Choose the method that best suits your workflow. ![cd into correct directory](assets/webserver-mkdir.png) -***Remember that you may need to run the next command to gain admin access for running the Docker's commands: `sudo su -` which default password is `fio`*** +***Access Docker with administrative privileges by executing `sudo su -`, with `fio` as the default password.*** + +Ensure no conflicting containers are running on your intended ports by inspecting current containers with *`docker ps -a`*. Remove any active containers by first stopping them with: + +```bash +docker stop +``` + +Then removing them with: + +```bash +docker rm +``` + +If you want more information about handling containers on your Portenta X8, take a look at our [Managing Containers with Docker tutorial](https://docs.arduino.cc/tutorials/portenta-x8/docker-container). + +With the setup directory ready and no port conflicts, begin the container installation with: -Before installing the containers, make sure that no other container is running on the ports that the WordPress container will use. You can check what containers are running and what port they are using by running the `docker ps -a` command. This will show a list of the currently installed and running containers on the Portenta X8. +```bash +docker compose up -d +``` +The `-d` flag runs the containers in the background; omitting it will tie the container's lifecycle to the terminal session. -To remove a container first stop it with `docker stop `, then you can run `docker rm ` to remove it. If you want more information about handling containers on your Portenta X8, take a look at our [Managing Containers with Docker tutorial](https://docs.arduino.cc/tutorials/portenta-x8/docker-container). +The installation of the **WordPress** and **MariaDB** containers will begin and may take some time. To monitor the installation process, use: -When you are in the correct directory and no other container is running on the ports that WordPress will use, you can now run `docker compose up -d`. Using the `-d` tag in the command will allow running these containers in the background. If you run the command without the `-d` tag, the application will exit when you close the terminal. +```bash +docker-compose logs -f +``` -When the command is executed it will start installing the **WordPress** and **MariaDB** containers. This can take a while. To get the output from the containers use: `docker-compose logs -f`. Once it is done you can connect to the device and site. +Upon completion, your WordPress site will be accessible from the Portenta X8. ![Containers install progress in the terminal](assets/webserver-container-install.png) ### Connecting to the WordPress Site -To connect to the WordPress setup site, you simply need to access it with your Portenta X8's unique id and port. So we can use the following address format: +Accessing your WordPress site on the Portenta X8 is straightforward. Use the following URL format, composed with your Portenta X8's unique id and port, in your browser: ```bash http://portenta-x8-.local: ``` -Where you would substitute the `` with your Portenta X8's unique id and the port chosen for the WordPress container with ``. The `` can be found on the setup page that is shown in the [User Manual's Out-of-the-Box Experience](https://docs.arduino.cc/tutorials/portenta-x8/user-manual#out-of-the-box-experience), but you can also get it in the terminal when running `adb` or you can go to `http://192.168.7.1:8000` if you use Windows and Linux, on MacOS use `http://192.168.8.1:8000`. +Replace *``* with your Portenta X8's unique identifier and *``* with the port you have allocated for the WordPress container. You can find your device's *``* in the setup guide within the [User Manual's Out-of-the-Box Experience](https://docs.arduino.cc/tutorials/portenta-x8/user-manual#out-of-the-box-experience), through terminal commands involving *`adb`*, or by visiting **`http://192.168.7.1:8000`** on Windows and Linux (use **`http://192.168.8.1:8000`**for MacOS). -When you connect, you should get some feedback in the terminal. Text will begin printing in the terminal, showing you information about the connection that has just been established as shown in the image below. +Upon establishing a connection, your terminal will display details similar to those below. ![Terminal printout during connection](assets/webserver-connect-terminal.png) -Now you should see a webpage, like the following image, in your browser. +Your browser will then present the WordPress setup page, allowing you to commence the configuration process. ![Wordpress setup site](assets/webserver-wordpress-site.png) You are now free to go through the WordPress setup process and configure it however you like. -### Removing the containers ### +### Removing the Containers -If you want to remove the container, you have to go to ```/home/fio/wordpress-test``` directory (where we previously executed the docker-compose command) and execute the following commands according to your needs: +Should you need to remove the containers, navigate back to the *`/home/fio/wordpress-test`* directory and use the commands below based on your requirements. -Remove the container but preserves your WordPress database: +To remove the containers while retaining your WordPress data: ```bash docker compose down ``` -Remove the container and the database: +To delete both the containers and all associated data: ```bash docker compose down --volumes ``` -To make sure that it was successful, run ```docker ps -a``` and check that the WordPress and MariaDB containers have disappeared. +Confirm the removal by executing *`docker ps -a`* and verifying that the WordPress and MariaDB containers are no longer listed. ## Conclusion -In this tutorial, we went through how to install and run a WordPress and database container on the Portenta X8. We then accessed the WordPress site on our X8 through our web browser. So now you can set up your own WordPress site on your X8 device and access it from another device. +In this tutorial, we went through installing and running a WordPress and database container on the Portenta X8. We then accessed the WordPress site on our X8 through our web browser. Now, you can set up your WordPress site on your X8 device and access it from another device. ## Troubleshooting -- If the containers are not being installed or running correctly, check if there are any other containers currently running on the same ports as the ones used by the WordPress container. You can check it with ``docker ps -a``. +- If the containers are not being installed or running correctly, check if any other containers are currently running on the same ports as the ones used by the WordPress container. You can check it with ``docker ps -a``. -- If there is any issue running docker commands, make sure you are using ``sudo`` before the commands or having root access using: ``sudo su -r`` with password: ``fio``. +- If there is any issue running docker commands, ensure you are using ``sudo`` before the commands or having root access using: ``sudo su -r`` with password: ``fio``. - If you cannot connect to the site when everything is running, you can double-check the X8's IP address. Run the command `ip -h address` in the **adb shell**. This will display the X8's IP address via USB and Wi-Fi®. Try connecting via those IP addresses if all the rest fails.