Loxone Integration: Sending Data to EnergyPal

Complete guide for configuring a Loxone Miniserver to send PV and battery storage metrics to EnergyPal via HTTP POST. All configuration is done visually in Loxone Config — no coding required.

Prerequisites

• Controller: Loxone Miniserver Gen 2 (HTTPS support required)
• Software: Loxone Config 14.0 or later
• Network: Miniserver must have internet access (port 443/HTTPS)
• API key: your energy_connection_key from EnergyPal administrator
• Configured devices: device codes (e.g., PV-1, BESS-1) must be registered in EnergyPal. Verify with GET /v1/devices.

Miniserver Gen 1

The Miniserver Gen 1 does not support outgoing HTTPS connections. If you use Gen 1, you need a local reverse proxy (e.g., nginx on a Raspberry Pi or NAS) that forwards HTTP from the Miniserver to HTTPS at api.energypal.ai. See Gen 1 workaround at the bottom of this page.

Overview

The Miniserver sends a JSON payload with current metric values to POST /v1/ingest every 15 minutes. A Pulse Generator triggers the Virtual HTTP Output, and a Status block builds the JSON body from your sensor inputs.

Modbus / Analog Inputs
        │
        ▼
  ┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
  │ Status Block │────►│ Virtual HTTP Out  │────►│ EnergyPal API   │
  │ (build JSON) │     │ POST /v1/ingest   │     │ api.energypal.ai│
  └─────────────┘     └──────────────────┘     └─────────────────┘
        ▲
        │
  Pulse Generator
  (every 15 min)

Step 1: Create the Virtual HTTP Output

1. In Loxone Config, go to the periphery tree and right-click Virtual Outputs → Add Virtual Output.
2. Name it EnergyPal Sender.
3. Set the Address to:

   https://api.energypal.ai

Add the Output Command

1. Right-click the Virtual Output → Add Virtual Output Command.
2. Name it Send Metrics.
3. Configure the command:

Field	Value
Command for ON	/v1/ingest
HTTP Method	POST
HTTP POST command	(see JSON body below)
HTTP Extensions for ON	X-API-Key: your-api-key\r\nContent-Type: application/json

Replace your-api-key with your actual API key in the HTTP Extensions field.

Step 2: Build the JSON Payload

In the HTTP POST command field of the Virtual Output Command, enter:

{"metrics":{"PV-1":{"energy_generated_meter":<v1>},"PV-2":{"energy_generated_meter":<v2>},"BESS-1":{"soc":<v3>,"energy_exported_meter":<v4>,"energy_imported_meter":<v5>},"LOAD-0":{"energy_consumed_meter":<v6>}}}

The placeholders <v1> through <v6> will be replaced with actual values from a Status block:

Placeholder	Metric	Unit
<v1>	PV-1 generation meter	kWh
<v2>	PV-2 generation meter	kWh
<v3>	Battery state of charge	%
<v4>	Battery discharge meter	kWh
<v5>	Battery charge meter	kWh
<v6>	Energy consumption meter	kWh

Custom devices

If you have a different number of inverters or batteries, adjust the JSON template and <v> placeholders accordingly. Device codes must match your EnergyPal configuration — verify with GET /v1/devices.

Step 3: Wire the Sensor Inputs

1. Add a Status block to your program page.
2. Connect your sensor values (from Modbus extensions, analog inputs, or other function blocks) to the Status block inputs:
   • AI1 → PV-1 generation meter (kWh) → maps to <v1>
   • AI2 → PV-2 generation meter (kWh) → maps to <v2>
   • AI3 → Battery SOC (%) → maps to <v3>
   • AI4 → Battery export meter (kWh) → maps to <v4>
   • AI5 → Battery import meter (kWh) → maps to <v5>
   • AI6 → Energy consumption meter (kWh) → maps to <v6>
3. Connect the Status block output (AQ) to the Virtual Output Command input.

Step 4: Add a Timer

1. Add a Pulse Generator block to the program page.
2. Configure it:
   • Pulse duration (ON): 1 second
   • Pause duration (OFF): 899 seconds
3. Connect the Pulse Generator output (Q) to the Status block trigger (TI).

This triggers a data send every 15 minutes (1 + 899 = 900 seconds).

Alternative: Pulse At

For sending at exact clock times, use a Pulse At block instead. Set it to trigger every 15 minutes (e.g., at :00, :15, :30, :45 past each hour).

Step 5: Verify

1. Save and push the configuration to the Miniserver.
2. Open the Loxone Config Status page and watch for the HTTP output triggering.
3. Check the API response — the Miniserver doesn't show HTTP status codes natively, but you can verify data arrived:

# Check that your devices are registered and data is flowing
curl -H "X-API-Key: your-api-key" https://api.energypal.ai/v1/devices

Configuration Notes

• Send interval: 15 minutes matches the system aggregation interval. Faster is unnecessary; slower risks data gaps.
• Cumulative meters: energy_*_meter values must be always increasing. Never reset — the system calculates energy gain automatically.
• Error handling: if a request fails, the Miniserver silently retries on the next timer cycle. The API is idempotent — duplicates within a 15-minute window are skipped.
• Device codes: must exactly match the configuration in EnergyPal.
• Content-Type charset: Loxone may append ; charset=utf-8 to the Content-Type header. This is harmless — the API accepts it.
• Diagnostics: Loxone Config's status page and the Miniserver log (accessible via web interface) show HTTP request results.

Reading Energy Prices

To fetch energy price forecasts on the Miniserver (for battery optimization), see the dedicated guide: Fetching Energy Prices (Loxone).

Testing with curl

Before configuring the Miniserver, test the API connection:

# Send test data
curl -X POST https://api.energypal.ai/v1/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "metrics": {
      "PV-1": {"energy_generated_meter": 12345.0},
      "BESS-1": {"soc": 85.5, "energy_exported_meter": 500.0, "energy_imported_meter": 450.0},
      "LOAD-0": {"energy_consumed_meter": 98765.0}
    }
  }'

# Verify your device codes
curl -H "X-API-Key: your-api-key" https://api.energypal.ai/v1/devices

Gen 1 Workaround

If you have a Miniserver Gen 1, set up a local HTTP-to-HTTPS proxy:

1. Install nginx on a Raspberry Pi, NAS, or any always-on device on your LAN.
2. Configure nginx to proxy HTTP requests to the EnergyPal API:

server {
    listen 8080;
    server_name _;

    location /v1/ {
        proxy_pass https://api.energypal.ai/v1/;
        proxy_set_header Host api.energypal.ai;
        proxy_set_header X-API-Key your-api-key;
        proxy_ssl_server_name on;
    }
}

3. In Loxone Config, set the Virtual Output address to http://192.168.x.x:8080 (your proxy's LAN IP).
4. Remove the X-API-Key from HTTP Extensions (nginx adds it).

caution

The proxy must be always available on your LAN. If it goes down, data sending stops. Consider upgrading to Miniserver Gen 2 for a more reliable setup.