### Added

- Added battery level and last updated sensors

Author: fwmone

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.1.1] - 2026-02-07
+
+### Added
+
+- Added battery level and last updated sensors
+
 ## [0.1.0] - 2026-02-03
 
 ### Added

README.md

@@ -13,8 +13,12 @@
   - [Sensor](#sensor)
     - [State:](#state)
     - [Attributes:](#attributes)
-  - [Services](#services)
-  - [Automation Examples](#automation-examples)
+- [Services](#services)
+- [Automation Examples](#automation-examples)
+- [Device Telemetry](#device-telemetry)
+  - [Telemetry sensors](#telemetry-sensors)
+  - [Manual refresh (optional)](#manual-refresh-optional)
+  - [Battery percentage calculation](#battery-percentage-calculation)
 - [API / Upload Method](#api--upload-method)
 - [Troubleshooting](#troubleshooting)
   - [Upload succeeds but frame shows old image](#upload-succeeds-but-frame-shows-old-image)
@@ -26,21 +30,24 @@
 
 # Features
 
-A small Home Assistant custom integration to **upload images from the Home Assistant server to a Paperlesspaper e-paper frame** using the WireWire API. The integration is designed to work well with Home Assistant automations (e.g. upload a new image twice a day), and provides a *“varied random”* image selection that avoids repeating the same images too often.
+A small Home Assistant custom integration to **upload images from the Home Assistant server to a paperlesspaper e-paper frame** using the WireWire API. The integration is designed to work well with Home Assistant automations (e.g. upload a new image twice a day), and provides a *“varied random”* image selection that avoids repeating the same images too often.
 
-- Upload a random image from an input folder to a Paperlesspaper frame via API
+- Upload a random image from an input folder to a paperlesspaper frame via API
 - "Varied random" selection:
   - remembers recently used images
   - recent-window size = **50% of available images** (min 5, max 50)
   - avoids repetition until the pool is exhausted
 - Optional publish/copy of the selected image into `/config/www/...` for preview/debugging
 - Optional cleanup of the publish directory before publishing
 - Robust upload retries with exponential backoff
-- Home Assistant sensor showing:
+- Gets device information like battery level and last update
+- Home Assistant sensors showing:
   - last upload timestamp
   - current file name
   - last result (success/failed/dry_run)
   - last HTTP status / error
+  - battery level / percentage
+  - last update
 
 # 📦 Installation
 
@@ -60,14 +67,17 @@ A small Home Assistant custom integration to **upload images from the Home Assis
 
 # Configuration
 
+Please follow the steps for [generating an API key](https://paperlesspaper.de/posts/api). 
+
 This integration currently uses YAML configuration.
 
 Add this to your `configuration.yaml`:
 
 ```yaml
 paperlesspaper_push:
   api_key: !secret paperlesspaper_api_key
-  paper_id: !secret paperlesspaper_paper_id
+  paper_id: "YOUR_PAPER_ID"
+  device_id: "YOUR_DEVICE_ID"
 
   # optional:
   base_url: https://api.memo.wirewire.de/v1
@@ -82,7 +92,6 @@ Add the secrets to secrets.yaml:
 
 ```yaml
 paperlesspaper_api_key: "YOUR_API_KEY"
-paperlesspaper_paper_id: "YOUR_PAPER_ID"
 ```
 
 Restart Home Assistant after changing YAML.
@@ -119,7 +128,7 @@ This is useful for debugging or previewing the selected image from Home Assistan
 - last_error
 - published_name
 
-## Services
+# Services
 ```paperlesspaper_push.upload_random```
 
 Uploads a (varied) random image.
@@ -148,7 +157,7 @@ Example:
 service: paperlesspaper_push.reset_recent
 ```
 
-## Automation Examples
+# Automation Examples
 
 Upload twice per day:
 
@@ -170,6 +179,44 @@ action:
   - service: paperlesspaper_push.upload_random
 ```
 
+# Device Telemetry
+
+In addition to upload/push functionality, the integration can poll the paperlesspaper API for **device telemetry** (battery, timestamps, sync state).
+
+The integration will periodically call ```GET /v1/devices/<device_id>``` and update the related sensors.
+
+## Telemetry sensors
+
+When device_id is configured, the following sensors are created:
+
+- Battery
+  - sensor.paperlesspaper_push_battery_voltage (V)
+  - sensor.paperlesspaper_push_battery (%)
+
+- Timestamps
+  - sensor.paperlesspaper_push_last_reachable
+  - sensor.paperlesspaper_push_next_device_sync
+  - sensor.paperlesspaper_push_updated_at
+  - sensor.paperlesspaper_push_loaded_at
+
+Note: The API exposes batLevel as a raw value (typically millivolts for 4×AAA in series).
+The integration converts it to a percentage using a pragmatic min/max voltage model.
+
+## Manual refresh (optional)
+
+You can trigger an immediate telemetry refresh via the service:
+```paperlesspaper_push.refresh_device```
+
+## Battery percentage calculation
+
+Battery percentage is derived from the reported raw battery voltage (`batLevel`).
+
+Default mapping (4×AAA in series):
+- 6.4 V → 100%
+- 4.8 V → 0%
+
+Values are clamped to the range and mapped linearly in between.
+
 # API / Upload Method
 
 The upload is performed using a multipart form-data request similar to:

custom_components/paperlesspaper_push/__init__.py

@@ -5,6 +5,8 @@
 from homeassistant.helpers.storage import Store
 from homeassistant.helpers.typing import ConfigType
 
+from .coordinator import PaperlesspaperDeviceCoordinator
+
 from .const import (
     DOMAIN,
     CONF_API_KEY,
@@ -15,6 +17,9 @@
     CONF_TIMEOUT,
     CONF_MAX_ATTEMPTS,
     CONF_PUBLISH,
+    CONF_DEVICE_ID, 
+    CONF_SCAN_INTERVAL, 
+    DEFAULT_SCAN_INTERVAL,
     DEFAULT_BASE_URL,
     DEFAULT_INPUT_DIR,
     DEFAULT_PUBLISH_DIR,
@@ -29,6 +34,7 @@
     SERVICE_FIELD_FORCE_FILE,
     SERVICE_FIELD_DRY_RUN,
     SERVICE_FIELD_PUBLISH,
+    SERVICE_REFRESH_DEVICE,
     ATTR_CURRENT_FILENAME,
     ATTR_LAST_RESULT,
     ATTR_LAST_HTTP_STATUS,
@@ -79,6 +85,23 @@ async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
         CONF_PUBLISH: bool(cfg.get(CONF_PUBLISH, DEFAULT_PUBLISH)),
     }
 
+    device_id = cfg.get(CONF_DEVICE_ID)
+    scan_interval = int(cfg.get(CONF_SCAN_INTERVAL, DEFAULT_SCAN_INTERVAL))
+
+    if device_id:
+        coordinator = PaperlesspaperDeviceCoordinator(
+            hass=hass,
+            api_key=api_key,
+            base_url=hass.data[DOMAIN]["config"][CONF_BASE_URL],
+            device_id=device_id,
+            scan_interval_s=scan_interval,
+        )
+        hass.data[DOMAIN]["device_coordinator"] = coordinator
+        hass.data[DOMAIN]["device_unique_prefix"] = f"{DOMAIN}_{device_id}"
+
+    # Initial fetch so sensors have values right away (YAML setup, no config entry)
+    await coordinator.async_refresh()
+
     # Stores
     hass.data[DOMAIN]["store_state"] = Store(hass, STORE_VERSION, STORE_KEY_STATE)
     hass.data[DOMAIN]["store_recent"] = Store(hass, STORE_VERSION, STORE_KEY_RECENT)
@@ -203,7 +226,14 @@ async def handle_reset_recent(call):
         if dispatcher:
             dispatcher()
 
+    async def handle_refresh_device(call):
+        coordinator = hass.data.get(DOMAIN, {}).get("device_coordinator")
+        if coordinator:
+            await coordinator.async_request_refresh()
+
     hass.services.async_register(DOMAIN, SERVICE_UPLOAD_RANDOM, handle_upload_random)
     hass.services.async_register(DOMAIN, SERVICE_RESET_RECENT, handle_reset_recent)
+    hass.services.async_register(DOMAIN, SERVICE_REFRESH_DEVICE, handle_refresh_device)
 
     return True
+

custom_components/paperlesspaper_push/const.py

@@ -8,13 +8,16 @@
 CONF_TIMEOUT = "timeout"
 CONF_MAX_ATTEMPTS = "max_attempts"
 CONF_PUBLISH = "publish"
+CONF_DEVICE_ID = "device_id"         
+CONF_SCAN_INTERVAL = "scan_interval"
 
 DEFAULT_BASE_URL = "https://api.memo.wirewire.de/v1"
 DEFAULT_INPUT_DIR = "/media/picture-frames/paperlesspaper"
 DEFAULT_PUBLISH_DIR = "/config/www/picture-frames/paperlesspaper"
 DEFAULT_TIMEOUT = 30
 DEFAULT_MAX_ATTEMPTS = 4
 DEFAULT_PUBLISH = True
+DEFAULT_SCAN_INTERVAL = 900  # 15 min
 
 STORE_VERSION = 1
 STORE_KEY_STATE = f"{DOMAIN}_state"
@@ -33,3 +36,4 @@
 SERVICE_FIELD_FORCE_FILE = "force_file"
 SERVICE_FIELD_DRY_RUN = "dry_run"
 SERVICE_FIELD_PUBLISH = "publish"
+SERVICE_REFRESH_DEVICE = "refresh_device"

custom_components/paperlesspaper_push/coordinator.py

@@ -0,0 +1,39 @@
+import logging
+from datetime import timedelta
+
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed
+from homeassistant.helpers.aiohttp_client import async_get_clientsession
+
+from .const import DOMAIN
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class PaperlesspaperDeviceCoordinator(DataUpdateCoordinator[dict]):
+    def __init__(self, hass: HomeAssistant, api_key: str, base_url: str, device_id: str, scan_interval_s: int):
+        self.hass = hass
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._device_id = device_id
+
+        super().__init__(
+            hass,
+            _LOGGER,
+            name=f"{DOMAIN}_device",
+            update_interval=timedelta(seconds=scan_interval_s),
+        )
+
+    async def _async_update_data(self) -> dict:
+        session = async_get_clientsession(self.hass)
+        url = f"{self._base_url}/devices/{self._device_id}"
+        headers = {"x-api-key": self._api_key}
+
+        try:
+            async with session.get(url, headers=headers, timeout=30) as resp:
+                text = await resp.text()
+                if resp.status != 200:
+                    raise UpdateFailed(f"HTTP {resp.status}: {text[:3000]}")
+                return await resp.json()
+        except Exception as e:
+            raise UpdateFailed(str(e)) from e