IoT Device Onboarding to Home Assistant

Pattern for adding new WiFi IoT devices (smart plugs, switches, sensors) to the local network and Home Assistant.

Phase 1: Get Device on WiFi

Stock Firmware (eWeLink / Tuya)

Device broadcasts a setup AP when first powered or reset (e.g., ITEAD-XXXX or SmartLife-XXXX)
Connect phone to that AP, use the eWeLink or Smart Life app to configure WiFi
After WiFi config, the AP disappears and device joins the home network

Tasmota / ESPHome (already flashed)

Device broadcasts its own AP (e.g., tasmota-XXXX-XXXX or esphome-XXXX)
Connect phone to the AP, browse to http://192.168.4.1 to configure WiFi
After save, device reboots onto the home network

Phase 2: Find the IP Address

Devices often get DHCP-assigned IPs that aren't immediately obvious.

Method A — Router DHCP table: Browse to router admin (ASUS: http://192.168.50.1), check Client List for the new device.

Method B — App device info: In eWeLink app: tap device → ⚙️ Settings → Network Info / Device IP. In Tasmota web UI: Information → Network.

Method C — ARP scan for new IPs:

# Compare current ARP table against known IPs to find new devices
import subprocess
arp_output = subprocess.run(['cat', '/proc/net/arp'], capture_output=True, text=True).stdout
new_ips = [line.split()[0] for line in arp_output.split('\n')[1:] if line.strip()
           and line.split()[0] not in known_ips]

Method D — MAC vendor lookup: Identify unknown devices by MAC OUI:

curl -s "https://api.macvendors.com/XX:XX:XX"  # first 3 octets only
# Sonoff/ITEAD common prefixes: 68:C6:3A, EC:FA:BC, C8:2B:96, DC:4F:22, 84:F3:EB

Method E — Port scan for IoT signatures:

# Sonoff LAN API port (Tasmota HTTP on :80, eWeLink LAN on :8081)
curl -s -m2 "http://DEVICE_IP:8081/"
# Tasmota status endpoint
curl -s -m2 "http://DEVICE_IP/cm?cmnd=Status%200"

Phase 3: Enable Local Control

Stock Sonoff (eWeLink)

In eWeLink app: ⚙️ Settings → LAN Control → ON
This enables the local TCP API on port 8081
Now HA's Sonoff LAN integration can auto-discover it

Troubleshooting LAN Mode

Symptom: port 8081 accepts TCP but never responds. The device completes the TCP handshake (SYN-ACK) but no application-layer data is returned — HTTP, WebSocket, and raw protocol requests all time out silently. This means the LAN API service process on the device is hung or was never started, even though the port shows as listening.

Fix: Power-cycle the device. Unplug for 10 seconds and plug back in. After reboot, verify:

# TCP must succeed
nc -zv -w3 DEVICE_IP 8081
# Must return JSON (not timeout)
curl -s --max-time 3 http://DEVICE_IP:8081/zeroconf/info

If zeroconf/info returns a JSON payload with deviceid, model, sw_version etc., LAN mode is working correctly.

Tasmota

Already local. Set MQTT or use the HTTP API directly.
Default web UI at http://DEVICE_IP/

Phase 4: Add to Home Assistant

Sonoff LAN integration: Settings → Devices & Services → Add Integration → Sonoff LAN → auto-discovers
Tasmota integration: Settings → Add Integration → Tasmota (auto-discovers via MQTT or HTTP)
ESPHome: Add via ESPHome dashboard or manual YAML

Manual MQTT discovery also works for all three.

Sonoff S31-Specific Notes

Model: S31 Lite (WiFi smart plug with power monitoring)
Flash method: tuya-convert (OTA) or serial (TX/RX/GND/3.3V — requires opening case)
Stock LAN API port: 8081 (TCP)
Tasmota template: {"NAME":"Sonoff S31","GPIO":[0,0,0,0,0,0,0,0,0,0,0,0,0,0],"FLAG":0,"BASE":18}
Power monitoring: HLW8012 chip — reports voltage, current, power, energy

3.7 KiB Raw Blame History