LightWatch

LightWatchは、Raspberry Piと対応カメラを使用して室内照明の状態を定期撮影・分類・記録する、オープンソースの監視・タイムラプスシステムです。

観測結果をSQLiteへ保存し、状態変化時や定時の画像を保持します。保存画像のNAS同期、Slack通知、定期レポート、Health Check、FastAPIとReactによるWeb UIをsystemdで運用できます。

Web UI

照明状態、最新画像、状態タイムライン、保存画像、観測履歴をWebブラウザから確認できます。

掲載している画面は、ローカルWebプレビュー用のサンプルデータとダミー画像を使用しています。

照明状態とタイムライン

最新の照明状態、判定値、Health Check、NAS同期状況と、1日の状態変化をタイムラインで表示します。

保存画像と判定詳細

保存された画像を状態別に確認し、選択した画像の判定理由や照度指標を表示できます。

観測履歴

観測結果を時系列で一覧表示し、各観測の判定詳細を展開できます。

主な機能

• Raspberry Piカメラによる定期撮影
• BRIGHT / PARTIAL / DIM / DARK の4段階分類
• ROIを使用した照明状態判定
• SQLiteへの観測結果保存
• 初回観測、定時、状態変化時、解析失敗時の画像保存
• 非DARKからDARKへの遷移時のSlack通知
• 画像付き定期レポート
• SSH / rsyncによるNAS同期
• 同期済みローカル画像の保持期間管理
• 撮影、NAS同期、ディスク容量などのHealth Check
• FastAPI + ReactによるWeb UI
• タイムライン表示と画像履歴閲覧
• 保存画像の選択と判定詳細表示
• flock による撮影とライブビューの排他制御
• systemd service / timerの設定例
• 本番環境を使用しないローカルWebプレビュー

同梱の設定例では、5分ごとの撮影、毎時10分のNAS同期、毎時15分のHealth Check、06:30・12:30・18:30の定期レポートを使用します。必要に応じて設定ファイルとsystemd timerを変更してください。

システム構成

対応カメラ
    │
    ▼
Raspberry Pi
    ├─ 撮影・画像解析・照明分類
    ├─ SQLite記録
    ├─ Slack通知・定期レポート
    ├─ NAS同期・ローカル画像整理
    ├─ Health Check
    └─ FastAPI + React Web UI（既定ポート8000）

フロントエンドは開発用PCでビルドし、生成された frontend/dist/ をRaspberry Piへ配置します。

動作環境

開発環境

• Python 3.11以上、3.14未満
• uv
• Node.js / npm
• Git

付属のPowerShellスクリプトを使用する場合は、次の環境を推奨します。

• Windows 11
• PowerShell 7

実行環境

• Raspberry Pi Zero 2 W以降
• Raspberry Pi OS Lite 64-bit
• rpicam-apps 対応カメラ
• Python 3.11以上、3.14未満
• rpicam-still
• rpicam-vid
• rsync
• sqlite3
• flock

同梱の設定例とsystemdユニットでは、配置先として /opt/lightwatch、実行ユーザーとして pi を使用します。

開発環境のセットアップ

プロジェクトルートでPython依存関係を準備します。

uv sync --frozen

フロントエンド依存関係をlockfileに基づいてインストールします。

Push-Location frontend
npm ci
Pop-Location

フロントエンドを含む標準検証を実行します。

.\scripts\verify.ps1

Python側だけ確認する場合：

.\scripts\verify.ps1 -SkipFrontend

詳細は 開発環境と検証 を参照してください。

Raspberry Piの初期セットアップ

以下は、同梱のsystemdユニットに合わせて /opt/lightwatch へ配置する例です。

sudo mkdir -p /opt/lightwatch
sudo chown pi:pi /opt/lightwatch
cd /opt/lightwatch

uvをインストールし、Python実行依存関係を準備します。

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

uv sync --frozen --no-dev

本番設定はGit管理外の config/production.toml を使用します。

サンプルから作成します。

cp config/production.toml.example config/production.toml

設定ファイルは、環境変数 LIGHTWATCH_CONFIG で指定できます。systemd運用では /etc/lightwatch.env へ記載します。

LIGHTWATCH_CONFIG=/opt/lightwatch/config/production.toml

実際の配置先や実行ユーザーが異なる場合は、設定ファイルとsystemdユニットを変更してください。

