diff --git a/.github/INITIAL_PR.md b/.github/INITIAL_PR.md new file mode 100644 index 0000000..57d94b1 --- /dev/null +++ b/.github/INITIAL_PR.md @@ -0,0 +1,9 @@ +Adds an experimental ESPHome configuration for local Home Assistant control of a Eurom Mon Soleil DSP 400 WiFi heater through its Tuya MCU. The maintainer is still testing; the 650/770 W and Swiss-plug variants are explicitly unverified candidates. + +Includes the sanitized configuration, two approved device photographs, setup and datapoint documentation, a hardware test checklist, contribution/AI instructions and dummy-secret validation CI. Public preparation removes the literal fallback AP password, private device address, placeholder area and unrelated Home Assistant helper while preserving the original heater mappings. + +Factory backup/restoration, initial flashing and the internal four-pin connector pinout remain TODO. The manufacturer manual and private original configuration are not included. The README documents M/P behavior, unknown timer persistence and the DP101 write interaction in the climate component. + +Validation: ESPHome 2026.10.1 configuration validation and C++ generation results are recorded in TESTING.md. Full firmware/toolchain compilation and hardware testing of this public example are not claimed; see that record for any environment limitation. The workflow has not run on GitHub before publication. + +Created with assistance from ChatGPT & Codex (OpenAI). Maintainer review and supervised hardware verification remain necessary. diff --git a/.github/ISSUE_TEMPLATE/compatibility-report.md b/.github/ISSUE_TEMPLATE/compatibility-report.md new file mode 100644 index 0000000..0ed939e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/compatibility-report.md @@ -0,0 +1,19 @@ +--- +name: Device compatibility / behavior report +about: Report a tested model or reproducible behavior with redacted evidence +title: "[Eurom DSP] " +labels: "" +assignees: "" +--- + +Model and article number: +Module / PCB revision (or unknown): +ESPHome and Home Assistant versions: +Configuration commit: + +Initial mode, ECO and timer state: +Steps / expected behavior: +Observed behavior and redacted datapoint changes: +What was not tested: + +Do not upload credentials, private logs, flash dumps or the manufacturer manual. Never create hazardous physical conditions to reproduce an issue. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..075500c --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,16 @@ +## Problem and resulting behavior + +Describe what changes and why. Identify the device/model and relevant datapoints. + +## Validation + +- Software checks and exact ESPHome version: +- Hardware tested (model/article number/revision), or explicitly not tested: +- Expected and observed behavior / remaining unknowns: +- AI assistance used and human review performed: + +## Publication review + +- [ ] No credentials, private addresses, identifying device logs, firmware dumps or manufacturer manual included. +- [ ] Experimental status and untested model limitations remain accurate. +- [ ] Relevant documentation/test record updated; physical claims are backed by evidence. diff --git a/.github/workflows/validate-esphome.yaml b/.github/workflows/validate-esphome.yaml new file mode 100644 index 0000000..30967fb --- /dev/null +++ b/.github/workflows/validate-esphome.yaml @@ -0,0 +1,25 @@ +name: Validate ESPHome + +on: + push: + pull_request: + workflow_dispatch: + +permissions: + contents: read + +jobs: + validate: + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@v5 + - uses: actions/setup-python@v6 + with: + python-version: '3.12' + cache: pip + cache-dependency-path: requirements-dev.txt + - name: Install pinned ESPHome + run: python -m pip install -r requirements-dev.txt + - name: Validate YAML and generate C++ with temporary dummy secrets + run: python scripts/validate-esphome.py --generate diff --git a/.gitignore b/.gitignore index 4d22a4d..1c697ed 100644 --- a/.gitignore +++ b/.gitignore @@ -22,6 +22,7 @@ firmware/ *.pdf # Local tooling +/PUBLISHING.md .venv/ venv/ __pycache__/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..85f472c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,30 @@ +# Instructions for coding assistants + +## Scope + +This repository contains public Home Assistant and ESPHome examples. Read the relevant project README, datapoint notes, test record and TODO before changing a device configuration. Keep changes small and reviewable. Explain behavior changes and preserve existing entity names and secret names unless a migration is documented. + +## Privacy and publication + +- Never commit actual credentials, API keys, private addresses, household details, private logs, firmware images or flash backups. Use `!secret` and explicit example values. +- Only the supplied public configuration and two approved device photographs may be published from the initial source material. Do not add the manufacturer PDF or extracted manual pages. Link to the manufacturer instead. +- Never assume `.gitignore` removes already tracked secrets. Inspect the staged diff and filenames before a commit. +- Do not embed a remote GitHub package dependency, telemetry or a cloud service into a working local configuration without an explicit request. + +## Hardware evidence and heater behavior + +- Distinguish maintainer observations, manufacturer descriptions and new contributor measurements. Never fabricate logs or mark untested variants as supported. +- Preserve the existing datapoint IDs, enum values, board and UART pins unless a proposed change includes evidence for that hardware revision. +- Do not invent connector pinouts, electrical isolation, voltage levels, module identities or flashing/backup procedures. GPIO assignments in YAML do not establish connector order. +- M mode is manual heat control; setting a target temperature does not make M mode thermostatic. Do not describe it otherwise. +- DP101 is shared by the climate component and a writable select. Account for the climate component writing it on Heat commands. Document and test changes to this interaction. +- Do not add automatic heating on boot, reconnect or time synchronization. Do not bypass safety mechanisms or create artificial fault conditions to test protections. +- Keep factory-backup, initial-flash and four-pin-connector instructions as TODO until verified evidence is provided. A qualified contributor may submit a PR with measurements, orientation photos and revision details. + +## Validation and reporting + +- Use the pinned ESPHome version in `requirements-dev.txt`. Run `python3 scripts/validate-esphome.py --generate` after configuration changes; use dummy credentials only. +- Validation and C++ generation are not firmware compilation, hardware verification or a safety assessment. Report exactly which checks ran. +- Hardware test records must state model/article number, module/PCB revision if known, ESPHome version, steps, expected result, observed result and date. Explicitly identify tests that were not run. +- Keep experimental status until the maintainer has evidence to change it. Update README, test notes and changelog when behavior changes. +- Describe AI assistance in the PR and preserve human authorship. Never claim the assistant physically tested a heater. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..bb57b22 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,20 @@ +# Contributing + +Small, focused pull requests are welcome, including documentation and compatibility reports. + +1. Read the project's README and TODO. Open an issue first for a substantial behavior or hardware change. +2. Work on a branch. Keep private device YAML, credentials, firmware and backups outside tracked files. +3. Describe the problem, resulting behavior and evidence. For a new model, include the article number, module/PCB revision if known and a redacted datapoint report. A similar enclosure or wattage is insufficient evidence. +4. Install `requirements-dev.txt` in a virtual environment and run `python3 scripts/validate-esphome.py --generate`. +5. For behavior changes, record relevant supervised device tests using the project test checklist. State clearly when hardware testing was not possible. +6. Review `git diff --cached` and `git diff --cached --name-only` before committing. Do not attach the manufacturer manual or raw device logs. + +Never intentionally obstruct, tip, overheat or fault a heater to test this project. Follow the manufacturer's operating instructions. Hardware work belongs with a competent, qualified person; no verified internal wiring guide is currently provided here. + +## AI-assisted contributions + +AI assistance is allowed. Contributors remain responsible for correctness, permission to contribute material, privacy and safety. Briefly disclose the tools used and what was checked in the PR. Follow [AGENTS.md](AGENTS.md); do not substitute plausible AI-generated mappings or pinouts for measurements. + +## License + +By contributing original material, you agree to provide it under the repository's MIT License. Only submit photographs and other material you have permission to redistribute. Do not upload manufacturer firmware or manuals. diff --git a/README.md b/README.md index 604fdf7..c0a4876 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Community configurations and notes for Home Assistant and ESPHome, developed and Each project documents its own requirements, observations and limitations. Device compatibility is only claimed when supported by hardware evidence. -See [CONTRIBUTING.md](CONTRIBUTING.md) for contributions, [AGENTS.md](AGENTS.md) for AI-assisted work and [PUBLISHING.md](PUBLISHING.md) for the initial GitHub setup. +See [CONTRIBUTING.md](CONTRIBUTING.md) for contributions and [AGENTS.md](AGENTS.md) for AI-assisted work. ## Credits and license diff --git a/esphome/eurom-mon-soleil-dsp/CHANGELOG.md b/esphome/eurom-mon-soleil-dsp/CHANGELOG.md new file mode 100644 index 0000000..039a5b2 --- /dev/null +++ b/esphome/eurom-mon-soleil-dsp/CHANGELOG.md @@ -0,0 +1,11 @@ +# Changelog + +## Unreleased - public starter prepared 2026-10-29 + +- Added the experimental Eurom Mon Soleil DSP project, attributed datapoint observations and the two maintainer-supplied photographs. +- Preserved the original board, UART, DP mappings, entity names and encrypted OTA configuration. No heater-control logic change was intentionally introduced. +- Replaced the literal fallback AP password with a `!secret` reference. Wi-Fi and API credentials remain secret references; example values contain no working credentials. +- Removed the private `wifi.use_address`, placeholder area and unrelated Home Assistant helper text sensor. No heater behavior depended on that helper in the supplied YAML. +- Added an ESPHome minimum version of 2026.9.0 for encrypted OTA syntax and a 2026.10.1 validation baseline. +- Added setup notes, raw DP12 limitations, M/P distinctions, DP101 write-path caveat, testing checklist and evidence requirements. +- Left manufacturer backup/restoration, initial flashing, module identification and connector pinout as explicit TODOs. The manual is excluded from the public project. diff --git a/esphome/eurom-mon-soleil-dsp/DATAPOINTS.md b/esphome/eurom-mon-soleil-dsp/DATAPOINTS.md new file mode 100644 index 0000000..9b7829d --- /dev/null +++ b/esphome/eurom-mon-soleil-dsp/DATAPOINTS.md @@ -0,0 +1,34 @@ +# Datapoints and evidence + +## Provenance + +The maintainer's supplied YAML says the following observations were confirmed with logs and button tests on **2026-10-28** on a 400 W unit. Raw logs were not included with the public starter, so these are attributed maintainer observations, not independently repeated measurements. The Tuya product ID in the source is `wv9d5ocs76u6maqj`; it is a product identifier, not a per-device credential or compatibility guarantee. + +| DP | Reported type | Meaning/value | Evidence and limits | +| --- | --- | --- | --- | +| 1 | Boolean | Power / standby | Maintainer reports confirmed on/off | +| 2 | Integer | Target 0-37 °C; ECO selects 16 °C | Maintainer reports confirmed; thermostat requires P mode | +| 3 | Integer | Room temperature, °C | Maintainer reports confirmed; ambient accuracy and external probe unverified | +| 4 | Enum | 0 = Manual (M), 1 = Thermostat/program (P) | Maintainer reports confirmed with MODE button | +| 101 | Enum | 0 = heating/sun, 3 = off | Maintainer reports confirmed; bars button in M, thermostat in P; writable through both select and climate Heat path | +| 102 | Boolean | ECO fixed 16 °C / EC display | Maintainer reports confirmed; transition behavior still needs a test record | +| 12 | Bitmask | Raw fault indication; 0 observed/described as no fault | Listed in source; nonzero values and individual bit meanings not verified | + +No changed datapoint was observed when testing the remote's open-window control. Do not assign a guessed DP to it or invent a corresponding entity. + +## UART assumptions + +| Setting | Value in supplied YAML | +| --- | --- | +| ESPHome platform | ESP8266 | +| Board profile | `esp01_1m` | +| ESP RX | GPIO13 | +| ESP TX | GPIO15 | +| Baud rate | 9600 | +| Serial logger | Disabled (`baud_rate: 0`) | + +These values describe firmware settings for the test installation. They do not identify the exact module, confirm flash size, specify connector pin order or prove safe voltage levels/isolation. GPIO15 is an ESP8266 boot strap pin; the existing hardware must maintain correct boot conditions. Do not rewire based only on this table. + +## Evidence needed for changes + +For a mapping change or new device, provide model/article number, revision, ESPHome version and a redacted sequence showing initial state, one physical/HA action, changed DP value/type and resulting display/heat indication. Include conflicting observations and unknown enum values. Keep private identifiers out of logs, and never intentionally trigger dangerous physical fault conditions. diff --git a/esphome/eurom-mon-soleil-dsp/README.md b/esphome/eurom-mon-soleil-dsp/README.md new file mode 100644 index 0000000..8d7038e --- /dev/null +++ b/esphome/eurom-mon-soleil-dsp/README.md @@ -0,0 +1,89 @@ +# Eurom Mon Soleil DSP for ESPHome + +Local Home Assistant control of a **Eurom Mon Soleil DSP 400 WiFi** infrared heater, using ESPHome and the heater's existing Tuya MCU protocol. + +**Experimental: maintainer testing is in progress.** The supplied YAML records observations from one 400 W unit. Other variants are candidates for testing, not confirmed compatible devices. This is an ESPHome configuration, not a Home Assistant custom integration or a HACS package. + +Home Assistant communicates with ESPHome through its native API; ESPHome exchanges UART messages with the heater's control MCU. The MCU remains responsible for the heater controls. Its safety behavior after modification has not been independently verified. + +## Current scope + +This project provides configuration and operating notes for a suitable device **already running ESPHome with a verified MCU connection**. It is not yet a complete stock-to-ESPHome conversion guide. Factory firmware backup/restoration, initial flashing, module identification and the internal four-pin connector pinout are still [TODO](TODO.md). Do not infer a wiring or flashing procedure from the YAML. + +This is a mains-powered heater. Internal work must be performed by a competent, qualified person with the appliance disconnected and made safe. Do not connect a computer/programmer to potentially mains-referenced electronics. Follow the manufacturer's placement and operating instructions, keep the heater uncovered and supervise experimental operation. Home Assistant availability, a fault sensor reading of zero and a successful software build are not safety guarantees. + +## Models and compatibility + +| Model | Article number | Status | +| --- | --- | --- | +| DSP 400 WiFi, 400 W | 361896 | Base model family; maintainer testing one 400 W unit; confirm its label/article number and hardware revision | +| DSP 650 WiFi, 650 W | 361919 | Untested candidate | +| DSP 770 WiFi, 770 W | 361933 | Untested candidate | +| DSP 400 WiFi, 400 W, Swiss plug | 361902 | Untested candidate | +| DSP 650 WiFi, 650 W, Swiss plug | 361926 | Untested candidate | +| DSP 770 WiFi, 770 W, Swiss plug | 361940 | Untested candidate | + +Article numbers identify the product family, not verified electronics. Check the module, flash size, PCB revision, UART and datapoints before adapting this configuration. Do not assume all Mon Soleil, DSP Frame or similarly named models use the same hardware. + +## Exposed entities + +| Entity | Function / limitation | +| --- | --- | +| Eurom heater | Power, target temperature and current temperature; heating/idle indication from DP101 | +| Eurom mode | Manual (M) or Thermostat (P); this is separate from the climate card's Heat/Off selection | +| Eurom heating element | Writable DP101 select: On/Off; observed manual control in M mode; interaction with P mode needs testing | +| Eurom ECO (16 °C) | Fixed 16 °C ECO mode, as observed by the maintainer | +| Eurom room temperature | Additional standalone sensor using the same DP3 value as the climate entity | +| Eurom fault code | Raw DP12 value; fault bit meanings are not decoded or verified | +| ESP IP Address / SSID / BSSID / MAC | Network diagnostics; redact these values from public logs/screenshots | + +The board (`esp01_1m`), RX GPIO13, TX GPIO15 and 9600 baud are retained from the maintainer's source YAML. They are not a verified connector diagram or evidence that every production unit contains the same module. + +## Setup in ESPHome Device Builder + +1. Back up your current **local ESPHome YAML and secrets** before editing. This is separate from the factory flash-backup procedure, which is not documented yet. If the heater is still on stock firmware, stop here until a verified conversion guide is available. +2. Use ESPHome **2026.10.1** for the documented validation baseline. The encrypted OTA syntax requires ESPHome 2026.9.0 or later; older versions are not covered by this example. +3. Copy [eurom-400-wifi.yaml](eurom-400-wifi.yaml) to the Device Builder configuration directory, normally `/config/esphome/`. Keep an existing device's node name and encryption key when updating it. For an additional heater, choose a unique `esphome.name`, `friendly_name` and fallback AP SSID, and use a distinct device key and AP password. +4. Merge the entries from [secrets.example.yaml](secrets.example.yaml) into your local `secrets.yaml` in the same directory. Do not overwrite an existing secrets file or reuse the example credentials. +5. For a new device, generate a 32-byte base64 key with `openssl rand -base64 32`. Set a unique fallback AP password of 8-63 characters. For an existing device, retain its current API/OTA key: a new key in the uploader config alone will not rotate the installed key and can prevent updates. +6. Review the GPIO, board and datapoint assumptions against your already verified installation. Validate the configuration, then compile it in Device Builder. A passing validation is not a successful firmware build. Check flash/OTA size limits for the 1 MB target before installing. +7. Only update a known working ESPHome installation through its established update path. The example requires encrypted OTA. If the installed firmware does not yet offer it, follow the [official OTA migration procedure](https://esphome.io/components/ota/esphome/#enabling-encryption-on-an-existing-device), retaining the existing key/password as directed. No initial flashing procedure is provided here. +8. In Home Assistant, use the discovered ESPHome integration, or add **ESPHome** under **Settings → Devices & services → Add integration** using the device hostname/IP and API key. Confirm the entities and state feedback before operating the heater. See the [official integration documentation](https://www.home-assistant.io/integrations/esphome/). +9. In a supervised session, select **Thermostat (P)** for temperature regulation, then exercise Heat/Off and temperature changes and compare the physical display and logs. Use [TESTING.md](TESTING.md) to record results. Set the Home Assistant area locally if wanted. + +If mDNS does not resolve across your VLANs, add `wifi.use_address` to your **private local copy** with the actual reachable IP/hostname. It changes the address used by ESPHome tools; it does not configure a static device IP. Keep that address out of pull requests. + +## Operating details and known limitations + +- **M is manual heat control.** Changing the climate setpoint does not make it thermostatic. On the original controls, the remote's bars button or the panel's +/− buttons control heat in M mode. Do not use a climate temperature display as evidence that temperature regulation is active. +- **P is thermostat/program mode.** Select it explicitly for setpoint regulation. The climate card's Heat action does not select DP4/P mode. Existing weekly schedules can interact with this mode. +- **DP101 is not just telemetry.** ESPHome 2026.10.1's Tuya climate implementation writes `heating_value` to the active-state datapoint when Heat is selected. Here that can send DP101=0, in addition to DP1=true. The separate element select also writes DP101. The mapping is preserved from the source; verify Heat/Off, M/P and ECO combinations before relying on it. Source: [Tuya climate implementation at the validation version](https://github.com/esphome/esphome/blob/2026.10.1/esphome/components/tuya/climate/tuya_climate.cpp). +- **Open-window detection is not exposed.** No changed Tuya datapoint was seen in the maintainer's tests. This is an observation, not proof that the firmware can never report it. +- **Weekly timer editing is not implemented.** The original manual describes separate local/app timers and retained settings. What remains active after replacing the Wi-Fi firmware has not been established. Do not assume old schedules have been cleared or that ESPHome reproduces the stock app timers. +- Home Assistant time is supplied through `time.homeassistant` and `tuya.time_id`; confirm day/time and behavior after cold start or lost HA connectivity. This does not implement a weekly scheduler. +- Replacing the stock Wi-Fi firmware removes its original cloud/app client; do not expect the Eurom Smart app to keep working. Panel and remote behavior still need the documented regression tests. +- A lost Wi-Fi/API connection is **not an automatic heater-off mechanism** in this YAML. The controller may retain its last state. No claim is made about boot/reboot restoration, heating cut-off or factory safety protections after modification. ESPHome networking/API defaults can also reboot the ESP; test recovery under supervision. +- The room sensor near the panel may differ from the room's ambient temperature. The stock manual describes an external probe; behavior with that probe has not been verified with this project. + +## Photos + +Photographs supplied by the maintainer show the controls of the test unit; they do not establish its internal hardware revision. + +Control panel on the maintainer's Eurom DSP 400 WiFi + +Eurom remote with power, mode, ECO, window detection, bars and timer buttons + +## Project notes + +- [Datapoint evidence and unknowns](DATAPOINTS.md) +- [Hardware test checklist and software validation record](TESTING.md) +- [Backup, flashing, connector and compatibility TODO](TODO.md) +- [Changes made when preparing the public example](CHANGELOG.md) +- [Contribution instructions](../../CONTRIBUTING.md) and [AI instructions](../../AGENTS.md) + +## References and credits + +- [Eurom product page](https://eurom.nl/product/permanente-verwarming/infrarood-verwarming/mon-soleil-dsp-400-wifi/) and [manufacturer manual/downloads page](https://eurom.nl/nl/manuals/). The supplied manual's English section, pages 48-63, was consulted for original operating behavior; no copy of the PDF is included in this repository. +- [ESPHome Tuya MCU](https://esphome.io/components/tuya/), [Tuya climate](https://esphome.io/components/climate/tuya/) and [encrypted OTA](https://esphome.io/components/ota/esphome/). + +Developed and maintained by [Graham van der Wielen](https://github.com/grayum). Created with assistance from ChatGPT & Codex (OpenAI). Independent community project; not affiliated with Eurom. See the repository [MIT License](../../LICENSE). diff --git a/esphome/eurom-mon-soleil-dsp/TESTING.md b/esphome/eurom-mon-soleil-dsp/TESTING.md new file mode 100644 index 0000000..c47f287 --- /dev/null +++ b/esphome/eurom-mon-soleil-dsp/TESTING.md @@ -0,0 +1,75 @@ +# Testing and validation + +## Starting evidence + +The source YAML attributes DP1/2/3/4/101/102 observations to the maintainer's log/button testing on 2026-10-28. Detailed logs, the exact installed ESPHome version and a full test record were not supplied. The maintainer is still testing. These notes do not certify heater safety or other variants. + +## Public example software validation + +Run from the repository root: + +```bash +python3 -m venv .venv +. .venv/bin/activate +python3 -m pip install -r requirements-dev.txt +python3 scripts/validate-esphome.py --generate +``` + +The script copies the public configuration into a temporary directory and supplies generated dummy secrets. It never reads your local `secrets.yaml`, connects to a device or flashes firmware. The included GitHub workflow runs the same checks on pushes and PRs. Review the Actions result; no successful GitHub run is claimed before publication. + +The validation baseline is ESPHome 2026.10.1. Configuration validation and C++ generation are checked separately from a full toolchain build. See the dated record at the end of this file for the actual preparation results. + +## Supervised hardware checklist + +Use the heater in its normal manufacturer-approved position. Do not intentionally tip, cover, overheat, obstruct or fault it. Stop if physical behavior is unexpected. Network-loss checks require a person present who can operate the heater directly; software disconnects are not a heat cut-off. + +Record each result as pass, fail or not run, with actual observations. A checkbox is only completed after a real test. + +| Check | Expected observation / question | Status | +| --- | --- | --- | +| Identity | Article number, module/PCB revision, installed ESPHome version and config commit recorded | Not run for this public example | +| State after startup | Observe DP1/4/101/102, display and heat state before sending commands; identify retained state | Not run | +| HA power Off | Heater/display and HA agree; observe DP1 and DP101 | Not run | +| HA Heat in M and P | Capture writes to DP1/DP101 and verify physical response; confirm DP4 is unchanged | Not run | +| P mode setpoint | Above/below ambient: compare setpoint, sun indicator, HA action and actual normal heat cycling | Not run | +| Manual mode | Confirm manual element control and that a setpoint does not imply thermostatic regulation | Not run | +| Element select in P | Determine whether writes are ignored, override temporarily or alter regulation; record results | Not run | +| Panel / remote feedback | Power, MODE, +/− and bars changes reach HA; preserve control behavior | Not run | +| ECO transitions | Enable/disable ECO from different modes; check 16 °C, EC display, restored setpoint and mode | Not run | +| Time sync | Check day/time after cold start and after HA reconnect; do not assume sync succeeded | Not run | +| Existing timers | Identify retained schedules and interactions without assuming the ESPHome YAML removed them | Not run | +| API/Wi-Fi loss | Under direct supervision, observe heater state and ESP reboot/reconnect behavior | Not run | +| Normal power cycle | Record heat, setpoint, mode, ECO and schedule state after restart | Not run | +| Temperature / probe | Compare DP3/display and, if already fitted, external-probe behavior | Not run | +| Fault DP | Record naturally occurring/previously known fault values only; do not manufacture faults | Not run | +| Open-window button | Repeat normal button interaction and record any DP changes; do not simulate dangerous conditions | Not run | + +## Hardware report template + +```text +Date: +Model and article number: +Module / PCB revision (or unknown): +ESPHome version: +Home Assistant version: +Configuration commit: +Initial M/P, power, ECO and timer state: +Action / expected result: +Observed panel, HA and redacted DP changes: +Result (pass / fail / not run): +Remaining uncertainties: +``` + +## Preparation record - 2026-10-29 + +| Check | Result | +| --- | --- | +| ESPHome 2026.10.1 configuration validation with temporary dummy secrets | Passed | +| ESPHome 2026.10.1 C++ source generation (`compile --only-generate`) | Passed | +| Compare control configuration against supplied YAML | Board, UART, logger, API, OTA, time, Tuya, climate, selects, switches and sensors preserved | +| Publication review | Original literal fallback password and private address absent; helper removed; photos unchanged and no EXIF entries found; no manufacturer PDF included | +| Full firmware/toolchain compilation and binary/OTA size | Not run | +| Flashing or hardware tests of this public example | Not run; requires maintainer testing | +| GitHub Actions | Workflow supplied; not run on GitHub before publication | + +Time zone is normally inferred from the build environment when it is not set in YAML. Check the resulting local day/time on the heater; set `time.homeassistant.timezone` explicitly in your private configuration if needed. Time-source availability and timer behavior remain hardware test items. diff --git a/esphome/eurom-mon-soleil-dsp/TODO.md b/esphome/eurom-mon-soleil-dsp/TODO.md new file mode 100644 index 0000000..ab9c8aa --- /dev/null +++ b/esphome/eurom-mon-soleil-dsp/TODO.md @@ -0,0 +1,24 @@ +# TODO + +## Installation and recovery documentation + +- [ ] Confirm the maintainer's exact article number, Wi-Fi module, flash size and PCB revisions. +- [ ] Document a verified way to back up the original manufacturer flash/configuration before modification, including integrity checks and private storage. Distinguish a full flash image from readable settings; do not upload either. +- [ ] Verify restoration/recovery using the owner's own backup and document the limitations. +- [ ] Document replacing stock firmware with ESPHome for a specifically identified module/revision, with safe isolation, power and programming requirements reviewed by a qualified person. +- [ ] Document the **internal four-pin connector**: clearly oriented photo, connector numbering, measured supply and logic levels, ground, signal directions, ESP pin mapping, revision and isolation evidence. Do not guess from wire color or the GPIO settings. + +These installation items are intentionally placeholders. Contributors may submit evidence-backed PRs. This starter does not provide a wiring diagram or initial flashing commands. + +## Behavior and compatibility + +- [ ] Complete the supervised [test checklist](TESTING.md), with versions and observations. +- [ ] Verify climate Heat/Off writes to DP1/DP101 in both M and P modes, including transitions from ECO and idle. +- [ ] Decide whether the writable DP101 select should remain, be diagnostic by default or be replaced with read-only reporting, based on test evidence. +- [ ] Verify power-loss, ESP reboot, API loss, Wi-Fi loss and time recovery behavior; document whether heating and stored schedules persist. +- [ ] Determine stock local/app timer persistence and a verified way to inspect/clear schedules before migration. +- [ ] Investigate open-window detection and external probe behavior without inventing datapoints. +- [ ] Decode fault bits only when supported by reliable evidence; never induce hazardous faults. +- [ ] Record full firmware compilation and flash/OTA size on the actual 1 MB target. +- [ ] Add evidence-backed compatibility reports for 361919, 361933, 361902, 361926 and 361940, including hardware revisions. +- [ ] Consider an ESPHome device-directory submission after the hardware and behavior are documented. diff --git a/esphome/eurom-mon-soleil-dsp/eurom-400-wifi.yaml b/esphome/eurom-mon-soleil-dsp/eurom-400-wifi.yaml new file mode 100644 index 0000000..91e0543 --- /dev/null +++ b/esphome/eurom-mon-soleil-dsp/eurom-400-wifi.yaml @@ -0,0 +1,124 @@ +# Eurom Mon Soleil DSP 400 WiFi - ESPHome via Tuya MCU protocol +# Tuya product id: wv9d5ocs76u6maqj +# +# Maintainer-reported datapoints (logs + button tests, 2026-10-28). +# Experimental; see DATAPOINTS.md and TESTING.md for evidence limits. +# Datapoints: +# DP1 switch -> power on/off REPORTED +# DP2 int -> target temperature (0-37 °C; ECO sets 16) REPORTED +# DP3 int -> room temperature REPORTED +# DP4 enum -> MODE button: 0 = M (manual), 1 = P (program) REPORTED +# DP101 enum -> heating element: 0 = heating (sun), 3 = off REPORTED +# (bars button toggles it in M-mode; in P-mode the thermostat sets it) +# DP102 switch -> ECO mode (16 °C, display "EC") REPORTED +# DP12 bitmask -> fault code (0 = no fault) +# Open-window detection: no datapoint change observed in maintainer tests. + +esphome: + name: eurom-400-wifi + min_version: 2026.9.0 + friendly_name: Eurom 400 + +esp8266: + board: esp01_1m + +logger: + baud_rate: 0 # hardware UART0 is used for the heater MCU; logs arrive over WiFi + +ota: + - platform: esphome + encryption: # Inherits the API key; see README for older-firmware migration. + +wifi: + ssid: !secret wifi_ssid + password: !secret wifi_password + ap: + ssid: Eurom 400 WiFi Fallback Hotspot + password: "ThisIsNotMyPassword" + +captive_portal: + +api: + encryption: + key: !secret eurom_400_wifi__encryption_key + +uart: + rx_pin: GPIO13 + tx_pin: GPIO15 + baud_rate: 9600 + id: uart_bus + +time: + - platform: homeassistant + id: ha_time + +tuya: + time_id: ha_time + +# Climate Heat/Off does not select M/P mode. Use P for thermostat regulation. +# Selecting Heat can also WRITE DP101=0; see README.md and TESTING.md. +# Thermostat card: on/off, setpoint, room temperature and heating/idle status +climate: + - platform: tuya + name: "Eurom heater" + switch_datapoint: 1 + target_temperature_datapoint: 2 + current_temperature_datapoint: 3 + supports_heat: true + active_state: + datapoint: 101 + heating_value: 0 + visual: + min_temperature: 0 + max_temperature: 37 + temperature_step: 1 + +select: + # MODE button: M = manual (heating on/off with bars button), P = thermostat / week timer + - platform: tuya + name: "Eurom mode" + enum_datapoint: 4 + options: + 0: "Manual (M)" + 1: "Thermostat (P)" + + # Heating element (sun icon). Observed manual control in M-mode. + # This select is writable in HA even in P-mode; effects require testing. + - platform: tuya + name: "Eurom heating element" + enum_datapoint: 101 + options: + 0: "On" + 3: "Off" + +switch: + - platform: tuya + name: "Eurom ECO (16 °C)" + switch_datapoint: 102 + icon: "mdi:leaf" + +sensor: + - platform: tuya + name: "Eurom room temperature" + sensor_datapoint: 3 + unit_of_measurement: "°C" + device_class: temperature + state_class: measurement + accuracy_decimals: 0 + + - platform: tuya + name: "Eurom fault code" + sensor_datapoint: 12 + accuracy_decimals: 0 + entity_category: diagnostic + +text_sensor: + - platform: wifi_info + ip_address: + name: ESP IP Address + ssid: + name: ESP Connected SSID + bssid: + name: ESP Connected BSSID + mac_address: + name: ESP Mac Wifi Address \ No newline at end of file diff --git a/esphome/eurom-mon-soleil-dsp/images/eurom-400-wifi_panel.jpg b/esphome/eurom-mon-soleil-dsp/images/eurom-400-wifi_panel.jpg new file mode 100644 index 0000000..0e3beea Binary files /dev/null and b/esphome/eurom-mon-soleil-dsp/images/eurom-400-wifi_panel.jpg differ diff --git a/esphome/eurom-mon-soleil-dsp/images/eurom-400-wifi_remote.jpg b/esphome/eurom-mon-soleil-dsp/images/eurom-400-wifi_remote.jpg new file mode 100644 index 0000000..1b1674f Binary files /dev/null and b/esphome/eurom-mon-soleil-dsp/images/eurom-400-wifi_remote.jpg differ diff --git a/esphome/eurom-mon-soleil-dsp/secrets.example.yaml b/esphome/eurom-mon-soleil-dsp/secrets.example.yaml new file mode 100644 index 0000000..e9dd845 --- /dev/null +++ b/esphome/eurom-mon-soleil-dsp/secrets.example.yaml @@ -0,0 +1,7 @@ +# EXAMPLES ONLY. Merge into your PRIVATE secrets.yaml; never commit real values. +wifi_ssid: "REPLACE_WITH_YOUR_WIFI_SSID" +wifi_password: "REPLACE_WITH_YOUR_WIFI_PASSWORD" +eurom_400_wifi_fallback_password: "REPLACE_WITH_UNIQUE_AP_PASSWORD" +# New device only: generate with openssl rand -base64 32. +# Existing device: preserve its installed key instead. +eurom_400_wifi__encryption_key: "REPLACE_WITH_YOUR_EXISTING_OR_NEW_DEVICE_KEY" diff --git a/requirements-dev.txt b/requirements-dev.txt new file mode 100644 index 0000000..c2c422a --- /dev/null +++ b/requirements-dev.txt @@ -0,0 +1,2 @@ +# Validation baseline; upgrade deliberately and record the results. +esphome==2026.10.1 diff --git a/scripts/validate-esphome.py b/scripts/validate-esphome.py new file mode 100644 index 0000000..f324aed --- /dev/null +++ b/scripts/validate-esphome.py @@ -0,0 +1,42 @@ +#!/usr/bin/env python3 +"""Validate the public example with throwaway credentials; never touch hardware.""" + +import argparse +import base64 +from pathlib import Path +import secrets +import shutil +import subprocess +import sys +import tempfile + +import yaml + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--generate', action='store_true', help='also generate C++ (not a full firmware build)') + args = parser.parse_args() + root = Path(__file__).resolve().parents[1] + project = root / 'esphome' / 'eurom-mon-soleil-dsp' + with tempfile.TemporaryDirectory(prefix='eurom-esphome-') as directory: + config = Path(directory) / 'eurom-400-wifi.yaml' + shutil.copyfile(project / config.name, config) + dummy_secrets = { + 'wifi_ssid': 'CI-NOT-A-REAL-NETWORK', + 'wifi_password': secrets.token_urlsafe(24), + 'eurom_400_wifi_fallback_password': secrets.token_urlsafe(24), + 'eurom_400_wifi__encryption_key': base64.b64encode(secrets.token_bytes(32)).decode('ascii'), + } + (Path(directory) / 'secrets.yaml').write_text(yaml.safe_dump(dummy_secrets), encoding='utf-8') + # Config output contains only throwaway values, never local device secrets. + commands = [['config', str(config)]] + if args.generate: + commands.append(['compile', str(config), '--only-generate']) + for command in commands: + subprocess.run([sys.executable, '-m', 'esphome', *command], check=True) + print('Validation complete. No device access or firmware flashing performed.') + + +if __name__ == '__main__': + main()