Coffee Hazel V2.3.3 — ユーザーマニュアル

Coffee Hazel は、焙煎中のΔH₂Oをリアルタイムで計測し、1ハゼ（First Crack）のタイミングを自動検出するデスクトップアプリケーションです。株式会社宙豆ラボ制作のCoffee Hazel センサーからデータを取得し、ΔH₂OとΔH₂O変化率のグラフをライブ表示します。

1. セットアップ

必要なもの

Coffee Hazel センサー（ΔH₂Oを計測し /getData エンドポイントで JSON を返すもの）
PC（Windows または macOS）と Coffee Hazel センサーが同じ Wi-Fi ネットワークに接続されていること

インストール（macOS）

Releases から CPU に合わせて DMG をダウンロード（Apple メニュー →「このMacについて」で確認） - Apple Silicon（M1 / M2 / M3 など）: CoffeeHazel-vX.Y.Z-AppleSilicon.dmg - Intel Mac: CoffeeHazel-vX.Y.Z-Intel.dmg
DMG を開き、Coffee Hazel.app をアプリケーションフォルダにドラッグ＆ドロップ
初回起動時に「"Coffee Hazel"は開いていません」「マルウェアが含まれていないことを検証できませんでした」と表示された場合（Apple公証を受けていないアプリに出る標準の警告で、アプリに問題はありません）: - macOS 15（Sequoia）以降: 警告を閉じ（「ゴミ箱に入れる」は押さない）→ システム設定 →「プライバシーとセキュリティ」→ 下部の「このまま開く」をクリック → パスワードまたは Touch ID で許可 - macOS 14（Sonoma）以前: アプリケーションフォルダで右クリック →「開く」→「開く」

インストール（Windows）

HazelSetup.exe を実行し、画面の指示に従ってインストールしてください。デスクトップにショートカットが作成されます。

対応OS: Windows 10 (64bit) 以降
本アプリは画面表示に WebView2 ランタイム を使用します。Windows 11 および最新の Windows 10（Edgeがプリインストールされているバージョン）では標準搭載されているため追加作業は不要です。
インストール後にアプリを起動しても画面が表示されない・真っ白になる場合は、WebView2 ランタイムが未導入の可能性があります。以下の手順で導入してください。 1. Microsoft公式のEvergreen Bootstrapperから「Evergreen Bootstrapper」をダウンロード 2. ダウンロードした MicrosoftEdgeWebview2Setup.exe を実行してインストール 3. Coffee Hazel を再起動

インストール（Ubuntu / Linux）

.deb パッケージを使ってインストールします。（対応OS: Ubuntu 22.04 / 24.04）

sudo dpkg -i coffee-hazel_2.3.3_amd64.deb
# 依存パッケージが不足している場合は以下を実行
sudo apt --fix-broken install

インストール後は以下のいずれかの方法で起動できます。

ターミナルから coffee-hazel コマンドを実行
アプリケーションメニューから「Coffee Hazel」を起動

アンインストールする場合は次のコマンドを実行してください。

sudo apt remove coffee-hazel

`.deb` パッケージを自分でビルドする場合

Hazel2_linux.spec を使って PyInstaller でビルドします（GTK3 の Python バインディングを使うため、--system-site-packages 付きの仮想環境を推奨）。

python3 -m venv --system-site-packages venv
source venv/bin/activate
pip install dash plotly requests pandas pywebview qrcode pillow pyinstaller flask
pyinstaller Hazel2_linux.spec

dist/CoffeeHazel/ に生成された実行ファイル一式を /opt/coffee-hazel/ などに配置し、DEBIAN/control を用意した上で dpkg-deb --build --root-owner-group <ディレクトリ名> で .deb を作成できます。

必要な実行時依存パッケージ：python3-gi, gir1.2-gtk-3.0, gir1.2-webkit2-4.1, libgtk-3-0（24.04 では libgtk-3-0t64）, bluez

ソースから実行する場合

pip install dash plotly requests pandas pywebview qrcode pillow
python app.py

起動するとデスクトップウィンドウが開きます。ブラウザから http://localhost:8050 にアクセスしても同じ画面を利用できます。

2. 画面構成

