Conow Energy

Conow Smart Energy Skill

Basic Information

• Authentication: Via Header Authorization: Bearer {Api-key}
• Credentials: Read from environment variable CONOW_API_KEY. Base URL is auto-detected from the API key prefix (see Base URL Auto-detection below). You can override by setting CONOW_BASE_URL.
• API Reference: See references/api_reference.md
• Skill Manifest: See references/skill_manifest.md
• Python CLI: See scripts/conow_cli.py

Environment Variable Configuration

Set the following environment variable before use:

export CONOW_API_KEY="your-conow-api-key"
# CONOW_BASE_URL is optional — auto-detected from the sk- key prefix.
# Set it only if your deployment provides a dedicated gateway URL, e.g.:
# export CONOW_BASE_URL="https://openapi.tuyaeu.com"

Optional variables:

| Env var | Flag | Purpose | |--------------------|----------------|------------------------------------------------------| | CONOW_API_KEY | --api-key | Required. Bearer token starting with sk-. | | CONOW_BASE_URL | --base-url | Override gateway URL. | | CONOW_HOME_ID | --home-id | Default home_id for queries. | | CONOW_HOMES_PATH | --homes-path | Override list-homes path (default /v1.0/end-user/homes/all). | | CONOW_TIMEZONE | --timezone | Force timezone; otherwise auto-derived from home/station. |

The skill will not load if CONOW_API_KEY is missing. Never echo the raw key back to the user.

Base URL Auto-detection

When CONOW_BASE_URL is not set, the CLI selects a production data center by the sk- key prefix:

| Prefix | Base URL | |-----------|---------------------------------------| | sk-AY | https://openapi.tuyacn.com | | sk-AZ | https://openapi.tuyaus.com | | sk-EU | https://openapi.tuyaeu.com | | sk-IN | https://openapi.tuyain.com | | sk-UE | https://openapi-ueaz.tuyaus.com | | sk-WE | https://openapi-weaz.tuyaeu.com | | sk-SG | https://openapi-sg.iotbing.com |

Usage

Always prefer Method 1 (Command Line). It handles authentication, URL resolution, JSON serialization, and error handling automatically.

Method 1: Via Command Line (Recommended)

python3 {baseDir}/scripts/conow_cli.py  [params...]
# Examples:
python3 {baseDir}/scripts/conow_cli.py list-homes
python3 {baseDir}/scripts/conow_cli.py resolve-home --home-name "My Home"
python3 {baseDir}/scripts/conow_cli.py indicators-list --energy-type electricity
python3 {baseDir}/scripts/conow_cli.py indicators-aggregate \
  --home-id  --date-type day \
  --begin-date 20260420 --end-date 20260420 \
  --indicator-code ele_consumption_sol --time-aggr-type sum
python3 {baseDir}/scripts/conow_cli.py indicators-trend --home-id  ...
python3 {baseDir}/scripts/conow_cli.py indicators-top --home-id  ...
python3 {baseDir}/scripts/conow_cli.py forecast --home-id  \
  --begin-date  --end-date 
python3 {baseDir}/scripts/conow_cli.py tariff-query --home-id  ...
python3 {baseDir}/scripts/conow_cli.py tariff-label --home-id  ...
python3 {baseDir}/scripts/conow_cli.py conow-flow --home-id 
python3 {baseDir}/scripts/conow_cli.py conow-power-curve --home-id  ...
python3 {baseDir}/scripts/conow_cli.py conow-impact --home-id  ...
python3 {baseDir}/scripts/conow_cli.py conow-indicators
python3 {baseDir}/scripts/conow_cli.py conow-station --home-id 

Use python3 {baseDir}/scripts/conow_cli.py --help for the full command list.

Feature Overview

| Module | Capabilities | Endpoints | |--------|-------------|-----------| | Home Discovery | List homes, fuzzy-resolve home by name | /v1.0/end-user/homes/all | | Indicator Metadata | Platform indicator dictionary, filter by energy type / keyword | /v1.0/end-user/energy/indicators | | Aggregate / Trend / Top | Sum, average, time-series and ranking on indicator codes | /v1.0/end-user/energy/indicators/aggregate|trend|top | | Forecast | Hour-granular next-N-hour predictions (≤ 48h, ≤ 2 codes) | /v1.0/end-user/energy/forecast | | Tariff | Tariff price and high/medium/low labels | /v1.0/end-user/energy/tariff/query|label | | Home Real-time / Curve / Impact | Real-time flow, power curve, optimization impact, home indicator dict, station metadata | /v1.0/end-user/energy/home/flow|power-curve|impact|indicators|station |

Routing Cheatsheet

