Skip to content

About

No description, website, or topics provided.

Resources

Contributing

Stars

10 stars

Watchers

0 watching

Forks

Latest commit

 

History

84 Commits

Folders and files

Repository files navigation

Samsung EHS Home Assistant Integration

⚠️ Stability Note

This integration is stable and ready for use. However, it may not cover all Samsung EHS device models and configurations. Some features or device compatibility may vary depending on your specific setup.

Technology Readiness Level: TRL 7 (System prototype demonstration in operational environment)

Overview

The Samsung EHS integration brings control and monitoring of Samsung Environmental Heat System (EHS) devices to Home Assistant. This integration communicates with Samsung heat pump and heat recovery ventilation systems using the NASА protocol over a local serial connection or a network serial bridge.

Why does this exist?

I wanted a local-only solution without relying on Samsung's commercial modbus adapter or their cloud-based WiFi kit (which requires internet connectivity for monitoring and control).

While there are excellent existing projects in this space that have paved the way, I created this integration to address my specific requirements and use case:

  • Samsung HVAC AC component for ESPHome - This project has done fantastic work and much of the protocol understanding comes from their efforts. For my setup, I needed more flexibility in discovering and monitoring custom registers, and wanted to avoid dedicating the UART connection exclusively to one component. Over extended periods, I also observed some challenges with packet processing in my environment.

  • Samsung EHS -> MQTT - Another solid project that works well for many users. I wanted a solution that integrated more tightly with Home Assistant's native entities and didn't require running a separate add-on or dedicated device. I also needed support for asynchronous communication patterns to address the message processing problems.

This integration takes a different architectural approach that suited my needs. All of these solutions have contributed valuable knowledge to the community.

Features

This integration provides support for the following Samsung EHS platforms:

  • Climate - Monitor and control the heating/cooling mode, target temperature, and HVAC operation status
  • Water Heater - Manage the domestic hot water (DHW) system with multiple operation modes (Eco, Heat Pump, Electric, Performance)
  • Sensor - Track various system parameters including temperatures, energy consumption, and operational status
  • Binary Sensor - Monitor connectivity and device availability
  • Switch - Control operational features like Quiet Mode and DHW Disinfection
  • Number - Adjust configuration parameters like DHW disinfection schedule and compressor settings
  • Select - Choose from predefined options like DHW disinfection day of week and pump modes
  • Diagnostics - Download connection and coordinator status to help troubleshoot the integration; connection details and device addresses are redacted

External room temperature

Use samsungehs.set_external_room_temperature to supply an external room sensor reading for zone 1 or zone 2. Select the Samsung EHS integration connection whose bus should receive the broadcast. Temperatures are always in degrees Celsius.

action: samsungehs.set_external_room_temperature
data:
  config_entry_id: YOUR_CONFIG_ENTRY_ID
  zone: 1
  enabled: true
  temperature: 21.4

Each indoor unit exposes a "Zone 1 external room sensor enabled" binary sensor and a "Zone 1 external room temperature" sensor, with equivalent entities for zone 2. These read reported attributes rather than assuming that the broadcast was accepted. The temperature sensor is unavailable when the override is disabled, the enable flag is unknown, the reading is missing, or the device is disconnected. The enabled binary sensor remains available and reports off when disabled.

Each call sends one notification. An automation must repeat the call periodically, including when the temperature has not changed. The upstream example uses a 30-second interval. Only send valid, fresh readings from your external sensor; never substitute zero for an unavailable reading. Convert readings from Fahrenheit to Celsius before calling this action.

To disable the external sensor, use the same action with enabled: false. No temperature is required. Any supplied temperature is ignored when disabled.

action: samsungehs.set_external_room_temperature
data:
  config_entry_id: YOUR_CONFIG_ENTRY_ID
  zone: 1
  enabled: false

The action broadcasts notifications as wired controller 510000 to B0FF20 on the selected connection. The broadcast can affect multiple indoor units on that bus. No climate entity or discovered device is required. A completed call confirms only that the send completed; notifications have no device acknowledgement. Verify operation and sensor-source restoration on your hardware. Automatic fallback when updates stop has not been established.

Water Heater Operation Modes

The Samsung EHS water heater (DHW) system supports the following operation modes:

