Solar Simulator User Guide

Welcome to the SolaSim Studio user guide. This document provides everything you need to set up your solar simulation hardware and use the web interface to control lighting, rotation, and imaging for your experiments.

🚀 Quick Start: Installation & Setup

1. Prepare the Device

The Solar Simulator supports two hardware platforms:

• RP2040:bit (Raspberry Pi Pico-based): Use the Setup Wizard to flash firmware and deploy files automatically — no software installation needed.
• ESP32-S3 (advanced): Flash MicroPython using esptool and upload files manually — see the GitHub repository for instructions.

2. Open SolaSim Studio

You do not need to install any software on your computer to control the device.

• Recommended: Open https://odeepllama.github.io/SolarSim/ in a compatible browser (Google Chrome, Microsoft Edge, or Opera).
• Advanced/Offline: If you have the SolaSimStudio.html file locally, you can simply double-click it to open it in your browser.

3. Connect

There are two ways to connect to your device:

Option A: USB Cable (all devices)

1. Connect the device to your computer via USB cable.
2. Click the green 🔌 Connect Device button in the top "Monitor / Interact" bar.
3. A browser window will pop up asking permission to connect to a serial device.
4. Select your device (often listed as "Board in FS node") and click Connect.
5. The status badge will turn green and show CONNECTED.
6. If the device does not immediately connect, press the RESET button on the edge of the board and try connecting again.

💡 Core Concepts

Before using the system, it is helpful to understand two key concepts:

Form vs. Device

• The Form (Web Page): This is your workspace. Changing numbers or settings here does not immediately change the device. It is like writing a document before printing it.
• The Device (Hardware): This is the physical board running the simulation.
• Syncing: To make your form settings take effect on the hardware, you must click Upload to Device.

Auto-Load & Persistence

• Temporary Changes: If you use the "Monitor" tiles to change speed or intensity, those changes are lost if the device loses power.
• Persistent Profiles: When you Upload to Device, the system saves your settings as a file.
• Auto-Load: By default, when the device powers up, it looks for the most recently uploaded profile and runs it automatically. If Auto-Load is disabled, the device will start with default settings (single sun, 1X speed, sunrise 0600, sunset 1800, etc).

🎮 Three Ways to Use SolaSim Studio

1. Real-Time Interaction (Monitor Mode)

Best for: Quick adjustments, testing hardware, and checking status.

At the top of the page is the Monitor / Interact bar. Click the arrow to expand it if the Solar Arc is not visible.

• Status Tiles: You will see live data from the device (e.g., SimTime, Speed, Intensity).
  • Click a tile to change its value immediately. For example, click Speed to pause (HOLD) or fast-forward (600x) the simulated time.
  • Double-click certain tiles (like Program or Rotation) to toggle them ON or OFF.
• Command Console: Type commands manually (e.g., set intensity 0.5) in the text box for precise control. The Show All Commands button will output all commands in the log window (Visible in Advanced mode).
• Solar Arc: A visual representation of the sun's position and day/night cycle.

Note: Changes made here happen immediately but are not saved to the permanent profile.

2. Building Custom Profiles

Best for: Designing specific experiments with precise lighting and timing requirements.

Use the main form to define your experiment parameters.

Core Settings

• Start Time: When the simulation clock begins (e.g., 0600 for 6 AM).
• Time Scale: How fast time passes (e.g., 60x means 1 hour passes in 1 minute).
• Solar Mode:
  • BASIC: Simple sunrise (6 AM) to sunset (6 PM) with constant sun size.
  • SCIENTIFIC: Calculates accurate sun position based on the Date and Latitude you provide.
  • CUSTOM: User-defined sunrise and sunset times with constant sun size (like BASIC).
• Sun Color: Choose BLUE (standard for experiments), NATURAL (yellow/white), or CUSTOM (RGB).

Program Steps (The Timeline)

If you need the conditions to change over time (e.g., "Run at 2x speed until noon, then hold for 1 hour"), use the Program Steps section.