アプリは大きく 2 つのエリアに分かれています。

左側：サイドバー（タブ切り替え）

上部に 2 つのタブがあります。

Settings — 焙煎に使う設定（SSID、閾値、軸範囲、豆プリセットなど）
CSV Viewer — 保存済みの焙煎 CSV を読み込んでグラフ表示

右側：メインエリア

Start Roast / Stop Roast ボタン — 焙煎の開始と終了
ステータスバッジ — 現在の状態（Standby / Roasting...）
1ハゼアラート — 検出時に赤字で「First crack soon!」と表示され、チャイム音が鳴る
リアルタイムグラフ — 上段：ΔH₂O、下段：ΔH₂O変化率（平滑化済み）
下段の縦軸は、ノイズ帯を圧縮しハゼ方向の変化を拡大する非線形スケールです（片対数グラフと同じ原理）。目盛り・ホバー表示・閾値はすべて実測値（g/m³/s）で表示されます
赤い点線＝1ハゼ検出の閾値ライン。グラフの線がこれを越えた瞬間に検出が発火します。閾値を変更してもグラフの形は変わらず、赤線だけが上下します
Sensor Data — 最新のセンサー生データ
Export Roast Data — 焙煎終了後に表示される CSV ダウンロードエリア

3. 焙煎の基本操作

焙煎開始

Settings タブで SSID が正しく設定されていることを確認（API URL が表示されます）
Start Roast ボタンを押す
ステータスが「Roasting...」（緑）に変わり、グラフの時間軸が 0 からリセットされます

投入・チャージの自動検出

Start Roast 後に「投入・チャージの自動検出」が ON の場合、生豆投入待機状態になります。ΔH₂Oの急変動（プラス・マイナスどちらの方向でも設定閾値を超えた場合）を検知すると、自動的に投入タイミングを 0 分にセットしてグラフが開始されます。

焙煎中

グラフがリアルタイムで更新されます（デフォルト 2 秒間隔）
ΔH₂O変化率が閾値を超えると、「First crack soon!」 のアラートが表示されます
初回検出時にチャイム音が鳴ります

1ハゼの確認・訂正

1ハゼを検知すると、グラフ上部に 「1ハゼを検知しました — ハゼですか？」 の確認バーが表示されます。

はい — 1ハゼとして確定します。確定後も焙煎中は「いいえ（取消）」ボタンが残るので、誤検出だった場合はあとから取り消せます
いいえ（取消） — 誤検出として記録を取り消します。その後、次の検知を待ちます
焙煎終了ボタンを押すと訂正バーは閉じます（1ハゼ時刻はグラフ上の赤いマーカーで確認できます）

焙煎終了

Stop Roast ボタンを押す
ステータスが「Standby」に戻ります
画面下部に CSV エクスポートエリアが表示されます

4. 設定パネル（Settings タブ）

サイドバーの Settings タブには、メイン設定と詳細設定があります。

メイン設定

項目	説明
SSID / Host	Coffee Hazel センサーの IP アドレスまたはホスト名。入力例：`192.168.1.10`、`hazel`（自動で `hazel.local` に補完）、`hazel.local`
1st Crack Threshold	1ハゼ検出に使うΔH₂O変化率の閾値（g/m³/s）。デフォルト 0.05
検出開始までの待ち時間（Detection start delay）	焙煎開始から指定分間は 1ハゼ検出を無効化。焙煎初期や排気操作による誤検知を防ぎます。デフォルト 3.0 分
X-axis range	Auto：データに応じて自動拡張 / Fixed：指定した値で固定
Y-axis: ΔH₂O	Auto：データに応じて自動調整 / Fixed：最小値〜最大値を手入力
Y-axis: ΔH₂O変化率	Auto：データに応じて自動調整 / Fixed：最小値〜最大値を手入力（実測値 g/m³/s で指定。軸が非線形のため画面上の見た目位置とは異なります）

投入・チャージの自動検出

項目	説明
自動検出 ON/OFF	ΔH₂Oの急変動から生豆投入を自動判定し、投入を 0 分に揃える
急変動のしきい (g/m³/s)	投入と判定する変化速度の絶対値。プラス・マイナスどちらの急変動も検出

