docs/0_Getting_Started/2_Developing_an_AGL_Image/9_Building_for_Raspberry_Pi_3_or_4.md

   1 ---
   2 edit_link: ''
   3 title: Build for Raspberry PI 3/4
   4 origin_url: >-
   5   https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/getting-started/machines/raspberrypi.md
   6 ---
   7
   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 -->
   9
  10 # Building for Raspberry Pi 3 or 4
  11
  12 The
  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.
  19 See the
  20 [Raspberry Pi Product Page](https://www.raspberrypi.org/products/) for more information.
  21
  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.
  24
  25 ## 1. Making Sure Your Build Environment is Correct
  26
  27 The
  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.
  33
  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:
  38
  39 **Raspberry Pi 4**:
  40
  41 ```bash
  42 $ source meta-agl/scripts/aglsetup.sh -m raspberrypi4 agl-demo agl-netboot agl-appfw-smack
  43 ```
  44
  45 **Raspberry Pi 3**:
  46
  47 ```bash
  48 $ source meta-agl/scripts/aglsetup.sh -m raspberrypi3 agl-demo agl-netboot agl-appfw-smack
  49 ```
  50
  51 ## 2. Configuring the Build to Include Packages Under a Commercial License
  52
  53 Before launching the build, it is good to be sure your build
  54 configuration is set up correctly (`/build/conf/local.conf` file).
  55 The
  56 "[Customizing Your Build](../image-workflow-cust-build.html)"
  57 section highlights some common configurations that are useful when
  58 building any AGL image.
  59
  60 For the Raspberry Pi platforms, you need to take an additional
  61 configuration step if you want to include any packages under a
  62 commercial license.
  63
  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:
  69
  70 ```bash
  71 # For libomxil
  72 LICENSE_FLAGS_WHITELIST = "commercial"
  73
  74 IMAGE_INSTALL_append = " libomxil"
  75 ```
  76
  77 ## 3. Using BitBake
  78
  79 This section shows the `bitbake` command used to build the AGL image.
  80
  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
  83 board.
  84 You can find this pre-built image on the
  85 [AGL Download web site](https://download.automotivelinux.org/AGL/release).
  86
  87 For the supported image, the filename has the following form:
  88
  89 ```
  90 <release-name>/<release-number>/raspberrypi3/deploy/images/raspberrypi3/*
  91 ```
  92
  93
  94 Start the build using the `bitbake` command.
  95
  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.
  99
 100 For this example, the target is "agl-demo-platform":
 101
 102 ```bash
 103 $ bitbake agl-demo-platform
 104 ```
 105
 106 By default, the build process puts the resulting image in the Build Directory.
 107 Here is example for the Raspberry Pi 4 board:
 108
 109 ```
 110 <build_directory>/tmp/deploy/images/raspberrypi4/agl-demo-platform-raspberrypi4.wic.xz
 111 ```
 112
 113 If you build for the Raspberry Pi 3 board, the location uses "raspberrypi3" in the path.
 114
 115 ## 4. Deploying the AGL Demo Image
 116
 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.
 119
 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:
 122
 123 1. Plug your MicroSD card into your Build Host (i.e. the system that has your build output).
 124
 125 2. Be sure you know the MicroSD device name.
 126
 127    Use the `dmesg` command as follows to discover the device name:
 128
 129    ```bash
 130    $ dmesg | tail -4
 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
 135    ```
 136
 137    In the previous example, the MicroSD card is attached to the device `/dev/sdc`.
 138
 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`:
 141
 142    ```bash
 143    $ lsblk
 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
 154    ```
 155
 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
 158    device.
 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.
 162
 163    To summarize this example so far, we have the following:
 164
 165    * The first SATA drive is `/dev/sda`.
 166
 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
 169      for that device.
 170
 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.
 173
 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`.
 176
 177    Be sure you are root, provide the actual device name for *sdcard_device_name*, and the actual
 178    image name for *image_name*:
 179
 180    ```bash
 181    $ sudo umount <sdcard_device_name>
 182    $ xzcat <image_name> | sudo dd of=<sdcard_device_name> bs=4M
 183    $ sync
 184    ```
 185
 186 4. Plug your MicroSD card into the Raspberry Pi board and boot the device.
 187
 188 ## 5. Using the Raspberry Pi Touch Display
 189
 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.
 193
 194 Plenty of information exists on how to configure and use this touchscreen.
 195 See the following references for more information:
 196
 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).
 199
 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).
 202
 203 * For information on Weston, which is the reference implementation of Wayland, see
 204   [Wayland](https://wiki.archlinux.org/index.php/wayland).
 205
 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
 208 display:
 209
 210 ```bash
 211 root@raspberrypi3:/etc/xdg/weston# cat weston.ini
 212 [core]
 213 backend=drm-backend.so
 214 shell=desktop-shell.so
 215
 216 [shell]
 217 locking=true
 218 # Uncomment below to hide panel
 219 #panel-location=none
 220
 221 [launcher]
 222 icon=/usr/share/weston/terminal.png
 223 path=/usr/bin/weston-terminal
 224
 225 [launcher]
 226 icon=/usr/share/weston/icon_flower.png
 227 path=/usr/bin/weston-flower
 228
 229 [output]
 230 name=DSI-1
 231 transform=270
 232 ```
 233
 234 ## 6. Debugging
 235
 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/).
 241
 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.
 245
 246 Use the following steps, which assume you are using the previously mentioned
 247 Olimex cable.
 248 You can reference the following diagram for information on the following steps:
 249
 250 <p align="center">
 251   <img src="images/RaspberryPi2-ModelB-debug-serial-cable.png">
 252 </p>
 253
 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.
 257
 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.
 261
 262 2. Connect the cable's BLUE wire to pin 6 (i.e. Ground) of the UART.
 263
 264 3. Connect the cable's GREEN RX line to pin 8 (i.e. the TXD line) of
 265    the UART.
 266
 267 4. Connect the cable's RED TX line to pin 10 (i.e. the RXD line) of
 268    the UART.
 269
 270 5. Plug the USB connector of the cable into your build host's USB port.
 271
 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:
 276
 277    ```bash
 278    $ sudo screen /dev/ttyUSB0 115200
 279    ```
 280
 281 ## 7. SOTA
 282
 283 Follow the step below to build AGL for Raspberry Pi with enabled software over
 284 the air (SOTA) updates:
 285
 286 1. Include **agl-sota** feature.
 287
 288 2. In **bblayers.conf** replace meta-updater-qemux86-64 with
 289    **meta-updater-raspberrypi**.
 290
 291 3. In **local.conf** set `SOTA_PACKED_CREDENTIALS` and `OSTREE_BRANCHNAME`.
 292
 293 More details are available [here](https://docs.ota.here.com/getstarted/dev/raspberry-pi.html).