COFFEE HAZEL ← セットアップガイドへ

アプリの使い方

Coffee Hazel App Manual

このページは manual.md から自動生成されています（2026/09/30 15:00 JST）

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

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

© 2026 SORAMAME LAB INC. All rights reserved.

目次

  1. セットアップ
  2. 画面構成
  3. 焙煎の基本操作
  4. イベントの記録（ボタン・右クリック）
  5. 設定パネル（Settings タブ）
  6. 豆プリセット（Bean Preset）
  7. CSV Viewer
  8. スマホ・タブレットからのアクセス
  9. CSV エクスポート
  10. 設定ファイルの場所
  11. アップデートの通知
  12. トラブルシューティング

1. セットアップ

必要なもの

インストール（macOS）

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

インストール（Windows）

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

インストール（Ubuntu / Linux）

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

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

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

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

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 つのタブがあります。

右側：メインエリア

3. 焙煎の基本操作

待機中の表示

焙煎開始を押していない間も、センサーの値をそのままグラフに流しています（直近10分ぶん）。焙煎前のドラムの状態を確認してから始められます。

焙煎開始

  1. Settings タブで SSID が正しく設定されていることを確認（API URL が表示されます）
  2. 焙煎開始 ボタンを押す
  3. グラフがリセットされ、ステータスが「投入待機中...」に変わります

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

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

検知は移動平均としきい値超えの分だけ遅れるため、検知した時点から平滑化前の変化率を遡って、実際に変化が始まった時刻を逆算しています。区間平均から投入位置を割り出すので、サンプル間隔（既定2秒）より細かい精度で 0 分の位置が決まります。

投入が確定すると、投入前のデータはマイナス側（-1分まで）に表示されます。

焙煎中

焙煎時間と DTR

画面上部のボタンの右に、状態・焙煎時間・DTR が並んで表示されます（本体のスマートフォン画面と同じ並びです）。

表示 待機中 投入待機中 焙煎中 焙煎終了
状態 待機中 投入待機中 焙煎中 焙煎終了
焙煎時間 — --:-- 8:30 計 10:00
DTR — DTR -- DTR -- → DTR 20.0% (2:00) DTR 20.0% (2:00)

DTR (%) = 1ハゼ以降の時間 ÷ 投入からの焙煎時間 × 100

1ハゼの確認・訂正

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

焙煎終了

  1. 焙煎終了 ボタンを押す（「排出・焙煎終了の自動検出」が ON の場合は、豆を出した時点で自動的に終了します。下記参照）
  2. 保存ポップアップが開きます。ファイル名は「豆プリセット名_日付_時刻」の形で自動的に提案されます（プリセットを使っていない場合は hazel_日付_時刻） - 保存 — その名前で CSV を書き出します - キャンセル — 何もせず閉じます。データは残っているので、画面下の書き出しパネルからいつでも保存できます
  3. 焙煎データはそのまま表示され続けるので、記録の追加や見直しができます

排出（焙煎終了）の自動検出

詳細設定の「排出・焙煎終了の自動検出」を ON にすると、豆をドラムから出したときのΔH₂Oの落ち込みから排出を判定し、焙煎を自動で終了します。初期設定はオフです。

判定の条件は次の2つです。

  1. ΔH₂Oが、30秒前までの最大値から設定した割合（初期値 20%）以上下がる
  2. そのまま15秒間、戻らない

排気操作やセンサーのノイズでも一時的に落ちることがありますが、そちらはすぐ戻るため停止しません。逆に、豆を出した後はΔH₂Oが戻らないので確実に判定できます。

4. イベントの記録（ボタン・右クリック）

排気操作や2ハゼなど、自動では判定できない出来事を手で記録できます。記録のしかたは 2 通りあります。

ボタンで「今」を記録する

「焙煎開始／焙煎終了」の下に 投入 / 排気操作 / 1ハゼ / 2ハゼ / 排出 / 取消 のボタンがあります。押した瞬間の時刻で記録されます。焙煎中（投入待機中を含む）だけ押せます。

右クリックで時刻を選んで記録する

過去の時刻に置きたいときや、焙煎終了後に訂正したいときは、グラフ上を右クリック（スマホ・タブレットは長押し）すると、その位置の時刻でメニューが開きます。

