CocktailPi installation

Preamble

To use CocktailPi we have to install it first. The following instructions have been tested on a RaspberryPi 3, a RaspberryPi 4 and a RaspberryPi 5 with Raspberry Pi OS Lite 64 bit! If you want to use the software in combination with a local touchscreen, it is recommended to use a Raspberry Pi 4 or 5 for performance reasons.

Table of contents:

• Install the OS
• Install CocktailPi
• Connect with the community
• Configuring GPIO-pin boot states (optional)
• Using a touchscreen (optional)

Install the OS

The first step is to install the operating system. For this you need a SD-card, that you can put into your Raspberry Pi. Before the raspberry Pi is able to start, we need to flash the operating system on the SD-card first. To flash the OS we can use the official Raspberry Pi Imager.

When selecting the operating system click on:
Choose OS -> Raspberry Pi OS (other) -> Raspberry Pi OS Lite (64-bit)

Next, click on the “gears” symbol located in the bottom right corner. This will bring up a menu. Within this menu, you should select a hostname, enable SSH, and create a user along with a password. In my case, I named this user “pi,” but you can choose any name you prefer. Just make sure to remember the user you create here, as you’ll need to use it when referencing the “pi” user in the rest of this tutorial.

Once you have entered the specified options, click on the “save” button. This will close the menu. Now, select your SD card and initiate the flashing process by clicking on “write/flash.”

Afterwards put the flashed SD-Card into your Pi, connect it to your network and start it.

Install CocktailPi

Connect to your PI

After a while the Pi should become reachable through the network. To connect to your PI you need an SSH-Client. I personally use PuTTy for that, but you can use any SSH-client that you like. Open your SSH-client and type in your raspberrys hostname or IP address. Click on “open” to open the connection. Enter the credentials that you’ve selected during the flashing progress (pi-user).

Install the application

After logging in as the pi user, you need to get root-privileges. You can become root using:

sudo -i

The application requires some dependencies. We install them first:

sudo apt update && sudo apt -yq upgrade
sudo apt install --no-install-recommends -y openjdk-17-jdk i2c-tools python3 python3-pip pigpio wget libjna-java alsa-utils python3-pip nano curl

We need to choose an installation folder. I’ve chosen /root/cocktailpi:

mkdir -p /root/cocktailpi
cd /root/cocktailpi

Download the application and configuration into the same folder:

wget https://github.com/alex9849/CocktailPi/releases/latest/download/server.jar -O cocktailpi.jar

Create a symlink from the cocktailpi.jar to /etc/init.d:

sudo ln -s /root/cocktailpi/cocktailpi.jar /etc/init.d/cocktailpi
sudo chmod +x /etc/init.d/cocktailpi

Reload systemctl and add the application to the autostart:

sudo systemctl daemon-reload
sudo update-rc.d cocktailpi defaults

CocktailPi should now start on reboot. All logs will be written to /var/log/cocktailpi.log. You can also manually start CocktailPi without rebooting:

service cocktailpi start

The webinterface should be reachable on port 80. You can reach the application through the network. The default login credentials are:
User: admin
Password: 123456

If you don’t want to use a touchscreen, you are done with the installation. If you like the project, please consider staring it. 🙂

Connect with the community

If you have questions, want to share your setup or just want to talk about cocktail machines, feel free to join our discord server:

Next, you need to add your pumps. Go to ‘Administration’ -> ‘Pumps’ and click ‘Add pump’. Fill in the form shown. Notice that the field ‘BCM-Pin’ is not the GPIO-Pin. BCM refers to the ‘Broadcom SOC channel’ number. The BCM number is the number, that is used inside the chip of the Raspberry Pi and determines the GPIO-Pin that should be used. These numbers may change between different board versions. You can find the mapping in the documentation of your Raspberry Pi board. Read more about the BCM mapping here: https://pi4j.com/getting-started/understanding-the-pins/#overview

If you don’t want to use a touchscreen, you are done. If you like the project, please consider staring it. 🙂

Configuring GPIO-pin boot states (optional)

To mitigate potential issues arising from GPIO pins being in different modes at boot time, such as unintended pump activation or unwanted hardware behavior, a feature has been introduced to define the boot state for each GPIO pin. This allows you to set the initial state of the GPIO pins during the boot process. This way, you can ensure that the hardware behaves as expected from the moment the system starts up, regardless of the application’s initialization time, which may take several minutes.

To set the boot state for GPIO pins, you’ll need to log in to SSH and obtain root privileges:

sudo -i

