SmalrubotS1のファームウェア書き込み機能の実装

[takaokouji]

概要

SmalrubotS1（Arduino互換マイコンボード）のファームウェアを、スモウルビーのブラウザから直接書き込めるようにします。

背景

現在の状況

SmalrubotS1を使うには、事前に専用ファームウェア（HEXファイル）を書き込む必要があります。現在はavrdudeを使って書き込んでいますが、以下の課題があります：

• avrdudeの知識が必要
• 開発環境のセットアップが必要
• 初心者にとってハードルが高い

解決策

WebSerial APIを使用して、ブラウザから直接ファームウェアを書き込めるようにします。これにより：

• ✅ 追加ツール不要（ブラウザだけで完結）
• ✅ 簡単な操作（ポート選択→自動書き込み）
• ✅ 初心者でも安心

ユーザー体験（想定操作フロー）

フェーズ1: 手動書き込み（まずはここを実現）

1. smalrubot_s1拡張機能を有効にする
2. 「SmalrubotS1」メニューが表示される（meshV2と同様の仕組み）
3. サブメニュー「ファームウェアを書き込む...」を選択
4. WebSerialのシリアルポート選択ダイアログが表示される
5. ポートを選択すると自動的に書き込みが開始される
6. 書き込み完了

フェーズ2: 自動促進（将来実装）

接続時のハンドシェイクに失敗した場合、接続モーダルでファームウェア書き込みを促します。

参考実装: MeshV2のネットワークフィルタリングエラー処理

• packages/scratch-gui/src/components/connection-modal/mesh-v2-network-filtered-step.jsx

ポリシー: 「まずはやってみる。だめだったらそのときに対策する」というユーザー体験を提供。

技術情報

SmalrubotS1 ハードウェア仕様

• ベース: Arduino互換マイコンボード
• MCU: ATmega168PA
• Flashメモリ: 16KB
• ブートローダー: Optibootプリインストール
• シリアルチップ: Prolific製（USB Vendor ID: 0x067b, Product ID: 0x2303）

ファームウェアファイル

• 場所: notes/sr_studu.ino.hex
• フォーマット: Intel HEX

STK500v1プロトコル

Optibootは STK500v1 プロトコルを使用してファームウェアを転送します。

主要コマンド:

• STK_GET_SYNC (0x30) - 同期確立
• STK_SET_DEVICE (0x42) - デバイスパラメータ設定
• STK_SET_DEVICE_EXT (0x45) - 拡張パラメータ設定
• STK_ENTER_PROGMODE (0x50) - プログラミングモード開始
• STK_LOAD_ADDRESS (0x55) - アドレス設定
• STK_PROG_PAGE (0x64) - ページプログラム（最大128バイト）
• STK_LEAVE_PROGMODE (0x51) - プログラミングモード終了

参考ドキュメント:

• https://arduino.stackexchange.com/questions/15936/what-happens-when-code-is-uploaded-using-the-bootloader

提供された実装ファイル

WebSerialでファームウェア書き込みを実現している企業から提供された情報：

1. notes/stk500.js

STK500v1プロトコルのJavaScript実装。主要な機能：

class STK500 {
  transfer(sketch, reset_cb, transfer_cb, transfering_cb)
  checkSync(command)
  get_sync(data)
  set_parameter(data)
  set_extended_parameter(data)
  enter_programmode(data)
  load_address(data)
  paged_write(data)
  leave_programmode(data)
}

特徴:

• WebSerial API対応
• Intel HEXフォーマットのパース機能
• プログレス通知機能

2. notes/sketch_testmode.js

ファームウェア（sr_studu.ino.hex）をJavaScriptから扱えるようにしたもの。

Dummy = '\
:100000000C9465000C948D000C948D000C948D0064\n\
:100010000C948D000C948D000C948D000C9485181C\n\
...

用途: ファームウェアデータをあらかじめこの形式に変換しておく必要がある。

既存の参考実装

Node.js実装（検証済み）

これまでの調査で、Node.jsでファームウェア書き込みに成功しています。

• 使用ライブラリ: avrgirl
• 結果: ✅ 成功

WebSerial実装（未検証）

• 結果: ❌ まだ成功していない
• 状況: シリアル通信自体は正常に動作するが、ファームウェア書き込みは失敗

現在のsmalrubot_s1拡張機能

実装場所: packages/scratch-vm/src/extensions/scratch3_smalrubot_s1/index.js

現在の接続フロー:

1. WebSerial APIでポート選択
2. シリアルポート接続（baudRate: 19200）
3. ハンドシェイク: reset_v2コマンドで 'S1' レスポンスを確認
4. 各種ポート初期化

接続失敗時の動作:

• PERIPHERAL_REQUEST_ERRORイベントを発行
• 接続モーダルでエラー表示

