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._
Although flutter-pi is only tested on a Rasberry Pi 4 2GB, it should work fine on other linux platforms, with the following conditions:
This means flutter-pi won't work on a Pi Zero (only the first one) or Pi 1.
Known working boards:
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.
git pull && git checkout origin/master and continue with compiling, step 2.Install the engine-binaries (not required anymore, except when using the old method to build the app bundle, see below)
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-devIf you want to use the gstreamer 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-alsaUpdate the system fonts.
sudo fc-cachegit clone --recursive https://github.com/ardera/flutter-pi
cd flutter-pimkdir build && cd build
cmake ..
make -j`nproc`sudo make installOpen raspi-config:
sudo raspi-configSwitch to console mode:
System Options -> Boot / Auto Login and select Console or Console (Autologin).
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)
Configure the GPU memory
Performance Options -> GPU Memory and enter 64.
Leave raspi-config.
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.)
usermod -a -G render piFinish 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:
flutter pub global activate flutterpi_tool (One time only)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.flutter pub global run flutterpi_tool ...Building the app bundle:
cd into your app directory.flutterpi_tool build to build the app.
flutterpi_tool build --help gives more usage information.flutterpi_tool build --arch=arm64 --cpu=pi4 --releasersync or scp:
rsync (available on linux and macOS or on Windows when using WSL)
rsync -a --info=progress2 ./build/flutter_assets/ pi@raspberrypi:/home/pi/my_apps_flutter_assetsscp (available on linux, macOS and Windows)
scp -r ./build/flutter_assets/ pi@raspberrypi:/home/pi/my_apps_flutter_assetsExample:
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/On Raspberry Pi, run sudo apt-get install xdg-user-dirs to install the runtime requirement of flutter_gallery. (otherwise it may throw exception)
Done. You can now run this app in release mode using flutter-pi --release /home/pi/flutter_gallery.
pi@hpi4:~ $ flutter-pi --help
flutter-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.
-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_app
SEE 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 containing kernel_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 engine Here.
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. (See dependencies)
And then, just use the stuff in the official video_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 for audioplayers: ^5.0.0.
There are several things you need to keep in mind:
AudioPlayer. There is limit you can easily hit if you're going to spam multiple instances of AudioPlayerpulseaudio might prevent the plugin from playing audio correctly:
pulseaudio package from your system.gstreamer1.0-alsa package installed in addition to packages needed for gstreamer video player.aplay -L
gst-launch command to invoke playbin on audio file directly.Graphics performance is actually pretty good. With most of the apps inside the flutter 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 is redrawing at 25Hz, making it look very laggy) The github issue for this raspberry pi kernel bug is here. 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. See this 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.
| Package | Category | Author | Description |
|---|---|---|---|
| flutterpi_tool (package) (repo) | 🔧 tooling | Hannes Winkler (me) | Tool to make developing & distributing apps for flutter-pi easier. |
| flutter_gpiod (package) (repo) | 🖨 peripherals | Hannes Winkler | GPIO control support for dart/flutter, uses kernel interfaces directly for more performance. |
| linux_serial (package) (repo) | 🖨 peripherals | Hannes Winkler | Serial Port support for dart/flutter, uses kernel interfaces directly for more performance. |
| linux_spidev (package) (repo) | 🖨 peripherals | Hannes Winkler | SPI bus support for dart/flutter, uses kernel interfaces directly for more performance. |
| dart_periphery (package) (repo) | 🖨 peripherals | Peter Sauer | All-in-one package GPIO, I2C, SPI, Serial, PWM, Led, MMIO support using c-periphery. |
| flutterpi_gstreamer_video_player (package) (repo) | ⏯️ multimedia | Hannes Winkler | Official video player implementation for flutter-pi. See GStreamer video player section above. |
| charset_converter (package) (repo) | 🗚 encoding | Bartosz Wiśniewski | Encode and decode charsets using platform built-in converter. |
| sentry_flutter (package) (repo) | 📊 Monitoring | sentry.io | See https://github.com/ardera/flutter-pi/wiki/Sentry-Support for instructions. |
There a #custom-embedders channel on the flutter 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.