|
1 | | -# Cast Protocol |
| 1 | +# CAST Protocol |
2 | 2 |
|
3 | | -ESP-IDF component for cast protocol (ESP32-S3). |
| 3 | +**CAST (Camera Adaptive Strategy Transmission)** は、ESP32-S3 向けの画像伝送ミドルウェアです。 |
| 4 | +カメラで撮影した画像フレームを MTU に合わせてチャンク分割・送信し、受信側で順不同のチャンクを組み立てて元のフレームを復元します。 |
4 | 5 |
|
5 | | -## Requirements |
| 6 | +トランスポート層（ESP-NOW, Wi-Fi など）は抽象化されており、`cast_transport_interface_t` を実装するだけで任意の通信方式に対応できます。 |
6 | 7 |
|
7 | | -- ESP-IDF v5.0 or later |
| 8 | +## Features |
8 | 9 |
|
9 | | -## Installation |
| 10 | +- 画像フレームの MTU ベース自動分割送信 (Chunker) |
| 11 | +- 順不同チャンクの受信・組み立て (Reassembler) |
| 12 | +- JPEG / RGB565 / Grayscale フォーマット対応 |
| 13 | +- トランスポート層の抽象化 (`cast_transport_interface_t`) |
| 14 | +- バッファ管理はミドルウェア側で完結（コールバックで通知） |
10 | 15 |
|
11 | | -Add the dependency to your project's `idf_component.yml`: |
| 16 | +## Requirements |
12 | 17 |
|
13 | | -```yaml |
14 | | -dependencies: |
15 | | - cast_protocol: |
16 | | - version: "*" |
17 | | -``` |
| 18 | +- ESP-IDF v5.4 or later |
| 19 | +- Target: ESP32-S3 |
18 | 20 |
|
19 | | -Then run: |
| 21 | +## Packet Structure |
20 | 22 |
|
21 | | -```bash |
22 | | -idf.py reconfigure |
23 | 23 | ``` |
24 | | - |
25 | | -## Usage |
26 | | - |
27 | | -```c |
28 | | -#include "cast_protocol.h" |
29 | | - |
30 | | -void app_main(void) |
31 | | -{ |
32 | | - ESP_ERROR_CHECK(cast_protocol_init()); |
33 | | - |
34 | | - // Your application code here |
35 | | - |
36 | | - ESP_ERROR_CHECK(cast_protocol_deinit()); |
37 | | -} |
| 24 | ++-------+----------+---------+ |
| 25 | +| Header (15B) | Payload | CRC (2B) | |
| 26 | ++-------+----------+---------+ |
38 | 27 | ``` |
39 | 28 |
|
40 | | -## Component Development Guide |
41 | | -
|
42 | | -### バージョニング |
43 | | -
|
44 | | -`idf_component.yml` の `version` はセマンティックバージョニング (`major.minor.patch`) に従います。 |
45 | | -レジストリに公開されたバージョンは**上書き不可**なので、変更するたびにバージョンを上げる必要があります。 |
46 | | -
|
47 | | -依存側で使えるバージョン制約: |
| 29 | +ヘッダには magic byte, パケットタイプ, フォーマット, フレームID, チャンク番号, 総チャンク数, 最大ペイロード長, ペイロード長が含まれます。 |
48 | 30 |
|
49 | | -| 構文 | 意味 | 例 | |
50 | | -|---|---|---| |
51 | | -| `*` | 任意のバージョン | `*` | |
52 | | -| `>=`, `<` 等 | 比較演算 | `>=1.0.0` | |
53 | | -| `^` (caret) | 最左の非ゼロ桁を固定 | `^1.2.3` = `>=1.2.3,<2.0.0` | |
54 | | -| `~` (tilde) | パッチレベルのみ変動 | `~1.2.3` = `>=1.2.3,<1.3.0` | |
55 | | -
|
56 | | -注意: `^0.x.y` は `>=0.0.0,<1.0.0` ではなく、マイナーバージョンで固定されます (`^0.2.3` = `>=0.2.3,<0.3.0`)。 |
57 | | -
|
58 | | -### 公開に必要なファイル |
59 | | -
|
60 | | -レジストリへの公開には最低限以下が必要です: |
| 31 | +## Usage |
61 | 32 |
|
62 | | -- `idf_component.yml` (`version` フィールド必須) |
63 | | -- `LICENSE` または `LICENSE.txt` |
64 | | -- `README.md` |
| 33 | +### Sender (Chunker) |
65 | 34 |
|
66 | | -### idf_component.yml の主なフィールド |
| 35 | +```c |
| 36 | +#include "cast_protocol.h" |
67 | 37 |
|
68 | | -```yaml |
69 | | -version: "1.0.0" # 必須 |
70 | | -description: "My component" |
71 | | -license: "MIT" # SPDX 識別子 |
72 | | -url: "https://github.com/..." |
73 | | -repository: "https://github.com/....git" |
74 | | -targets: # 省略すると全ターゲット対応 |
75 | | - - esp32s3 |
76 | | -dependencies: |
77 | | - idf: |
78 | | - version: ">=5.0.0" |
79 | | - espressif/button: # namespace/name 形式 |
80 | | - version: "^3.0.0" |
| 38 | +// トランスポートインタフェースを実装 |
| 39 | +cast_transport_interface_t transport = { |
| 40 | + .send = my_send, |
| 41 | + .get_mtu = my_get_mtu, |
| 42 | + .get_rssi = my_get_rssi, |
| 43 | + .is_connected = my_is_connected, |
| 44 | + .is_ready = my_is_ready, |
| 45 | + .set_recv_callback = my_set_recv_callback, |
| 46 | +}; |
| 47 | + |
| 48 | +// フレーム送信 |
| 49 | +esp_err_t err = cast_send_frame(jpeg_buf, jpeg_len, CAST_FMT_JPEG, &transport); |
81 | 50 | ``` |
82 | 51 |
|
83 | | -- `path:` や `git:` による依存は**公開時に使用不可**（ローカル開発専用） |
84 | | -- `targets` を省略すると全チップ対応として扱われます |
85 | | - |
86 | | -### namespace |
87 | | - |
88 | | -- レジストリ上のコンポーネントは `namespace/component_name` で識別されます |
89 | | -- namespace を省略すると `espressif` がデフォルトになります |
90 | | -- GitHub ログイン時にユーザー名と同名の namespace が自動作成されます |
| 52 | +### Receiver (Reassembler) |
91 | 53 |
|
92 | | -### examples ディレクトリ |
| 54 | +```c |
| 55 | +#include "cast_protocol.h" |
93 | 56 |
|
94 | | -- `examples/` 配下の各プロジェクトはレジストリ上で個別にダウンロード可能になります |
95 | | -- 各 example は**自己完結**している必要があります（example 外のファイルに依存しない） |
96 | | -- example の `idf_component.yml` では `override_path` でローカル開発時に親コンポーネントを参照します: |
| 57 | +// フレーム完成時のコールバック |
| 58 | +// data はコールバックから戻った後にミドルウェアが解放する |
| 59 | +// 保持する場合はコールバック内でコピーすること |
| 60 | +void on_frame_ready(const uint8_t *data, size_t len, cast_image_format_t fmt) { |
| 61 | + // data を表示・保存など |
| 62 | +} |
97 | 63 |
|
98 | | -```yaml |
99 | | -dependencies: |
100 | | - my_namespace/my_component: |
101 | | - version: "*" |
102 | | - override_path: "../../" |
| 64 | +// 受信側の初期化 |
| 65 | +esp_err_t err = cast_init_receiver(&transport, on_frame_ready); |
103 | 66 | ``` |
104 | 67 |
|
105 | | -- example の `CMakeLists.txt` で `EXTRA_COMPONENT_DIRS` を使ってはいけません（レジストリからダウンロードした場合に壊れます） |
106 | | - |
107 | | -### 公開方法 |
108 | | - |
109 | | -```bash |
110 | | -# パッケージの確認（アップロードせずアーカイブ作成） |
111 | | -compote component pack --name cast_protocol |
112 | | -
|
113 | | -# アップロード |
114 | | -compote component upload --name cast_protocol --namespace my_namespace |
115 | | -``` |
| 68 | +## API |
116 | 69 |
|
117 | | -CI/CD では環境変数 `IDF_COMPONENT_API_TOKEN` を設定するか、GitHub Actions の OIDC を利用できます。 |
| 70 | +| Function | Description | |
| 71 | +|---|---| |
| 72 | +| `cast_send_frame()` | 画像フレームをチャンク分割して送信 | |
| 73 | +| `cast_init_receiver()` | 受信側を初期化しコールバックを登録 | |
| 74 | +| `cast_reassembler_reset()` | 受信中のフレーム組み立てをリセット | |
118 | 75 |
|
119 | 76 | ## License |
120 | 77 |
|
|
0 commit comments