Skip to content

Latest commit

 

History

History
194 lines (151 loc) · 4.78 KB

README.md

File metadata and controls

194 lines (151 loc) · 4.78 KB
Raw

Gecko Controller

A Raspberry Pi-based temperature, light, and UV controller for gecko vivarium monitoring and control.

Diablo the Leopard Gecko

Diablo the Leopard Gecko, for whom this controller was built

Features

  • Real-time temperature and humidity monitoring via SHT31 sensor
  • UV spectrum monitoring (UVA/UVB/UVC) via AS7331 sensor
  • Automated light cycle control with configurable schedules
  • Temperature-based heating control with day/night settings
  • OLED status display showing:
    • Current time
    • Temperature and humidity readings
    • Target temperature
    • UV levels with status indicators
    • Light and heat status
    • Time until next light transition
  • Web interface for:
    • Real-time environmental monitoring
    • Temperature and light schedule configuration
    • Historical data visualization
    • Mobile-friendly responsive design
  • Logging of environmental conditions

Hardware Requirements

  • Raspberry Pi (any model with GPIO pins)
  • SSH1106 OLED Display (I2C interface)
  • SHT31 Temperature/Humidity Sensor
  • AS7331 Spectral UV Sensor
  • 2x Relay modules (for light and heat control)
  • Compatible 5V power supply
  • I2C-compatible cables and connectors

Installation

Method 1: Using the Debian Package (Recommended)

  1. Enable I2C on your Raspberry Pi:

    sudo raspi-config
# Navigate to Interface Options > I2C > Enable

  2. Install the package:

    sudo apt update
sudo apt install gecko-controller

  3. The controller service will start automatically. Check its status with:

    sudo systemctl status gecko-controller

  4. Start and enable the web interface:

    sudo systemctl start gecko-web
sudo systemctl enable gecko-web

Method 2: Running from Source

  1. Enable I2C as described above

  2. Clone the repository:

    git clone https://github.com/yourusername/gecko-controller.git
cd gecko-controller

  3. Install required packages:

    python3 -m pip install RPi.GPIO smbus2 Pillow Flask

  4. Run the controller:

    python3 gecko_controller/controller.py

  5. In a separate terminal, run the web interface:

    python3 -m gecko_controller.web.app

Web Interface

The web interface is accessible at http://<raspberry-pi-ip>/ and provides:

  • Real-time monitoring dashboard
    • Current temperature and humidity
    • UV levels with status indicators
    • Light and heat status
  • Historical data graphs
    • Temperature and humidity trends
    • UV exposure levels
  • Configuration panel
    • Temperature thresholds
    • Light schedule
    • UV warning levels

Configuration

Create or modify /etc/gecko-controller/config.py with your settings:

# Gecko Controller Configuration File
# This file will be installed to /etc/gecko-controller/config.py
# You can modify these values to customize your gecko enclosure settings
# The service must be restarted after changes: sudo systemctl restart gecko-controller

# Display I2C
DISPLAY_ADDRESS = 0x3c

# GPIO Pins
LIGHT_RELAY = 17
HEAT_RELAY = 4
DISPLAY_RESET = 21

# Temperature Settings
MIN_TEMP = 15.0
DAY_TEMP = 30.0
TEMP_TOLERANCE = 1.0

# Time Settings
LIGHT_ON_TIME = "07:30"
LIGHT_OFF_TIME = "19:30"

# UV Thresholds # μW/cm²
UVA_THRESHOLDS = {
    'low': 50.0,
    'high': 100.0
}

UVB_THRESHOLDS = {
    'low': 2.0,
    'high': 5.0
}

# UV View Factor Correction
SENSOR_HEIGHT = 0.2
LAMP_DIST_FROM_BACK = 0.3
ENCLOSURE_HEIGHT = 0.5
SENSOR_ANGLE = 90

GPIO Wiring

Component GPIO Pin Notes
Light Relay GPIO 4 Active HIGH for ON
Heat Relay GPIO 17 Active HIGH for ON
Display Reset GPIO 21 Optional, HIGH for normal
I2C SDA GPIO 2 For all I2C devices
I2C SCL GPIO 3 For all I2C devices

Troubleshooting

  1. Check I2C devices are detected:

    sudo i2cdetect -y 1

  2. View service logs:

    journalctl -u gecko-controller -f

  3. Common issues:

    • If display shows no data, check I2C connections and addresses
    • If UV readings show as "None", verify AS7331 sensor connection
    • For temperature/humidity errors, check SHT31 sensor wiring

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues, questions, or contributions, please open an issue on the GitHub repository.