Then open the config.txt at /boot/firmware/config.txt:

nano /boot/firmware/config.txt

Now edit that file as described in the official Raspberry PI documentation: <Click me>

Define the default state for each pin you are currently using or intend to use. Save the file, and upon the next boot, your pins should immediately assume the desired state.

Using a touchscreen (optional)

This step is optional. You can control CocktailPi through your network. But if you have a touchscreen and want to use it, you might want to follow these steps:
Please login as pi user and download these files into the folder /home/pi/wait-for-app-html:

mkdir -p /home/pi
cd /home/pi
wget https://github.com/alex9849/CocktailPi/releases/latest/download/wait-for-app.tar

unpack them and delete the tar archive:

tar -xf wait-for-app.tar
rm wait-for-app.tar

Note that the wait-for-app folder contains a html file that is shown as long as the real application is in its startup process. In case you’ve changed the application port, you also have to edit the url-constant in your index.html-file in the wait-for-app-html-folder to match the correct server address and port!

Next you have to configure autologin for the current pi-user:

sudo raspi-config nonint do_boot_behaviour B2

We are going to use wayfire and chromium to display CocktailPis UI. We configure wayfire and chromium here. (We install both later.) First, we create the configuration file and open it.

mkdir -p /home/pi/.config
nano /home/pi/.config/wayfire.ini

Paste this into it and exit/save the file using CTRL+X and confirm saving by pressing Y:

[core]
plugins = \
        autostart

[autostart]
chromium = chromium-browser /home/pi/wait-for-app-html/index.html --noerrdialogs --enable-extensions --disable-component-update --check-for-update-interval=31536000 --disable-infobars --no-first-run --ozone-platform=wayland --enable-features=OverlayScrollbar --disable-features=OverscrollHistoryNavigation --force-device-scale-factor=1.0
screensaver = false
dpms = false

For the next steps we have to become root. Sudo to the root user:

sudo -i

Install the needed dependencies:

apt install --no-install-recommends -y chromium-browser rpi-chromium-mods
apt install --no-install-recommends -y wayfire seatd xdg-user-dirs

Next enable the wayland display protocol:

raspi-config nonint do_wayland W2

Login as the pi user…:

su - pi

… and create a .bashrc file for the pi user:

nano /home/pi/.bashrc

Add the content to the end of the file. Afterwards save and exit the editor:

if [ "$(tty)" = "/dev/tty1" ]; then
    wayfire -c ~/.config/wayfire.ini
fi

Reboot the raspberry now:

sudo reboot

After some time chromium should open and you should see the login page of the webinterface. You may notice that chromium didn’t launch in kiosk mode. That’s because we are not done yet. Since we want to use a touchscreen we need to add a virtual keyboard. I decided to use a chrome extension.
I tested some extensions and couldn’t find one that was compatible with the webinterface and included an autoshow/hide feature. So I wrote one. You can find it here https://chrome.google.com/webstore/detail/chrome-simple-keyboard/cjabmkimbcmhhepelfhjhbhonnapiipj. (Or this URL, if you don’t want to copy the previous one: https://bit.ly/3KrbPwz (Warning: case sensitive!)) Open the URL within chromium and click Add to Chrome and on Add Extension. Afterwards you can configure the extension in within it’s options. You can only select the keyboard language. I added english and german. Click Save afterwards.

SSH into your pi again and edit the wayland config file as pi-user…

nano /home/pi/.config/wayfire.ini

… and replace the old content with this new content:

[core]
plugins = \
        autostart

[autostart]
chromium = chromium-browser /home/pi/wait-for-app-html/index.html --kiosk --noerrdialogs --enable-extensions --disable-component-update --check-for-update-interval=31536000 --disable-infobars --no-first-run --ozone-platform=wayland --enable-features=OverlayScrollbar --disable-features=OverscrollHistoryNavigation --start-maximized --force-device-scale-factor=1.0
screensaver = false
dpms = false

In case the UI is too small or too large, you can edit the --force-device-scale-factor parameter (that is already present as last parameter in the ‘chromium = …’-line at your copied configuration) to increase or decrease the size of your UI. Example:

• --force-device-scale-factor=0.5 ← Scale down (Reduce size) by 50%
• --force-device-scale-factor=1.0 ← Don’t scale at all
• --force-device-scale-factor=1.5 ← Increase size by 50%
• --force-device-scale-factor=2.0 ← Increase size by 100% (Double the size)

Reboot the pi afterwards:

sudo reboot

You are done. Have fun! If you like the project, please consider staring it. 🙂