diff --git a/docs/install/linux/raspberry.md b/docs/install/linux/raspberry.md index 69a77fbba7..0b81f67cf4 100644 --- a/docs/install/linux/raspberry.md +++ b/docs/install/linux/raspberry.md @@ -1,262 +1,158 @@ --- -title: Installing MPF on a Raspberry Pi 3 +title: Installing MPF on a Raspberry Pi --- -# Installing MPF on a Raspberry Pi 3 +# Installing MPF on a Raspberry Pi +These instructions are based on those created by [Gilles Bouthenot](https://github.com/orgs/missionpinball/discussions/115). They use a Python virtual environment without system-wide Python packages, and you can have multiple versions Python if you need. +A few other notes: +* These instructions are specifically made for a Raspberry Pi 5 running Raspberry Pi OS "Bookworm," which appears to have the power to run both MPF and MPF-MC. Older models strugged with video and sounds, but may work in certain scenarios. These instructions should work for them as well. +* It's assumed that you've already installed Raspberry Pi OS, expanded your filesystem, configured wifi, and so on. If you need help getting to that point, check out the [Raspberry Pi documentation](https://www.raspberrypi.com/documentation/computers/getting-started.html). +* The Pi 5 does not have a dedicated Audio Out jack like prior models. You will need a USB audio interface. [This one has been tested](https://www.amazon.com/Adapter-External-Converter-Compatible-Desktops/dp/B099FLWJD3) and is known to work. +* We're assuming you're not developing your game from the Pi, so these instructions omit mpf-monitor and the MPF Language Server. It may or may not be possible to run those. If you need one or both and get them working, feel free to edit this doc with instructions. +* The versions of MPF and MPF-MC available via pip are not able to run on Raspberry Pi. We will need to install in "editable" mode for the time being, but this page will be updated if and when installation via pip is possible. -MPF can be installed on a Raspberry Pi 4, and possibly a 3. +## Prerequisites and dependencies -MPF itself runs fine, but you might run into limitations with the -Media Controller since videos and sounds can potentially take more -resources than the Pi has. (You can address this by tuning the codecs -and configuration of your Pi, or, you can just buy a more powerful -NUC or single-board computer for $100-200 and then never have to worry about performance again.) - -* Get the latest Raspberry Pi Imager from here: - -* Install Raspbian Lite onto your SD card. -* Boot your PI and connect keyboard + monitor -* Login with user:pi password:raspberry -* now type this: - -``` shell -sudo raspi-config -``` - -and choose 7. Advanced Options -> A1. Expand Filesystem to use the -whole SD-Card Space, we will need it. You can change your username and -localization settings too. - -After that we will give the GPU a bit more of RAM: - -Go to 7. Advanced Options -> A3 Memory split and change the value to -256. - -Now reboot, login and type: +To get started, log in to the terminal (locally or via SSH) and update your device and install some dependencies: ``` shell sudo apt update sudo apt upgrade -sudo apt install git - -git clone https://github.com/missionpinball/mpf-debian-installer.git -cd mpf-debian-install -sudo ./install -``` - -To checkout and run the -[MPF Linux Debian installer](index.md). It will install MPF, MPF-MC and all dependencies for you. - -This will take some time as it may compile some drivers mpf-mc needs -like the audio driver. Sometimes it looks like it hangs, but it does -not. It will take up to half an hour, at least on a Raspberry 1 (which -you should not use). Compiling is really slow on the Raspi. - -Now copy your machine folder from your develop station or create a new -one under your home directory (/home/pi/your_machine) -If you need a file-manager start mc (No, not the mpf mediacontroller, -its the midnight commander ;-)) +# Dependencies: +sudo apt-get install libssl-dev libncurses-dev libffi-dev libreadline-dev libbz2-dev libsqlite3-dev liblzma-dev tk-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libsdl2-mixer-dev libavfilter-dev libsdl2-dev libsdl2-image-dev libavcodec-dev libavformat-dev libswscale-dev libavdevice-dev -If you need to copy your folders from an usb-stick you have to manually -mount it (we dont have X, so everything has to be done by hand). - -``` shell -sudo mount /dev/sda1 /mnt +# These are for mpf-monitor and are not necessarily needed +sudo apt-get install libjpeg-dev libxcb-cursor0 libxkbcommon-x11-0 libxcb-icccm4 libxcb-keysyms1 libxcb-shape0 xsel ``` -This works in 90% otherwise your stick is not sda1, just look inside the -/dev folder to find out which device you have to mount or type +## Installing pyenv + +Now we need to install pyenv, which will both install a specific version of Python and create a virtual environment. To do this, follow these steps: ``` shell -lsblk -``` +# download the pyenv installer +wget https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer -to list your block devices. +# execute the installer +bash pyenv-installer -Now you find the contents of your stick in /mnt. +# clean up +rm pyenv-installer -To tell mpf-mc and the underlying kivy to use the framebuffer via SDL2 -you have to put this in your machine/config/config.yaml: +# Update your bash profile to customise the shell at login +cat <<'EOF'>>.bashrc +export PYENV_ROOT="$HOME/.pyenv" +command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH" +eval "$(pyenv init -)" +EOF +exec $SHELL -``` mpf-mc-config -window: - width: 1280 - height: 800 -kivy_config: - graphics: - fbo: force-hardware -##! test -#! advance_time_and_run .1 +# Check to ensure pyenv is available (A list of pyenv commands is the expected output) +pyenv ``` -## More or less important last steps: - -## Serial communication: - -Linux always had and has the possibility to log in via a serial -connection. If you run a hardware platform which uses the serial pin on -the Raspberry you should disable the Linux login shell on that port. The -device is called /dev/ttyAMA0 and you need to stop it from starting: +## Installing Python -Type: +Next step is to install Python itself and set up the virtual environment. We'll use Python 3.9.18 since it's compatible with both MPF 0.56 and 0.57, and is the most recent version of Python 3.9. ``` shell -sudo systemctl disable serial-getty@ttyAMA0.service -``` - -Now you have to disable the console itself: - -``` shell -sudo mc -``` - -to start Midnight Commander as root (normally you should not do this, -but this time you have to.) +# python3.9 compilation. Note this can take a while since Python is being downloaded and compiled from source +pyenv install 3.9.18 -Now go to /boot and press F4 over cmdline.txt. +# Create virtual environment +pyenv virtualenv 3.9.18 mpf -Remove these entries: +# Activate virtual environment +pyenv activate 3.9.18/envs/mpf - console=ttyAMA0,115200 kgdboc=ttyAMA0, 115200 +# Assuming that works, let's add that command to .bashrc so that the virtual environment activates at each login +cat <<'EOF'>>.bashrc +pyenv activate 3.9.18/envs/mpf +EOF +exec $SHELL +``` -and save the file. +## Installing MPF -You have the possibility to connect RS 232 devices directly to the raspi -but take care, the voltage levels are 3.3V on the raspi gpio. Further -instructions here: +Now it's time to install MPF. As mentioned, installing automatically via pip isn't possible right now, but that's not a show stopper. With a few extra steps, we can get things up and running in "editable" mode (which still uses pip, but in a different way). -## Sound output: +Note: Ensure you're doiong this with the Python pyenv environment activated! You'll see the terminal prompt change to something like this `(3.9.18/envs/mpf) pi@raspberrypi:~ $ ` -Navigate to /boot/config.txt if you want to use audio out of the -Raspberry built in ""soundcard"": edit this file as root and insert -this line: +``` shell +# Upgrade pip +pip install --upgrade pip - dtparam=audio=on +# clone mpf repository (note 0.56.x branch has been specified) +git clone -b 0.56.x https://github.com/missionpinball/mpf-mc.git ~/mpf-git/mpf -Inside this file you can change some settings that initialize on boot, -its like a bios which the raspberry does not have. +# install MPF +cd ~/mpf-git/mpf +pip install –e . -## Video Playback: -If you need video capability in your mpf-mc you need to install one -player that kivy will use to play your videos: +# clone mpf-mc repository (note 0.56.x branch has been specified) +git clone -b 0.56.x https://github.com/missionpinball/mpf.git ~/mpf-git/mpf-mc -``` shell -sudo apt-get install omxplayer +# install MPF-MC +cd ~/mpf-git/mpf-mc +pip install –e . ``` -You can try videoplayback with +That's it! Now it's time to test. -``` shell -omxplayer your_video.mp4 -``` - -To test the video playback capability under kivy into the framebuffer -just run this command: +## Tests +You'll need to get mpf-examples first, then make a few tweaks to the demo_man config before you can test. ``` shell -python3 -m kivy.uix.videoplayer /usr/local/lib/python3.4/dist-packages/mpfmc/tests/machine_files/video/videos/mpf_video_small_test.mp4 -``` +# clone mpf-examples repo +git clone -b 0.56.x https://github.com/missionpinball/mpf-examples.git ~/mpf-git/mpf-examples -## Troubleshooting: - -More documentation about kivypie can be found here: - +# switch to the demo_man configs folder +cd ~/mpf-git/mpf-examples/demo-man/config +``` -## No sound: +From here, you'll need to edit two files. How you do this is up to you, but if you're relatively new the easiest way is probably to use `nano` from the command line. Simply run `nano filename.yaml` to open the file. -If you have trouble getting sound out of your speakers or monitor have a -look here: +First, open hardware.yaml and page down towards the bottom. In the `sound_system:` section towards the bottom, change the `enabled: false` line to `enabled: true` - +If using nano, push Control-X to exit, Y to save. Then open the config.yaml file to turn on BCP. At the top of the file, you'll see the `bcp:` section. Simply comment out the `connections: None` line by placing a # in front of it, like this: `# connections: None` -If sound plays via omxplayer but not in MPF, set use_sdl_mixer_loader: -False in your MPF configuration file. +To run the test, ensure your virtual environment is activated (it should be since you added it to your bash profile) and that you have a display connected. -## Do a reboot: +Note: If you're connected via SSH, you'll need to specify which display should be used. The default is 0, but your configuration might be different. To do this, simply run the following command (remember - you only need to do this if you're not using the local console, either directly or via VNC): ``` shell -sudo reboot +# set default display for windowed apps +export DISPLAY=:0 ``` - -## Remote log in: - -To log in from your development machine into your raspberry you can do -it easily via ssh. For windows I recommend putty: - - -## See whats going on on your pinball: +To test MPF with the demo-man game, follow these steps: ``` shell -sudo dispman_vncserver -``` +# Switch to demo-man directory +cd ~/mpf-git/mpf-examples/demo-man -This starts a vncserver on your raspi and you can log in remotely from a -RealVNCViewer - -Kivypie IP address, port 5900. It is not 100% reliable but fairly -usable. Thanks to Peter Hanzel. - -## Start mpf and mpf-mc - -To test your installation type - -``` shell -mpf +# start MPF +mpf both -X ``` -in your machine_folder. - -Press (STRG+ALT F2) to change to the second terminal tty2. +You should see MPF run, and the demo-man DMD animations running. If you do, you're in good shape! -Login and start mpf-mc inside your machine folder with +To test the media controller to ensure it works, you can switch to the mc_demo folder and run MPF. ``` shell -mpf mc -``` - -Enjoy! - -## What if it did not work? +# switch to mc_demo directory +cd ../mc_demo -In the following we list some common problems and solutions. If you got -another problem please ask in our [forum](../../community/index.md). +# start MPF +mpf both -X +``` -### YAML error on first start +You can step left and right through the slides to see animations and videos. You can also test audio here by listening for sounds during slide transitions. -You will see this error if there is already a different version of -ruamel.yaml installed on your system: +Now that MPF is working on the Raspberry Pi, there are steps to take to tweak the device itself and harden it for use in the machine. Those are A) not fully known and B) outside the scope of this page, but as information becomes available, it can be added. -``` doscon -pkg_resources.VersionConflict: (ruamel.yaml 0.15.37 (c:\users\robert\appdata\local\programs\python\python36\lib\site-packages), Requirement.parse('ruamel.yaml<0.11,>=0.10') -``` -This could have happened if you are upgrading to a newer version of MPF -or you have incompatible versions of MPF, MPF-MC and/or the MPF-Monitor -installed. The required ruamel.yaml version is different on newer MPF -versions. We used to install ruamel 0.11 and switched to 0.15 in MPF -0.53+. MPF cannot start with two yaml libraries. To fix this check your -versions `pip3 list` and check `mpf`, `mpf-mc` and `mpf-monitor`. Remove -the wrong version and install the right one. All versions need to match -(for instance all or all dev). - -The following command will remove all three and install the latest -release: - -``` doscon -pip3 uninstall mpf mpf-mc mpf-monitor -pip3 install mpf mpf-mc mpf-monitor -``` -This error can also occur if you already have ruamel.yaml installed in -your python system packages for a non-MPF package. Often times, you will -have a newer version of ruamel.yaml than MPF requires. Unfortunately, -MPF cannot use a newer version of this package because that caused -issues in the past because newer versions dropped support (wheels for -windows) for older python versions. In the case that you need a -different version than the one MPF requires, it is advised to create a -python virtual environment and install the required packages there, and -use that virtual environment for running MPF.