Add library code, tests and example

.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: # Replace with a single GitHub username
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-Fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single LiberaPay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: ankohanse
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/dependabot.yml

@@ -0,0 +1,16 @@
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-packages:
+        patterns:
+          - "*"

.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI.org
+on:
+  release:
+    types: [published]
+jobs:
+  pypi:
+    name: Publish release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/aiodabpumps
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install setuptools wheel
+      - name: Build package
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

.vscode/settings.json

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

.vscode/tasks.json

@@ -0,0 +1,33 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "build",
+            "type": "shell",
+            "command": "py -m build",
+            "group": {
+                "kind": "build",
+                "isDefault": false
+            },
+            "presentation": {
+                "reveal": "always",
+                "panel": "new"
+            }
+        },
+        {
+            "label": "publish",
+            "type": "shell",
+            "command": "py -m twine upload dist/*",
+            "group": {
+                "kind": "build",
+                "isDefault": false
+            },
+            "presentation": {
+                "reveal": "always",
+                "panel": "new"
+            }
+        }
+    ]
+}

README.md

@@ -1,2 +1,56 @@
+[![license](https://img.shields.io/github/license/toreamun/amshan-homeassistant?style=for-the-badge)](LICENSE)
+[![buy_me_a_coffee](https://img.shields.io/badge/If%20you%20like%20it-Buy%20me%20a%20coffee-yellow.svg?style=for-the-badge)](https://www.buymeacoffee.com/ankohanse)
+
+
 # aiodabpumps
-Async python library to communicate with DAB Pumps DConnect or DAB Live
+
+Python library for retrieving sensor information from DAB Pumps devices.
+This component uses webservices to connect to the DAB Pumps DConnect website and automatically determines which installations and devices are available there.
+
+The custom component was tested with a ESybox 1.5kw combined with a DConnect Box 2. It has also been reported to function correctly for ESybox Mini and ESybox Diver.
+
+Disclaimer: this library is NOT created by DAB Pumps
+
+
+# Prerequisites
+This device depends on the backend servers for the DAB Pumps DAB Live app and DConnect app to retrieve the device information from.
+
+- For ESybox Mini3 pumps:
+
+  These are supported on the DAB Live app with a free DAB Live account, or on the DConnect App with a paid account. Follow the steps under either [DAB Live](#dab-live) or [DConnect](#dconnect).
+
+- For other pumps:
+
+  To see whether your pump device is supported via DConnect, browse to [internetofpumps.com](https://internetofpumps.com/), select 'Professional Users' and scroll down to the operation diagram. Some pump devices will have integrated connectivity (Esybox MAX and Esybox Mini), others might require a DConnect Box/Box2 device (Esybox and Esybox Diver). A free trial period is available, after that there is a yearly subscription to DAB Pumps DConnect (US$ 20 in 2024). Follow the steps under [DConnect](#dconnect).
+
+## DAB Live
+If you have a pump that is supported for DAB Live then:
+- Download the DAB Live app on your phone or tablet
+- Open the app and create a new account. When asked between 'Professional' or 'End User' either are good, this has no implications on the app or the use of this library.
+- Remember the email address and password for the account as these are needed in any script using this library.
+- Follow the steps in the app to register your pump.
+
+## DConnect
+If you have a device that is supported for DConnect then:
+- Enable your DAB Pumps devices to connect to DConnect. For more information on this, see the manual of your device.
+- Install the DConnect app, or open the DConnect website in a browser.
+- Setup an account for DConnect, see the remarks under 'DConnect Account' below.
+- Remember the email address and password for the account as these are needed during setup of this Home Assistant integration.
+- In DConnect, add your installation via the device serial number.
+
+### DConnect Account
+The DAB Pumps DConnect website and app seem to have a problem with multiple logins from the same account. I.e. when already logged into the app or website, then a subsequent login via this library may fail. 
+
+Therefore it is recommended to create a separate account within DAB Pumps DConnect that is specific for script use. 
+- Create a fresh email address specifically for scripting at gmail, outlook or another provider. 
+- Register this email address in the DAB Pumps DConnect website. Go to  [internetofpumps.com](https://internetofpumps.com/). Select 'Professional Users' and 'Open DConnect', or one of the apps.
+- When entering your details and needing to choose between 'Professional' or 'End User' either are good, this has no implications on the website, app or this library.
+- Then, while logged in into DAB Pumps DConnect using your normal account, go to 'installation settings' and under 'manage permissions' press 'Add member' to invite the newly created email account. Access level 'Installer' is recommended to be able to use all features of the library.
+
+
+# Usage
+
+The library is available from PyPi using:
+`pip install aiodabpumps`
+
+See example_api_use.py for an example of usage.

example_api_use.py

@@ -0,0 +1,60 @@
+import asyncio
+import json
+import logging
+import sys
+
+from aiodabpumps import DabPumpsApi
+
+# Setup logging to StdOut
+logging.basicConfig(stream=sys.stdout, level=logging.DEBUG)
+logger = logging.getLogger(__name__)
+
+TEST_USERNAME = "fill in your DConnect username here"
+TEST_PASSWORD = "fill in your DConnect password here"
+
+async def main():
+    api = None
+    try:
+        # Process these calls in the right order
+        api = DabPumpsApi(TEST_USERNAME, TEST_PASSWORD)
+        await api.async_login()
+
+        # Retrieve installations accessible by this user
+        install_map = await api.async_fetch_install_list()
+
+        logger.info(f"installs: {len(install_map)}")
+
+        for install_id, install in install_map.items():
+            logger.info("")
+            logger.info(f"installation: {install.name} ({install.id})")
+
+            # Retrieve installation details
+            device_map = await api.async_fetch_install_details(install_id)
+            logger.info(f"devices: {len(device_map)}")
+
+            for device_serial, device in device_map.items():
+                logger.info("")
+                logger.info(f"device: {device.name} ({device.serial})")                
+
+                # Retrieve device config details
+                config_id = device.config_id
+                config = await api.async_fetch_device_config(config_id)
+                #logger.info(f"device config: {config}")
+
+                # Once the calls above have been perfomed, the call below can be repeated periodically
+                # Retrieve device statusses
+                status_map = await api.async_fetch_device_statusses(device_serial)
+                logger.info(f"statusses: {len(status_map)}")
+
+                for k,v in status_map.items():
+                    logger.info(f"  {v.serial} - {v.key}: {v.val}")
+
+    except Exception as e:
+        logger.info(f"Unexpected exception: {e}")
+
+    finally:
+        if api:
+            await api.async_close()
+
+
+asyncio.run(main())  # main loop

pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "aiodabpumps"
+version = "0.0.1"
+authors = [
+  { name="Anko Hanse", email="[email protected]" },
+]
+description = "Async python library to communicate with DAB Pumps servers for DConnect and DAB Live"
+readme = "README.md"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.8"
+dependencies = [
+]
+
+[project.optional-dependencies]
+tests = [
+  'pytest',
+  'pytest-asyncio',
+]
+
+[project.urls]
+Homepage = "https://github.com/ankohanse/aiodabpumps"
+Issues = "https://github.com/ankohanse/aiodabpumps/issues"
+
+[build-system]
+requires = [
+    "setuptools>=61.0",
+    "wheel",
+    "cython"
+]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+aiodabpumps = ["*.json"]
+

pytest.ini

@@ -0,0 +1,7 @@
+[pytest]
+log_cli=true
+log_cli_level=DEBUG
+log_format = %(asctime)s %(levelname)s %(message)s
+log_date_format = %Y-%m-%d %H:%M:%S
+asyncio_mode=auto
+asyncio_default_fixture_loop_scope=session

src/aiodabpumps/__init__.py

@@ -0,0 +1,19 @@
+from .dabpumps_api import (
+    DabPumpsApi, 
+    DabPumpsInstall,
+    DabPumpsDevice,
+    DabPumpsConfig,
+    DabPumpsParams,
+    DabPumpsStatus,
+    DabPumpsApiAuthError, 
+    DabPumpsApiRightsError, 
+    DabPumpsApiError, 
+    DabPumpsApiHistoryItem, 
+    DabPumpsApiHistoryDetail,
+)
+
+# for unit tests
+from  .dabpumps_client import (
+    DabPumpsClient_Httpx, 
+    DabPumpsClient_Aiohttp,
+)