diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 9af449e..5b7fd8f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -33,7 +33,7 @@ repos: - id: gitlint - repo: https://github.com/astral-sh/ruff-pre-commit - rev: 859e42ab7d54544f32d4f73bbc2136a7d9094f54 # frozen: v0.8.1 + rev: 36b36942c52d8ce8ae6314461f2d86b1fda158e3 # frozen: v0.9.3 hooks: - id: ruff files: ^(scripts|tests|custom_components)/.+\.py$ @@ -55,7 +55,7 @@ repos: - setuptools - repo: https://github.com/pre-commit/mirrors-mypy - rev: f56614daa94d5cd733d3b7004c5df9caad267b4a # frozen: v1.13.0 + rev: bbc3dc1f890007061f18f17e2334f216ea9e5df7 # frozen: v1.14.1 hooks: - id: mypy additional_dependencies: @@ -73,6 +73,6 @@ repos: - id: reuse - repo: https://github.com/rhysd/actionlint - rev: 5db9d9cde2f3deb5035dea3e45f0a9fff2f29448 # frozen: v1.7.4 + rev: 03d0035246f3e81f36aed592ffb4bebf33a03106 # frozen: v1.7.7 hooks: - id: actionlint diff --git a/README.md b/README.md index 1bdf85c..d116c69 100644 --- a/README.md +++ b/README.md @@ -10,115 +10,115 @@ calendars and sensors to go with them related to managing rental properties. # Table of Contents -- [Features](#features) -- [Installation](#installation) - - [MANUAL INSTALLATION](#manual-installation) - - [INSTALLATION VIA Home Assistant Community Store (HACS)](#installation-via-home-assistant-community-store-hacs) -- [Setup](#setup) -- [Reconfiguration](#reconfiguration) -- [Known issues](#known-issues) -- [Frequently Asked Questions](#frequently-asked-questions) - - [Why does my calendar events say `Reserved` instead of the guest's name?](#why-does-my-calendar-events-say-reserved-instead-of-the-guests-name) - - [Where can I find my rental calendar's `ics` URL?](#where-can-i-find-my-rental-calendars-ics-url) - - [How do I use custom calendars?](#how-do-i-use-custom-calendars) - - [Automation Examples](#automation-examples) +- [Features](#features) +- [Installation](#installation) + - [MANUAL INSTALLATION](#manual-installation) + - [INSTALLATION VIA Home Assistant Community Store (HACS)](#installation-via-home-assistant-community-store-hacs) +- [Setup](#setup) +- [Reconfiguration](#reconfiguration) +- [Known issues](#known-issues) +- [Frequently Asked Questions](#frequently-asked-questions) + - [Why does my calendar events say `Reserved` instead of the guest's name?](#why-does-my-calendar-events-say-reserved-instead-of-the-guests-name) + - [Where can I find my rental calendar's `ics` URL?](#where-can-i-find-my-rental-calendars-ics-url) + - [How do I use custom calendars?](#how-do-i-use-custom-calendars) + - [Automation Examples](#automation-examples) ## Features -- Ingests ICS calendars from any HTTPS source as long as it's a text/calendar - file -- Configurable refresh rate from as often as possible to once per day (default - every 2 minutes) -- Define checkin/checkout times which will be added to all calendar entries - that are all day events -- Ability to ignore 'Blocked' and 'Not available' events -- Creates a customizable number of event sensors that are the current and - upcoming events - - sensor.rental_control_my_calendar_event_0 - - sensor.rental_control_my_calendar_event_1 - - sensor.rental_control_my_calendar_event_2 - - (...) -- Creates a calendar-entry that can be used with calendar cards - - calendar.rental_control_my_calendar -- Calendars can have their own timezone definition that is separate from the - Home Assitant instance itself. This is useful for managing properties that are - in a different timezone from where Home Assistant is -- Events can have a custom prefix added to them to help differentiate between - entities if more than one calendar is being tracked in an instance -- Forcing a calendar refresh is currently possible by submitting a - configuration change -- Optional code length starting at 4 digits (requires even number of digits) -- 3 door code generators are available: - - A check-in/out date based 4 digit (or greater) code using the check-in - day combined with the check-out day (default and fallback in the case - another generator fails to produce a code) - - Codes can can optionally be regenerated if the reservation start or - end dates are at least 1 day in future - - A random 4 digit (or greater) code based on the event description - - The last 4 digits of the phone number. This only works properly if the - event description contains '(Last 4 Digits): ' or 'Last 4 Digits: ' - followed quickly by a 4 digit number. This is the most stable, but only - works if the event descriptions have the needed data. The previous two - methods can have the codes change if the event makes changes to length - or to the description. -- All events will get a code associated with it. In the case that the criteria - to create the code are not fulfilled, then the check-in/out date based - method will be used as a fallback -- Each event has dynamically added attributes which consist of extracted - information if available in the event description. The following attributes - now get added: - - Last four -- the last 4 digits of the phone number of the booking guest - - Number of guests -- the number of guests in the reservation - - Guest email -- the email of the booking guest - - Phone number -- the phone number of the booking guest - - Reservation url -- the URL to the reservation -- Integration with [Keymaster](https://github.com/FutureTense/keymaster) to - control door codes matched to the number of events being tracked -- Custom calendars are supported as long as they provide a valid ICS file via - an HTTPS connection. - - Rental Events should be created as all day events (which is how all of - the rental platforms provide events) - - Maintenance style events should be created with start and end times - - The event Summary (aka event title) _may_ contiain the word Reserved. - This will cause the slot name to be generated in one of two ways: - - The word Reserved is followed by ' - ' and then something else, the - something else will be used - - The word Reserved is _not_ followed by ' - ' then the full slot will - be used - - The Summary contains nothing else _and_ the Details contain - something that matches an Airbnb reservation identifier of - `[A-Z][A-Z0-9]{9}` that is a capital alphabet letter followed by 9 - more characters that are either capital alphabet letters or numbers, - then the slot will get this - - If the the Summary is _just_ Reserved and there is no Airbnb code in - the Description, then the event will be ignored for purposes of - managing a lock code. - - Technically any of the othe supported platform event styles for the - Summary can be used and as long as the Summary conforms to it. - - The best Summary on a manual calendar is to use your guest name. The - entries do need to be unique over the sensor count worth of events - or Rental Control will run into issues. - - Additional information can be provided in the Description of the event - and it will fill in the extra details in the sensor. - - Phone numbers for use in generating door codes can be provided in - one of two ways - - A line in the Description matching this regular expression: - `\(?Last 4 Digits\)?:\s+(\d{4})` -- This line will always take - precedence for generating a door code based on last 4 digits. - - A line in the Description matching this regular expression: - `Phone(?: Number)?:\s+(\+?[\d\. \-\(\)]{9,})` which will then - have the "air" squeezed out of it to extract the last 4 digits - in the number - - Number of guests - - A line in the Description that matches: `Guests:\s+(\d+)$` - - Alternatively, the following lines will be added together to get - the data: - - `Adults:\s+(\d+)$` - - `Children:\s+(\d+)$` - - Email addresses can be extracted from the Description by matching - against: `Email:\s+(\S+@\S+)` - - Reservation URLS will match against the first (and hopefully only) - URL in the Description +- Ingests ICS calendars from any HTTPS source as long as it's a text/calendar + file +- Configurable refresh rate from as often as possible to once per day (default + every 2 minutes) +- Define checkin/checkout times which will be added to all calendar entries + that are all day events +- Ability to ignore 'Blocked' and 'Not available' events +- Creates a customizable number of event sensors that are the current and + upcoming events + - sensor.rental_control_my_calendar_event_0 + - sensor.rental_control_my_calendar_event_1 + - sensor.rental_control_my_calendar_event_2 + - (...) +- Creates a calendar-entry that can be used with calendar cards + - calendar.rental_control_my_calendar +- Calendars can have their own timezone definition that is separate from the + Home Assitant instance itself. This is useful for managing properties that are + in a different timezone from where Home Assistant is +- Events can have a custom prefix added to them to help differentiate between + entities if more than one calendar is being tracked in an instance +- Forcing a calendar refresh is currently possible by submitting a + configuration change +- Optional code length starting at 4 digits (requires even number of digits) +- 3 door code generators are available: + - A check-in/out date based 4 digit (or greater) code using the check-in + day combined with the check-out day (default and fallback in the case + another generator fails to produce a code) + - Codes can can optionally be regenerated if the reservation start or + end dates are at least 1 day in future + - A random 4 digit (or greater) code based on the event description + - The last 4 digits of the phone number. This only works properly if the + event description contains '(Last 4 Digits): ' or 'Last 4 Digits: ' + followed quickly by a 4 digit number. This is the most stable, but only + works if the event descriptions have the needed data. The previous two + methods can have the codes change if the event makes changes to length + or to the description. +- All events will get a code associated with it. In the case that the criteria + to create the code are not fulfilled, then the check-in/out date based + method will be used as a fallback +- Each event has dynamically added attributes which consist of extracted + information if available in the event description. The following attributes + now get added: + - Last four -- the last 4 digits of the phone number of the booking guest + - Number of guests -- the number of guests in the reservation + - Guest email -- the email of the booking guest + - Phone number -- the phone number of the booking guest + - Reservation url -- the URL to the reservation +- Integration with [Keymaster](https://github.com/FutureTense/keymaster) to + control door codes matched to the number of events being tracked +- Custom calendars are supported as long as they provide a valid ICS file via + an HTTPS connection. + - Rental Events should be created as all day events (which is how all of + the rental platforms provide events) + - Maintenance style events should be created with start and end times + - The event Summary (aka event title) _may_ contiain the word Reserved. + This will cause the slot name to be generated in one of two ways: + - The word Reserved is followed by ' - ' and then something else, the + something else will be used + - The word Reserved is _not_ followed by ' - ' then the full slot will + be used + - The Summary contains nothing else _and_ the Details contain + something that matches an Airbnb reservation identifier of + `[A-Z][A-Z0-9]{9}` that is a capital alphabet letter followed by 9 + more characters that are either capital alphabet letters or numbers, + then the slot will get this + - If the the Summary is _just_ Reserved and there is no Airbnb code in + the Description, then the event will be ignored for purposes of + managing a lock code. + - Technically any of the othe supported platform event styles for the + Summary can be used and as long as the Summary conforms to it. + - The best Summary on a manual calendar is to use your guest name. The + entries do need to be unique over the sensor count worth of events + or Rental Control will run into issues. + - Additional information can be provided in the Description of the event + and it will fill in the extra details in the sensor. + - Phone numbers for use in generating door codes can be provided in + one of two ways + - A line in the Description matching this regular expression: + `\(?Last 4 Digits\)?:\s+(\d{4})` -- This line will always take + precedence for generating a door code based on last 4 digits. + - A line in the Description matching this regular expression: + `Phone(?: Number)?:\s+(\+?[\d\. \-\(\)]{9,})` which will then + have the "air" squeezed out of it to extract the last 4 digits + in the number + - Number of guests + - A line in the Description that matches: `Guests:\s+(\d+)$` + - Alternatively, the following lines will be added together to get + the data: + - `Adults:\s+(\d+)$` + - `Children:\s+(\d+)$` + - Email addresses can be extracted from the Description by matching + against: `Email:\s+(\S+@\S+)` + - Reservation URLS will match against the first (and hopefully only) + URL in the Description ## Installation @@ -150,58 +150,58 @@ Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.hom The integration is set up using the GUI. -- Press the following button to install the `Rental Control` integration - [![Open your Home Assistant instance and start setting up a new +- Press the following button to install the `Rental Control` integration + [![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=rental_control) -- Follow the prompts and then press `OK` on the question about installing - `Rental Control` -- Enter a name for the calendar, and the calendar's `ics` URL (see FAQ) -- By default it will set up 5 sensors for the 5 nex upcoming events - (sensor.rental_control\_\\_event_0 ~ 4). You can adjust this - to add more or fewer sensors -- The calendar refresh rate defaults to every 2 minutes but can be set to 0 - for as often as possible (roughly every 30 seconds) to once per day (1440). - This is adjustable in minute increments -- The integration will only consider events with a start time 365 days (1 year) - into the future by default. This can also be adjusted when adding a new - calendar -- Set your checkin and checkout times. All times are in 24 hour format. These - times will be added to the calendar events. If the events come in with times - already attached they _will_ be overwritten (most rental hosting platforms - only provide day in / day out in the events) -- For configuration managing a Keymaster controlled lock, make sure that you - have defined the lock during initial setup and that you have the starting - slot set correctly for the integration. - - - It is _very_ important that you have Keymaster fully working before - trying to utilize the slot management component of Rental Control. - - **NOTE:** The Keymaster slots that are defined as being managed will be - completely taken control of by Rental Control. Any data in the slots - will be overwritten by Rental Control when it takes over the slot unless - it matches event data for the calendar. - - The following portions of a Keymaster slot will influence (that is - override) data in the calendar or event sensor: - - Checkin/out TIME (not date) will update the calendar event and also - the sensor tracked information. **NOTE:** If you are using a - timezone that is _not_ the system timezone on your calendar, you - will likely run into weird and unexpected issues as that is not - presently supported! - - Door code - by default when the slot is updated by the integration - the code that is extracted / created by the sensor will be used. If, - however, you have a need to override the code you may do so after - the slot has been updated. This is useful if you have a non-managed - slot that has the same door code (or starting code, typically first - 4 digits) that is the generated code and thus causing the slot to - not function properly +- Follow the prompts and then press `OK` on the question about installing + `Rental Control` +- Enter a name for the calendar, and the calendar's `ics` URL (see FAQ) +- By default it will set up 5 sensors for the 5 nex upcoming events + (sensor.rental_control\_\\_event_0 ~ 4). You can adjust this + to add more or fewer sensors +- The calendar refresh rate defaults to every 2 minutes but can be set to 0 + for as often as possible (roughly every 30 seconds) to once per day (1440). + This is adjustable in minute increments +- The integration will only consider events with a start time 365 days (1 year) + into the future by default. This can also be adjusted when adding a new + calendar +- Set your checkin and checkout times. All times are in 24 hour format. These + times will be added to the calendar events. If the events come in with times + already attached they _will_ be overwritten (most rental hosting platforms + only provide day in / day out in the events) +- For configuration managing a Keymaster controlled lock, make sure that you + have defined the lock during initial setup and that you have the starting + slot set correctly for the integration. + + - It is _very_ important that you have Keymaster fully working before + trying to utilize the slot management component of Rental Control. + - **NOTE:** The Keymaster slots that are defined as being managed will be + completely taken control of by Rental Control. Any data in the slots + will be overwritten by Rental Control when it takes over the slot unless + it matches event data for the calendar. + - The following portions of a Keymaster slot will influence (that is + override) data in the calendar or event sensor: + - Checkin/out TIME (not date) will update the calendar event and also + the sensor tracked information. **NOTE:** If you are using a + timezone that is _not_ the system timezone on your calendar, you + will likely run into weird and unexpected issues as that is not + presently supported! + - Door code - by default when the slot is updated by the integration + the code that is extracted / created by the sensor will be used. If, + however, you have a need to override the code you may do so after + the slot has been updated. This is useful if you have a non-managed + slot that has the same door code (or starting code, typically first + 4 digits) that is the generated code and thus causing the slot to + not function properly ## Reconfiguration This integration supports reconfiguration after initial setup -- Press this button [![Open your Home Assistant instance and show an +- Press this button [![Open your Home Assistant instance and show an integration.](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration/?domain=rental_control) -- Select the calendar and then select `Configure` -- Reconfigure as if you were setting it up for the first time +- Select the calendar and then select `Configure` +- Reconfigure as if you were setting it up for the first time **NOTE:** Changes may not be picked up right away. The default update cycle of the calendar is to check for updates every 2 minutes and events are refreshed @@ -228,9 +228,9 @@ that rather than `Reserved` in calendar events. Each provider has slightly different instructions: -- [AirBnB](https://www.airbnb.com/help/article/99) -- [VRBO](https://help.vrbo.com/articles/Export-your-reservation-calendar) -- [Host Tools](https://help.hosttools.com/en/articles/5128627-how-do-i-export-an-ical-link-from-host-tools) +- [AirBnB](https://www.airbnb.com/help/article/99) +- [VRBO](https://help.vrbo.com/articles/Export-your-reservation-calendar) +- [Host Tools](https://help.hosttools.com/en/articles/5128627-how-do-i-export-an-ical-link-from-host-tools) ### How do I use custom calendars? @@ -245,23 +245,23 @@ slot management. Data that will be pulled from the Description of the event (and the match keys): -- Phone numbers for use in generating door codes can be provided in one of two - ways - - A line in the Description matching this regular expression: - `\(?Last 4 Digits\)?:\s+(\d{4})` -- This line will always take - precedence for generating a door code based on last 4 digits. - - A line in the Description matching this regular expression: - `Phone(?: Number)?:\s+(\+?[\d\. \-\(\)]{9,})` which will then have the - "air" squeezed out of it to extract the last 4 digits in the number -- Number of guests - - A line in the Description that matches: `Guests:\s+(\d+)$` - - Alternatively, the following lines will be added together to get the data: - - `Adults:\s+(\d+)$` - - `Children:\s+(\d+)$` -- Email addresses can be extracted from the Description by matching against: - `Email:\s+(\S+@\S+)` -- Reservation URLS will match against the first (and hopefully only) URL in - the Description +- Phone numbers for use in generating door codes can be provided in one of two + ways + - A line in the Description matching this regular expression: + `\(?Last 4 Digits\)?:\s+(\d{4})` -- This line will always take + precedence for generating a door code based on last 4 digits. + - A line in the Description matching this regular expression: + `Phone(?: Number)?:\s+(\+?[\d\. \-\(\)]{9,})` which will then have the + "air" squeezed out of it to extract the last 4 digits in the number +- Number of guests + - A line in the Description that matches: `Guests:\s+(\d+)$` + - Alternatively, the following lines will be added together to get the data: + - `Adults:\s+(\d+)$` + - `Children:\s+(\d+)$` +- Email addresses can be extracted from the Description by matching against: + `Email:\s+(\S+@\S+)` +- Reservation URLS will match against the first (and hopefully only) URL in + the Description An example calendar entry with all of this data might look like this: @@ -289,7 +289,7 @@ Reservation URL: https://www.example.com/reservation/123456789 Here are some examples of automations that can be done with Rental Control -- Manage thermostat for guests and between guests +- Manage thermostat for guests and between guests ```yaml alias: Manage Thermostat for Guests mode: single diff --git a/info.md b/info.md index dd3cfaa..ec8c22f 100644 --- a/info.md +++ b/info.md @@ -14,168 +14,168 @@ calendars and sensors to go with them related to managing rental properties. # Table of Contents -- [Features](#features) -- [Setup](#setup) -- [Reconfiguration](#reconfiguration) -- [Known issues](#known-issues) -- [Frequently Asked Questions](#frequently-asked-questions) - - [Why does my calendar events say `Reserved` instead of the guest's name?](#why-does-my-calendar-events-say-reserved-instead-of-the-guests-name) - - [Where can I find my rental calendar's `ics` URL?](#where-can-i-find-my-rental-calendars-ics-url) - - [How do I use custom calendars?](#how-do-i-use-custom-calendars) - - [Automation Examples](#automation-examples) +- [Features](#features) +- [Setup](#setup) +- [Reconfiguration](#reconfiguration) +- [Known issues](#known-issues) +- [Frequently Asked Questions](#frequently-asked-questions) + - [Why does my calendar events say `Reserved` instead of the guest's name?](#why-does-my-calendar-events-say-reserved-instead-of-the-guests-name) + - [Where can I find my rental calendar's `ics` URL?](#where-can-i-find-my-rental-calendars-ics-url) + - [How do I use custom calendars?](#how-do-i-use-custom-calendars) + - [Automation Examples](#automation-examples) ## Features -- Ingests ICS calendars from any HTTPS source as long as it's a text/calendar - file -- Configurable refresh rate from as often as possible to once per day (default - every 2 minutes) -- Define checkin/checkout times which will be added to all calendar entries - that are all day events -- Ability to ignore 'Blocked' and 'Not available' events -- Creates a customizable number of event sensors that are the current and - upcoming events - - sensor.rental_control_my_calendar_event_0 - - sensor.rental_control_my_calendar_event_1 - - sensor.rental_control_my_calendar_event_2 - - (...) -- Creates a calendar-entry that can be used with calendar cards - - calendar.rental_control_my_calendar -- Calendars can have their own timezone definition that is separate from the - Home Assitant instance itself. This is useful for managing properties that are - in a different timezone from where Home Assistant is -- Events can have a custom prefix added to them to help differentiate between - entities if more than one calendar is being tracked in an instance -- Forcing a calendar refresh is currently possible by submitting a - configuration change -- Optional code length starting at 4 digits (requires even number of digits) -- 3 door code generators are available: - - A check-in/out date based 4 digit (or greater) code using the check-in - day combined with the check-out day (default and fallback in the case - another generator fails to produce a code) - - Codes can can optionally be regenerated if the reservation start or - end dates are at least 1 day in future - - A random 4 digit (or greater) code based on the event description - - The last 4 digits of the phone number. This only works properly if the - event description contains '(Last 4 Digits): ' or 'Last 4 Digits: ' - followed quickly by a 4 digit number. This is the most stable, but only - works if the event descriptions have the needed data. The previous two - methods can have the codes change if the event makes changes to length - or to the description. -- All events will get a code associated with it. In the case that the criteria - to create the code are not fulfilled, then the check-in/out date based - method will be used as a fallback -- Each event has dynamically added attributes which consist of extracted - information if available in the event description. The following attributes - now get added: - - Last four -- the last 4 digits of the phone number of the booking guest - - Number of guests -- the number of guests in the reservation - - Guest email -- the email of the booking guest - - Phone number -- the phone number of the booking guest - - Reservation url -- the URL to the reservation -- Integration with [Keymaster](https://github.com/FutureTense/keymaster) to - control door codes matched to the number of events being tracked -- Custom calendars are supported as long as they provide a valid ICS file via - an HTTPS connection. - - Rental Events should be created as all day events (which is how all of - the rental platforms provide events) - - Maintenance style events should be created with start and end times - - The event Summary (aka event title) _may_ contiain the word Reserved. - This will cause the slot name to be generated in one of two ways: - - The word Reserved is followed by ' - ' and then something else, the - something else will be used - - The word Reserved is _not_ followed by ' - ' then the full slot will - be used - - The Summary contains nothing else _and_ the Details contain - something that matches an Airbnb reservation identifier of - `[A-Z][A-Z0-9]{9}` that is a capital alphabet letter followed by 9 - more characters that are either capital alphabet letters or numbers, - then the slot will get this - - If the the Summary is _just_ Reserved and there is no Airbnb code in - the Description, then the event will be ignored for purposes of - managing a lock code. - - Technically any of the othe supported platform event styles for the - Summary can be used and as long as the Summary conforms to it. - - The best Summary on a manual calendar is to use your guest name. The - entries do need to be unique over the sensor count worth of events - or Rental Control will run into issues. - - Additional information can be provided in the Description of the event - and it will fill in the extra details in the sensor. - - Phone numbers for use in generating door codes can be provided in - one of two ways - - A line in the Description matching this regular expression: - `\(?Last 4 Digits\)?:\s+(\d{4})` -- This line will always take - precedence for generating a door code based on last 4 digits. - - A line in the Description matching this regular expression: - `Phone(?: Number)?:\s+(\+?[\d\. \-\(\)]{9,})` which will then - have the "air" squeezed out of it to extract the last 4 digits - in the number - - Number of guests - - A line in the Description that matches: `Guests:\s+(\d+)$` - - Alternatively, the following lines will be added together to get - the data: - - `Adults:\s+(\d+)$` - - `Children:\s+(\d+)$` - - Email addresses can be extracted from the Description by matching - against: `Email:\s+(\S+@\S+)` - - Reservation URLS will match against the first (and hopefully only) - URL in the Description +- Ingests ICS calendars from any HTTPS source as long as it's a text/calendar + file +- Configurable refresh rate from as often as possible to once per day (default + every 2 minutes) +- Define checkin/checkout times which will be added to all calendar entries + that are all day events +- Ability to ignore 'Blocked' and 'Not available' events +- Creates a customizable number of event sensors that are the current and + upcoming events + - sensor.rental_control_my_calendar_event_0 + - sensor.rental_control_my_calendar_event_1 + - sensor.rental_control_my_calendar_event_2 + - (...) +- Creates a calendar-entry that can be used with calendar cards + - calendar.rental_control_my_calendar +- Calendars can have their own timezone definition that is separate from the + Home Assitant instance itself. This is useful for managing properties that are + in a different timezone from where Home Assistant is +- Events can have a custom prefix added to them to help differentiate between + entities if more than one calendar is being tracked in an instance +- Forcing a calendar refresh is currently possible by submitting a + configuration change +- Optional code length starting at 4 digits (requires even number of digits) +- 3 door code generators are available: + - A check-in/out date based 4 digit (or greater) code using the check-in + day combined with the check-out day (default and fallback in the case + another generator fails to produce a code) + - Codes can can optionally be regenerated if the reservation start or + end dates are at least 1 day in future + - A random 4 digit (or greater) code based on the event description + - The last 4 digits of the phone number. This only works properly if the + event description contains '(Last 4 Digits): ' or 'Last 4 Digits: ' + followed quickly by a 4 digit number. This is the most stable, but only + works if the event descriptions have the needed data. The previous two + methods can have the codes change if the event makes changes to length + or to the description. +- All events will get a code associated with it. In the case that the criteria + to create the code are not fulfilled, then the check-in/out date based + method will be used as a fallback +- Each event has dynamically added attributes which consist of extracted + information if available in the event description. The following attributes + now get added: + - Last four -- the last 4 digits of the phone number of the booking guest + - Number of guests -- the number of guests in the reservation + - Guest email -- the email of the booking guest + - Phone number -- the phone number of the booking guest + - Reservation url -- the URL to the reservation +- Integration with [Keymaster](https://github.com/FutureTense/keymaster) to + control door codes matched to the number of events being tracked +- Custom calendars are supported as long as they provide a valid ICS file via + an HTTPS connection. + - Rental Events should be created as all day events (which is how all of + the rental platforms provide events) + - Maintenance style events should be created with start and end times + - The event Summary (aka event title) _may_ contiain the word Reserved. + This will cause the slot name to be generated in one of two ways: + - The word Reserved is followed by ' - ' and then something else, the + something else will be used + - The word Reserved is _not_ followed by ' - ' then the full slot will + be used + - The Summary contains nothing else _and_ the Details contain + something that matches an Airbnb reservation identifier of + `[A-Z][A-Z0-9]{9}` that is a capital alphabet letter followed by 9 + more characters that are either capital alphabet letters or numbers, + then the slot will get this + - If the the Summary is _just_ Reserved and there is no Airbnb code in + the Description, then the event will be ignored for purposes of + managing a lock code. + - Technically any of the othe supported platform event styles for the + Summary can be used and as long as the Summary conforms to it. + - The best Summary on a manual calendar is to use your guest name. The + entries do need to be unique over the sensor count worth of events + or Rental Control will run into issues. + - Additional information can be provided in the Description of the event + and it will fill in the extra details in the sensor. + - Phone numbers for use in generating door codes can be provided in + one of two ways + - A line in the Description matching this regular expression: + `\(?Last 4 Digits\)?:\s+(\d{4})` -- This line will always take + precedence for generating a door code based on last 4 digits. + - A line in the Description matching this regular expression: + `Phone(?: Number)?:\s+(\+?[\d\. \-\(\)]{9,})` which will then + have the "air" squeezed out of it to extract the last 4 digits + in the number + - Number of guests + - A line in the Description that matches: `Guests:\s+(\d+)$` + - Alternatively, the following lines will be added together to get + the data: + - `Adults:\s+(\d+)$` + - `Children:\s+(\d+)$` + - Email addresses can be extracted from the Description by matching + against: `Email:\s+(\S+@\S+)` + - Reservation URLS will match against the first (and hopefully only) + URL in the Description ## Setup The integration is set up using the GUI. -- Press the following button to install the `Rental Control` integration - [![Open your Home Assistant instance and start setting up a new +- Press the following button to install the `Rental Control` integration + [![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=rental_control) -- Follow the prompts and then press `OK` on the question about installing - `Rental Control` -- Enter a name for the calendar, and the calendar's `ics` URL (see FAQ) -- By default it will set up 5 sensors for the 5 nex upcoming events - (sensor.rental_control\_\\_event_0 ~ 4). You can adjust this - to add more or fewer sensors -- The calendar refresh rate defaults to every 2 minutes but can be set to 0 - for as often as possible (roughly every 30 seconds) to once per day (1440). - This is adjustable in minute increments -- The integration will only consider events with a start time 365 days (1 year) - into the future by default. This can also be adjusted when adding a new - calendar -- Set your checkin and checkout times. All times are in 24 hour format. These - times will be added to the calendar events. If the events come in with times - already attached they _will_ be overwritten (most rental hosting platforms - only provide day in / day out in the events) -- For configuration managing a Keymaster controlled lock, make sure that you - have defined the lock during initial setup and that you have the starting - slot set correctly for the integration. - - - It is _very_ important that you have Keymaster fully working before - trying to utilize the slot management component of Rental Control. - - **NOTE:** The Keymaster slots that are defined as being managed will be - completely taken control of by Rental Control. Any data in the slots - will be overwritten by Rental Control when it takes over the slot unless - it matches event data for the calendar. - - The following portions of a Keymaster slot will influence (that is - override) data in the calendar or event sensor: - - Checkin/out TIME (not date) will update the calendar event and also - the sensor tracked information. **NOTE:** If you are using a - timezone that is _not_ the system timezone on your calendar, you - will likely run into weird and unexpected issues as that is not - presently supported! - - Door code - by default when the slot is updated by the integration - the code that is extracted / created by the sensor will be used. If, - however, you have a need to override the code you may do so after - the slot has been updated. This is useful if you have a non-managed - slot that has the same door code (or starting code, typically first - 4 digits) that is the generated code and thus causing the slot to - not function properly +- Follow the prompts and then press `OK` on the question about installing + `Rental Control` +- Enter a name for the calendar, and the calendar's `ics` URL (see FAQ) +- By default it will set up 5 sensors for the 5 nex upcoming events + (sensor.rental_control\_\\_event_0 ~ 4). You can adjust this + to add more or fewer sensors +- The calendar refresh rate defaults to every 2 minutes but can be set to 0 + for as often as possible (roughly every 30 seconds) to once per day (1440). + This is adjustable in minute increments +- The integration will only consider events with a start time 365 days (1 year) + into the future by default. This can also be adjusted when adding a new + calendar +- Set your checkin and checkout times. All times are in 24 hour format. These + times will be added to the calendar events. If the events come in with times + already attached they _will_ be overwritten (most rental hosting platforms + only provide day in / day out in the events) +- For configuration managing a Keymaster controlled lock, make sure that you + have defined the lock during initial setup and that you have the starting + slot set correctly for the integration. + + - It is _very_ important that you have Keymaster fully working before + trying to utilize the slot management component of Rental Control. + - **NOTE:** The Keymaster slots that are defined as being managed will be + completely taken control of by Rental Control. Any data in the slots + will be overwritten by Rental Control when it takes over the slot unless + it matches event data for the calendar. + - The following portions of a Keymaster slot will influence (that is + override) data in the calendar or event sensor: + - Checkin/out TIME (not date) will update the calendar event and also + the sensor tracked information. **NOTE:** If you are using a + timezone that is _not_ the system timezone on your calendar, you + will likely run into weird and unexpected issues as that is not + presently supported! + - Door code - by default when the slot is updated by the integration + the code that is extracted / created by the sensor will be used. If, + however, you have a need to override the code you may do so after + the slot has been updated. This is useful if you have a non-managed + slot that has the same door code (or starting code, typically first + 4 digits) that is the generated code and thus causing the slot to + not function properly ## Reconfiguration This integration supports reconfiguration after initial setup -- Press this button [![Open your Home Assistant instance and show an integration.](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration/?domain=rental_control) -- Select the calendar and then select `Configure` -- Reconfigure as if you were setting it up for the first time +- Press this button [![Open your Home Assistant instance and show an integration.](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration/?domain=rental_control) +- Select the calendar and then select `Configure` +- Reconfigure as if you were setting it up for the first time **NOTE:** Changes may not be picked up right away. The default update cycle of the calendar is to check for updates every 2 minutes and events are refreshed @@ -202,9 +202,9 @@ that rather than `Reserved` in calendar events. Each provider has slightly different instructions: -- [AirBnB](https://www.airbnb.com/help/article/99) -- [VRBO](https://help.vrbo.com/articles/Export-your-reservation-calendar) -- [Host Tools](https://help.hosttools.com/en/articles/5128627-how-do-i-export-an-ical-link-from-host-tools) +- [AirBnB](https://www.airbnb.com/help/article/99) +- [VRBO](https://help.vrbo.com/articles/Export-your-reservation-calendar) +- [Host Tools](https://help.hosttools.com/en/articles/5128627-how-do-i-export-an-ical-link-from-host-tools) ### How do I use custom calendars? @@ -219,23 +219,23 @@ slot management. Data that will be pulled from the Description of the event (and the match keys): -- Phone numbers for use in generating door codes can be provided in one of two - ways - - A line in the Description matching this regular expression: - `\(?Last 4 Digits\)?:\s+(\d{4})` -- This line will always take - precedence for generating a door code based on last 4 digits. - - A line in the Description matching this regular expression: - `Phone(?: Number)?:\s+(\+?[\d\. \-\(\)]{9,})` which will then have the - "air" squeezed out of it to extract the last 4 digits in the number -- Number of guests - - A line in the Description that matches: `Guests:\s+(\d+)$` - - Alternatively, the following lines will be added together to get the data: - - `Adults:\s+(\d+)$` - - `Children:\s+(\d+)$` -- Email addresses can be extracted from the Description by matching against: - `Email:\s+(\S+@\S+)` -- Reservation URLS will match against the first (and hopefully only) URL in - the Description +- Phone numbers for use in generating door codes can be provided in one of two + ways + - A line in the Description matching this regular expression: + `\(?Last 4 Digits\)?:\s+(\d{4})` -- This line will always take + precedence for generating a door code based on last 4 digits. + - A line in the Description matching this regular expression: + `Phone(?: Number)?:\s+(\+?[\d\. \-\(\)]{9,})` which will then have the + "air" squeezed out of it to extract the last 4 digits in the number +- Number of guests + - A line in the Description that matches: `Guests:\s+(\d+)$` + - Alternatively, the following lines will be added together to get the data: + - `Adults:\s+(\d+)$` + - `Children:\s+(\d+)$` +- Email addresses can be extracted from the Description by matching against: + `Email:\s+(\S+@\S+)` +- Reservation URLS will match against the first (and hopefully only) URL in + the Description An example calendar entry with all of this data might look like this: @@ -263,7 +263,7 @@ Reservation URL: https://www.example.com/reservation/123456789 Here are some examples of automations that can be done with Rental Control -- Manage thermostat for guests and between guests +- Manage thermostat for guests and between guests ```yaml alias: Manage Thermostat for Guests mode: single