Home Assistant Mode Samsung EHS Mode Description
Off Off Water heater is disabled
Eco ECO Energy-efficient mode, minimal energy consumption
Heat Pump STANDARD Standard heat pump operation for water heating
Performance POWER High-performance mode for faster heating
Electric FORCE Electric heating element mode for maximum power

You can switch between these modes in Home Assistant's climate card or through automations. The integration will send the corresponding command to your Samsung EHS device.

Heating/Cooling Modes

The Samsung EHS climate system supports the following HVAC modes:

Home Assistant Mode Samsung EHS Mode Description
Off Off HVAC system is disabled
Auto AUTO Uses water law to achieve the set room temperature
Heat HEAT Heating mode only, if no external thermostats are used, this will control the water flow target temperature
Cool COOL Cooling mode only, if no external thermostats are used, this will control the water flow target temperature
Fan Only FAN Fan operation without heating or cooling

You can change the HVAC mode and set target temperatures through Home Assistant's climate card or automations. The integration will send the corresponding command to your Samsung EHS device.

HVAC Actions

In addition to HVAC modes, the integration reports the current HVAC action - what the system is actually doing at any given moment. This is different from the HVAC mode (what you've set it to do) and is useful for automations and status monitoring.

HVAC Action States

Action Description Conditions
Off System is powered off Power switch is off
Heating System is actively heating Mode is Heat AND outdoor unit running normally
Cooling System is actively cooling Mode is Cool AND outdoor unit running normally
Idle System is on but not heating/cooling Power is on, but no active heating/cooling demand
Preheating System is in safety/preheat mode Outdoor unit in safety operation (OP_SAFETY)
Defrosting System is defrosting Defrost cycle is active on outdoor or indoor unit

How HVAC Actions Work

The integration monitors several parameters to determine the current action:

  • Power State: Whether the system is powered on or off
  • HVAC Mode: The currently selected mode (Heat, Cool, Fan, Auto)
  • Outdoor Unit Status: Monitors if the outdoor heat pump unit is running normally (OP_NORMAL), in safety mode (OP_SAFETY), or stopped
  • Defrost Status: Detects when the system is in defrost cycle to prevent ice buildup

Example Scenarios:

  • Heating without demand: HVAC mode is Heat, system is on, but room temperature is at target → Action shows "Idle"
  • Heating with defrost: System needs to heat but defrost cycle is active → Action shows "Defrosting"
  • System shutdown: Power is off → Action shows "Off" regardless of mode setting
  • Cold startup: System starting up and warming before normal operation → Action shows "Preheating"

This information is exposed as the hvac_action attribute in Home Assistant and can be used in automations to trigger actions based on what the system is actually doing, not just what mode it's in.

Services

This integration provides the following services for advanced control and monitoring:

Read Attribute

Read an attribute value from your Samsung EHS device.

Service: samsungehs.read_attribute

Fields:

  • device_id (required): The Samsung EHS device to read from
  • attribute (required): The attribute ID in format 0xXXXX (e.g., 0x0001)

Example:

service: samsungehs.read_attribute
data:
   device_id: abc123def456
   attribute: "0x0001"

Attribute IDs: See the pysamsungnasa message factory documentation for available attribute IDs.

Write Attribute

Write a value to an attribute on your Samsung EHS device.

Service: samsungehs.write_attribute

Fields:

  • device_id (required): The Samsung EHS device to write to
  • attribute (required): The attribute ID in format 0xXXXX (e.g., 0x0001)
  • value (required): The value to write

Example:

service: samsungehs.write_attribute
data:
   device_id: abc123def456
   attribute: "0x0001"
   value: 42

Attribute IDs: See the pysamsungnasa message factory documentation for available attribute IDs and their expected value formats.

Hardware Configuration

Samsung EHS devices communicate via the NASА protocol over RS485. You can connect a USB-to-RS485 adapter directly to the Home Assistant host, use a serial proxy available in Home Assistant, or use a network RS485 adapter such as a Waveshare RS485-to-Ethernet device or an ESPHome UART bridge. An ESP32 is only needed if you choose the ESPHome bridge option.

Required Hardware

To establish communication, you will need:

  1. A device with RS485 interface - Examples:

    • M5Stack with RS485 Base
    • Any ESP32-based device with RS485 module
    • Raspberry Pi with RS485 HAT
    • USB-to-RS485 adapter connected to the Home Assistant host
    • Waveshare RS485-to-Ethernet adapter
  2. Connection to Home Assistant - A local adapter must be accessible to the Home Assistant runtime. A network adapter or proxy must be reachable from Home Assistant on its configured address and port.

Setting Up with ESPHome

For an ESPHome TCP bridge, use ESPHome with the esphome-stream-server component:

  1. Flash ESPHome to your bridge device (e.g., M5Stack):

    • Install ESPHome
    • Create a new device configuration with RS485 support
    • Use the esphome-stream-server component for TCP bridging
  2. Example ESPHome Configuration:

    esphome:
       name: samsung-ehs-bridge
    
    uart:
       id: uart_rs485
       tx_pin: GPIO17
       rx_pin: GPIO16
       baud_rate: 9600
       data_bits: 8
       parity: EVEN
       stop_bits: 1
    
    external_components:
       - source: github://oxan/esphome-stream-server
    
    stream_server:
       uart_id: uart_rs485
       port: 8000
  3. Connect the RS485 module:

    • Wire the RS485 module to your ESP device according to your specific hardware pinout
    • Connect the RS485 A/B lines to your Samsung EHS device
    • Ensure proper termination resistors if needed for your installation
  4. Note the device's IP address and stream server port - For example, enter socket://192.168.1.50:8000 manually in the integration's serial port selector. Adjust the GPIO pins for your hardware and include the board/platform, network, and other settings required by your ESPHome device.

Connecting to Samsung EHS Device

⚠️ SAFETY WARNING: The Samsung EHS heatpump contains high voltages. Ensure the unit is electrically isolated from power supply before making any electrical connections.

Connection Points:

The RS485 communication lines connect to the F1 and F2 terminals on your Samsung EHS unit. These can be found on either:

  • Indoor Unit: Control board or communication module
  • Outdoor Unit: Main control board

Wiring:

  • RS485 A line → F1 terminal
  • RS485 B line → F2 terminal
  • Ensure a common ground connection between the bridge and the heatpump unit

Power Supply:

The M5Stack ESP32 device can be powered independently via USB, or you can use the 12V power terminals on the Samsung EHS unit when using the M5Stack RS485 Base:

  • 12V + terminal → M5Stack RS485 Base 12V input
  • 12V - (ground) → Common ground with the heatpump

This option eliminates the need for separate external power and keeps all connections in one location.

Important Safety Steps:

  1. Turn off the heatpump at the main power switch before connecting any cables
  2. Verify the unit is de-energized using a multimeter if possible
  3. Use insulated terminals when connecting to F1/F2 to prevent accidental contact
  4. Check your specific unit's manual for exact terminal locations (they may vary by model)
  5. Power on the unit only after all connections are verified and the bridge device is powered on

Network Connection

Once your UART bridge is set up:

  • Your Samsung EHS device communicates via RS485 to the bridge hardware
  • The bridge converts this to TCP/IP on its configured port (8000 in the ESPHome example)
  • Home Assistant connects to the bridge via your local network

Installation

Via Home Assistant Community Store (HACS)

  1. Add this repository to HACS as a custom repository
  2. Search for "Samsung EHS" in HACS
  3. Click Install
  4. Restart Home Assistant

Manual Installation

  1. Download samsungehs.zip from the desired GitHub release and extract it into your Home Assistant custom_components/samsungehs directory
  2. Restart Home Assistant
  3. Go to Settings → Devices & Services → Create Integration
  4. Search for "Samsung EHS" and follow the configuration flow

Configuration

Via UI

The integration uses Home Assistant's SerialPortSelector for the Port field. It supports local serial ports and serial proxies exposed by Home Assistant. You can override the selection with a manually entered device path or connection URL. There are no separate Host and Port fields.

  1. Go to Settings → Devices & Services → Add Integration.
  2. Search for "Samsung EHS".
  3. In Port, select your local serial adapter or an available serial proxy.
  4. To override the selection or use a network adapter that is not listed, open the selector, choose Enter manually, and enter the full device path or URL from the examples below.
  5. Submit the form. The integration will discover connected Samsung devices and set up their entities.

The integration uses pysamsungnasa for the Samsung protocol and the serialx library under the hood for serial connections. Manual values must be device paths or URLs supported by that library; a bare IP address is not sufficient for a TCP adapter. Configure an RS485 bridge's UART for 9600 baud, 8 data bits, even parity, 1 stop bit (8E1).

Common connection examples

These are values or selections for the UI's Port field, not configuration.yaml entries. Replace the example paths, addresses, and ports with your own.

Setup Port selection or manual value Required setup
Local USB-to-RS485 adapter Select the adapter, or enter /dev/serial/by-id/usb-YOUR_ADAPTER_ID Make the device accessible to Home Assistant; use its actual persistent path where possible.
Local serial device without a persistent path /dev/ttyUSB0 Ensure the path exists inside the Home Assistant runtime; device numbering may change after a restart.
Home Assistant serial proxy Select the proxy's serial port from the selector Set up the proxy in Home Assistant first so its port is available.
Waveshare RS485-to-Ethernet adapter socket://192.168.1.60:8899 Configure the adapter as a TCP server providing a transparent serial stream; use its actual listening port.
ESPHome stream server from the example above socket://192.168.1.50:8000 Run the UART stream server on port 8000.
TCP bridge using a hostname socket://samsung-ehs-bridge.local:8000 Ensure Home Assistant can resolve that hostname and reach the port.

Waveshare RS485-to-Ethernet setup

A Waveshare adapter can connect directly to the integration over TCP; no ESP32 or virtual COM port is required.

  1. Set the adapter to TCP server mode with transparent serial forwarding and note its IP address and listening port. Use raw TCP rather than Modbus TCP mode.
  2. Set its serial parameters to 9600 baud, 8E1.
  3. Close other clients connected to the adapter, including virtual COM software, S-NET Pro, or NASAMonitor. An existing connection can block Home Assistant from connecting.
  4. Add Samsung EHS, choose Enter manually in the Port selector, and enter socket://IP_ADDRESS:PORT, for example socket://192.168.1.60:8899.

See issue #18 for the original setup question.

Changing an existing connection

Open the Samsung EHS integration entry's menu in Settings → Devices & Services and choose Reconfigure to select another port, proxy, or manual URL. Existing entries from the older Host/Port configuration are migrated automatically to a socket://HOST:PORT value.

Supported Devices

This integration supports Samsung EHS systems that communicate via the NASА protocol, including:

  • Samsung heat pumps (ASHP, WSHP models)
  • Samsung air-to-water heat pumps
  • Samsung heat recovery ventilation systems with integrated heat pump functionality
  • This integration may support a variety of Samsung AC units, however as I don't have any packet dumps from these, I cannot implmenent the required functions.

Note: Compatibility depends on your specific device model and firmware version. Please refer to the issue tracker if you encounter compatibility issues.

How It Works

The integration uses pysamsungnasa for the Samsung NASА protocol and serialx for the underlying serial transport. It:

  1. Opens the selected local serial port, serial proxy, or manually configured network serial connection
  2. Continuously polls the device for status updates (every 15 seconds by default)
  3. Translates device-specific protocols into Home Assistant entities
  4. Provides climate control, water heater management, and sensor monitoring capabilities

All communication is local and does not require internet connectivity.

Troubleshooting

Device Not Found

  • For a local adapter, check that the selected device path exists and Home Assistant has permission to access it. For Container or VM installations, pass the serial device through to the Home Assistant runtime.
  • For a serial proxy, check that it is online and its serial port is available in Home Assistant.
  • For a TCP adapter, use Enter manually with socket://HOST:PORT, verify the address and listening port, and check that Home Assistant can reach it through any firewall.
  • Check that the bridge is configured for 9600 baud, 8E1 and connected to the correct RS485 terminals.

Connection Issues

  • Restart the integration from Settings → Devices & Services
  • Check the Home Assistant logs for error messages
  • Ensure your device is powered on and responsive
  • Close competing connections to the serial adapter, including virtual COM clients and diagnostic software
  • For a Waveshare adapter, confirm TCP server / transparent serial mode rather than Modbus TCP mode

Missing Entities

Some entities may not appear if your device firmware doesn't support them. This is normal behavior.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines on how to contribute to this project.

Development

Releases are managed by Release Please. See the release process for commit conventions and repository setup.

This project includes a development environment that can be set up using Docker and Visual Studio Code:

# Lint the code
./scripts/lint

# Set up development environment
./scripts/setup

# Start development environment
./scripts/develop

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support

For issues, feature requests, or questions, please use the GitHub issue tracker.

Related Projects

About

No description, website, or topics provided.

Resources

Contributing

Stars

10 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages