tuya-vacuum 0.1.0__tar.gz

tuya_vacuum-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,117 @@
+name: Publish
+
+on: push
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      # Download the repository into the CI runner
+      # Then, install and activate the newest Python 3 release
+      - uses: actions/checkout@v4
+      - name: set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Install pypa/build
+        run: python3 -m pip install build --user
+      # Build the dists from source and store them
+      - name: Build a binary wheel and a source tarball
+        run: python3 -m build
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish distribution to PyPI
+    # Only publish to PyPI on tag pushes
+    if: startsWith(github.ref, 'refs/tags/')
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/tuya-vacuum/
+    permissions:
+        id-token: write # IMPORTANT: mandatory for trusted publishing
+    steps:
+      - name: Download the distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  # Sign the distribution packages with Sigstore.
+  # Upload the signed packages to GitHub Release.
+  github-release:
+    name: Sign and upload to GitHub Release
+    needs:
+      - publish-to-pypi
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write # IMPORTANT: mandatory for making GitHub Releases
+      id-token: write # IMPORTANT: mandatory for trusted publishing
+    
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Sign the dists with Sigstore
+        uses: sigstore/gh-action-sigstore-python@v3.0.0
+        with:
+          inputs: >-
+            ./dist/*.tar.gz
+            ./dist/*.whl
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >-
+          gh release create
+          '${{ github.ref_name }}'
+          --repo '${{ github.repository }}'
+          --notes ""
+      - name: Upload artifact signatures to GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        # Upload to GitHub Release using the `gh` CLI.
+        # `dist/` contains the built pacakges, adn the
+        # sigstore-produced signatures and certificates.
+        run: >-
+          gh release upload
+          '${{ github.ref_name }}' dist/**
+          --repo '${{ github.repository }}'
+
+
+  publish-to-testpypi:
+    name: Publish distribution to TestPyPI
+    needs:
+      - build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/tuya-vacuum/
+
+    permissions:
+      id-token: write # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+      - name: Download the distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true # Tolerate already-published packages

tuya_vacuum-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: Test
+
+on: push
+
+jobs:
+  build:
+    name: Build and Test
+    runs-on: ubuntu-latest
+
+    steps:
+      # Download the repository into the CI runner
+      # Then, install and activate the newest Python 3 release
+      - uses: actions/checkout@v4
+      - name: set up Python
+        uses: actions/setup-python@v5
+        with:
+          # Semantic version range syntax or exact verison of a Python version
+          python-version: "3.x"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+      - name: Install pytest
+        run: pip install pytest pytest-cov
+      - name: Test with pytest
+        run: pytest ./tests --doctest-modules --junitxml=junit/test-results.xml --cov=com --cov-report=xml --cov-report=html
+      - name: Upload pytest test results
+        uses: actions/upload-artifact@v4
+        with:
+          name: pytest-results
+          path: junit/test-results.xml
+        # Use always() to always run this step to publish test results.
+        # Even when there are test failures
+        if: ${{ always() }}

tuya_vacuum-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.env
+__pycache__
+.pytest_cache
+venv
+.coverage
+
+# Distribution archives
+dist
+
+# Hide files made while manually testing
+/layout.bin
+path.bin
+combined.png

tuya_vacuum-0.1.0/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

tuya_vacuum-0.1.0/.vscode/tasks.json

@@ -0,0 +1,24 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Code Coverage",
+            "detail": "Generate code coverage report.",
+            "type": "shell",
+            "command": "${command:python.interpreterPath}",
+            "args": [
+                "-m",
+                "pytest",
+                "--cov",
+            ],
+            "group": {
+                "kind": "test",
+                "isDefault": true
+            },
+            "presentation": {
+                "reveal": "always",
+                "panel": "dedicated"
+            }
+        }
+    ]
+}

tuya_vacuum-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jaiden Labelle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tuya_vacuum-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.3
+Name: tuya-vacuum
+Version: 0.1.0
+Summary: A python library to view maps from Tuya robot vacuums
+Project-URL: Homepage, https://github.com/jaidenlabelle/tuya-vacuum
+Project-URL: Issues, https://github.com/jaidenlabelle/tuya-vacuum/issues
+Author-email: Jaiden Labelle <jaidenjlabelle@gmail.com>
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+
+# tuya-vacuum
+tuya-vacuum is a python library to view maps from Tuya robot vacuums.
+
+## Installation
+Use the package manager [pip](https://pip.pypa.io/en/stable/) to install tuya-vacuum.
+
+```bash
+pip install tuya-vacuum
+```
+
+## Usage
+```python
+from tuya_vacuum.tuya import TuyaCloudAPI
+import requests
+
+# Create a new TuyaCloudAPI instance
+tuya = TuyaCloudAPI(
+    origin="https://openapi.tuyaus.com",
+    client_id="<Client ID>",
+    client_secret="<Client Secret>"
+)
+
+# Request the current realtime map data from the cloud
+device_id = "<Device ID>"
+response = tuya.request("GET", f"/v1.0/users/sweepers/file/{device_id}/realtime-map")
+
+# Get the layout and path data using the returned map urls
+layout_data = requests.get(response["result"][0]["map_url"]).content.hex()
+path_data = requests.get(response["result"][1]["map_url"]).content.hex()
+
+# Parse the map data
+vacuum_map = VacuumMap(layout_data, path_data)
+
+# Save the map as an image
+image = vacuum_map.to_image()
+image.save("output.png")
+```
+
+## Compatability List
+
+This is a list of all currently tested devices. Create a new [issue](https://github.com/jaidenlab/tuya-vacuum/issues) to add your device.
+
+| Device                                                | Support                           |
+| ----------------------------------------------------- | --------------------------------- |
+| [Lefant M1](https://www.lefant.com/en-ca/products/m1) | <text style="color:lightgreen">Supported</text> |
+
+## Special Thanks
+- [Tuya Cloud Vacuum Map Extractor](https://github.com/oven-lab/tuya_cloud_map_extractor) by [@oven-lab](https://github.com/oven-lab)

tuya_vacuum-0.1.0/README.md

@@ -0,0 +1,48 @@
+# tuya-vacuum
+tuya-vacuum is a python library to view maps from Tuya robot vacuums.
+
+## Installation
+Use the package manager [pip](https://pip.pypa.io/en/stable/) to install tuya-vacuum.
+
+```bash
+pip install tuya-vacuum
+```
+
+## Usage
+```python
+from tuya_vacuum.tuya import TuyaCloudAPI
+import requests
+
+# Create a new TuyaCloudAPI instance
+tuya = TuyaCloudAPI(
+    origin="https://openapi.tuyaus.com",
+    client_id="<Client ID>",
+    client_secret="<Client Secret>"
+)
+
+# Request the current realtime map data from the cloud
+device_id = "<Device ID>"
+response = tuya.request("GET", f"/v1.0/users/sweepers/file/{device_id}/realtime-map")
+
+# Get the layout and path data using the returned map urls
+layout_data = requests.get(response["result"][0]["map_url"]).content.hex()
+path_data = requests.get(response["result"][1]["map_url"]).content.hex()
+
+# Parse the map data
+vacuum_map = VacuumMap(layout_data, path_data)
+
+# Save the map as an image
+image = vacuum_map.to_image()
+image.save("output.png")
+```
+
+## Compatability List
+
+This is a list of all currently tested devices. Create a new [issue](https://github.com/jaidenlab/tuya-vacuum/issues) to add your device.
+
+| Device                                                | Support                           |
+| ----------------------------------------------------- | --------------------------------- |
+| [Lefant M1](https://www.lefant.com/en-ca/products/m1) | <text style="color:lightgreen">Supported</text> |
+
+## Special Thanks
+- [Tuya Cloud Vacuum Map Extractor](https://github.com/oven-lab/tuya_cloud_map_extractor) by [@oven-lab](https://github.com/oven-lab)

tuya_vacuum-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tuya-vacuum"
+version = "0.1.0"
+description = "A python library to view maps from Tuya robot vacuums"
+authors = [
+    { name = "Jaiden Labelle", email = "jaidenjlabelle@gmail.com" }
+]
+readme = "README.md"
+requires-python = ">=3.6"
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/jaidenlabelle/tuya-vacuum"
+Issues = "https://github.com/jaidenlabelle/tuya-vacuum/issues"

tuya_vacuum-0.1.0/scripts/download_maps.py

@@ -0,0 +1,49 @@
+"""Script to download the current realtime map from a vacuum using the Tuya Cloud API."""
+
+import os
+
+import requests
+from dotenv import load_dotenv
+from tuya_vacuum.tuya import TuyaCloudAPI
+
+# Load environment variables
+load_dotenv()
+
+# Get environment variables
+CLIENT_ID = os.environ["CLIENT_ID"]
+CLIENT_SECRET = os.environ["CLIENT_SECRET"]
+DEVICE_ID = os.environ["DEVICE_ID"]
+
+
+def main():
+    """Download the current realtime map from a vacuum using the Tuya Cloud API."""
+
+    BASE = "https://openapi.tuyaus.com"
+    ENDPOINT = f"/v1.0/users/sweepers/file/{DEVICE_ID}/realtime-map"
+
+    tuya = TuyaCloudAPI(base=BASE, client_id=CLIENT_ID, client_secret=CLIENT_SECRET)
+    response = tuya.request(ENDPOINT)
+
+    maps = response["result"]
+
+    for vacuum_map in maps:
+        print(vacuum_map)
+
+        map_url = vacuum_map["map_url"]
+        map_data = requests.get(map_url, timeout=2.5).content
+
+        if vacuum_map["map_type"] == 1:
+            # Save Path Data
+            with open("path.bin", "wb") as file:
+                file.write(map_data)
+        if vacuum_map["map_type"] == 0:
+            # Save Map Data
+            with open("layout.bin", "wb") as file:
+                file.write(map_data)
+        else:
+            # Unknown Map Type
+            print(f"Unknown Map Type: {vacuum_map['map_type']}")
+
+
+if __name__ == "__main__":
+    main()

tuya_vacuum-0.1.0/scripts/parse_map_data.py

@@ -0,0 +1,36 @@
+"""Script to parse data from a vacuum map."""
+
+import logging
+
+from tuya_vacuum.vacuum_map import VacuumMap
+
+
+logging.basicConfig(level=logging.DEBUG)
+
+
+def main():
+    """Parse data from a vacuum map."""
+
+    with open("path.bin", "rb") as path_file:
+        with open("layout.bin", "rb") as layout_file:
+            # Read each file as a hex string
+            layout_data = layout_file.read().hex()
+            path_data = path_file.read().hex()
+
+            vacuum_map = VacuumMap(layout_data, path_data)
+            map_image = vacuum_map.to_image()
+            map_image = VacuumMap.crop_image(
+                map_image,
+                410,
+                250,
+                vacuum_map.layout.origin_x,
+                vacuum_map.layout.origin_y,
+                offset_x=50,
+                offset_y=60,
+            )
+
+            map_image.save("combined.png")
+
+
+if __name__ == "__main__":
+    main()

tuya_vacuum-0.1.0/tests/test_tuya.py

@@ -0,0 +1,209 @@
+"""Functional test for communication with the Tuya Cloud API."""
+
+import logging
+from uuid import UUID
+import httpx
+from pytest_httpx import HTTPXMock
+from pytest_mock import MockerFixture
+from freezegun import freeze_time
+import pytest
+
+from tuya_vacuum.tuya import CrossRegionAccessError, InvalidClientIDError, InvalidDeviceIDError, TuyaCloudAPI, InvalidClientSecretError
+
+_LOGGER = logging.getLogger(__name__)
+
+CLIENT_ID = "example"
+CLIENT_SECRET = "example"
+DEVICE_ID = "example"
+ORIGIN = "https://openapi.tuyaus.com"
+ENDPOINT = f"/v1.0/users/sweepers/file/{DEVICE_ID}/realtime-map"
+
+# Mock the datetime module to a fixed time
+@freeze_time("2024-11-02 12:00:01")
+def test_get_timestamp():
+    """Test TuyaCloudAPI.get_timestamp."""
+
+    assert TuyaCloudAPI.get_timestamp() == "1730548801000"
+
+def test_get_nonce(mocker: MockerFixture):
+    """Test TuyaCloudAPI.get_nonce."""
+
+    # Mock the UUID generation
+    mocker.patch("uuid.uuid4", return_value=UUID('0e950a25-9a73-4b8e-bae7-86f131450350'))
+
+    assert TuyaCloudAPI.get_nonce() == "0e950a259a734b8ebae786f131450350"
+
+def test_create_signature():
+    """Test TuyaCloudAPI.create_signature."""
+    tuya = TuyaCloudAPI(origin=ORIGIN, client_id=CLIENT_ID, client_secret=CLIENT_SECRET)
+
+    method = "GET"
+    endpoint = ENDPOINT
+    timestamp = "1730548801000"
+    nonce = "0e950a259a734b8ebae786f131450350"
+    access_token = "example_access_token"
+
+    tuya = TuyaCloudAPI(origin=ORIGIN, client_id=CLIENT_ID, client_secret=CLIENT_SECRET)
+    signature = tuya.create_signature(method, endpoint, timestamp, nonce, access_token)
+
+    assert signature == "7ADE4474E49D93106F236A261C539CFEC7C89801047896F5A3376202B422A8FD"
+
+# Mock the datetime module to a fixed time
+@freeze_time("2024-11-02 12:00:01")
+def test_request(mocker: MockerFixture, httpx_mock: HTTPXMock):
+    """Test TuyaCloudAPI.request."""
+
+    # Mock response for the request to get the access token
+    httpx_mock.add_response(
+        url = f"{ORIGIN}/v1.0/token?grant_type=1",
+        json = {
+            "success": True,
+            "result": {
+                "access_token": "example_access_token",
+            }
+        }
+    )
+    # Mock response for the request to get the map URLs
+    httpx_mock.add_response(
+        url = f"{ORIGIN}{ENDPOINT}",
+        json = {
+            "success": True,
+            "result": [
+                {
+                    "map_url": "example_layout_map_url",
+                    "map_type": 0
+                },
+                {
+                    "map_url": "example_path_map_url",
+                    "map_type": 1
+                }
+            ]
+        }
+    )
+
+    # Mock the UUID generation
+    mocker.patch("uuid.uuid4", return_value=UUID('0e950a25-9a73-4b8e-bae7-86f131450350'))
+
+    with httpx.Client() as client:
+        # Create a TuyaCloudAPI instance
+        tuya = TuyaCloudAPI(
+            origin=ORIGIN,
+            client_id=CLIENT_ID,
+            client_secret=CLIENT_SECRET,
+            client=client
+        )
+
+        response = tuya.request("GET", ENDPOINT)
+
+        # Check if the returned values are correct
+        # Check if the response is successful
+        assert response["success"]
+        # Check if the layout map URL is correct
+        assert response["result"][0]["map_url"] == "example_layout_map_url"
+        # Check if the path map URL is correct
+        assert response["result"][1]["map_url"] == "example_path_map_url"
+
+        requests = httpx_mock.get_requests()
+
+        # Check if the access token request was successful
+        request = requests[0]
+        headers = request.headers
+        assert request.url == f"{ORIGIN}/v1.0/token?grant_type=1"
+        assert headers.get("client_id") == CLIENT_ID
+        assert headers.get("sign") == (
+            "B557C364FD291EFF020769E5D1D1689C7C9BAF9AFAA7D936CCA26361D01B17DE"
+        )
+        assert headers.get("sign_method") == "HMAC-SHA256"
+        assert headers.get("t") == "1730548801000"
+        assert headers.get("lang") == "en"
+        assert headers.get("nonce") == "0e950a259a734b8ebae786f131450350"
+
+        # Check if the endpoint request was successful
+        request = requests[1]
+        headers = request.headers
+        assert request.url == f"{ORIGIN}{ENDPOINT}"
+        assert headers.get("client_id") == CLIENT_ID
+        assert headers.get("sign") == (
+            "7ADE4474E49D93106F236A261C539CFEC7C89801047896F5A3376202B422A8FD"
+        )
+        assert headers.get("sign_method") == "HMAC-SHA256"
+        assert headers.get("t") == "1730548801000"
+        assert headers.get("lang") == "en"
+        assert headers.get("nonce") == "0e950a259a734b8ebae786f131450350"
+
+def test_invalid_request(httpx_mock: HTTPXMock):
+    """Test TuyaCloudAPI.request with an invalid request."""
+
+    # Invalid client id request
+    httpx_mock.add_response(
+        url = f"{ORIGIN}/v1.0/token?grant_type=1",
+        match_headers={"client_id": "wrong_client_id"},
+        json = {
+            "success": False,
+            "code": 1005,
+        }
+    )
+
+
+    # Invalid origin
+    httpx_mock.add_response(
+        url = "https://invalid_origin.com/v1.0/token?grant_type=1",
+        json = {
+            "success": False,
+            "code": 2007,
+        }
+    )
+
+    # Mock response for the request to get the map URLs
+    httpx_mock.add_response(
+        url = f"{ORIGIN}/invalid_device_id/realtime-map",
+        json = {
+            "success": False,
+            "code": 1106
+        }
+    )
+
+    with httpx.Client() as client:
+        # # Create a TuyaCloudAPI instance
+        # tuya = TuyaCloudAPI(
+        #     origin=ORIGIN,
+        #     client_id=CLIENT_ID,
+        #     client_secret="wrong_client_secret",
+        #     client=client
+        # )
+
+        # with pytest.raises(InvalidClientSecretError):
+        #     tuya.request("GET", "/v1.0/token?grant_type=1", fetch_token=False)
+
+        # Create a TuyaCloudAPI instance
+        tuya = TuyaCloudAPI(
+            origin=ORIGIN,
+            client_id="wrong_client_id",
+            client_secret=CLIENT_SECRET,
+            client=client
+        )
+
+        with pytest.raises(InvalidClientIDError):
+            tuya.request("GET", "/v1.0/token?grant_type=1", fetch_token=False)
+
+        # Create a TuyaCloudAPI instance
+        tuya = TuyaCloudAPI(
+            origin="https://invalid_origin.com",
+            client_id=CLIENT_ID,
+            client_secret=CLIENT_SECRET,
+            client=client
+        )
+
+        with pytest.raises(CrossRegionAccessError):
+            tuya.request("GET", "/v1.0/token?grant_type=1", fetch_token=False)
+
+        # Create a TuyaCloudAPI instance
+        tuya = TuyaCloudAPI(
+            origin=ORIGIN,
+            client_id=CLIENT_ID,
+            client_secret=CLIENT_SECRET,
+            client=client
+        )
+
+        with pytest.raises(InvalidDeviceIDError):
+            tuya.request("GET", "/invalid_device_id/realtime-map", fetch_token=False)