Skip to content

Commit

Permalink
Merge pull request #227 from marcelvriend/fix/update-readme
Browse files Browse the repository at this point in the history 
Update readme
  • Loading branch information
@isabellaalstrom
isabellaalstrom authored Jun 12, 2022
2 parents 9072310 + f71742e commit fe9e5ab
Showing 1 changed file with 60 additions and 31 deletions.
91 changes: 60 additions & 31 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,52 +3,72 @@
---
**INFO**

**Works with Grocy version 3 and above.**
**The integration supports Grocy version 3.2 and above.**

**At least Home Assistant version 2021.12 is required for the integration from v4.3.3 and above.**

You have to have the Grocy software already installed and running, this integration only communicates with an existing installation of Grocy. You can install the software with the [Grocy add-on](https://github.com/hassio-addons/addon-grocy) or another installation method, found at [Grocy website](https://grocy.info/).

---


# Adding the integration
## <a name="addon"></a>for Grocy add-on

## First steps <a name="addon"></a>for Grocy add-on
The configuration is slightly different for those who use the [official Grocy add-on](https://github.com/hassio-addons/addon-grocy) from the add-on store.

1. If you haven't already done so, install Grocy from the add-on store
2. In the 'Configuration' section of the add-on config, input `9192` in the host field - see [screenshot](#screenshot). Save your changes and restart the add-on.
3. Install [HACS](https://hacs.xyz/)
4. Go to Community > Store > Grocy
5. Install the Grocy integration
6. Restart Home Assistant
7. Go to Grocy > Wrench icon > Manage API keys > Add
8. Copy resulting API key
9. In the HA UI go to "Configuration" -> "Integrations" click "+" and search for "Grocy"
10. Fill out the information according to [this instruction](#integration-configuration).
11. You will now have a new integration for Grocy. Some or all of the entities might be disabled from the start.

1. If you haven't already done so, install Grocy from the add-on store.
2. In the 'Configuration' section of the add-on config, input `9192` in the Network port field - see [screenshot](#screenshot-addon-config). Save your changes and restart the add-on.
3. Now continue with the instructions below.

## <a name="external"></a> for existing external Grocy install
## Instructions for <a name="both"></a>both installation methods
1. Install [HACS](https://hacs.xyz/), if you haven't already done so.
2. In Home Assistant go to HACS > Integrations. Search for the "Grocy custom component" repository by clicking the "Explore & download repositories" button in the bottom right corner.
3. In the bottom right corner click "Download the repository with HACS". Click "Download". Optional: for latest features and fixes choose "Show beta versions".
4. Restart Home Assistant as instructed by HACS.
5. Install the [Grocy integration](https://my.home-assistant.io/redirect/config_flow_start/?domain=grocy). Fill out the information according to [this instruction](#integration-configuration).
6. Before integration version v4.3.3, now restart Home Assistant again (with later versions you can skip this step).
7. You will now have a new integration for Grocy. All entities are disabled from start, manually enable the entities you want to use.

1. Install [HACS](https://hacs.xyz/)
2. Go to Community > Store > Grocy
3. Install the Grocy integration
4. Restart Home Assistant
5. Go to Grocy > Wrench icon > Manage API keys > Add
6. Copy resulting API key
7. In the HA UI go to "Configuration" -> "Integrations" click "+" and search for "Grocy"
8. Fill out the information according to [this instruction](#integration-configuration).
9. You will now have a new integration for Grocy. Some or all of the entities might be disabled from the start.
Future integration updates will appear automatically within Home Assistant via HACS.


# Entities
Some or all of the entities might be disabled from the start.

**All entities are disabled from the start. You have to manually enable the entities you want to use in Home Assistant.**
You get a sensor each for chores, meal plan, shopping list, stock and tasks.
You get a binary sensor each for expired, expiring and missing products and overdue tasks and chores.

# Translation

# Services

The following services come with the integration. For all available options check the [Developer Tools: Services](https://my.home-assistant.io/redirect/developer_services/) within Home Assistant.

- **Grocy: Add Generic** (_grocy.add_generic_)

Adds a single object of the given entity type.

- **Grocy: Add Product To Stock** (_grocy.add_product_to_stock_)

Adds a given amount of a product to the stock.

- **Grocy: Complete Task** (_grocy.complete_task_)

Completes the given task.

- **Grocy: Consume Product From Stock** (_grocy.consume_product_from_stock_)

Consumes a given amount of a product from the stock.

- **Grocy: Execute Chore** (_grocy.execute_chore_)

Executes the given chore with an optional timestamp and executor.


# Translations

Translations are done via [Lokalise](https://app.lokalise.com/public/260939135f7593a05f2b79.75475372/). If you want to translate into your native language, please [join the team](https://app.lokalise.com/public/260939135f7593a05f2b79.75475372/).


# Troubleshooting

If you have problems with the integration you can add debug prints to the log.
Expand All @@ -61,18 +81,27 @@ logger:
   custom_components.grocy: debug
```
If you are having issues and want to report a problem, always start with making sure that you're on the latest version of the integration, Grocy and Home Assistant.
If you are having issues and want to report a problem, always start with making sure that you're on the latest _beta_ version of the integration, Grocy and Home Assistant.
You can ask for help [in the forums](https://community.home-assistant.io/t/grocy-custom-component-and-card-s/218978), or [make an issue with all of the relevant information here](https://github.com/custom-components/grocy/issues/new?assignees=&labels=&template=bug_report.md&title=).
# <a name="integration-configuration"></a>Integration configuration
The api url should be in the form below. If you use an SSL certificate you should have `https` and also check the box. Do **not** have a trailing slash at the end of the url and do not have the port in the url. It should work with for example a duck dns address as well, but you still have to access it via a port, and the above instructions for the url still apply.
## URL
The Grocy url should be in the form below (start with `http://` or `https://`) and point to your Grocy instance. If you use a SSL certificate you should have `https` and also check the "Verify SSL Certificate" box. Do **not** enter a port in the url field. Subdomains are also supported, fill out the full url in the field.

## API key
Go to your Grocy instance. Navigate via the wrench icon in the top right corner to "Manage API keys" and add a new API key. Copy and paste the generated key.

**(This component will not currently work if you have an install where you don't use a port, as long as [this issue](https://github.com/SebRut/pygrocy/issues/121) is not resolved)**
## Port
It should work with for example a Duck DNS address as well, but you still have to access it via a port, and the above instructions for the url still apply.
- If you have configured the [Grocy add-on](#addon) as described, use port 9192 (without https). Either be sure the port is open in your router or use your internal Home Assistant address.
- If you have configured an [external Grocy](#both) instance and not sure, use port 80 for http or port 443 for https. Unless you have set a custom port for Grocy.

![alt text](grocy-integration-config.png)

# <a name="screenshot"></a>Add-on port configuration

# <a name="screenshot-addon-config"></a>Add-on port configuration

![alt text](grocy-addon-config.png)

0 comments on commit fe9e5ab

Please sign in to comment.