ecowitt2mqtt 0.0.5

A small web server to send data from Ecowitt devices to an MQTT Broker

🔘 ecowitt2mqtt: Send Ecowitt device data to an MQTT broker

ecowitt2mqtt is a small CLI/web server that allows Ecowitt device data to be sent to an MQTT broker.

• Installation
• Python Versions
• Quick Start
• Advanced Usage
• Contributing

Installation

pip install ecowitt2mqtt

Python Versions

ecowitt2mqtt is currently supported on:

• Python 3.6
• Python 3.7
• Python 3.8

Quick Start

Note that this README assumes:

• you have access to an MQTT broker
• you have already paired your Ecowitt device with the WS View Android/iOS app from Ecowitt.

First, install ecowitt2mqtt via pip:

$ pip install ecowitt2mqtt

Then, shift over to the WS View app on your Android/iOS device. While viewing your device in the app, select Weather Services:

Press Next until you reach the Customized screen:

Fill out the form with these values and tap Save:

• Protocol Type Same As: Ecowitt
• Server IP / Hostname: the IP address/hostname of the device running ecowitt2mqtt
• Path: /data/report (note that unlike the default in the WS View App, there shouldn't be a trailing slash)
• Port: 8080
• Upload Interval: 60 (change this to alter the frequency with which data is published)

Then, on the machine where you installed ecowitt2mqtt, run it:

$ ecowitt2mqtt \
    --mqtt-broker=192.168.1.101 \
    --mqtt-username=user \
    --mqtt-password=password \
    --mqtt-topic=ecowitt/testdevice1

Within the Upload Interval, data should begin to appear in the MQTT broker at the topic specified.

Advanced Usage

Command Line Interface

The ecowitt2mqtt executable contains several configurable parameters:`

usage: ecowitt2mqtt [-h] --mqtt-broker MQTT_BROKER --mqtt-topic MQTT_TOPIC [--mqtt-port MQTT_PORT]
                    [--mqtt-username MQTT_USERNAME] [--mqtt-password MQTT_PASSWORD]
                    [--endpoint ENDPOINT] [--port PORT] [-l LOG_LEVEL]

Send data from Ecowitt devices to an MQTT broker

optional arguments:
  -h, --help            show this help message and exit
  --mqtt-broker MQTT_BROKER
                        The hostname or IP address of the MQTT broker
  --mqtt-topic MQTT_TOPIC
                        The MQTT topic to publish the device's data to
  --mqtt-port MQTT_PORT
                        The port of the MQTT broker (default: 1883)
  --mqtt-username MQTT_USERNAME
                        The username to use with the MQTT broker (default: None)
  --mqtt-password MQTT_PASSWORD
                        The password to use with the MQTT broker (default: None)
  --endpoint ENDPOINT   The relative endpoint/path to serve the web app on (default: /data/report)
  --port PORT           The port to serve the web app on (default: 8080)
  -l LOG_LEVEL, --log-level LOG_LEVEL
                        The logging level (default: INFO)

Run in the Background

ecowitt2mqtt doesn't, itself, provide any sort of daemonization mechanism. The suggested route is to use something like supervisord:

[supervisord]
nodaemon=true
loglevel=info
user=root

[program:ecowitt2mqtt]
command=ecowitt2mqtt --mqtt-broker=192.168.1.101 --mqtt-topic=ecowitt/testdevice1
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
redirect_stderr=true

Docker

The library is available via a Docker image (bachya/ecowitt2mqtt). It is configured by a handful of environment variables that correspond to the command line parameters listed above:

• LOG_LEVEL: the log level to use (default: INFO)
• ENDPOINT: the relative endpoint/path to serve the web app on (default: /data/report)
• PORT: the port to serve the web app on (default: 8080)
• MQTT_BROKER: the hostname or IP address of the MQTT broker
• MQTT_PORT: the port of the MQTT broker (default: 1883)
• MQTT_PASSWORD: the password to use with the MQTT broker (default: None)
• MQTT_USERNAME: the password to use with the MQTT broker (default: None)
• MQTT_TOPIC: the MQTT topic to publish the device's data to

Running the image is straightforward:

docker run -it \
    -e MQTT_BROKER=hub.phil.lan \
    -e MQTT_USERNAME=hass \
    -e MQTT_PASSWORD=pgNf4_TjSGcvIVCXnpTFn5IL^ \
    -e MQTT_TOPIC=ecowitt2mqtt/testdevice1 \
    -p 8080:8080 \
    bachya/ecowitt2mqtt:latest

Note the value of the -p flag: you must expose the port defined by the MQTT_PORT environment variable. In the example above, the default port (8080`) is used and is exposed via the same port on the host.

docker-compose users can find an example configuration file at docker-compose.dist.yml.

Contributing

1. Check for open features/bugs or initiate a discussion on one.
2. Fork the repository.
3. (optional, but highly recommended) Create a virtual environment: python3 -m venv .venv
4. (optional, but highly recommended) Enter the virtual environment: source ./.venv/bin/activate
5. Install the dev environment: script/setup
6. Code your new feature or bug fix.
7. Write tests that cover your new functionality.
8. Run tests and ensure 100% code coverage: script/test
9. Update README.md with any new documentation.
10. Add yourself to AUTHORS.md.
11. Submit a pull request!