この位置に記録  4:51
─────────────────
投入
1ハゼ
排気操作
2ハゼ
排出
─────────────────
直前の記録を取消

投入・1ハゼの手動修正

自動検出が外れたときの保険として、同じメニューから 投入 と 1ハゼ も指定できます。

CSV への記録

書き出した CSV には event 列が追加され、その時刻の行に種類（damper / crack2 / drop）が入ります。CSV Viewer で読み込むと、記録したイベントもグラフに重ねて表示されます。

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

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

メイン設定

項目 説明
SSID / Host Coffee Hazel センサーの IP アドレスまたはホスト名。入力例：192.168.1.10、hazel（自動で hazel.local に補完）、hazel.local。スマホ・タブレットからは変更できません（表示のみ。PC側の計測先が切り替わってしまうため）
1ハゼ検出しきい値 1ハゼ検出に使うΔH₂O変化率の閾値（g/m³/s）。デフォルト 0.05。スライダーはよく使う 0〜0.1 の範囲が全体の45%を占める目盛りになっており、細かい調整がしやすくなっています。右の欄に数値を直接入力することもできます（0.001刻み）
検出開始までの待ち時間（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 で指定。軸が非線形のため画面上の見た目位置とは異なります）

設定のコツ（1ハゼを正しく判定するために）

1ハゼを正しく判定できるかどうかは、「検出開始までの待ち時間」と「1ハゼ検出しきい値」の2つでほぼ決まります。

検出開始までの待ち時間

排気操作（ファンの操作）を行うと排気中の水蒸気が大きく動くため、1ハゼと誤判定する原因になります。

1ハゼ検出しきい値

1ハゼで豆から水蒸気が放出されると、ΔH₂Oの上昇率（ΔH₂O変化率）が上がります。この変化率が、しきい値として設定した値を超えたときに1ハゼと判定します。

豆プリセットと CSV ガイドで再現性を高める

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

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

排出・焙煎終了の自動検出

項目 デフォルト 説明
自動検出 ON/OFF OFF ΔH₂Oの落ち込みから排出を判定し、焙煎を自動終了する（3. 焙煎の基本操作）
排出と判定する落ち込み (%) 20% 30秒前までの最大値から、この割合まで下がった状態が15秒続くと排出と判定。過去の焙煎9本で検証したところ、20%では焙煎途中での誤検出はゼロ、15%まで下げると5本が途中で止まったため、設定できる下限は15%です。小さくすると早く反応しますが、排気操作でも止まりやすくなります

詳細設定（Advanced Settings）

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

項目 デフォルト 説明
Polling interval 2 sec センサーへのデータ取得間隔
Moving average window 3 変化率計算に使う直近サンプル数
Require 3 consecutive ON 閾値を 3 回連続で超えたときのみ 1ハゼと判定
Max data points 1200 メモリに保持する最大データ点数
起動時に更新を確認する ON 新しいバージョンがあれば起動時に通知する（11. アップデートの通知）
変化率グラフの強調 しきい値の前後を強調（標準） 下記参照

変化率グラフの強調

1ハゼの判定に必要な範囲を拡大して見やすくする設定です。表示だけの設定で、検出結果は変わりません。

選択肢 内容
オフ 測定値をそのまま表示
しきい値の前後を強調（標準） 1ハゼ判定ラインの前後を拡大し、排気操作などの大きな変動は圧縮して表示（初期設定）
しきい値の前後を強調（強め） 標準よりさらに強く拡大

拡大の中心は1ハゼ検出しきい値です。ハゼの山が赤い判定ラインに全く近づかない場合は、しきい値の設定がずれているサインとして読み取れます。

なお、縦軸の目盛りとカーソル表示の数値は、どの方式でも実測値（g/m³/s）のままです。

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

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

豆の選択

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

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

新しい豆の登録

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

いまの設定がそのまま新しい豆に引き継がれます。 調整した内容を別名で残したいときにも使えます。

設定の保存（重要）

名前を付けた豆プリセットは、設定を変えても自動では保存されません。

プリセット名の下に状態が表示されます。

表示 意味
✓ 保存済み 保存内容と一致しています
● 未保存の変更があります 変更しましたが、まだプリセットには書き込まれていません

未保存のときは ［保存］［取り消し］ のボタンが出ます。

