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 — claim your Tome and manage your conversions.