sig-cloud-control 0.3.0__tar.gz → 0.3.2__tar.gz

{sig_cloud_control-0.3.0 → sig_cloud_control-0.3.2}/.github/workflows/release.yml

@@ -14,6 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     outputs:
       release_created: ${{ steps.release.outputs.release_created }}
+      pr: ${{ steps.release.outputs.pr }}
     steps:
       - uses: googleapis/release-please-action@v4
         id: release
@@ -23,6 +24,32 @@ jobs:
           release-type: python
           token: ${{ secrets.GITHUB_TOKEN }}
 
+  update-lockfile:
+    runs-on: ubuntu-latest
+    needs: release-please
+    if: ${{ needs.release-please.outputs.pr }}
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: release-please--branches--main
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.0.0
+
+      - name: Update lock file
+        run: uv lock
+
+      - name: Commit updated lock file
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add uv.lock
+          git diff --staged --quiet || git commit -m "chore: update uv.lock for version bump"
+          git push
+
   publish:
     runs-on: ubuntu-latest
     needs: release-please

{sig_cloud_control-0.3.0 → sig_cloud_control-0.3.2}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.3.2](https://github.com/lawther/sig-cloud-control/compare/v0.3.1...v0.3.2) (2026-04-24)
+
+
+### Bug Fixes
+
+* **cli:** correct path highlighting in show-config command ([d915a55](https://github.com/lawther/sig-cloud-control/commit/d915a55141b8852aeb6ff9973c4e887d9d05d9f5))
+
+## [0.3.1](https://github.com/lawther/sig-cloud-control/compare/v0.3.0...v0.3.1) (2026-04-22)
+
+
+### Documentation
+
+* update disclaimer wording and fix spelling in README ([77d4f40](https://github.com/lawther/sig-cloud-control/commit/77d4f4049a505b57ce07bb3b562ad57a4220c782))
+
 ## [0.3.0](https://github.com/lawther/sig-cloud-control/compare/v0.2.0...v0.3.0) (2026-04-22)
 
 

{sig_cloud_control-0.3.0 → sig_cloud_control-0.3.2}/Justfile

@@ -46,6 +46,7 @@ precommit:
         set -e
         just _lint-justfile
         just lint
+        git add $(git diff --cached --name-only)
         just test
     ) > "$tmpfile" 2>&1
     status=$?

{sig_cloud_control-0.3.0 → sig_cloud_control-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sig-cloud-control
-Version: 0.3.0
+Version: 0.3.2
 Summary: Control Sigenergy battery via Sigen Cloud
 Project-URL: Homepage, https://github.com/lawther/sig-cloud-control
 Project-URL: Repository, https://github.com/lawther/sig-cloud-control
@@ -34,8 +34,8 @@ Description-Content-Type: text/markdown
 A Python library and CLI for controlling Sigenergy (Sigen Cloud) solar and battery systems.
 
 > [⚠️ CAUTION]
-> **Non-Affiliation & Warning**
-> - **Not Official:** This project is not affiliated with, authorized by, or endorsed by Sigenergy. Use of this tool is at your own risk.
+> **Non-Affiliation**
+> - **Not Official:** This project is not affiliated with, authorised by, or endorsed by Sigenergy. Use of this tool is at your own risk.
 > - **Warranty Warning:** Using this tool may violate your Sigenergy Terms of Service and could potentially void your hardware warranty. The author is not responsible for any loss of warranty or damage to equipment.
 > - **Reverse Engineering:** This tool was developed for the purpose of interoperability between Sigenergy batteries and third-party automation systems.
 

{sig_cloud_control-0.3.0 → sig_cloud_control-0.3.2}/README.md

@@ -3,8 +3,8 @@
 A Python library and CLI for controlling Sigenergy (Sigen Cloud) solar and battery systems.
 
 > [⚠️ CAUTION]
-> **Non-Affiliation & Warning**
-> - **Not Official:** This project is not affiliated with, authorized by, or endorsed by Sigenergy. Use of this tool is at your own risk.
+> **Non-Affiliation**
+> - **Not Official:** This project is not affiliated with, authorised by, or endorsed by Sigenergy. Use of this tool is at your own risk.
 > - **Warranty Warning:** Using this tool may violate your Sigenergy Terms of Service and could potentially void your hardware warranty. The author is not responsible for any loss of warranty or damage to equipment.
 > - **Reverse Engineering:** This tool was developed for the purpose of interoperability between Sigenergy batteries and third-party automation systems.
 

{sig_cloud_control-0.3.0 → sig_cloud_control-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sig-cloud-control"
-version = "0.3.0"
+version = "0.3.2"
 description = "Control Sigenergy battery via Sigen Cloud"
 readme = "README.md"
 requires-python = ">=3.12"

sig_cloud_control-0.3.2/src/sig_cloud_control/_encryption.py

@@ -0,0 +1,24 @@
+import base64
+from typing import Final
+
+from cryptography.hazmat.primitives import padding
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+# Fixed key and IV used by Sigen Cloud
+_ENCRYPT_KEY: Final[bytes] = (b"s" + b"i" + b"g" + b"e" + b"n") * 3 + b"p"
+_ENCRYPT_IV: Final[bytes] = (b"s" + b"i" + b"g" + b"e" + b"n") * 3 + b"p"
+_CIPHER: Final[Cipher] = Cipher(
+    algorithms.AES(_ENCRYPT_KEY),
+    modes.CBC(_ENCRYPT_IV),
+)
+
+
+def encrypt_password(password: str) -> str:
+    """Encrypt a plaintext password using Sigen's AES-128-CBC logic."""
+    padder = padding.PKCS7(128).padder()
+    padded_data = padder.update(password.encode()) + padder.finalize()
+
+    encryptor = _CIPHER.encryptor()
+    ct = encryptor.update(padded_data) + encryptor.finalize()
+
+    return base64.b64encode(ct).decode()

sig_cloud_control-0.3.2/src/sig_cloud_control/cli_app/__init__.py

@@ -0,0 +1,3 @@
+from .main import app
+
+__all__ = ["app"]

sig_cloud_control-0.3.2/src/sig_cloud_control/cli_app/actions.py

@@ -0,0 +1,63 @@
+import asyncio
+import logging
+import sys
+
+import typer
+from rich.console import Console
+
+from sig_cloud_control.client import SigCloudClient, SigCloudError
+from sig_cloud_control.models import Config
+
+from .config import _resolve_config_path, load_config
+
+console = Console()
+
+
+async def execute_action(
+    config: Config,
+    action: str,
+    duration: int = 0,
+    power: float | None = None,
+    verbose: bool = False,
+) -> None:
+    """Internal helper to run the async client logic."""
+    if verbose:
+        logging.basicConfig(
+            level=logging.DEBUG,
+            format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+            stream=sys.stderr,
+        )
+
+    async with SigCloudClient(config) as client:
+        typer.echo("Logging in to Sigen Cloud...")
+        await client.login()
+
+        with console.status(f"Executing '{action}' action...", spinner="dots"):
+            if action == "charge":
+                await client.charge_battery(duration, power)
+            elif action == "discharge":
+                await client.discharge_battery(duration, power)
+            elif action == "hold":
+                await client.hold_battery(duration)
+            elif action == "self-consumption":
+                await client.self_consumption(duration)
+            elif action == "cancel":
+                await client.cancel_self_control()
+
+    console.print(f"[bold green]✔︎  [/bold green]Executing '{action}' action... [bold green]Done.[/bold green]")
+
+
+def _run_command_action(
+    action: str,
+    duration: int = 0,
+    power: float | None = None,
+    config: str | None = None,
+    verbose: bool = False,
+) -> None:
+    """Internal helper to load config and run an action."""
+    conf = load_config(_resolve_config_path(config))
+    try:
+        asyncio.run(execute_action(conf, action, duration, power, verbose))
+    except SigCloudError as e:
+        typer.secho(f"❌ Sigen API Error: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from e

sig_cloud_control-0.3.2/src/sig_cloud_control/cli_app/config.py

@@ -0,0 +1,97 @@
+import os
+import tomllib
+from enum import StrEnum
+from pathlib import Path
+from typing import NamedTuple
+
+import typer
+from pydantic import ValidationError
+
+from sig_cloud_control.models import Config, Region
+
+from .constants import _DEFAULT_CONFIG_PATH
+from .setup import perform_setup
+
+
+class SigenEnvVar(StrEnum):
+    """Sigen environment variable names.
+
+    Each member name (lowercased) is the corresponding Config field name,
+    and each value is the environment variable name.
+    """
+
+    USERNAME = "SIGEN_USERNAME"
+    PASSWORD = "SIGEN_PASSWORD"  # noqa: S105
+    PASSWORD_ENCODED = "SIGEN_PASSWORD_ENCODED"  # noqa: S105
+    STATION_ID = "SIGEN_STATION_ID"
+    REGION = "SIGEN_REGION"
+
+
+class ConfigSources(NamedTuple):
+    """The resolved configuration and the sources it was loaded from."""
+
+    env_vars_present: frozenset[SigenEnvVar]
+    config_file: Path | None
+    config: Config
+
+
+def _resolve_config_path(config_opt: str | None) -> Path:
+    """Resolve config path: explicit CLI arg > ./config.toml > platform default."""
+    if config_opt is not None:
+        return Path(config_opt)
+    local = Path("config.toml")
+    if local.exists():
+        return local
+    return _DEFAULT_CONFIG_PATH
+
+
+def _try_load_config(config_path: Path) -> ConfigSources | None:
+    """Attempt to load config from env vars and/or a TOML file.
+
+    Returns None if no valid config could be assembled (without triggering interactive setup).
+    Precedence: SIGEN_* environment variables override file values.
+    """
+    env_vars_present = frozenset(v for v in SigenEnvVar if v in os.environ)
+
+    try:
+        config = Config.model_validate({})
+        return ConfigSources(env_vars_present=env_vars_present, config_file=None, config=config)
+    except ValidationError:
+        pass
+
+    if not config_path.exists():
+        return None
+
+    try:
+        with open(config_path, "rb") as f:
+            file_data: dict[str, object] = tomllib.load(f)
+
+        # TOML parses region as a plain string; coerce to Region for strict-mode validation.
+        # (env_settings handles this automatically; init_settings does not.)
+        if "region" in file_data and isinstance(file_data["region"], str):
+            file_data["region"] = Region(file_data["region"])
+
+        # env_settings overrides init_settings per Config.settings_customise_sources.
+        config = Config(**file_data)
+        return ConfigSources(env_vars_present=env_vars_present, config_file=config_path, config=config)
+    except ValidationError as e:
+        typer.secho(
+            f"❌ Error: Invalid configuration format in '{config_path}':\n{e}",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1) from e
+
+
+def load_config(config_path: Path) -> Config:
+    """Load configuration from environment variables and/or TOML file, prompting for setup if missing."""
+    typer.echo("Loading configuration...")
+    sources = _try_load_config(config_path)
+    if sources is None:
+        typer.secho(f"⚠️  Config file not found at '{config_path}'", fg=typer.colors.YELLOW)
+        perform_setup(config_path)
+        sources = _try_load_config(config_path)
+        if sources is None:
+            typer.secho("❌ Configuration unavailable after setup.", fg=typer.colors.RED, err=True)
+            raise typer.Exit(code=1)
+    return sources.config

sig_cloud_control-0.3.2/src/sig_cloud_control/cli_app/constants.py

@@ -0,0 +1,5 @@
+from pathlib import Path
+
+from platformdirs import user_config_path
+
+_DEFAULT_CONFIG_PATH: Path = user_config_path("sig-cloud-control") / "config.toml"

sig_cloud_control-0.3.2/src/sig_cloud_control/cli_app/main.py

@@ -0,0 +1,152 @@
+import os
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.markup import escape
+
+from .actions import _run_command_action, console
+from .config import SigenEnvVar, _resolve_config_path, _try_load_config
+from .constants import _DEFAULT_CONFIG_PATH
+from .setup import perform_setup
+
+app = typer.Typer(help="Control a Sigen solar/battery station.")
+
+# Common types for CLI arguments and options to reduce duplication
+DurationArg = Annotated[int, typer.Argument(help="Duration in minutes (1-1440)", min=1, max=1440)]
+PowerOpt = Annotated[float | None, typer.Option(help="Charge/discharge rate limit for the battery in kW")]
+ConfigOpt = Annotated[str | None, typer.Option(help="Path to the TOML configuration file")]
+VerboseOpt = Annotated[bool, typer.Option("--verbose", "-v", help="Enable verbose logging")]
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context) -> None:
+    """Control a Sigen solar/battery station."""
+    if ctx.invoked_subcommand is None:
+        typer.secho("Missing command.", fg=typer.colors.RED, err=True)
+        typer.echo(ctx.get_help())
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def charge(
+    duration: DurationArg,
+    power: PowerOpt = None,
+    config: ConfigOpt = None,
+    verbose: VerboseOpt = False,
+) -> None:
+    """Charge battery from the grid for a specified duration."""
+    _run_command_action("charge", duration, power, config, verbose)
+
+
+@app.command()
+def discharge(
+    duration: DurationArg,
+    power: PowerOpt = None,
+    config: ConfigOpt = None,
+    verbose: VerboseOpt = False,
+) -> None:
+    """Discharge battery for a specified duration."""
+    _run_command_action("discharge", duration, power, config, verbose)
+
+
+@app.command()
+def hold(
+    duration: DurationArg,
+    config: ConfigOpt = None,
+    verbose: VerboseOpt = False,
+) -> None:
+    """Hold battery at its current state of charge for a specified duration."""
+    _run_command_action("hold", duration, config=config, verbose=verbose)
+
+
+@app.command(name="self-consumption")
+def self_consumption(
+    duration: DurationArg,
+    config: ConfigOpt = None,
+    verbose: VerboseOpt = False,
+) -> None:
+    """Enable self-consumption mode for a specified duration."""
+    _run_command_action("self-consumption", duration, config=config, verbose=verbose)
+
+
+@app.command()
+def cancel(
+    config: ConfigOpt = None,
+    verbose: VerboseOpt = False,
+) -> None:
+    """Return the battery to its configured default mode."""
+    _run_command_action(action="cancel", config=config, verbose=verbose)
+
+
+@app.command()
+def setup(
+    config: Annotated[str | None, typer.Option(help="Path to the TOML configuration file to create")] = None,
+) -> None:
+    """Interactively setup credentials and save to config file."""
+    config_path = Path(config) if config else _DEFAULT_CONFIG_PATH
+    if config_path.exists():
+        typer.secho(
+            f"⚠️  Warning: Configuration file '{config_path}' already exists and will be overwritten.",
+            fg=typer.colors.YELLOW,
+        )
+
+    perform_setup(config_path)
+
+
+@app.command(name="show-config")
+def show_config(
+    config: ConfigOpt = None,
+) -> None:
+    """Show the current configuration and where it was loaded from."""
+    config_path = _resolve_config_path(config)
+    sources = _try_load_config(config_path)
+
+    if sources is None:
+        env_vars_present = frozenset(v for v in SigenEnvVar if v in os.environ)
+        local_config = Path("config.toml")
+        console.print("\n[bold yellow]⚠️  No configuration found.[/bold yellow]")
+        console.print("\n[bold]Locations checked:[/bold]")
+        if not env_vars_present:
+            all_vars = ", ".join(sorted(SigenEnvVar))
+            console.print(f"  Environment vars:  {all_vars} — [yellow]none set[/yellow]")
+        else:
+            set_vars = ", ".join(sorted(env_vars_present))
+            console.print(f"  Environment vars:  {set_vars} set, but insufficient")
+        local_status = "[yellow]not found[/yellow]" if not local_config.exists() else "found"
+        console.print(f"  Local config:      [repr.path]./config.toml[/repr.path] — {local_status}", highlight=False)
+        default_status = "[yellow]not found[/yellow]" if not _DEFAULT_CONFIG_PATH.exists() else "found"
+        console.print(
+            f"  Default config:    [repr.path]{escape(str(_DEFAULT_CONFIG_PATH))}[/repr.path] — {default_status}",
+            highlight=False,
+        )
+        console.print("\nRun [bold]sig-cloud-control setup[/bold] to create a configuration file.")
+        raise typer.Exit(code=1)
+
+    console.print("\n[bold]Sources:[/bold]")
+    if sources.config_file is not None:
+        console.print(
+            f"  Config file:       [repr.path]{escape(str(sources.config_file))}[/repr.path]", highlight=False
+        )
+    else:
+        console.print("  Config file:       [dim](not used — env vars were sufficient)[/dim]")
+
+    if sources.env_vars_present:
+        console.print(f"  Environment vars:  {', '.join(sorted(sources.env_vars_present))}")
+    else:
+        console.print("  Environment vars:  [dim](none)[/dim]")
+
+    console.print("\n[bold]Configuration:[/bold]")
+    console.print(f"  Username:          {sources.config.username}")
+
+    if sources.config.password is not None:
+        console.print("  Password:          [dim]*** (plaintext)[/dim]")
+    elif sources.config.password_encoded is not None:
+        console.print("  Password:          [dim]*** (encoded)[/dim]")
+
+    if sources.config.station_id is not None:
+        console.print(f"  Station ID:        {sources.config.station_id}")
+    else:
+        console.print("  Station ID:        [dim](auto-detect)[/dim]")
+
+    console.print(f"  Region:            {sources.config.region.value}")

sig_cloud_control-0.3.2/src/sig_cloud_control/cli_app/setup.py

@@ -0,0 +1,54 @@
+import os
+from pathlib import Path
+
+import tomli_w
+import typer
+
+from sig_cloud_control._encryption import encrypt_password
+from sig_cloud_control.models import Region
+
+
+def perform_setup(config_path: Path) -> None:
+    """Interactively prompt for credentials and save to file."""
+    typer.echo(f"Setting up new configuration at '{config_path}'...")
+    username = typer.prompt("Sigen Cloud login name (eg. user@example.com)")
+    password = typer.prompt("Sigen Cloud Password", hide_input=True)
+    _region_labels: dict[Region, str] = {
+        Region.AUS: "Australia / New Zealand",
+        Region.APAC: "Asia-Pacific",
+        Region.EU: "Europe",
+        Region.CN: "China",
+        Region.US: "United States",
+    }
+    _regions = list(Region)
+    typer.echo("Select your region (check your Sigenergy app Settings->System Settings->About):")
+    for i, r in enumerate(_regions, 1):
+        typer.echo(f"  {i}. {r.value:<6} {_region_labels[r]}")
+    while True:
+        _choice = typer.prompt(f"Region [1-{len(_regions)}]", type=int)
+        if 1 <= _choice <= len(_regions):
+            region = _regions[_choice - 1]
+            break
+        typer.secho(f"Please enter a number between 1 and {len(_regions)}.", fg=typer.colors.RED)
+    station_id_str = typer.prompt("Station ID (optional, press Enter to skip)", default="")
+
+    password_encoded = encrypt_password(password)
+
+    station_id = int(station_id_str) if station_id_str.strip().isdigit() else None
+
+    config_data: dict[str, object] = {
+        "username": username,
+        "password_encoded": password_encoded,
+        "region": region.value,
+    }
+    if station_id:
+        config_data["station_id"] = station_id
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(config_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "wb") as f:
+        tomli_w.dump(config_data, f)
+
+    typer.secho("✔︎  ", fg=typer.colors.GREEN, bold=True, nl=False)
+    typer.secho(f"Success! Configuration saved to {config_path}", fg=typer.colors.GREEN)
+    typer.echo("Note: Your password has been encrypted for storage.")

sig_cloud_control-0.3.2/src/sig_cloud_control/client/__init__.py

@@ -0,0 +1,15 @@
+from .core import SigCloudClient
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    SigCloudError,
+    StationError,
+)
+
+__all__ = [
+    "APIError",
+    "AuthenticationError",
+    "SigCloudClient",
+    "SigCloudError",
+    "StationError",
+]

sig_cloud_control-0.3.2/src/sig_cloud_control/client/cache.py

@@ -0,0 +1,51 @@
+import asyncio
+import os
+import time
+from pathlib import Path
+from typing import Final
+
+from platformdirs import user_cache_path
+from pydantic import ValidationError
+
+from ..models import TokenCache
+
+_DEFAULT_CACHE_PATH: Final[Path] = user_cache_path("sig-cloud-control") / "token-cache.json"
+
+
+async def load_cache(cache_path: Path | None) -> TokenCache | None:
+    """Load the token from the cache file if it exists and is valid."""
+    if cache_path is None:
+        return None
+    try:
+        content = await asyncio.to_thread(cache_path.read_text)
+        return TokenCache.model_validate_json(content)
+    except (FileNotFoundError, ValidationError):
+        return None
+    except Exception:
+        return None
+
+
+def _write_cache_file(cache_path: Path, content: str) -> None:
+    """Helper to write the cache file securely with restricted permissions."""
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(cache_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        f.write(content)
+
+
+async def save_cache(
+    cache_path: Path | None,
+    access_token: str | None,
+    expires_in_secs: int,
+    station_id: int | None,
+) -> None:
+    """Save the current token and station ID to the cache file."""
+    if cache_path is None or access_token is None:
+        return
+    cache = TokenCache(
+        access_token=access_token,
+        expires_at=time.time() + expires_in_secs,
+        station_id=station_id,
+    )
+    content = cache.model_dump_json()
+    await asyncio.to_thread(_write_cache_file, cache_path, content)