localthings README

项目的 README,来自 github.com/mbillow/localthings。合并为一个 markdown 文件:README.md。

LocalThings Logo LocalThings Logo

GitHub Repo stars GitHub watchers

GitHub Release hacs validation hassfest tests

LocalThings

Control your Samsung appliances from Home Assistant over your home network, with no cloud account.

LocalThings connects Home Assistant to Samsung washers, dryers, refrigerators, air conditioners, ovens and other appliances that work with the SmartThings app. It talks to each appliance on your local network.

What it supports

Appliance Appliance
Air conditioner, including multi-unit systems Microwave
Air dresser Oven
Air monitor Range and range hood
Air purifier Refrigerator, kimchi refrigerator, wine cellar
Cooktop, gas, radiant electric and induction; some models read-only Robot vacuum, early support
Dehumidifier Soundbar, media player, settings and status
Dishwasher Vacuum clean station
Dryer Washer and washer-dryer
EHS heat pump Water purifier

Samsung TV support provides a TV media player (volume, mute, input, sound mode, channel and now-showing, casting), Wake-on-LAN turn-on, a remote, on-screen notifications, an app launcher and a picture-mode setting. An existing OCF credential is required; most owners cannot acquire one yet.

What you see depends on what each appliance reports. Typical controls and sensors include power, program or mode selection, start, pause and stop, temperatures and setpoints, time remaining and finish time, door and child-lock state, energy use, filter status and alarms.

Most Samsung appliances from about 2022 onward work, and so do some earlier washers, air conditioners and wall ovens that use an older local interface. See Older appliances on TCP 8888. Setup detects which interface an appliance has, and tells you if it finds none.

If an appliance sets up but LocalThings doesn't recognize it, or a control is missing, Home Assistant shows a notice asking for a diagnostics download. That download is usually all the maintainers need to add support. See Reporting a capability gap.

Built on open standards

LocalThings uses the standards the appliances implement:


Install

  1. In HACS, go to Integrations, search for LocalThings, and select Download. LocalThings is in HACS's default list, so you don't need to add a custom repository.

    Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.

    Without HACS, copy custom_components/localthings/ into the custom_components/ folder of your Home Assistant config.

  2. Restart Home Assistant.

Add an appliance

  1. Go to Settings > Devices & Services > Add Integration > LocalThings.
  2. Enter the appliance's IP address. For most appliances, that's the whole setup.
  3. LocalThings connects, reads the appliance's type and model, and adds one Home Assistant device for it.

When you add your first appliance, LocalThings contacts Samsung's servers once to read a public identifier. It uses no account or login. Later appliances reuse that identifier, so adding them needs only an IP address and no internet access.

A few appliances need one more step:

You can rename devices. LocalThings identifies each appliance by its OCF device ID, not by its name or serial number. Some models ship the same serial number on every unit.

Per-device settings

Each appliance has a Configure option in Settings > Devices & Services, with these settings under Device settings:

An appliance that exposes more than one device, such as each indoor unit of a multi-split system or each cavity of a dual oven, also gets Subdevices in the same menu. Some appliances report an extra slot that isn't real hardware, which shows up as a duplicate or empty device. Untick it there: LocalThings removes that device and stops reading it. Tick it again to bring it back.


Known device behavior

Brief disconnects are normal. Samsung appliances drop their connection for a moment now and then. LocalThings reconnects, and entities keep their last value meanwhile. If reconnects happen several times a minute, check the appliance's Wi-Fi signal. Also check that nothing else on your network holds a connection to it, because an appliance accepts one connection at a time.

Keep appliances registered in SmartThings. If you remove an appliance from SmartThings, it resets its network settings the next time it reaches Samsung's servers. It then drops off Wi-Fi until you set it up in the app again. This happens even if you block its internet access most of the time.

Some washers and dryers stop counting energy without SmartThings. On the DA_WM_TP2_20_COMMON board (for example the WW80T654ALX and DV80T6220LX), the energy total stops increasing while the appliance can't reach SmartThings, and resumes once it reconnects. LocalThings can only show what the appliance records, so if your energy sensor stays at one value while cycles run, check that the appliance can reach Samsung's servers.

Restarting while an appliance is powered off

If Home Assistant restarts while an appliance is off, LocalThings loads the appliance's device and entities from the last successful setup. They show unavailable until the appliance answers, then recover without any action from you. This works for any appliance LocalThings has reached at least once. A new appliance must be reachable to set it up.

When an appliance's IP address changes

About half of Samsung's appliances report their Wi-Fi MAC address. For those, Home Assistant's DHCP discovery spots the new address and LocalThings updates the entry. For other appliances, select Reconfigure on the entry and enter the new address. LocalThings checks that the appliance at that address is the right one, and keeps its entities, history and automations. Deleting and re-adding the appliance would lose all three.

Older appliances on TCP 8888

Some appliances from about 2018 to 2022 have a different local interface, HTTPS on TCP port 8888. So far this covers WW6500 and WW9000HE washers, TP6X air conditioners, a Samsung FlexDry dryer, an NV51K777OS Flex Duo wall oven, an NQ70M6650DS microwave/oven combo, NZ36K7570R and NZ30K7570RS cooktops, and an RF28K9380SR refrigerator. Setup detects the interface from the IP address and then asks for a device token. Leave the field empty and the appliance issues a token, sending it back to Home Assistant on port 8889. For that to work, switch Remote Control on at the appliance with the door closed, and make sure the appliance can reach Home Assistant on port 8889. If the appliance later rejects its token, Home Assistant asks for a new one.

