flutter-pi

NEWS

• Added a (not complete) sentry plugin, see: https://github.com/ardera/flutter-pi/wiki/Sentry-Support
• There's now flutterpi tool to make building the app easier: https://pub.dev/packages/flutterpi_tool

flutter-pi

A light-weight Flutter Engine Embedder for Raspberry Pi. Inspired by https://github.com/chinmaygarde/flutter_from_scratch. Flutter-pi also runs without X11, so you don't need to boot into Raspbian Desktop & have X11 and LXDE load up; just boot into the command-line.

You can now theoretically run every flutter app you want using flutter-pi, including apps using packages & plugins, just that you'd have to build the platform side of the plugins you'd like to use yourself.

The difference between packages and plugins is that packages don't include any native code, they are just pure Dart. Plugins (like the shared_preferences plugin) include platform-specific code.

️ Supported Platforms

Although flutter-pi is only tested on a Rasberry Pi 4 2GB, it should work fine on other linux platforms, with the following conditions:

• support for hardware 3D acceleration. more precisely support for kernel-modesetting (KMS) and the direct rendering infrastructure (DRI)
• CPU architecture is one of ARMv7, ARMv8, x86 or x86 64bit.

This means flutter-pi won't work on a Pi Zero (only the first one) or Pi 1.

Known working boards:

• Pi 2, 3 and 4 (even the 512MB models)
• Pi Zero 2 (W)

If you encounter issues running flutter-pi on any of the supported platforms listed above, please report them to me and I'll fix them.

Contents

1. Building flutter-pi on the Raspberry Pi
   1.1 Dependencies
   1.2 Compiling
2. Running your App on the Raspberry Pi
   2.1 Configuring your Raspberry Pi
   2.2 Building the App
   2.3 Running your App with flutter-pi
   2.4 gstreamer video player
   2.5 audioplayers
3. Performance
   3.1 Graphics Performance
   3.2 Touchscreen latency
4. Useful Dart Packages
5. Discord

Building flutter-pi on the Raspberry Pi

• If you want to update flutter-pi, you check out the latest commit using git pull && git checkout origin/master and continue with compiling, step 2.

Dependencies

1. Install the engine-binaries (not required anymore, except when using the old method to build the app bundle, see below)

   Instructions

   • Follow the instructions in the flutter-engine-binaries-for-arm repo..

     More Info

     flutter-pi needs flutters icudtl.dat and libflutter_engine.so.{debug,profile,release} at runtime, depending on the runtime mode used. You actually have two options here:

     • you build the engine yourself. takes a lot of time, and it most probably won't work on the first try. But once you have it set up, you have unlimited freedom on which engine version you want to use. You can find some rough guidelines here.
     • you can use the pre-built engine binaries I am providing in the flutter-engine-binaries-for-arm repo.. I will only provide binaries for some engine versions though (most likely the stable ones).

2. Install cmake, graphics, system libraries and fonts:

   bash复制

   sudo apt install cmake libgl1-mesa-dev libgles2-mesa-dev libegl1-mesa-dev libdrm-dev libgbm-dev ttf-mscorefonts-installer fontconfig libsystemd-dev libinput-dev libudev-dev  libxkbcommon-dev

   If you want to use the gstreamer video player, install these too:

   bash复制

   sudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libgstreamer-plugins-bad1.0-dev gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-ugly gstreamer1.0-plugins-bad gstreamer1.0-libav gstreamer1.0-alsa

   More Info
   • flutter-pi needs the mesa OpenGL ES and EGL implementation and libdrm & libgbm. It may work with non-mesa implementations too, but that's untested.
   • The flutter engine depends on the Arial font. Since that doesn't come included with Raspbian, you need to install it.
   • libsystemd is not systemd, it's just an utility library. It provides the event loop and dbus support for flutter-pi.
   • libinput-dev, libudev-dev and libxkbcommon-dev are needed for (touch, mouse, raw keyboard and text) input support.
   • libudev-dev is required, but actual udev is not. Flutter-pi will just open all event devices inside /dev/input (unless overwritten using -i) if udev is not present.
   • gpiod and libgpiod-dev where required in the past, but aren't anymore since the flutter_gpiod plugin will directly access the kernel interface.

3. Update the system fonts.

   bash复制

   sudo fc-cache

Compiling

1. Clone flutter-pi and cd into the cloned directory:
   bash复制

   git clone --recursive https://github.com/ardera/flutter-pi
   cd flutter-pi

2. Compile:
   bash复制

   mkdir build && cd build
   cmake ..
   make -j`nproc`

3. Install:
   bash复制

   sudo make install

Running your App on the Raspberry Pi

Configuring your Raspberry Pi

1. Open raspi-config:

   bash复制

   sudo raspi-config

2. Switch to console mode: System Options -> Boot / Auto Login and select Console or Console (Autologin).

3. You can skip this if you're on Raspberry Pi 4 with Raspbian Bullseye
   Enable the V3D graphics driver:
   Advanced Options -> GL Driver -> GL (Fake KMS)

