Merge pull request #404 from webdjoe/dev

fix: Disconnection and Core 200S Parse

Author: webdjoe

.github/workflows/RunTest.yaml

@@ -4,6 +4,7 @@ on:
   pull_request:
     branches:
       - master
+      - dev
   push:
   workflow_dispatch:
 
@@ -44,4 +45,4 @@ jobs:
           pytest -v
       - name: Fail if any steps failed
         run: |
-          [ "${{ steps.ruff.outcome }}" == "failure" ] || [ "${{ steps.pylint.outcome }}" == "failure" ] || [ "${{ steps.pytest.outcome }}" == "failure" ] && exit 1 || exit 0
+          [ "${{ steps.ruff.outcome }}" == "failure" ] || [ "${{ steps.pylint.outcome }}" == "failure" ] || [ "${{ steps.pytest.outcome }}" == "failure" ] && exit 1 || exit 0

docs/authentication.md

@@ -2,68 +2,61 @@
 
 The VeSync Authentication Module provides a clean separation of authentication logic from the main VeSync class, offering improved maintainability, better error handling, and additional features like token persistence.
 
-## Features
-
-- **Flexible Authentication**: Support for both username/password and token-based authentication
-- **Token Persistence**: Automatic saving and loading of authentication tokens to/from disk
-- **Improved Error Handling**: More granular and descriptive error messages
-- **Better Security**: Secure file permissions for token storage
-- **Graceful Token Validation**: Automatic validation of existing tokens before use
-- **Cross-Region Support**: Automatic handling of region changes during authentication
-
 ## Usage
 
+Username and password must still be provided when instantiating the `VeSync` class, but a token can be loaded instead of logging in. If the loaded token is not valid, the `login()` method will be automatically called.
+
 ### Basic Username/Password Authentication
 
 ```python
 import asyncio
 from pyvesync import VeSync
 
 async def main():
-    manager = VeSync(
-        username="[email protected]",
-        password="your_password",
-        country_code="US"
-    )
-
-    # Login
-    success = await manager.login()
-    if success:
-        print("Login successful!")
-        # Use manager for device operations
-        await manager.get_devices()
-        await manager.update_all_devices()
+    with VeSync(username="[email protected]", password="password") as manager:
+        # Login
+        success = await manager.login()
+        if not success:
+            print("Login failed!")
+            return
 
-    await manager.__aexit__()
+        print("Login successful!")
 
 asyncio.run(main())
 ```
 
-### Token-Based Authentication
+### Loading authentication data
+
+The authentication data can be provided to arguments of the `set_credentials()` or `load_credentials_from_file()` methods of the instantiated `VeSync` object.
+
+The credentials needed are: `token`, `account_id`, `country_code`, and `region`.
 
 ```python
 import asyncio
 from pyvesync import VeSync
 
 async def main():
-    # Use existing token (e.g., from previous login)
-    manager = VeSync(
-        token="your_existing_token",
-        account_id="your_account_id",
-        country_code="US"
-    )
-
-    # Login with token
-    success = await manager.login()
-    if success:
-        print("Token authentication successful!")
-
-    await manager.__aexit__()
+    with VeSync(username="[email protected]", password="password") as manager:
+        # Load credentials from a dictionary
+        credentials = {
+            "token": "your_token_here",
+            "account_id": "your_account_id_here",
+            "country_code": "US",
+            "region": "US"
+        }
+        success = await manager.set_credentials(**credentials)
+
+        # Or load from a file
+        await manager.load_credentials_from_file("path/to/credentials.json")
 
 asyncio.run(main())
 ```
 
-### Persistent Token Storage
+### Credential Storage
+
+Credentials can be saved to a file or output as a json string. If no file path is provided the credentials will be saved to the users home directory as `.vesync_auth`.
+
+The credentials file is a json file that has the keys `token`, `account_id`, `country_code`, and `region`.
 
 ```python
 import asyncio
@@ -73,142 +66,21 @@ from pyvesync import VeSync
 async def main():
     token_file = Path.home() / ".vesync_token"
 
-    manager = VeSync(
-        username="[email protected]",
-        password="your_password",
-        token_file_path=token_file
-    )
+    with VeSync(username="[email protected]", password="password") as manager:
+        # Login and save credentials to file
+        success = await manager.login(token_file_path=token_file)
+        if success:
+            # Save credentials to file
+            manager.save_credentials(token_file)
 
-    # First login saves token to file
-    success = await manager.login()
-    if success:
-        print("Login successful! Token saved for future use.")
+            # Output credentials as json string
+            print(manager.output_credentials())
 
-    # Subsequent runs will automatically load the saved token
-    # and validate it before falling back to username/password
-
-    await manager.__aexit__()
+            print("Login successful and credentials saved!")
+        else:
+            print("Login failed!")
 
 asyncio.run(main())
 ```
 
