Power Trace — Configuration Guide

📖 Before You Start

Power Trace is a local real-time energy monitoring system for tracking electricity consumption through a Tuya-compatible smart relay (such as Atorch GR2PWS or any device that supports Tuya Local Protocol). It runs entirely on your own computer — no cloud servers, no real-time internet connection required.

What you need

A Tuya-compatible relay connected to Wi-Fi. The device must already be paired with your home network using the Tuya or Smart Life app. Once on Wi-Fi it is reachable on your local network at a specific IP address.

A Tuya IoT Platform account (optional but recommended). A free developer account at iot.tuya.com lets Power Trace fetch the Device ID and Local Key automatically. If you already have those credentials you can skip the account and enter them manually.

Your electricity tariff. To calculate cost, you need the price per kilowatt-hour from your electricity bill. If you are on a time-of-use (day/night) tariff, you will need both rates and their time boundaries.

✅ Where to start: fill in the Device section (or auto-fill via Tuya Cloud scan), fill in Billing, click Save Configuration, then restart the collector. Everything else is optional.

☁ Tuya Cloud One-time setup

This section is used to automatically retrieve the Device ID, IP address and Local Key of your relay from the Tuya cloud. If you already have those credentials, skip this section and go straight to Device.

How to get API keys from iot.tuya.com

Go to iot.tuya.com and create a free account, or sign in with the same credentials you use in the Tuya / Smart Life app on your phone.

In Cloud → Development, click Create Cloud Project. Give it any name, choose type Smart Home, and select the data center region that matches your Tuya account region.

On the project overview page you will see Access ID and Access Secret. Copy them into the corresponding fields in Power Trace Settings.

In project settings open Devices → Link Tuya App Account and connect your Tuya / Smart Life account. Your devices will become visible in the project.

Return to Power Trace Settings, enter Access ID, Access Secret, choose the region and click 🔍 Scan Devices. Power Trace fetches your devices from the cloud and simultaneously scans the local network for their IP addresses.

Access ID

The identifier of your Cloud Project on iot.tuya.com. A long alphanumeric string, for example p7n8fk3x2q...

Access Secret

The secret key of the project. Stored encrypted — the field shows a mask ••••XXXX. Click the 👁 button to temporarily reveal it.

The data center region you selected when setting up your Tuya account. Most commonly Europe (eu). If a scan returns an error, try a different region.

🔒 The Access Secret is stored in an encrypted file (secret.key) on your computer and is never sent anywhere other than Tuya's servers during a scan.

📟 Device Required

The core section. Without filling in these fields the collector cannot connect to the relay and no data will be collected. If you used the Tuya Cloud scan and clicked Use this device, most fields will be auto-filled.

Device Name

A name you choose yourself. Shown in the dashboard header instead of the default "Power Trace". For example: Apartment, Workshop, Panel #2.

Device ID

The unique identifier of your relay in the Tuya system. A long alphanumeric string, for example bfefafdde42999f1887ghk. Found in the Tuya / Smart Life app or retrieved via the cloud scan.

IP Address

The local IP address of the relay on your Wi-Fi network, for example 192.168.0.114. Required for a direct local connection. If the scan did not find an IP, check the DHCP client list in your router's admin panel, or assign a static IP to the device.

Local Key

The encryption key for Tuya Local Protocol. Without it the device will reject every connection. Obtained via the cloud scan or from the device details on iot.tuya.com. Stored encrypted — the field shows only a mask.

Device Profile

The model of your device. Defines which numbers mean what in the data stream from the relay — for example, DPS 6 = power in tenths of a watt. Select the matching model from the list. If your model is not listed, refer to the documentation.

Protocol Version

The Tuya Local Protocol version. Most modern devices use 3.5. If the connection fails, try 3.4 or 3.3. The version can usually be found in your device's specifications.

⚠ After changing Device ID, IP, Local Key, or Protocol Version you must restart the collector using ⟳ Restart Collector in the Collector section for the changes to take effect.

📡 Collector Rarely needs changing

