TESLA HS4 Vehicles Plug In For Homeseer User Guide

TESLA HS4 Vehicles Plug In For Homeseer User Guide

TERMS & CONDITIONS

Tesla has not officially published their API, though it has been documented by unrelated entities and is in use by many non-Tesla projects. This means that if Tesla changes their API, work will have to be done on this plugin to make it compatible, and that there is a chance the changes could render it inoperable. These changes are done without my knowledge or control, and your purchase/use of this plug-in is as-is and at your own risk. That being said, I own a Tesla and will always endeavor to resolve any issues created by Tesla’s changes whenever possible!

While there are currently no specific limits published, as with any API, excessive activity may result in negative actions being taken on your account.

The ability to control items like door locks, trunks, and initiate remote driving of a Tesla vehicle without a key present is also a known risk that you accept when controlling your vehicle remotely and could result in theft or loss of property.

By activating this plugin in your HomeSeer software, you acknowledge this risk and agree to indemnify and hold harmless the developer of this plugin (Steve Hill), HomeSeer Technologies, and any other third-party plugin developers from any damages (including but not limited to financial, physical injury, time spent, opportunity cost, loss of account privileges, and the inability to control your vehicle or other connected devices).

Tesla™ is a trademark of Tesla, Inc.

OVERVIEW

The skWare Tesla Vehicles Plug-In for HomeSeer provides you with a way to monitor and control your Tesla vehicle from HomeSeer.

INSTALLATION

This Plug-In is installed using the built-in updater capability of Homeseer. New installations include the binaries and supporting files needed to run the Plug-In, and updates will replace any of those items that have changed.

Before you set it up, you must create your account with Tesla and you must have a vehicle registered to your
account. If you can see your vehicle in the official Tesla mobile app, you should also be able to see it in this plugin once your account is connected.

SYSTEM REQUIREMENTS

The Tesla Vehicles Plug-In for HomeSeer HS4 runs on both Windows and Linux installations of HS4 and has been tested with version 4.2.19.0.

Due to modern network security restrictions, this plugin is not supported on Windows XP, and for Linux/Zee users, it requires Mono version 4.8.1 or higher.

You must have a Tesla vehicle connected to the account you’re using. To date, this plugin has been developed and tested with the following models:

• Tesla Model S
• Tesla Model 3*
• Tesla Model X
• Tesla Model Y

Other models are also expected to work, but there are features of those vehicles that the author cannot fully test.
Please report any issues (or successes) on the forums so they can be resolved/documented.

POWER MANAGEMENT

In order to minimize “vampire drain” (the loss of range and battery levels over time when not driving), it is important to allow your car to sleep when not in use. When the car is asleep, no data (other than whether it is “online” or “asleep”) is available without waking it up.

One of the challenges with these vehicles is that both the amount of time it takes to wake up a sleeping car and the amount of time it takes the car to go into sleep mode are unpredictable. The plugin has been designed to give you options that help control the way in which it interacts with your vehicle and to allow you to minimize the drain caused by polling it. These options are detailed in Configuration below, but as you use the plugin, please keep in mind the variability of the “wake” process (which may sometimes fail) and for how long it takes the car to fall asleep – there is no command to tell it to do so, it’s simply a matter of not disturbing it for as long as it takes.

See https://support.teslafi.com/knowledge-bases/2/articles/161-my-vehicle-is- not-sleeping for more info on the challenges with getting these cars to go to sleep in general.

When the car is awake (or when it’s in use, if the vehicle option to “keep awake while charging/driving” is enabled), the plugin will keep updating the data, but once those conditions are no longer met, it will stop updating and only check to see if it’s asleep for a period of time. Once it goes to sleep, it simply monitors to see when it’s awake again so it can keep updating. Note that the “Update” button on the Status device will force the car awake to do the update, after which it will allow the car to go back to sleep before another schedule polling happens. (If the “Wake to Update” options is turned on, it will always attempt to wake the car with every polling interval.)

Of course, you can use HomeSeer events to create your own polling process as well by forcing updates at specific times or based on other conditions, too.

CONFIGURATION