詳細設定（Advanced Settings）

「Advanced Settings」の行をクリックすると展開されます。通常はデフォルト値のままで問題ありません。

項目	デフォルト	説明
Polling interval	2 sec	センサーへのデータ取得間隔
Moving average window	3	変化率計算に使う直近サンプル数
Require 3 consecutive	ON	閾値を 3 回連続で超えたときのみ 1ハゼと判定
Max data points	1200	メモリに保持する最大データ点数
起動時に更新を確認する	ON	新しいバージョンがあれば起動時に通知する（10. アップデートの通知）
変化の強調 (γ)	1.6	変化率グラフの縦軸の強調度。小さな揺れを圧縮し、ハゼ方向の大きな変化を拡大して表示する（1.0 で通常の線形軸）。表示のみの設定で、検出には影響しない。強調の基準は固定値 0.05 で、1ハゼ閾値の設定とは独立

5. 豆プリセット（Bean Preset）

焙煎する豆ごとに設定一式を保存・切り替えできます。

豆の選択

Settings タブ最上部の Bean Preset ドロップダウンから選択します。選択すると、その豆に紐付いた全設定が自動的に読み込まれます。

「Default」は汎用の設定で、特定の豆を選ばない場合に使用します。

新しい豆の登録

ドロップダウン右の 「+」ボタン を押す
入力欄に豆の名前を入力（例：「Ethiopia Yirgacheffe」）
Save を押す

豆の削除

削除したい豆をドロップダウンで選択した状態で、「x」ボタン を押すと削除されます。Default は削除できません。

設定の自動保存

豆を選択した状態で設定を変更すると、変更内容はその豆の設定に自動的に上書き保存されます。明示的な保存操作は不要です。

6. CSV Viewer

過去の焙煎データ（CSV）を読み込み、グラフとして表示する機能です。

使い方

サイドバーの CSV Viewer タブを選択
点線のエリアに CSV ファイルをドラッグ＆ドロップ、またはクリックしてファイルを選択
グラフが表示されます

表示内容

上段グラフ：ΔH₂O（h2o_density）の時系列
下段グラフ：ΔH₂O変化率（slope_smoothed または slope）の時系列
1ハゼ区間：first_crack_flag カラムが 1 の区間を赤い半透明の帯でハイライト

対応する CSV フォーマット

カラム名	用途
`time_min`	時間軸（分）必須
`h2o_density`	ΔH₂O 必須
`slope_smoothed`	平滑化済みΔH₂O変化率（下段グラフ）
`slope`	ΔH₂O変化率（`slope_smoothed` がない場合に使用）
`first_crack_flag`	1ハゼ区間のハイライト表示（0 or 1）

7. スマホ・タブレットからのアクセス

Settings タブの下部に QR コードが表示されています。

スマホ・タブレットを PC と同じ Wi-Fi に接続
QR コードをスキャン（またはその下の URL にアクセス）
ブラウザでリアルタイムグラフを確認できます

QR コードの印刷（シェアロースター向け）

QR コードの下の 「🖨 QRコードを印刷」 リンクから印刷用ページが開きます。右上の印刷ボタンでそのまま印刷できるので、焙煎機のそばに掲示しておけば、誰でもスマホをかざすだけで焙煎グラフを見られます。

PC 側で Coffee Hazel アプリを起動している間のみ接続できます
QR コードの URL は Wi-Fi 環境によって変わることがあるため、印刷はアプリを使う場所で行ってください

スマホでのデータ保存

スマホからも CSV やグラフ画像を保存できます。この場合、保存先フォルダの指定は表示されず、ブラウザのダウンロードとして端末内に保存されます（Android: ダウンロードフォルダ / iPhone: ファイルアプリ）。

8. CSV エクスポート

焙煎終了後にデータを CSV ファイルとして保存できます。

Stop Roast を押すと、画面下部に「Export Roast Data」エリアが表示されます
ファイル名を入力（省略するとタイムスタンプ付きの名前が自動生成されます）
Download CSV ボタンを押す

PC 本体では「保存先フォルダ」に指定したフォルダへ直接保存されます（「フォルダ選択...」で変更可能。設定は記憶されます）。スマホからアクセスしている場合はブラウザのダウンロードとして端末に保存されます。

