diff --git a/docs/.devnotes.md b/docs/.devnotes.md index 19bc34af..3d52f390 100644 --- a/docs/.devnotes.md +++ b/docs/.devnotes.md @@ -26,7 +26,7 @@ This is an additional section for information, generally not relevant for the us # Python Version -Currently used version (just use uv and see .python-version file): +Currently used version (just use uv and see the .python-version file): ``` Python Version 3.13.x @@ -84,15 +84,15 @@ In the following diagram, the DB Architecture is shown. The used DB is a SQLite **Notes:** -- Even if not all fields are mandatory (NOT NULL) they should be initiated with a value of 0, if no other value is desired. This may be changed in the future with a DEFAULT 0 setting. The CocktailBerry app does always assign a value to all fields, so this is only an issue when using a own script for additional data filling +- Even if not all fields are mandatory (NOT NULL) they should be initialized with a value of 0, if no other value is desired. This may be changed in the future with a DEFAULT 0 setting. The CocktailBerry app always assigns a value to all fields, so this is only an issue when using your own script for additional data filling - AUTOINCREMENT ID / PK are generated by SQLite and do not need to be provided when inserting data -- SQLite does not have the boolean type, so an integer representation of `0: false 1: true` was used. This is case in following columns: +- SQLite does not have the boolean type, so an integer representation of `0: false 1: true` was used. This is the case in the following columns: - Hand - Enabled - Virgin -- Counter / Consumption should be set to 0 when initiating +- Counter / Consumption should be set to 0 when initializing - The Recipes.Comment field is historical and will probably be removed in the future, since the new DataClass representation takes this job now. Some testing needs to be done to ensure a working app without this column. This can be left as an empty string or null. -- SQLite does only provides a small amount of [alter operations](https://www.sqlite.org/lang_altertable.html), which is also why some columns still got no default value (schema creation was without this constraint). +- SQLite only provides a small amount of [alter operations](https://www.sqlite.org/lang_altertable.html), which is also why some columns still have no default value (schema creation was without this constraint). # Addon Schema @@ -102,15 +102,15 @@ In the following diagram, the schema and interaction with the addons are shown. # Translating the UI -One contribution, that does not require any programming skill is the possibility to add a translation to your language. -The language file for the backend and qt app is found in `src/language.yaml` for CocktailBerry, `web_client/src/locales/LANGUAGENAME` and in `dashboard/frontend/language.yaml` for the Dashboard. In the best szenerio, both files get the according translation. You can use any of the existing language to translate into your own language, in most cases english will probably be the best to use. Please add for every existing option a translation, following the current YAML schema. Using an [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_code) **two letter code** language codes is desired. +One contribution that does not require any programming skill is the possibility to add a translation to your language. +The language file for the backend and qt app is found in `src/language.yaml` for CocktailBerry, `web_client/src/locales/LANGUAGENAME` and in `dashboard/frontend/language.yaml` for the Dashboard. In the best scenario, both files get the according translation. You can use any of the existing languages to translate into your own language, in most cases English will probably be the best to use. Please add a translation for every existing option, following the current YAML schema. Using an [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_code) **two-letter code** language codes is desired. # Other Hardware than RPi -There is also the generic board option, which should work with a broad option of other boards. +There is also the generic board option, which should work with a broad range of other boards. They only need to be controllable over the GPIO interface, especially with [python-periphery](https://github.com/vsergeev/python-periphery). -Depending on the OS of the system, some set up steps may differ from the RPi ones. -For the Qt GUI its important to run the LXDE or similar Desktop variant. +Depending on the OS of the system, some setup steps may differ from the RPi ones. +For the Qt GUI it's important to run the LXDE or similar Desktop variant. Gnome or others may break some features like always stays on top or other window settings. Example for RockPi: @@ -210,11 +210,11 @@ To manage the style, a qss (qt-css) file is used. [qtsass](https://github.com/sp qtsass /src/ui/styles/ -o /src/ui/styles/ ``` -If you want to implement a new style, copy the default.scss file, rename the copy to your style name and plug your colors into the variables. After that, just compile the file. You got a new style setting. To be supported, the style name needs to be added to the `src.__init__` file into the `SUPPORTED_STYLES` list. +If you want to implement a new style, copy the default.scss file, rename the copy to your style name and plug your colors into the variables. After that, just compile the file. You now have a new style setting. To be supported, the style name needs to be added to the `src.__init__` file into the `SUPPORTED_STYLES` list. ### Button clicked.connect behavior -One issue, which is not clear on the first view, is that there are two signatures for this function. See [this issue on StackOverflow](https://stackoverflow.com/questions/53110309/qpushbutton-clicked-fires-twice-when-autowired-using-ui-form/53110495#53110495) for more details. When using the error logging wrapper and just passing the wrapped function into the connect function, PyQt will also emit the `False` argument into the wrapper. This will result in a crash of the program in case the wrapped function got no arguments. In this case it is better to use a lambda to explicitly tell PyQt the function got no arguments. +One issue, which is not clear on the first view, is that there are two signatures for this function. See [this issue on StackOverflow](https://stackoverflow.com/questions/53110309/qpushbutton-clicked-fires-twice-when-autowired-using-ui-form/53110495#53110495) for more details. When using the error logging wrapper and just passing the wrapped function into the connect function, PyQt will also emit the `False` argument into the wrapper. This will result in a crash of the program in case the wrapped function has no arguments. In this case it is better to use a lambda to explicitly tell PyQt the function got no arguments. ```Python # Wrapped function without arguments @@ -225,16 +225,16 @@ def some_function(): # Good your_button.clicked.connect(lambda: some_function()) -# Will crash because the wrapper got *args=(False,) +# Will crash because the wrapper receives *args=(False,) # and will call some_function(False) your_button.clicked.connect(some_function) ``` ### Those God Damn Buttons -Even if buttons support a icon element, there seem no way to change the icon color over a css property. +Even if buttons support an icon element, there seems to be no way to change the icon color over a css property. You either change the icon file (lol) or adjust the color over the property. -Qtawesome got a color argument. +Qtawesome has a color argument. It could be used to change the color to the given theme color, but therefore some refactoring is needed. Example: diff --git a/docs/about.md b/docs/about.md index 3b880baf..4ff1b6fa 100644 --- a/docs/about.md +++ b/docs/about.md @@ -1,18 +1,18 @@ # Overview -CocktailBerry is used to control a cocktail your machine and easily prepare cocktails over a nice-looking user interface. -It also offers the option to create and manage your recipes and ingredients over the interface and calculates the possible cocktails to prepare over given ingredients. +CocktailBerry is used to control your cocktail machine and easily prepare cocktails via a nice-looking user interface. +It also offers the option to create and manage your recipes and ingredients via the interface and calculates the possible cocktails to prepare from given ingredients. Track and display cocktail data for different teams to even further increase the fun. -Have also a look into the [User Guide](assets/CocktailBerryUserGuide.pdf). +Also have a look at the [User Guide](assets/CocktailBerryUserGuide.pdf). Let's get started! ## tl;dr -You can easily install the software by just flashing the Raspberry Pi OS on a SD card, insert it, start the device and install the software with just one command. +You can easily install the software by just flashing the Raspberry Pi OS on an SD card, insert it, start the device and install the software with just one command. Then, get some coffee and let the script do the work. -When you come back, you can set up the machine over the graphical user interface and start mixing cocktails. -This way, you don't have to know much about software an can go full focus on the hardware. -If you want to do your own software part, you can still add this over [addons](addons.md). +When you come back, you can set up the machine via the graphical user interface and start mixing cocktails. +This way, you don't have to know much about software and can focus fully on the hardware. +If you want to do your own software part, you can still add this via [addons](addons.md).
![Cocktail in the making](pictures/Cocktailmaker_action.gif){ width="600" } @@ -25,7 +25,7 @@ CocktailBerry comes with two versions: v1 and v2. Most impressions here shown are from v1, but v2 is quite similar. The main difference is that v2 comes with a more modern design and as a web app, offering more flexibility and accessibility. You can have a look at the [v2 demo](https://demo.cocktailberry.org/cocktails) to interactively experience it. -The interface was programmed for the users to easily interact with CocktailBerry and manage everything over the GUI. +The interface was programmed for the users to easily interact with CocktailBerry and manage everything via the GUI. There are different views for the tasks.
@@ -41,7 +41,7 @@ There are different views for the tasks. This is the main window of the application and the window your guest will interact with. They can choose a cocktail of their choice, a crossed glass at the start indicates that there is also a virgin option of this cocktail. The cocktail data is displayed after selection. -The user can choose from your defined list of volume, as well as the alcohol level of the cocktail. +The user can choose from your defined list of volumes, as well as the alcohol level of the cocktail.
![Ingredient](pictures/Ingredients_ui.png) @@ -59,8 +59,8 @@ This is extremely handy, if you want to prompt the user to add a slice of someth
Here you can manage all your recipes. -Define the name and ingredients with corresponding volume. -You can disable recipes, you currently don't want to serve, or activates the virgin option for a cocktail. +Define the name and ingredients with corresponding volumes. +You can disable recipes, you currently don't want to serve, or activate the virgin option for a cocktail. The number after the ingredient defines the order of the ingredients in the cocktail, same numbers are added in parallel.
@@ -76,8 +76,8 @@ Within this, you can export data, change settings, make and restore backups or r ## Example Machines -The base machine consists out of a Raspberry Pi + touchscreen, 5V relays as well as membrane pumps and some cabling. +The base machine consists of a Raspberry Pi + touchscreen, 5V relays as well as membrane pumps and some cabling. Using wood, metal or 3D printed parts for the housing, you can create a very nice-looking cocktail machine. There are a lot of custom-builds out there, check out the [official dashboard](https://stats-cocktailberry.streamlit.app/#existing-machines) for more impressions. See [Hardware](hardware.md) for a detailed example list of components. -You can also have a look at the official website for cocktailberry for more examples and information: [cocktailberry.org](https://cocktailberry.org). +You can also have a look at the official website for CocktailBerry for more examples and information: [cocktailberry.org](https://cocktailberry.org). diff --git a/docs/addons.md b/docs/addons.md index 35879e22..56c53e94 100644 --- a/docs/addons.md +++ b/docs/addons.md @@ -8,54 +8,54 @@ Currently, addons can be triggered at: - Before a cocktail is prepared, this may also prevent the cocktail - After a cocktail is prepared - Run a continuous loop, which can trigger a cocktail preparation -- Build up it's own GUI or buttons to execute other program logic +- Build up its own GUI or buttons to execute other program logic You can use the addons to implement some exotic feature, just for you, or make it accessible for the public. Addons were introduced to give the user more control over specific things. -Like you could implement a scale into your machine below the position for the glass and only prepare the cocktail if a glass is recognized. +For example, you could implement a scale into your machine below the position for the glass and only prepare the cocktail if a glass is recognized. !!! danger "Everyone can make Addons" In general, you should check and understand the addon or trust the author of it. Addons are not made directly by the CocktailBerry development team. - The installation of additional packages required for the addon must also be handled be the user or the provided addon. + The installation of additional packages required for the addon must also be handled by the user or the provided addon. Usually, the addon provider should deliver an installation or setup guide for the addon. The extension for addons was made, so that there is no big feature creep within the main application. -This would cause more and more optional settings, which most user are not interested in. -With addons, users will get the best base experience of CocktailBerry, but can easily extent it to their own taste. +This would cause more and more optional settings, which most users are not interested in. +With addons, users will get the best base experience of CocktailBerry, but can easily extend it to their own taste. Some examples for an addon could be: - Implementation of a weight scale to detect if a glass is present - Add a checklist for invoices or cost splitting -- Modify starting values (default output volume, eg.) to let them be changed over the GUI +- Modify starting values (default output volume, e.g.) to let them be changed via the GUI - Integrate external things like automatic ice crasher - And almost anything you can think of ## Installing Addons There are two options to install an addon. -If it's an [official addon](https://github.com/AndreWohnsland/CocktailBerry-Addons), you can manage it over CocktailBerry. -Go to Setting > Addons > Manage, there you can check the addons you want to have installed. -For any none official one, just put the Python file of the addon into the `addons` folder. +If it's an [official addon](https://github.com/AndreWohnsland/CocktailBerry-Addons), you can manage it via CocktailBerry. +Go to Settings > Addons > Manage, there you can check the addons you want to have installed. +For any non-official one, just put the Python file of the addon into the `addons` folder. It is usually located at `~/CocktailBerry/addons`. If the addon needs additional Python packages, make sure you also install the needed requirements by the addon. An addon should only contain **one** file per addon. If an addon is not working properly, this is mostly due to an error within the addon and not CocktailBerry. -If you think it is related to CocktailBerry, you can open an according issue. +If you think it is related to CocktailBerry, you can open a corresponding issue. ## Updating Addons The update process is quite similar to the installation one. Either go to the CocktailBerry GUI for addons, manage and apply the addons. This will also update existing ones. -If you use an external one, just replace the current file with the latest one, this let you run the latest version. +If you use an external one, just replace the current file with the latest one, this lets you run the latest version. ## Verified Addons Here is a list of verified addons that you can use. They are either directly from CocktailBerry or from other third party providers. -Verified means that the addon is known by the CocktailBerry programmers and was at least once tested for its functionality. +Verified means that the addon is known by the CocktailBerry programmers and was tested at least once for its functionality. - [Start Glass Volume](https://github.com/AndreWohnsland/CocktailBerry-Addons#start-glass-volume): Change default glass volume at machine start - [Recipe Presets](https://github.com/AndreWohnsland/CocktailBerry-Addons?tab=readme-ov-file#-recipe-presets): Manage and use recipe presets @@ -70,11 +70,11 @@ Verified means that the addon is known by the CocktailBerry programmers and was ## Creating Addons -This section is for people, who want to write their own addon. -Here you will find the ressources to get started. +This section is for people who want to write their own addon. +Here you will find the resources to get started. !!! info "Developers Guide" - This section is for developer and people, who want to add some features to CocktailBerry. + This section is for developers and people who want to add some features to CocktailBerry. If you just want to use addons of other people, look at the sections above. ### Set Up @@ -102,8 +102,8 @@ An addon can currently execute code at init, cleanup, start or end of a cocktail In addition, you can provide logic to build up your own GUI, if it is necessary. The file needs the Addon class, please also inherit from the Interface, so you get information about all functions. A more detailed description can be found at the plus icons in the code below. -Even if not all functions must be present within the file, it is best practice to define all. -So it is explicitly clear, that some of the functions do not do anything by design. +Even if not all functions must be present within the file, it is best practice to define all of them. +This makes it explicitly clear that some of the functions intentionally do nothing. A basic structure could look like this: ```python @@ -145,7 +145,7 @@ class Addon(AddonInterface): # (2)! 2. Your class needs to have the name Addon and should inherit from the AddonInterface. 3. Define additional configuration values for your addon here, executed before setup. 4. Initializes the addon, executed at program start. -5. Method for cleanup, executed a program end just before the program closes. +5. Method for cleanup, executed at program end just before the program closes. 6. Executed right before the cocktail preparation. In case of a RuntimeError, the cocktail will not be prepared and the message will be shown to the user instead. 7. Executed right after the cocktail preparation, before other services are connected or DB is updated. 8. This function will be run in a thread on a continuous loop. You can use the `prepare` function to trigger a cocktail preparation. It will return a boolean if the cocktail was prepared successfully and a message string holding more information. There is currently no GUI indication that this cocktail preparation was triggered. @@ -157,11 +157,11 @@ Now that you know the skeleton, you can fill it with your program logic. Some addons may need additional user information, like connected pins, or other variable settings. The easiest (but bad) way is to hard code this into the code and let the user change this value. -But this approach is not robust against code changes (new versions of addon), and also not user friendly (config not accessible over GUI). +But this approach is not robust against code changes (new versions of addon), and also not user friendly (config not accessible via GUI). Therefore, the addon provider can use the CocktailBerry configuration. To do so, the user needs to inject the config name, type and validation function into the config. -There is also the option to provided a description, as well as according translations. -It is important that you use the `define_configuration()` function for this, as it is executed before the setup of the addon and loading in local set config values. +There is also the option to provide a description, as well as corresponding translations. +It is important that you use the `define_configuration()` function for this, as it is executed before the setup of the addon and loading of locally set config values. You can find each direction in the subsections below. #### Add Config Values @@ -187,12 +187,12 @@ def define_configuration(self): ``` 1. Needs to import the `CONFIG` object from CocktailBerry. -2. Adds the configuration under given name and default value. Currently supported are int, float, str, bool and list. Different types have different input mask in the config GUI. +2. Adds the configuration under given name and default value. Currently supported are int, float, str, bool and list. Different types have different input masks in the config GUI. #### Use Config Values Using existing, as well as your newly defined configuration values is quite easy. -All configuration are stored within the `CONFIG` object and are accessible there. +All configurations are stored within the `CONFIG` object and are accessible there. You can use the config name as its attribute to get the desired configuration. ```python @@ -201,7 +201,7 @@ my_config = getattr(cfg, "ADDON_CONFIG") # (2)! program_language = cfg.UI_LANGUAGE # (3)! ``` -1. You can access your previously defined attributes over the `CONFIG` object. +1. You can access your previously defined attributes via the `CONFIG` object. 2. Using the `getattr()` will work as well, if you prefer this way. 3. The `CONFIG` object also holds all settings, which are in the base CocktailBerry app. You can access them as well! @@ -210,7 +210,7 @@ program_language = cfg.UI_LANGUAGE # (3)! You can further add validation besides the type validation of your config. If you don't want to have any other validation besides the type, you don't need to provide additional information. If you want to have additional validation, you can pass any number of functions into the validation list. -Each function needs to have two arguments: The first one being the config name, the second one is the according value. +Each function needs to have two arguments: The first one being the config name, the second the corresponding value. If the value is not valid, you must raise a ConfigError, other errors are not caught by the GUI. The description of the error should inform the user, why it is not valid. Cases may be limiting length of characters, only specific number ranges or similar. @@ -236,16 +236,16 @@ def define_configuration(self): 2. Check function for config validation. First argument is the configname, second is the configvalue. 3. We just raise the exception if the value is "forbidden". 4. Failed validation should throw the `ConfigError`, other errors will crash the app. -5. You can define any number of check function. Please take care that the function interface has two arguments. +5. You can define any number of check functions. Please take care that the function interface has two arguments. #### Validate List Settings An extra case is, if your setting is a list of values. In this case, you can also add a validation function, which will validate each list element. -The schema is identical as before, you can define your custom validation functions. +The schema is identical to before, you can define your custom validation functions. Take note that currently no nested lists are supported and each list element needs to have the same type. If the default value is an empty list, you must provide the element type to the `list_type` argument. -Otherwise, the string type will used as fallback type. +Otherwise, the string type will be used as fallback type. ```python def _less_than_10(configname: str, configvalue: int): # (1)! @@ -263,9 +263,9 @@ def define_configuration(self): ) ``` -1. This function just raises an error is the value is 10 or greater. Again, use the ConfigError, as shown in the last example. +1. This function just raises an error if the value is 10 or greater. Again, use the ConfigError, as shown in the last example. 2. The general set up is identical to the other config examples. -3. Here you could check the list, for example if the length meets a criteria. We do not check anything additional. +3. Here you could check the list, for example if the length meets a criterion. We do not check anything additional. 4. Here you can check each element in the list, in this case we check if any element is >10. #### Using Selection for Dropdowns @@ -275,7 +275,7 @@ In this case, you provide a list of allowed string values. The default value will be the first element of the options, but you can also define this value, if it should be another one. The GUI will then display a drop down, only showing the allowed values. Please take note, if you want types other than string, you need to convert them after you retrieve the value from the config. -The dropdown element only support string values. +The dropdown element only supports string values. ```python def define_configuration(self): @@ -296,16 +296,16 @@ def define_configuration(self): 1. First, you need to define the list of allowed options. 2. Here, you set the default value to the second option. The default value uses the first option. -3. Provide the values as string, even if they are other (here int) types -4. Convert the values after retrieving to your desired type +3. Provide the values as strings, even if they are other (here int) types +4. Convert the values after retrieving them to your desired type #### Add GUI Description Optionally, you can add an additional description to your configuration. -This helps users using the GUI understanding the value better. +This helps users using the GUI to understand the value better. Use the `UI_LANGUAGE` object to set the configuration description. -You can either use a single string describing the config in english, or use a dictionary with the language codes. -At least english is needed, if you do not provided a full list of translations. +You can either use a single string describing the config in English, or use a dictionary with the language codes. +At least English is needed, if you do not provide a full list of translations. If you don't want to provide GUI description, you can skip this step. But it is encouraged to do so to improve user experience. @@ -326,8 +326,8 @@ def define_configuration(self): ``` 1. You need to import the `UI_LANGUAGE` object to access the dialogues -2. If you do provide a dictionary, it needs at least the english (`en`) key! -3. You can also just use a string in the english language, if you don't want to provide translation +2. If you do provide a dictionary, it needs at least the English (`en`) key! +3. You can also just use a string in the English language, if you don't want to provide translation ### Prevent Cocktail Preparation @@ -336,8 +336,8 @@ This way, you can prevent the preparation of the cocktail. For example, if your scale does not recognize a glass, a cocktail should not be prepared. To break the preparation process, raise a RuntimeError. Please do not use other error types, because only this type will be caught and handled. -You can provide an error message in either english, or an according translation for the current language. -You do not need to provide all languages if you do an translation, but you need at least the english one. +You can provide an error message in either English, or a corresponding translation for the current language. +You do not need to provide all languages if you do a translation, but you need at least the English one. The error message will be shown as a dialog to the user, so it should explain why the cocktail was not prepared. ```python @@ -354,7 +354,7 @@ def before_cocktail(self, data: dict): ``` 1. Insert your custom logic to check on condition or external devices if everything is as it should be. -2. You can either directly provide the message, or again define a translation. In the latter, see handling below. If you do provide translation, please make sure english is at least present. +2. You can either directly provide the message, or again define a translation. In the latter, see handling below. If you do provide translation, please make sure English is at least present. 3. When you do the language selection here, it is best to fall back to `en` on a not found key. This is useful when a new language is released, which your addon currently does not support. Otherwise a KeyError will crash the program. The current language is in `cfg.UI_LANGUAGE`. 4. Please raise a `RuntimeError`, other errors will not be caught and crash the program. The used message will be shown to the user. @@ -362,9 +362,9 @@ def before_cocktail(self, data: dict): The best way to implement logging into your addon is to use the internal CocktailBerry logger. This way, your logs are saved and formatted the same way as the other logs. -This makes it easy for the user to view them over the GUI. +This makes it easy for the user to view them via the GUI. The `log_event` takes two arguments: The log level ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL") and the log message. -Or you can just use the default way, the python logger is implemented with the according level function. +Or you can just use the default way: the Python logger is implemented with the corresponding level function. ```python from src.logger_handler import LoggerHandler # (1)! @@ -388,7 +388,7 @@ def setup(self): There are scenarios where you want to persistently store your data. You can either define your own database location and use a framework to your liking, or use the default CocktailBerry database. If you want to use the default database, import the `DatabaseCommander` class and create an instance of it. -The handler attribute have the `query_database` command as an abstraction to interact with the database. +The handler attribute has the `query_database` command as an abstraction to interact with the database. Here you can execute SQLite commands passed as a string. If you want to have dynamic arguments, you can pass them according to the SQLite syntax (`?`), with the corresponding values in the second argument as tuple. The results are automatically fetched and returned as a list of tuples. @@ -422,9 +422,9 @@ def setup(self): ### Own GUI -The `build_gui()` function is used to build up an own GUI for your addon if the user navigates to the addon window. +The `build_gui()` function is used to build your own GUI for your addon if the user navigates to the addon window. A `container` (QVBoxLayout) for your elements is provided, where you can fill in custom Qt elements, if you want that. -If you just want to have some buttons which executes a function, when the user clicks on it, you can use the `button_generator`. +If you just want to have some buttons which execute a function when the user clicks on it, you can use the `button_generator`. It takes a string (label of the button) and a function (executed at button click) as arguments. With the help of this function, you can generate Qt buttons without knowing any Qt at all. If you are experienced with Qt, you can use the container to build more complex things. @@ -476,10 +476,10 @@ ADDON_NAME = "Your Displayed Name" # (1)! 1. Define the ADDON_NAME at root level (outside the other functions or classes) in your file. -### Dialogues an Prompts +### Dialogues and Prompts -There are times, you either want to inform the user with a dialog or want to have a confirmation of the user. -In this cases, you can use the `DP_CONTROLLER` object. +There are times when you either want to inform the user with a dialog or want to have a confirmation of the user. +In these cases, you can use the `DP_CONTROLLER` object. The method `standard_box` will create a window showing your text. The method `user_ok` will prompt the user with the text and return if the user pressed ok. Those methods will use the default used elements from CocktailBerry. @@ -493,35 +493,35 @@ def after_cocktail(self, data: dict): ``` 1. Import the `DP_CONTROLLER` from CocktailBerry to use dialogues. -2. The `user_okay` method will wait until the user accepts or decline and return the result as boolean. +2. The `user_okay` method will wait until the user accepts or declines and return the result as a boolean. 3. The `standard_box` will display your text as a full screen window, with a close / ok button. ### Data Before and After Cocktail -In addition for the action before and after the cocktail preparation, there is additional data provided with the function. +In addition to the action before and after the cocktail preparation, there is additional data provided with the function. You can use the data for your custom logic. -All data is contained within the dictionary as first argument. +All data is contained within the dictionary as the first argument. You can extract the needed properties from it. In the future, there may be more attributes you can use. -The advantage of an dictionary is that this won't break your addon, if new properties are added. +The advantage of a dictionary is that this won't break your addon, if new properties are added. #### Before Cocktail -Following attributes are available in the before_cocktail data: +The following attributes are available in the before_cocktail data: -- cocktail: [Cocktail object](https://github.com/AndreWohnsland/CocktailBerry/blob/master/src/models.py#L28), containing name, adjusted_ingredients and many more attributes. Ingredient object got name and amount for example. +- cocktail: [Cocktail object](https://github.com/AndreWohnsland/CocktailBerry/blob/master/src/models.py#L28), containing name, adjusted_ingredients and many more attributes. Ingredient object has name and amount for example. #### After Cocktail -Following attributes are available in the after_cocktail data: +The following attributes are available in the after_cocktail data: -- cocktail: [Cocktail object](https://github.com/AndreWohnsland/CocktailBerry/blob/master/src/models.py#L28), containing name, adjusted_ingredients and many more attributes. Ingredient object got name and amount for example. -- consumption: List of spend ingredients, which where added by machine (cocktail.machineadds). +- cocktail: [Cocktail object](https://github.com/AndreWohnsland/CocktailBerry/blob/master/src/models.py#L28), containing name, adjusted_ingredients and many more attributes. Ingredient object has name and amount for example. +- consumption: List of spent ingredients, which were added by machine (cocktail.machineadds). ### And Many More In theory, you can use any element from CocktailBerry, but this would go beyond the scope and is not necessary in most cases. -If you are a little familiar with the base code, this should no problem for you. +If you are a little familiar with the base code, this should be no problem for you. Some examples may be: - `src.machine.rfid` RFID Controller @@ -532,14 +532,14 @@ Some examples may be: If your addon uses other external dependencies (Python libraries), please provide some sort of installation guide. The easiest way would be information in the readme of your project, that instructs the user which commands are necessary to get the addon running. Also, if your configuration values are more complex or do need additional context, it is best practice to also provide documentation for them. -This will reduce user confusion an will raise the popularity of your addon. +This will reduce user confusion and will raise the popularity of your addon. If you created a cool addon, you can link me the project. -It may be included here, after it's functionality has been verified. +It may be included here, after its functionality has been verified. This way, more users may find the addon and can use it. ### Make it Verified -To publish your addon and make it visible to the users of CocktailBerry, you can checkout the [official repository](https://github.com/AndreWohnsland/CocktailBerry-Addons). +To publish your addon and make it visible to the users of CocktailBerry, you can check out the [official repository](https://github.com/AndreWohnsland/CocktailBerry-Addons). CocktailBerry will use the information listed there, to get the addon data. Follow the development steps to make your addon a verified and accessible addon! diff --git a/docs/advanced.md b/docs/advanced.md index a70079b7..62ce5df1 100644 --- a/docs/advanced.md +++ b/docs/advanced.md @@ -6,7 +6,7 @@ If you are not interested in them, just skip this section. !!! example "Use the CLI" - The **easiest** way to install the CocktailBerry microservice is over the [CLI](commands.md#setup-the-microservice). + The **easiest** way to install the CocktailBerry microservice is via the [CLI](commands.md#setup-the-microservice). Just run: ```bash uv run runme.py setup-microservice @@ -17,12 +17,12 @@ There is the option to install directly from Docker Hub, a new tag is built every release. This is for more advanced users, since you need to set the files/settings yourself. - Visit [Docker Hub](https://hub.docker.com/search?q=andrewo92) and pull the according images and follow the instruction on Docker Hub. + Visit [Docker Hub](https://hub.docker.com/search?q=andrewo92) and pull the corresponding images and follow the instructions on Docker Hub. ## Installation of Services Simply have `docker compose` installed and run either the CLI command or the docker compose command in the folder, where you specified the `docker-compose.yaml` file. -You will also find more information below for the specific services. +You will also find more information below about the specific services. ```bash uv run runme.py setup-microservice # (1)! @@ -31,8 +31,8 @@ docker compose up --build -d # (3)! ``` 1. This is the recommended and easiest way! -2. Just use this in case you want to use the team feature and also on the same device as CocktailBerry, I recommend at least a RPi 4 with 2GB RAM. -3. If you are an experienced docker user, feel free to do it yourself! If you got a quite old system, docker v1 may be installed. Best is to upgrade, but you can use `docker-compose` as command. +2. Just use this in case you want to use the team feature and also on the same device as CocktailBerry, I recommend at least an RPi 4 with 2GB RAM. +3. If you are an experienced docker user, feel free to do it yourself! If you got a quite old system, docker v1 may be installed. Best is to upgrade, but you can use `docker-compose` as a command. This will handle the setup of all docker services. You may have to set the environment variables, depending on your setup. @@ -57,7 +57,7 @@ uv run runme.py setup-microservice The terminal will interactively ask you for the required information. One example of the usage [can be found in my blog](https://andrewohnsland.github.io/blog/cocktailberry-now-with-home-assistant). -The service will also temporary stores the data within a database, if there was no connection to the endpoint, and try later again. +The service will also temporarily store the data within a database, if there was no connection to the endpoint, and try again later. This way, no data will get lost in the void. ### Posting Data to the Official API @@ -74,13 +74,13 @@ After that, your CocktailBerry will be able to also submit data and help populat !!! warning "For Experienced Users" This is an advanced feature, and you should be familiar with some tinkering on the RPi and command shell. -CocktailBerry got an optional team feature. +CocktailBerry has an optional team feature. If enabled within the config, the user can choose one of the defined teams to register the cocktail to. -The names of the teams, as well the URL of the dashboard device, can be specified within the config. +The names of the teams, as well as the URL of the dashboard device, can be specified within the config. CocktailBerry will then send the information to the team's API. The Dashboard will use the API to display the current status. -You can use amount of cocktails or cocktail volume as metric. +You can use the number of cocktails or cocktail volume as metric. In addition, there is the option to display all time data of the leader board. By default, the latest 24 hours, so mostly this party, will be shown. You should use a second device for the API / the dashboard for easy display on another screen. @@ -98,10 +98,10 @@ You should use a second device for the API / the dashboard for easy display on a The **recommended way** is to use a second Raspberry Pi with a touchscreen attached. But you might also install everything on the same device, if you have enough resources. For this case, I recommend at least a Raspberry Pi 4 with 2GB RAM. -In addition, docker and compose needs to be installed on the device. +In addition, docker and compose need to be installed on the device. !!! tip "More Flexibility" - Both of these images are also available at [Docker Hub](https://hub.docker.com/search?q=andrewo92), so if you want to tweak them, you can just use the pre-build image. + Both of these images are also available at [Docker Hub](https://hub.docker.com/search?q=andrewo92), so if you want to tweak them, you can just use the pre-built image. Create the according `docker-compose.yaml` file on your desktop, or in a separate location. In `CocktailBerry/dashboard` you will find the `docker-compose.both.yaml` file, which you can also use as a template. @@ -116,7 +116,7 @@ sh scripts/setup.sh dashboard ``` !!! danger "Important" - **Please do not use the script on the same Device as CocktailBerry!** It will else overwrite the CocktailBerry autostart. + **Please do not use the script on the same Device as CocktailBerry!** It will otherwise overwrite the CocktailBerry autostart. ### Teams on Same Device @@ -155,7 +155,7 @@ For this, a very easy way is to use [RaspAp](https://raspap.com/). !!! info "Less Typing" Using the included script `sh scripts/install_docker.sh` and `sh scripts/install_compose.sh` will also do that for you. You may have executed it at the setup of your CocktailBerry, if you used the all in one script, and therefore already installed docker. - Using them have the benefit that they may be more up to date than the commands below. + Using them has the benefit that they may be more up to date than the commands below. Just run these commands in sequence on the Pi: diff --git a/docs/commands.md b/docs/commands.md index 0b377e9e..ed7f783c 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -2,13 +2,13 @@ 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 it's sub-commands. +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. !!! info "Used Auto Setup?" - If you installed over the setup script, the program will usually started over the `~/launcher.sh` file. + 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 according values to the `uv run runme.py` command. + Just add the flags or their corresponding values to the `uv run runme.py` command. !!! info "v1 or v2?" If you are already running the API (v2) version, you need to use the command `api.py` instead of `runme.py`. @@ -32,15 +32,15 @@ uv run runme.py [OPTIONS] # --help Show help ``` -If you want to debug your microservice, you ca activate the debug `-d` flag. -When debug is active, the data will be send to the **/debug** endpoint. +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 omit the machine name, version and platform data, use the `-q` flag. +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 user be able to change it via settings: +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. @@ -66,10 +66,10 @@ uv run api.py [OPTIONS] ## Switch to CocktailBerry Web This command will set up the web interface as the default interface. -Take care, this wil no longer start the main program, but the web 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://` 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 user can ignore. +If SSL is enabled, since this is a self-signed certificate, you will get a warning in the browser, which you can ignore. ```bash uv run runme.py setup-web @@ -84,7 +84,7 @@ uv run runme.py setup-web 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 an full windowed app. +The main program will then be started as usual as a full windowed app. ```bash uv run runme.py switch-back @@ -92,7 +92,7 @@ uv run runme.py switch-back ## Clearing Local Database -There may be CocktailBerry owners, who want to create a complete new database. +There may be CocktailBerry owners, who want to create a completely new database. To clean the local database, run: ```bash @@ -104,7 +104,7 @@ uv run runme.py clear-database [OPTIONS] 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 over the interface, or import your recipes from a file (see below). +You can then either enter new recipes via the interface, or import your recipes from a file (see below). ## Importing Recipes from File @@ -137,30 +137,30 @@ 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 new added ingredients. +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 got no unit between amount and name, use the `--no-unit` or `-nu` flag. -If the recipe use another unit than ml, please provide the according conversion factor, like `--conversion 29.5735` or `-c 29.5735`, when using oz. +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. !!! danger "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 build-in backup functionality in CocktailBerry for this. + You can also use the built-in backup functionality in CocktailBerry for this. !!! note "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 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 even) happening, and some consideration and checking of the recipes should take place before doing so. + 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 starting developing your own addon! +Use this command to get started developing your own addon! ```bash uv run runme.py create-addon [OPTIONS] ADDON_NAME @@ -174,12 +174,12 @@ uv run runme.py create-addon [OPTIONS] ADDON_NAME 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, space are replaced with underscores and stripped of special characters. +File name will be the name converted to lower case, spaces are replaced with underscores and stripped of special characters. ## Setup the Microservice You can also use CocktailBerry to set up the [microservice](advanced.md#cocktailberry-microservice) and change the env variables. -It uses the latest image from Dockerhub. +It uses the latest image from Docker Hub. With the microservice, also [watchtower](https://containrrr.dev/watchtower/) will be deployed. Watchtower will check periodically if there is a new microservice image and install it in the background. @@ -195,7 +195,7 @@ uv run runme.py setup-microservice [OPTIONS] ``` Set up the microservice. -If the API key, hook endpoint or hook header is not provided as an option, prompts the user for the values. +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. @@ -209,7 +209,7 @@ If this file already exists, the values will be replaced with the provided ones. ## Setup the Teams Dashboard You can also use CocktailBerry to set up the [Teams Dashboard](advanced.md#dashboard-with-teams). -It uses the latest image from Dockerhub. +It uses the latest image from Docker Hub. With the dashboard, also [watchtower](https://containrrr.dev/watchtower/) will be deployed. Watchtower will check periodically if there is a new dashboard image and install it in the background. @@ -221,13 +221,13 @@ uv run runme.py setup-teams-service [OPTIONS] # --help Show help ``` -Set up the teams microservice. You can use english (en) or german (de) as language. +Set up the teams microservice. You can use English (en) or German (de) 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 crated on a virtual wlan1 interface. +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+. diff --git a/docs/development.md b/docs/development.md index a8327bee..c51c9c62 100644 --- a/docs/development.md +++ b/docs/development.md @@ -12,7 +12,7 @@ It may be implemented in the future. ## Contributing Possibilities -To get started, have a quick look into the [Guidelines for contributing](https://github.com/AndreWohnsland/CocktailBerry/blob/master/CONTRIBUTING.md). +To get started, have a quick look at the [Guidelines for contributing](https://github.com/AndreWohnsland/CocktailBerry/blob/master/CONTRIBUTING.md). Here is a general list of features or refactoring things, I may do in the future. With your help, these things come even faster! If your idea is not on the list, feel free to open a feature request, I may consider it! diff --git a/docs/faq.md b/docs/faq.md index 5b9d49ad..700b3551 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -3,47 +3,47 @@ Here you will find a list of commonly asked questions about the Software or Hardware. Please make sure to check here first, before asking similar questions. You may find your solution under the [troubleshooting](troubleshooting.md) section, if it's not here. -Also, there is plenty information at the [setup section](setup.md). +Also, there is plenty of information at the [setup section](setup.md). ## Hardware ### What are Good Pumps -Any pumps being food save and having a volume flow between 10-50 ml/s are optimal. +Food-safe pumps with a volume flow between 10-50 ml/s are optimal. Higher or lower values are also possible, but may lead either to longer cocktail preparation time or not perfectly dosed cocktails. Best pumps to look out for are peristaltic pumps or membrane pumps. -Also take note that currently all pumps run in parallel so check that your power supply is able to power at least 6 pumps at once. -You can see at the [hardware section](hardware.md) for some recommended pumps. +Also take note that currently all pumps run in parallel, so check that your power supply is able to power at least 6 pumps at once. +You can look at the [hardware section](hardware.md) for some recommended pumps. ### Which Raspberry Pi is Recommended My machines still run on the 1GB RAM 3b+ version. I know of other machines running on a 1/2 GB RAM 4 Version without any problems. Anything older or with less RAM may work, but is not supported. -We officially support also the Raspberry Pi 5, but i strongly recommend using the 4 instead. +We officially support also the Raspberry Pi 5, but I strongly recommend using the 4 instead. ### Will CocktailBerry Work Without Internet Besides pulling this project from GitHub and installing the dependencies at setup, there is no internet connection needed after that. You will not be able to get auto update notifications without an internet connection or use the microservice to send data to an endpoint. -If the microservice is active and the connection is temporary lost, the data is saved until the internet is back again. +If the microservice is active and the connection is temporarily lost, the data is saved until the internet is back again. ### How to Wire the System -Checkout [this section](hardware.md#possible-basic-circuit), this explains a basic circuit you could use. +Check out [this section](hardware.md#possible-basic-circuit), this explains a basic circuit you could use. ### What Display to Use It depends on how you build your machine, but you will most likely want some sort of touchscreen which can be connected to the Raspberry Pi. -Even an 5-inch 800x480 will work, but in my opinion a 7-inch 1024x600 is quite good. -You can see at the [hardware section](hardware.md) for some recommended displays. -Higher resolution screen can be used, for high-res screens (at least v1) I recommend [this setting](troubleshooting.md#using-a-high-resolution-screen) for the best user experience. +Even a 5-inch 800x480 will work, but in my opinion a 7-inch 1024x600 is quite good. +You can look at the [hardware section](hardware.md) for some recommended displays. +Higher resolution screens can be used, for high-res screens (at least v1) I recommend [this setting](troubleshooting.md#using-a-high-resolution-screen) for the best user experience. ### Can I use another Board / SBC You probably can use a wide variety of Single Board Computers (SBCs) beside the Raspberry Pi. The software should work on any system, but there are still some considerations. -Especially if you are unexperienced with programming and Linux, I strongly suggest to stick to the recommended Pi setup. +Especially if you are inexperienced with programming and Linux, I strongly suggest to stick to the recommended Pi setup. If you are experienced with Linux, you can probably get almost any SBC to work properly. I recommend using a wayland based desktop variant, for example a Debian Linux for the OS. The autorun / installation may differ a bit from the Pi. @@ -77,7 +77,7 @@ In v2, you will find the options in the header. Enter the master password (if set), click on configuration. There, you will be able to change all possible settings. See [Setup](setup.md#setting-up-the-machine-modifying-other-values) for a detailed explanation of the configuration options. -The values will also be validated before a change is applies. +The values will also be validated before a change is applied. The changes may require a restart of the program. ### How to Install CocktailBerry @@ -88,24 +88,24 @@ The commands do: Loading the project from GitHub, updating the system, installin ### Can I run Without Pumps -CocktailBerry is a software and therefore will work on any machine, even without any parts of a cocktail machine. +CocktailBerry is software and therefore will work on any machine, even without any parts of a cocktail machine. If you want to have a look into the software, you can also install / run it on your PC or Pi. ### Do I Have to Manually Start There are different ways to auto start an application on the Raspberry Pi. -The installer script automatically sets up a way, that the program starts after the system is booted. +The installer script automatically sets up a way that the program starts after the system is booted. So after the installation, you just need to turn on your Pi! ### What is the Restricted Mode -When you enable the `UI_ONLY_MAKER_TAB` option in the configuration, the user will only can access the maker tab. +When you enable the `UI_ONLY_MAKER_TAB` option in the configuration, the user will only be able to access the maker tab. At program start, you will have to choose if you want to enter the restricted mode or the full mode. If the restricted mode is chosen, only the maker tab is shown or clickable. -Take note that you will still be able to access the urls in the web version, so enabling password protection is recommended if you want to restrict access. +Take note that you will still be able to access the URLs in the web version, so enabling password protection is recommended if you want to restrict access. In the Qt version (v1) the tabs are still shown, but disabled. -To remove restricted mode you will have to click a specific combination on of the different tabs. +To remove restricted mode you will have to click a specific combination of the different tabs. Click the following tabs in this order to exit restricted mode: - 2x Ingredients tab @@ -114,15 +114,15 @@ Click the following tabs in this order to exit restricted mode: Do not click too fast, since this might not work properly. A recommended delay of 0.5s should be sufficient. -If clicked another tab in between, the counter will reset. +If you click another tab in between, the counter will reset. ### What is the Available Button -If you click the available button under bottles, you get to another window, were you can select ingredients. +If you click the available button under bottles, you get to another window, where you can select ingredients. On the right side (possible) are all known ingredients, currently not on the left side. You can put them to the left side (available) or vice versa with the arrow buttons. -Available means, that this ingredient exists / stands besides the maker, but is not connected to a pump. -If a recipe got an ingredient, which should be added via hand / the user later, the machine knows it exists. +Available means, that this ingredient exists / stands beside the maker, but is not connected to a pump. +If a recipe has an ingredient, which should be added via hand / the user later, the machine knows it exists. So CocktailBerry can accurately offer only recipes where both, machine and hand ingredients are there. A little tip here: Ingredients connected to the pump are automatically added by the maker. @@ -133,36 +133,37 @@ So you can switch from machine to hand or the other way in your setup and Cockta Currently, CocktailBerry supports up to 24 pumps in v1 and how many you like in v2. This should usually be more than enough and goes well hand in hand with the hardware. -Relays-arrays can have up to 8 switches controlled with one 5V input. -The usual size is 8 (or 16 with an build in converter) relays for a relay board. -In theory, the RPi could control up to 26 pumps when using all possible GPIOs, but thats overkill IMHO. +Relay arrays can have up to 8 switches controlled with one 5V input. +The usual size is 8 (or 16 with a built-in converter) relays for a relay board. +In theory, the RPi could control up to 26 pumps when using all possible GPIOs, but that's overkill IMHO. +If you use I2C, you can theoretically control up to 128 pumps with one Raspberry Pi. ### What is the Inverted Option -Depending on your controlling unit (relay, mosfet, eg.) the on / off signal may be inverted. +Depending on your controlling unit (relay, mosfet, e.g.) the on / off signal may be inverted. The relay arrays I've seen use a high state for switching off and a low state for switching on. This is the inverted state to a regular n-channel mosfet without any extra elements. The default setting is set to True, so it's inverted by default and should work as expected with usual relay arrays. ### Do I Need Docker -No, docker is optional. -If you don't understand what docker is or what it does, don't worry. +No, Docker is optional. +If you don't understand what Docker is or what it does, don't worry. CocktailBerry will perfectly run without Docker installed. It's for some optional advanced features you can add anytime you are interested or ready for them. -If you use the installer script, docker and its dependencies will be installed automatically. +If you use the installer script, Docker and its dependencies will be installed automatically. ### How to Exit the Program If you want to exit the program to get to the desktop, because you want to do some adjustments, -just press alt+F4 in the main program on your keyboard. -Like with most programs, this will exit the current opened program. +just press Alt+F4 in the main program on your keyboard. +Like with most programs, this will exit the currently open program. You will then be on your desktop. ### I don't Need a Password -Just set the password empty / delete all numbers. -If the password setting ist empty or zero, actions requiring a password will automatically succeed without prompting a password. +Just leave the password empty / delete all numbers. +If the password setting is empty or zero, actions requiring a password will automatically succeed without prompting for a password. ### How to Minimize Start Terminal @@ -188,19 +189,19 @@ With this setting, the window will be minimized before the rest of the program a ### What about Tube Volume -If your pumps got a long tube to the bottle, the first cocktail may have too little volume. +If your pumps have a long tube to the bottle, the first cocktail may have too little volume. You can set the tube volume of each pump in `PUMP_CONFIG`. When applying a new bottle, CocktailBerry will also pump that much volume up. ### Implementing LEDs -You can define one or more pins which control a LED (array). -The LEDs will light up during cocktail preparation, as well when the cocktail is finished. -If it's an controllable WS28x LED you can activate the setting. +You can define one or more pins which control an LED (array). +The LEDs will light up during cocktail preparation, as well as when the cocktail is finished. +If it's a controllable WS28x LED you can activate the setting. Instead of just turning on / off / blinking, the LED will then have some advanced light effects. -If you want to have multiple ring LEDs having the effect synchronously, you can define the number of identical daisy chained rings. +If you want to have multiple ring LEDs having the effect synchronously, you can define the number of identical daisy-chained rings. The program will then not treat this chain as one, but as multiple chains. -This does not include some default LEDs used for general lighting of the machine, because they usually don't need controlling. +This does not include some default LEDs used for general lighting of the machine, because they usually don't need to be controlled. It's better to directly connect them to the main source current and turn them on when the machine is turned on. ### View Logs @@ -209,4 +210,4 @@ You can either go to the logs folder to have the raw logs. Or you can go to the option window and select the logs option. Then you will get a summarized view of the logs. The latest logs are shown on top. -Identical logs are only shown once, with their latest occurrence time, as well as count. +Identical logs are only shown once, with their latest occurrence time, as well as the count. diff --git a/docs/features.md b/docs/features.md index f1625298..2aec5bba 100644 --- a/docs/features.md +++ b/docs/features.md @@ -1,9 +1,9 @@ # Feature Timetable Here you will find a list of the new features introduced over time. -If you don't find a feature listed in the docs on your CocktailBerry, chances may be that you didn't update for some time. -Cross check your version with the feature list and their according introduction time. -Usually, updating to the lastest version is always a good idea. +If you don't find a feature listed in the docs on your CocktailBerry, chances are that you didn't update for some time. +Cross check your version with the feature list and their corresponding introduction time. +Usually, updating to the latest version is always a good idea. | Version | Feature Description | | :---------- | :------------------------------------------------------------------------------------------------------------------- | @@ -36,7 +36,7 @@ Usually, updating to the lastest version is always a good idea. | **v1.18.0** | Addons are now possible
Better recipe ingredient calculation | | **v1.17.0** | Setting up your own custom theme
Possibility to set up WiFi over the GUI
Implementation of the RFID reader | | **v1.16.0** | Summarized logs over the GUI | -| **v1.15.0** | Control a LED during cocktail preparation | +| **v1.15.0** | Control an LED during cocktail preparation | | **v1.14.0** | Can invert pins
set simultaneous pump count
support for generic board | | **v1.13.1** | Clearing the database over the CLI | | **v1.11.0** | Internet check and time adjustment feature | diff --git a/docs/hardware.md b/docs/hardware.md index 69a9fa62..44dedf36 100644 --- a/docs/hardware.md +++ b/docs/hardware.md @@ -2,7 +2,7 @@ You can run the software on any non RPi hardware, but you won't be able to control the pins without a device supporting GPIO control. To build a functional machine, you can take this reference and customize it to your needs. -This offers a good starting point what you might need. +This offers a good starting point for what you might need. How exactly you will build your CocktailBerry is completely up to you. ## Example Machine @@ -12,7 +12,7 @@ The following components were used within the showcase for the Machines (Cocktai - 1x [Raspberry Pi 3b+](https://amzn.to/48bhCBc) (or newer [Model 4](https://amzn.to/4pqSH3v)) - 1x [5-inch Touch Screen](https://amzn.to/3K6Ntei) or [7-inch Touch Screen](https://amzn.to/49sKlnn) for the Raspberry Pi - Official [Touch Screen](https://amzn.to/4pnDPmj) also works -- 1x Micro [SD-Card](https://amzn.to/3JY3Dqn) (16-32 Gb is enough, depending what else you want to store) +- 1x Micro [SD-Card](https://amzn.to/3JY3Dqn) (16-32 GB is enough, depending on what else you want to store) - 1x 5V Power supply for the [Raspberry Pi 3](https://amzn.to/3XbImwj) or [Raspberry Pi 4](https://amzn.to/48axtjp) - 1-2x [8 Channel](https://amzn.to/49ya120) or [16 Channel](https://amzn.to/49xgxGe) Relay-Boards depending on pump count (important to have 5V input control) - 6-24x Pumps, it should be food safe, examples are: @@ -23,18 +23,18 @@ The following components were used within the showcase for the Machines (Cocktai - Female to Female [jumper wires](https://amzn.to/47TY7yc) - Some wires, [Hex-Standoffs](https://amzn.to/4oRQBd0), Screws and other small parts for mounting - Your custom build machine casing -- *Optional*: [HDMI](https://amzn.to/4ra7Wzo) and [USB](https://amzn.to/48n4NF7) cable for small space builds -- *Optional*: A good! [converter](https://amzn.to/4qT18oW) (using usb ones may result in too high voltage loss) if you only want one power source +- *Optional*: [HDMI](https://amzn.to/4ra7Wzo) and [USB](https://amzn.to/48n4NF7) cables for small space builds +- *Optional*: A good [converter](https://amzn.to/4qT18oW) (using USB ones may result in too high voltage loss) if you only want one power source - *Optional*: [USB C](https://amzn.to/3X9I7lw) or [Micro USB](https://amzn.to/4oQDCIu) open cable ## Payment Service -If you want to use the NFC-Reader functionality with the payment service, you will need at least two additional NFC-Reader and another Pi setup: +If you want to use the NFC-Reader functionality with the payment service, you will need at least two additional NFC readers and another Pi setup: - 2x [USB RFID Reader](https://amzn.to/4p75hVZ), other ones might not work out of the box - Compatible NFC tags (e.g., [MIFARE Classic](https://amzn.to/43ZPcsC) or [in Blue](https://amzn.to/43ZPcsC)) - 1x [Raspberry Pi 3b+](https://amzn.to/48bhCBc) (or newer [Model 4](https://amzn.to/4pqSH3v)) -- Additional monitor + mouse + keyboard or another touchscreen see above +- Additional monitor + mouse + keyboard or another touchscreen; see above ## Teams Dashboard @@ -49,11 +49,11 @@ The following components were used within the showcase for the Teams Dashboard: ## Possible Basic Circuit The following picture shows a possible circuit for CocktailBerry. -The Raspberry Pi will provide too litte power / current to operate the pumps. +The Raspberry Pi will provide too little power / current to operate the pumps. You have to use two power circuits, one for powering the Raspberry Pi and one for the pumps. -The pump circuit will be most likely 12 or 24 V. +The pump circuit will most likely be 12 or 24 V. You can either use two different power supplies or use a step down converter for the RPi. -The RPi will control a relay, mosfet or another electrical switch over the GPIO output. +The RPi will control a relay, MOSFET or another electrical switch via the GPIO output.
![circuit](pictures/circuit.jpg) @@ -61,9 +61,9 @@ The RPi will control a relay, mosfet or another electrical switch over the GPIO
You can use any of the GPIOs of the RPi, the connected pump to that pin can be defined in the config. -The switch will then turn the pump on or of over the RPi. +The switch will then turn the pump on or off via the RPi. How you will build your CocktailBerry is still completely up to you. -The only restriction by the software is that the GPIO pins are turned on / off over the RPi. +The only restriction by the software is that the GPIO pins are turned on / off via the RPi. ## Custom PCBs or STLs diff --git a/docs/index.md b/docs/index.md index 22184d87..ef2ad93f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,7 +15,7 @@ Welcome to the CocktailBerry documentation. CocktailBerry is a Python and Qt (or React for v2) based software for a cocktail machine on the Raspberry Pi. -It enables you to build your own, fully customized machine, while still be able to use the identical software on each machine. +It enables you to build your own, fully customized machine, while still being able to use the identical software on each machine. Here you will find everything to get started!
@@ -33,31 +33,32 @@ Like this project? Give it a star on [GitHub](https://github.com/AndreWohnsland/ CocktailBerry currently comes in two versions, v1 and v2. The v1 is the stable version which ships the QT app as a single application. -[v2](https://docs.cocktailberry.org/web/) is the new version with a separate API and UI, which offers more flexibility, but might have some issues on build in touchscreens. +[v2](https://docs.cocktailberry.org/web/) is the new version with a separate API and UI, which offers more flexibility, but might have some issues on built-in touchscreens. Both versions have the full feature set listed below. CocktailBerry offers the following features: - Prepare cocktails of a given volume and adjusted concentration of alcoholic ingredients -- Let customers pay over NFC chips/cards -- Add new ingredients and recipes with needed information over the UI +- Let customers pay via NFC chips/cards +- Add new ingredients and recipes with needed information via the UI - Specify additional ingredients for later hand add within a recipe (like sticky syrup) -- Define connected ingredients to the machine and existing additional ingredients over the UI +- Define connected ingredients to the machine and existing additional ingredients via the UI - Auto calculate and display possible recipes dependent on given information - Option to serve cocktails without alcohol - Execute a cleaning program to get rid of remaining fluids - Visualize the cocktail data and get insights -- Run headless, so you can access it over another device +- Run headless, so you can access it from another device - Send cocktail production data to a given endpoint, for example a webhook - Keep track of cocktail count and volume from different teams for some fun competition - Select different themes to fit your liking - Switch between user interface languages - Support WS281x LEDs on your machine - Support for RFID/NFC reader +- Support for Service Personnel - Implement your own [addon](https://github.com/AndreWohnsland/CocktailBerry-Addons) to extend the base functionality In addition, there is the possibility to use and set up a second device as a dashboard: - Provide the teams API to post and get cocktail data -- Display different modes of data for a by team comparison +- Display different modes of data for a team-by-team comparison - _Optional_: Use the dashboard as WiFi hot-spot diff --git a/docs/installation.md b/docs/installation.md index b9bcb3c4..5a7cc169 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -10,34 +10,34 @@ These are the minimal tools needed to get started: - [Git](https://git-scm.com/downloads) - recommended: **latest** [Raspberry Pi OS, 64 bit](https://www.raspberrypi.com/software/) (Desktop, Trixie) -The desktop version of Raspberry Pi OS is recommended, but if you just want to have a peak into the project, any OS having Python and Git will work just fine. -The RPi is needed to control the Pumps in a real machine, but the program will work fine even without any physical machine. +The desktop version of Raspberry Pi OS is recommended, but if you just want to have a peek into the project, any OS having Python and Git will work just fine. +The RPi is needed to control the pumps in a real machine, but the program will work fine even without any physical machine. ## Install CocktailBerry on the RPi -After flashing the latest Raspberry Pi 64 bit OS, you can use the provided shell scripts to set everything automatically up on your Raspberry Pi. +After flashing the latest Raspberry Pi 64-bit OS, you can use the provided shell scripts to set everything up automatically on your Raspberry Pi. Or just install [the requirements](#installing-requirements), when you want to have a look into the program on your PC. -You can always install the other things later, the docs provide information within each according section. +You can always install the other things later, the docs provide information within each corresponding section. ### Automatic Installation !!! tip "RPi: Try the new all in one Script" - If you are on your Raspberry Pi, you can now also use the so called *All In One Script*! + If you are on your Raspberry Pi, you can now also use the so-called *All In One Script*! This will check that git, Python and your OS are compatible for the project and install CocktailBerry including Docker and compose on the Pi. - + Just use: ```bash wget -O - https://raw.githubusercontent.com/AndreWohnsland/CocktailBerry/master/scripts/all_in_one.sh | bash ``` - to get the script and run it on the Pi. To easy to be true, isn't it? + to get the script and run it on the Pi. Too easy to be true, isn't it? -If you want to have the new v2 API and app, see [web setup](web.md) how to easily switch after the setup. +If you want to have the new v2 API and app, see [web setup](web.md) for how to easily switch after the setup. Or add a `-s v2` at the end of the command to execute the switch directly after installing. ### Manual Installation -To clone and setup this project run: +To clone and set up this project run: ```bash cd ~ @@ -58,12 +58,12 @@ uv run runme.py # (1)! !!! note "This Should be All" As long as you are on the recommended Raspberry Pi + OS, this should be all you need to execute for a complete setup. - This provided script will probably not properly work on other systems, since each OS may handle things differently. + This script will likely not work properly on other systems, since each OS may handle things differently. If you are on another system, have a look into the other instructions, [faq](faq.md) or [troubleshooting](troubleshooting.md). ## Installing Requirements -On none Pi systems, the best way is to use [uv](https://docs.astral.sh/uv/getting-started/installation/). +On non-Pi systems, the best way is to use [uv](https://docs.astral.sh/uv/getting-started/installation/). You just need to clone the project and navigate into the folder. If uv is installed, just run: @@ -76,7 +76,7 @@ to get all requirements. ## Install PyQt6 on RaspberryPi On the latest Raspberry Pi OS (Trixie), PyQt6 installs automatically via uv when you run `uv sync --extra v1`. -If you encounter issues, you can install the system package as fallback: +If you encounter issues, you can install the system package as a fallback: ```bash sudo apt update @@ -85,16 +85,16 @@ sudo apt install python3-pyqt6 ## Development on Non-Pi Hardware -When you are working on another hardware (for example on a Windows or macOS engine) it is recommended (but not necessary) to set `UI_DEVENVIRONMENT` to `true`. +When you are working on other hardware (for example on a Windows or macOS engine) it is recommended (but not necessary) to set `UI_DEVENVIRONMENT` to `true`. This will enable your cursor. All configuration can be customized under `custom_config.yaml`, or over the user interface of the program. This file will be created at the first program start. ## Touchscreen settings -It's worth mentioning that the UI is optimized for a touch display with a 800x480 or a 1024x600 resolution. +It's worth mentioning that the UI is optimized for a touch display with an 800x480 or a 1024x600 resolution. By default, the full screen is also limited to 800x480. So usually, you won't have any problems with the usual HD or uHD screens. -You can change the application size with the according config settings, if you want to use a different screen size. +You can change the application size with the corresponding config settings, if you want to use a different screen size. See [Setting up the Machine / Modifying other Values](setup.md#setting-up-the-machine-modifying-other-values) for more information. -If you are using a high resolution screen, I recommend [this solution](troubleshooting.md#using-a-high-resolution-screen) to prevent the UI looking weird. +If you are using a high resolution screen, I recommend [this solution](troubleshooting.md#using-a-high-resolution-screen) to prevent the UI from looking weird. diff --git a/docs/languages.md b/docs/languages.md index 8df0fc26..da708fef 100644 --- a/docs/languages.md +++ b/docs/languages.md @@ -8,5 +8,5 @@ CocktailBerry includes multi-language support. You can change the language with | German | `de` | 1.3.0 | ✔️ | ✔️ | !!! info "Not your Language?" - If you are interested in implementing your own native language, feel free to contact me or submit an according pull request. + If you are interested in implementing your own native language, feel free to contact me or submit a corresponding pull request. So you can also become a part of CocktailBerry. diff --git a/docs/payment.md b/docs/payment.md index 97d951fd..dc8aab11 100644 --- a/docs/payment.md +++ b/docs/payment.md @@ -9,19 +9,19 @@ If you want to use CocktailBerry autonomously, while still charging for cocktails, you can use one of the Payment Features. This is an optional feature, where you can use CocktailBerry in a more robust way to limit cocktail spending by some criteria. -Currently, two types are supported: NFC based payments and SumUp Terminal payments. +Currently, two types are supported: NFC-based payments and SumUp Terminal payments. === "NFC Based" - For the NFC based payments, a separate Payment Service is used to manage user entities and their balances. + For the NFC-based payments, a separate Payment Service is used to manage user entities and their balances. You can own the whole service and manage the NFC tags yourself. - A "User" entity is a NFC tag, which can have some (non-personal) properties associated with it. + A "User" entity is an NFC tag, which can have some (non-personal) properties associated with it. Currently supported criteria are: - **Alcohol restriction**: Users can be restricted from ordering alcoholic cocktails (child vs adult). - **Balance**: Each entity can have a balance, which is checked and deducted when ordering cocktails. - A separate payment service needs to be installed and setup to manage the user entities. + A separate payment service needs to be installed and set up to manage the user entities. There is a dedicated project and (see below) setup instructions for this service. === "SumUp" @@ -33,7 +33,7 @@ Currently, two types are supported: NFC based payments and SumUp Terminal paymen For SumUp Terminal payments, a physical SumUp card terminal (Solo) is used to process payments. CocktailBerry as well as the terminal need to be connected to the internet for this to work. When a user wants to order a cocktail, CocktailBerry will request a payment from the SumUp Terminal. - This will be done over the SumUp Cloud API, which is currently only supported for SumUp Solo terminals. + This will be done via the SumUp Cloud API, which is currently only supported for SumUp Solo terminals. The user will then need to confirm the payment on the terminal, by the supported payment methods. You will need a SumUp account and a compatible terminal for this to work. @@ -49,13 +49,13 @@ To use payments with CocktailBerry, you will need the following: === "SumUp" - A [SumUp Solo Terminal](https://store.sumup.com/de-DE/website/product-selection/card_reader.solo_bundle_cradle) - - A [SumUp Account](https://www.sumup.com/) fully set up and you merchant code + - A [SumUp Account](https://www.sumup.com/) fully set up and your merchant code - API key generated for your account - CocktailBerry version 3.1 or higher !!! danger "Updating from older Versions?" If you are updating from an older version of CocktailBerry, you might need to run some additional setup steps. - It is recommended to backup your current settings and do a clean install over the setup script instead. + It is recommended to backup your current settings and do a clean install via the setup script instead. Then use the backup to restore your settings. If you want to update your existing installation, do the usual update process. @@ -70,13 +70,13 @@ After that, CocktailBerry should start normally again. ## Concept -If this feature is enabled, user will need to pay before being able to order a cocktail. +If this feature is enabled, users will need to pay before being able to order a cocktail. === "NFC Based" - When using NFC based payments, each user will need to have an NFC tag (e.g., card or key fob) associated with them. + When using NFC-based payments, each user will need to have an NFC tag (e.g., card or key fob) associated with them. The tag will be read by the NFC reader, and the unique identifier (UID) of the tag will be sent to the CocktailBerry Manager Service. The Manager Service will then check if the UID is valid and if the user associated with the tag has sufficient balance to order a cocktail. - A Tag ID can be associated with a 18+ or younger than 18 user, allowing to restrict cocktail orders based on age. + A Tag ID can be associated with an 18+ or younger than 18 user, allowing to restrict cocktail orders based on age. If the UID is valid and the user has sufficient balance, the order will be processed. The Service will take care of deducting the cocktail price from the user's balance. Also, managing user balances and age restrictions will be handled by the Manager Service. @@ -131,8 +131,8 @@ Overall Process: While you can run it on the same device as the backend, it is recommended to run it on a separate device for better performance and security. CocktailBerry Machines using the payment option will communicate with the backend API to process payments and manage user balances. - This requires the machines being either on the same network or having access to the backend API over the internet. - User will then pay the cocktails over NFC cards, while service personal can manage the users and top up balances via the GUI separately. + This requires the machines being either on the same network or having access to the backend API via the internet. + Users will then pay for the cocktails via NFC cards, while service personnel can manage the users and top up balances via the GUI separately. === "SumUp" ```mermaid @@ -153,9 +153,9 @@ Overall Process: The customer orders a cocktail from the CocktailBerry machine. CocktailBerry requests a payment from the SumUp API. The SumUp API communicates with the SumUp Terminal to start the payment process. - The customer pays using the terminal over Card or other supported methods. - The transaction data is sent back to the SumUp API, which then is polled by CocktailBerry about the successful payment. - Since this is done over the cloud API, CocktailBerry and the Terminal both need to be connected to the internet. + The customer pays using the terminal via card or other supported methods. + The transaction data is sent back to the SumUp API, which is then polled by CocktailBerry about the successful payment. + Since this is done via the cloud API, CocktailBerry and the Terminal both need to be connected to the internet. Once the payment is confirmed, CocktailBerry processes the order and dispenses the cocktail. ## Setup @@ -170,7 +170,7 @@ The recommended way for a "basic" hardware setup is: - A desktop device + USB NFC reader running the payment GUI, can be Windows - CocktailBerry machine + USB NFC reader, connected to the payment API over the network - While you can run the backend on the same machine as CocktailBerry, or the the Admin payment GUI, it is recommended to run them on separate devices for better performance and security. + While you can run the backend on the same machine as CocktailBerry, or the Admin payment GUI, it is recommended to run them on separate devices for better performance and security. If you want to really keep it minimalistic, you can also run both API and GUI on the same device, e.g. a Raspberry Pi 4. In this case you would need to ensure that this device is not down or turned off. @@ -186,7 +186,7 @@ The recommended way for a "basic" hardware setup is: You will need a setup [sumup](https://www.sumup.com/) account for this to work. Once created, you will be asked multiple things during the account setup. - When you are done, see at your account settings, where you should see your Merchant Code (a string starting with "MCM"). + When you are done, check your account settings, where you should see your Merchant Code (a string starting with "MCM"). In addition, you will need to [create an API key](https://me.sumup.com/settings/api-keys) for your account. More information can also be found in the [SumUp Developer Documentation](https://developer.sumup.com/tools/authorization/authorization#create-api-key). Keep this safe, you will need it in the CocktailBerry settings. @@ -198,11 +198,11 @@ The recommended way for a "basic" hardware setup is: === "NFC Based" - Follow the according steps for your OS to set up the payment service and GUI. + Follow the corresponding steps for your OS to set up the payment service and GUI. === "Linux Systems" - Linux is the most easy way, since most of the things can be done over a script. + Linux is the easiest way, since most of the things can be done over a script. Just run: ```bash @@ -222,7 +222,7 @@ The recommended way for a "basic" hardware setup is: ``` Alternatively, there is also a pre-built executable available for the GUI, which you can download from the [release page](https://github.com/AndreWohnsland/CocktailBerry-Payment/releases). - You might not be able to set all options tough when using this directly, so even when using this, going over this preparation and service installation steps is recommended. + You might not be able to set all options though when using this directly, so even when using this, going over this preparation and service installation steps is recommended. If [uv](https://docs.astral.sh/uv/getting-started/installation) or [git](https://git-scm.com/install/windows) fails to install, you might need to install them manually first. @@ -242,27 +242,27 @@ The recommended way for a "basic" hardware setup is: === "SumUp" First, you will need to provide both, the SumUp API key as well as the merchant code to CocktailBerry. - You can enter both over the GUI, or edit the `custom_config.yaml` directly in the CocktailBerry folder, since the copying the key is better. + You can enter both over the GUI, or edit the `custom_config.yaml` directly in the CocktailBerry folder, since copying the key is better. Look for the `PAYMENT_SUMUP_API_KEY` and `PAYMENT_SUMUP_MERCHANT_CODE` entries and set them accordingly. In addition, you will need to select the SumUp payment option in the GUI or set `PAYMENT_OPTION` to `SumUp` in the config file. After that, you will need to connect your terminal to the internet following the steps on it. Then select Cloud API mode on the terminal. It will display a code, you will need this in CocktailBerry to link the terminal to your account. - Go to options -> SumUp, there you can give you Terminal a name and enter the code. + Go to options -> SumUp, there you can give your Terminal a name and enter the code. After submitting, you should see a successful message and the terminal should be displayed and selected in the list of connected Terminals. In case you own multiple machines and registered terminals, you can also select or change the terminal over the dropdown. Take note that only one terminal per machine is supported. The terminal identifier will be stored in the config file as `PAYMENT_SUMUP_TERMINAL_ID`. - Since you will store the API key in you settings, which is accessible over the options GUI, make sure to set a good master password to protect your settings. + Since you will store the API key in your settings, which is accessible over the options GUI, make sure to set a good master password to protect your settings. ## Configuration You can manage the settings like all other settings over the CocktailBerry Interface. See also the [Configuration documentation](setup.md) for more details. -In general, the options were made so you can tweak them as you needed. +In general, the options were made so you can tweak them as you need. You might experiment with different settings to find the best fit for your use case. Some important options are: @@ -272,7 +272,7 @@ Some important options are: - **Auto Logout**: Automatically log out users after a specified time, only enable this if you are sure this time is more than enough for a user to order a cocktail. - **Logout after Order**: Log out the user after each order, useful if users usually just order one Cocktail and you use the lock screen. - **Lock Screen**: User needs to scan his NFC to unlock the cocktail selection. Use this if you want to enforce first time scanning to filter/show only possible cocktails. - - **Show not possible cocktails**: Show all cocktails (not possible in another style), even if the user is not allowed to order them. Might be not the best if you use age restrictions, since they will never be able to order them. + - **Show not possible cocktails**: Show all cocktails (not possible in another style), even if the user is not allowed to order them. might not be the best if you use age restrictions, since they will never be able to order them. === "SumUp" - **Opt In**: Enable and select the SumUp payment integration. diff --git a/docs/quickstart.md b/docs/quickstart.md index dd39f2a5..fde8cb1b 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -7,18 +7,18 @@ If you want to use v2 in a manual installation, you also need to have [Node.js]( ## Raspberry Pi !!! tip "RPi: Try the all in one Script" - If you are on your Raspberry Pi, you can just use the so called *All In One Script*! + If you are on your Raspberry Pi, you can just use the so-called *All In One Script*! This will check that git, Python and your OS are compatible for the project and install CocktailBerry including Docker and Compose on the Pi. - + Just use: ```bash wget -O - https://raw.githubusercontent.com/AndreWohnsland/CocktailBerry/master/scripts/all_in_one.sh | bash ``` - to get the script and run it on the Pi. To easy to be true, isn't it? + to get the script and run it on the Pi. Too easy to be true, isn't it? Now you can [Set Up](setup.md#setting-up-the-machine-modifying-other-values) your CocktailBerry and tweak the settings to your liking. -If you want to have the new v2 API and app, see [web setup](web.md) how to easily switch after the setup. +If you want to have the new v2 API and app, see [web setup](web.md) for how to easily switch after the setup. Or add a `-s v2` at the end of the command to execute the switch directly after installing. ## Other OS or Development Setup diff --git a/docs/setup.md b/docs/setup.md index b9854917..4d6bfe9c 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -6,26 +6,26 @@ CocktailBerry will work directly after using the installer, but you can make you CocktailBerry comes with a limited set of recipes and ingredients. You can use the program to add your own ingredients or recipes, or rename and change existing ones. -Just use the implemented UI for the procedure under the according tabs (**Ingredients** or **Recipes**). -All entered values are checked for reason and if something is wrong, an error message will inform the user what is wrong with the data input. +Just use the implemented UI for the procedure under the corresponding tabs (**Ingredients** or **Recipes**). +All entered values are checked for validity and if something is wrong, an error message will inform the user what is wrong with the data input. !!! info "Database Structure" - If you want to browse through the data in the database, I recommend some program like [DB Browser for SQLite](https://sqlitebrowser.org/). + If you want to browse through the data in the database, I recommend a program like [DB Browser for SQLite](https://sqlitebrowser.org/). You can view the DB schema [here](https://github.com/AndreWohnsland/CocktailBerry/blob/master/docs/.devnotes.md#db-schema). ## Setting up the Machine / Modifying other Values You can manage your config within CocktailBerry. -Just go to the bottles tab (v1), click the gear icon or to the according option tab (v2) and enter your password. +Just go to the bottles tab (v1), click the gear icon or to the corresponding option tab (v2) and enter your password. You can then use the UI to change the configuration. -The configuration is also divided into own tabs, containing similar categories in one tab. +The configuration is also divided into separate tabs, containing similar categories in one tab. -These values are stored under the local `custom_config.yaml` file. +These values are stored in the local `custom_config.yaml` file. This file will be created at the first machine run and inherit all default values. Depending on your pumps and connection to the Pi, these can differ from the default and can be changed. -If any of the values got a wrong data type, a message with the issue will be shown. +If any of the values have a wrong data type, a message with the issue will be shown. Names starting with `EXP` are experimental and may be changed in the future. -They can be used at own risk of CocktailBerry not working 100% properly. +They can be used at your own risk of CocktailBerry not working 100% properly. ??? info "List UI Config Values" UI Config Values are used to change the look and feel of the program. @@ -48,7 +48,7 @@ They can be used at own risk of CocktailBerry not working 100% properly. | Value Name | Description | | :---------------------------- | :-------------------------------------------------------- | - | `MAKER_NAME` | Give your CocktailBerry an own name, max 30 chars | + | `MAKER_NAME` | Give your CocktailBerry its own name, max 30 chars | | `MAKER_NUMBER_BOTTLES` | Number of displayed bottles, can use up to 16 bottles | | `MAKER_PREPARE_VOLUME` | List of possible spend volumes of machine | | `MAKER_SIMULTANEOUSLY_PUMPS` | Number of pumps which can be simultaneously active | @@ -140,14 +140,14 @@ Customizing and using your own setting will make your CocktailBerry unique. The choice is up to you what you want to connect. See [here](#possible-ingredient-choice) for a possible ingredient setting. -Select under **Bottles** your assigned ingredients for each pump. +Select your assigned ingredients under **Bottles** for each pump. In addition, you can define ingredients which are available, but are not connected to the machine (under **Bottles** > _available_). -This can be ingredients, which would not be optimal for your pump (sticky), or are only very rarely used in cocktails. -At the ingredient properties, you can set this ingredient only addable by hand. -These ingredients are not shown in the bottle dropdown but only at the available window. -Choose this option for ingredients you won't connect to the machine, to reduce the amount of options displayed at the dropdown. +These can be ingredients, which would not be optimal for your pump (sticky), or are only very rarely used in cocktails. +In the ingredient properties, you can set this ingredient as only addable by hand. +These ingredients are not shown in the bottle dropdown but only in the available window. +Choose this option for ingredients you won't connect to the machine, to reduce the amount of options displayed in the dropdown. -The program will then evaluate which recipe meets all requirements to only show the recipes where all existing ingredients (machine + hand) exist. +The program will then evaluate which recipes meet all requirements to only show the recipes where all existing ingredients (machine + hand) exist. All possible recipes will be shown in the **Maker** Tab. See also [this FAQ](faq.md#what-is-the-available-button) for more information on this topic. @@ -161,11 +161,11 @@ Currently supported options (boards) are: !!! info "Not your Board?" Even if your board is not listed here, it may work. - This value is used to determinate the control method for the pins of the board. + This value is used to determine the control method for the pins of the board. ## Themes -Currently, there are following themes: +Currently, there are the following themes: - **default**: The look and feel of the project pictures. Blue, Orange and Black as main colors. - **bavaria**: The somewhat light mode of the app. Blue, Black and White as main colors. @@ -189,21 +189,21 @@ Do a mix of the different volumes, add them together and check if the scale show ## Cleaning the Machine -CocktailBerry has a build in cleaning function for cleaning at the end of a party. +CocktailBerry has a built-in cleaning function for cleaning at the end of a party. You will find the feature at the option gear under the **Bottles** tab. CocktailBerry will then go to cleaning mode for the defined time within the config (default is 20 seconds). A message prompt will inform the user to provide enough water for the cleaning process. !!! question "When to Clean" Depending on the build specification of your machine, it is a good practice to execute the cleaning of the machine before and after usage. - This depends on the frequency you use CocktailBerry, where it's stored, how good it was cleaned and so on. + This depends on how frequently you use CocktailBerry, where it's stored, how good it was cleaned and so on. -If you have activated the the option of inverted current with `MAKER_PINS_INVERTED`, you will be prompted before the cleaning if you want to invert the current for the cleaning process. +If you have activated the option of inverted current with `MAKER_PINS_INVERTED`, you will be prompted before the cleaning if you want to invert the current for the cleaning process. This way, you can clean the tubes from both sides and get rid of all fluid in the end. ## Possible Ingredient Choice -If you are unsure, which ingredients you may need or want to connect to CocktailBerry, here is a quick suggestion. +If you are unsure which ingredients you may need or want to connect to CocktailBerry, here is a quick suggestion. You don't need to use all ten slots, but the more you use, the more recipes will be possible: - Vodka @@ -217,7 +217,7 @@ You don't need to use all ten slots, but the more you use, the more recipes will - _optional_ Tequila - _optional_ Grapefruit Juice -In addition, there are some ingredients recommend adding by hand, the most important additional ingredients will be: +In addition, there are some ingredients recommended for adding by hand, the most important additional ingredients will be: - Soft drinks (Cola, Fanta, Sprite) - Grenadine syrup @@ -225,7 +225,7 @@ In addition, there are some ingredients recommend adding by hand, the most impor - Lemon juice (just a little, you can also use fresh lemons) - _optional_ Cointreau (you may just not add it if not desired) -With this as your base set up, even if not using the optional ingredients, your CocktailBerry will be able to do plenty of different cocktails. +With this as your base setup, even if not using the optional ingredients, your CocktailBerry will be able to do plenty of different cocktails. !!! tip "Data Insights" You can export the CocktailBerry data to a CSV file over the interface. @@ -236,13 +236,13 @@ With this as your base set up, even if not using the optional ingredients, your There is the option to enable the automatic search for updates at program start. The `MAKER_SEARCH_UPDATES` config can enable this feature. -CocktailBerry will then check the GitHub repository for new releases and informs the user about it. +CocktailBerry will then check the GitHub repository for new releases and inform the user about it. If accepted, CocktailBerry will pull the latest version and restart the program afterwards. The migrator will do any necessary steps to adjust local files, like the database to the latest release. ## Backups You can backup your local data (local database, config-file) to a desired folder or external device. -Use this backup to restore the data, or recover the progress and recipes after doing a OS reinstall. +Use this backup to restore the data, or recover the progress and recipes after doing an OS reinstall. Just go to the **Bottles** tab, click on the gear icon and enter your master password to get to the options window. There you will find both options for backup and restoring your data. diff --git a/docs/support.md b/docs/support.md index 241db8fe..80cb70f0 100644 --- a/docs/support.md +++ b/docs/support.md @@ -6,16 +6,16 @@ There are different ways to support and contribute to CocktailBerry. This includ This helps to identify missing features as well as eliminate bugs. This way, CocktailBerry will get better faster. -Also, if a desired feature makes sense, it will probably implemented in the future. +Also, if a desired feature makes sense, it will probably be implemented in the future. #### Star the project on GitHub -This shows that the project is used and trusted, as well will raise it's visibility. +This shows that the project is used and trusted and raises its visibility. If more people are using CocktailBerry, more feedback will be received. !!! quote "Tell your Friends" - If you think other people might enjoy CocktailBerry, be not shy to tell them about the project. - More active user means more feedback, which is always a great benefit and will boost development. + If you think other people might enjoy CocktailBerry, don't be shy to tell them about the project. + More active users mean more feedback, which is always a great benefit and will boost development. #### Implement an addon @@ -24,8 +24,8 @@ This is a good place to start, since you need little knowledge about the base co #### Contribute to the base code -Either help implementing new base features, fix issues or improve the existing code base. -This requires some working into the existing base code, but delivers a great opportunity to shape CocktailBerry. +Either help implement new base features, fix issues or improve the existing code base. +This requires some work on the existing base code, but delivers a great opportunity to shape CocktailBerry. #### Buy me a coffee and other support options diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 989ea584..f5a9d0a9 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -7,7 +7,7 @@ If you don't find any solution here, you can [open a ticket](https://github.com/ ## Major Version Updates If a breaking change is introduced, a major version update is released (e.g. v2.9.0 to v3.0.0). -Usually, this changes cannot be automatically migrated and need some manual steps. +Usually, these changes cannot be automatically migrated and need some manual steps. Other cases might need the latest OS version or python version, which you might or might not have. See below for migration steps for the related versions. @@ -19,7 +19,7 @@ This way, you ensure that everything is working as intended and you don't run in V3 introduces the NFC Payment service integration as well as the update from PyQt5 to PyQt6. While the NFC changes "just" need some shell commands, the PyQt6 library needs the latest Raspberry Pi OS to work properly out of the box. -There is a good chance that your current setup will work due to the migrator doing it magic and you have PyQt6 after that. +There is a good chance that your current setup will work due to the migrator doing its magic and you have PyQt6 after that. It is however not guaranteed, so if you run into any issues, please ensure that you are on the latest OS (Trixie) first. To add the NFC, please run the following commands in your terminal: @@ -31,7 +31,7 @@ bash scripts/setup_usb_nfc.sh If you are not on the latest Raspberry Pi OS, please consider updating your system first. The best way is to backup your data and do a fresh install of the OS. -I personally cannot recommend upgrading an existing OS, except you know what you are doing and how to fix issues. +I personally cannot recommend upgrading an existing OS, unless you know what you are doing and how to fix issues. Otherwise, you can run: ```bash @@ -43,47 +43,47 @@ sudo apt install python3-pyqt6 All cases (e.g. not enough of one ingredient, no/wrong values ...) should be handled, and an info message should be displayed. If in any case any unexpected behavior occurs, feel free to open an issue. -Usually, a part of the actions are also logged into the log files. +Usually, part of the actions is also logged into the log files. When submitting an error, please also provide the `logs/debuglog.log` file. ## Icons are Missing If some of the icons (check / cross on the checkbox, up / down arrow on the list view) are missing, make sure you run the script within the folder (e.g. `uv run runme.py`) and not from another folder (e.g. `CocktailBerry/runme.py`). -This is because of the nature of Qt and the translation to python, if you go from another folder the picture ressources can't be found. +This is because of the nature of Qt and the translation to python, if you go from another folder the picture resources can't be found. -Another reason may be, if you are using a custom style sheet with colors using rgb. -If thats the case, please change the color codes to the hexadecimal representation of the color, because qtawesome can't handle rgb color codes. +Another reason may be if you are using a custom style sheet with colors using rgb. +If that's the case, please change the color codes to the hexadecimal representation of the color, because qtawesome can't handle rgb color codes. ## Changing Volume Unit -For the users of the machine, there is the possibility to set the `EXP_MAKER_UNIT` and `EXP_MAKER_FACTOR` option to change the displayed unit, for example to oz. +For the users of the machine, there is the possibility to set the `EXP_MAKER_UNIT` and `EXP_MAKER_FACTOR` options to change the displayed unit, for example to oz. Please take note that the units stored in the database are still in ml, and if inserting new recipes, you still need to provide them in ml. -This feature is purely cosmetic and for the user of the maker tab when making cocktails, that no calculations need to be done while making cocktails. +This feature is purely cosmetic and for the user of the maker tab when making cocktails, so that no calculations need to be done while making cocktails. ## Restoring Database The migrations create a backup of the database before doing the modifying steps. -If you rather don't want to have the new recipes, you can overwrite the local `Cocktail_database.db` with the `Cocktail_database_backup.db` file. +If you'd rather not have the new recipes, you can overwrite the local `Cocktail_database.db` with the `Cocktail_database_backup.db` file. ```bash cp Cocktail_database_backup-{your-date-string}.db Cocktail_database.db ``` -This will restore the state of the backup previous this migration step. -Please take a look into the production_log file, if a backup was created. -Otherwise, you may up ending using an older one. +This will restore the state of the backup prior to this migration step. +Please take a look at the production_log file, if a backup was created. +Otherwise, you may end up using an older one. ## Using a High Resolution Screen -The UI of the program is somewhat dynamic, but Qt got it's limitations. +The UI of the program is somewhat dynamic, but Qt has its limitations. To ensure that the UI looks nice like in the screenshots, a resolution not higher than ~1200px on the long side (width) is recommended. -If you happen to use a high res screen, there is a easy fix, tough. -For example, when using a screen with a 2560x1600 resolution, I would recommend divide the value by `x` (for example x=2). -In the CocktailBerry config set width to 2560/2 = 1280 and height to 1600/2 = 800. +If you happen to use a high-resolution screen, there is an easy fix, though. +For example, when using a screen with a 2560x1600 resolution, I would recommend dividing the value by `x` (for example x=2). +In the CocktailBerry config, set width to 2560/2 = 1280 and height to 1600/2 = 800. In case you used the provided setup, just change the first line in the ~/launcher.sh file `export QT_SCALE_FACTOR=1` from 1 to x (2 in the example case). This will use the lower dimensions for the application but scale it up by the factor of two so it occupies the whole screen. -Decimal numbers for x do also work, just try not to get decimals for width / height. -If you use your own startup script or similar, just add the export line with an according value to it, or set the environment variable in any other desired way. +Decimal numbers for x also work, just try not to get decimals for width / height. +If you use your own startup script or similar, just add the export line with a corresponding value to it, or set the environment variable in any other desired way. ## Touchscreen Calibration @@ -114,19 +114,19 @@ After the reboot, the calibration should be okay. ## How to Have the Right Time There is the config value `MAKER_CHECK_INTERNET`. -If you wish to use your microservice, but got no internet at the moment, the data will be saved and send later. +If you wish to use your microservice, but have no internet at the moment, the data will be saved and sent later. One problem that occurred, is that, for example on a standard Raspberry Pi, the clock and therefore the timestamp will probably be wrong. -This new option tackles that. If it's set active with an active microservice, it will check for internet connection at startup. +This new option tackles that. If it's set to active with an active microservice, it will check for internet connection at startup. If there is no connection, a dialog will pop up and give the user the possibility to adjust the time. -In case the machine got a RTC build in and uses it, this option can usually be set to `false`, because due to the RTC, the time should be correct. +In case the machine has an RTC built in and uses it, this option can usually be set to `false`, because due to the RTC, the time should be correct. ## Get the LED Working Getting the WS281x to work may be a little bit tricky. You need to run the program as root/sudo, so you also need to change this in `~/launcher.sh`. If you are using the latest installer, there will be a virtual environment created, so you should use this as root. -This also does you require to reinstall the python packages for the main program. -A better way would be to add the user to the gpio/other needed groups, so you can run the program as normal user. +This also requires you to reinstall the python packages for the main program. +A better way would be to add the user to the gpio/other needed groups, so you can run the program as a normal user. ```bash # for v1: change this line @@ -144,55 +144,55 @@ sudo -E .venv/bin/python api.py If the GUI looks different than when you run it without sudo, try the `-E` flag, this should use your environment for Qt. See [here](https://github.com/jgarff/rpi_ws281x#gpio-usage) for a possible list and explanation for GPIOs. -I had success using the 12 and 18 PWM0 pin, while also disabling (use a # for comment) the line `#dtparam=audio=on` on `/boot/config.txt`. -Other described pins may also work, but are untested, so I recommend to stick to the both one that should work. +I had success using the 12 and 18 PWM0 pins, while also disabling (use a # for comment) the line `#dtparam=audio=on` on `/boot/config.txt`. +Other described pins may also work, but are untested, so I recommend sticking to the two that should work. If you use any other non controllable LED connected over the relay, you can use any pin you want, since it's only activating the relay. ## Set Up RFID Reader -Setting up a GPIO RFID reader and integrate it into the program is an intermediate task. +Setting up a GPIO RFID reader and integrating it into the program is an intermediate task. It is not recommended for complete beginners, and it may include some tinkering. As long as you use the recommended usb reader, you should be fine. -Currently you can use those different types of reader: +Currently, you can use these different types of readers: - Basic MFRC522 ([like this](https://amzn.to/4puhW4T), SPI Protocol) - USB RFID Reader (like [this](https://amzn.to/4p75hVZ), only reading UID supported) !!! bug "Please Read" - Reading / Writing RFIDs while still having a interactive GUI may cause a lot of troubles. + Reading / Writing RFIDs while still having an interactive GUI may cause a lot of trouble. Some reader frameworks lock themselves until the read or write is done and have no direct cancel methods. So even using threads only fixes the responsiveness of the app. - Therefore, the best is if you trigger a write, finish the write. - If you have experience with the reader + python feel free to contact me, so we can improve this feature. + Therefore, it's best to trigger a write, finish the write. + If you have experience with the reader + Python feel free to contact me, so we can improve this feature. Setting them up is described [here for the MFRC522](https://pimylifeup.com/raspberry-pi-rfid-rc522/). You only need the wiring and the installation of the libraries (usually they are already installed). -The according code is integrated into CocktailBerry. -After that, you select the according option in the settings dropdown for the reader. -When using the teams function, you can then also use a RFID chip, which inserts the information (name of person) for the leaderboard. +The corresponding code is integrated into CocktailBerry. +After that, you select the corresponding option in the settings dropdown for the reader. +When using the teams function, you can then also use an RFID chip, which inserts the information (name of person) for the leaderboard. In addition, when going to the settings tab, the option to write a string (name) to a chip is enabled. Take care that you don't use any of the connected pins of the RFID reader in the CocktailBerry config for a pump or a LED. If you do so, remove them or replace them with another pin. Otherwise, the RFID will not work. -Best is to restart the Pi afterwards and then check if the RFID is working as intended. +It's best to restart the Pi afterwards and then check if the RFID is working as intended. While the USB NFC reader does not occupy any GPIO pins, it has some challenges on its own. -You currently cant write data to the card, only read the UID is supported. +You currently can't write data to the card, only reading the UID is supported. -## Ui Seems Wrong on none RaspOS System +## UI Seems Wrong on non-RaspOS System On different Linux systems (other than the recommended Raspbian OS), there may be differences in the look and functionality of the user interface. -This can be dependant on the flavour of Linux, as well as the desktop variant you are using. -I had best experience when using a LXDE/XFCE variant, for example of a Debian Linux, on a none Raspberry Pi single board computer. -Other desktop variants may do not respect the always on top property, resulting in the taskbar show up on top the app when running the program and pop ups appear. +This can be dependent on the flavour of Linux, as well as the desktop variant you are using. +I had the best experience when using a LXDE/XFCE variant, for example of a Debian Linux, on a non-Raspberry Pi single board computer. +Other desktop variants may not respect the always on top property, resulting in the taskbar showing up on top of the app when running the program and pop ups appear. Please take note that CocktailBerry will run on other systems than the Raspberry Pi OS and RPi, but may take some tweaking and testing in the settings. -Since I probably don't own that combination of Hardware and OS, you probably need to figure out that settings by yourself. -If you are a unexperienced user with Linux, I recommend you stick to the recommended settings on a Pi. +Since I probably don't own that combination of hardware and OS, you probably need to figure out those settings by yourself. +If you are an inexperienced user with Linux, I recommend you stick to the recommended settings on a Pi. ## Task Bar Overlap / Push GUI -This may happen (especially at older versions os RPi OS or higher res screens) when running the program and some dialog window opens. -The task bar (bar with programs on it) may overlap the dialog window or push it down by it's height. +This may happen (especially at older versions of RPi OS or higher res screens) when running the program and some dialog window opens. +The task bar (bar with programs on it) may overlap the dialog window or push it down by its height. Ensure that you have unchecked the "Reserve space, and not covered by maximised windows" option. You can find it under the panel preferences (right click the task bar > panel settings > Advanced). Unchecking this box usually fixes this problem. @@ -200,7 +200,7 @@ Unchecking this box usually fixes this problem. ## Reset Config In case you want to reset the configuration, it is the best way to just delete the custom_config.yaml in the main folder. -This file holds your configuration and will be created with the defaults if it does not exists. +This file holds your configuration and will be created with the defaults if it does not exist. There are also backups of the config file before migration, located at `~/cb_backup/` with the version number before this specific migration. The config file is located at `~/CocktailBerry/custom_config.yaml`. @@ -222,11 +222,11 @@ cat ~/cb_backup/custom_config_pre_{version_number}.yaml It may happen that you don't get the latest version of the software prompted at start, even if you check for updates. This can be due to different reasons. -First, check if you have a internet connection. +First, check if you have an internet connection. If you have, check if you have the latest recommended version of python installed. -CocktailBerry will not show the update if the future needed python version is higher than the current installed one. +CocktailBerry will not show the update if the future required Python version is higher than the current installed one. Another reason may be that your git file is corrupted. -Check with for errors like object file x is empty: +Check for errors like object file x is empty: ```sh cd ~/CocktailBerry @@ -245,24 +245,24 @@ If you get another error output, it is best to submit the error output with the With the v1.30.0 release, the maker view was completely rewritten. This includes the way cocktails are shown as a list and single view. -There is a picture now for every cocktail, the default provided cocktails all got an according picture. +There is a picture now for every cocktail, the default provided cocktails all got a corresponding picture. There is also a default picture for cocktails without a picture, like newly user added ones. -You can upload your own pictures over the according button the recipe tab. +You can upload your own pictures via the corresponding button in the recipe tab. Your picture will then replace the default provided picture. The user pictures are stored in the `~/CocktailBerry/display_images_user` folder. The picture will be saved with the cocktail id as name and jpg format. -You can also provide the cocktail name in lowercase and underscore instead spaces as picture name in jpg format (e.g. `cuba_libre.jpg` for "Cuba Libre"), if you prefer to upload the pictures via hand in that folder instead of the GUI. +You can also provide the cocktail name in lowercase with underscores instead of spaces as the picture name in jpg format (e.g. `cuba_libre.jpg` for "Cuba Libre"), if you prefer to upload the pictures manually in that folder instead of the GUI. If your database is quite old, newer cocktails you added may either have the default picture, or may have another picture from new cocktails contained now in the database. This is due to the database using incrementing integers as primary key for the cocktails. -This is historically and can't be changed easily in running installations. -If thats the case, please use the GUI option to replace wrong pictures with your desired ones. +This is historical and can't be changed easily in running installations. +If that's the case, please use the GUI option to replace wrong pictures with your desired ones. If you feel that the default pictures are switched, you can also use the default ones as replacement. They are located at `~/CocktailBerry/default_cocktail_images`. -Here is an extensive list of all default cocktails and their according image. -If you think your cocktail have the wrong picture, you can use the according picture name from the list below to replace it. +Here is an extensive list of all default cocktails and their corresponding image. +If you think your cocktail has the wrong picture, you can use the corresponding picture name from the list below to replace it. ??? info "List of Default Pictures" @@ -366,14 +366,14 @@ sudo chmod 755 ~/launcher.sh ``` !!! info "By the Way" - The provided installer script does all that steps for you. + The provided installer script does all those steps for you. ### The GUI on the RPi Looks Different from the Screenshots I've noticed when running as root (sudo python) and running as the pi user (python) by default the pi will use different GUI resources. Using the pi user will result in the shown interfaces at CocktailBerry (and the program should work without root privilege). Setting the XDG_RUNTIME_DIR to use the qt5ct plugin may also work but is untested. -Using the users environment with `sudo -E .venv/bin/python runme.py` should also do the trick. +Using the user's environment with `sudo -E .venv/bin/python runme.py` should also do the trick. ### Raspberry Pi 5 GPIO Issues diff --git a/docs/waiter.md b/docs/waiter.md index d19a92e3..9031120b 100644 --- a/docs/waiter.md +++ b/docs/waiter.md @@ -6,7 +6,7 @@ !!! warning "NFC Reader Conflict" Service Personnel Mode and CocktailBerry NFC Payment both require the NFC reader. - They cannot be enabled at the same time, nor is the initial intend that they would be used together. + They cannot be enabled at the same time, nor is the initial intent that they would be used together. If you need payment functionality, see the [Payment Feature](payment.md) instead. ## Overview @@ -61,13 +61,13 @@ sequenceDiagram cb->>cb: Auto-Logout (if configured) ``` -Once logged in, the staff member can then prepare cocktails, and each preparation is logged to their name. +Once logged in, the staff member can then prepare cocktails, and each preparation is logged under their name. Logout happens either manually, automatically after a cocktail, or after a configured timeout. ## Difference in Appearance Between v1 and v2 Since we use distinct GUI technologies for v1 (Qt) and v2 (Web), there are some differences in how the logged-in staff member is displayed and how logout works. -See the according section for your version below. +See the corresponding section for your version below. ### Logged-in Staff Display and Logout diff --git a/docs/web.md b/docs/web.md index 7e2b919f..156fa0e7 100644 --- a/docs/web.md +++ b/docs/web.md @@ -1,40 +1,40 @@ # CocktailBerry Web !!! info "This is still new and not the default interface yet" - This is a new implementation and not so much battle tested like the old interface. + This is a new implementation and not as battle-tested as the old interface. If you spot any issues, please report them in the [GitHub repository](https://github.com/AndreWohnsland/CocktailBerry/issues/new/choose). In general, most features should work as expected, but there might be some edge cases that are not covered yet. This is within the [roadmap](https://github.com/users/AndreWohnsland/projects/1) for v2. The goal of this release is to provide a more polished and at the same time more flexible app. -It includes a new web interface that can be used to control the machine from any device in the same network. +It includes a new web interface that can be used to control the machine from any device on the same network. This allows users to control the machine from their phone, tablet, or any other device that has a web browser. Machines without a display (e.g. Headless) are no longer a dream, you can build and use them now with CocktailBerry. In addition, the API (backend) is no longer tightly coupled to the frontend. -Advanced users can use the API for their own use, like writing their own frontend or automating tasks over home automation. +Advanced users can use the API for their own use, like writing their own frontend or automating tasks via home automation. ## Quick Install -You can also directly install it over the all in one installer script by specifying `v2` as version. +You can also directly install it via the all-in-one installer script by specifying `v2` as version. ```bash wget -O - https://raw.githubusercontent.com/AndreWohnsland/CocktailBerry/master/scripts/all_in_one.sh | bash -s v2 ``` -This will do the similar setup steps as in v1, but directly install the web interface version. +This will do similar setup steps as in v1, but directly install the web interface version. ## Requirements It is not recommended to use this on Raspberry Pi 3 series or older, as the performance might not be sufficient. Use a Raspberry Pi 4 with 2 GB or more of RAM for the best experience. -You need to have an up to date Raspberry Pi OS installed. +You need to have an up-to-date Raspberry Pi OS installed. The web interface requires a modern web browser that supports the latest web technologies. You do not need a touch screen, just a device being able to connect to the same network as the Raspberry Pi. However, a touchscreen can be used to control the app directly on the Raspberry Pi. -As a word of caution: Currently it is difficult to propagate events to open the keyboard on kiosk mode (full screen). -This is only an issue if you are using a touchscreen directly connected to the Raspberry Pi, not over phone or tablet. -You might start with a none full screen web browser for now, but we are working on a solution. +As a word of caution: Currently it is difficult to trigger the virtual keyboard in kiosk mode (full screen). +This is only an issue if you are using a touchscreen directly connected to the Raspberry Pi, not via phone or tablet. +You might start with a non-full-screen web browser for now, but we are working on a solution. ## Limitations @@ -42,7 +42,7 @@ Currently, the web interface might have some issues with touch screens directly In some occasions, older OS or not properly configured screens, the default keyboard might not show up. If you are using an external device to control the app, this should not be an issue. In case you are using a touch screen directly connected to the Raspberry Pi, running the browser in non-kiosk mode might help. -Installing maliit keyboard might also be an alternative. +Installing the maliit keyboard might also be an alternative. ## Installation @@ -63,7 +63,7 @@ uv run runme.py setup-web ``` This will set up the web interface as the default interface and start it instead of the old main program. -You can now access the the website by opening your browser and navigating to `http://` or locally on `http://localhost`. +You can now access the website by opening your browser and navigating to `http://` or locally on `http://localhost`. Note: In the following section we use `uv run api.py` instead of `uv run runme.py` to start the web interface. diff --git a/readme.md b/readme.md index c471a6af..5d6abbe0 100644 --- a/readme.md +++ b/readme.md @@ -14,7 +14,7 @@ [![Support CocktailBerry](https://img.shields.io/badge/Support%20CocktailBerry-donate-yellow)](https://www.buymeacoffee.com/AndreWohnsland) CocktailBerry is a Python and Qt (or React for v2) based app for a cocktail machine on the Raspberry Pi. -It enables you to build your own, fully customized machine, while still be able to use the identical software on each machine. +It enables you to build your own, fully customized machine, while still being able to use the identical software on each machine. Detailed information, installation steps and SetUp can be found at the [Official Documentation](https://docs.cocktailberry.org). v2-demo @@ -25,8 +25,8 @@ Supercharge your next party to a whole new level! 🐍 + 🍸 = 🥳 documentation dashboard -This app is used to control a cocktail machine and easily prepare cocktails over a nice-looking user interface. -It also offers the option to create and manage your recipes and ingredients over the interface and calculates the possible cocktails to prepare over given ingredients. +This app is used to control a cocktail machine and easily prepare cocktails via a nice-looking user interface. +It also offers the option to create and manage your recipes and ingredients via the interface and calculates the possible cocktails to prepare from given ingredients. Track and display cocktail data for different teams to even further increase the fun. Let's get started! @@ -40,33 +40,34 @@ Like this project? Give it a star on GitHub! ⭐ CocktailBerry currently comes in two versions, v1 and v2. The v1 is the stable version which ships the QT app as a single application. -[v2](https://docs.cocktailberry.org/web/) is the new version with a separate API and UI, which offers more flexibility, but might have some issues on build in touchscreens. +[v2](https://docs.cocktailberry.org/web/) is the new version with a separate API and UI, which offers more flexibility, but might have some issues on built-in touchscreens. Both versions have the full feature set listed below. CocktailBerry can do: - Prepare cocktails of a given volume and adjusted concentration of alcoholic ingredients -- Let customers pay over NFC chips/cards -- Add new ingredients and recipes with needed information over the UI +- Let customers pay via NFC chips/cards +- Add new ingredients and recipes with needed information via the UI - Specify additional ingredients for later hand add within a recipe (like sticky syrup) -- Define connected ingredients to the machine and existing additional ingredients over the UI +- Define connected ingredients to the machine and existing additional ingredients via the UI - Auto calculate and display possible recipes dependent on given information - Option to serve cocktails without alcohol - Execute a cleaning program to get rid of remaining fluids - Visualize the cocktail data and get insights -- Run headless, so you can access it over another device +- Run headless, so you can access it from another device - Send cocktail production data to a given endpoint, for example a webhook - Keep track of cocktail count and volume from different teams for some fun competition - Select different themes to fit your liking - Switch between user interface languages - Support WS281x LEDs on your machine - Support for RFID/NFC reader +- Support for Service Personnel - Implement your own [addon](https://github.com/AndreWohnsland/CocktailBerry-Addons) to extend the base functionality In addition, there is the possibility to use and set up a second device as a dashboard: - Provide the teams API to post and get cocktail data -- Display different modes of data for a by team comparison +- Display different modes of data for a team-by-team comparison - _Optional_: Use the dashboard as WiFi hot-spot # Quickstart @@ -74,7 +75,7 @@ In addition, there is the possibility to use and set up a second device as a das Here are some simple steps to get CocktailBerry running. You need to have **Python 3.13** or newer and **git** installed. If you are using a Raspberry Pi and a current OS, you should be good to go. -On the RPi, you can try the new [all in one installer script](https://github.com/AndreWohnsland/CocktailBerry/blob/master/scripts/all_in_one.sh). +On the RPi, you can try the new [all-in-one installer script](https://github.com/AndreWohnsland/CocktailBerry/blob/master/scripts/all_in_one.sh). One command should install everything: ```bash @@ -145,7 +146,7 @@ Generally, it is recommended to first open an issue or an discussion to talk abo # Development -This project uses [uv](https://docs.astral.sh/uv/), [node.js](https://nodejs.org/en) and [yarn](https://yarnpkg.com/getting-started/install) to manage all its python dependencies. +This project uses [uv](https://docs.astral.sh/uv/), [node.js](https://nodejs.org/en) and [yarn](https://yarnpkg.com/getting-started/install) to manage all its Python dependencies. To get started, you need to install the tools and then install the dependencies. See also at the [dev notes](./docs/.devnotes.md) section for a complete run down as well as extra information. @@ -181,7 +182,7 @@ If you want to develop the api, you can also run it with uv run fastapi dev ./src/api/api.py ``` -and run the web ui over: +and run the web UI via: ```bash cd web_app/ @@ -198,8 +199,8 @@ The mocked NFC reader will cycle through two predefined IDs every minute, it wil If you want to test specific behavior, it is recommended not to mock but use the real hardware. The mocked payment service will simulate successful payments without actually connecting to any external service. -It will create not existing ids with a default balance of 20. -The adult flag will circle between true and false for each new id. +It will create non-existing IDs with a default balance of 20. +The adult flag will cycle between true and false for each new id. ## Building Documentation