-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
7 changed files
with
224 additions
and
129 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -8,12 +8,13 @@ A lightweight app that will operate your MyQ connected garage doors based on the | |
| - [How to use](#how-to-use) | ||
| - [Docker](#docker) | ||
| - [Supported Environment Variables](#supported-environment-variables) | ||
| - [Portable App](#portable-app) | ||
| - [Notes](#notes) | ||
| - [Serials](#serials) | ||
| - [Geofence Radii](#geofence-radii) | ||
| - [Custom Geofence vs TeslaMate Geofence](#custom-geofence-vs-teslamate-geofence) | ||
| - [Triggers](#triggers) | ||
| - [Geofence Types](#geofence-types) | ||
| - [Circular Geofence](#circular-geofence) | ||
| - [TeslaMate Defined Geofence](#teslamate-defined-geofence) | ||
| - [Polygon Geofence](#polygon-geofence) | ||
| - [Operation Cooldown](#operation-cooldown) | ||
| - [Credits](#credits) | ||
|
|
||
| <!-- /TOC --> | ||
|
|
@@ -23,7 +24,7 @@ This app uses the MQTT broker bundled with [TeslaMate](https://github.com/adrian | |
|
|
||
| ## How to use | ||
| ### Docker | ||
| There is now a docker image available and will be the only supported release type going forward. You will need to download the [config.example.yml](https://github.com/brchri/tesla-youq/blob/main/config.example.yml) file and edit it appropriately, and then mount it to the container at runtime. For example: | ||
| This app is provided as a docker image. You will need to download the [config.example.yml](https://github.com/brchri/tesla-youq/blob/main/config.example.yml) file and edit it appropriately, and then mount it to the container at runtime. For example: | ||
|
|
||
| ```bash | ||
| docker run \ | ||
|
|
@@ -39,7 +40,6 @@ Or you can use a docker compose file like this: | |
| ```yaml | ||
| version: '3.8' | ||
| services: | ||
|
|
||
| tesla-youq: | ||
| image: brchri/tesla-youq:latest | ||
| container_name: tesla-youq | ||
|
|
@@ -65,22 +65,6 @@ The following Docker environment variables are supported but not required. | |
| | `TESTING` | Bool | Will perform all functions *except* actually operating garage door, and will just output operation *would've* happened | | ||
| | `TZ` | String | Sets timezone for container | | ||
|
|
||
| ### Portable App | ||
| Deprecated after release `v0.1.0`. Please refer to the [Docker](#docker) instructions for more recent versions. For earlier versions, continue on. | ||
|
|
||
| Download the release zip containing the binary and sample `config.example.yml` file. Edit the yml file to have the settings appropriate for your use case (see Notes section below for more info). | ||
|
|
||
| Open a terminal (e.g. bash on linux or cmd/powershell on Windows), `cd` to the directory containing the downloaded binary, and execute it with a `-c` flag to point to your config file. Here's an example: | ||
|
|
||
| `tesla-youq -c /etc/tesla-youq/config.yml` | ||
|
|
||
| You can also set `CONFIG_FILE` environment variable to pass the config file directory: | ||
|
|
||
| ```bash | ||
| export CONFIG_FILE=/etc/tesla-youq/config.yml | ||
| tesla-youq | ||
| ``` | ||
|
|
||
| ## Notes | ||
|
|
||
| ### Serials | ||
|
|
@@ -100,16 +84,79 @@ Portable app: | |
|
|
||
| `[email protected] MYQ_PASS=supersecretpass tesla-youq -d` | ||
|
|
||
| ### Geofence Radii | ||
| There are separate geofence radii for opening and closing a garage. This is to facilitate closing the garage more immediately when leaving, but opening it sooner so it's already open when you arrive. This is useful due to delays in receiving positional data from the Tesla API. The recommendation is to set a larger value for `open_radius` and a smaller one for `close_radius`, but this is up to you. | ||
| ### Geofence Types | ||
| You can define 3 different types of geofences to trigger garage operations. You must configure *one and only one* geofence type for each garage door. Each geofence type has separate "open" and "close" configurations (though you can set them to have the same values). This is useful for situations where you might want a smaller geofence that closes the door so you can visually confirm it's closing, but you want a larger geofence that opens the door so it will start sooner and be fully opened when you actually arrive. | ||
|
|
||
| #### Circular Geofence | ||
| This is the simplist geofence to configure, which is just a circular fence. You provide a latitude and longitude coordinate as the center point, and the distance from the center point to trigger the garage action (in kilometers). You can use a tool such as [free map tools](https://www.freemaptools.com/radius-around-point.htm) to determine what the center latitude and longitude coordinates are, as well as how big your want your radius to be. An example of a garage door configured with this type of geofence would look like this: | ||
|
|
||
| ### Custom Geofence vs TeslaMate Geofence | ||
| As of `v0.1.2`, you can either define your own geofence triggers in the `config.yml` file (using `location`, `close_radius`, and `open_radius` parameters), or you can reference the geofences that can be created directly through the TeslaMate web UI (using `trigger_close_geofence` and `trigger_open_geofence` parameters). However, it should be noted that if using the Geofences defined in the TeslaMate web UI, Tesla-YouQ will subscribe to the Geofence topic for updates to trigger garage door actions. This topic does not appear to be updated in realtime, but rather in a polling manner, which can cause significant delays in updates that trigger a garage close action. It also does not (currently) allow for overlapping geofence definitions. It is therefore recommended to define your own geofences in the `config.yml` file rather than relying on TeslaMate's geofencing feature. See [this PR](https://github.com/brchri/tesla-youq/pull/12) for more detailed observations. | ||
| ```yaml | ||
| garage_doors: | ||
| - circular_geofence: | ||
| center: | ||
| lat: 48.858195 | ||
| lng: 2.294689 | ||
| close_distance: .03503 | ||
| open_distance: .23138 | ||
| myq_serial: myq_serial_1 | ||
| cars: | ||
| - teslamage_car_id: 1 | ||
| ``` | ||
|
|
||
| #### TeslaMate Defined Geofence | ||
| You can choose to use geofences defined in TeslaMate. To define these geofences, go to your TeslaMate page and click `Geo-Fences` at the top, and create a new fence (or reference your existing fences). Some notes about using TeslaMate Defined Geofences: | ||
| * TeslaMate does not update its geofence calculations in realtime. *This will cause delays in your garage door operations*. | ||
| * You cannot define overlapping geofences in TeslaMate, as it will cause TeslaMate to behave unexpectedly as it cannot determine which Geofence you should be in when you're in more than one. This means you cannot define separate open and close geofences and should only use a single geofence. | ||
| * You must configure TeslaMate to have a "default" geofence when no defined geofences apply. You do this by configuring an environment variable for TeslaMate, such as `DEFAULT_GEOFENCE=not_home`. | ||
| * In general, it is not recommended to use this method as it is the least reliable due to how TeslaMate updates the Geofence data. | ||
|
|
||
| An example of a garage door configured with this type of geofence would look like this: | ||
|
|
||
| ```yaml | ||
| garage_doors: | ||
| - teslamate_geofence: | ||
| close_trigger: | ||
| from: home | ||
| to: not_home | ||
| open_trigger: | ||
| from: not_home | ||
| to: home | ||
| myq_serial: myq_serial_1 | ||
| cars: | ||
| - teslamage_car_id: 1 | ||
| ``` | ||
|
|
||
| #### Polygon Geofence | ||
| This is the most customizable method of defining a geofence, which allows you to specifically define a polygonal geofence using a list of latitude and longitude coordinates. You can use a tool like [geojson.io](https://geojson.io/) to assist with creating a geofence and providing latitude and longitude points. An example of a garage door configured with this type of geofence would look like this: | ||
|
|
||
| ### Triggers | ||
| Tesla-YouQ allows you to define separate geofence radii for open and close triggers. This means that there can be an overlap where, for example, you're leaving home and cross the "close door" threshold, which shares a space with the "open door" zone for when you return, as the "open door" zone is larger since you want the garage to start opening sooner so it's ready when you arrive. To account for this and remove the possibility of flapping, The close door event will only trigger when you go from *inside* the "close door" geofence and move *outside* it, indicating you are moving away from the garage. Conversely, the open door event will only trigger when you go from *outside* the "open door" geofence and move *inside* it. | ||
| ```yaml | ||
| garage_doors: | ||
| - polygon_geofence: | ||
| open: | ||
| - lat: 48.8580729 | ||
| lng: 2.2924089 | ||
| - lat: 48.8553411 | ||
| lng: 2.296679 | ||
| - lat: 48.8585317 | ||
| lng: 2.2964001 | ||
| - lat: 48.8580729 | ||
| lng: 2.2924089 | ||
| close: | ||
| - lat: 48.8580603 | ||
| lng: 2.2924089 | ||
| - lat: 48.8553411 | ||
| lng: 2.296679 | ||
| - lat: 48.8585317 | ||
| lng: 2.2964001 | ||
| - lat: 48.8580729 | ||
| lng: 2.2924089 | ||
| myq_serial: myq_serial_1 | ||
| cars: | ||
| - teslamage_car_id: 1 | ||
| ``` | ||
|
|
||
| There is also a configurable "operation cooldown" property in the `global` section of the `config.yml` file, which will prevent any operations against a recently operated door until the number of minutes specified has passed. This can be set to 0 if you don't want any operation cooldown. | ||
| ### Operation Cooldown | ||
| There's a configurable `cooldown` parameter in the `config.yml` file that will allow you to specify how many minutes Tesla-YouQ should wait after operating a garage door before it attemps any further operations. This helps prevent potential flapping if that's a concern. | ||
|
|
||
| ## Credits | ||
| * [TeslaMate](https://github.com/adriankumpf/teslamate) | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| # This config file is meant to serve as an example of how simple the config file can be if you don't need the extra options | ||
| # To keep it clean, it won't explain any parameters; please refer to the full config.example.yml file for parameter explanations | ||
|
|
||
| global: | ||
| mqtt_host: localhost | ||
| mqtt_port: 1883 | ||
| cooldown: 5 | ||
| myq_email: [email protected] | ||
| myq_pass: super_secret_password | ||
|
|
||
| garage_doors: | ||
| - circular_geofence: | ||
| center: | ||
| lat: 48.858195 | ||
| lng: 2.294689 | ||
| close_distance: .03503 | ||
| open_distance: .23138 | ||
| myq_serial: myq_serial_1 | ||
| cars: | ||
| - teslamage_car_id: 1 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.