Connection Methods - homebridge-plugins/homebridge-ewelink GitHub Wiki

HTTPS API

The plugin connects to the eWeLink HTTPS API on Homebridge startup to authenticate user credentials and request a list of devices and current state. The plugin also uses the HTTPS API to request the full details of a new device that is added to your eWeLink account whilst Homebridge is running.

This initial connection to the eWeLink server is necessary regardless of your plugin mode setting (except when using LAN mode without eWeLink credentials, see last section on this page).

Connection Modes

You can use the mode setting to allow and restrict which connection methods the plugin should use:

  • Hybrid ("auto")

    • LAN control for supported devices will be attempted and will revert to the web socket upon failure
    • Devices that don't support LAN mode will automatically use the web socket
    • This setting is the default and is recommended for most users

  • Cloud-Only ("wan")

    • The plugin will only use the web socket to control your devices
    • This setting can be useful if you find LAN updates are slow and failing, and in some cases the web socket can be faster than LAN control

  • LAN-Only ("lan")

    • The plugin will only communicate to supported devices via LAN
    • Devices that don't support LAN control will be removed from Homebridge
    • The plugin will not create a web socket connection with eWeLink
    • This mode can be useful if you only use LAN-enabled devices and you can block the devices from accessing the internet

The LAN mode monitoring and the web socket are persistent connections that "listen" for device updates whilst Homebridge is running. This means there is no need to "poll" for device updates. If a device goes offline then Homebridge will be notified once eWeLink updates the device status. There can be a small delay. If a devices comes back online then Homebridge will be notified once eWeLink updates the device status. Again, there can be a small delay. Homebridge will refresh a device's current status upon being notified it is online.

WAN Mode

A web socket connection is used for (1) devices that don't support LAN mode and (2) as a "fallback" if there is an issue with LAN mode. In these cases the web socket is used to:

  • Send device updates from Homebridge to eWeLink, and
  • Receive real-time updates from eWeLink when devices are controlled outside of Homebridge (e.g. physically or through the eWeLink app)

LAN Mode

LAN mode is available for devices that support this mode and is generally faster than the web socket (see below). Currently the plugin will:

  • Discover eWeLink devices on your local network,
  • Send device updates for supported devices, and
  • Receive real-time updates when devices are controlled outside of Homebridge (e.g. physically or through the eWeLink app).

If a device on your network changes IP address then the plugin will be updated upon receiving a status update from the device. If you try to control the device before this, then the request will fail and default to web socket. It is recommended to give your eWeLink devices a static IP from your router. You can also use the configuration to "override" device IPs, see Configuration.

Devices are unable to "alert" Homebridge via LAN mode if they go offline - because they are offline! The only way that Homebridge gets notified of offline devices is through the web socket (see above).

For a list of devices that support LAN control, see Supported Devices.

LAN Mode (without eWeLink credentials)

With your eWeLink credentials, the plugin obtains a device list from your account. This includes retrieving a 'device key' per device which is used to encrypt and decrypt LAN messages sent across your local network to and from your LAN devices. For this reason, it is necessary to configure your eWeLink credentials at least once in the plugin. The plugin will store a 'cache' version of your devices in the Homebridge storage directory.

You can then remove your eWeLink credentials from the configuration and the plugin will use this cache to maintain the accessory list in Homebridge. Note that the plugin must be in lan-mode when you remove your eWeLink credentials. If the plugin is in any other mode and initialises without any eWeLink credentials, then all your accessories will be removed from Homebridge.

Since the plugin is no longer linked to your eWeLink account, any changes to your device list (e.g. adding new devices or removing old ones) will not be reflected in Homebridge. Simply add your eWeLink credentials back to the plugin, restart, and the plugin will re-create the accessory cache with your new devices and removing any you have deleted from your eWeLink account. After this, you can remove your eWeLink credentials from the configuration once again.