The collector is the background process that connects to the relay and writes data to the database. The default values work fine for most setups — only change them if you have a specific reason.

⚠ Incorrect values may cause data loss or collector malfunction.

DB Flush Interval (sec)

Range: 2–300, default: 10. How often buffered data is written from memory to disk. A lower value means more frequent writes and better protection against sudden power loss. A higher value means less disk activity.

Peak Window (samples)

Range: 1–100, default: 10. The size of the sliding window used to track peak power and current. At a ~60-second device tick: 10 samples = peak over the last 10 minutes. A larger value means the system remembers peaks for longer.

Stall Threshold (minutes)

Range: 1–120, default: 15. How long the relay must remain unreachable before the dashboard shows a "device unreachable" warning. Until this threshold is reached, the status only shows "reconnecting".

⟳ Restart Collector

Restarts the background collector process. Press this after changing any parameters in the Device or Collector sections, and also if the collector is stuck or fails to connect. Always save your configuration first — otherwise the restart will use the old parameters.

🔄 Connection Recovery Rarely needs changing

These control the collector's internal reconnection logic — how it detects a lost or silent connection to the relay, and how it escalates from a quick retry to a full network rescan. The defaults are tuned to the relay's ~60-second tick interval and work fine for most setups.

⚠ Wrong values may cause the collector to reconnect too aggressively, or fail to recover from a dropped connection. These settings are read only when the collector starts — save your configuration, then press ⟳ Restart Collector below for changes to take effect.

Connection Timeouts

Connect Timeout (sec)

Range: 3–30, default: 10. How long to wait for the device to answer a connection/status probe before giving up and retrying.

Subscribe Timeout (sec)

Range: 3–30, default: 10. How long to wait for the device to acknowledge the push-data subscription request.

Data Wait

First Packet Deadline (sec)

Range: 30–600, default: 150. How long to wait for the first data packet after subscribing before treating the connection as silent. The relay ticks every ~60s — keep this above that.

Stream Silence Timeout (sec)

Range: 30–600, default: 190. Maximum silence allowed once streaming is already established, before the collector treats the connection as lost and starts recovering.

Stable Stream Reset (sec)

Range: 30–600, default: 180. How long the stream must run uninterrupted before retry and backoff counters reset to their starting values. Prevents a flapping connection from permanently escalating.

Backoff & Escalation

Backoff Start (sec)

Range: 1–60, default: 5. Starting delay before the first reconnect attempt after a failure.

Backoff Cap (sec)

Range: 30–1800, default: 300. Maximum delay between reconnect attempts. The delay doubles after each failure, up to this cap — it never grows unbounded.

Tier 0 Max Retries

Range: 0–10, default: 2. How many times to retry just re-subscribing to push data (cheap, no reconnect) before falling back to a full reconnect.

Rescan After (failures)

Range: 1–10, default: 3. How many full reconnect failures in a row before scanning the local network for the device — useful if its IP address changed (e.g. after a router reboot with DHCP).

Hard Reset After (sec)

Range: 300–86400, default: 1800. How long the collector can stay disconnected before performing a full internal reset, or restarting the process entirely if it is running under a supervisor (PowerTrace on Windows, systemd on Linux/Raspberry Pi).

LAN Rescan

Scan Watchdog (sec)

Range: 10–120, default: 60. Maximum time allowed for a single LAN scan attempt before giving up and falling back to the normal backoff schedule.

Scan Listen Time (sec)

Range: 5–60, default: 18. How long to listen for device broadcasts during a single LAN scan.

⟳ Restart Collector

Same button as in the Collector section above — recovery settings are read only when the collector process starts, so press this after saving any changes here.

🖥️ Server Rarely needs changing

Controls the network port for the local API server that the dashboard and Settings page talk to. Most setups never need to touch this.

⚠ Be careful changing this port — if it conflicts with another app on this machine, or is blocked by a firewall, the server may fail to come back up after restart. The dashboard URL (and any bookmarks, Tailscale links, or reverse-proxy rules pointing to the old port) will stop working until updated.

API Server Port

Range: 1–65535, default: 8000. The network port the dashboard and API listen on. Change this only if port 8000 is already used by another program on your computer. Takes effect only after clicking ⟳ Restart Server below — the ⟳ Restart Collector button does not apply it, and the dashboard address changes to the new port once it restarts.

Reverse proxy — allowed hostnames

Power Trace refuses configuration changes that arrive under an unexpected hostname. This blocks DNS rebinding, an attack where a web page you visit tricks your browser into sending commands to devices on your home network. Local addresses are trusted automatically: localhost, any private LAN address (192.168.x.x, 10.x.x.x, 172.16–31.x.x), Tailscale addresses and *.ts.net names, and *.local names. You do not need to configure anything for a normal setup.

If you put Power Trace behind a reverse proxy on a public domain, that domain is not local and is therefore not trusted by default. Saving settings then fails with host_not_allowed. Add your domain to config.yaml by hand and restart the server:

server.allowed_hosts

A list of extra hostnames to trust, edited directly in config.yaml (there is no field for it in Settings). Example: server: → allowed_hosts: ["power.example.com"]. List the hostname only — no scheme and no port. Reading the dashboard is never blocked; only requests that change something are.

⚠ Restarts the whole API server (not just the collector) — the dashboard will briefly disconnect.

🧾 Billing Required

Defines how the cost of electricity consumption is calculated. Without filling in this section the dashboard will show dashes in the Bill and Total Energy fields.

House Timezone

Timezone

Selected from a list of all IANA time zones. Detected automatically from your browser on first open. Set this correctly if you use a time-of-use tariff — the system uses it to determine local time and assigns each kWh to the correct day or night zone. Change it only if the server runs in a different location than the house.

Tariff Mode

Single-zone — flat rate

All electricity is billed at the same price regardless of time of day.

Tariff (per kWh) — the price of one kilowatt-hour, e.g. 0.32 or 4,32 (both dot and comma accepted).
Currency Symbol — e.g. $, €, or ₴.

Two-zone — time-of-use tariff (day / night)

Different prices apply during daytime and nighttime hours.

Zone 1 (day) — From / To: the start and end of the daytime rate, e.g. 07:00 – 23:00. Wrap-around is supported: if the night zone crosses midnight, define Zone 1 as the daytime hours and the system fills in Zone 2 automatically.

Zone 1 Rate / Zone 2 Rate: price per kWh for each zone. Zone 2 time boundaries fill in automatically as the inverse of Zone 1.

Currency Symbol is shared between both zones.

Thresholds

Warning threshold (kWh)

When consumption for the selected period exceeds this value, the figure on the dashboard is highlighted yellow.

Alert threshold (kWh)

When consumption exceeds this value, the figure is highlighted red. Must be greater than the Warning threshold.

🎨 Appearance — Colors Optional

