devfest-pi-demo

This repository utilizes the Yocto Project's Poky reference distribution to build an embedded Linux OS capable of running Flutter in a few different ways.

Prerequisites

⚠️ Yocto Project tooling is required to run in a Linux environment. If you are on Windows or an Intel-based Mac, you will need to setup a Linux environment. Please note that, although this is tooling in this repository to facilitate developing on Windows/MacOS, full support is not guaranteed.

See the Dockerfile for the full list of dependencies if you are on a Linux host.

If you are on a Windows 11 (or 10) host, see windows_11_setup_steps.md for instructions on setting up your environment.

Getting Started

Clone this repository:

git clone --recursive [email protected]:lapumb-spindance/devfest-demo-pi.git

Note: if you do not add the --recursive flag, run ./tools/update_submodules.sh once the repository has successfully been cloned.

Containerized Development

This repository utilizes Yocto Project tooling that is required to be run in a Linux environment. Since not everyone has access to a Linux machine, this repository has been containerized using Visual Studio Code Remote Containers. This allows you to develop in a Linux environment without having to install Linux on your machine.

If you choose to use a containerized environment for development, the following dependencies must be installed:

MacOS:

brew install node
npm install -g @devcontainers/cli

Linux / WSL2:

Note: along with the following dependencies, if you are working in WSL(2) and have not already done so, it is probably a good idea to hike up your resources. For example, on a machine with 16GB RAM and 20 (logical) cores, you may want a configuration like the following in your ${env:USERPROFILE}\.wslconfig:

[wsl2]
memory=14GB
swap=4GB
processors=18

See the Microsoft documentation for more information about the .wslconfig.

sudo apt install nodejs npm -y
sudo npm cache clean -f
sudo npm install -g n
sudo n stable
sudo npm install -g @devcontainers/cli

⚠️ If you opt to develop directly in WSL(2), be sure to install the dependencies outlined in the Dockerfile.

Docker Desktop must also be installed and running. Make sure you are signed into a docker account (free is fine) and docker is running.

Visual Studio Code

Note: before proceeding, make sure you have the Dev Containers Extension installed and enabled in Visual Studio Code.

To utilize the container defined in this repository, open this repository in Visual Studio Code. You will likely be greeted with a prompt to "Reopen in Container". If so, click the "Reopen in Container" button, which will create a Docker container (if necessary) and mount you at the location of this repository in the container filesystem. If not, open the command palette (Mac: Cmd+Shift+P, Windows: Ctrl+Shift+P) and search for "Remote-Containers: Reopen in Container". A new VSCode window will open with the container running, where you can execute all your git commands and run the Yocto Project tooling.

Command Line

If you do not want to use VSCode, you can still use the containerized environment. From the root of this repository, run the following command, which will create a Docker container (if necessary) and mount you at the location of this repository in the container filesystem:

./.devcontainer/enter_container.sh

To exit the container, enter the exit command.

Important Note about Containerized Development

It has been observed that errors occur when attempting to enter the container in VS Code after having already entered the container from the command line (and / or vice-versa). If you run into this issue, delete the image / container that was spun up by the other method and try again. That said, it is probably best to stick to one method of entering the container until we figure out a more graceful solution.

Non-Containerized Development

Don't want to use a Docker container to build? No problem! See the Yocto Project Quick Start for setting up either your native Linux host.

Project-Level Environment Setup

Once you have your Linux environment setup, it is time to setup the project environment by sourcing the .envrc file:

source .envrc

This can be done manually, or you can use direnv (sudo apt install direnv) to automatically source this file when you enter the project directory.

Note: if using direnv, ensure the tool is properly hooked into your shell.

Custom Configurations

The .envrc file also sources a .userenv file if one is available. This file is ignored by git, so you can add any custom environment variables or overwrite any existing environment variables you see fit. For an example .userenv file, see the example file.

The bitbake Command

This repository is setup in a way that makes it simple for multiple developers to contribute to the same project. In order to achieve this, several custom environment variables have to be sent to bitbake to map dynamic paths correctly. Because of this, using the raw bitbake command will not work. Instead, utilize the execute_bitbake.sh script to properly source the environment variables and execute bitbake:

./execute_bitbake <additional_args_here>

Note: this script is used within the build.sh. Do not use this script directly unless you are experienced with the Yocto Project tooling.

Building and Flashing the Image

