⚠️ Stability NoteThis 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)
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.
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.
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
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.4Each 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: falseThe 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.
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.
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.
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.
| 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 |
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.
This integration provides the following services for advanced control and monitoring:
Read an attribute value from your Samsung EHS device.
Service: samsungehs.read_attribute
Fields:
device_id(required): The Samsung EHS device to read fromattribute(required): The attribute ID in format0xXXXX(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 a value to an attribute on your Samsung EHS device.
Service: samsungehs.write_attribute
Fields:
device_id(required): The Samsung EHS device to write toattribute(required): The attribute ID in format0xXXXX(e.g.,0x0001)value(required): The value to write
Example:
service: samsungehs.write_attribute
data:
device_id: abc123def456
attribute: "0x0001"
value: 42Attribute IDs: See the pysamsungnasa message factory documentation for available attribute IDs and their expected value formats.
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.
To establish communication, you will need:
-
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
-
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.
For an ESPHome TCP bridge, use ESPHome with the esphome-stream-server component:
-
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
-
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
-
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
-
Note the device's IP address and stream server port - For example, enter
socket://192.168.1.50:8000manually 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.
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:
- Turn off the heatpump at the main power switch before connecting any cables
- Verify the unit is de-energized using a multimeter if possible
- Use insulated terminals when connecting to F1/F2 to prevent accidental contact
- Check your specific unit's manual for exact terminal locations (they may vary by model)
- Power on the unit only after all connections are verified and the bridge device is powered on
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
- Add this repository to HACS as a custom repository
- Search for "Samsung EHS" in HACS
- Click Install
- Restart Home Assistant
- Download
samsungehs.zipfrom the desired GitHub release and extract it into your Home Assistantcustom_components/samsungehsdirectory - Restart Home Assistant
- Go to Settings → Devices & Services → Create Integration
- Search for "Samsung EHS" and follow the configuration flow
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.
- Go to Settings → Devices & Services → Add Integration.
- Search for "Samsung EHS".
- In Port, select your local serial adapter or an available serial proxy.
- 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.
- 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).
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. |
A Waveshare adapter can connect directly to the integration over TCP; no ESP32 or virtual COM port is required.
- 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.
- Set its serial parameters to 9600 baud, 8E1.
- 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.
- Add Samsung EHS, choose Enter manually in the Port selector, and enter
socket://IP_ADDRESS:PORT, for examplesocket://192.168.1.60:8899.
See issue #18 for the original setup question.
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.
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.
The integration uses pysamsungnasa for the Samsung NASА protocol and serialx for the underlying serial transport. It:
- Opens the selected local serial port, serial proxy, or manually configured network serial connection
- Continuously polls the device for status updates (every 15 seconds by default)
- Translates device-specific protocols into Home Assistant entities
- Provides climate control, water heater management, and sensor monitoring capabilities
All communication is local and does not require internet connectivity.
- 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.
- 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
Some entities may not appear if your device firmware doesn't support them. This is normal behavior.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines on how to contribute to this project.
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/developThis project is licensed under the MIT License. See the LICENSE file for details.
For issues, feature requests, or questions, please use the GitHub issue tracker.
- pysamsungnasa - Python library for Samsung NASА protocol
- Home Assistant - Open-source home automation platform