Colors for chart lines, card values, and bars. The defaults are tuned for the dark theme. Each color can be set with the color picker or by typing a HEX code (e.g. #4caf50). Both stay in sync.

Metrics

Power, Voltage, Current, Power Factor, Total Energy, Bill — the color of the line or bar and the live value in each card on the dashboard.

Thresholds

Warning and Alert — highlight colors used when the consumption thresholds from the Billing section are exceeded.

Day / Night Billing

Appears only when Two-zone is selected in Billing. Sets separate colors for daytime and nighttime consumption on the stacked Energy and Bill charts.

🏷️ Appearance — Labels Optional

All text labels in the interface. Use these to adapt terminology to your own wording — Consumption instead of Total Energy, or a different unit style.

💡 These fields are not how you translate the interface — pick a language pack under Interface Language below instead. Leave a field empty to use the label from that pack; the grey placeholder shows what will be used. Only fields you actually type into are written to config.yaml, so they survive a language change.

Metric Names

Names shown in the dashboard cards and on the chart tabs: Power, Voltage, Current, Power Factor, Total Energy, Bill, and System (the tile showing grid frequency and device temperature).

Units

Units of measurement: W, V, A, kWh, Hz. Change only for localisation. kW·h instead of kWh.

Labels

System labels: Live, Min, Max, Avg. Also the text of the Apply ▸ button and the Estimated data note — the warning shown above the Energy and Bill charts when some bars are estimated rather than measured (see Dashboard → Estimated Bar Threshold).

Date Range Controls

Labels for the date range buttons: DATE RANGE, Today, Yesterday, Month, Year, Custom.

Scope

Labels for the live-window mode: SCOPE and the suffixes m (minutes) and h (hours) used in the 30m / 1h / 2h buttons.

Day / Night Billing

Appears only with Two-zone billing. Labels for the Day / Night / Both switcher on the Energy and Bill charts.

Interface Language

Sets the language of the whole interface — dashboard, Settings, Rules, the Analysis report and the tray menu. The dropdown lists every pack found in the lang/ folder next to config.yaml; adding a language means dropping a JSON file there, with no rebuild. A pack that is only partly translated shows its progress in the dropdown, and any key it lacks falls back to English. Saving reloads the page.

Chart Locale

Separate from the interface language, and deliberately so: it controls the language of month names on chart axes and in tooltips, and the two are often not the same. Enter a locale tag in the standard language-REGION form — uk-UA, de-DE, en-US (the IETF BCP 47 format). A live preview below the field shows all 12 month names in real time.

Locale tag	Language	Month names (Jan → Dec)
`en-US`	English	Jan · Feb · Mar · Apr · May · Jun · Jul · Aug · Sep · Oct · Nov · Dec
`uk-UA`	Ukrainian	Січ · Лют · Бер · Кві · Тра · Чер · Лип · Сер · Вер · Жов · Лис · Гру
`de-DE`	German	Jan · Feb · Mär · Apr · Mai · Jun · Jul · Aug · Sep · Okt · Nov · Dez
`fr-FR`	French	janv. · févr. · mars · avr. · mai · juin · juil. · août · sept. · oct. · nov. · déc.
`zh-CN`	Chinese (Simplified)	1月 · 2月 · 3月 · 4月 · 5月 · 6月 · 7月 · 8月 · 9月 · 10月 · 11月 · 12月

🕐 Display Format Optional

How time, date, and temperature are displayed on the dashboard.

Time

Clock

24-hour — standard format: 14:05.
12-hour — AM/PM format: 2:05 PM. When selected, AM label and PM label fields appear so you can localise the suffixes.

Leading zero

Whether to pad single-digit hours with a zero. On: 02:05. Off: 2:05.

Date

Format

Nine combinations of DD/MM/YYYY with different separators (hyphen, slash, dot). A live preview shows how 5 June 2026 looks in the selected format.

Units

Temperature

°C or °F. Affects how the relay's onboard temperature is shown in the System tile. Conversion is automatic.

🧮 Aggregation Optional

Applies only to Month, Year, and Custom modes when the range spans more than 2 days. Controls which single value represents each day or month on the Power, Voltage, Current, and Power Factor charts.

AVG — Average

The mean value over the day or month. Best suited for Power and Voltage — gives a sense of the typical load level throughout the period.

MAX — Peak

The highest value recorded during the day or month. Best suited for Current — knowing peak current is important when assessing wiring and breaker capacity.

MIN — Minimum

The lowest value recorded. Useful for Voltage — the minimum daily voltage reveals grid dips that might affect sensitive equipment.

💡 The Energy and Bill charts are not affected — they always show the total actual consumption for each day or month.

📊 Dashboard Rarely needs changing

Live Status Timeout (sec)

Range: 60–300, default: 120.

How many seconds after the last received data packet the dashboard switches to OFFLINE. The relay sends new data approximately once every 60 seconds — a firmware limit. The default of 120 s covers two missed transmissions in a row.

When to increase: if your relay is on an unstable Wi-Fi connection. For example, 180 s allows three missed ticks before going offline.
Do not set below 60 seconds — the dashboard will flicker between ONLINE and OFFLINE.

Chart Point Spacing (px)

Range: 2–12, default: 4.

The minimum horizontal width, in pixels, given to each data point on the charts. Charts scroll horizontally once the points no longer fit — this setting controls how spread out they are.

Higher values spread points further apart, making individual ticks easier to read but requiring more scrolling. Lower values fit more of the day on screen at once, at the cost of more tightly packed points.

Chart Gap Threshold (min)

Range: 0–60, default: 5.

How long a silence has to last before the chart line is broken instead of drawn straight through. Power Trace records every tick the relay sends, so a stretch with no records means the collector genuinely received nothing — a power cut, a Wi-Fi drop, or the application not running. Joining those points with a smooth line would make a blackout look like a steady reading.

Setting it to 0 disables breaks entirely and always draws a continuous line.

Do not set below 3 minutes. The relay reports roughly once every 60 seconds and the interval drifts, so a low threshold marks ordinary jitter as an outage and fills the chart with breaks that mean nothing.

When to increase: if your relay is on a weak Wi-Fi signal and brief reconnects are normal for your setup, raising this to 10–15 keeps the chart readable and reserves breaks for real outages.

💡 This threshold changes how existing data is drawn, not the data itself — nothing is added or deleted. You can change it and reload the dashboard as often as you like, and the same break will appear at every zoom level.

Estimated Bar Threshold

Range: 0–1, default: 0.5.

When the connection to the relay drops for a long time, the meter inside the relay keeps counting but Power Trace records nothing. On reconnect, the energy consumed during the outage is recovered from the meter and spread evenly across the missing hours. That spread is an estimate, not a measurement — nobody knows how the load actually behaved while the device was offline.

Bars on the Energy and Bill charts whose energy is at least this fraction estimated are drawn dimmed, and a note appears above the chart. A bar that is 30% estimated stays normal at the default 0.5, and becomes dimmed at 0.3.

0 — dim any bar containing even a trace of estimated energy. 1 — dim only bars that are entirely estimated.

The threshold controls dimming only. Whenever a chart contains any estimated energy at all, a note above it reports the exact amount — for example 0.90 / 23.40 kWh — whatever the threshold is set to. So an estimate is never hidden: the colour tells you whether a single bar can be trusted, the note tells you how much of the whole period was estimated.

This matters most on the Month and Year charts, where one bar is a whole day. A two-hour outage in a 12 kWh day is only 7% of that bar, so it stays undimmed at the default — correctly, since the day as a whole is reliable — but the note still accounts for those kilowatt-hours, because they are on your bill.

💡 The Power, Voltage, Current, and Power Factor charts stay empty for those hours, and that is correct: those are instantaneous readings taken at a moment in time, and no such moments were recorded. Only energy can be recovered, because the meter accumulates it while the connection is down.

🔗 Remote Access (Tailscale) Optional

By default the dashboard is only accessible on the computer where Power Trace runs (http://localhost:8000, or whichever port you set as the API Server Port in the Server section), or from other devices on the same Wi-Fi. If you want to view it from your phone outside your home, you need Tailscale.

💡 What is Tailscale: a free service that creates an encrypted private network between your own devices over the internet. It does not open any ports to the public — traffic is end-to-end encrypted and only flows between devices signed into your account.

Setup steps

Create a free account at tailscale.com — sign up with Google, GitHub, or Microsoft.

Download and install the Tailscale client on the computer running Power Trace from tailscale.com/download. Sign in. The computer gets a stable Tailscale address and a short machine name.

Install Tailscale on every device you want to access from — phone, tablet, laptop. Apps for Windows, macOS, Linux, iOS, and Android. Sign in with the same account on every device.

In Power Trace Settings, open the Remote Access section and enable the toggle. Enter the Machine Name of your computer (e.g. my-pc). Port fills in automatically from your API Server Port setting — only change it by hand if you use a reverse proxy or port-forwarding.

A ready-to-use URL appears below the fields, e.g. http://my-pc:8000. Click 📋 Copy URL and open it on any Tailscale-connected device.

⚠ These settings are stored in the browser only and are not saved to config.yaml. If you open Settings in a different browser the fields will be empty and Port will re-sync from the API Server Port setting, but the Tailscale network itself will keep working.

🗄 Database

This section is read-only — it reports the current state of your database rather than a setting you configure. It shows the file size on disk, the total number of stored measurements, and the free space remaining on this drive.

ℹ Power Trace never deletes measurements on its own — every reading is kept forever. At the relay's ~60-second tick, a year of history is typically around 60–70 MB. On any modern SD card or drive this is not something you need to plan around.

Size on disk

Combined size of the database file and its WAL (write-ahead log) companion file. The WAL can temporarily be tens of megabytes between checkpoints — this is normal and shrinks again automatically.

Measurements stored

The total row count in the database, i.e. how many individual readings have been recorded since installation.

Free space on this drive

Space remaining on the disk or SD card where the database lives. If this is running low, see below.

Reclaiming disk space

If you ever delete rows from the database by hand (for example with a SQL tool), the file will not shrink on its own — SQLite keeps the freed space inside the file for reuse rather than returning it to the operating system. To actually shrink the file, you need to run a VACUUM.

⚠ Stop the collector and the API server before running VACUUM, and make sure you have free disk space at least equal to the current database size — it needs to build a new copy of the file before replacing the old one. On a Raspberry Pi this can take a few minutes.

Linux / Raspberry Pi — from a terminal, in the Power Trace folder:

sqlite3 db/energymonitor.db "VACUUM;"

Windows — sqlite3.exe is not included by default. Use the free DB Browser for SQLite instead: open db\energymonitor.db, then Tools → Compact Database.

⬆ Updates Rarely needs changing

Power Trace can tell you when a newer version has been released. It never downloads or installs anything by itself — it only shows a small notice on the dashboard with a link to the download page, and updating stays entirely your decision.

ℹ This is the only request the application makes to the outside world. Once a day it fetches a small file from getpowertrace.com containing the latest version number. Nothing is sent except the version you are running — no readings, no device details, no identifiers. See the Privacy Policy for the full description.

Check for updates automatically

On by default. Turn it off if you prefer the application to make no outbound connections at all — everything else keeps working exactly the same, you simply will not be told when a new version appears.

Installed version / Last check

Read-only. Shows which version you are running and when the last check happened. If the last check failed, the reason is shown here too — usually just a temporary network problem, and the next attempt happens automatically.

↻ Check Now

Runs a check immediately instead of waiting for the daily one. If you have just switched the toggle on, save the configuration first — the button acts on what is stored in config.yaml, not on what is currently shown on screen.

ℹ When an update is available, an arrow with the version number appears in the dashboard header. Clicking it opens the download page; clicking the × hides it until a newer version than that one is released.

💾 Save Buttons

💾 Save Configuration

Writes all settings to config.yaml on disk. Before saving, all fields are validated — if there are errors a message is shown and nothing is saved. Empty Device ID / IP / Local Key triggers a confirmation dialog. The dashboard picks up the new configuration automatically without reloading the page.

↺ Reset to Saved

Discards all unsaved changes and restores the form to the state currently stored in config.yaml. Use this if you changed something and want to undo it without reloading the page.

⚠ Reset to Defaults

Resets only UI and operational parameters to factory defaults. Device and Cloud credentials are not touched. After resetting, click Save Configuration to write the defaults to disk.

⚠ Changes to Device or Collector settings only take effect after you save and restart the collector with ⟳ Restart Collector. Changing the API Server Port additionally requires ⟳ Restart Server.

After the first setup

1. Save your configuration

Click Save Configuration at the bottom of the Settings page.

2. Restart the collector

Open the Collector section and click ⟳ Restart Collector.

3. Open the dashboard

Click the ← Power Trace button in the top-left corner of Settings.

4. Wait for the first tick

The relay sends data approximately once every 60 seconds. After the first packet the status changes to ONLINE.