Skip to content

improve wording, fix some typos #68

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jose1711 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

improve wording, fix some typos #68

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 28 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# ICS

Adds a sensor to Home Assistant that displays the date and number of days to the next event.
E.g. 5 days until the trash will be picked up. The information will be read from a user definded
Adds a sensor to Home Assistant that displays the date and number of days to the next event.
E. g. 5 days until the trash will be picked up. The information will be read from a user defined
ics file.

**This component will set up the following platforms.**
**This component will set up the following platforms:**

Platform | Description
-- | --
Expand All @@ -17,19 +17,19 @@ Platform | Description

- Supports ICS file (local and online) with reoccuring events
- Events can be filtered, so you can tell it to look only for certain events
- Has attributes that calculated the number of days, so you can easily run a automation trigger, show start / end of the events
- Has attributes that calculates the number of days, so you can easily run an automation trigger or show start/end of the events
- Low CPU and network usage, as it only updates once per day (whenever the date changes) or when the event is over (assuming force reload is disabled)
- If multiple events occure on the same time, all title will be shown, connected with "/"
- If multiple events occur on the same time, all titles will be shown, connected with "/"
- Can be configured to look for 'the event after the event'

# Installation

## HACS

The easiest way to add this to your Homeassistant installation is using [HACS].
The easiest way to add this to your Home Assistant installation is using [HACS].

It's recommended to restart Homeassistent directly after the installation without any change to the Configuration.
Homeassistent will install the dependencies during the next reboot. After that you can add and check the configuration without error messages.
It is recommended to restart Home Assistant directly after the installation without any change to the Configuration.
Home Assistant will install the dependencies during the next reboot. After that you can add and check the configuration without error messages.
This is nothing special to this Integration but the same for all custom components.


Expand All @@ -56,33 +56,33 @@ custom_components/ics/const.py

# Setup

All you need to have is a link to a ICS file, e.g. https://www.rmg-gmbh.de/download/Hamb%C3%BChren.ics
All you need to have is a link to a ICS file, e. g. https://www.rmg-gmbh.de/download/Hamb%C3%BChren.ics

## Configuration options

Key | Type | Required | Default | Description
-- | -- | -- | -- | --
`name` | `string` | `true` | `None` | The friendly name of the sensor
`url` | `string` | `true` | `None` | The url to the ics file usually some weblink, but can also be local file e.g. https://www.rmg-gmbh.de/download/Hamb\%C3%BChren.ics or file:///tmp/test.ics
`id` | `int` | `true` | `None` | A number to identify your sensor later on. e.g. for id=1 the entity will be sensor.ics_1 using id 1 a second will result in sensor.ics_1_2
`timeformat` | `string` | `false` | `"%A, %d.%m.%Y"` | The format that is used to display the date see http://strftime.org/ for more infomation
`lookahead` | `int` | `false` | `365` | The number of days that limits the forecast. E.g. 1 will only show the events of today
`startswith` | `string` | `false` | `""` | A filter that will limit the display of events. E.g. if your file contains multiple entries and you only want to know one type at per sensor, simply create multiple sensors and filter. Have a look at sensor 3 and 4 above. startswith: Bio will ohne show events that start with Bio.
`contains` | `string` | `false` | `""` | A filter like startswith, but this will search within the string instead of the start.
`show_blank` | `string` | `false` | `""` | Indicates whether to show empty events (events without title), and what should be used as title instead. e.g. "Meeting123" would show events with empty title with the string "Meeting123". An empty string (default) or " " will avoid showing blank events.
`force_update` | `int` | `false` | `0` | Force to update the data with given intervall (seconds). This can be useful if the calendar is very dynamic, but pointless for almost static calendars. The calendar will reload at midnight and once the (start/end) of the event is over regardless of this setting. 0 = Disabled
`url` | `string` | `true` | `None` | The url to the ics file, typically a http(s) address, but can also be local file e. g. https://www.rmg-gmbh.de/download/Hamb\%C3%BChren.ics or file:///tmp/test.ics
`id` | `int` | `true` | `None` | A number to identify your sensor later on. e. g. for id=1 the entity will be sensor.ics_1 using id 1 a second will result in sensor.ics_1_2
`timeformat` | `string` | `false` | `"%A, %d.%m.%Y"` | The format that is used to display the date, see http://strftime.org/ for more infomation
`lookahead` | `int` | `false` | `365` | The number of days that limits the forecast. E. g. 1 will only show the events of today
`startswith` | `string` | `false` | `""` | A filter that will limit the display of events. E. g. if your file contains multiple entries and you only want to know one type at per sensor, simply create multiple sensors and filter. Have a look at sensor 3 and 4 above. startswith: Bio will only show events that start with Bio. Case is ignored.
`contains` | `string` | `false` | `""` | A filter like startswith, but this will search anywhere in the string instead of just matching the start. Case is ignored.
`show_blank` | `string` | `false` | `""` | Indicates whether to show empty events (events without title), and what should be used as title instead. e. g. "Meeting123" would show events with empty title with the string "Meeting123". An empty string (default) or " " will avoid showing blank events.
`force_update` | `int` | `false` | `0` | Force to update the data using the given interval (seconds). This can be useful if the calendar is very dynamic, but pointless for almost static calendars. The calendar will reload at midnight and once the (start/end) of the event is over regardless this setting. 0 = Disabled
`show_remaining` | `bool` | `false` | `true` | Show the remaining days in the sensor state, close to the date.
`show_ongoing` | `bool` | `false` | `false` | Show events that have already started but not finished.
`group_events` | `bool` | `false` | `true` | Show events with same start date as one event
`n_skip` | `int` | `false` | `0` | Skip the given amount of events, useful to show the appointment AFTER the next appointment
`description_in_state` | `bool` | `false` | `false` | Show the title of the events in the state
`icon` | `string` | `false` | `mdi:calendar` | MDI Icon string, check https://materialdesignicons.com/