On the RF28K9380SR refrigerator, when setup asks for the token, hold Lighting / Control Lock for about 5 seconds, until "on" shows in the freezer temperature display. It refuses the automatic certificate, so setup then asks for an AC14K_M CA certificate and key, and it needs both to finish.

For the tested NZ36K7570R and NZ30K7570RS cooktops, NV51K777OS oven and NQ70M6650DS combo, if Smart Connect is already on, no token will be returned. Turn it off, request a token in LocalThings, then turn it on.

The WW9000HE washer, and a sibling washer reporting LCD_Washer_14K, won't return a token while they can reach Samsung's servers. Block the washer's internet access at your router while keeping it on your local network, then turn Smart Control off and on at the washer and request the token.

On these appliances, a chosen cycle, temperature, rinse count or spin speed takes effect only when the cycle starts. The selects hold your choice, and the Start button sends it. If you turn the dial on the appliance, the dial's setting replaces the held choice.

This interface speaks only TLS 1.0 and presents a certificate LocalThings can't verify, so LocalThings accepts both on this one connection. No other part of LocalThings relaxes TLS.

Starting an oven, range or microwave

An oven only starts when the mode, temperature and cook time arrive together. While it's idle, the mode select, setpoint and cook time hold your choice, starting from the mode's own defaults, and the Start cooking button sends them. The localthings.start_cooking action does the same in one call, with any value you leave out taken from the mode's defaults. Once a cook is running, changes to the setpoint and cook time go straight to the oven.

Each appliance reports which of its modes a remote may start, and the temperature and time limits for each. LocalThings follows that list, and only offers the modes the oven can run right now. The button appears only on an appliance that reports at least one mode it can start, and a start outside those limits is refused with the allowed range. On a range with two ovens, each oven has its own Start cooking button and starts separately. Some modes can't be started remotely by design: on every microwave seen so far, none of the microwave-power modes can be. Remote Control has to be on at the appliance, and it switches off after a power cut.

Multi-unit air conditioners

Some installations run several indoor units from one outdoor unit, all at one IP address. LocalThings finds the extra units after its first connection. Each unit gets its own Home Assistant device and climate card, linked to the main unit. LocalThings skips the unused slots some systems report. If a unit you expect is missing, attach a diagnostics download to an issue.


Reporting a capability gap

If LocalThings doesn't recognize an appliance, or the appliance reports something LocalThings doesn't handle yet, a notice appears under Settings > System > Repairs. It points you to Download diagnostics on the device. LocalThings removes personal and network details from that download before you save it. It removes the account email, tokens, device IDs, MAC addresses, serial numbers, the Wi-Fi network name and password, the device's name, the name of a paired phone and the device's on/off history. You can attach the file to a device-support issue, and that is the fastest way to get an appliance supported.

A diagnostics download can't show whether a command sticks or what order commands need. The localthings.read_resource and localthings.write_resource actions answer those questions by reading and writing an appliance's resources without going through its entities. See Reading and writing resources directly.

Contributing

We welcome patches, especially:

Please don't include real device UUIDs, MAC addresses, serial numbers, IP addresses or private keys in a pull request. CONTRIBUTING.md covers the dev environment, the checks to run, the repo layout, and the rules for comments and commits.

localthings (mbillow/localthings)

正在搜索数据库…

这是什么?这是一个 Home Assistant 集成,可以通过家庭网络直接控制兼容 Samsung SmartThings 的家电,例如洗衣机、烘干机、冰箱、空调和烤箱。无需云端账户。
它是独立应用,还是 Home Assistant 的插件?它是 Home Assistant 的自定义组件(插件)。你可以通过 HACS 安装,也可以将文件夹复制到 Home Assistant 配置目录下的 custom_components 文件夹中。
怎样让它运行起来?在 HACS 中下载 LocalThings(它在默认列表中,因此无需添加自定义仓库),然后重启 Home Assistant。接着进入 设置 > 设备与服务 > 添加集成 > LocalThings,并输入家电的 IP 地址。
我需要三星账户或互联网连接吗?不需要账户或登录。首次设置时会联系三星服务器一次,以读取一个公开标识符。之后添加更多家电只需要 IP 地址,并且无需互联网即可工作。
它能支持所有三星家电吗?大多数 2022 年左右及之后的三星家电都可以使用,另外一些较旧的洗衣机、空调和烤箱也可以通过旧的本地接口(TCP 8888)使用。部分家电会拒绝自动证书,需要预共享密钥,而 LocalThings 无法为你获取该密钥。无法识别的型号会提示下载诊断信息。
没有互联网也能用吗?可以。设置完成后,它不会再联系三星服务器,而是直接在你的本地网络中与每台家电通信,因此无需互联网即可工作。
我的数据会离开家吗?不会。LocalThings 不会向三星发送任何数据。家电本身仍会保持与三星的连接,LocalThings 不会改变这一点。
它能支持多联式空调吗?可以。在首次连接后,会自动发现同一台室外机和 IP 地址下的其他室内机。每台室内机都会获得各自的 Home Assistant 设备和空调卡片,并与主机关联。
家电的 IP 地址变了怎么办?约一半的家电会上报其 Wi-Fi MAC 地址,因此 DHCP 发现功能会自动更新配置条目。其余家电请使用“重新配置”并输入新地址,这样实体、历史记录和自动化都会保留。
家电关机时重启 Home Assistant,它还能继续工作吗?可以。它会根据上次成功设置时的信息恢复设备和实体。在家电再次响应之前,这些实体会显示为不可用,之后会自动恢复。
作者
mbillow
大小
6.3 MB
星标
1.4K
时长
4个月
提交 · 90 天