# ポケット歳時記 — QPad プロトタイプ

QPad (Seeed XIAO RP2040 + SSD1306 OLED + 6タッチパッド) を十字キーにして、
**七十二候 × 7分類 = 504マス**の歳時記を歩くデバイス。歩いた軌跡がそのまま
**円環の曼荼羅アート**と、採集した季語の**フラッシュカード**になる。

- 横軸 = 七十二候（立春 → 大寒） … 左右で「時間を歩く」
- 縦軸 = 季語の7分類（時候／天文／地理／生活／行事／動物／植物） … 上下で「見る角度を変える」

## いま動くもの

`prototype.html` … 実機を組む前の**ブラウザ・シミュレーション**。ダブルクリックで開く。

- 6パッド（画面のボタン or キーボード）で 504マスを移動
- OLED を再現：中央に季語を大きく、四辺に隣のマスを薄く覗かせる（スライドアニメ付き）
- **ズーム軸**（場所 ← 語 → 説明）：`q0 タップ`=説明（寄る）、`q5`=場所＝現在地マップ（引く）
- **採集**：`q0 長押し(0.4秒)` → 朱印＋フラッシュカード追加
- 右パネル：**曼荼羅アート**／**フラッシュカード**、そして **人の地図／機械の地図** の切替
  （同じ語を 人＝モノの種類／機械＝意味 で並べ替え。候名が人では一輪に密集→機械では主題へ散る）
- 「デモ散歩」ボタンで一年を一巡りしてアートを即プレビュー

デバイス操作: `← →` 候を歩く／`↑ ↓` 分類／`i` 説明・`o` 場所・`Space` 採集。
PC側: 右上ボタンで 人／機械 の地図を切替。カード画面では `← →` めくり、クリックで裏返す。

### 三人の分類者（コンセプト）
同じ季語集合を **人（伝統の歳時記）／機械（意味で再編）／あなた（歩いた軌跡）** の3通りで並べ、
その違い自体を作品にする。デバイスは「人の地図」を歩く窓。機械との比較は PC 側で。

## ファイル

| file | 役割 |
|---|---|
| `data/kigo.json` | **単一ソース・オブ・トゥルース**：72候 + 7分類 + 季語オーバーレイ |
| `tools/make_font.py` | `kigo.json` → 実機ヘッダ + `kigo-data.js` + 検証PNG を生成 |
| `tools/add_machine_cats.py` | 「機械の分類」(意味ベース)を `kigo.json` に付与 |
| `prototype.html` | ブラウザで動く全体プロトタイプ（QPad + アート + カード） |
| `kigo-data.js`   | ↑プロトタイプ用（`make_font.py` が `kigo.json` から**自動生成**） |
| `firmware/kigo_font.h` | 使う文字だけの 32px明朝(漢字) / 16px太ゴシック(かな・ステータス) ビットマップ **[生成物]** |
| `firmware/kigo_table.h` | 72候 + 分類オーバーレイのセル表 **[生成物]** |
| `firmware/kigo_min/kigo_min.ino` | 関門テスト：72候を 32px で自動送り表示 |
| `firmware/kigo_pad/kigo_pad.ino` | **本体ファーム**：タッチで移動/ズーム/採集、語・説明・場所ビュー、LittleFS保存、シリアル連携 |
| `操作.md` | ボタンで何が出るか（やさしい版） |
| `tools/preview.png` / `tools/sim_device.png` | 生成ビットマップから描き戻した確認画像 |

## データ構造（`data/kigo.json`）

- `ko[72]` … 七十二候 `[候名, 読み]`（時候の行を自動生成）
- `overlay["col-row"]` … 分類マスに置く季語 `{k,y,d,h,a}`（空マスは `──`）
- `mcats[7]` / `ko_mcat[72]` / overlay の `m` … 機械の分類（意味ベース。人の7分類と対比）
- 俳句 `h` は出典の確かな著名句のみ。不確かなものは空にしてある。
- **編集はここだけ。** その後 `python3 tools/make_font.py` で全生成物とプロトタイプ用データを作り直す。

## 実機フォント生成（Step 1・完了）

```bash
pip install Pillow
python3 tools/make_font.py          # 既定: 明朝(32px) + 太ゴシック(16px)
# 別フォント: --font 明朝.otf --font16 ゴシック.otf
```

- 漢字209字＋かな104字で **約29KB**。RP2040 の 2MB フラッシュには誤差。
- 32px は明朝で見出しを美しく、16px は太ゴシックで潰れず読める（明朝は小サイズで線が消える）。
- `kigo_min.ino` を XIAO RP2040 に書き込むと、七十二候が 2.5秒ごとに 32px で切り替わる
  （＝UTF-8デコード＋二分探索＋ビットマップ描画が全72候で動く確認）。
- macOS の生成結果は `tools/preview.png` で目視確認できる。

## 次の段（実機へ）

- [x] **Step 1** データ＋フォント生成、OLED に漢字を 32px 表示（`make_font.py` / `kigo_min.ino`）
- [x] **Step 2〜3** 本体ファーム `kigo_pad.ino`：移動・ズーム(語/説明/場所)・q0長押し採集・LittleFS保存・シリアル
      （glyph/layout はヘッダに対して検証済み。**実機での要確認**：①ピン番号と各パッド位置 ②タッチ計測を Quentin の `test_touch` に差し替え）
- [ ] **Step 4** ドック時に **Web Serial**（`HELLO/DUMP/SAVED/CLR`）で吸い出し、PC で同じアート／カードを描画
- [ ] **Step 5** アートを SVG 書き出し → CBA のプロッタ／ビニールカッターで掛け軸に

### 実機に載せる手順（kigo_pad）
1. `python3 tools/make_font.py` で `firmware/kigo_font.h` / `kigo_table.h` を生成（`kigo_pad/` から見えるよう同梱）。
2. Arduino IDE: ボード=Seeed XIAO RP2040、**USB Stack=Adafruit TinyUSB**、ライブラリ Adafruit SSD1306 / GFX。
3. `kigo_pad.ino` 冒頭の **`PAD_PIN[]` を QPad の回路図で確認**。タッチが不安定なら `readPadRaw()` を Quentin の `test_touch` ルーチンに差し替え。
4. 書き込み。起動時は**指を触れずに**（キャリブレーションのため）。

## 実機の注意（設計メモより）

- USB Stack を **Adafruit TinyUSB** に（LittleFS + Serial 同居のため）。
- OLED の 1×4 ヘッダは片持ち。**下を押すと銅箔が剥がれる**ので筐体で支える。
- 静電容量パッドはドリフトする → 起動時キャリブレーション＋非接触時のベースライン追従。
- q0 保存の誤爆対策：長押し＋保存後デッドタイム。