グラフ画像の保存（PNG / JPG / PDF）

「グラフ画像の保存:」の PNG / JPG / PDF ボタンを押すと、いま画面に表示されているグラフ（1ハゼマーカーなども含めた見た目そのまま）を高解像度の画像として保存できます。

ファイル名は CSV と共通の「ファイル名」欄を使用します（省略時はタイムスタンプ付きの名前）
保存先は CSV と同じです（PC: 保存先フォルダ / スマホ: ブラウザダウンロード）

CSV に含まれるカラム

カラム名	説明
`time_min`	焙煎開始からの経過時間（分）
`h2o_density`	ΔH₂O（g/m³）
`slope`	ΔH₂O変化率の生値（g/m³/s）
`slope_smoothed`	平滑化済みのΔH₂O変化率
`timestamp`	センサーのタイムスタンプ
`temperature1`	センサー 1 温度（°C）
`humidity1`	センサー 1 湿度（%）
`water_vapor_density1`	センサー 1 水蒸気密度（g/m³）
`temperature2`	センサー 2 温度（°C）
`humidity2`	センサー 2 湿度（%）
`water_vapor_density2`	センサー 2 水蒸気密度（g/m³）
`first_crack_flag`	1ハゼ判定フラグ（0 or 1）
`rate_emphasis_gamma`	焙煎時に使用していた表示強調γの値（全行同じ。フィードバック集計用）

9. 設定ファイルの場所

設定はホームディレクトリに自動保存されます。

ファイル	内容
`~/.hazel_settings.json`	グローバル設定（最後に選択した豆、Default の設定値、更新確認の設定）
`~/.hazel_beans.json`	豆ごとの設定（豆名をキーとした JSON）

これらのファイルを削除すると設定がリセットされます。

10. アップデートの通知

起動時に GitHub の最新リリースを確認し、使用中のバージョンより新しい版が公開されていれば、画面上部に通知バーを表示します。

ボタン	動作
ダウンロード	既定のブラウザが開き、使用中の OS・CPU に合った配布ファイル（macOS は Apple Silicon / Intel を自動判別）のダウンロードが始まります。インストールは従来どおり手動です
このバージョンをスキップ	そのバージョンについては以降の起動でも通知しません。さらに新しい版が出れば再び通知されます
閉じる	今回だけ非表示にします。次回の起動時にはまた表示されます

通知バーには 更新内容（リリースノート） がそのまま表示されます。何が変わるのかを確認してからダウンロードしてください。

確認は起動時の1回だけで、焙煎中に通信が発生することはありません。オフラインや GitHub 側の不調時は何も表示せず、起動や動作に影響しません
公開前のドラフトリリースは通知の対象外です
スマホ・タブレットからアクセスしている場合は、その端末のブラウザでダウンロードページが開きます
通知が不要な場合は、詳細設定の 「起動時に更新を確認する」 をオフにしてください

11. トラブルシューティング

（Windows）起動後に画面が表示されない・真っ白になる

WebView2 ランタイムが未導入の可能性があります。Evergreen Bootstrapper をダウンロードして MicrosoftEdgeWebview2Setup.exe を実行し、Coffee Hazel を再起動してください
Windows 11、または Edge が導入済みの Windows 10 では通常このランタイムは標準搭載されています

「API Error」が表示される

Coffee Hazel センサーが起動しているか、PC と同じ Wi-Fi に接続されているか確認してください
SSID / IP アドレスが正しいか確認してください
ブラウザで API URL に直接アクセスして JSON が返るかテストしてください

グラフが更新されない

ステータスを確認してください。Standby の場合は Start Roast を押してください
詳細設定の Polling interval が大きすぎないか確認してください

1ハゼが検出されない

閾値（Threshold）が高すぎる可能性があります。値を下げてみてください
「検出開始までの待ち時間」の設定で、焙煎開始直後の検出が無効化されている可能性があります
「Require 3 consecutive」が ON の場合、瞬間的な超過では検出されません

1ハゼの誤検知が多い

