SimpleCloudDetect

<div align="center">

☁️ SimpleCloudDetect

A Machine Learning-based cloud detection system for AllSky cameras with MQTT and ASCOM Alpaca SafetyMonitor integration.

</div>

---

Table of Contents

• Features
• Quick Start
• Screenshots
• Docker Installation
  • Environment Variables
  • Docker Run Examples
  • Docker Compose Examples
• Home Assistant Integration
• ASCOM Alpaca SafetyMonitor
• External REST API
• Training Your Own Model
• Recent Changes
• Documentation

---

Features

• ML Cloud Classification - Detects Clear, Wisps, Mostly Cloudy, Overcast, Rain, and Snow conditions
• Home Assistant Integration - MQTT Discovery for automatic setup or legacy manual configuration
• ASCOM Alpaca SafetyMonitor - Compatible with N.I.N.A., SGP, TheSkyX, and other astronomy software
• External REST API - Flexible JSON API for dashboards, monitoring systems, and custom integrations
• Docker Support - Easy deployment with both services running simultaneously
• Flexible Image Sources - Supports URL-based and local file images
• Custom Models - Bring your own trained model and labels
• Confidence Scores - Includes detection confidence and timing metrics

---

Quick Start

Docker (Recommended):

1. Prepare the configuration directory:

mkdir -p /path/to/config
sudo chown 1000:1000 /path/to/config

2. Run the container:

docker run -d --name simple-cloud-detect --network=host \
  -v /path/to/config:/config \
  -v /path/to/keras_model.h5:/app/keras_model.h5 \
  -v /path/to/labels.txt:/app/labels.txt \
  -e IMAGE_URL="http://your-allsky-camera/image.jpg" \
  -e MQTT_BROKER="192.168.1.250" \
  -e MQTT_DISCOVERY_MODE="homeassistant" \
  -e DETECT_INTERVAL="60" \
  -e VERIFY_SSL="false" \
  -e DEVICE_ID="clouddetect_001" \
  chvvkumar/simpleclouddetect:latest

Important: The model files (keras_model.h5 and labels.txt) must have read+write permissions for the container user. To ensure proper permissions:

# Set appropriate permissions (Linux/macOS)
chmod 666 /path/to/keras_model.h5
chmod 666 /path/to/labels.txt

# Or set ownership to your user and make group-writable
chown $USER:$USER /path/to/keras_model.h5 /path/to/labels.txt
chmod 664 /path/to/keras_model.h5 /path/to/labels.txt

That's it! Your device will automatically appear in Home Assistant under Settings → Devices & Services → MQTT.

---

Screenshots

Cloud Detection Examples

| Condition | Example | |-----------|---------| | Clear Skies | | | Majority Clouds | | | Wisps of Clouds | | | Overcast | |

ASCOM Alpaca Settings Interface

| View | Screenshot | |------|------------| | Settings Collapsed | | | Settings Expanded | |

---

Docker Installation

Pull the Image

docker pull chvvkumar/simpleclouddetect:latest

Environment Variables

Required Variables

| Variable | Description | Example | |----------|-------------|---------| | IMAGE_URL | URL or file path to AllSky camera image | http://allskypi.lan/image.jpg | | MQTT_BROKER | MQTT broker address | 192.168.1.250 |

Cloud Detection Settings

| Variable | Default | Description | |----------|---------|-------------| | MQTT_PORT | 1883 | MQTT broker port | | MQTT_USERNAME | - | MQTT authentication username (optional) | | MQTT_PASSWORD | - | MQTT authentication password (optional) | | DETECT_INTERVAL | 60 | Detection interval in seconds | | VERIFY_SSL | false | Set to true to enable SSL certificate verification for HTTPS IMAGE_URLs. Defaults to false for convenience with self-signed certificates. |

MQTT Publishing Modes

| Variable | Default | Description | |----------|---------|-------------| | MQTT_DISCOVERY_MODE | legacy | Mode: legacy or homeassistant |

Legacy Mode (manual YAML configuration):

• MQTT_TOPIC - Topic for publishing (e.g., Astro/SimpleCloudDetect)

Home Assistant Discovery Mode (automatic setup):

• DEVICE_ID - Unique device identifier (e.g., clouddetect_001)
• DEVICE_NAME - Custom device name (default: Cloud Detector)
• MQTT_DISCOVERY_PREFIX - HA discovery prefix (default: homeassistant)

