- the physical dimensions of the screen can now be specified via cmdline, using the
--dimensions
option. - the layout of the engine-binaries branch has changed again. The symbolic link from
libflutter_engine.so
to the fittinglibflutter_engine.so.release
orlibflutter_engine.so.debug
is no longer needed, flutter-pi will now dynamically load the engine fitting the the runtime mode that was specified via cmdline. (if--release
is given, flutter-pi will loadlibflutter_engine.so.release
, elselibflutter_engine.so.debug
) - flutter-pi now requires
libsystemd-dev
,libinput-dev
andlibudev-dev
at compile-time. (libudev-dev
is actually optional. To build without udev support, use cmake.) - flutter-pi and the engine binaries updated for flutter 1.20.
- it's possible to run flutter-pi in AOT mode now. Instructions for that are WIP.
--aot
was renamed to--release
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 extensions & plugins, just that you'd have to build the platform side of the plugins you'd like to use yourself.
The difference between extensions and plugins is that extensions don't include any native code, they are just pure dart. Plugins (like the connectivity 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, ARM64, x86 or x86 64bit.
This means flutter-pi won't work on a Pi Zero, Pi 1, or Pi 2. A Pi 3 works fine, even the 512MB A+ model.
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.
- Running your App on the Raspberry Pi
1.1 Configuring your Raspberry Pi
1.2 Building the Asset bundle
1.3 Building theapp.so
(for running your app in Release/Profile mode)
1.4 Running your App with flutter-pi - Dependencies
- Compiling flutter-pi (on the Raspberry Pi)
- Performance
- Keyboard Input
- Touchscreen Latency
flutter-pi only works when Raspbian is in console mode (no X11 or Wayland server running). To switch the Pi into console mode,
go to raspi-config -> Boot Options -> Desktop / CLI
and select Console
or Console (Autologin)
.
flutter-pi doesn't support the legacy broadcom-proprietary graphics stack anymore. You need to make sure the V3D driver in raspi-config.
Go to raspi-config -> Advanced Options -> GL Driver
and select GL (Fake-KMS)
.
With this driver, it's best to give the GPU as little RAM as possible in raspi-config -> Advanced Options -> Memory Split
, which is 16MB
. This is because the V3D driver doesn't need GPU RAM anymore. NOTE: If you want to use the omxplayer_video_player
plugin to play back videos in flutter, you need to give the GPU some more RAM, like 64MB.
It seems like with newer versions of Raspbian, the pi
user doesn't have sufficient permissions to directly access the GPU anymore. IIRC, this is because of some privilege escalation / arbitrary code execution problems of the GPU interface.
You can fix this by adding the pi
user to the render
group, but keep in mind that may be a security hazard:
usermod -a -G render pi
Then, restart your terminal session so the changes take effect. (reconnect if you're using ssh or else just reboot the Pi)
Otherwise, you'll need to run flutter-pi
with sudo
.
Then to build the asset bundle, run the following commands on your host machine. You can't build the asset bundle on target (== your Raspberry Pi), since the flutter SDK doesn't support linux on ARM yet.
My host machine is actually running Windows. But I'm also using WSL to upload the binaries to the Raspberry Pi, since rsync
is a linux tool.
Be careful to use a flutter SDK that's compatible to the engine version you're using.
- use flutter stable and keep it up to date.
flutter channel stable
&&flutter upgrade
- use the latest engine binaries (explained later) and keep them up to date
If you encounter error messages like Invalid kernel binary format version
, Invalid SDK hash
or Invalid engine hash
:
- Make sure your flutter SDK is on
stable
and up to date and your engine binaries are up to date. - If you made sure that's the case and the error still happens, create a new issue for it.
I'm using flutter_gallery
in this example. flutter_gallery is developed against flutter master. So you need to use an older version of flutter_gallery to run it with flutter stable. It seems commit 9b11f12 is the latest one working with flutter 1.20.
git clone https://github.com/flutter/gallery.git flutter_gallery
cd flutter_gallery
git checkout 9b11f127fb46cb08e70b2a7cdfe8eaa8de977d5f
flutter build bundle
Then just upload the asset bundle to your Raspberry Pi. pi@raspberrypi
is of course just an example <username>@<hostname>
combination, your need to substitute your username and hostname there.
$ rsync -a --info=progress2 ./build/flutter_assets pi@raspberrypi:/home/pi/flutter_gallery_assets
This is done entirely on the host machine as well.
- First, find out the path to your flutter SDK. For me it's
C:\flutter
. (I'm on Windows) - Open the commandline,
cd
into your app directory.
git clone https://github.com/flutter/gallery.git flutter_gallery
cd flutter_gallery
git checkout 9b11f127fb46cb08e70b2a7cdfe8eaa8de977d5f
- Build the kernel snapshot.
C:\flutter\bin\cache\dart-sdk\bin\dart.exe ^
C:\flutter\bin\cache\dart-sdk\bin\snapshots\frontend_server.dart.snapshot ^
--sdk-root C:\flutter\bin\cache\artifacts\engine\common\flutter_patched_sdk_product ^
--target=flutter ^
--aot ^
--tfa ^
-Ddart.vm.product=true ^
--packages .packages ^
--output-dill build\kernel_snapshot.dill ^
--verbose ^
--depfile build\kernel_snapshot.d ^
package:gallery/main.dart
- Build the
app.so
. This uses thegen_snapshot_linux_x64
executable I provide in the engine-binaries branch. It needs to be executed under linux. If you're on Windows, you need to use WSL.
$ git clone --branch engine-binaries https://github.com/ardera/flutter-pi ~/engine-binaries
$ cd /path/to/your/app
$ ~/engine-binaries/gen_snapshot_linux_x64 \
--causal_async_stacks \
--deterministic \
--snapshot_kind=app-aot-elf \
--elf=build/app.so \
--strip \
--sim_use_hardfp \
--no-use-integer-division \
build/kernel_snapshot.dill
- Upload the asset bundle and the
app.so
to your Raspberry Pi. Flutter-pi expects theapp.so
to be located inside the asset bundle directory.
$ rsync -a --info=progress2 ./build/flutter_assets pi@raspberrypi:/home/pi/flutter_gallery_assets
$ scp ./build/app.so pi@raspberrypi:/home/pi/flutter_gallery_assets/app.so
- When starting your app, make sure you invoke flutter-pi with the
--release
flag.
USAGE:
flutter-pi [options] <asset bundle path> [flutter engine options]
OPTIONS:
-i, --input <glob pattern> Appends all files matching this glob pattern to the
list of input (touchscreen, mouse, touchpad,
keyboard) devices. Brace and tilde expansion is
enabled.
Every file that matches this pattern, but is not
a valid touchscreen / -pad, mouse or keyboard is
silently ignored.
If no -i options are given, flutter-pi will try to
use all input devices assigned to udev seat0.
If that fails, or udev is not installed, flutter-pi
will fallback to using all devices matching
"/dev/input/event*" as inputs.
In most cases, there's no need to specify this
option.
Note that you need to properly escape each glob
pattern you use as a parameter so it isn't
implicitly expanded by your shell.
--release Run the app in release mode. The AOT snapshot
of the app ("app.so") must be located inside the
asset bundle directory.
This also requires a libflutter_engine.so that was
built with --runtime-mode=release.
-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.
--no-text-input Disable text input from the console.
This means flutter-pi won't configure the console
to raw/non-canonical mode.
-h, --help Show this help and exit.
EXAMPLES:
flutter-pi -i "/dev/input/event{0,1}" -i "/dev/input/event{2,3}" /home/pi/helloworld_flutterassets
flutter-pi -i "/dev/input/mouse*" /home/pi/helloworld_flutterassets
flutter-pi -o portrait_up ./flutter_assets
flutter-pi -r 90 ./flutter_assets
flutter-pi -d "155, 86" ./flutter_assets
flutter-pi /home/pi/helloworld_flutterassets
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 git repository.
For a list of options you can pass to the flutter engine, look here:
https://github.com/flutter/engine/blob/master/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.
flutter-pi needs libflutter_engine.so
and flutter_embedder.h
to compile. It also needs the flutter engine's icudtl.dat
at runtime.
You 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 engine-binaries branch of this project.. I will only provide binaries for some engine versions though (most likely the stable ones).
Additionally, flutter-pi depends on mesa's OpenGL, OpenGL ES, EGL implementation and libdrm & libgbm.
You can easily install those with sudo apt install libgl1-mesa-dev libgles2-mesa-dev libegl-mesa0 libdrm-dev libgbm-dev
.
The flutter engine, by default, uses the Arial font. Since that doesn't come included with Raspbian, you need to install it using:
sudo apt install ttf-mscorefonts-installer fontconfig
sudo fc-cache
sudo apt-get install gpiod libgpiod-dev libsystemd-dev libinput-dev libudev-dev
fetch all the dependencies, clone this repo and run
cd /path/to/the/cloned/flutter-pi/directory
make
The flutter-pi executable will then be located at this path: /path/to/the/cloned/flutter-pi/directory/out/flutter-pi
Performance is actually better than I expected. With most of the apps inside the flutter SDK -> examples -> catalog
directory I get smooth 50-60fps.
Keyboard input is supported. There is one important limitation though. Text input (i.e. writing any kind of text/symbols to flutter input fields) only works when typing on the keyboard, which is attached to the terminal flutter-pi is running on. So, if you ssh into your Raspberry Pi to run flutter-pi, you have to enter text into your ssh terminal.
Raw Keyboard input (i.e. using tab to iterate through focus nodes) works with any keyboard attached to your Raspberry Pi.
converting raw key-codes to text symbols is not that easy (because of all the different keyboard layouts), so for text input flutter-pi basically uses stdin
.
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). If I have enough time in the future, I'll try to build a better touchscreen driver to lower the delay.