Shelly Plasma Meter

A KSystemStats plugin that exposes Shelly EM data to the native KDE Plasma 6 System Monitor widgets. Shelly sensors appear in the same picker as CPU, memory, disk, and GPU sensors, and they work with line charts, bar charts, pie charts, and text-only displays.

The plugin performs read-only HTTP requests to a Shelly EM Gen 1 /status compatible endpoint. The complete URL, including its path, is configurable.

Available sensors

The provider appears as Shelly EM, or the custom device name from the configuration, and publishes the following groups.

Channels and aggregate values

For each channel and for the aggregate of all valid channels:

• active power in W;
• reactive power in var;
• computed apparent power in VA;
• voltage in V;
• computed current in A;
• power factor as a percentage;
• consumed, returned, and net energy in Wh;
• measurement validity.

The Shelly Gen 1 total fields use watt-minutes. The plugin converts them to Wh before publishing them.

KSystemStats does not provide native var or VA units. These two sensors remain numeric and include the unit in their names.

Device status

• endpoint reachability, response time, last-update age, and the latest error;
• device uptime, local time, and status sequence;
• total, free, used, and percentage values for device RAM and storage;
• firmware update state and version information;
• configuration-change and skipped-action counters;
• detected channel and relay counts.

Connectivity and relays

• Wi-Fi connection, RSSI, SSID, IP address, and MAC address;
• Shelly Cloud, MQTT, and ping-check state;
• relay state, timers, overpower state, validity, and last command source.

The plugin is read-only. It cannot switch relays or modify the Shelly device.

Requirements

• KDE Plasma 6;
• KSystemStats and libksysguard 6 development files;
• Qt 6 Core, Network, and Test;
• KDE Frameworks 6 CoreAddons;
• Extra CMake Modules;
• CMake 3.24 or newer;
• a systemd-based user session.

On Arch Linux and Manjaro, install the corresponding packages with:

sudo pacman -S --needed cmake extra-cmake-modules qt6-base kcoreaddons libksysguard ksystemstats

Package names differ between distributions.

Per-user installation

For the first installation, provide the endpoint and the default power limit:

./install-user.sh \
  --url http://shelly-em.local/status \
  --max-power 3000

Subsequent installations only require:

./install-user.sh

The script:

1. configures a Release build;
2. compiles the project and runs its tests;
3. replaces any previously installed version;
4. installs under ~/.local without sudo;
5. adds the local plugin path only to the KSystemStats user service;
6. restarts the service and verifies that the sensors are available over D-Bus.

Existing configuration is preserved. The main installed files are:

~/.local/lib/qt6/plugins/ksystemstats/ksystemstats_plugin_shelly.so
~/.local/bin/shelly-plasma-meter-config
~/.config/shelly-plasma-meter.conf
~/.config/systemd/user/plasma-ksystemstats.service.d/50-shelly-plasma-meter.conf

Use --prefix PATH or the PREFIX environment variable to select a different installation prefix.

System-wide installation

A system-wide installation places the plugin in Qt's system plugin directory under /usr. The plugin becomes available to every user without a KSystemStats systemd drop-in. Configuration remains private and separate for each user.

Do not keep a per-user copy of the plugin for an account that will use the system-wide version. Remove it first from that account's checkout:

./uninstall-user.sh

Install the plugin system-wide and configure one user with:

./install-system.sh \
  --user "$USER" \
  --url http://shelly-em.local/status \
  --max-power 3000

The script builds and tests as the current user, requests sudo only for files installed under /usr, writes the selected user's configuration with the correct ownership and 0600 permissions, and restarts that user's KSystemStats service when an active session is available.

Install or update the shared plugin without changing any user configuration with:

./install-system.sh

Typical system-wide files are:

/usr/lib/qt6/plugins/ksystemstats/ksystemstats_plugin_shelly.so
/usr/bin/shelly-plasma-meter-config
/usr/share/doc/shelly-plasma-meter/

The exact Qt plugin directory is selected by Extra CMake Modules and can differ between distributions. Other active users must restart plasma-ksystemstats.service or log in again after a system-wide update.

Remove the shared plugin while preserving one user's configuration with:

./uninstall-system.sh --user "$USER"

Remove that user's configuration as well with:

./uninstall-system.sh --user "$USER" --purge-user-config

When --user is omitted, the scripts only install or remove shared files. They do not modify files in any home directory.

Configuration

Run the configuration command without arguments for interactive mode:

shelly-plasma-meter-config

If ~/.local/bin is not in PATH, use:

~/.local/bin/shelly-plasma-meter-config

Non-interactive examples:

shelly-plasma-meter-config \
  --url http://shelly-em.local/status \
  --max-power 3000 \
  --poll-interval 1000

shelly-plasma-meter-config \
  --channel-name '0=Home consumption' \
  --channel-name '1=Second channel'

shelly-plasma-meter-config --show

The configurator restarts KSystemStats so that changes take effect immediately. The minimum polling interval is 500 ms. When no clients subscribe to the sensors, the plugin performs only its initial request and does not generate continuous network traffic.

The configuration can also be edited directly at:

~/.config/shelly-plasma-meter.conf

See config.example.ini for every available setting. After editing the file manually, run:

systemctl --user restart plasma-ksystemstats.service

HTTP authentication

Qt-managed Basic and Digest authentication are supported. Do not put credentials in the URL. Interactive mode accepts a password without displaying it.

The configuration file uses 0600 permissions. Credentials are not published as sensors or included in error messages. Query parameters and URL fragments are also removed from the sensor that displays the configured endpoint.

Adding a Plasma widget

1. Right-click the desktop and select Add Widgets.
2. Add System Monitor Sensor.
3. Open the widget configuration and select Sensors.
4. Search for Shelly and select, for example, Shelly EM → Channel 1 → Active Power.
5. Choose the preferred display style.

PowerMaximumW is published as the sensor's default maximum. To force a 0 to 3 kW range for one widget, open the chart details, disable the automatic range, set the minimum to 0 W, and set the maximum to 3 kW or 3000 W.

The maximum is graph metadata only. Measurements are never clipped when they exceed it.

Updating and uninstalling

Update a per-user installation with:

./install-user.sh

Remove it while preserving user settings with:

./uninstall-user.sh

Remove its configuration file as well with:

./uninstall-user.sh --purge

For a system-wide installation, use install-system.sh and uninstall-system.sh as described in System-wide installation.

Manual build and test

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DKDE_INSTALL_PLUGINDIR=lib/qt6/plugins \
  -DBUILD_TESTING=ON
cmake --build build --parallel
ctest --test-dir build --output-on-failure

Troubleshooting

First check that the Plasma widget uses a Shelly sensor and that its chart range is configured as intended. Then verify the endpoint configuration:

shelly-plasma-meter-config --show

Inspect the service state and logs with:

systemctl --user status plasma-ksystemstats.service
journalctl --user -u plasma-ksystemstats.service -n 50

Check whether the provider is available:

qdbus6 --literal \
  org.kde.ksystemstats1 \
  /org/kde/ksystemstats1 \
  org.kde.ksystemstats1.allSensors | grep 'shelly/'

Previous measurement values remain available when a request fails. In that case, Shelly EM → Endpoint Status → Reachable becomes false and Last Error describes the failure.

Privacy

The SSID, IP address, and MAC address returned by the device are exposed on the local session D-Bus because they are part of the requested sensor set. The plugin does not send them to external services. Check screenshots and diagnostics before sharing them publicly.

License

This project is available under the MIT License. See LICENSE.