Merge pull request #40 from tesla-local-control/iain-dev

INSTALL.md

@@ -21,6 +21,7 @@
 
 ### 1 - Deploy the Container ###
 There are various methods to deploy the container, see the main ones below:
+
 #### Deploy using Command Line ####
 i. Create a tesla_ble_mqtt_docker folder in your user directory and change directory into it:
    ```shell
@@ -34,6 +35,7 @@ ii. Download docker-compose.yml and stack.env from the github repository:
    curl -O https://raw.githubusercontent.com/tesla-local-control/tesla_ble_mqtt_docker/main/stack.env
    ```
 iii. Check docker-compose.yml contents are suitable for your needs. It will be ok as is for most people
+<br /><br />
 iv. Update the environment variables in stack.env according to your needs. As a minimum enter the VIN of your car, and the connection details for your MQTT server. If you want BLE detection enter the BLE MAC address of the car (see below for instructions on how to find this TODO):
   ```shell
   # Mandatory; if multiple VINs separate with , or white space
@@ -76,8 +78,11 @@ iv. Update the environment variables in stack.env according to your needs. As a
   ENABLE_HA_FEATURES=true
   ```
 v. Create the Docker volume: `docker volume create tesla_ble_mqtt`
+<br /><br />
 vi. Create a symbolic link to the environment file: `ln -s stack.env env`
+<br /><br />
 vii. Start the container: `docker compose up -d`
+<br /><br />
 vii. Check the logs `docker logs -f tesla_ble_mqtt`. Typical logs after start up look like this (when DEBUG=false):
   ```
   Configuration Options are:
@@ -104,27 +109,29 @@ vii. Check the logs `docker logs -f tesla_ble_mqtt`. Typical logs after start up
   Launching listen_to_mqtt
   ```
 #### Deploy using Dockerfile ####
-See instructions here: [INSTALL-WITH-DOCKERFILE.md](INSTALL-WITH-DOCKERFILE.md)
+See instructions here: [INSTALLwDockerfile.md](INSTALLwDockerfile.md)
+
 #### Deploy using Portainer ####
-TODO
+See instructions here: [INSTALLwPortainer.md](INSTALLwPortainer.md)
 
 ### 2 - Activate the Key via Home Assistant
-- Go to the Integrations page in Home Assistant and click on the MQTT box.
+- Go to the Integrations page in Home Assistant and click on the MQTT box
 - One new device per vehicle should appear in the list: `Tesla_BLE_LRWXXXXXXXXXXX403`
-- Access the list of entities linked to the device by clicking on it.
+- Access the list of entities linked to the device by clicking on it
 - Press the button `Generate Keys`
 - It is useful to monitor the logs during this process
 
 ### 3 - Add the Key to the Vehicle ###
 
 > [!Important]
-> The Host Device must be near the vehicle.
+> The Host Device must be near the vehicle
 
-- Get a vehicle key card.
-- Sit in the driver’s seat with your phone open to the Home Assistant page for the MQTT device. The vehicle screen should be active.
-- Press Deploy Key from the HA interface on your phone.
-- Immediately, place the key card on the central console as if to start the vehicle. A confirmation message will ask you to validate adding the key.
-- Rename the newly added Unknown Key to a recognizable name, like BLE Key.
+- Get a vehicle key card
+- Sit in the driver’s seat with your phone open to the Home Assistant page for the MQTT device. The vehicle screen should be active
+- Press Deploy Key from the HA interface on your phone
+- Immediately place the key card on the central console as if to start the vehicle. A confirmation dialog will popup ask you to validate adding the key
+- Rename the newly added Unknown Key to a recognizable name, e.g. BLE Key
+- NOTE: You may have to try this process several times before the confirmation dialog will appear
 
 ### 4 - Test Sending Commands with the BLE Key
-- From the Home Assistant interface, test the available commands.
+- From the Home Assistant interface, test the available commands

INSTALL-WITH-DOCKERFILE.md → INSTALLwDockerfile.md

