CLI Commands#

In this section, there is an overview and description of the Command Line Interface (CLI) commands of the program. Within the CocktailBerry folder, you can execute them with the schema uv run runme/api.py [command] [options]. There is also a --help flag to get information on the program, or its sub-commands. You can use this to get information on the commands when running locally.

Used Auto Setup?

If you installed via the setup script, the program will usually be started via the ~/launcher.sh file. When you want to use other than the default options, change the ~/launcher.sh file accordingly. Just add the flags or their corresponding values to the uv run runme.py command.

v1 or v2?

If you are already running the API (v2) version, you need to use the command api.py instead of runme.py. Everything else (like the options) is the same. Also, if you are on the latest version, you should use uv run ... instead of python ....

The Main Program#

This is usually what you want to run. The main program starts the CocktailBerry interface. You can run it with:

uv run runme.py [OPTIONS]

# Options:
#   -n, --name TEXT    Name to display at start.  [default: CocktailBerry]
#   -q, --quiet        Hide machine name, version and platform data.
#   -d, --debug        Using debug instead of normal Endpoints.
#   -V, --version      Show current version.
#   --help             Show help

If you want to debug your microservice, you can activate the debug -d flag. When debug is active, the data will be sent to the /debug endpoint. This endpoint will only log the payload (request.json), but not send it anywhere. You can also show the program version, this is also shown at program start in the console. In addition, you may want to display another name than CocktailBerry, which is the default. Use the -n option, like -n "YourName", to set a custom name. If you want to omit the machine name, version and platform data, use the -q flag.

There are some additional environment variables you can set to alter the program behavior, without the user being able to change it via settings:

COCKTAILBERRY_NO_WELCOME_MESSAGE: If this variable is set to any value, the welcome message at program start will be omitted (v1).
COCKTAILBERRY_LOG_LEVEL: Set the log level of the program. Possible values are: DEBUG, INFO, WARNING, ERROR, CRITICAL. Default is INFO. If you run into issues, set this to DEBUG to get more information.
MOCK_RFID: If this variable is set to any value, the RFID/NFC reader will be mocked. Do not use for production!
MOCK_PAYMENT_SERVICE: If this variable is set to any value, the payment service will be mocked. Do not use for production!

In case you want to hide the terminal completely, see this section.

CocktailBerry Web#

Run the FastAPI web server (for v2). Can be used as an alternative way to control the machine, for example over an external program or a web ui. The FastAPI server will be started at the given port.

uv run api.py [OPTIONS]

# Options:
#   -p, --port INTEGER  Port for the FastAPI server [default: 8000]
#   --help              Show help

Switch to CocktailBerry Web#

This command will set up the web interface as the default interface. Take care, this will no longer start the main program, but the web interface. The web interface will then be accessible over a web browser, which will be opened in Kiosk mode on the machine. If you want to access the web interface from another device, you can open the browser and navigate to http://<ip> or locally on http://localhost. If SSL is enabled, since this is a self-signed certificate, you will get a warning in the browser, which you can ignore.

uv run runme.py setup-web

# Options:
#   --ssl   -s        Use SSL for the Nginx configuration    
#   --help            Show help

Switch to old Main Program (v1)#

In case you activated the web interface as the default interface, you can switch back to the old main program. This command will switch back to the old main program. This will no longer start the web interface, but the main program. The main program will then be started as usual as a full windowed app.

uv run runme.py switch-back

Clearing Local Database#

There may be CocktailBerry owners, who want to create a completely new database. To clean the local database, run:

uv run runme.py clear-database [OPTIONS]

# Options:
#   --help  Show help

This command will delete all recipes and ingredients from the local database. Before that, a local backup is created, in case you want a rollback. You can then either enter new recipes via the interface, or import your recipes from a file (see below).

Importing Recipes from File#

You can use this functionality to import batch recipe data. You can now provide a .txt or similar text file to quickly insert a lot of new recipes, as well as ingredients. To use this functionality, just use the CLI, similar to running CocktailBerry:

uv run runme.py data-import [OPTIONS] PATH

# Arguments:
#   PATH  [required]

# Options:
#   -c, --conversion FLOAT  Conversion factor to ml  [default: 1.0]
#   -nu, --no-unit          Ingredient data got no unit text
#   --help                  Show help

As usual, you can use the --help flag to get help on this functionality. The data should be in the format:

Recipe Name1
Amount [unit] Ingredient1 Name
Amount [unit] Ingredient2 Name
...
Recipe Name2
Amount [unit] Ingredient1 Name
Amount [unit] Ingredient2 Name

You need to adjust the alcohol level, the bottle volume and hand add flag after the import, if there are newly added ingredients. The script will use a default of 0%, 1000 ml and not only handadd for each new ingredient.

The amount of newlines can be one or more between each line. If there is another type of separator, please use a text editor to change it accordingly. Also, if the recipe uses different types of units, please convert to the one provided by the conversion argument. The script will check for duplicates and wait for user prompt, if there are any issues. If the data has no unit between amount and name, use the --no-unit or -nu flag. If the recipe uses another unit than ml, please provide the corresponding conversion factor, like --conversion 29.5735 or -c 29.5735, when using oz.

Safety First

I still STRONGLY recommend doing a backup of your local database (Cocktail_database.db) before running the import, just in case. You can also use the built-in backup functionality in CocktailBerry for this.

As a Side Note