| User intent | Default command | Notes | |-------------|-----------------|-------| | "What is my home using right now?" / "Am I importing or exporting?" | conow-flow; if unsupported, fall back to same-day indicators-aggregate | The fallback is kWh aggregation, not real-time power. | | "How much did I use today / this month?" | indicators-aggregate | Use the consumption SOL quartet for home totals. | | "How much solar did I generate?" | indicators-aggregate | Use the produce SOL quartet for home totals. | | "Battery SOC?" / "Is the battery charging or discharging?" with no devId | indicators-aggregate / trend with ele_store_percent, or conow-flow | Home-asset overview without a device. | | "Which device used the most this week?" | indicators-top | --group-by device --indicator-code ele_usage. | | "Is the current tariff high or low?" / "Tariff for tomorrow?" | tariff-query + tariff-label | Provide window and direction (import/export). | | "How much will my solar produce in the next day?" | forecast | Hour-only, ≤ 48h window, anchor --begin-date at the current hour or later. | | "When is electricity cheapest?" | tariff-query plus optional forecast | Rule-based advice; do not claim exact savings unless an endpoint returns it. | | "How much did optimization save me?" | conow-impact | If unavailable, explain the missing baseline; do not fabricate. |

When the user's query is in English, Chinese, or mixed language, the same routing applies. Reply in the user's language; keep home_id, devId, indicator codes, and gateway error codes unchanged.

Core Workflows

Workflow 1: Resolve a Home

home_id is required by every energy endpoint, but never ask the user for home_id as the first move — talk in terms of home names.

1. If the user already provided a home_id, or CONOW_HOME_ID is set, use it silently.
2. Otherwise call resolve-home (or list-homes):

• If exactly one home is returned, auto-select it and tell the user which one.
• If several are returned, ask the user by name. Show home_id only if the user requests it or if names collide.
• Pass partial names via --home-name; the CLI fuzzy-matches.

1. If list-homes fails, ask the user for a home_id directly and tell them where to find it (e.g. App settings / admin console).

python3 {baseDir}/scripts/conow_cli.py resolve-home
python3 {baseDir}/scripts/conow_cli.py resolve-home --home-name "My Home"
python3 {baseDir}/scripts/conow_cli.py list-homes

resolve-home returns:

• {"success": true, "home_id": "..."} — safe to proceed.
• {"success": false, "error": "...", "candidates": [...]} — a normal "ask which home" outcome, not a gateway error. The CLI exits 0 here (no stderr "gateway returned success=false"). Present candidates[].name to the user and let them pick. On an ambiguous name match, candidates lists only the matched subset; on a genuine not-found or a multi-home account with no --home-name, candidates lists all homes.

home_id is a numeric string (e.g. "100200300"). Pass it verbatim to downstream endpoints. Non-numeric strings are rejected with 1109.

> --home-name wins over a CONOW_HOME_ID default — if you pass --home-name, the CLI resolves the name even when CONOW_HOME_ID is set. CONOW_HOME_ID is only used as the default when no --home-name is given.

Workflow 2: Resolve Home Timezone

For statistics windows, prefer the home's timezone over the agent or machine timezone. The CLI applies it automatically — but only for indicators-aggregate, indicators-trend, and indicators-top:

• These three first use --timezone / CONOW_TIMEZONE if set.
• Otherwise they call POST /v1.0/end-user/energy/home/station to read time_zone_id and inject timezone into the body. When this auto-fill happens, the CLI prints a one-line stderr note naming the station timezone, e.g. [conow] using home station timezone Europe/Berlin for date windows.
• If station lookup fails or omits time_zone_id, the request continues without timezone; do not fail the user-facing query.
• forecast, tariff-query, tariff-label, conow-flow, and conow-power-curve do NOT auto-fill the timezone — they use --timezone / CONOW_TIMEZONE verbatim (or the home default server-side). For these, pass --timezone yourself when the window boundary matters.

Watch the stderr note: a home's station timezone can differ from its physical location (e.g. a CN home configured as Europe/Berlin). When the named station tz looks wrong for the user's locale, caveat relative windows like "today" / "this month", or pass an explicit --timezone.

python3 {baseDir}/scripts/conow_cli.py conow-station --home-id 

Workflow 3: Aggregate / Trend / Top

python3 {baseDir}/scripts/conow_cli.py indicators-aggregate \
  --home-id  \
  --date-type day --begin-date 20260420 --end-date 20260420 \
  --indicator-code ele_consumption_sol,ele_produce \
  --time-aggr-type sum

python3 {baseDir}/scripts/conow_cli.py indicators-trend \
  --home-id  \
  --date-type day --begin-date 20260414 --end-date 20260420 \
  --indicator-code ele_consumption_sol

python3 {baseDir}/scripts/conow_cli.py indicators-top \
  --home-id  \
  --date-type month --begin-date 202604 --end-date 202604 \
  --indicator-code ele_usage \
  --group-by device --number 5

Wire-format rules (the CLI normalizes input):

• --indicator-code accepts repeated flags or a comma-separated list. The CLI joins to a single "a,b,c" string. Max 20 codes per request.
• --time-aggr-type / --device-aggr-type are UPPERCASE on the wire (SUM/AVG/MAX/MIN).
• --date-type is lowercase on the wire. Valid values are quarter/hour/day/month/year only — there is no week. The CLI rejects week locally at argparse (choices=quarter/hour/day/month/year, exit 2) before any HTTP call, so it never reaches the gateway. (Historically the raw API returned 501 for week; that observation no longer applies via the CLI.) For a weekly total, use --date-type day over the 7-day range with --time-aggr-type sum; for finer-than-hour granularity use quarter (15-minute buckets, yyyyMMddHHmm).
• indicators-top requires a singular --indicator-code, plus --group-by (device / space / usage) and --number in [1, 50]. Optional --sort-type is asc/desc (default desc).
• Use --ext-condition '{"deviceIds":["..."]}' for documented dimension or device filters.