@@ -1,6 +1,8 @@
 # Deploy using Dockerfile #
+
 ## Deploy using Dockerfile via Command Line ##
 This is for those who can't (or don't want to) use the pre-built images from Dockerhub. For example you may have an architecture for which there is no image on Dockerhub
+<br /><br />
 i. Build the image from the command line `docker build -t tesla_ble_mqtt:latest https://github.com/tesla-local-control/tesla_ble_mqtt_docker.git`. Note this can take some time on slower machines, e.g. 65mins+ on a RPi1b. The output will look something like this:
 ```
 [+] Building 3977.9s (18/18) FINISHED                                                                                                       docker:default
@@ -46,7 +48,8 @@ i. Build the image from the command line `docker build -t tesla_ble_mqtt:latest
  => => writing image sha256:87b1c8676fba83a9903257dbc41e5a6bbd95339ca29eebe4da4aa4bf0aceb908                                                          0.0s
  => => naming to docker.io/library/tesla_ble_mqtt:latest  
 ```
-ii. When completed, check it's there by issuing `docker images`. You will see somthing like this:
+ii. When completed, check it's there by issuing `docker images`. You will see something like this:
+
 ```
 REPOSITORY                   TAG                 IMAGE ID       CREATED          SIZE
 tesla_ble_mqtt               latest              8032d3fc0fb8   14 minutes ago   35.4MB
@@ -64,6 +67,7 @@ iv. Download docker-compose.yml and stack.env from the github repository:
    curl -O https://raw.githubusercontent.com/tesla-local-control/tesla_ble_mqtt_docker/main/stack.env
    ```
 v. You will need to edit docker-compose.yml. Change the line `image: "iainbullock/tesla_ble_mqtt:latest"` to `image: "tesla_ble_mqtt:latest"`
+<br /><br />
 vi. Update the environment variables in stack.env according to your needs. As a minimum enter the VIN of your car, and the connection details for your MQTT server. If you want BLE detection enter the BLE MAC address of the car (see below for instructions on how to find this TODO):
 ```shell
 # Mandatory; if multiple VINs separate with , or white space
@@ -106,15 +110,18 @@ DEBUG=
 ENABLE_HA_FEATURES=true
 ```
 vii. Create the Docker volume: `docker volume create tesla_ble_mqtt`
+<br /><br />
 viii. Create a symbolic link to the environment file: `ln -s stack.env env`
+<br /><br />
 ix. Start the container: `docker compose up -d`
+<br /><br />
 x. Check the logs `docker logs -t tesla_ble_mqtt`. Typical logs after start up look like this (when DEBUG=false):
 ```
 Configuration Options are:
   BLE_CMD_RETRY_DELAY=5
   BLE_MAC_LIST=40:XX:XX:XX:XX:F9
   DEBUG=false
-  MQTT_SERVER=192.168.1.5
+  MQTT_SERVER=192.168.X.Y
   MQTT_PORT=1883
   MQTT_PASSWORD=Not Shown
   MQTT_USERNAME=XXXXXX