After installing the plug-in, a new “Tesla Vehicles” menu item can be found under “Plug-Ins” menu in the Homeseer browser interface. The “Configuration” item will take you to the configuration page, where you are able to define your devices and setup additional options for the plug-in.

The first step is to accept the plug-in Terms & Conditions (see above) and provide your account details. The Tesla
API requires a token which cannot be generated using the web-based architecture of Homeseer. Fortunately there are mobile apps that can be used to generate these tokens, such as Tesla Tokens on the Google Play Store or Tesla
Token on the Apple App Store. Disclaimer: This plugin nor its author have any affiliation nor make any warranty regarding these or any similar applications.

The Status device will alert you if your authentication is failing by changing to “Login Failed” so you can create an event based on this value to provide a notification if this occurs.

Because of the need to use mobile applications to generate the tokens, it is recommended that the initial setup is performed via the Homeseer web site from your mobile device in order to use copy/paste.

Once your account is connected, you will have the option to reset your tokens from the Settings page if needed. Reauthorizing your account may be necessary from time to time.

The “Settings” page also provides the control over plug-in behavior and logging output.

The Account Options allows you to replace the Access and Refresh Tokens, shows the current authorization status, and provides a “Validate Tokens” button to test the provided tokens. In order to use the optional “Streaming” (COMING SOON) interface to the vehicle, the account email address must be provided. Likewise, in order to use the optional “Remote Start” capability, the account password must be provided.

This plugin also provides the ability to define geofences for locations that are set based on the latitude and
longitude of the vehicle. In order to use this capability, a Google Maps API Key must be provided. See Appendix 2
for details on the process to create this key.
Optional log data can be recorded in a stand-alone Plugin log (which can be found in the “Logs” directory of your

Homeseer installation). Please note that this logging level should only be used when troubleshooting or sending in
for support as it can have a significant impact on performance. This option also enables a special “Debug” item
under the “Plugins > Tesla Vehicles” menu that may be helpful in diagnosing issues.

The “Download Log File” and “Clear Log File” buttons on this page make it easier to manage the plugin log files on
your server, as you are no longer required to access the file system to get them when requested for support.

VEHICLE CONFIGURATION

Once your account is connected, the “Vehicles” Page will be added to the plug- in menu, where you can add one or more vehicles to be controlled by Homeseer, edit the settings for a single vehicle, or remove a connected vehicle.

The “Plugin Permissions” section provides control over which types of actions are allowed by the plugin and is where the PINs for Speed Limit Mode and Valet Mode can be defined.

The “Vampire Drain Control” section is where most of the options related to the Power Management settings are managed.

The polling interval specifies how often to retrieve the current data for this vehicle. A value of 120 seconds or
higher is required.

The “Update Frequency” controls how much time must pass between update requests. A value of 15 seconds or
higher is required. Requests made within less time than this will result in a “Waiting for update…” status.

You may choose whether to wake the vehicle on every update (high drain, not recommended) or when charging, and when attempting to wake the vehicle, you can specify how many times to retry and how long to wait between each attempt.

The final two options in this section define how long, after stopping, to wait before starting to ignore the vehicle so it will sleep, as well as how long (in minutes) to wait before giving up and checking on the vehicle again. These settings are important because a short stop of the vehicle could get caught in the “Waiting to Sleep” state even though it’s started driving again.

The final section under Vehicle Configuration is the list of Homeseer Features to create for this vehicle. There are many possible options, and not all may be useful in your situation, so rather than cluttering up the Homeseer interface, you can only choose to enable the features you desire. See below for a full list of the options under each dropdown.

Note that some options may not be available for your vehicle and will not result in devices being created even if selected. Homeseer Features are added following the first update after changing these values.

In addition to the Parent device, three mandatory features are always created:

• A “Controls” device with Flash, Honk, Start (if allowed), Vent Windows (if allowed), Close Windows (Model 3/Y only), and Homelink (if allowed) controls.
• A “Wake State” device that shows whether the vehicle is online or asleep, or waiting for a change. This device also has a Wake button.
• The Status device, representing the result of the last command, with an Update button. It also tracks the last command date/time (so the date/time changes even if the status does not).

