From 9ad012f88cbf2e41300884488c1fece10bcf82b7 Mon Sep 17 00:00:00 2001 From: James Pattinson Date: Sun, 5 Oct 2025 15:24:45 +0100 Subject: [PATCH] Adding README --- README.md | 191 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 191 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..ad03af3 --- /dev/null +++ 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