CocktailPi installation

Preamble

To use CocktailPi we have to install it first. The following instructions have been tested on a RaspberryPi 4, a RaspberryPi 3 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 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:

Run with user: pi

sudo -i

The application requires some dependencies. We install them first:

Run with user: root

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:

Run with user: root

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

Download the application and configuration into the same folder:

Run with user: root

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:

Run with user: root

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:

Run with user: root

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:

Run with user: root

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 and/or sponsoring 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 and/or sponsoring 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:

Run with user: pi

sudo -i

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

Run with user: root

nano /boot/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:

Run with user: pi

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:

Run with user: pi

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!

Sudo to the root user:

Run with user: pi

sudo -i

Install the needed dependencies:

Run with user: root

apt install --no-install-recommends -y xserver-xorg x11-xserver-utils xinit openbox chromium-browser rpi-chromium-mods libgles2-mesa libdbus-glib-1-2 
# if you use Bullseye
apt install --no-install-recommends -y libevent-2.1-7 libvpx6 libgtk-3-common libdbus-glib-1-2

Configure the auto login. In case you get asked for the user for which the settings should be applied select the pi-user:

Run with user: root

raspi-config

Go to System Options –> Boot / Auto Login –> Console Autologin

Next, we have to setup openbox:

Run with user: root

nano /etc/xdg/openbox/autostart

Fill in the following content:

Run with user: root | File: /etc/xdg/openbox/autostart

# Disable any form of screen saver / screen blanking / power management
#xset s off
#xset s noblank
#xset -dpms

xset +dpms
xset s blank
xset 0 0 120

# Allow quitting the X server with CTRL-ATL-Backspace
setxkbmap -option terminate:ctrl_alt_bksp

# Start Chromium in kiosk mode
sed -i 's/"exited_cleanly":false/"exited_cleanly":true/' ~/.config/chromium/'Local State'
sed -i 's/"exited_cleanly":false/"exited_cleanly":true/; s/"exit_type":"[^"]\+"/"exit_type":"Normal"/' ~/.config/chromium/Default/Preferences

chromium-browser /home/pi/wait-for-app-html/index.html --enable-extensions --disable-component-update --check-for-update-interval=31536000 --enable-features=OverlayScrollbar --disable-features=OverscrollHistoryNavigation --force-device-scale-factor=1.0

Run with user: root

su - pi

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

Run with user: pi

nano /home/pi/.bashrc

Fill in the following content. In case the file already exists you can just add the content to the end of the file:

Run with user: pi | File: /home/pi/.bashrc

[[ -z $DISPLAY && $XDG_VTNR -eq 1 ]] && startx -- -nocursor

Reboot the raspberry now:

Run with user: pi

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 sudo to the root user:

Run with user: pi

sudo -i

Open the openbox config again…:

Run with user: root

nano /etc/xdg/openbox/autostart

… and replace the old content with this new content:

Run with user: root | File: /etc/xdg/openbox/autostart

# Disable any form of screen saver / screen blanking / power management
#xset s off
#xset s noblank
#xset -dpms

xset +dpms
xset s blank
xset 0 0 120

# Allow quitting the X server with CTRL-ATL-Backspace
setxkbmap -option terminate:ctrl_alt_bksp

# Start Chromium in kiosk mode
sed -i 's/"exited_cleanly":false/"exited_cleanly":true/' ~/.config/chromium/'Local State'
sed -i 's/"exited_cleanly":false/"exited_cleanly":true/; s/"exit_type":"[^"]\+"/"exit_type":"Normal"/' ~/.config/chromium/Default/Preferences

chromium-browser /home/pi/wait-for-app-html/index.html --kiosk --enable-extensions --disable-component-update --check-for-update-interval=31536000 --enable-features=OverlayScrollbar --disable-features=OverscrollHistoryNavigation --force-device-scale-factor=1.0

In case the UI is too small or too large, you can edit the --force-device-scale-factor parameter (that is already present in the last 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:

Run with user: root

reboot

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