Workflow 4: Forecast

POST /v1.0/end-user/energy/forecast constraints:

• Hour granularity only. Both begin_date and end_date must be yyyyMMddHH (10 digits).
• Maximum 48-hour window (inclusive). Longer windows silently return an empty list.
• Past-only windows return an empty list (no error). Anchor --begin-date at the current hour or later.
• Up to 2 indicator codes per request, drawn from ele_forecast_produce and ele_forecast_consumption. The CLI defaults to both when --indicator-code is omitted.

python3 {baseDir}/scripts/conow_cli.py forecast \
  --home-id  \
  --begin-date  --end-date 

# Single indicator
python3 {baseDir}/scripts/conow_cli.py forecast \
  --home-id  \
  --indicator-code ele_forecast_produce \
  --begin-date  --end-date 

# Bypass forecast cache for fresh predictions
python3 {baseDir}/scripts/conow_cli.py forecast \
  --home-id  \
  --begin-date  --end-date  \
  --use-cache false

Response shape (one entry per requested indicator):

{
  "success": true,
  "result": [
    {
      "indicator": "ele_forecast_produce",
      "totalValue": { "Value": "12.34" },
      "unit": "kWh",
      "list": [
        { "date": "2026042710", "unit": "kWh", "value": { "Value": "0.00" } }
      ]
    }
  ]
}

Workflow 5: Tariff

tariff-query and tariff-label are POST JSON.

python3 {baseDir}/scripts/conow_cli.py tariff-query \
  --home-id  \
  --date-type hour --begin-date 2026042100 --end-date 2026042200 \
  --direction import

python3 {baseDir}/scripts/conow_cli.py tariff-label --home-id  --direction import

Workflow 6: Home Real-time / Curve / Impact

python3 {baseDir}/scripts/conow_cli.py conow-flow --home-id 

python3 {baseDir}/scripts/conow_cli.py conow-power-curve --home-id  \
  --date-type day --begin-date 20260420 --end-date 20260420 \
  --indicator-code home_total_load_power,home_total_grid_port_power

# Weekly impact: use date-type day across the 7-day range (there is no `week`).
python3 {baseDir}/scripts/conow_cli.py conow-impact --home-id  \
  --date-type day --begin-date 20260414 --end-date 20260420 \
  --phone-code CN

python3 {baseDir}/scripts/conow_cli.py conow-indicators
python3 {baseDir}/scripts/conow_cli.py conow-station --home-id 

conow-flow and conow-power-curve return power values with their own payload units (typically W in power-curve). Do not convert or relabel units unless you have verified the payload.

Live response-shape notes (do not assume the richer shapes are always present):

• conow-flow: the rich fields (grid_status, has_grid, the indicators[] array with per-device breakdowns and soc) appear only when the home has live device telemetry. Otherwise the gateway returns just {"soc_count": 0} with success=true. When the flow snapshot is empty, fall back to a same-day indicators-aggregate and tell the user it's an aggregate, not real-time power.
• conow-flow implausible-value flags: the CLI annotates suspect power readings. A reading equal to a 32-bit sentinel (e.g. 2863311530 W = 0xAAAAAAAA uninitialized/NaN, or 0xFFFFFFFF) or above a 100 MW cap gets a "_suspect" field on that item, and the payload gains a top-level "_warnings" list naming each flagged value. Trust these flags: do NOT quote a flagged value as live power — treat that device/indicator as unreported and prefer a same-day indicators-aggregate (kWh) instead, telling the user the live reading was unavailable.
• conow-impact: read both wrapped and bare forms — carbon_reduction and total_ele_produce_cost may be wrapped as {"Value": "..."}, while total_ele_produce is a bare number; self_sufficiency may come back empty ({}). Do not assume the percent splits sum to 100, and skip self-sufficiency reporting when it's unavailable.
• energy_production.ele_unit is mislabeled "W" but the accompanying total_ele_produce is an energy total in Wh — divide by 1000 for kWh, not by any power-to-energy conversion. Report kWh; do not quote it as watts.
• --phone-code wants an ISO 3166 alpha-2 code (CN / SE / DE), and it is NOT validated — a numeric dialing code like 86 is silently accepted and quietly changes the carbon-reduction factor (wrong figure, no error). Always pass the alpha-2 country code, never a dial code.
• conow-station: time_zone_id is an IANA timezone — use it as the timezone field in statistics calls. country_code may be alpha-3 (e.g. CHN), whereas conow-impact --phone-code wants ISO 3166 alpha-2 (e.g. CN, SE). Map / confirm the code before passing it to impact; do not copy country_code verbatim.

Indicator Reference

Consumption SOL Quartet (home electricity consumption, default for home totals)

For home-level questions about how much electr

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: conow-labs
• Source: conow-labs/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.