Veloxa Solar Widget

Veloxa Solar Widget is a presentation layer for photovoltaic data you already monitor elsewhere. It is not a monitoring system: it takes the data your inverter cloud, gateway or Home Assistant already has and shows it nicely on your website — on a company page, in a case study, or on a screen in your reception area. Free and Pro | | Free | Pro | Agency | |---|---|---|---| | Widgets: current power, energy today, total energy, summary, battery, avoided CO₂ | ✓ | ✓ | ✓ | | Data sources: Generic REST / JSON, push, Home Assistant, SolaX Cloud (beta) | ✓ | ✓ | ✓ | | Number of installations, data sources and widgets | unlimited | unlimited | unlimited | | Daily production chart | — | ✓ | ✓ | | Production history (30 days, 12 months, this year) and statistics | — | ✓ | ✓ | | Full-screen display for a TV or tablet | — | ✓ | ✓ | | Energy flow: solar, home, battery and grid in one diagram | — | ✓ | ✓ | | Solarman cloud data source (your own Solarman API access) | — | ✓ | ✓ | | SolarEdge cloud data source (beta) | — | ✓ | ✓ | | "Our installations": all your installations in one widget | — | — | ✓ | | Add every plant of a Solarman account at once | — | — | ✓ | | Your branding: company name, logo and brand colour | — | — | ✓ | The free version has no limits: add as many installations, data sources and widgets as you need. Widgets

• Current power (e.g. 4.82 kW)
• Energy today (e.g. 24.8 kWh)
• Total energy, scaled automatically (e.g. 38.4 MWh)
• Summary — all three in one card
• Battery — charge level and whether it is charging, discharging or idle, with the charging/discharging power
• Avoided CO₂ — the emissions your solar production has saved so far and today, as an estimate with the emission factor shown

Every widget is available as a block and as a shortcode, shows when the data was last updated, and marks data as out of date when the source stops sending it. Data sources refresh roughly every 5 to 15 minutes, so widgets show the current production — not a real-time feed. A widget is offered only for values your source actually provides: no battery in the source means no battery value to choose, not a zero. Data sources

• Generic REST / JSON — any cloud API that returns JSON. Point each value at its place in the response with a dot path (e.g. result.acpower) — or add several together with + (e.g. result.powerdc1+result.powerdc2) — and pick the unit the API uses; the plugin converts it.
• Push — your device, script or Home Assistant automation sends readings to your site. Each channel has its own token, which you can replace at any time.
• Home Assistant — sensors are offered by their type and unit. For Solarman/Sofar they are pre-selected; for Huawei Solar, Fronius, GoodWe, SMA, Enphase, SolarEdge and similar integrations they are pre-selected by their names (beta) — check them before saving. Gaps caused by rare refreshes are filled from Home Assistant's own history.
• SolaX Cloud (beta) — enter the token ID from SolaxCloud (Service → API) and the registration number of the dongle; solar power, energy, battery and grid are mapped for you.

You can edit every data source later — for example, replace an API key or a Home Assistant token — without losing its settings or breaking the widgets that use it. Pro