閾値を上げてください
「Require 3 consecutive」を ON にしてください
「検出開始までの待ち時間」を長めに設定してください
Moving average window を大きくすると変化率が平滑化され、ノイズによる誤検知が減ります

投入が自動検出されない

「急変動のしきい」の値が大きすぎる可能性があります。値を下げてみてください
生豆投入時のΔH₂Oの変動が小さい場合は、しきい値を調整してください

音が鳴らない

ブラウザの自動再生ポリシーにより、Start Roast ボタンを押す前に音が再生されない場合があります
ブラウザのタブがミュートになっていないか確認してください

スマホから接続できない

PC とスマホが同じ Wi-Fi ネットワークに接続されていることを確認してください
ファイアウォールがポート 8050 をブロックしていないか確認してください
QR コード下に表示されている URL をスマホのブラウザに直接入力してみてください

バージョン履歴

最新の変更履歴は CHANGELOG.md（各リリースのリリースノート）を参照してください。

バージョン	内容
V2.3.3	起動時のアップデート通知を追加。新しいバージョンがあれば更新内容（リリースノート）とダウンロード先を画面上部に表示
V2.3.2	「検出開始までの待ち時間（旧: Ignore first N min）」を詳細設定からメイン設定へ移動し、名称と説明を分かりやすく変更
V2.3.1	Linux版が起動直後にクラッシュする不具合を修正
V2.3.0	グラフ画像の保存（PNG / JPG / PDF）を追加。QRコード印刷用ページを追加。スマホアクセス時の保存UIを改善。X軸メモリを1分間隔に固定。焙煎終了後は1ハゼ訂正バーを非表示に
V2.2.3	Ubuntu 22.04 で起動できない問題を修正（22.04 / 24.04 両対応に）
V2.2.0	Bluetooth (BLE) 接続モード追加
V2.0.1	ΔH₂O・ΔH₂O変化率に用語統一。投入・チャージ自動検出を急変動（正負両方向）に変更。更新間隔デフォルト 2 秒。アプリアイコン追加。著作権表示追加。Ubuntu 用 `.deb` パッケージを追加
V2.0.2	投入チャージ検出の `poll_sec` 未定義バグ修正。急変動しきい値をスライダーに変更。1ハゼしきい値ラベルを日本語化
V2.0.3	変化率グラフの表示を再設計：強調の基準をハゼ閾値から固定値 0.05 に分離（閾値を変えてもグラフの形が不変に）。縦軸を実測値目盛りの非線形スケールに変更し、軸・ホバー・閾値の数字を実測 g/m³/s に統一。閾値の赤線は変換後の正確な位置に描画。CSV出力に使用γ値を記録（`rate_emphasis_gamma` 列）。投入検出しきい値のデフォルトを 0.3→0.25 に変更

アプリの使い方

Coffee Hazel V2.3.3 — ユーザーマニュアル

目次

1. セットアップ

必要なもの

インストール（macOS）

インストール（Windows）

インストール（Ubuntu / Linux）

.deb パッケージを自分でビルドする場合

ソースから実行する場合

2. 画面構成

左側：サイドバー（タブ切り替え）

右側：メインエリア

3. 焙煎の基本操作

焙煎開始

投入・チャージの自動検出

焙煎中

1ハゼの確認・訂正

焙煎終了

4. 設定パネル（Settings タブ）

メイン設定

投入・チャージの自動検出

詳細設定（Advanced Settings）

5. 豆プリセット（Bean Preset）

豆の選択

新しい豆の登録

豆の削除

設定の自動保存

6. CSV Viewer

使い方

表示内容

対応する CSV フォーマット

7. スマホ・タブレットからのアクセス

QR コードの印刷（シェアロースター向け）

スマホでのデータ保存

8. CSV エクスポート

グラフ画像の保存（PNG / JPG / PDF）

CSV に含まれるカラム

9. 設定ファイルの場所

10. アップデートの通知

11. トラブルシューティング

（Windows）起動後に画面が表示されない・真っ白になる

「API Error」が表示される

グラフが更新されない

1ハゼが検出されない

1ハゼの誤検知が多い

投入が自動検出されない

音が鳴らない

スマホから接続できない

バージョン履歴

`.deb` パッケージを自分でビルドする場合