Once you have your environment setup and your hardware connected, it is time to build and flash the image to a uSD card. Building has been simplified to a build.sh script, which will build the core-image-base image by default. To build the image, simply run ./build.sh.

Once the build completes successfully, you can flash the image to a uSD card by running ./flash.sh if you are working on a native Linux machine. This script will automatically detect the newest image, but you also have the option to supply a specific image. Run ./flash.sh -h for more information.

Please note that running the flash.sh script requires sudo privileges, and that ⚠️ you must be cautious when specifying your device. If you specify the wrong device, you could potentially wipe your hard drive. Use lsblk to detect find your uSD device. You have been warned ⚠️.

If you are not on a native Linux machine, use the following for flashing:

• Windows: rufus

  Keep the default options, but when "SELECT"ing a file, make sure to change the filter to All files (*.*). When you plug in your uSD card, Windows will complain. Only focus on the rufus application and do not do anything with any explorer windows that pop up.

• MacOS: balenaEtcher

Hardware Setup

1. Raspberry Pi Zero 2W

2. uUSB <--> uUSB cable

3. uSD Card

4. Waveshare 7" Capacitive Touch Display

5. Header Pins

   Note: you will have to solder these pins to the Raspberry Pi Zero 2W. If you are not comfortable with soldering, you can use a Raspberry Pi Zero 2W with pre-soldered header pins, or a different Raspberry Pi SBC. If you opt for the latter, you will need to update the MACHINE variable in the local.conf file to match your Raspberry Pi SBC.

6. ESP-Prog

Serial Monitoring

On the ESP-Prog, we will use the 6-pin breakout section. Below is the pin layout for this section (x's denote pins we don't care about):

    +--------------+
    |  x   GND  x  |
    |  x   TX  RX  |
    +-----    -----+

NOTE: Notice the orientation of the break in the bottom of the wall around these pins; please make sure when you are wiring this, that break is facing down/south.

Once you have wires connected to those pins, please connect them to their respective pins on the Raspberry Pi breakout header:

    +-----------+
    |  x   x    |
    |  x   x    |
    |  x   GND  |
    |  x   TX   |
    |  x   RX   |
    |  x   x    |
    |  ..  ..   |
    +-----------+

NOTE: When looking at the Raspberry Pi, the above diagram assumes an orientation where the pins on the right side of the board.

Once the connections are made, you can monitor serial output from your Raspberry Pi by executing picocom (sudo apt install picocom), minicom (sudo apt install minicom), or any other serial monitoring tool of your choice after finding your device (ls /dev/ttyUSB*) and setting the baud rate to 115200:

# To exit picocom, press Ctrl+A followed by Ctrl+X.
picocom -b 115200 /dev/ttyUSB1

Running the Embedder Examples

The following sections outline the steps required to start and stop each embedder example. Please note that you must follow the "stop" steps for each example before starting another example.

wayland Embedder

To run the Gallery application using the wayland embedder, run the following:

# Start the Weston compositor
systemctl start weston

# Run the example
systemctl start flutter-gallery

# Note: if you want to monitor the service and Flutter logs:
journalctl -fu flutter-gallery

To stop the example, run:

systemctl stop weston
systemctl stop flutter-gallery

DRM Embedder

To run the Gallery application using the DRM embedder, run the following:

flutter-drm-gbm-backend --bundle=/usr/share/flutter/gallery/3.13.9/release/

# Optionally: append a " &" to the end of the command to run in the background so you can perform other tasks in the terminal

To stop the example, run:

# Find your process ID
ps | grep flutter-drm-gbm-backend

# Kill the process
kill <process_id>

flutter-pi Embedder

To run the Gallery application using the flutter-pi embedder, run the following:

flutter-pi --release /usr/share/flutter/gallery/3.13.9/release/

# Optionally: append a " &" to the end of the command to run in the background so you can perform other tasks in the terminal

To stop the example, run:

# Find your process ID
ps | grep flutter-pi

# Kill the process
kill <process_id>

Helpful Resources

• Yocto Project Documentation
• OpenEmbedded Layers Index
• DigiKey Yocto Project Introduction

  The first video in the series is focused on buildroot, but the rest of the videos are focused on the Yocto Project.

• Helpful Embedded Flutter Plugins
• Helpful Linux Flutter Packages
• Debugging Embedded Flutter Applications
• Debugging Flutter Embedders
• libflutter_engine.so Command Line Switches
• Raspberry Pi 40-pin Header Pinout