Proforio Help Center

wmbusmeters connector

Connect a wmbusmeters gateway to send meter readings to Proforio.

Your existing wmbusmeters installation is already doing the hard part. Install the Proforio connector and link it with one integration token.

Proforio then receives new readings, matches meters by serial number, and retains the original wmbusmeters data.

Before you start

  • wmbusmeters is already running and decoding your meters.
  • wmbusmeters writes one-line JSON records to a meterfiles archive in append mode.
  • The device runs Debian 13 or a compatible Raspberry Pi OS environment and can reach Proforio over the Internet.

The production flow has been verified on Debian 13 (trixie), an aarch64 Raspberry Pi, and wmbusmeters 3.0.0.

Step 1

Create the integration in Proforio

  1. Open Settings → Meter Reading Settings → Incoming readings.
  2. Under Readings sent to Proforio, choose Add inbound integration, give it a name, and select wmbusmeters.
  3. Create the integration and copy the generated token.

The token is shown only once. Keep it secure until you configure the device.

Open integrations

Step 2

Install the connector

Download proforio-wmbusmeters 1.0.0 (.deb)

curl --fail --location --remote-name https://proforio.com/downloads/wmbusmeters/1.0.0/proforio-wmbusmeters_1.0.0_all.deb
curl --fail --location --remote-name https://proforio.com/downloads/wmbusmeters/1.0.0/SHA256SUMS
sha256sum --check SHA256SUMS
sudo apt install ./proforio-wmbusmeters_1.0.0_all.deb

Step 3

Connect the device to Proforio

sudo proforio-wmbusmeters setup

Paste the integration token when prompted. Input is hidden and does not enter shell history.

Setup validates the connection and archive access, stores the token securely, starts at the end of existing files, and automatically enables and starts the service.

Historical records already present before installation are not uploaded.

When setup finishes, it confirms that the service is already running and shows the status command:

Setup complete. Connector is running.
Readings are sent hourly by default, so the first reading may take up to about one hour to appear in Proforio.

Check status with:
  sudo proforio-wmbusmeters status

Step 4

Check the connection

sudo proforio-wmbusmeters status
Proforio wmbusmeters connector

Service:        active
Connection:     OK
Last upload:    2026-09-19 16:02:05 UTC
Pending:        0
Meters tracked: 3
Version:        1.0.0

Before the first upload, Connection shows “Waiting for first reading”. Authentication, configuration, or service problems are shown there in clear text.

Readings are sent hourly by default, so the first reading may take about an hour to appear in Proforio.

Done

In the Proforio integration view you will see the last connection, last received reading, and connector version. Newly discovered meter IDs and their reading events appear automatically.

Troubleshooting

Connected, but no readings yet

This can be normal: delivery is hourly by default, so setup can be successful before the first reading arrives.

sudo proforio-wmbusmeters status

If no reading appears after a full interval, confirm that wmbusmeters is still appending new JSON records to the archive files.

Authentication or authorization error

Run setup again and read the concise error returned by Proforio. A 401 usually means an invalid, replaced, or revoked token. A 403 can mean a disabled or unavailable integration, or temporarily unavailable ingestion.

sudo proforio-wmbusmeters setup

Do not rotate the token automatically for every 403. Check the returned message and the integration status in Proforio first.

Archive files are not discovered

Check that JSON files are actually being written in the configured directory:

ls -lah /var/lib/wmbusmeters/meter_readings/

The functional requirements are JSON format, enabled meterfiles, and append behavior. The filename scheme is not fixed: name-id, id, and other normal wmbusmeters naming schemes work.

Service diagnostics

These commands are normally needed only for troubleshooting:

sudo systemctl status proforio-wmbusmeters.service --no-pager
sudo journalctl -u proforio-wmbusmeters.service -n 50 --no-pager
Advanced configuration

Most installations do not need custom settings. The installed /etc/proforio-wmbusmeters.conf documents every option, default, unit, valid range, and the effect of changing it.

For detailed diagnostics and automation, request the structured status with:

sudo proforio-wmbusmeters status --json
  • archive_directory - the wmbusmeters meterfiles directory.
  • upload_interval_seconds / interval_grace_seconds - the reading selection interval and short closing grace period.
  • poll_interval_seconds, connect_timeout_seconds, read_timeout_seconds - archive polling and network timeouts.
  • retry_initial_seconds, retry_max_seconds, max_requests_per_minute - retry timing and request-rate limits.
  • state_retention_days, live_max_record_age_days - operational-state cleanup and the old-data safety boundary.

Open the complete commented configuration

wmbusmeters archive settings

The required behavior is JSON, a meterfiles directory, and append mode. This is an example, not a mandatory filename scheme:

format=json
meterfiles=/var/lib/wmbusmeters/meter_readings
meterfilesaction=append

# Optional examples; existing working naming schemes can remain unchanged.
meterfilesnaming=name-id
meterfilestimestamp=day

Daily file rotation is recommended for manageable archives, but the connector does not depend on it.

How the connector works

By default, Proforio receives the latest reading from each meter once per hour. The connector continuously reads new local telegrams and sends the latest sample for each meter after the hourly interval closes.

Cumulative meter fields are not summed. The complete original wmbusmeters JSON is sent to Proforio, where meter matching, normalization, and billing eligibility are handled.

The connector keeps a small local operational state so it can resume safely after restarts or network outages. wmbusmeters archive files remain untouched, pre-installation history is not sent, and live records older than the configured safety limit are not uploaded automatically.

Acceptance testing verified multiple existing name-id archive files: they were initialized at EOF, new records were discovered, and all readings from the closed interval were acknowledged by Proforio.

Upgrade and token replacement

Download the new version’s .deb and checksum, verify them, and install with apt. Upgrades preserve user configuration, the token, and connector state.

To replace a token, generate a new one in the Proforio integration view and run sudo proforio-wmbusmeters setup again. Reconfiguration preserves file positions and pending deliveries.