Merge pull request #158 from jbergler/process

Update documentation

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Start a discussion (config, doubts, docs)
+    url: https://github.com/jbergler/hass-ttlock/discussions
+    about: If you have general questions, or are unsure about whether a bug report is the right thing to open, click here to create a Discussion instead of an Issue.

.github/workflows/lint_test.yml

@@ -39,7 +39,7 @@ jobs:
       - name: Setup Python
         uses: "actions/setup-python@v4"
         with:
-          python-version: "3.11"
+          python-version: "3.12"
       - name: Install requirements
         run: python3 -m pip install -r requirements.txt
       - name: Run tests

README.md

@@ -37,23 +37,43 @@ This integration uses the TTLock Cloud to communicate with your lock. It support
 1. A TTLock based smart lock
 1. A Gateway (if your lock doesn't have integrated wifi)
    - These can be purchased from the vendor of your lock or direct from [Aliexpress](https://s.click.aliexpress.com/e/_DEPpClx)
+1. Remote unlock must be enabled for each lock
+   - This must be done while in bluetooth range of the lock, from the mobile app
+   - Here is a [youtube video](https://www.youtube.com/watch?v=ni-38QpoNA4) which explains the process
 
 ## Creating an OAuth APP
 
 1. Go to https://open.ttlock.com/manager and create an account
 1. Register an application (this will take a few days to get approved)
 1. Install the extension [via HACS](https://my.home-assistant.io/redirect/hacs_repository/?owner=jbergler&repository=hass-ttlock&category=integration) and restart Home Assistant
 1. Setup the integration [via Home Assistant UI](https://my.home-assistant.io/redirect/config_flow_start/?domain=ttlock)
+   - The first credentials you will be prompted for are the Application Client ID & Secret that you created earlier.
+   - The second credentials you will be prompted for are the username/password you use to login to the ttlock app on your phone.
 1. Once the integration is working you should receive a system notification with the webhook url
    - This will go away when the webhook receives data
 1. Go back to the url from the first step and set the 'Callback URL' for your application
 
+# Troubleshooting
+
+## Common issues
+
+1. Invalid client_id
+   - Your Application (ie oauth) Client ID & Client Secret for the application you created on open.ttlock.com.
+   - These are stored in the "Application Credentials" feature of Home Assistant. If you need to remove/update them, please follow the official [docs](https://www.home-assistant.io/integrations/application_credentials)
+   - If you get this error, you need to remove the invalid credentials and re-setup the integration with the correct ones.
+1. Invalid username or password
+   - The username/password for open.ttlock.com is only used for managing API credentials for the ttlock cloud - do not use these within home assistant.
+   - The username/password for the ttlock (or 3rd party branded) mobile app. This is the account that will work.
+1. "Failed to execute the action lock/lock." or "The function is not supported for this lock"
+   - This is most likely because you haven't enabled remote unlock, please follow the instructions in the requirements section.
+
 ## Reporting issues
 
 When reporting issues, please attach the diagnostic information and consider enabling debug logging to provide extra information.
 
-## Say thanks
+# Say thanks
 
-If you found this helpful and you'd like to say thanks you can do so via buy me a coffee. Thanks!
+If you found this helpful and you'd like to say thanks you can do so via buy me a coffee or a beer.
+I've put a bunch of time into this integration and it always puts a smile on my face when people say thanks!
 
 <a href="https://www.buymeacoffee.com/jbergler" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" height="60" width="217"></a>

pyproject.toml

@@ -6,8 +6,8 @@ authors = ["Jonas Bergler <jonas@lemon.nz>"]
 readme = "README.md"
 
 [tool.poetry.dependencies]
-python = "^3.11"
-homeassistant = "^2023.3.6"
+python = "^3.12"
+homeassistant = "^2024.12.1"
 
 
 [build-system]
@@ -32,7 +32,7 @@ forced_separate = [
 combine_as_imports = true
 
 [tool.pylint.MAIN]
-py-version = "3.10"
+py-version = "3.12"
 ignore = [
     "tests",
 ]

requirements.txt

@@ -1,4 +1,5 @@
 pytest-homeassistant-custom-component
+
 # cloud component
 hass_nabucasa
 webrtcvad
@@ -7,5 +8,8 @@ home-assistant-intents
 mutagen
 python-matter-server
 ha-ffmpeg
+pymicro_vad
+pyspeex_noise
+
 aiohttp_cors # http component
 dateparser # tests