SmartHomeShop Docs

Firmware Guide

Local operation and GitHub update checks

The local Home Assistant firmware keeps P1MeterKit measurements on your own network. Sensor readings go directly to Home Assistant and are not sent to GitHub or the SmartHomeShop cloud.

The WiFi firmware for V2 and V3 includes an ESPHome update entity. It periodically reads a small firmware manifest from SmartHomeShop GitHub Pages to compare the installed version with the latest release. Only firmware metadata is requested; the firmware file is downloaded only when you install an update.

Cloud firmware intentionally communicates with the SmartHomeShop app as part of its cloud features. Disabling the GitHub update check does not convert cloud firmware into local firmware. Thread firmware does not perform this check.

Use P1MeterKit without internet access

You may block internet access for P1MeterKit; its local measurements and Home Assistant connection continue to work. To prevent a blocked check from triggering the red status LED, take control of the device in the ESPHome Device Builder app/add-on, open its YAML and add this at the bottom:

update:
  - id: !extend firmware_update
    update_interval: never

Save the YAML, select Validate, and install the build using Install > Wirelessly. This disables scheduled checks only; it does not remove the update component or change any P1MeterKit sensors.

The adopted YAML continues to contain a packages: link to the SmartHomeShop GitHub repository. ESPHome uses that link on the Home Assistant host when it compiles your firmware. The device itself no longer polls for firmware versions after the customized build is installed.

To restore automatic checks, remove the added update: block and install the firmware again. If ESPHome cannot find the firmware_update ID, update P1MeterKit through the SmartHomeShop web flasher before applying this customization.

P1MeterKit runs on ESPHome, an open-source firmware platform that works with Home Assistant. ESPHome allows you to customize every aspect of your device's behavior while maintaining full local control, no cloud required.

Open Source & GitHub

All P1MeterKit firmware is 100% open source and available on GitHub:

🔗 github.com/smarthomeshop/p1meterkit

The repository includes:

  • Complete ESPHome configurations for V1 (ESP8266), V2 (ESP32-C3), and V3 (ESP32-C6)
  • DSMR/P1 port reader implementation
  • MBus gas meter integration
  • Automated builds via GitHub Actions
  • Community contributions welcome (PRs & issues)

You can view, modify, and customize the firmware to suit your needs, from adjusting sensor update intervals to adding completely new features.

Hardware Versions

P1MeterKit is available in three hardware versions:

V1 - ESP8266

  • Microcontroller: ESP8266
  • Connectivity: WiFi only
  • Features: Standard DSMR/P1 reading, MBus gas meter, temperature/humidity sensors
  • Best for: Basic smart meter monitoring

V2 - ESP32-C3

  • Microcontroller: ESP32-C3
  • Connectivity: WiFi + Bluetooth (Improv BLE)
  • Features: All V1 features + improved performance + BLE provisioning
  • Best for: Existing V2 installations with easier setup

V3 - ESP32-C6 (Current)

  • Microcontroller: ESP32-C6
  • Connectivity: WiFi + Bluetooth (Improv BLE)
  • Features: All V2 features + current-generation ESP32-C6 hardware + Thread with the Thread firmware
  • Best for: New installations and current firmware support

How to check your version: Check the Hardware Version sensor in Home Assistant. The "ESPHome Version" sensor only shows the ESPHome release.

Firmware Variants

Variant Connection Use with
WiFi (local) 2.4 GHz WiFi Home Assistant, fully local
WiFi + SmartHomeShop App (cloud) 2.4 GHz WiFi SmartHomeShop app, Home Assistant stays possible
Thread (V3) Thread network Home Assistant, local only. See Connect via Thread

On V2 and V3 you switch between the local and the cloud variant with the Firmware Variant selector in Home Assistant or on the setup page. The device then installs the chosen variant over the air. V1 has no selector: use the web flasher.

Quick Update Methods

Method 1: Home Assistant (Easiest)

For regular firmware updates (recommended):

  1. Go to Settings → Devices & Services → Devices
  2. Select your P1MeterKit device
  3. Enable the Update entity if it's disabled
  4. Open the Update entity and click Check for updates
  5. Click Install to download and apply the update
  6. The device will reboot automatically

V1: has no update entity. Update it with Method 2 or Method 3.

Method 2: ESPHome Device Builder

For updates with custom configurations:

⚠️ Important: This method requires the ESPHome Device Builder app (not just the ESPHome integration). If you haven't installed it yet, see the ESPHome Integration Guide section below for step-by-step installation instructions.

  1. Open the ESPHome Device Builder in Home Assistant (from the sidebar)
  2. Click on your P1MeterKit device card
  3. Click Install → choose Wirelessly
  4. Wait for the OTA update to complete

Method 3: USB-C Web Flasher

For changing hardware versions or recovering devices:

  1. Connect P1MeterKit with a USB-C data cable to a computer with Chrome or Edge
  2. Open the flasher: smarthomeshop.io/en/firmware?product=p1meterkit
  3. Select your hardware version (V1, V2, or V3)
  4. Choose how you use the device: Local with Home Assistant or SmartHomeShop app + local use
  5. Click Install firmware and choose the USB port of your device

