Home Pump Monitor

A Java application that reads data from a heat pump via Modbus TCP and sends metrics to InfluxDB.

Features

• Reads Modbus holding registers from a heat pump
• Configurable send interval to InfluxDB (default: 5 minutes)
• Automatic buffering when InfluxDB is unavailable (up to 50,000 data points)
• Health check endpoint for monitoring application status
• Automatic restart on Modbus connection failures
• Graceful shutdown with InfluxDB buffer flush
• Systemd service with automatic recovery
• Configurable via JSON file

Quick Start

Local Development

mvn clean package
java -jar target/home-pump-1.0.0.jar

Production Deployment (Raspberry Pi / Ubuntu)

See DEPLOYMENT.md for complete installation and configuration guide.

# Build
mvn clean package

# Install as systemd service
sudo scripts/install-service.sh

# Check status
systemctl status home-pump.service
curl http://localhost:8080/health

Configuration

Edit src/main/resources/registryMapping.json to configure:

• Modbus TCP connection (address, port)
• InfluxDB connection (address, username, password)
• Send interval (influxSendIntervalSeconds, default: 300)
• Connection timeouts and retry settings
• List of registers to read with descriptions

Additional mapping fields (optional):

• useMock (Boolean, top-level): When true, the application runs with a local MockRepository instead of attempting to connect to a Modbus device. Useful for local development when a device is not available (default: false).

• unitId (Integer): Modbus slave/unit id for the register (default: 1)

• scale (Double): Multiply raw device value by this to obtain display value (default: 0.1)

• dataType (String): Data type used for the locator (e.g. TWO_BYTE_INT_SIGNED). Supported values: TWO_BYTE_INT_SIGNED, TWO_BYTE_INT_UNSIGNED, FOUR_BYTE_INT_SIGNED, FOUR_BYTE_INT_UNSIGNED, FOUR_BYTE_FLOAT (the latter reads two adjacent registers and interprets as IEEE754 float). For devices with non-standard word order, the following swapped variants are supported: FOUR_BYTE_INT_SWAPPED, FOUR_BYTE_INT_UNSIGNED_SWAPPED, FOUR_BYTE_FLOAT_SWAPPED (word order low/high).

• Example Configuration

{
  "address": "192.168.0.150",
  "port": 502,
  "useMock": false,
  "influxSendIntervalSeconds": 300,
  "timeoutMs": 5000,
  "maxRetries": 2,
  "retryBackoffMs": 1000,
  "influx_db": {
    "address": "https://influxdb.example.com",
    "username": "",
    "password": ""
  },
  "registry_mapping": [
    {
      "registry": 4065,
      "desc": "External temperature",
      "unitId": 1,
      "scale": 0.1,
      "dataType": "TWO_BYTE_INT_SIGNED"
    }
  ]
}

Monitoring & Health Check

The application exposes a health check endpoint on port 8080:

curl http://localhost:8080/health

Healthy response (HTTP 200):

{
  "status": "UP",
  "lastSuccessfulRead": "2026-02-06T19:30:45Z",
  "message": "Last successful read 15 seconds ago"
}

Unhealthy response (HTTP 503):

{
  "status": "DOWN",
  "lastSuccessfulRead": "2026-02-06T19:20:45Z",
  "message": "No successful read for 620 seconds. Last error: Connection timeout"
}

Important Notes

• InfluxDB failures do NOT trigger unhealthy status - data is buffered in memory
• Only Modbus read failures trigger unhealthy status and potential restart
• Health check considers the application unhealthy if no successful Modbus read within 2× send interval
• Automatic monitoring script restarts the service on health check failures

Production Deployment

For production use on Raspberry Pi or Ubuntu server:

1. Install as systemd service - Auto-start on boot with resource limits
2. Enable health monitoring - Cron job checks health every 2 minutes
3. Automatic recovery - Restarts service on Modbus failures (max 3 attempts per 10 minutes)
4. Graceful shutdown - Flushes buffered data to InfluxDB before exit

See DEPLOYMENT.md for detailed instructions.

Data Buffering

When InfluxDB is unavailable, data is automatically buffered:

• Buffer size: 50,000 data points in memory
• Batch size: 50 points per flush
• Flush interval: 180 seconds (3 minutes)
• No data loss: Buffer persists during InfluxDB outages
• Automatic retry: Built-in retry mechanism in InfluxDB Java client

Troubleshooting

Check application logs

journalctl -u home-pump.service -f

Test health endpoint

./scripts/test-health.sh

View monitor logs

tail -f /var/log/home-pump-monitor.log

Common Issues

1. Service won't start: Check JAR file exists and Java 21 is installed
2. Health check fails: Verify Modbus device is accessible
3. InfluxDB connection errors: Check network and credentials (data will be buffered)
4. Too many restarts: Check Modbus device connectivity and network stability clean package java -jar target/home-pump-1.0.0.jar

## Requirements

- Java 21
- Modbus TCP accessible heat pump
- InfluxDB instance