• Daily production chart built from the history the plugin collects.
• Production history — daily bars for the last 30 days, or monthly bars for the last 12 months or this year. A day without data is shown as a gap, never as zero; estimated days and the current, incomplete day or month are marked.
• Statistics — production this year, total production since data collection started, the best day and the peak power. Choose which items are shown publicly.
• Full-screen display at an address such as /solar-display/your-connection-id/ for a TV or tablet in your reception area — large type, refreshing automatically, without the theme's navigation. Three layouts (summary; energy flow with battery; flow with today's chart and statistics), dark or light, for landscape TVs and portrait tablets. When data stops arriving or the screen loses its network connection, it says so and resumes by itself.
• Energy flow — solar panels, home, battery and grid on one diagram, with the direction of each flow. Shown when your source reports the solar power and the home consumption; parts your source does not report (for example no battery) are left out.
• SolarEdge cloud data source (beta) — reads solar power, energy today and total, and — with a meter — home consumption, grid and battery, using the site API key from the SolarEdge monitoring portal (or an installer's account key; Agency: add every site at once). Refreshes every 15 minutes by default to stay within SolarEdge's 300 requests a day.
• Solarman cloud data source — reads solar power, home consumption, battery and grid directly from the Solarman cloud, without Home Assistant or a custom API mapping. Requires your own Solarman API access (APP ID and APP SECRET, requested from Solarman support) and your Solarman account login. Energy today is calculated from the inverter's total energy counter. When your site has few visitors and data is refreshed rarely, the plugin fills the gaps from Solarman's own history: exact daily totals, energy today and the 5-minute readings for the daily chart and peak power.

Agency — for installers

• "Our installations" — all your public installations in one widget: how much they produce right now, energy today, total energy and avoided CO₂, with a list of the installations and their current power. Ideal for an installer's "our projects" page.
• Solarman: add every plant of a Solarman account as a separate data source in one step, with refresh intervals that keep all plants within the daily request limit.
• Your branding — your company name and logo in the header of the full-screen display, and your brand colour for the chart line, the battery level and the history bars.

Beta data sources SolaX Cloud, SolarEdge and the name-based Home Assistant suggestions are built from the manufacturers' documentation and have not yet been confirmed on a real installation of each type. They are marked "beta". Compare the values with the manufacturer's app; the plugin also checks every reading of a beta source (for example energy today larger than total energy, negative solar power, battery outside 0–100 %, a daily counter going down) and writes problems to the Diagnostics error log. The raw values received are shown on the data source's edit screen — if something is wrong, send them with the diagnostic report and we will correct the mapping. Nothing is sent anywhere automatically. Home consumption Use your source's own home consumption value when it has one. If it does not, the plugin estimates it as solar power + power taken from the grid − battery charging power (grid: positive when taking power from the grid; battery: positive when charging), and marks the value with "≈" and this formula wherever it is shown. Privacy by default Solar production can reveal when people are at home. Widgets of a data source are hidden from visitors until you switch on "Show on public pages" for that source. Public widgets show only the values themselves — never the source address, keys or raw API responses. Performance Data is fetched in the background (WP-Cron) and served from the database. A visitor loading a page never triggers a request to your data source. Diagnostics The Diagnostics screen shows whether each data source is up to date, when it was last measured and refreshed, the background tasks and the most recent errors. One button copies it all as a text report for a support request — without addresses, tokens or API keys.

0.7.2

• Security: every field of the data source forms is sanitized as it is read, before it reaches any other code or filter.
• Security: widget HTML (shortcode and block) is passed through an allow-list of HTML and SVG tags before it is output.
• Fix: the request limit of push channels (60 per minute) holds under many simultaneous requests.
• Fix (Pro): the Account link appears once on the Account page.

0.7.1

• Fix: a push value the widget cannot use — text instead of a number, battery level outside 0–100 % — is now refused with a clear message (HTTP 400) instead of being accepted and ignored.
• Fix: the Avoided CO₂ factor falls back to the default 0.7 when it is set to zero or a negative number.
• Fix: the hint under "Home consumption" in Generic REST describes the home, not the grid.
• Fix: background refresh results in Diagnostics and the "waiting for the device" message of push channels are shown in the language of the person viewing them.
• Fix (Pro): production history no longer marks today as incomplete when there are no readings today yet.
• Fix (Pro): "Total production" in Statistics uses the inverter's lifetime counter when the data source has one, matching the summary widget.
• Fix (Pro): the "Account" page (licence, plan) is now in the Solar Widget menu.
• Fix (Agency): the brand colour now also colours the production history bars.
• Fix (Agency): "Our installations" shows "—" instead of 0 kWh for energy today when no installation has a reading from today.

0.7.0

• New: SolaX Cloud data source (beta) — token ID and dongle number, everything else is mapped for you.
• New (Pro): SolarEdge cloud data source (beta) — overview and power flow with the direction of grid and battery; Agency: add every site of an installer's API key at once.
• New: Home Assistant sensors of Huawei Solar, Fronius, GoodWe, SMA, Enphase, SolarEdge and similar integrations are pre-selected by their names (beta).
• New: readings of beta sources are checked for typical mapping mistakes, and the raw values are shown on the edit screen for comparison with the manufacturer's app.
• New: Generic REST paths can add values together, e.g. result.powerdc1+result.powerdc2.
• New: Site Health (Tools → Site Health) checks whether your solar data sources are up to date and whether the background refresh runs.
• New: a "Getting started" list on the Connections screen — add a data source, show it on public pages, add the widget to a page.
• New: Diagnostics can download the list of your Home Assistant power, energy and battery sensors (without the address and token, without phones and other battery devices) to send to support when your inverter is not recognised.
• Fix: a host name that cannot be resolved no longer writes a PHP warning to the debug log; .local addresses are not looked up in DNS.
• New (Agency): your branding — company name and logo on the full-screen display, brand colour on the widgets (Solar Widget → Connections → Settings).
• New: Avoided CO₂ widget — emissions saved so far and today, with an emission factor you can set (default 0.7 kg CO₂/kWh).
• New (Agency): "Our installations" widget — all public installations in one widget: production now, energy today, total energy, avoided CO₂ and a list of installations.
• New (Agency): Solarman — add every plant of an account at once, with refresh intervals that fit the daily request limit.
• New: the [veloxa_solar] shortcode accepts connections="id1,id2" for the "Our installations" widget.
• New (Pro): Solarman cloud data source — solar power, home consumption, battery and grid straight from the Solarman cloud, with your own Solarman API access. Energy today is calculated from the inverter's total energy counter.
• New (Pro): Solarman data is completed from Solarman's history when your site has few visitors — exact daily totals for days without readings, energy today, and 5-minute readings for the daily chart and peak power. The connection form shows the estimated daily requests per APP ID and warns when the intervals are too short.
• New: Home Assistant data is completed from Home Assistant's history when your site has few visitors — daily totals for days without readings and the solar power for the daily chart and peak power.
• New: Diagnostics warns when a data source was refreshed much less often than set in the last 24 hours (WP-Cron runs only when the site has visitors).
• Fix: Pro widgets are shown with their styles in the block editor preview (the energy flow was drawn without them).
• New (Pro): Production history widget — 30 days, 12 months or this year, with gaps for days without data.
• New (Pro): Statistics widget — this year, total since the start, best day and peak power.
• New (Pro): Full-screen display layouts (summary, flow, full), light theme, portrait tablets, "Last data" and "No connection" bars with automatic resume.
• New (Pro): Energy flow adapts to 2, 3 or 4 nodes and warns administrators when the energy balance does not add up (usually a reversed battery or grid sign).
• New (Pro): Polish translation.
• New: The block offers the period and statistics items as settings; Pro widgets are marked "(Pro)" in the free version.
• Security: Carrier-grade NAT addresses (100.64.0.0/10) are treated as a local network.
• Fix: After activating a Pro licence, the full-screen display could return "page not found" until the plugin was updated.

0.2.0

• New: Battery widget — charge level, charging / discharging / idle state and power. The idle threshold is set per data source (50 W by default).
• New: Energy flow (Pro) — solar, home, battery and grid on one diagram with the direction of each flow.
• New: Home consumption value from your source; an optional estimate (solar + grid − battery), off by default and marked "≈".
• New: Daily production totals are kept from the first day, for longer-term charts.
• New: Home Assistant — sensors of Solarman / Sofar inverters are recognised and pre-selected.
• New: Invert the sign of battery, grid and home consumption values per data source.
• Changed: Shortcode is now [veloxa_solar]; block, REST route and all internal names use the veloxa-solar prefix.
• Fix: Units sent by push devices are validated — unknown units are rejected instead of silently using the channel unit.
• Fix: Without an active licence, the Pro package behaves exactly like the free version.

0.1.2

• New: Diagnostics screen (Solar Widget → Diagnostics) with the state of each data source, background tasks and recent errors, plus a "Copy diagnostic report" button for support requests. Addresses, tokens and API keys are never included in the report.
• Fix: the error log is now limited to the 200 most recent entries.
• Fix: editing a push channel updates its current reading right away.

0.1.0

• First version.