実装アプローチ

ステップ1: 実験フェーズ（必須）

提供されたstk500.jsを使って、まずは書き込みが成功するかを確認します。

(1) Node.js でコマンドライン実験

# notes/stk500.js を使ってファームウェアを書き込む
node experiment-upload.js

成功条件: Node.jsでstk500.jsを使った書き込みが成功すること

(2) WebSerial でブラウザ実験

<!-- シンプルなHTML/JSでWebSerial経由の書き込みテスト -->
<script src="notes/stk500.js"></script>
<script src="notes/sketch_testmode.js"></script>

成功条件: WebSerialでstk500.jsを使った書き込みが成功すること

ステップ2: 統合実装フェーズ（実験成功後）

実験で書き込みが成功したら、smalruby3-editorに統合します。

実装場所

1. scratch-vm拡張

   • packages/scratch-vm/src/extensions/scratch3_smalrubot_s1/index.js
   • uploadFirmware()メソッドを追加

2. GUIメニュー

   • packages/scratch-gui/src/components/menu-bar/smalrubot-s1-menu.jsx（新規）
   • meshV2と同様の仕組みでメニュー追加

3. 接続モーダル（将来）

   • packages/scratch-gui/src/components/connection-modal/smalrubot-s1-firmware-upload-step.jsx（新規）
   • 接続失敗時のファームウェア書き込みステップ

タスク

🔬 実験フェーズ

• Node.jsでstk500.jsを使った書き込みテスト
• WebSerialでstk500.jsを使った書き込みテスト
• 実験結果のドキュメント化

🛠️ 実装フェーズ（実験成功後）

• stk500.jsのscratch-vmへの統合
• SmalrubotS1BlocksにuploadFirmware()メソッド追加
• 進捗イベントの実装
• エラーハンドリングの実装
• GUIメニューの追加（「ファームウェアを書き込む...」）
• ファームウェアデータの管理（sketch_testmode.js形式）

✅ テストフェーズ

• 書き込み機能の動作確認
• エラーケースのテスト
• ユーザビリティテスト

参考情報

関連Issue

• smalruby3-gui#407: Smalrubot S1用ファームウェア転送機能の実装
  • Smalrubot S1用ファームウェア転送機能の実装 smalruby3-gui#407
  • より詳細な技術情報が記載されています

参考実装

• micro:bit用ファームウェア転送機能
  • packages/scratch-gui/src/lib/microbit-update.js

技術ドキュメント

• STK500プロトコル: https://arduino.stackexchange.com/questions/15936/what-happens-when-code-is-uploaded-using-the-bootloader
• WebSerial API: https://developer.mozilla.org/en-US/docs/Web/API/Web_Serial_API

受け入れ基準

フェーズ1

• 「SmalrubotS1」メニューが表示される
• 「ファームウェアを書き込む...」サブメニューが動作する
• シリアルポート選択ダイアログが表示される
• ファームウェア書き込みが正常に完了する
• 書き込み中の進捗が表示される
• エラー発生時に適切なメッセージが表示される

フェーズ2（将来）

• 接続失敗時にファームウェア書き込み確認ダイアログが表示される
• 書き込み後に自動的に再接続が試行される

🤖 Generated with Claude Code

[takaokouji]

成功したケース

index.js

/**
 * Phase 2: Arduino HEXファイル書き込みスクリプト
 * avrgirl-arduinoを使用してHEXファイルをArduinoに書き込む
 */

const Avrgirl = require('avrgirl-arduino');
const fs = require('fs');
const path = require('path');

// Studuino (ATmega168 + Optiboot) のカスタムボード設定
const STUDUINO_BOARD = {
  name: 'studuino',
  baud: 115200,
  signature: Buffer.from([0x1e, 0x94, 0x06]),  // ATmega168
  pageSize: 128,
  numPages: 128,  // 16KB
  timeout: 400,
  protocol: 'stk500v1'
};

async function uploadHex(portPath, hexFilePath) {
  console.log('Arduino WebSerial調査 - Phase 2: HEX書き込み\n');
  console.log('========================================\n');

  // HEXファイルの存在確認
  if (!fs.existsSync(hexFilePath)) {
    console.error(`エラー: HEXファイルが見つかりません: ${hexFilePath}`);
    process.exit(1);
  }

  const hexFileName = path.basename(hexFilePath);
  const hexSize = fs.statSync(hexFilePath).size;

  console.log(`HEXファイル: ${hexFileName}`);
  console.log(`ファイルサイズ: ${hexSize} bytes`);
  console.log(`ポート: ${portPath}`);
  console.log(`ボード: ${STUDUINO_BOARD.name}`);
  console.log(`ボーレート: ${STUDUINO_BOARD.baud}`);
  console.log('');

  return new Promise((resolve, reject) => {
    const avrgirl = new Avrgirl({
      board: STUDUINO_BOARD,
      port: portPath,
      debug: true  // デバッグ出力を有効化
    });

    console.log('書き込み開始...\n');
    const startTime = Date.now();

    avrgirl.flash(hexFilePath, (error) => {
      const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);

      if (error) {
        console.error('\n========================================');
        console.error('書き込み失敗!');
        console.error(`エラー: ${error.message}`);
        console.error(`経過時間: ${elapsed}秒`);
        console.error('========================================\n');
        reject(error);
      } else {
        console.log('\n========================================');
        console.log('書き込み成功!');
        console.log(`経過時間: ${elapsed}秒`);
        console.log('========================================\n');
        resolve();
      }
    });
  });
}