Here is the full list of other devices and their Device Types:

*Depends on vehicle configuration.
Controllable.
Can be restricted in options.

The “Status Graphics” for this plugin are based entirely on graphics contained within the “\html\TeslaVehicles\images” folder (see Appendix 1). If you prefer different icons, you can replace those (keeping the same name/case/extension) with your own and prevent any recurring or future changes to those “Status Graphics” pairs from reverting the icons to the original settings.

LOCATIONS

If you have configured a Google Maps API Key, there will be a “Locations” menu item available the plugin menu.
This allows you to define geofences that will be used by the “Location” feature to easily trigger events or use as conditions based on the current location of the vehicle.

Adding a new location is accomplished by clicking “Add New Location” then dragging the marker on the map to the desired location. The default location will be the current location of the first vehicle you have added to the plug- in, or in some circumstances may interrogate your browser or use the Google Maps API as a last resort.

The latitude and longitude will change as you move the marker; manually edit the “Radius” option to increase or decrease the size of the area inside the circle.

ACTIONS

This plugin provides the following Actions that can be included in Events:

• Navigate

FUNCTIONS

The following functions are available for use via scripts and the Homeseer “hs.PluginFunction” method.

• Navigate(vehicleID, destination)
  o vehicleID = string ID of the vehicle, found on the Vehicles page
  o destination = string address or coordinates to send to the vehicle

• ScheduleUpdate(vehicleID, seconds)
  o vehicleID = string ID of the vehicle, found on the Vehicles page
  o seconds = number of seconds from now to start the install of a new system update

KNOWN ISSUES

• When using Fahrenheit temperature units, Tesla does some strange math/rounding and the actual value shown in the plugin and vehicle may vary by 1 degree

SUPPORT

Support for the skWare Tesla Vehicles Plug-In for HomeSeer is provided through the standard HomeSeer channels.
The primary mechanism is via the Tesla Vehicles forum on the HomeSeer website. The author can be contacted directly at steve@skware.net.
Links to the documentation and the support forum can be found on the Plugin’s “Docs” page in the Plugin menu.

APPENDIX 1: FILES

The following files are used by the Plug-In. Directories in bold are part of the standard Homeseer installation. Files marked with * are created by the software during usage; all other files are included in the installation.

APPENDIX 2: CREATING A GOOGLE MAPS API KEY

In order to use the “Locations” capability of the plugin, you must provide an Google Maps API key properly configured to allow use of Google’s Services with this plugin.

Step 1: Setup your Google Cloud Account
This can be a new or existing gmail or GSuite account. Visit https://cloud.google.com to get started. You can then click “Start Free” to set up your Google Cloud account if you don’t have one already configured. Simply provide your country, organization needs (“Other” works) and accept the Google Cloud Terms of Service.
The second step is to provide your payment details. This is required, but the usage of the API by this plugin should never exceed the “free” volume allowed each month since it’s only accessed while setting up Locations.

Step 2: Configure the Google Maps Platform
Choose the “Embed Maps” option to start the setup of this feature.

On the very first screen, an API Key will be provided. Copy this value and paste it into the appropriate field on the plugin “Settings” screen. I recommend choosing “Maybe Later” on the prompt to secure the API key so you can use the more detailed configuration documented below.

Step 3: Configure the Credentials

From the Cloud Console, choose Keys & Credentials, then click on the “Maps API Key” that was created for you.

To protect your API key from misuse, you can restrict it to certain APIs or only allow referrals from specific
websites. Note that “IP Address” does not work with this type of API request according to Google, so use the IP of
your server as a “Website” restriction instead and add your IP and, if you choose, include support for access via
MyHS (for example, “192.168.0.128/” and “.homeseer.com/*”).

You can also restrict it to only certain API types by including only:

• Geocoding API
• Geolocation API
• Maps JavaScript API
• Places API

References

• Smart Home Systems For Every Need & Budget | HomeSeer
• Tesla Vehicles (Shill) - HomeSeer Message Board
• My vehicle is not sleeping! / Knowledge base / TeslaFi

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>