## GUI configuration
## GUI configuration

As of 2020/04/20 config flow is supported and is the prefered way to setup the integration. (No need to restart Home-Assistant)
As of 2020/04/20 config flow is supported and is the preferred way to setup the integration. (No need to restart Home Assistant)

## Manual configuration
## Manual configuration

To enable the sensor, add the following lines to your `configuration.yaml` file and replace the link accordingly:

Expand Down Expand Up @@ -169,7 +169,7 @@ automation:
value_template: "{{ state_attr('sensor.ics_3', 'remaining') == 1 }}"
```

and create / send some beautiful messages like this:
and create/send some beautiful messages like this one:

```yaml
script:
Expand All @@ -186,7 +186,7 @@ script:

# Use-cases for skip property
Show the next n-Events. Simply by creating three sensors with `n_skip:0 / n_skip:1 / n_skip:2` <br>
Setting 'description_in_state: True` will also show the title.
Setting `description_in_state: True` will also show the title.


![Example](img_feiertage.png)
Expand All @@ -195,12 +195,12 @@ Or list the next sport events

![Example](img_fussi.png)

# Advance feature
Reoccuring events, events at the same time, skippig events (EXDATE) ... all that can have quite some complexity to it.
# Advanced feature
Reoccuring events, events at the same time, skipping events (EXDATE) ... all that can have quite some complexity to them.

![Example](img_complex_cal.png)

The image above shows my test calendar (year = 2030! thus all lookahead must be >> 365)
The image above shows my test calendar (year = 2030! thus all lookahead must be > 365)

## Regular (with grouping)
```yaml
Expand All @@ -220,7 +220,7 @@ sensor:
n_skip: 0
description_in_state: False
```
Without advance options (all defaults) we'll get a sensor, showing both event1 and event3 because grouping is enabled (`group_events: True`).
Without advanced options (all defaults) we'll get a sensor, showing both event1 and event3 because grouping is enabled (`group_events: True`).

![Example](img_1_reg.png)

Expand All @@ -244,7 +244,7 @@ Without advance options (all defaults) we'll get a sensor, showing both event1 a
n_skip: 3
description_in_state: True
```
This configuration will show 'allday'. `group_events` will combine the "event1/event3". `show_blank` is not set, so the event without title will be ignored.
This configuration will show 'allday'. `group_events` will combine the "event1/event3". `show_blank` is not set, so the event without title will be ignored.

## Skip 3 next events but show blank events
```yaml
Expand Down Expand Up @@ -282,4 +282,4 @@ Setting `show_blank: 'Hallo'` will add the previous empty event to the list and
n_skip: 1
description_in_state: False
```
This will only look at events that `startswith: 'reocc'`. The first occurance on the 7.1.2030 will be skipped (`n_skip:1`), [the exdate will drop the 8.1.2030] and thus 9.1.2030 will be shown.
This will only look at events that `startswith: 'reocc'`. The first occurence on the 7.1.2030 will be skipped (`n_skip:1`), [the exdate will drop the 8.1.2030] and thus 9.1.2030 will be shown.