async function listPorts() {
  console.log('=== 利用可能なシリアルポート ===\n');

  return new Promise((resolve, reject) => {
    Avrgirl.list((err, ports) => {
      if (err) {
        reject(err);
        return;
      }

      const usbPorts = ports.filter(p =>
        p.path.includes('usbserial') ||
        p.path.includes('usbmodem') ||
        p.path.includes('ttyUSB') ||
        p.path.includes('ttyACM') ||
        p.path.includes('cu.wch') ||
        (p.manufacturer && p.manufacturer !== '')
      );

      if (usbPorts.length === 0) {
        console.log('USBシリアルポートが見つかりませんでした。');
      } else {
        usbPorts.forEach((port, index) => {
          console.log(`[${index + 1}] ${port.path}`);
          if (port.manufacturer) {
            console.log(`    製造元: ${port.manufacturer}`);
          }
        });
      }
      console.log('');
      resolve(usbPorts);
    });
  });
}

async function main() {
  const args = process.argv.slice(2);

  if (args.length < 2) {
    console.log('Arduino WebSerial調査 - Phase 2: HEX書き込み\n');
    console.log('========================================\n');

    await listPorts();

    console.log('使い方:');
    console.log('  node index.js <ポートパス> <HEXファイル>');
    console.log('');
    console.log('例:');
    console.log('  node index.js /dev/cu.usbserial-210 sr_studu.ino.hex');
    console.log('========================================\n');
    return;
  }

  const portPath = args[0];
  const hexFilePath = args[1];

  try {
    await uploadHex(portPath, hexFilePath);
    console.log('プログラムの書き込みが完了しました。');
    console.log('Arduinoが正常に動作するか確認してください。');
  } catch (err) {
    console.error('書き込みに失敗しました。');
    process.exit(1);
  }
}

main().catch(console.error);

package.json

{
  "name": "phase2-nodejs-upload",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "description": "",
  "dependencies": {
    "avrgirl-arduino": "^5.0.1",
    "intel-hex": "^0.2.0"
  }
}

[takaokouji]

実験結果報告

Node.js環境でSTK500v1プロトコルを使用したファームウェア書き込み実験を実施しました。

✅ 成功した部分

1. 通信設定

• ボーレート: 115200 bps（ブートローダー標準）
• 初回同期: 手動リセットで100%成功（1回で同期、102ms）

2. プロトコルシーケンス

以下のコマンドは全て正常動作：

• ✅ GET_SYNC
• ✅ SET_PARAMETER（22バイト、分割送信）
• ✅ SET_EXTENDED_PARAMETER
• ✅ ENTER_PROGMODE

3. 部分的なアップロード

2ページ（256バイト）のアップロードに成功

Page 1 (address 0):    128 bytes ✅
Page 2 (address 128):  128 bytes ✅
Page 3 (address 256):  128 bytes ❌ フリーズ

❌ 問題点

3ページ目で必ずフリーズ

症状:

→ TX: 0x55 0x80 0x00 0x20  (LOAD_ADDRESS for address 256)
（応答なし）

試行した対策（全て効果なし）:

• チャンク間遅延の調整（5ms → 10ms）
• ページ間遅延の追加（20ms → 50ms）
• 競合状態の修正（送信完了フラグ追加）
• テスト用ファームウェア使用（6,256バイト）
• 実際のファームウェア（11,454バイト）

結果: 全て3ページ目で同じ動作

🤔 考えられる原因

1. ブートローダーのバグ: 特定アドレス以降で問題がある可能性
2. ハードウェアの問題: ボードまたはUSB-シリアル変換チップ
3. プロトコル実装の差異: 提供されたstk500.jsと実際のOptibootの期待動作の違い

💡 次のステップ（推奨）

1. avrdude での検証（最優先）

実績のあるツールで書き込みが成功するか確認：

avrdude -c arduino -p m168p -P /dev/tty.usbserial-140 -b 115200 \
        -U flash:w:notes/sr_studu.ino.hex:i