systemdの導入と確認は systemd運用 を参照してください。

ローカルWebプレビュー

Raspberry Pi、本番DB、NAS、Slack、カメラを使用せず、サンプルDBとダミー画像を生成してWeb UIを確認できます。

サンプル画像には、次の4状態に対応した架空のオフィス画像を使用します。

• BRIGHT
• PARTIAL
• DIM
• DARK

実在するオフィス、人物、機密情報、実運用の撮影画像は含まれていません。

1. 開発用設定の作成

Copy-Item `
  .\config\development.toml.example `
  .\config\development.toml

2. サンプルデータの生成

uv run --locked python .\scripts\create-web-sample-data.py

既存のサンプルデータを作り直す場合：

uv run --locked python .\scripts\create-web-sample-data.py --force

生成先は既定で次の場所です。

.local/web-preview/
├─ timelapse.db
└─ images/

.local/ はGit管理対象外です。

3. バックエンドの起動

$env:LIGHTWATCH_CONFIG = "config/development.toml"

uv run --locked python -m uvicorn lightwatch.web:app `
  --host 127.0.0.1 `
  --port 8000 `
  --reload

APIの確認先：

http://127.0.0.1:8000/api/status

4. フロントエンドの起動

別のPowerShellを開いて実行します。

Push-Location frontend
npm run dev
Pop-Location

ブラウザで、Viteが表示したURLを開きます。通常は次のURLです。

http://127.0.0.1:5173

詳細は ローカルWebプレビュー を参照してください。

設定

設定ファイルの解決順は次のとおりです。

1. アプリ作成時に明示した設定パス
2. 環境変数 LIGHTWATCH_CONFIG
3. config/default.toml

主な設定項目：

セクション	内容
[camera]	撮影コマンド、解像度、画質、フォーカスなど
[storage]	画像、一時ファイル、状態ファイルの保存先
[database]	SQLiteデータベースのパス
[lighting]	照明判定の閾値とROI
[operations]	撮影間隔、画像保持期間
[nas]	NAS接続先、SSH鍵、タイムアウト

同梱のROI座標と閾値は2304×1296画像向けのサンプルです。実際のカメラ位置、画角、照明配置に合わせて調整してください。

プロジェクト構成

lightwatch/
├─ config/
│  ├─ default.toml
│  ├─ development.toml.example
│  └─ production.toml.example
├─ docs/
│  └─ images/
├─ frontend/
├─ scripts/
├─ src/
│  └─ lightwatch/
│     └─ assets/
│        └─ sample-images/
├─ systemd/
├─ tests/
├─ pyproject.toml
├─ uv.lock
└─ VERSION

src/lightwatch/assets/sample-images/ の画像は、ローカルWebプレビュー用のサンプルデータ生成に使用します。

docs/images/ の画像は、READMEやドキュメントへ掲載する画面キャプチャです。

ドキュメント

資料	内容
開発環境と検証	開発セットアップ、テスト、フロントエンドビルド
運用ガイド	撮影、通知、NAS、Health、Web UI、SQLite
照明状態判定とROI	画像指標、判定順序、ROI座標と閾値
systemd運用	service / timerの構成、導入、確認、ログ
ローカルWebプレビュー	サンプルDB生成とローカルUI確認

セキュリティ

LightWatchのWeb UIには、アプリケーション単体でのユーザー認証やTLS終端は含まれていません。信頼できるネットワーク内で使用するか、リバースプロキシやVPNなどでアクセス制御とHTTPSを追加してください。

次の情報や生成物はGitへコミットしないでください。

• .env とSlack認証情報
• 本番用設定ファイル
• SSH秘密鍵とNAS認証情報
• 実運用の撮影画像
• SQLiteデータベース
• 状態ファイル
• ログ
• .venv/
• frontend/node_modules/
• frontend/dist/
• ローカルWebプレビュー生成物

次の画像は、公開用サンプルとして意図的にGit管理します。

• src/lightwatch/assets/sample-images/*.png
• docs/images/*.png

脆弱性の報告方法とサポート対象バージョンは SECURITY.md を参照してください。

コントリビューション

IssueやPull Requestを作成する前に CONTRIBUTING.md を参照してください。

ライセンス

LightWatchはMIT Licenseで公開されています。詳細は LICENSE を参照してください。