-### Direct Authentication Management
-
-```python
-from pyvesync import VeSync
-
-# Create manager without initial credentials
-manager = VeSync()
-
-# Set credentials programmatically
-manager.auth.set_credentials(
-    username="[email protected]",
-    password="your_password"
-)
-
-# Check authentication state
-print(f"Is authenticated: {manager.auth.is_authenticated}")
-print(f"Username: {manager.auth.username}")
-
-# Clear credentials
-manager.auth.clear_credentials()
-```
-
-## Authentication Flow
-
-The authentication process follows these steps:
-
-1. **Token Validation**: If a token exists, validate it first
-2. **Username/Password Login**: If no valid token, use credentials
-3. **Authorization Code Exchange**: Get auth code, then exchange for token
-4. **Cross-Region Handling**: Automatically handle region changes
-5. **Token Persistence**: Save token to file if path is provided
-
-## VeSyncAuth Class
-
-The `VeSyncAuth` class handles all authentication logic:
-
-### Properties
-
-- `token`: Authentication token
-- `account_id`: VeSync account ID
-- `country_code`: Country code for the account
-- `username`: Account username (read-only)
-- `password`: Account password (read-only)
-- `is_authenticated`: Boolean indicating if user is authenticated
-
-### Methods
-
-- `login()`: Perform authentication
-- `set_credentials()`: Set authentication credentials
-- `clear_credentials()`: Clear all stored credentials
-- `get_auth_headers()`: Get headers for authenticated API requests
-- `to_dict()`: Get authentication state as dictionary
-
-## Migration from Old VeSync Class
-
-The new authentication module is fully backward compatible. Existing code will continue to work:
-
-```python
-# Old way (still works)
-manager = VeSync("[email protected]", "password")
-await manager.login()
-
-# New way (recommended)
-manager = VeSync(
-    username="[email protected]",
-    password="password",
-    token_file_path="~/.vesync_token"
-)
-await manager.login()
-```
-
-## Advanced Features
-
-### Custom Token File Location
-
-```python
-from pathlib import Path
-
-# Custom location
-token_file = Path("/secure/location/vesync_token.json")
-manager = VeSync(
-    username="[email protected]",
-    password="password",
-    token_file_path=token_file
-)
-```
-
-### Token-Only Authentication
-
-```python
-# For applications that manage tokens externally
-manager = VeSync(
-    token="externally_managed_token",
-    account_id="known_account_id"
-)
-```
-
-### Error Handling
-
-```python
-from pyvesync.utils.errors import VeSyncLoginError, VeSyncAPIResponseError
-
-try:
-    success = await manager.login()
-except VeSyncLoginError as e:
-    print(f"Login failed: {e}")
-except VeSyncAPIResponseError as e:
-    print(f"API error: {e}")
-```
-
-## Security Considerations
-
-- Token files are created with restrictive permissions (0o600)
-- Sensitive information is not included in string representations
-- Credentials are cleared from memory when `clear_credentials()` is called
-- Token validation prevents use of expired tokens
-
-## Thread Safety
-
-The authentication module is designed for use with asyncio and is not thread-safe. Use appropriate synchronization if accessing from multiple threads.
+For a full list of methods and attributes, refer to the [auth](development/auth_api.md) and [vesync](development/vesync_api.md) documentation.

docs/development/auth_api.md

@@ -0,0 +1,19 @@
+# Documentation for `pyvesync.auth` module
+
+This module handles the authentication logic for the VeSync API. It is stored as the `auth` instance attribute of the `VeSync` class.
+
+::: pyvesync.auth.VeSyncAuth
+    handler: python
+    options:
+      group_by_category: true
+      show_root_heading: true
+      show_category_heading: true
+      show_source: false
+      filters:
+        - "!.*_dev_test"
+        - "!set_dev_id"
+        - "!process_devices"
+        - "!remove_old_devices"
+        - "!device_time_check"
+      merge_init_into_class: true
+      show_signature_annotations: true

docs/development/capturing.md