1. Ensure Program Enabled is checked.
2. Click Add Step to create a new sequence — or click the Examples… button to load a ready-made template program.
3. For each step, define:
   • Sim Time: When this step targets (e.g., 1200). This is the simulated hour of the day, not wall-clock time.
   • Transition: RUN (simulate time passing) or JUMP (skip instantly).
   • Speed/Intensity: The conditions during this step.
   • Sun Color: Optional per-step color override (R,G,B). Use the color picker or leave blank to use the global sun color.
4. Use the Timeline Visualization to verify your sequence looks correct.
5. You can add additional days with different steps/conditions if your experiment requires.

Rotation Imaging

Configure the turntable and camera triggers.

• Rotation Enabled: Master switch for the rotating platform.
• Capture Mode: STILLS (stop-motion) or VIDEO (continuous).
• Intervals: How often to take photos or rotate.

3. Uploading & Running

Best for: Starting your experiment.

Once your form is configured:

1. Check the Profile Diff Viewer (yellow highlights). This shows you what is different between your form and the device.
2. Click the green Upload to Device button.
3. Follow the prompt (you may need to press the RESET button on the device if requested, though usually it is automatic).
4. The device will save the profile, restart, and begin running your experiment immediately.

📂 Managing Profiles

Loading from Device

If you want to see or edit the profile currently running on the hardware:

1. Click Load / Delete from Device.
2. A list of profiles stored on the device will appear.
3. Select a profile to load it into the web form.
   Note: Selecting a profile here also tells the device to run it immediately, but it does not make it the "default" for the next startup unless you re-upload it or it is already the most recent profile.

Saving & Importing

• Save Profile: Saves your current settings as a text file (.txt) to your computer. Useful for sharing experiments or backups.
• Import Profile: Loads a .txt file from your computer into the web form.
• Recent Profiles: The bar at the top of the form saves your recent configurations automatically. Click one to restore it. Click the Star to prevent key profiles from rotating off the screen as more are created.

Profile Comparison

When you load a profile, the Comparison Window will show you exactly what is different between your current settings and the new profile.

• Orange Fields: Indicate settings that differ.
• Apply: Overwrites your form with the new profile.

⚙️ Advanced Features

Simple vs. Advanced Mode

• Simple Mode: Hides complex settings (like specific servo timings or RGB values) to keep the interface clean.
• Advanced Mode: Shows all available parameters.
• Use the Gear Icon (⚙) next to the mode toggle to customize which sections are hidden in Simple Mode.

Device Labeling

If you have multiple devices connected:

1. Click the Device Badge (e.g., "Device 1") in the top header.
2. Rename it (e.g., "Experiment A").
3. Use the Background Color swatches (top right) to color-code your tabs (Green, Blue, Red).

Troubleshooting

Issue	Solution
Device not connecting (USB)	Ensure no other tab or program (like Thonny or VS Code) is using the USB port. Unplug and replug the device.
Settings didn't change	Did you click Upload? Changing the form only updates the web view, not the hardware.
Wrong profile on startup	The device auto-loads the profile with the newest timestamp. If you loaded an older profile via "Load from Device", it won't persist after a reboot. To make an old profile permanent, Upload it again so it gets a new timestamp.
Orange highlights everywhere	This is normal! It means the settings in your web form are different to those on the device. Click Sync to Device (in the banner) or Upload to make them match.

ソーラーシミュレーター ユーザーガイド

SolaSim Studio ユーザーガイドへようこそ。このドキュメントは、ソーラーシミュレーションハードウェアのセットアップ方法と、ウェブインターフェースを使った照明、回転、イメージング制御の手順をすべて説明します。

🚀 クイックスタート：インストールとセットアップ

