Adding README
This commit is contained in:
191
README.md
Normal file
191
README.md
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user