@@ -0,0 +1,88 @@
+# Packet Capturing for New Device Support
+
+This document outlines the steps to capture network packets for adding support for new devices in the `pyvesync` library. It is intended for developers who want to extend the library's functionality by integrating additional VeSync devices. Packet captures are required in order to add new devices and functionality.
+
+The process outlined below is time consuming and can be difficult. An alternative method is to temporarily share the device. If you would prefer this method, please indicate in an issue or contact the maintainer directly. Sharing a device is done by going to the device settings and selecting "Share Device". Please create a post to notify the maintainers to receive the correct email address to share the device with.
+
+Please do not post a device request without being will to either capture packets or share the device.
+
+## Prerequisites
+
+1. **Mumu Emulator**: Download and install the Mumu Android emulator from [Mumu Player](https://www.mumuplayer.com/). This emulator allows you to run Android apps on your computer. Other emulators may work, but Mumu is known to be compatible with Arm64 apk's and allows `adb root` access.
+
+2. **VeSync App**: The latest VeSync app from apkpure or another apk sharing site.
+
+3. **Charles Proxy**: Download and install Charles Proxy from [Charles](https://www.charlesproxy.com/). The 30
+day trial is sufficient for this purpose. If you do like the software, support the developer by purchasing a license.
+
+4. **ADB (Android Debug Bridge)**: Ensure you have ADB installed on your system. This is typically included with Android Studio, but can also be installed separately with Android Command Line Tools. This is the site for [Android Studio](https://developer.android.com/studio). Scroll to the "Command Line Tools Only" section to download just the command line tools. Once installed, ensure adb is in your system PATH. You may have to restart your terminal or IDE to pick up the PATH change. The following path is where the `adb` binary is located: `C:\Users\YOUR_USERNAME\AppData\Local\Android\Skd\platform-tools` on Windows or `/home/YOUR_USERNAME/Android/Sdk/platform-tools` on Linux.
+
+5. **frida-server**: Download the latest frida-server from [frida-server](https://github.com/frida/frida/releases). Choose the release that matches the architecture of the MuMu emulator - `frida-server-x.x.x-android-x86_x64.xz`. Extract the `frida-server` binary and place it in the project directory.
+
+
+## Steps
+
+1. **Set up project directory**:
+   - Create a new directory for the project and place the extracted `frida-server` binary in it.
+   - Move the VeSync (x)apk to the project directory.
+   - Open a terminal in the project directory.
+   - Create a virtual environment and install frida:
+
+      ```bash
+         python -m venv venv
+         source venv/bin/activate
+         # On Windows cmd use `venv\Scripts\activate`
+         # On powershell use `venv\Scripts\Activate.ps1`
+         pip install frida-tools
+      ```
+
+2. **Set up Charles Proxy**:
+    - Open Charles Proxy and go to `Proxy` > `Proxy Settings`. Note the HTTP Proxy port (default is 8888).
+    - Go to `Help` > `SSL Proxying` > `Save Root Certificate` > `cert format`.
+    - Save the certificate to the project directory as `cert-der.crt`.
+
+3. **Set up MuMu Emulator**:
+    - Open the Mumu emulator and install the VeSync app by using the down arrow icon on the top right. Select "Install APK" from the bottom of the menu and choose the VeSync apk in the project directory.
+    - Configure the proxy in `System Applications` > `Settings` > `Network & Internet` > `Internet` > Gear icon next to the connected network. If charles is running on the same machine, set the proxy hostname to `localhost:8888` (or the port you noted earlier).
+    - Enable SSL Proxying in Charles by going to `Proxy` > `SSL Proxying Settings` and checking `Enable SSL Proxying`. Add a location with Host: `*` and Port: `*` if not already set.
+
+4. **Configure MuMu to use Charles Proxy**:
+    - Once the MuMu emulator is running, open a new terminal in the project directory and run:
+
+    ```bash
+       adb connect 127.0.0.1:7555
+       adb root
+       adb push cert-der.crt /data/local/tmp/
+       adb push frida-server /data/local/tmp/
+       adb shell
+
+       # This should bring up the android emulator command line
+       cd /data/local/tmp
+       chmod +x frida-server
+       ./frida-server
+    ```
+
+    - **LEAVE THIS TERMINAL OPEN**. There will be no output from the final command.
+
+5. **Run the frida script**:
+   - With Mumu and the frida-server terminal running, open a separate terminal in the project directory, and ensure that the virtual environment is activated.
+   - Run the following command to start frida with the VeSync app:
+
+   ```bash
+      frida -U --codeshare akabe1/frida-multiple-unpinning -f com.etekcity.vesyncplatform
+   ```
+
+   - This will start the VeSync app and allow charles to capture the packets. You should see output in the terminal indicating that frida has attached to the process and the app will open in the emulator.
+   - Login to your VeSync account in the app and check that charles is able to capture and decode the packages. The url should start with `https://smartapi.vesync.com` or `https://smartapi.vesync.eu`. On occasion it may start with `https://smartapi.vesyncapi.com` or `https://smartapi.vesyncapi.eu`.
+
+6. **Run actions in the VeSync app**:
+   - Perform all of the actions, including timers and schedulers. Ensure that after each action you go back to the device list and then back into the device. This ensures that the status of the device is captured after each action.
+   - If you have multiple devices, perform actions on each device.
+
+7. **Save the Charles session**:
+   - Once all actions have been performed, stop the frida process by pressing `CTRL+C` in the frida terminal.
+   - In Charles, go to `File` > `Save Session As...` and save the session as `vesync_session.chls` in the project directory.
+
+8. **Share the capture**:
+   - **DO NOT** post the capture in an issue. Please create an issue or comment on an issue to notify the maintainers that you have a capture ready to share.
+   - Files can be shared via discord or email to webdjoe at gmail.