4. Configure the GPU memory Performance Options -> GPU Memory and enter 64.

5. Leave raspi-config.

6. Give the pi permission to use 3D acceleration. (NOTE: potential security hazard. If you don't want to do this, launch flutter-pi using sudo instead.)

   bash复制

   usermod -a -G render pi

7. Finish and reboot.

• flutter-pi requires that no other process, like a X11- or wayland-server, is using the video output. So to disable the desktop environment, we boot into console instead.
• The old broadcom-proprietary GL driver was bugged and not working with flutter, so we have to use the Fake KMS driver.
• Actually, you can also configure 16MB of GPU memory if you want to. 64MB are needed when you want to use the omxplayer_video_player plugin.
• pi isn't allowed to directly access the GPU because IIRC this has some privilege escalation bugs. Raspberry Pi has quite a lot of system-critical, not graphics-related stuff running on the GPU. I read somewhere it's easily possible to gain control of the GPU by writing malicious shaders. From there you can gain control of the CPU and thus the linux kernel. So basically the pi user could escalate privileges and become root just by directly accessing the GPU. But maybe this has already been fixed, I'm not sure.

Building the App (New Method, Linux-only)

The app must be built on your development machine. Note that you can't use a Raspberry Pi as your development machine.

One-time setup:

1. Make sure you've installed the flutter SDK. Only flutter SDK >= 3.10.5 is supported for the new method at the moment.
2. Install the flutterpi_tool: Run flutter pub global activate flutterpi_tool (One time only)
3. If running flutterpi_tool directly doesn't work, follow https://dart.dev/tools/pub/cmd/pub-global#running-a-script-from-your-path to add the dart global bin directory to your path.
   Alternatively, you can launch the tool via: flutter pub global run flutterpi_tool ...

Building the app bundle:

1. Open terminal or commandline and cd into your app directory.
2. Run flutterpi_tool build to build the app.
   • This will build the app for ARM 32-bit debug mode.
   • flutterpi_tool build --help gives more usage information.
   • For example, to build for 64-bit ARM, release mode, with a Raspberry Pi 4 tuned engine, use:
     flutterpi_tool build --arch=arm64 --cpu=pi4 --release
3. Deploy the bundle to the Raspberry Pi using rsync or scp:
   • Using rsync (available on linux and macOS or on Windows when using WSL)
     bash复制

     rsync -a --info=progress2 ./build/flutter_assets/ pi@raspberrypi:/home/pi/my_apps_flutter_assets

   • Using scp (available on linux, macOS and Windows)
     bash复制

     scp -r ./build/flutter_assets/ pi@raspberrypi:/home/pi/my_apps_flutter_assets

Example:

1. We'll build the asset bundle for flutter_gallery and deploy it using rsync to a Raspberry Pi 4 in this example.

git clone https://github.com/flutter/gallery.git flutter_gallery
cd flutter_gallery
git checkout d77920b4ced4a105ad35659fbe3958800d418fb9
flutter pub get
flutterpi_tool build --release --cpu=pi4
rsync -a ./build/flutter_assets/ pi@raspberrypi:/home/pi/flutter_gallery/

1. On Raspberry Pi, run sudo apt-get install xdg-user-dirs to install the runtime requirement of flutter_gallery. (otherwise it may throw exception)

2. Done. You can now run this app in release mode using flutter-pi --release /home/pi/flutter_gallery.

Building the App (old method, linux or windows)

1. Make sure you've installed the flutter SDK. You must use a flutter SDK that's compatible to the installed engine binaries.

   • for the flutter SDK, use flutter stable and keep it up to date.
   • always use the latest available engine binaries

   If you encounter error messages like Invalid kernel binary format version, Invalid SDK hash or Invalid engine hash:

   1. Make sure your flutter SDK is on stable and up to date and your engine binaries are up to date.
   2. If you made sure that's the case and the error still happens, create a new issue.

2. Open terminal or commandline and cd into your app directory.

3. flutter build bundle

4. Deploy the asset bundle to the Raspberry Pi using rsync or scp.

   • Using rsync (available on linux and macOS or on Windows when using WSL)
     bash复制

     rsync -a --info=progress2 ./build/flutter_assets/ pi@raspberrypi:/home/pi/my_apps_flutter_assets

   • Using scp (available on linux, macOS and Windows)
     bash复制

     scp -r ./build/flutter_assets/ pi@raspberrypi:/home/pi/my_apps_flutter_assets

Example

1. We'll build the asset bundle for flutter_gallery and deploy it using rsync in this example.

git clone https://github.com/flutter/gallery.git flutter_gallery
cd flutter_gallery
git checkout d77920b4ced4a105ad35659fbe3958800d418fb9
flutter build bundle
rsync -a ./build/flutter_assets/ pi@raspberrypi:/home/pi/flutter_gallery/

1. Done. You can now run this app in debug-mode using flutter-pi /home/pi/flutter_gallery.

• flutter_gallery is developed aga