Note: Flashing here writes the factory firmware and erases all settings, including your WiFi credentials. Set up WiFi again afterwards.

ESPHome Integration Guide

Want to customize your P1MeterKit firmware? Follow this step-by-step guide to adopt your device in ESPHome and make modifications.

🚨 Critical: Understanding the Difference

Many users get confused between two different things:

  • ESPHome Integration (Settings → Devices & Services → Integrations) - This is how your P1MeterKit communicates with Home Assistant. You probably already have this. ✅
  • ESPHome Device Builder app (Settings → Apps, called add-ons before Home Assistant 2026.2) - This is the tool you need to edit, build, and flash firmware. You need to install this separately! 🔧

To customize firmware, you MUST install the ESPHome Device Builder app below. Having just the integration is not enough!

Step 1: Install the ESPHome Device Builder App

If you haven't installed the ESPHome Device Builder app yet:

  1. Open Home Assistant → Settings → Apps
  2. Click Install app
  3. Search for ESPHome Device Builder
  4. Click it → Install
  5. Enable Start on boot and Show in sidebar
  6. Click Start

Step 2: Adopt Your P1MeterKit

Adopting allows ESPHome to manage your device's configuration:

  1. Open ESPHome from the Home Assistant sidebar
  2. Your P1MeterKit should appear as a discovered device
  3. Click Adopt on the P1MeterKit card
  4. Give it a name (e.g., "Living Room P1 Meter")
  5. Click Adopt again to confirm

ESPHome will now download the current configuration from your device.

What does the adopted configuration look like?

After adoption, you'll see a YAML configuration that looks like this:

substitutions:
  name: p1meterkit-a1b2c3
  friendly_name: P1MeterKit A1B2C3

packages:
  smarthomeshop.p1meterkit: github://smarthomeshop/p1meterkit/p1meterkit-v3/p1meterkit.yaml@main

esphome:
  name: ${name}
  name_add_mac_suffix: false
  friendly_name: ${friendly_name}

api:
  encryption:
    key: YOUR_UNIQUE_ENCRYPTION_KEY_HERE==

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

Understanding this structure:

  • substitutions: Device-specific variables (name, friendly name). Add more here to customize behavior!
  • packages: Links to the base configuration on GitHub. This automatically pulls updates when available.
  • api/wifi: Your device's unique encryption key and WiFi credentials.

This modular approach means: ✅ You get automatic updates from GitHub ✅ Your customizations stay separate in substitutions ✅ You don't need to copy/paste the entire configuration

Step 3: Customize the Configuration

After adoption, you can modify the YAML configuration:

  1. Click Edit on your adopted P1MeterKit device
  2. The YAML editor opens with your current configuration
  3. Make your desired changes (see examples below)
  4. Click Save

Step 4: Upload Modified Firmware

After making changes:

  1. Click Install on your device card
  2. Choose Wirelessly (recommended) or Plug into this computer
  3. ESPHome will compile and upload your custom firmware
  4. Wait for the device to reboot and reconnect

✅ Done! Your P1MeterKit is now running custom firmware.

Advanced Customization

Example 1: Adjust DSMR Update Interval

Make the kit read the P1 meter less often:

dsmr:
  request_interval: 30s  # Default is 0ms: every telegram your meter sends is read

Example 2: Add Custom Sensors

Calculate what the meter totals cost at a fixed price:

sensor:
  - platform: template
    name: "Total Energy Cost"
    unit_of_measurement: "EUR"
    device_class: monetary
    lambda: |-
      // Assuming 0.30 EUR per kWh
      float cost = id(dsmr_electricity_delivered_1).state * 0.30;
      cost += id(dsmr_electricity_delivered_2).state * 0.30;
      return cost;
    update_interval: 60s

Example 3: Gas Consumption Alerts

Gas usage alerts work best in Home Assistant, without changing the firmware. Create a Utility Meter helper with an hourly reset cycle on Gas Consumed (see Creating Utility Meters) and let an automation notify you when the helper goes above your limit.

Example 4: Custom LED Indicators

The firmware already exposes a LED Green light entity. Use it in a Home Assistant automation, no YAML change needed: turn it on when Power Consumed goes above your limit, and off again when it drops.

Learn More: Check the ESPHome documentation for complete configuration reference.

Configuration Structure

P1MeterKit firmware uses a modular architecture:

p1meterkit-v1/  (ESP8266)
├── p1meterkit.yaml              # WiFi firmware
├── p1meterkit-cloud.yaml        # WiFi + SmartHomeShop App
└── [component files]

p1meterkit-v2/  (ESP32-C3)
├── p1meterkit.yaml              # WiFi firmware
├── p1meterkit-cloud.yaml        # WiFi + SmartHomeShop App
└── [component files]

p1meterkit-v3/  (ESP32-C6)
├── p1meterkit.yaml              # WiFi firmware
├── p1meterkit-cloud.yaml        # WiFi + SmartHomeShop App
├── p1meterkit-thread.yaml       # Thread firmware
└── [component files]