1. デバイスの準備
   ソーラーシミュレーターは2つのハードウェアプラットフォームに対応しています：
   
   • RP2040:bit（Raspberry Pi Picoベース）：ブートローダーモードで.uf2ファイルをドラッグ＆ドロップしてファームウェアをインストールします。
   • ESP32-S3：esptoolを使用してMicroPythonファームウェアをフラッシュし、ソーラーシミュレーターのPythonファイルをアップロードします。
   RP2040:bit ファームウェアのインストール：
   
   1. ファームウェアのダウンロード： SolaSim GitHubリポジトリから最新のSolarSimulator_YYYYMMDD.uf2ファイルを取得します。
   2. ブートローダーモードに入る：
      • 基板の端にあるBOOTボタンを押し続けます。
      • BOOTを押したまま、RESETボタンを押します。
      • ボタンを離します。
   3. ファームウェアのインストール：
      • コンピュータに「RPI-RP2」という新しいドライブが表示されます（USBメモリのように）。
      • このドライブに.uf2ファイルをドラッグ＆ドロップします。
      • デバイスは自動的に切断・再起動します。これでインストール完了です！
2. SolaSim Studioを開く
   デバイスを操作するためにPCへソフトウェアをインストールする必要はありません。
   
   • 推奨：https://odeepllama.github.io/SolarSim/ をGoogle Chrome、Microsoft Edge、Operaなどの対応ブラウザで開きます。
   • 上級者/オフライン：ProfileBuilder.htmlファイルをローカルでダブルクリックしてブラウザで開くことも可能です。
3. 接続
   デバイスへの2つの接続方法があります：
   方法A：USBケーブル（全デバイス）
   
   1. USBケーブルでデバイスをPCに接続します。
   2. 画面上部の「Monitor / Interact」バーの緑色の「🔌 USB接続」ボタンをクリックします。
   3. ブラウザのウィンドウが開き、シリアルデバイスへの接続許可を求められます。
   4. デバイス（多くの場合「Board in FS node」等）を選択し、「接続」をクリックします。
   5. ステータスバッジが緑色になり「CONNECTED」と表示されます。
   6. すぐに接続できない場合は、基板のRESETボタンを押して再度お試しください。

💡 基本概念

• フォームとデバイス
  フォーム（ウェブページ）: ここが作業スペースです。数値や設定を変更しても、すぐにデバイスへ反映されるわけではありません。印刷前の文書作成のようなものです。
  デバイス（ハードウェア）: 実際にシミュレーションを実行する物理ボードです。
  同期: フォームの設定をハードウェアに反映させるには「アップロード」ボタンをクリックしてください。
• 自動ロードと永続性
  一時的な変更: 「Monitor」タイルで速度や強度を変更した場合、電源が切れるとその変更は失われます。
  永続プロファイル: 「アップロード」時、設定はファイルとして保存されます。
  自動ロード: 通常、デバイス起動時は最新のプロファイルが自動で読み込まれます。自動ロードを無効にすると、デフォルト設定（単一太陽、1X速度、日の出0600、日の入り1800等）で起動します。

🎮 SolaSim Studioの3つの使い方

1. リアルタイム操作（モニターモード）
   最適：素早い調整、ハードウェアのテスト、状態確認
   ページ上部の「Monitor / Interact」バーを展開し、Solar Arcが見えない場合は矢印をクリックしてください。
   
   • ステータスタイル: デバイスからのライブデータ（SimTime、Speed、Intensity等）が表示されます。
   • タイルをクリックすると値を即座に変更できます（例：Speedで一時停止や高速化）。
   • 一部タイル（ProgramやRotation等）はダブルクリックでON/OFF切替が可能です。
   • コマンドコンソール: テキストボックスにコマンド（例：set intensity 0.5）を手入力できます。「Show All Commands」ボタンで全コマンドをログウィンドウに出力（Advancedモード時）。
   • Solar Arc: 太陽の位置や昼夜サイクルを視覚的に表示します。
   • ※ここでの変更は即時反映されますが、永続プロファイルには保存されません。