• 成功: Node.js実装に問題 → デバッグ継続
• 失敗: ボード/ファームウェアに問題 → ハードウェア調査

2. 提供元との環境比較

• 実際に成功している環境の詳細情報
• ブートローダーのバージョン確認
• 動作ログとの比較

3. 代替アプローチの検討

• WebUSB APIの使用
• サーバーサイド処理
• Electronアプリ化

📂 実験ファイル

詳細なレポート: notes/issues/52/EXPERIMENT_REPORT.md

全実験ファイル:

notes/issues/52/
├── README.md                  # 実験手順書
├── EXPERIMENT_REPORT.md       # 詳細レポート
├── experiment-node.js         # 実験スクリプト
├── stk500.js                  # STK500実装
├── sr_studu_firmware.js       # 実際のファームウェア
└── sketch_testmode.js         # テストファームウェア

まとめ

進捗: 基本的な通信とプロトコルは動作確認済み。最初の256バイトのアップロードに成功。

課題: 3ページ目以降のアップロードで応答がなくなる問題が未解決。

推奨: まずavrdudeでの書き込みテストを実施し、問題の切り分けを行う。

🤖 Generated with Claude Code

[takaokouji]

調査進捗報告: experiment-node.js オートリセット実験 (2026-02-03)

現時点の状況

experiment-node.js で DTR/RTS オートリセットを使った書き込みは 未解決です。調査を一時中断しました。

成功した実験

• --manual-reset モード: ✅ 書き込み成功
• avrgirl-arduino（Node.js実装）: ✅ オートリセット書き込み成功 (4.55秒)

オートリセットモードの問題

最初の GET_SYNC には応答を受けることに成功しますが、その直後の GET_SYNC には応答が全く返りません。

avrgirl-arduino では同じボード・同じポートで問題なく動作しており、タイミング・バイト列ともに完全に一致させた場合にも experiment-node.js では失敗します。

avrgirl (成功):
  19.017  sync-1 RX: 0x14 0x10     ← first response
  19.018  sync-2 TX: 0x30 0x20     (1ms後)
  19.019  sync-2 RX: 0x14 0x10     ← immediate response ✅

experiment-node.js (失敗):
  12.313  sync   RX: 0x14 0x10     ← first response
  12.314  transfer TX: 0x30 0x20   (1ms後)
          ← RX: NOTHING            ❌ ボード無応答

試した修正と結果

#	修正内容	結果
1	Buffer pooling バグ修正 (data.buffer.slice)	✅ pointBuf正常化
2	forEach→while ループ修正	✅ 応答処理正常化
3	ページ間遅延 50ms→4ms (avrgirl同等)	✅
4	チャンク間10ms遅延削除	✅
5	DTR+RTS 同時トグル (avrgirl同等)	✅ リセット正常化
6	avrgirl にデバッグログ追加・バイトレベル比較	✅ 動作確認・仮説検証
7	drain() 追加 (TX→HW フラッシュ確認)	❌ 書き込み失敗のまま
8	checkSync の即時解決 (setInterval遅延15ms排除)	❌ タイミング1msに正規化されたが無応答
9	drain() 削除 (avrgirl のwriteパターンに完全一致)	❌ 依然無応答

否定済みの仮説

• タイミング遅延: setInterval の15ms遅延を排除し1msに短縮 → 依然失敗
• drain()の副作用: drain()削除し avrgirl と完全同一パターンに → 依然失敗
• バイト列の誤り: TXログで 0x30 0x20 を毎回確認済み
• シリアルポートエラー: エラーイベントの発生なし

残りの仮説と次の調査ポイント

1. pre-boot GET_SYNC による受信バッファの混乱 (最も有望)

   • checkSync は起動中に7〜11回のGET_SYNCを送信する
   • UARTが初期化されるタイミングにより、ボード側に半途のバイト(0x30のみ)が受信バッファに残る可能性がある
   • Optiboot のメインループで次のバイトを読む際にバイト列がズレ、GET_SYNCが正しく処理されない
   • 対策: checkSync の送信回数を3回に制限し、sync後にのみ次のコマンドを送信する

2. GET_SYNC 自体の拒否

   • 初回sync後、ブートローダーが次のコマンドとしてGET_SYNC以外を期待している可能性
   • 対策: transfer GET_SYNC をスキップし、直接 SET_PARAMETER を送信してテスト

3. グローバルコールバック vs コマンド単位リスナー

   • avrgirl はコマンドごとに stream.on('data') リスナーを登録/削除
   • experiment-node.js はグローバルコールバック (onReceiveSensor) を使用
   • 対策: avrgirl の sendCommand パターン（write callback 内でリスナー登録）に移植

詳細は notes/issues/52/INVESTIGATION_SUMMARY.md に記載しています。