|
| 1 | +--- |
| 2 | +beta: true |
| 3 | +title: 'How To Build a Custom Image for Your Portenta X8' |
| 4 | +description: 'This tutorial teaches you how to compile a custom image for your Portenta X8' |
| 5 | +difficulty: advanced |
| 6 | +tags: |
| 7 | + - Embedded Linux |
| 8 | + - Building |
| 9 | + - Yocto-project |
| 10 | +author: 'Pablo Marquínez' |
| 11 | +hardware: |
| 12 | + - hardware/04.pro/boards/portenta-x8 |
| 13 | +--- |
| 14 | + |
| 15 | +## Overview |
| 16 | + |
| 17 | +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). |
| 18 | +Building your image locally can help debug certain aspects of the system, such as the bootloader or kernel support. |
| 19 | + |
| 20 | +***Keep in mind that 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. |
| 21 | +This tutorial targets customers that are not FoundriesFactory subscribers, but still want to extend the functionality of the Arduino pre-built sources by building their own images. For FoundriesFactory subscribers, we strongly suggest making use of your Factory's continuous integration system for creating images.*** |
| 22 | + |
| 23 | +## Goals |
| 24 | + |
| 25 | +- Build a "builder" Docker image |
| 26 | +- Get the required files |
| 27 | +- Configure the build settings |
| 28 | +- Build the image |
| 29 | +- Save the needed files for flashing |
| 30 | + |
| 31 | +### Required Hardware and Software |
| 32 | + |
| 33 | +- [Docker Engine](https://docs.docker.com/engine/install/) |
| 34 | +- [Arduino Portenta X8](https://store.arduino.cc/products/portenta-x8) |
| 35 | +- ~60GB available space on your machine's drive |
| 36 | + |
| 37 | +## Instructions |
| 38 | + |
| 39 | +### Docker |
| 40 | + |
| 41 | +#### Build the Docker Image |
| 42 | + |
| 43 | +You will create a Docker image that has the dependencies needed to build your device image. |
| 44 | + |
| 45 | +To do so you will need to clone our [lmp-manifest repository](https://github.com/arduino/lmp-manifest), follow these steps to do so: |
| 46 | + |
| 47 | +First, clone the lmp-manifest repository with this command: |
| 48 | + ``` |
| 49 | + git clone https://github.com/arduino/lmp-manifest.git |
| 50 | + ``` |
| 51 | +  |
| 52 | + |
| 53 | +Then build the Docker Image using: |
| 54 | + ``` |
| 55 | + cd lmp-manifest |
| 56 | + docker build -t yocto-build ./lmp-manifest |
| 57 | + ``` |
| 58 | +  |
| 59 | + |
| 60 | +#### Run The Docker Image (Builder) |
| 61 | + |
| 62 | +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. |
| 63 | + |
| 64 | +***If you do not use a volume while running the image, you will lose the data when the image stops*** |
| 65 | + |
| 66 | +Run the `yocto-build` builder image with: |
| 67 | +``` |
| 68 | +docker run -v <source>:/dockerVolume -it yocto-build bash |
| 69 | +``` |
| 70 | + |
| 71 | +Switch to the `builder` user with the following command, the password is **builder**: |
| 72 | +``` |
| 73 | +su builder |
| 74 | +``` |
| 75 | + |
| 76 | +### Setup and Build |
| 77 | + |
| 78 | +***You can download a [bash script](assets/portenta-x8_build.sh) that wraps all the upcoming steps.*** |
| 79 | + |
| 80 | +#### Setup the Environment |
| 81 | + |
| 82 | +Now that you are running inside the Docker Image, you can use tools like **git-repo**, which is already installed. |
| 83 | + |
| 84 | +First configure git with your credentials. They don't need to be the real ones, but are required by `git-repo` to pull. |
| 85 | +Copy and paste the following: |
| 86 | +``` |
| 87 | +git config --global user.email "you@example.com" |
| 88 | +git config --global user.name "Your Name" |
| 89 | +``` |
| 90 | + |
| 91 | + |
| 92 | +Change to the home directory, and initialize the repository using **repo**: |
| 93 | +``` |
| 94 | +cd ~ |
| 95 | +repo init -u https://github.com/arduino/lmp-manifest.git -m arduino.xml -b release |
| 96 | +``` |
| 97 | + |
| 98 | + |
| 99 | +Then pull the needed files with: |
| 100 | +``` |
| 101 | +repo sync |
| 102 | +``` |
| 103 | + |
| 104 | + |
| 105 | +After completion it should look like the following image: |
| 106 | + |
| 107 | + |
| 108 | + |
| 109 | +***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.*** |
| 110 | + |
| 111 | +#### Set Up The Portenta X8 Distribution |
| 112 | + |
| 113 | +You can set `DISTRO` to: |
| 114 | +- `lmp-base`: insecure image without ostree, developer friendly, not OTA compatible |
| 115 | +- `lmp`: secure image without xwayland |
| 116 | +- `lmp-xwayland`: secure image with xwayland support |
| 117 | + |
| 118 | +***`lmp-partner-arduino-image` will be better supported in the near future.*** |
| 119 | + |
| 120 | +```bash |
| 121 | +DISTRO=lmp-xwayland MACHINE=portenta-x8 . setup-environment |
| 122 | +``` |
| 123 | + |
| 124 | +It will then switch automatically to a new folder. Now to accept the EULA with: |
| 125 | + |
| 126 | +```bash |
| 127 | +echo "ACCEPT_FSL_EULA = \"1\"" >> conf/local.conf |
| 128 | +``` |
| 129 | + |
| 130 | + |
| 131 | + |
| 132 | +#### Build Image With Bitbake |
| 133 | + |
| 134 | +To start building the image, run: |
| 135 | + |
| 136 | +``` |
| 137 | +bitbake lmp-partner-arduino-image |
| 138 | +``` |
| 139 | +***This process takes ~7h depending on the build host*** |
| 140 | + |
| 141 | + |
| 142 | + |
| 143 | +In case you want to use your computer while it builds, (which is going to take time and resources) you should lower the threads used. |
| 144 | +Do so by opening `conf/local.conf` and lower the values of the following variables: |
| 145 | + |
| 146 | +- `BB_NUMBER_PARSE_THREADS = "4"` |
| 147 | +- `BB_NUMBER_THREADS = "4"` |
| 148 | + |
| 149 | +And add: |
| 150 | + |
| 151 | +- `PARALLEL_MAKE = "-j 4"` |
| 152 | + |
| 153 | +Once it finishes you will see something similar to: |
| 154 | + |
| 155 | + |
| 156 | +#### Setup Manufacturing Tools |
| 157 | + |
| 158 | +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`: |
| 159 | +``` |
| 160 | +cd .. |
| 161 | +DISTRO=lmp-mfgtool MACHINE=portenta-x8 . setup-environment |
| 162 | +echo "ACCEPT_FSL_EULA = \"1\"" >> conf/local.conf |
| 163 | +echo "MFGTOOL_FLASH_IMAGE = \"lmp-partner-arduino-image\"" >> conf/local.conf |
| 164 | +``` |
| 165 | + |
| 166 | + |
| 167 | +#### Build Manufacturing Tools: Flash The Board |
| 168 | + |
| 169 | +To compile and get the tools you will need to type: |
| 170 | +``` |
| 171 | +bitbake mfgtool-files |
| 172 | +``` |
| 173 | + |
| 174 | + |
| 175 | +After completion: |
| 176 | + |
| 177 | + |
| 178 | +***This process takes ~2h depending on your build host*** |
| 179 | + |
| 180 | +#### Save Your Image For Flashing |
| 181 | + |
| 182 | +After a successful build, save the needed files to the host volume you mounted with `docker run`. Use the following commands to copy the files to your storage unit: |
| 183 | + |
| 184 | +``` |
| 185 | +cd .. |
| 186 | +mkdir ../../dockerVolume/flashing |
| 187 | +DEPLOY_FOLDER=../../dockerVolume/flashing |
| 188 | +
|
| 189 | +cp -L build-lmp-mfgtool/deploy/images/portenta-x8/mfgtool-files-portenta-x8.tar.gz $DEPLOY_FOLDER |
| 190 | +cp -L build-lmp-xwayland/deploy/images/portenta-x8/imx-boot-portenta-x8 $DEPLOY_FOLDER |
| 191 | +cp -L build-lmp-xwayland/deploy/images/portenta-x8/u-boot-portenta-x8.itb $DEPLOY_FOLDER |
| 192 | +cp -L build-lmp-xwayland/deploy/images/portenta-x8/sit-portenta-x8.bin $DEPLOY_FOLDER |
| 193 | +cp -L build-lmp-xwayland/deploy/images/portenta-x8/lmp-partner-arduino-image-portenta-x8.wic $DEPLOY_FOLDER |
| 194 | +
|
| 195 | +cd $DEPLOY_FOLDER |
| 196 | +tar xvf mfgtool-files-portenta-x8.tar.gz |
| 197 | +``` |
| 198 | + |
| 199 | + |
| 200 | + |
| 201 | +You will be able to see the copied files in your OS file explorer. |
| 202 | + |
| 203 | + |
| 204 | + |
| 205 | +## Conclusion |
| 206 | + |
| 207 | +Now you have all the required files to flash the image you built onto the device. |
| 208 | + |
| 209 | +Please follow the [Flashing tutorial](image-flashing) to flash your device with your custom image. |
| 210 | +Keep in mind you will need to use the files provided from this build, not the ones mentioned in the Flashing tutorial. |
| 211 | + |
| 212 | +## Troubleshooting |
| 213 | + |
| 214 | +- If you are having `do_fetch` issues, try to check your system's and virtual machine's DNS settings. |
0 commit comments