2. カスタムプロファイルの作成
   最適：実験に合わせた詳細な照明・タイミング設計
   メインフォームで実験パラメータを定義します。
   • 開始時刻: シミュレーション開始時刻（例：0600は午前6時）
   • タイムスケール: 時間の進み方（例：60xは1分で1時間進行）
   • ソーラーモード:
     • BASIC：単純な日の出（6時）～日の入り（18時）、太陽サイズ一定
     • SCIENTIFIC：日付・緯度に基づき正確な太陽位置を計算
     • CUSTOM：ユーザー定義の日の出・日の入り時刻、太陽サイズ一定（BASIC式）
   • 太陽色: BLUE（実験標準）、NATURAL（黄/白）、CUSTOM（RGB指定）

   プログラムステップ（タイムライン）

   • 条件を時間で変化させたい場合（例：「正午まで2x速度、その後1時間HOLD」等）はProgram Stepsを利用します。
   • Program EnabledをONにします。
   • Add Stepで新しいシーケンスを追加します。
   • 各ステップで以下を設定：
     • Time：このステップの時刻（例：1200）
     • Transition：RUN（時間進行）またはJUMP（即時遷移）
     • Speed/Intensity：このステップ中の条件
     • Sun Color：ステップごとの太陽色オーバーライド（R,G,B）。カラーピッカーで選択するか、空欄でグローバル太陽色設定を使用
   • Timeline Visualizationでシーケンスを確認できます。
   • 必要に応じて複数日・異なる条件も追加可能です。

   回転・イメージング

   • 回転有効: ターンテーブルの主電源
   • キャプチャモード: STILLS（静止画）またはVIDEO（連続）
   • インターバル: 撮影や回転の間隔
3. アップロードと実行
   最適：実験開始時
   
   1. フォーム設定後、「Profile Diff Viewer」（黄色ハイライト）でフォームとデバイスの差分を確認します。
   2. 緑色の「アップロード」ボタンをクリックします。
   3. プロンプトに従い、必要に応じてRESETボタンを押してください（通常は自動）。
   4. デバイスがプロファイルを保存し、再起動して実験を開始します。

📂 プロファイル管理

デバイスからの読み込み

1. 現在ハードウェアで動作中のプロファイルを確認・編集したい場合：
2. 「Load / Delete from Device」をクリックします。
3. デバイスのプロファイル一覧が表示されます。
4. プロファイルを選択するとウェブフォームに読み込まれます。
   ※ここで選択したプロファイルは即時実行されますが、再起動後もデフォルトにしたい場合は再度アップロードしてください。

保存とインポート

• プロファイルのダウンロード: 現在の設定をテキストファイル（.txt）としてPCに保存。実験共有やバックアップに便利です。
• プロファイルのインポート: .txtファイルをPCからウェブフォームに読み込みます。
• 最近のプロファイル: フォーム上部のバーに最近の設定が自動保存されます。クリックで復元、スターで重要プロファイルを固定可能。

プロファイル比較

• プロファイルを読み込むと、Comparison Windowで現在の設定と新しいプロファイルの違いが明確に表示されます。
• オレンジ色のフィールド: 設定が異なる箇所を示します。
• 適用: 新しいプロファイルでフォームを上書きします。

⚙️ 高度な機能

シンプルモードとアドバンストモード

• シンプルモード: 複雑な設定（サーボタイミングやRGB値等）を非表示にし、インターフェースを簡潔に保ちます。
• アドバンストモード: すべてのパラメータを表示します。
• モード切替横のギアアイコン（⚙）でシンプルモード時に非表示にするセクションをカスタマイズ可能です。

デバイスラベリング

• 複数デバイス接続時：
• 上部ヘッダーのDevice Badge（例：「Device 1」）をクリック
• 名前を変更（例：「Experiment A」）
• 右上の背景色スウォッチ（緑・青・赤）でタブを色分け

トラブルシューティング

問題	解決策
デバイスが接続できない（USB）	他のタブやプログラム（ThonnyやVS Code等）がUSBポートを使用していないか確認し、デバイスを抜き差ししてください。
設定が反映されない	「アップロード」ボタンをクリックしましたか？フォームの変更だけではハードウェアに反映されません。
起動時に違うプロファイルが読み込まれる	デバイスは最新のタイムスタンプのプロファイルを自動で読み込みます。「Load from Device」で古いプロファイルを読み込んだ場合、再起動後は保持されません。古いプロファイルを常時使いたい場合は再度アップロードしてください。
オレンジ色のハイライトが消えない	これは正常です！フォームとデバイスの設定が異なる場合に表示されます。「デバイスと同期」または「アップロード」で一致させてください。