You should probably not mindlessly import a great amount of cocktails, because this will make the user experience of your CocktailBerry worse. In cases of many ingredients, it's quite exhausting to select the right one. Having too many recipes active at once may also overwhelm your user, because there is too much to choose. The recipes provided by default with CocktailBerry try to aim for a good balance between the amount of cocktails, as well as a moderate common amount of ingredients within the single cocktails. This import function is limited by design, because batch import should only rarely (if ever) happen, and some consideration and checking of the recipes should take place before doing so.

Creating Addon Base File#

Use this command to get started developing your own addon!

uv run runme.py create-addon [OPTIONS] ADDON_NAME

# Arguments:
#   ADDON_NAME  [required]

# Options:
#   --help  Show help

Creates a file containing the base structure to get started with your addon. The file is placed in the addons folder. File name will be the name converted to lower case, spaces are replaced with underscores and stripped of special characters.

Creating Hardware Extension Base Files#

Similar to addon files, you can use the CLI to generate skeleton files for each type of hardware extension. The file is placed in the corresponding subfolder under addons/. File name will be the name converted to lower case, spaces are replaced with underscores and stripped of special characters.

Dispenser Extension#

uv run runme.py create-dispenser DISPENSER_NAME

# Arguments:
#   DISPENSER_NAME  [required]

# Options:
#   --help  Show help

Creates a base file in addons/dispensers/ for a custom pump or valve driver. Once added, the new dispenser type appears in the pump configuration dropdown.

Hardware Context Extension#

uv run runme.py create-hardware HARDWARE_NAME

# Arguments:
#   HARDWARE_NAME  [required]

# Options:
#   --help  Show help

Creates a base file in addons/hardware/ for shared hardware (e.g. a UART board or SPI bus) that multiple dispenser extensions can access at runtime.

Scale Extension#

uv run runme.py create-scale SCALE_NAME

# Arguments:
#   SCALE_NAME  [required]

# Options:
#   --help  Show help

Creates a base file in addons/scales/ for a custom load-cell amplifier or weighing hardware driver. Once added, the new scale type appears in the scale configuration dropdown.

Carriage Extension#

uv run runme.py create-carriage CARRIAGE_NAME

# Arguments:
#   CARRIAGE_NAME  [required]

# Options:
#   --help  Show help

Creates a base file in addons/carriages/ for a custom linear positioning driver that moves the glass between dispenser slots. Once added, the new carriage type appears in the carriage configuration dropdown.

RFID Extension#

uv run runme.py create-rfid RFID_NAME

# Arguments:
#   RFID_NAME  [required]

# Options:
#   --help  Show help

Creates a base file in addons/rfid/ for a custom NFC/RFID reader driver. Once added, the new reader type appears in the RFID configuration dropdown.

LED Extension#

uv run runme.py create-led LED_NAME

# Arguments:
#   LED_NAME  [required]

# Options:
#   --help  Show help

Creates a base file in addons/leds/ for a custom LED or lighting driver. Once added, the new LED type appears in the LED configuration dropdown.

Setup the Microservice#

You can also use CocktailBerry to set up the microservice and change the env variables. It uses the latest image from Docker Hub. With the microservice, also watchtower will be deployed. Watchtower will check periodically if there is a new microservice image and install it in the background.

uv run runme.py setup-microservice [OPTIONS]

# Options:
#   -a, --api-key TEXT        API key for dashboard
#   -e, --hook-endpoint TEXT  Custom hook endpoint
#   -h, --hook-header TEXT    Custom hook headers
#   -o, --old-compose         Use compose v1
#   --help                    Show help

Set up the microservice. If the API key, hook endpoint or hook header is not provided as an option, it prompts the user for the values. Within the prompts, you can reset the value to the default one, or also skip this value if it should not be changed. A compose file will be created in the home directory, if this command was not already run once. If this file already exists, the values will be replaced with the provided ones.

For Docker Compose V2

Please take note that this command is programmed for docker compose v2. It's currently the default compose and the CocktailBerry setup will also install it. If you are still running v1 (docker-compose), consider upgrading. In case you are using v1, add the -o or --old-compose flag.

Setup the Teams Dashboard#

You can also use CocktailBerry to set up the Teams Dashboard. It uses the latest image from Docker Hub. With the dashboard, also watchtower will be deployed. Watchtower will check periodically if there is a new dashboard image and install it in the background.

uv run runme.py setup-teams-service [OPTIONS]

# Options:
#   -l, --language [en|de|pl]  language for the teams service  [default: en]
#   --help                  Show help

Set up the teams microservice. You can use English (en), German (de) or Polish (pl) as the language. Will run the frontend at localhost:8050 (http://127.0.0.1:8050), backend at localhost:8080 (http://127.0.0.1:8080).

Create an Access Point#

You can also use CocktailBerry to set up an access point. The access point will be created on a virtual wlan1 interface. So you can still use the wlan0 interface for your normal network connection. This requires that you can have a virtual interface on your chip, for example the Raspberry Pi 3B+.

uv run runme.py setup-ap [OPTIONS]

# Options:
#   --ssid      SSID Name of the AP [default: CocktailBerry]
#   --password  Password of the AP [default: cocktailconnect]
#   --help      Show help

Remove the Access Point#

If you want to remove the access point, you can use this.

uv run runme.py remove-ap [OPTIONS]

# Options:
#   --ssid      SSID Name of the AP [default: CocktailBerry]
#   --help      Show help

Virtual Keyboard Commands#

For managing the virtual keyboard on the Raspberry Pi when using the web interface (v2), see the web documentation for the add-virtual-keyboard and remove-virtual-keyboard commands.