codejive/ewelink-mqtt-bridge repository overview

⁠eWeLink to MQTT Bridge

From: https://github.com/codejive/ewelink-mqtt-bridge⁠

ewelink-mqtt-bridge connects to the eWeLink cloud websocket and republishes device updates to any MQTT broker.

This is useful when your eWeLink devices can't connect directly to your MQTT broker. For example because your broker is on a public server and uses SSL, which the eWeLink devices don't support.

⁠How It Works

1. Authenticate to eWeLink cloud using account credentials.
2. Open a persistent websocket to receive live device update events.
3. Publish each update to MQTT topics using a predictable topic structure.

⁠MQTT Topics

Default topic layout:

• ewelink/<deviceId>/state/raw
• ewelink/<deviceId>/state/<key>
• ewelink/bridge/status

Examples:

• ewelink/1000abcdef/state/raw -> {"temperature":22.5,"humidity":48}
• ewelink/1000abcdef/state/temperature -> 22.5
• ewelink/1000abcdef/state/humidity -> 48
• ewelink/bridge/status -> online or offline

Topic prefix is configurable via TOPIC_PREFIX.

⁠Environment Variables

The bridge is configured only through environment variables.

Boolean variables (PUBLISH_RAW_STATE, MQTT_RETAIN, EXIT_ON_WEBSOCKET_CLOSE) accept: true/false, 1/0, yes/no, on/off.

⁠Quick Start (Node.js)

1. Install dependencies:

npm install

1. Run with required variables:

EWELINK_EMAIL="[email protected]" \
EWELINK_PASSWORD="your-password" \
EWELINK_REGION="eu" \
MQTT_URL="mqtt://127.0.0.1:1883" \
node bridge.js

⁠Docker

Build image:

docker build -t ewelink-mqtt-bridge:local .

Run container:

docker run -d \
  --name ewelink-mqtt-bridge \
  --restart unless-stopped \
  -e EWELINK_EMAIL="[email protected]" \
  -e EWELINK_PASSWORD="your-password" \
  -e EWELINK_REGION="eu" \
  -e MQTT_URL="mqtt://broker:1883" \
  -e MQTT_USER="mqtt-user" \
  -e MQTT_PASS="mqtt-pass" \
  ewelink-mqtt-bridge:local

Use host networking only if your platform/setup requires it.

⁠Docker Compose

1. Copy .env.example to .env and fill in your values.
2. Update image in docker-compose.yml to your published image (or build locally and point to that tag).
3. Start:

docker compose up -d

⁠Publish to Docker Hub (Manual)

docker login
docker tag ewelink-mqtt-bridge:local <namespace>/ewelink-mqtt-bridge:latest
docker push <namespace>/ewelink-mqtt-bridge:latest

<namespace> can be a personal Docker Hub username or an organization name.

⁠Publish via GitHub Actions

Workflow: .github/workflows/docker-publish.yml

Required repository secrets:

• DOCKERHUB_USERNAME: Docker account used for login.
• DOCKERHUB_TOKEN: Docker access token.
• DOCKERHUB_NAMESPACE: Docker Hub namespace to publish to (user or organization).

Publish behavior:

• Push to default branch publishes latest.
• Push tag v*.*.* publishes version tags.

⁠Operational Notes

• If websocket connectivity drops, the bridge can exit and rely on container restart policy.
• MQTT retained messages are convenient for Home Assistant and similar consumers, but can be disabled with MQTT_RETAIN=false.
• If your broker requires TLS, use an mqtts:// URL and ensure trust/cert settings are provided by your runtime environment.

⁠License

This project is licensed under the Apache License 2.0. See LICENSE⁠.