# Marstek Open API Udp

> How this integration talks to Marstek devices via the local Open API over UDP (JSON messages) and how to handle errors safely Use when this capability is needed.

- Skill: `tomevault-io/marstek-open-api-udp` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/marstek-open-api-udp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/marstek-open-api-udp/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/marstek-open-api-udp

---


# Marstek Device Open API (UDP)

This repository communicates with Marstek devices using the **Open API over UDP** as documented in `docs/marstek_device_openapi.MD`.
In code, this is encapsulated by the `py-marstek` library (`pymarstek`).

## When to Use

- You need to change how device data is fetched (polling)
- You’re debugging connectivity or “no data” scenarios
- You’re adding new data points that might require additional Open API methods

## Transport & Message Shape

- Transport is UDP to the device (default port **30000**).
- Messages are JSON objects with a `method` and `params`, e.g.:
  - Discovery: `Marstek.GetDevice`
  - Status: `ES.GetStatus`, `ES.GetMode`, `Bat.GetStatus`, `PV.GetStatus`, `EM.GetStatus`
  - Control: `ES.SetMode`

Discovery pattern from the spec:
- A UDP broadcast may first receive a `Parse error` response (devices reacting to a non-JSON broadcast probe).
- Then send a proper JSON request with `method: Marstek.GetDevice` to receive the device’s metadata including `ip`, `ble_mac`, `wifi_mac`, `device`, and `ver`.

## Key Objects & Calls (in this repo)

- Library client: `pymarstek.MarstekUDPClient`
- Used patterns:
  - `await udp_client.discover_devices(...)` (config flow + scanner)
  - `await udp_client.send_request(...)` (setup connectivity check)
  - `await udp_client.get_device_status(...)` (coordinator polling)

Important library behavior (current implementation):
- `get_device_status(...)` can return **default values** on failure instead of raising.
- The coordinator treats `device_mode == "Unknown"` as “no valid data received” and falls back to previous `coordinator.data`.

## Error Handling Contract

The integration aims to be resilient to device/network flakiness:

- **Timeouts / OSError / ValueError**
  - Meaning: UDP request did not complete, network unreachable, or response parse issues.
  - Behavior in polling: log a warning and return previous data (entities keep last-known values instead of flapping).
  - Behavior in setup: raise `ConfigEntryNotReady` to let HA retry while the scanner updates IP if needed.

Local API enablement:
- Devices must have **OPEN API enabled** in the Marstek app or discovery/polling will fail.

## Concurrency Guidance

Marstek devices can be sensitive to request bursts.

- Prefer one request per update interval.
- Avoid parallel requests.
- Keep all I/O in the coordinator (entities read from coordinator data).
- All device I/O must stay async; do not introduce blocking sockets or file access on the event loop.

Control actions (`ES.SetMode`):
- Pause polling for the target host while sending a command + verifying the result (see `custom_components/marstek/device_action.py`).
- Use retries + backoff; UDP packets may be dropped.

## Practical Debugging Steps

- If discovery finds no devices:
  - Confirm device is on the same LAN segment and OPEN API is enabled.
  - Confirm UDP port (default 30000) is not blocked.
- If polling returns stale/default data:
  - Check logs for `device_mode=Unknown` warnings (indicates no valid response).
  - Validate the device IP in the config entry; scanner should update it automatically.

## When NOT to Use

- Don’t implement raw UDP handling in entities; keep it inside `pymarstek` + coordinator.
- Don’t add extra Open API calls per poll cycle unless you can justify the added device load.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/taurgis) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->