diff --git a/docs/README.md b/docs/README.md index edee99d0c93..1b483b6b625 100644 --- a/docs/README.md +++ b/docs/README.md @@ -63,7 +63,7 @@ smalruby3-editor の機能ドキュメントは **ユーザーストーリー単 | [`extension-boost/`](extension-boost/) (`defaultHidden: true`) | ⬆️ そのまま | ✅ | | [`extension-wedo2/`](extension-wedo2/) (`defaultHidden: true`) | ⬆️ そのまま | ✅ | | [`extension-mesh-v2/`](extension-mesh-v2/) | 🆕 独自 | ✅ | -| [`extension-smalrubot-s1/`](extension-smalrubot-s1/) | 🆕 独自 | ✅ | +| [`extension-smalrubot-s1/`](extension-smalrubot-s1/)(アーテックロボ・Studuino 基板/旧 スモウルボットS1) | 🆕 独自 | ✅ | | [`extension-koshien/`](extension-koshien/) | 🆕 独自 | ✅ | | [`extension-smalruby-ruby/`](extension-smalruby-ruby/) | 🆕 独自 | ✅ | | [`extension-tm2scratch/`](extension-tm2scratch/) | 🆕 独自 | ✅ | diff --git a/docs/extension-smalrubot-s1/README.md b/docs/extension-smalrubot-s1/README.md index 4aae19cb080..81ad762498f 100644 --- a/docs/extension-smalrubot-s1/README.md +++ b/docs/extension-smalrubot-s1/README.md @@ -1,64 +1,387 @@ -# 拡張機能: Smalrubot S1 +# 拡張機能: アーテックロボ/旧 スモウルボットS1 > **🆕 Smalruby 独自** — upstream に存在しない、Smalruby のために新規追加された拡張機能 - **Smalruby ランタイム対応**: ❌(smalruby3 gem は未対応。WebSerial API 経由でハードウェアと通信するためブラウザ専用) - **デフォルト表示**: ✅(拡張機能ライブラリにデフォルトで表示される) +> **いまの状態とこれから**: この拡張機能は、**同じ拡張機能のまま「アーテックロボ」の名前に変えた**(前の名前は「スモウルボットS1」。2027-11-30 までは前の名前のカードも残す。下の「移行期間(前の名前のカード)」)。 +> ブロックの表示は一般的な名前にし、実機が無くても動かせる **練習用の基板**(VM の中のしくみと、ステージの横のパネル)を入れた。 +> このページは、いまの挙動と、リニューアルで決まった方針の両方を書く。 +> 見分けがつくように、まだ実装していないことには **🚧 これから** と付ける(印の無いことは、いまの挙動)。 + ## 概要 -**Smalrubot S1**(Studuino ベースの教育用ロボット)を Smalruby から制御する拡張機能。Web Serial API を使ってブラウザから USB 経由でロボットと通信し、モーター・サーボ・LED・センサを操作する。 +株式会社アーテックのロボットキット **アーテックロボ(ArtecRobo)** の制御基板 **Studuino®(スタディーノ)** を Smalruby から制御する拡張機能(前の名前は、この基板を使ったロボット「スモウルボットS1」から取った「スモウルボットS1」)。Web Serial API を使ってブラウザから USB 経由で基板と通信し、DC モーター・サーボモーター・LED・センサーを操作する。 + +ファームウェアの書き込みも内蔵(**WebSerial STK500v1 実装**、`smalrubot-firmware-flasher.js`)しており、初回利用時にブラウザから基板へファームウェアを転送できる(macOS は PL2303 Serial Driver が別途必要)。 + +### リニューアルのねらい -ファームウェアの書き込みも内蔵(**WebSerial STK500v1 実装**、`smalrubot-firmware-flasher.js`)しており、初回利用時にブラウザからロボットへファームウェアを転送できる(macOS は PL2303 Serial Driver が別途必要)。 +- 中学校技術・家庭科の「計測・制御」の授業で、**アーテックロボで授業ができる** と先生に伝わるようにする(スモウルボットは名前が知られていない)。 +- 教科書は「光センサー」「仕事を行う部分」のような一般的な言葉で書かれているので、ブロックの表示も一般的な名前にする(いまは「左のセンサー」のようなロボットの部品の名前)。 +- 実機がつながっていないと、センサーの値は 0 のままで、LED・モーター・サーボの命令は何もしない。そのため、2 人で 1 台・自宅・欠席の補習では進められず、レッスンの「できた」の判定もできない。これを **練習用の基板** で解決する。 ## ユーザーストーリー -- **Smalrubot S1 を購入した小学生**として、Smalruby のブロックでロボットを動かしたい +- **アーテックロボ(スモウルボットS1)を持っている小学生・中学生**として、Smalruby のブロックでロボットを動かしたい +- **「計測・制御」を教える先生**として、教科書と同じ言葉(光センサー、DC モーターなど)で Studuino を扱わせたい +- **基板が足りない教室・自宅で学ぶ生徒**として、実機が無くても練習用の基板でプログラムを動かして確かめたい(センサーの値はパネルのスライダーとボタンで変える) - **教師**として、複数台のロボットを生徒それぞれに渡して、教室全体でロボットプログラミングをさせたい - **保護者**として、子どもが自分のノート PC から直接ロボットを動かせる(追加アプリのインストール不要)状態にしたい - **初めて使う子**として、自分のロボットにファームウェアを書き込む手順を Smalruby の中で完結させたい +## 名前の変更と互換の方針 + +**同じ拡張機能のまま、表示の名前だけを「アーテックロボ」にした**。前の作品(sb3・Ruby)はそのまま開けて、そのまま動く。 + +### キットと基板の呼び分け + +中学校の教員用テキスト「計測と制御キットB」に合わせて、**キット全体を「アーテックロボ(ArtecRobo)」、制御基板を「Studuino(スタディーノ)」** と呼び分ける。 + +| 呼び名 | 使うところ | +|---|---| +| **アーテックロボ**(英語は ArtecRobo。ラベルはすべてこの名前にし、Studuino の名前はカードの説明に書く) | 拡張機能の名前(ライブラリのカード・ブロックのカテゴリ・メニューバー・接続モーダルの見出し)、紹介ページ。名前の後ろに基板の名前を添えて、「Studuino で授業ができる」と先生に伝わるようにする | +| **アーテックロボ** | Ruby タブのふりがな(`studuino` の上に出る名前。短いままにする) | +| **Studuino**(スタディーノ) | 基板のこと: 接続の手順の文・ファームウェアのモーダル・練習用の基板のパネル・カードの説明文(「アーテックロボの Studuino 基板」) | + +Ruby の書き方は `studuino.` のまま(下の「Ruby の書き方」)。スモウルビーのふりがなは読みではなく意味を書くので、`studuino` の上には「アーテックロボ」と出る。 + +### 変えたもの + +| 対象 | 前 | いま | +|---|---|---| +| 拡張機能の名前(ライブラリ・カテゴリ・メニューバー・接続モーダルの見出し) | スモウルボットS1 | **アーテックロボ**(カテゴリ・メニューバーも同じ。ひらがなの表示は「アーテックロボ」、英語は「ArtecRobo」) | +| 基板を指す文(接続モーダルの文・ファームウェアのモーダル・練習用の基板のパネル) | スモウルボットS1 | **Studuino**(ひらがなの表示の文の中は「スタディーノ」) | +| ライブラリの絵(カード・接続モーダル・カテゴリの絵) | スモウルボットS1 のロボットの写真 | **自分たちで用意した基板の絵**(アーテック社の写真・ロゴは使わない。下の「ライブラリの絵と商標の表記」) | +| ライブラリのカードの説明 | スモウルボットS1を制御する。 | アーテック社の表記に合わせた紹介と、登録商標の一文(下の「ライブラリの絵と商標の表記」) | +| Ruby タブのふりがな(`studuino` / `smalrubot_s1` の上に出る名前) | スモウルボットS1 | アーテックロボ | +| Ruby の書き出し | `smalrubot_s1.` | **`studuino.`**(読みこみは `smalrubot_s1.` も受けつける。下の「Ruby の書き方」) | +| ブロック・選択肢の表示 | ロボットの部品の名前(「左のセンサー」など) | 一般的な名前(下の「ブロックと選択肢」)。センサーの選択肢を足し、ロボットのブロックを「ロボットカー」の見出しの下にまとめた | + +### ライブラリの絵と商標の表記 + +- **絵**: 人間が Gemini で描いた、ケースに入った青い基板を斜めから見たオレンジ背景のイラストを **もとにして** 作った。アーテック社の製品の写真やロゴは使っていない。左下の小さいアイコンと外側の白い枠は取り除いた(左下は上の背景で塗りつぶした)。 + - カード(600×372)は背景ごと切り出して縮小した。接続モーダルの絵(95×95)とカテゴリ・カードの小さい絵(40×40)は、基板とケースを正方形に切り出し、同じオレンジの背景で余白を埋めた。カテゴリの絵(VM の `blockIconURI`)は 40×40 と同じ絵。 +- **商標の表記**: カードの説明は「アーテックロボの Studuino®(スタディーノ)基板を動かす。**アーテックロボは株式会社アーテックの製品で、Studuino® は同社の登録商標です。**」。Studuino® は登録商標なので ® を付ける。アーテックロボは商標の扱いを確かめていないので、「登録商標」と言い切らず「株式会社アーテックの製品」と書く。カードには「協力: Artec Co., Ltd.」も出る(実際に協力いただき、基板も提供いただいている)。紹介ページ(`pages/about.html`)の紹介にも同じ一文を入れ、写真はこの基板の絵にした。 + + ![紹介ページの計測と制御のカード](screenshots/0701-about-page-1280x800.png) + +### 移行期間(前の名前のカード) + +前の名前の資料(授業の手引き・プリント)が「スモウルボットS1 を選ぶ」と書いているので、**1 年の移行期間**を置く。 + +- 拡張機能ライブラリには、**アーテックロボ** のカードのすぐ後ろに、前の名前・前の絵(スモウルボットS1 のロボットの写真。`smalrubot-s1/legacy-smalrubot-s1*.png`)の **スモウルボットS1** のカードも出す。説明は「アーテックロボの前の名前です。選ぶと、アーテックロボが使えます。」。 +- どちらのカードを選んでも、読みこむのは同じ拡張機能 `smalrubotS1`(ブロック・作品・Ruby は同じ)。拡張機能の ID は 1 つのまま。前のカードはライブラリの中だけの別の項目(キーと DOM の id は `smalrubotS1Legacy`)で、選ぶと今のカードに置きかえてから読みこむので、接続の流れも同じになる。 +- 前のカードを選ぶと、画面の上に **名前が変わったことの知らせ**(アラート・閉じるボタンつき。`data-testid="smalrubot-s1-renamed-alert"`)が出る: 「スモウルボットS1 は「アーテックロボ」に名前が変わりました。中身は同じです。これからは「アーテックロボ」を選んでください。」。アラートは接続モーダルより上に出るので、接続の手順の途中でも読める。 +- 前のカードには `smalrubot` / `スモウルボット` などのタグを付けてある(拡張機能ライブラリはいまは検索欄を出していないが、検索を出したときに前の名前で見つかる)。 +- **期限**: 前のカードを出すのは **2027-11-30 まで**(その日の終わりまで。端末の日付で判断)。日付は `legacy-card.jsx` の `SMALRUBOT_S1_LEGACY_CARD_LAST_DAY` の 1 か所で、過ぎると自動で出なくなる。期限が来たら、前のカードのコード(`legacy-card.jsx`・前の絵・知らせ・翻訳・テスト・このセクション)を消す。 + +![拡張機能ライブラリの 2 枚のカード](screenshots/0402-library-legacy-card-1280x800.png) + +![前のカードを選んだときの知らせ](screenshots/0403-renamed-alert-1280x800.png) + +### 変えないもの + +前の作品を開けるように、次のものは **変えない**: + +- 拡張機能の ID: `smalrubotS1` +- ブロックの opcode(`smalrubotS1_action` など。下の表) +- メニューの名前(`actions` / `sensorPositions` / `positions`)と、メニューの **値**(`forward` / `left` / `touch` など)。選択肢を増やすときは値を **足すだけ** にして、既存の値の意味を変えない +- Ruby のメソッド名(`action` / `bend_arm` / `sensor_value` など)と、`smalrubot_s1.` の **読みこみ** +- ファームウェア(`smalrubot-firmware.hex.js`)と基板との通信のしかた +- 翻訳メッセージのキー(`smalrubotS1.*` / `gui.smalruby3.extension.smalrubotS1.*` など)。変えるのは値(表示の文字)だけ +- ソースのファイル名・ディレクトリ名(`scratch3_smalrubot_s1/`、`smalrubot-s1-*-step.jsx` など)と、計測イベント名(`smalrubot_s1`。[`docs/analytics/`](../analytics/)) +- このドキュメントの置き場所(`docs/extension-smalrubot-s1/`)。ID を変えない方針に合わせる + +## ポートの配置 + +ポートの配置は、いまのスモウルボットS1 の配置のまま変えない。既存のブロックは、部品ごとに挿すポートが決まっているので、それに従う。 + +| ポート | 部品 | 使うブロック | +|---|---|---| +| A0 / A1 | LED(左 / 右) | `turnLedOn` / `turnLedOff` | +| A2 | タッチセンサー | `getSensorValue`(`touch`) | +| A4 / A5 | 赤外線センサー(フォトリフレクタ)(左 / 右) | `getSensorValue`(`left` / `right`) | +| A6 | 光センサー | `getSensorValue`(`light`) | +| A7 | 音センサー | `getSensorValue`(`sound`) | +| M1 / M2 | DC モーター(左 / 右) | `action` / `actionAndStopAfter` / `getMotorSpeed` / `setMotorSpeed` | +| D10 | サーボモーター(アーム) | `bendArm` / `setArmCalibration` | + +ポートの割り当てを変えられる形は、この拡張機能の通常の使い方には入れない(下の「Studuino モードとの境目」)。 + +## ブロックと選択肢 + +### 方針 + +- **通常の拡張機能には、できる限りブロックを足さない**。そのかわり **ドロップダウンの選択肢を増やして**、一般的な名前でも選べるようにした。例: センサーのブロックで「左のセンサー (A4)」も「赤外線センサー(フォトリフレクタ)(A4)」も選べる。 +- センサーの名前は、**教科書の一般的な名前を先に、部品名をかっこで** 書く:「光センサー (A6)」「赤外線センサー(フォトリフレクタ)(A4)」「タッチセンサー (A2)」「音センサー (A7)」。 +- 教科書の例にある部品のうち Studuino に無いもの(超音波センサーなど)は扱わない。 +- LED と DC モーターは同じメニュー(`positions`)を使うので、片方だけの選択肢は足せない。ブロックの文言にポートを書く(「[左▼] のLED (左:A0, 右:A1) をオンにする」)。 + +### ブロックの一覧 + +パレットの上から順に並べた。「ロボットカー」の見出しより下が、ロボットとして動かすブロック。 + +| opcode | 表示(日本語) | ポート | +|---|---|---| +| `getSensorValue` | `[光センサー (A6)▼] の値` | A2 / A4 / A5 / A6 / A7 | +| `turnLedOn` / `turnLedOff` | `[左▼] のLED (左:A0, 右:A1) をオン(オフ)にする` | A0 / A1 | +| `getMotorSpeed` | `[左▼] のDCモーター (左:M1, 右:M2) の速度 (%)` | M1 / M2 | +| `setMotorSpeed` | `[左▼] のDCモーター (左:M1, 右:M2) の速度を (50) (%) にする` | M1 / M2 | +| (見出し) | **ロボットカー** | — | +| `action` | `[車を前進させる▼] (M1, M2)` | M1 / M2 | +| `actionAndStopAfter` | `(0.5) 秒 [車を前進させる▼] (M1, M2)` | M1 / M2 | +| `bendArm` | `(1) 秒でアーム(サーボモーター D10)を (90) 度に曲げる` | D10 | +| `setArmCalibration` | `アーム(サーボモーター D10)を (0) 度調整する` | D10 | + +### センサーの選択肢(`sensorPositions` メニュー) + +上から並べた順。新しいブロックを出したときは、いちばん上の「光センサー (A6)」が選ばれている(前は「左」)。保存してある作品の値は変わらない。 + +| 値 | 表示 | 読むポート | +|---|---|---| +| `light` | 光センサー (A6) | A6 | +| `ir_a4`(新しい値) | 赤外線センサー(フォトリフレクタ)(A4) | A4(`left` と同じ) | +| `ir_a5`(新しい値) | 赤外線センサー(フォトリフレクタ)(A5) | A5(`right` と同じ) | +| `touch` | タッチセンサー (A2) | A2 | +| `sound` | 音センサー (A7) | A7 | +| `left` | 左のセンサー (A4) | A4 | +| `right` | 右のセンサー (A5) | A5 | + +既存の値(`left` / `right` など)は残してあるので、前の作品はそのまま動く。 + +### 動きの選択肢(`actions` メニュー) + +| 値 | 表示 | +|---|---| +| `forward` | 車を前進させる | +| `backward` | 車を後退させる | +| `left` | 車を左に曲げる | +| `right` | 車を右に曲げる | +| `stop` | 車を止める | + +### 「ロボットカー」の見出し + +ロボットとして動かすブロック(前進・後退・回転、アームを曲げる、アームを調整する)は **残したまま**、パレットの後ろの方に「**ロボットカー**」の見出しをつけてまとめた。ブロックは足さず、opcode とメニューの値も変えていない(並べる順番と表示だけが変わった)。 + +見出しは、拡張機能のブロックの情報に `blockType: BlockType.LABEL` を書くと出る(Smalruby が scratch-vm に足した種類。Blockly のフライアウトの見出し `