StackChan StreetPass

ESP32 Arduino firmware に組み込める、Stack-chan 互換の BLE すれ違い通信ライブラリです。

近くにある対応デバイス同士が BLE advertisement で互いを見つけ、GATT でプロフィールカードを交換します。受け取ったカードはデバイス内に履歴として保存され、USB Serial などから JSON API で読み出せます。

English documentation is available in README.en.md.

できること

• Stack-chan firmware と互換の StreetPass protocol v1
• BLE advertisement / scan / GATT server / GATT client
• 自分のプロフィール保存
• 最大 30 件のすれ違い履歴保存
• streetpass.profile.* / streetpass.encounters.* / streetpass.time.* JSON API
• firmware 側の都合で BLE を一時停止する callback
• すれ違い受信時に UI や通知を更新する callback
• Python からプロフィール変更・履歴取得できるサンプルツール
• M5Stack Core2 / Stack-chan CoreS3 用の動作確認 firmware

ディレクトリ構成

src/
  StackChanStreetPass.h          firmware が組み込む公開 facade。
  StackChanStreetPass.cpp        BLE transport、callback、高レベル制御。
  StreetPassController.h         profile、record、JSON API のデータモデル。
  StreetPassController.cpp       保存、merge/eviction、JSON command 処理。
  StreetPassProtocol.h           BLE UUID と protocol version。

examples/
  basic_device/                  最小 ESP32 example。
  stackchan_core2_test/          M5Stack Core2 用テスト firmware。
  stackchan_cores3_test/         Stack-chan/CoreS3 用テスト firmware。

tools/
  set_profile.py                 Serial JSON でプロフィールを変更する。
  get_profile.py                 Serial JSON で現在プロフィールを読む。
  get_encounters.py              Serial JSON で履歴を読む。

docs/
  architecture.ja.md             設計構成と実装境界。
  protocol.ja.md                 BLE / JSON API 仕様。
  tools.ja.md                    Python tool の使い方。
  examples.ja.md                 build、upload、テスト firmware の使い方。

  architecture.en.md             English architecture document.
  protocol.en.md                 English protocol document.
  tools.en.md                    English Python tools document.
  examples.en.md                 English examples document.

最小実装例

#include <StackChanStreetPass.h>

StackChanStreetPass streetpass;

void setup() {
  Serial.begin(115200);

  StackChanStreetPassConfig config;
  config.deviceName = "My Firmware StreetPass";
  config.source = "my-firmware";

  streetpass.begin(config);
}

void loop() {
  streetpass.update(millis());
}

音声再生、録音、カメラ処理など BLE を止めたいタイミングがある firmware では setBusyCallback() を使います。すれ違い受信時に UI や通知を更新したい場合は setEncounterCallback() を使います。

依存ライブラリ

• ESP32 Arduino framework
• ArduinoJson
• NimBLE-Arduino
• ESP32 Arduino の Preferences / LittleFS

M5Stack examples では追加で以下を使います。

• M5Unified

Example のビルド

Stack-chan/CoreS3:

cd examples/stackchan_cores3_test
pio run

M5Stack Core2:

cd examples/stackchan_core2_test
pio run

接続中のデバイスへ upload:

pio device list
pio run -t upload --upload-port /dev/cu.xxxxx

Core2 / CoreS3 test firmware の詳細は docs/examples.ja.md を参照してください。

Python tools

プロフィール変更:

cd stackchan-streetpass
python3 tools/set_profile.py \
  --port /dev/cu.usbmodem101 \
  --name "Stack-chan CoreS3" \
  --message "Hello from Stack-chan"

履歴取得:

python3 tools/get_encounters.py --port /dev/cu.usbmodem101

pyserial が入っていれば通常の python3 でも動きます。各 tool の役割と返り値の見方は docs/tools.ja.md を参照してください。

ドキュメント

日本語:

• docs/architecture.ja.md: 実装構成と設計境界。
• docs/protocol.ja.md: BLE UUID、advertisement、Public Card、JSON API、履歴仕様。
• docs/tools.ja.md: Python tools と serial command。
• docs/examples.ja.md: Core2 / CoreS3 test firmware の build と操作。

English:

• README.en.md
• docs/architecture.en.md
• docs/protocol.en.md
• docs/tools.en.md
• docs/examples.en.md

互換性方針

このライブラリは、Stack-chan StreetPass protocol v1 の protocol / JSON API / 保存形式を固定し、 複数の firmware 実装が同じすれ違いネットワークに参加できるようにしています。

• 同じ BLE service / characteristic UUID
• 同じ Public Card JSON field
• 同じ JSON command 名
• 同じ Preferences namespace と LittleFS records path
• 同じ履歴 merge / eviction behavior

これは、別々の人が作った firmware でも同じすれ違いの仕組みに参加できるようにするためです。

ライセンス

この repository のソースコードは MIT License です。詳細は LICENSE を参照してください。

依存ライブラリの license は THIRD_PARTY_NOTICES.md にまとめています。