@@ -133,7 +140,6 @@ Entering Listen to MQTT loop...
 Launch BLE scanning for car presence every 120 seconds
 Launching listen_to_mqtt
 ```
-
+<br /><br />
 ## Deploy using Dockerfile via Portainer ##
-Again this is for those who can't (or don't want to) use the pre-built images from Dockerhub
-TODO
+This is for those who can't (or don't want to) use the pre-built images from Dockerhub. Instructions are in this document: [INSTALLwPortDFile.md](INSTALLwPortDFile.md)

INSTALLwPortDFile.md

@@ -0,0 +1,45 @@
+# Deploy using Portainer with Dockerfile
+This is for those who can't (or don't want to) use the pre-built images from Dockerhub. For example you may have an architecture for which there is no image on Dockerhub.
+<br /><br />
+It is assumed that Docker and Portainer are already setup and working.
+<br /><br />
+i. Login to your Portainer instance. Select the Environment where the deployment will be made
+<br /><br />
+ii. Select the 'Volumes' link from the left menu. Click the blue '+ Add volume' button. In the Create volume page, enter `tesla_ble_mqtt` in the Name field and press the blue 'Create the volume' button:
+<br /><br />
+<img width="805" alt="image" src="https://github.com/user-attachments/assets/179f32b0-5df4-40ce-a836-8376bf49657b">
+<br /> <br />
+iii. Select the 'Images' link from the left menu. Click the blue '+ Build a new image' button. In the 'Build image' page, enter `tesla_ble_mqtt` in the Name field. Select the 'URL. Specify a URL to a file' button in the Build method section. Enter `https://github.com/tesla-local-control/tesla_ble_mqtt_docker.git#main` in the URL field. Click the blue 'Build the image' button. Note this can take some time on slower machines, e.g. 60mins+ on a RPi1b
+<br /><br />
+![image](https://github.com/user-attachments/assets/4da7b772-8281-431b-80f9-1dad7efddde9)
+<br /><br />
+iv. When the build has completed, the Output tab on the 'Build image' page will display 'No build output available. Select the 'Images' link from the left menu, an image with tag 'tesla_ble_mqtt:latest' should be visible in the 'Image list' page:
+![image](https://github.com/user-attachments/assets/ef854d30-52b0-447c-b9e6-a299b5997352)
+<br /><br />
+v. Select the 'Stacks' link from the left menu. Click the blue '+ Add Stack' button. In the 'Create stack' page, enter `tesla_ble_mqtt` in the Name field. Copy and Paste the contents of [docker-compose.yml](https://raw.githubusercontent.com/tesla-local-control/tesla_ble_mqtt_docker/main/docker-compose.yml) into the Web editor box. 
+<br /><br />
+**You must change the ``line image: "iainbullock/tesla_ble_mqtt:latest"`` to ``image: "tesla_ble_mqtt:latest"``**
+<br /><br />
+![image](https://github.com/user-attachments/assets/a7508fce-eb26-4d12-ae05-c3825d57510d)
+<br /><br />
+vi. Scroll further down the Create stack page. In the Environment variables section press the blue Advanced Mode link:
+<br /><br />
+<img width="755" alt="image" src="https://github.com/user-attachments/assets/47b83be5-b52f-4cc5-8077-e50aafdd91cc">
+<br /><br />
+vii. A box to enter environment variables will open up. Copy and Paste the contents of [stack.env](https://raw.githubusercontent.com/tesla-local-control/tesla_ble_mqtt_docker/main/stack.env) into the box, and press the blue 'Deploy the stack' button:
+<br /><br />
+<img width="714" alt="image" src="https://github.com/user-attachments/assets/cb09e093-3791-4fb4-bfea-07b0f7b2f821">
+<br /><br />
+viii. After some time, if all is well, the message 'Success. Stack successfully deployed' will briefly pop-up, and you will be returned to the 'Stacks list' page. Click the newly created tesla_ble_mqtt stack to enter the 'Stack details' page for the new stack. Click the red 'Stop this stack' button, then click the 'Editor' tab:
+<br /><br />
+![image](https://github.com/user-attachments/assets/92351402-e404-4926-b69e-c1420ed500a9)
+<br /><br />
+ix. Scroll down to the 'Environment variables' section. Enter the values required for your setup in the respective fields and when completed press the 'Update the stack' button. Use [stack.env](https://github.com/tesla-local-control/tesla_ble_mqtt_docker/blob/main/stack.env) as a reference
+<br /><br />
+![image](https://github.com/user-attachments/assets/a0a0f149-92ba-49e0-a8fa-b149983f9172)
+<br /><br />
+x. If all is well, the message 'Success. Stack successfully deployed' will briefly pop-up, and you will be returned to the 'Stacks list' page. Click the tesla_ble_mqtt stack to enter the 'Stack details' page for the new stack. In the Containers section click the tesla_ble_mqtt container to enter the 'Container details' page. From here you can view the logs by pressing the Logs link in the 'Container status' section. Succesful logs look something like this at startup:
+<br /><br />
+![Screenshot 2024-07-15 180414](https://github.com/user-attachments/assets/29a47eeb-e509-4541-a130-37e20629b3d4)
+
+

INSTALLwPortainer.md

@@ -0,0 +1,44 @@
+# Deploy using Portainer
+It is assumed that Docker and Portainer are already setup and working.
+<br /><br />
+There are two options for deployment using Portainer:
+<br /><br />
+## 1 - Deploy using Dockerfile via Portainer
+This is for those who can't (or don't want to) use the pre-built images from Dockerhub. For example you may have an architecture for which there is no image on Dockerhub.
+See this document for instructions: [INSTALLwPortDFile.md](INSTALLwPortDFile.md)
+<br /><br />
+## 2 - Deploy using docker-compose.yml via Portainer - recommended
+This will be the preferred option for most people who are using Portainer. 
+<br /><br />
+i. Login to your Portainer instance. Select the Environment where the deployment will be made
+<br /><br />
+ii. Select the 'Volumes' link from the left menu. Click the blue '+ Add volume' button. In the Create volume page, enter `tesla_ble_mqtt` in the Name field and press the blue 'Create the volume' button:
+<br /><br />
+<img width="805" alt="image" src="https://github.com/user-attachments/assets/179f32b0-5df4-40ce-a836-8376bf49657b">
+<br /><br />
+iii. Select the 'Stacks' link from the left menu. Click the blue '+ Add Stack' button. In the 'Create stack' page, enter `tesla_ble_mqtt` in the Name field. Copy and Paste the contents of [docker-compose.yml](https://raw.githubusercontent.com/tesla-local-control/tesla_ble_mqtt_docker/main/docker-compose.yml) into the Web editor box:
+<br /><br />
+<img width="788" alt="image" src="https://github.com/user-attachments/assets/b0c318c3-df7c-498e-84aa-a547d577c073">
+<br /><br />
+iv. Scroll further down the Create stack page. In the Environment variables section press the blue Advanced Mode link:
+<br /><br />
+<img width="755" alt="image" src="https://github.com/user-attachments/assets/47b83be5-b52f-4cc5-8077-e50aafdd91cc">
+<br /><br />
+v. A box to enter environment variables will open up. Copy and Paste the contents of [stack.env](https://raw.githubusercontent.com/tesla-local-control/tesla_ble_mqtt_docker/main/stack.env) into the box, and press the blue 'Deploy the stack' button:
+<br /><br />
+<img width="714" alt="image" src="https://github.com/user-attachments/assets/cb09e093-3791-4fb4-bfea-07b0f7b2f821">
+<br /><br />
+vi. After some time, if all is well, the message 'Success. Stack successfully deployed' will briefly pop-up, and you will be returned to the 'Stacks list' page. Click the newly created tesla_ble_mqtt stack to enter the 'Stack details' page for the new stack. Click the red 'Stop this stack' button, then click the 'Editor' tab:
+<br /><br />
+![image](https://github.com/user-attachments/assets/92351402-e404-4926-b69e-c1420ed500a9)
+<br /><br />
+vii. Scroll down to the 'Environment variables' section. Enter the values required for your setup in the respective fields and when completed press the 'Update the stack' button. Use [stack.env](https://github.com/tesla-local-control/tesla_ble_mqtt_docker/blob/main/stack.env) as a reference
+<br /><br />
+![image](https://github.com/user-attachments/assets/a0a0f149-92ba-49e0-a8fa-b149983f9172)
+<br /><br />
+vii. If all is well, the message 'Success. Stack successfully deployed' will briefly pop-up, and you will be returned to the 'Stacks list' page. Click the tesla_ble_mqtt stack to enter the 'Stack details' page for the new stack. In the Containers section click the tesla_ble_mqtt container to enter the 'Container details' page. From here you can view the logs by pressing the Logs link in the 'Container status' section. Succesful logs look something like this at startup:
+<br /><br />
+![Screenshot 2024-07-15 180414](https://github.com/user-attachments/assets/065ece8f-2d91-4679-81be-12195fe89a81)
+
+
+

README.md

@@ -1,39 +1,17 @@
 # Tesla BLE MQTT Docker
 
-Send commands via MQTT to a Tesla car using Bluetooth Low Energy (BLE).
-
-# Read before
-
-The advantage of the MQTT setup is that it can run on HA system or any device separate to your HA server, e.g. Raspberry Pi located close to where you park your car
+Send commands via MQTT to a Tesla car using Bluetooth Low Energy (BLE). BLE bypasses the current Fleet API rate limitation and does not rely on the API.
+The MQTT setup can run on your Home Assistant (HA) system or any device separate from your HA server, e.g. Raspberry Pi located close to where you park your car
 
 **Prerequisite: Have an MQTT broker installed (in Home Assistant or other of your choice).**
-If Home Assistant (HA) is already using the MQTT integration, then the various entities will be auto-discovered by HA.
-
-# Two options to run this tool
-
-## Standalone docker deployed on any machine you want
-
-Good introduction: read this alongside Shankar's blog https://shankarkumarasamy.blog/2024/01/28/tesla-developer-api-guide-ble-key-pair-auth-and-vehicle-commands-part-3
-You should already have Docker working on the host device, and you are familiar with basic Docker concepts and actions
-
-Then:
-- Build the docker image using the Dockerfile. Alternatively you can get the image directly from Dockerhub https://hub.docker.com/r/iainbullock/tesla_ble_mqtt
-- Make any required changes required to suit your setup in docker-compose.yml, in particular the environment variables will need changing according to your requirements
-- Deploy the stack. View the container logs whilst working on the next steps, as this gives some feedback as to what is going on
-- On your HA instance, navigate to the Integrations page, and click on the MQTT Integration tile. A new device called Tesla_BLE_MQTT should have automatically appeared. Click it to view the the associated entities. You should find a list of Button entities and a Number entity
-- If this is the first time you have run the container, press the 'Generate Keys' button. This will generate the public and private keys as per Shankar's blog
-- Wake up your car using the Tesla App. Then press the 'Deploy Key' button. This will deploy the public key to the car. You will then need to access your car and use a Key Card to accept the public key into the car (see the blog for screenshots)
-- Press the other button entities to send various commands, or change the Charging Current. You can use the relevant service calls in HA automations if you wish
-
-## Using as a Home Assistant addon
+If Home Assistant is already using the MQTT integration, then the various entities will be auto-discovered by HA.
 
-This repo is embedded in the Home Assistant [tesla-local-control-addon](https://github.com/tesla-local-control/tesla-local-control-addon) 
-Please follow this link, or add the repo to your home assistant addon repos
+## Two options to run this tool:
 
-[![Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https://github.com/tesla-local-control/tesla-local-control-addon)
+### 1 - Tesla BLE MQTT Docker
 
+This is a Docker container which can be deployed on any machine you want. See [INSTALL.md](https://github.com/tesla-local-control/tesla_ble_mqtt_docker/blob/main/INSTALL.md) for instructions
 
-# Credits
+### 2 - Tesla Local Control Add-on
 
-I got the idea for this from Raphael Murray as described here https://github.com/alandtse/tesla/issues/961#issuecomment-2150897886
-The technical method was derived from Shankar Kumarasamy's blog https://shankarkumarasamy.blog/2024/01/28/tesla-developer-api-guide-ble-key-pair-auth-and-vehicle-commands-part-3
+This is a Home Assistant Add-On installed on your HA instance. Go to this associated repository: [tesla-local-control-addon](https://github.com/tesla-local-control/tesla-local-control-addon)