ASCOM Alpaca Settings (Optional)

| Variable | Default | Description | |----------|---------|-------------| | ALPACA_PORT | 11111 | HTTP API port | | ALPACA_DEVICE_NUMBER | 0 | Device number | | ALPACA_UPDATE_INTERVAL | 30 | Update interval in seconds |

Note: For detailed Alpaca configuration, see ALPACA_README.md

Persistent Configuration

To ensure your settings (device name, thresholds, etc.) are saved across container restarts, mount the /config directory:

-v /path/to/config:/config

The application will save alpaca_config.json in this directory. If a config file exists, it will take precedence for environment variables for the settings it contains.

Setting Proper Permissions:

The config directory must be writable by the container user. To ensure proper permissions:

# Create the config directory
mkdir -p /path/to/config

# Set appropriate permissions (Linux/macOS)
chmod 777 /path/to/config

# Or set ownership to a specific user (uses current user's UID, recommended for better security)
sudo chown $(id -u):$(id -g) /path/to/config
chmod 755 /path/to/config

Note: The container runs as user ID 1000 by default. If you encounter permission errors like [Errno 13] Permission denied: '/config/alpaca_config.json', verify that the config directory is writable by the container user.

Raspberry Pi Support

Multi-architecture support: The Docker images are built for both AMD64 (x86_64) and ARM64 (Raspberry Pi 4/5). Docker will automatically pull the correct image for your platform.

For Raspberry Pi, use the same docker commands. The ARM64 build uses full TensorFlow instead of tensorflow-cpu for compatibility.

Note: First run on Raspberry Pi may take longer as it downloads the ARM64 image (~500MB).

Docker Run Examples

Home Assistant Discovery Mode (Recommended)

With URL-based image:

docker run -d --name simple-cloud-detect --network=host \
  -v /path/to/config:/config \
  -v /path/to/keras_model.h5:/app/keras_model.h5 \
  -v /path/to/labels.txt:/app/labels.txt \
  -e IMAGE_URL="http://allskypi5.lan/current/resized/image.jpg" \
  -e MQTT_BROKER="192.168.1.250" \
  -e MQTT_PORT="1883" \
  -e MQTT_DISCOVERY_MODE="homeassistant" \
  -e DEVICE_ID="clouddetect_001" \
  -e DEVICE_NAME="AllSky Cloud Detector" \
  -e MQTT_USERNAME="your_username" \
  -e MQTT_PASSWORD="your_password" \
  -e DETECT_INTERVAL="60" \
  -e VERIFY_SSL="false" \
  chvvkumar/simpleclouddetect:latest

With local file:

docker run -d --name simple-cloud-detect --network=host \
  -v /path/to/config:/config \
  -v $HOME/path/to/image.jpg:/tmp/image.jpg \
  -v /path/to/keras_model.h5:/app/keras_model.h5 \
  -v /path/to/labels.txt:/app/labels.txt \
  -e IMAGE_URL="file:///tmp/image.jpg" \
  -e MQTT_BROKER="192.168.1.250" \
  -e MQTT_DISCOVERY_MODE="homeassistant" \
  -e DETECT_INTERVAL="60" \
  -e DEVICE_ID="clouddetect_001" \
  chvvkumar/simpleclouddetect:latest

Legacy Mode

With URL-based image:

docker run -d --name simple-cloud-detect --network=host \
  -v /path/to/config:/config \
  -v /path/to/keras_model.h5:/app/keras_model.h5 \
  -v /path/to/labels.txt:/app/labels.txt \
  -e IMAGE_URL="http://allskypi5.lan/current/resized/image.jpg" \
  -e MQTT_BROKER="192.168.1.250" \
  -e MQTT_TOPIC="Astro/SimpleCloudDetect" \
  -e DETECT_INTERVAL="60" \
  -e MQTT_USERNAME="your_username" \
  -e MQTT_PASSWORD="your_password" \
  -e VERIFY_SSL="false" \
  chvvkumar/simpleclouddetect:latest

Custom Model Support

To use your own trained model and labels:

docker run -d --name simple-cloud-detect --network=host \
  -v /path/to/config:/config \
  -v /path/to/your/keras_model.h5:/app/keras_model.h5 \
  -v /path/to/your/labels.txt:/app/labels.txt \
  -e IMAGE_URL="