変更はその場の焙煎にはすぐ反映されるので、その日だけの調整でプロフィールを汚さずに済みます。 手で元の値に戻した場合は、自動的に「✓ 保存済み」の表示に戻ります。

「Default」を選んでいるときは従来どおり自動保存です（下書きとして使えます）。

豆の削除・整理

ドロップダウン右の ［管理］ボタン を押すと、登録済みの豆が一覧で表示されます。チェックを付けて ［選択したものを削除］ で、複数まとめて削除できます。選択中の豆を削除した場合は Default に戻ります。

7. CSV Viewer

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

使い方

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

表示内容

焙煎中のグラフに重ねて表示する（CSV ガイド）

CSV Viewer で読み込んだ焙煎データは、メイン画面の焙煎グラフの背景に薄い色で重ねて表示されます。前回のカーブを下敷きにしながら焙煎を進められるので、同じ豆を繰り返し焙煎するときの目安になります。

対応する CSV フォーマット

カラム名 用途
time_min 時間軸（分）必須
h2o_density ΔH₂O 必須
slope_smoothed 平滑化済みΔH₂O変化率（下段グラフ）
slope ΔH₂O変化率（slope_smoothed がない場合に使用）
first_crack_flag 1ハゼ区間のハイライト表示（0 or 1）
event 記録したイベント（damper＝排気操作 / crack2＝2ハゼ / drop＝排出）

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

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

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

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

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

Artisan・他の端末との同時利用

COFFEE HAZEL 本体には、複数の接続先が同時につながっても問題ありません。次の組み合わせを同時に使えます。

どれか1つを使うために他を終了する必要はありません。用途に応じて、たとえば「記録は Artisan、1ハゼの自動検知はデスクトップアプリ、焙煎機のそばではスマホ」といった使い分けができます。

スマホでのデータ保存

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

9. CSV エクスポート

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

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

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

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

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

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 焙煎時に使用していた表示強調γの値（全行同じ。フィードバック集計用）

10. 設定ファイルの場所

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

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

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

11. アップデートの通知

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

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

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

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

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

「API Error」が表示される

グラフが更新されない

1ハゼが検出されない

1ハゼの誤検知が多い

投入が自動検出されない

音が鳴らない

スマホから接続できない

バージョン履歴

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

バージョン 内容
V2.3.10 「排出」を記録してから焙煎終了ボタンを押すと、終わりの線が「排出」「上げ」の2本になる不具合を修正（線は「排出 mm:ss」の1本に）。手動の「排出」のあとに自動検出が働いても2本目を足さない
V2.3.9 1ハゼの通知音を大音量のアラームに（音量最大・矩形波・3回、確認まで 10 秒ごとに鳴り直す）。本体のスマートフォン画面（ファームウェア V2.4.3）と同じ音
V2.3.8 イベント入力のボタン（投入 / 排気操作 / 1ハゼ / 2ハゼ / 排出 / 取消）を復活。焙煎中は「焙煎開始」を押せないように。複数のブラウザを同時に開いていると右クリック／ボタンの操作が繰り返し適用される不具合を修正
V2.3.7 DTR と焙煎時間の終わりを、手動で記録した「排出」の時刻に合わせた（排出から焙煎終了ボタンまでの時間が水増しされていた）
V2.3.6 排出（焙煎終了）の自動検出を追加（ΔH₂Oの落ち込みから判定。オン／オフとしきい値を設定可能、初期設定はオフ）。DTR（1ハゼ以降の時間 ÷ 焙煎時間）の自動計算と表示を追加。配布版でグラフの右クリックメニューが開かない不具合を修正
V2.3.5 変化率の計算を、機器が値を更新した実時間で割るように修正（Bluetooth接続＋旧ファームでの過大評価とノコギリ波を解消）
V2.3.4 グラフの右クリックでイベント（排気操作・2ハゼ・排出）を記録。投入・1ハゼの手動修正。待機中もグラフ表示。変化率グラフの強調方式を刷新。しきい値スライダーを微調整しやすく。豆プリセットを明示保存に変更し、管理画面を追加。時刻表示を mm:ss に統一。基調色をスカイブルー＋オレンジに。日本語入力とスマホ操作の不具合を修正
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 に変更