Adding README

2025-10-05 15:24:45 +01:00
parent 7e7889b157
commit 9ad012f88c
1 changed files with 191 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,191 @@
+# Meteostick Logger
+
+A Python application for reading weather data from Davis Instruments weather stations via a Meteostick USB receiver. The application can display real-time weather data and optionally send it to InfluxDB for storage and visualization.
+
+## Features
+
+- Real-time weather data collection from Davis weather stations
+- Support for multiple sensor types (ISS, anemometer, temperature/humidity sensors)
+- InfluxDB integration for data storage
+- Docker support for easy deployment
+- Configurable via environment variables
+- Token-based authentication for InfluxDB
+
+## Supported Sensors
+
+- **ISS (Integrated Sensor Suite)**: Temperature, humidity, wind speed/direction, rain
+- **Anemometer Kit**: Additional wind measurements
+- **Temperature/Humidity Sensors**: Up to 2 additional T/H sensors
+- **Leaf/Soil Station**: Soil moisture and temperature sensors
+
+## Requirements
+
+- Python 3.7+
+- Meteostick USB device
+- Davis Instruments weather station transmitters
+- InfluxDB (optional, for data storage)
+
+## Installation
+
+### Python Dependencies
+
+```bash
+pip install pyserial influxdb
+```
+
+### Docker (Recommended)
+
+1. Clone this repository
+2. Create a `.env` file (see configuration below)
+3. Build and run with Docker Compose:
+
+```bash
+docker-compose up --build
+```
+
+## Configuration
+
+### Environment Variables
+
+The application is configured using environment variables. Create a `.env` file in the project root:
+
+```env
+# Meteostick Hardware Configuration
+METEOSTICK_PORT=/dev/ttyACM0
+METEOSTICK_BAUDRATE=115200
+METEOSTICK_FREQUENCY=EU
+METEOSTICK_RF_SENSITIVITY=90
+
+# Weather Station Channels (1-8, or 0 to disable)
+METEOSTICK_ISS_CHANNEL=1
+METEOSTICK_ANEMOMETER_CHANNEL=0
+METEOSTICK_LEAF_SOIL_CHANNEL=0
+METEOSTICK_TH1_CHANNEL=0
+METEOSTICK_TH2_CHANNEL=0
+
+# Rain Bucket Type (0=0.01in, 1=0.2mm)
+METEOSTICK_RAIN_BUCKET=1
+
+# InfluxDB Configuration
+METEOSTICK_ENABLE_INFLUXDB=true
+METEOSTICK_INFLUXDB_HOST=localhost
+METEOSTICK_INFLUXDB_PORT=8086
+METEOSTICK_INFLUXDB_DB=weather
+METEOSTICK_INFLUXDB_MEASUREMENT=meteostick
+METEOSTICK_INFLUXDB_TOKEN=your_influxdb_token_here
+```
+
+### Configuration Options
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `METEOSTICK_PORT` | `/dev/ttyUSB0` | Serial port for Meteostick device |
+| `METEOSTICK_BAUDRATE` | `115200` | Serial communication baud rate |
+| `METEOSTICK_FREQUENCY` | `EU` | RF frequency: `US`, `EU`, or `AU` |
+| `METEOSTICK_RF_SENSITIVITY` | `90` | RF sensitivity (0-125) |
+| `METEOSTICK_ISS_CHANNEL` | `1` | ISS transmitter channel (1-8) |
+| `METEOSTICK_ANEMOMETER_CHANNEL` | `0` | Anemometer channel (0=disabled, 1-8) |
+| `METEOSTICK_LEAF_SOIL_CHANNEL` | `0` | Leaf/soil station channel (0=disabled, 1-8) |
+| `METEOSTICK_TH1_CHANNEL` | `0` | T/H sensor 1 channel (0=disabled, 1-8) |
+| `METEOSTICK_TH2_CHANNEL` | `0` | T/H sensor 2 channel (0=disabled, 1-8) |
+| `METEOSTICK_RAIN_BUCKET` | `1` | Rain bucket type: 0=0.01in, 1=0.2mm |
+| `METEOSTICK_ENABLE_INFLUXDB` | `false` | Enable InfluxDB data logging |
+| `METEOSTICK_INFLUXDB_HOST` | `localhost` | InfluxDB server hostname |
+| `METEOSTICK_INFLUXDB_PORT` | `8086` | InfluxDB server port |
+| `METEOSTICK_INFLUXDB_DB` | `weather` | InfluxDB database name |
+| `METEOSTICK_INFLUXDB_MEASUREMENT` | `meteostick` | InfluxDB measurement name |
+| `METEOSTICK_INFLUXDB_TOKEN` | - | InfluxDB authentication token |
+
+## Usage
+
+### Direct Python Execution
+
+```bash
+# Basic usage with console output only
+python meteostick_reader.py --port /dev/ttyACM0
+
+# With InfluxDB logging
+python meteostick_reader.py --port /dev/ttyACM0 --enable-influxdb --influxdb-token "your_token"
+
+# All options via command line
+python meteostick_reader.py \
+  --port /dev/ttyACM0 \
+  --freq EU \
+  --iss-channel 1 \
+  --enable-influxdb \
+  --influxdb-host influxdb.example.com \
+  --influxdb-token "your_token"
+```
+
+### Docker Compose
+
+```bash
+# Start the service
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop the service
+docker-compose down
+```
+
+## Output Format
+
+### Console Output
+
+The application displays real-time weather data:
+
+```
+[2023-12-07 14:30:15] Message #123: I 1 0 48 89 8A 12 34 56 78 9A BC DE 95 1234567 0
+  Parsed data: {'channel': 1, 'temperature': 18.5, 'humidity': 65.0, 'wind_speed': 2.3, 'wind_dir': 225.0, 'rf_signal': 95}
+```
+
+### InfluxDB Data
+
+Data is stored in InfluxDB with the following structure:
+
+- **Measurement**: Configurable (default: `meteostick`)
+- **Tags**: `channel` (transmitter channel)
+- **Fields**: Weather data (temperature, humidity, wind_speed, wind_dir, pressure, etc.)
+- **Timestamp**: UTC timestamp when data was received
+
+## Troubleshooting
+
+### Serial Port Issues
+
+- Ensure the Meteostick device is connected and recognized by the system
+- Check permissions: `sudo usermod -a -G dialout $USER`
+- Verify the correct port with `ls /dev/tty*`
+
+### InfluxDB Connection Issues
+
+- Verify InfluxDB is running and accessible
+- Check authentication token validity
+- Ensure the database exists or the token has creation permissions
+
+### No Weather Data
+
+- Verify weather station transmitters are within range
+- Check RF sensitivity settings
+- Ensure correct channel configuration
+- Verify transmitter battery levels
+
+## License
+
+This project is based on the WeewX meteostick driver and is released under the same license terms.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Test thoroughly
+5. Submit a pull request
+
+## Support
+
+For issues and questions:
+1. Check the troubleshooting section
+2. Review Davis Instruments documentation
+3. Open an issue on the project repository