3 title: Build for Raspberry PI 3/4
5 https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/getting-started/machines/raspberrypi.md
8 <!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/getting_started/master/image-development-workflow-getting-started-book.yml -->
10 # Building for Raspberry Pi 3 or 4
13 [Raspberry Pi](https://www.raspberrypi.org/help/what-%20is-a-raspberry-pi/) is a small
14 computer that is ideal for learning computing and computer languages.
15 The AGL Project supports building images for the
16 [Raspberry Pi 3](https://www.raspberrypi.org/products/raspberry-pi-3-model-a-plus/) and the
17 [Raspberry Pi 4](https://www.raspberrypi.org/products/raspberry-pi-4-model-b/) boards.
18 Each of these boards comes in a variety of models.
20 [Raspberry Pi Product Page](https://www.raspberrypi.org/products/) for more information.
22 This section describes the steps you need to take to build the
23 AGL demo image for both the Raspberry Pi 4 and 3 boards. Raspberry Pi 4 is recommended.
25 ## 1. Making Sure Your Build Environment is Correct
28 "[Initializing Your Build Environment](../image-workflow-initialize-build-environment.html)"
29 section presented generic information for setting up your build environment
30 using the `aglsetup.sh` script.
31 If you are building the AGL demo image for a Raspberry Pi board, you need to specify some
32 specific options when you run the script.
34 Use the following commands to initialize your build environment.
35 In each case, the "-m" option specifies the machine and the
36 list of AGL features used with script are appropriate for development of
37 the AGL demo image suited for either Raspberry Pi 4 (recommended) or 3:
42 $ source meta-agl/scripts/aglsetup.sh -m raspberrypi4 agl-demo agl-netboot agl-appfw-smack
48 $ source meta-agl/scripts/aglsetup.sh -m raspberrypi3 agl-demo agl-netboot agl-appfw-smack
51 ## 2. Configuring the Build to Include Packages Under a Commercial License
53 Before launching the build, it is good to be sure your build
54 configuration is set up correctly (`/build/conf/local.conf` file).
56 "[Customizing Your Build](../image-workflow-cust-build.html)"
57 section highlights some common configurations that are useful when
58 building any AGL image.
60 For the Raspberry Pi platforms, you need to take an additional
61 configuration step if you want to include any packages under a
64 For example, suppose you want to include an implementation of the
65 [OpenMAX](https://www.khronos.org/openmax/) Intagration Library
66 (`libomxil`) under a commercial license as part of your AGL image.
67 If so, you must include the following two lines in your
68 `/build/conf/local.conf` file:
72 LICENSE_FLAGS_WHITELIST = "commercial"
74 IMAGE_INSTALL_append = " libomxil"
79 This section shows the `bitbake` command used to build the AGL image.
81 Before running BitBake to start your build, it is good to be reminded that AGL
82 does provide a pre-built image for developers that want to use the Raspberry Pi 3
84 You can find this pre-built image on the
85 [AGL Download web site](https://download.automotivelinux.org/AGL/release).
87 For the supported image, the filename has the following form:
90 <release-name>/<release-number>/raspberrypi3/deploy/images/raspberrypi3/*
94 Start the build using the `bitbake` command.
96 **NOTE:** An initial build can take many hours depending on your
97 CPU and and Internet connection speeds.
98 The build also takes approximately 100G-bytes of free disk space.
100 For this example, the target is "agl-demo-platform":
103 $ bitbake agl-demo-platform
106 By default, the build process puts the resulting image in the Build Directory.
107 Here is example for the Raspberry Pi 4 board:
110 <build_directory>/tmp/deploy/images/raspberrypi4/agl-demo-platform-raspberrypi4.wic.xz
113 If you build for the Raspberry Pi 3 board, the location uses "raspberrypi3" in the path.
115 ## 4. Deploying the AGL Demo Image
117 Deploying the AGL demo image consists of copying the image on a MicroSD card,
118 plugging the card into the Raspberry Pi board, and then booting the board.
120 Follow these steps to copy the image to a MicroSD card and boot
121 the image on the Raspberry Pi 3 or 4 board:
123 1. Plug your MicroSD card into your Build Host (i.e. the system that has your build output).
125 2. Be sure you know the MicroSD device name.
127 Use the `dmesg` command as follows to discover the device name:
131 [ 1971.462160] sd 6:0:0:0: [sdc] Mode Sense: 03 00 00 00
132 [ 1971.462277] sd 6:0:0:0: [sdc] No Caching mode page found
133 [ 1971.462278] sd 6:0:0:0: [sdc] Assuming drive cache: write through
134 [ 1971.463870] sdc: sdc1 sdc2
137 In the previous example, the MicroSD card is attached to the device `/dev/sdc`.
139 You can also use the `lsblk` command to show all your devices.
140 Here is an example that shows the MicroSD card as `/dev/sdc`:
144 NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
145 sda 8:0 0 167,7G 0 disk
146 ├─sda1 8:1 0 512M 0 part /boot/efi
147 ├─sda2 8:2 0 159,3G 0 part /
148 └─sda3 8:3 0 7,9G 0 part [SWAP]
149 sdb 8:16 0 931,5G 0 disk
150 └─sdb1 8:17 0 931,5G 0 part /media/storage
151 sdc 8:32 1 14,9G 0 disk
152 ├─sdc1 8:33 1 40M 0 part
153 └─sdc2 8:34 1 788M 0 part
156 **IMPORTANT NOTE:** Before re-writing any device on your Build Host, you need to
157 be sure you are actually writing to the removable MicroSD card and not some other
159 Each computer is different and removable devices can change from time to time.
160 Consequently, you should repeat the previous operation with the MicroSD card to
161 confirm the device name every time you write to the card.
163 To summarize this example so far, we have the following:
165 * The first SATA drive is `/dev/sda`.
167 * `/dev/sdc` corresponds to the MicroSD card, and is also marked as a removable device.
168 You can see this in the output of the `lsblk` command where "1" appears in the "RM" column
171 3. Now that you know the device name, unmount the device and use the
172 `xzcat` command to copy the image to the MicroSD card.
174 **NOTE:** For Raspberry Pi 3, the image is at `build/tmp/deploy/images/raspberrypi3/agl-demo-platform-raspberrypi3.wic.xz`.
175 For Raspberry Pi 4, the image is at `build/tmp/deploy/images/raspberrypi4/agl-demo-platform-raspberrypi4.wic.xz`.
177 Be sure you are root, provide the actual device name for *sdcard_device_name*, and the actual
178 image name for *image_name*:
181 $ sudo umount <sdcard_device_name>
182 $ xzcat <image_name> | sudo dd of=<sdcard_device_name> bs=4M
186 4. Plug your MicroSD card into the Raspberry Pi board and boot the device.
188 ## 5. Using the Raspberry Pi Touch Display
190 If you have connected the official
191 [Raspberry Pi Touch Display](https://www.raspberrypi.org/products/raspberry-pi-touch-display/),
192 you can configure the display by editing the `weston.ini` file.
194 Plenty of information exists on how to configure and use this touchscreen.
195 See the following references for more information:
197 * For information on where the `weston.ini` file is located, see
198 [location](https://jlk.fjfi.cvut.cz/arch/manpages/man/weston.ini.5#DESCRIPTION).
200 * For information on the `weston.ini` file in general, see the
201 [manpage](https://jlk.fjfi.cvut.cz/arch/manpages/man/weston.ini.5).
203 * For information on Weston, which is the reference implementation of Wayland, see
204 [Wayland](https://wiki.archlinux.org/index.php/wayland).
206 As an example on how to configure and manipulate the touchscreen, consider
207 the following edits to the `weston.ini` file used to rotate the
211 root@raspberrypi3:/etc/xdg/weston# cat weston.ini
213 backend=drm-backend.so
214 shell=desktop-shell.so
218 # Uncomment below to hide panel
222 icon=/usr/share/weston/terminal.png
223 path=/usr/bin/weston-terminal
226 icon=/usr/share/weston/icon_flower.png
227 path=/usr/bin/weston-flower
236 When things go wrong, you can take steps to debug your Raspberry Pi.
237 For debugging, you need a 3.3 Volt USB Serial cable to fascilitate
238 communication between your Raspberry Pi board and your build host.
239 A good cable to use is the 3.3V USB-to-Serial cable
240 [Olimex USB-Serial-Cable-F](https://www.olimex.com/Products/Components/Cables/USB-Serial-Cable/USB-Serial-Cable-F/).
242 **NOTE:** If you are using a USB console cable from Adafruit, see
243 "[Adafruit's Raspberry Pi Lesson 5](https://learn.adafruit.com/adafruits-raspberry-pi-lesson-5-using-a-console-cable/connect-the-lead)"
244 for connection information.
246 Use the following steps, which assume you are using the previously mentioned
248 You can reference the following diagram for information on the following steps:
251 <img src="images/RaspberryPi2-ModelB-debug-serial-cable.png">
254 1. Connect the Olimex cable to the Universal Asynchronous Receiver-Transmitter
255 (UART) connection on your Raspberry Pi board.
256 Do not connect the USB side of the cable to your build host at this time.
258 **CAUTION:** No warranty is provided using the following procedure.
259 Pay particular attention to the collors of your cable as they could
260 vary depending on the vendor.
262 2. Connect the cable's BLUE wire to pin 6 (i.e. Ground) of the UART.
264 3. Connect the cable's GREEN RX line to pin 8 (i.e. the TXD line) of
267 4. Connect the cable's RED TX line to pin 10 (i.e. the RXD line) of
270 5. Plug the USB connector of the cable into your build host's USB port.
272 6. Use your favorite tool for serial communication between your build host
273 and your Raspberry Pi.
274 For example, if your build host is a native Linux machine (e.g. Ubuntu)
275 you could use `screen` as follows from a terminal on the build host:
278 $ sudo screen /dev/ttyUSB0 115200
283 Follow the step below to build AGL for Raspberry Pi with enabled software over
284 the air (SOTA) updates:
286 1. Include **agl-sota** feature.
288 2. In **bblayers.conf** replace meta-updater-qemux86-64 with
289 **meta-updater-raspberrypi**.
291 3. In **local.conf** set `SOTA_PACKED_CREDENTIALS` and `OSTREE_BRANCHNAME`.
293 More details are available [here](https://docs.ota.here.com/getstarted/dev/raspberry-pi.html).