This modular design makes it easy to:

  • Add/remove sensors
  • Share configurations across devices
  • Maintain consistency across versions
  • Contribute improvements back to the community

Troubleshooting

Quick fix for N/A electricity values: if P1MeterKit powers on but electricity data stays empty, first add USB-C power, then adopt the device in Home Assistant → ESPHome Device Builder app, and test the older DSMR profile below. If only gas is missing, usually test gas_mbus_id values 1 to 4.

Device Won't Update OTA

Symptoms: OTA update fails or times out

Solutions:

  1. Ensure the device is powered on and connected to WiFi
  2. Check that the device is within WiFi range (strong signal)
  3. Verify the P1 meter is providing power (RJ12 cable connected)
  4. Try rebooting the device via Home Assistant
  5. If all else fails, flash via USB-C cable

No Data from Smart Meter

Symptoms: All sensor values show "unknown" or "0"

Solutions:

  1. Check RJ12 connection: Ensure cable is properly connected to both P1 meter and device
  2. Add USB-C power: Older DSMR meters do not always provide enough power over P1
  3. Older DSMR profile: If values stay empty, adopt the device in ESPHome and test an older UART / DSMR profile:
uart:
  id: uart_dsmr
  baud_rate: 9600
  data_bits: 7
  parity: EVEN
  stop_bits: 1

dsmr:
  id: dsmr_instance
  uart_id: uart_dsmr
  crc_check: false
  1. DSMR 2.2 alternative: If your meter is confirmed DSMR 2.2, test parity: NONE instead of EVEN
  2. Check logs: View ESPHome logs for DSMR parsing errors
  3. Cable quality: Use a good quality RJ12 cable (some cheap cables have incorrect pinout)
  4. Gas only missing? Then the issue is usually gas_mbus_id, not the P1 cable itself

Gas Consumption Not Updating

Symptoms: Gas reading stays at 0 or doesn't update

Solutions:

  1. Gas meter link: Verify your gas meter is connected to your smart meter. The kit reads gas through the P1 port, there is no separate cable to the kit
  2. Gas meter compatibility: Not all gas meters have MBus output
  3. Update frequency: Gas meters typically update every hour
  4. Check configuration: Test gas_mbus_id values 1 to 4, see Gas MBus Configuration

Device Not Discovered After Flashing

Symptoms: P1MeterKit doesn't appear in ESPHome after USB flashing

Solutions:

  1. The device may have lost WiFi credentials during flashing
  2. Connect via USB-C and check the logs in ESPHome
  3. V2/V3 only: Use Improv via BLE to reconfigure WiFi:
    • Open Home Assistant companion app
    • Go to Settings → Devices → Add Device
    • Select your P1MeterKit from the BLE devices list
  4. Alternatively, connect to the captive portal:
    • Device creates a WiFi AP named "p1meterkit" with the password "p1meterkit"
    • Connect to it and configure WiFi through the web interface

Incorrect Tariff Detection

Symptoms: Energy values appear in wrong tariff

Solutions:

  1. Check if your energy provider uses standard tariff switching
  2. Some smart meters have non-standard DSMR implementations
  3. Consider using Home Assistant utility meter for tariff management
  4. Check DSMR logs for tariff indicator values

High WiFi Reconnection Rate

Symptoms: Device frequently disconnects and reconnects

Solutions:

  1. Check signal strength: Ensure strong WiFi signal (-70 dBm or better)
  2. Power supply: Verify stable power from P1 port (some meters provide unstable voltage)
  3. Add external power: Connect USB-C power for more stable operation
  4. Router settings: Disable WiFi band steering and enable 2.4GHz only
  5. V1 (ESP8266): Known to be less stable on busy WiFi networks, consider upgrading to V3

Compilation Errors in ESPHome

Symptoms: Custom YAML fails to compile

Solutions:

  1. Check for YAML syntax errors (indentation must be consistent)
  2. Verify you're using compatible ESPHome version (check GitHub repo requirements)
  3. Check the compilation log for specific error messages
  4. Compare your changes against the official configuration
  5. Ask for help on GitHub Issues or our Discord community

DSMR Specifications

P1MeterKit supports the following DSMR (Dutch Smart Meter Requirements) versions:

  • DSMR 2.2 (older meters, with custom ESPHome UART settings)
  • DSMR 4.0/4.2 (common)
  • DSMR 5.0 (most modern meters)

What is DSMR? DSMR is the protocol used by Dutch and Belgian smart electricity meters to communicate energy data. The P1 port provides real-time access to:

  • Electricity consumption per tariff (day/night)
  • Electricity production (solar panels)
  • Real-time power usage
  • Voltage and current per phase
  • Gas consumption (via MBus)

Firmware Changelog

Latest changes are announced alongside releases. Major updates will appear here.

Where to find changes:

Additional Resources

Need help? Visit our Support Portal or join our Discord community!

Thread Firmware

P1MeterKit V3 can also join a Thread network for local Home Assistant use, reading one DSMR telegram every 5 seconds. See Connect P1MeterKit via Thread.