Repository files navigation

• 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

A light-weight Flutter Engine Embedder for Raspberry Pi. Inspired byhttps://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 nowtheoretically 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 theshared_preferences plugin) include platform-specific code.

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.

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

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

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

   Instructions

   • Follow the instructionsin theflutter-engine-binaries-for-arm repo..

     More Info

     flutter-pi needs fluttersicudtl.dat andlibflutter_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 guidelineshere.
     • you can use the pre-built engine binaries I am providingin theflutter-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:

   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 thegstreamer video player, install these too:

   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 theArial 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 andlibxkbcommon-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 allevent devices inside/dev/input (unless overwritten using-i) if udev is not present.
   • gpiod andlibgpiod-dev where required in the past, but aren't anymore since theflutter_gpiod plugin will directly access the kernel interface.

3. Update the system fonts.

   sudo fc-cache

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

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

2. Compile:

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

3. Install:

   sudo make install

1. Open raspi-config:

   sudo raspi-config

2. Switch to console mode:System Options -> Boot / Auto Login and selectConsole orConsole (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 memoryPerformance Options -> GPU Memory and enter64.

5. Leaveraspi-config.

6. Give thepi permission to use 3D acceleration. (NOTE: potential security hazard. If you don't want to do this, launchflutter-pi usingsudo instead.)

   usermod -a -G render pi

7. Finish and reboot.

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 theflutterpi_tool:Runflutter pub global activate flutterpi_tool (One time only)
3. If runningflutterpi_tool directly doesn't work, followhttps://dart.dev/tools/pub/cmd/pub-global#running-a-script-from-your-pathto 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 andcd into your app directory.
2. Runflutterpi_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 usingrsync orscp:
   • Usingrsync (available on linux and macOS or on Windows when usingWSL)

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

   • Usingscp (available on linux, macOS and Windows)

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

Example:

1. We'll build the asset bundle forflutter_gallery and deploy it usingrsync to a Raspberry Pi 4 in this example.

git clone https://github.com/flutter/gallery.git flutter_gallerycd flutter_gallerygit checkout d77920b4ced4a105ad35659fbe3958800d418fb9flutter pub getflutterpi_tool build --release --cpu=pi4rsync -a ./build/flutter_assets/ pi@raspberrypi:/home/pi/flutter_gallery/

2. On Raspberry Pi, runsudo apt-get install xdg-user-dirs to install the runtime requirement of flutter_gallery. (otherwise it maythrow exception)

3. Done. You can now run this app in release mode usingflutter-pi --release /home/pi/flutter_gallery.

git clone https://github.com/flutter/gallery.git flutter_gallerycd flutter_gallerygit checkout d77920b4ced4a105ad35659fbe3958800d418fb9flutter build bundlersync -a ./build/flutter_assets/ pi@raspberrypi:/home/pi/flutter_gallery/

pi@hpi4:~$ flutter-pi --helpflutter-pi - run flutter apps on your Raspberry Pi.USAGE:  flutter-pi [options] <bundle path> [flutter engine options]OPTIONS:  --release                  Run the app in release mode. The AOT snapshot                             of the app must be located inside the bundle directory.                             This also requires a libflutter_engine.so that was                             built with --runtime-mode=release.  --profile                  Run the app in profile mode. The AOT snapshot                             of the app must be located inside the bundle directory.                             This also requires a libflutter_engine.so that was                             built with --runtime-mode=profile.  --vulkan                   Use vulkan for rendering.  -o, --orientation <orientation>  Start the app in this orientation. Valid                             for <orientation> are: portrait_up, landscape_left,                             portrait_down, landscape_right.                             For more information about this orientation, see                             the flutter docs for the "DeviceOrientation"                             enum.                             Only one of the --orientation and --rotation                             options can be specified.  -r, --rotation <degrees>   Start the app with this rotation. This is just an                             alternative, more intuitive way to specify the                             startup orientation. The angle is in degrees and                             clock-wise.                             Valid values are 0, 90, 180 and 270.  -d, --dimensions "width_mm,height_mm" The width & height of your display in                             millimeters. Useful if your GPU doesn't provide                             valid physical dimensions for your display.                             The physical dimensions of your display are used                             to calculate the flutter device-pixel-ratio, which                             in turn basically "scales" the UI.  --pixelformat <format>     Selects the pixel format to use for the framebuffers.                             If this is not specified, a good pixel format will                             be selected automatically.                             Available pixel formats: RGB565, ARGB4444, XRGB4444, ARGB1555, XRGB1555, ARGB8888, XRGB8888, BGRA8888, BGRX8888, RGBA8888, RGBX8888,   --videomode widthxheight  --videomode widthxheight@hz  Uses an output videomode that satisfies the argument.                             If no hz value is given, the highest possible refreshrate                             will be used.  --dummy-display            Simulate a display. Useful for running apps                             without a display attached.  --dummy-display-size "width,height" The width & height of the dummy display                             in pixels.  --drm-fd <fd>              An opened and valid DRM file descriptor  -h, --help                 Show this help and exit.EXAMPLES:  flutter-pi ~/hello_world_app  flutter-pi --release ~/hello_world_app  flutter-pi -o portrait_up ./my_app  flutter-pi -r 90 ./my_app  flutter-pi -d "155, 86" ./my_app  flutter-pi --videomode 1920x1080 ./my_app  flutter-pi --videomode 1280x720@60 ./my_appSEE ALSO:  Author:  Hannes Winkler, a.k.a ardera  Source:  https://github.com/ardera/flutter-pi  License: MIT  For instructions on how to build an asset bundle or an AOT snapshot    of your app, please see the linked github repository.  For a list of options you can pass to the flutter engine, look here:    https://github.com/flutter/engine/blob/main/shell/common/switches.h

<asset bundle path> is the path of the flutter asset bundle directory (i.e. the directory containingkernel_blob.bin)of the flutter app you're trying to run.

[flutter engine options...] will be passed as commandline arguments to the flutter engine. You can find a list of commandline options for the flutter engineHere.

Gstreamer video player is a newer video player based on gstreamer.

To use the gstreamer video player, just rebuild flutter-pi (delete your build folder and reconfigure) and make sure the necessary gstreamer packages are installed. (Seedependencies)

And then, just use the stuff in the officialvideo_player package. (VideoPlayer,VideoPlayerController, etc, there's nothing specific you need to do on the dart-side)

As of current moment flutter-pi implements plugin foraudioplayers: ^5.0.0.There are several things you need to keep in mind:

• As flutter-pi is intended for use on constrained systems like raspberry pi, you should avoid creating multiple temporary instances and instead prefer to use one global instance ofAudioPlayer. There is limit you can easily hit if you're going to spam multiple instances ofAudioPlayer
• Plugin was tested to work with ALSA andpulseaudio might prevent the plugin from playing audio correctly:
  • Hence please make sure you deletepulseaudio package from your system.
  • Make sure you havegstreamer1.0-alsa package installed in addition to packages needed for gstreamer video player.
  • Make sure you can list audio devices using command:aplay -L
    • If there is error, please investigate why and fix it before using audio
    • One of the common reasons is outdated ALSA config in which case you should delete existing config and replace it with up to date one
• Finally, if you want to verify your audio setup is good, you can usegst-launch command to invokeplaybin on audio file directly.

Graphics performance is actually pretty good. With most of the apps inside theflutter SDK -> examples -> catalog directory I get smooth 50-60fps on the Pi 4 2GB and Pi 3 A+.

Due to the way the touchscreen driver works in raspbian, there's some delta between an actual touch of the touchscreen and a touch event arriving at userspace. The touchscreen driver in the raspbian kernel actually just repeatedly polls some buffer shared with the firmware running on the VideoCore, and the videocore repeatedly polls the touchscreen. (both at 60Hz) So on average, there's a delay of 17ms (minimum 0ms, maximum 34ms). Actually, the firmware is polling correctly at ~60Hz, but the linux driver is not because there's a bug. The linux side actually polls at 25Hz, which makes touch applications look terrible. (When you drag something in a touch application, but the application only gets new touch data at 25Hz, it'll look like the application itself isredrawing at 25Hz, making it look very laggy) The github issue for this raspberry pi kernel bug ishere. Leave a like on the issue if you'd like to see this fixed in the kernel.

This is why I created my own (userspace) touchscreen driver, for improved latency & polling rate. Seethis repo for details. The driver is very easy to use and the difference is noticeable, flutter apps look and feel a lot better with this driver.

There a#custom-embedders channel on theflutter discord which you can use if you have any questions regarding flutter-pi or generally, anything related to embedding the engine for which you don't want to open issue about or write an email.