Skip to content

About

A browser-based VT100/ANSI terminal emulator using the Web Serial API for embedded hardware debugging and communication. Web Serial APIを利用した、ブラウザ上で動作する組み込み開発・デバッグ向けのVT100/ANSI対応シリアルターミナルエミュレータ。

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Web Serial Console

Web Serial API と Xterm.js をベースとし、 「ターミナル(ブラウザ)側にコマンド履歴およびデバッグログ保存機能を持たせる」 ことで、組み込み機器側のCLI・デバッグロジックを極限までシンプルに保てるよう設計されています。

License: MIT-0

Web Serial Console


主な機能

  • 単一ファイル構成: ビルドツールやサーバーは不要です。web-serial-console.html をブラウザ(ChromeやEdgeなど)で開くだけで使用できます。
    • ※ Xterm.js は CDN (jsDelivr) から読み込むため、初回はインターネット接続が必要です。完全オフラインで使う場合は、Xterm.js のファイルをローカルに置き、HTML 内の <link> / <script> の URL を書き換えてください。
  • 高度なローカル行編集:
    • ブラウザ側でコマンドをバッファリングし、左右のカーソル移動 (←/→)、バックスペース、Deleteキーによる編集が可能。
    • マイコン側のプロンプト(> や uart:~$ など)を消去してしまわない安全な部分再描画方式を採用。
    • Enter で入力行をまとめて送信します(改行は LF のみ。CR は送信しません)。
    • Ctrl+V (Cmd+V) でクリップボードの内容を貼り付け可能。改行は LF に統一し、ESC などの制御文字は除去します。
    • 複数行を貼り付けた場合は、確認ダイアログのあと、最後の行以外を 50ms 間隔で順に送信します。
  • 充実した履歴機能:
    • 矢印キー (↑/↓) によるコマンド履歴の呼び出し(LocalStorageに最大100件保存)。
    • 直近20件(重複除く)の履歴をすばやく選択・送信できるクイック送信ドロップダウン。
  • 受信データの自動整形:
    • 受信した CR (\r) はすべて破棄し、LF (\n) のみを行区切りとして扱います。
    • 自分が送信したコマンドのエコーバックを自動で除去します(1文字ずつ返ってくる場合も対応)。
    • 空行を表示・記録しません(画面とログの両方)。デバイスが意図的に送る空行も除去されます。
  • タイムスタンプ付与:
    • 各行の行頭にミリ秒精度の時刻 [YYYY-MM-DD hh:mm:ss.mmm] を付与(「タイムスタンプ付与」チェックボックスで ON/OFF)。
    • 一括で届いた複数行も、同一時刻にならないよう順序を保って補正します。
    • コマンド行は、プロンプトが表示された時刻ではなく Enter を押した(送信した)時刻 に更新されます(画面・ログの両方)。
  • ログ保存 & ユーティリティ:
    • 受信ログに加えて、入力・送信したコマンドも記録し、serial_YYYYMMDD_hhmmss.log として一括保存。
    • ログ保存時、エスケープシーケンスは除去されます。
    • ログバッファとターミナル画面(スクロールバック 30000 行)を一括クリア。
    • ターミナル領域は縦方向にドラッグしてリサイズでき、ウィンドウサイズにも自動追従します。
  • 自動フォーカス管理: 接続や各種ボタン操作の完了と同時にターミナルへ自動フォーカスし、すぐにキーボード入力が可能。

キー操作

キー 動作
↑ / ↓ コマンド履歴の前 / 次を呼び出す
← / → カーソル移動
Backspace / Delete カーソルの左 / 位置の文字を削除
Enter 入力行を送信(LF のみ)
Ctrl+C (Cmd+C) テキスト選択中: クリップボードへコピー
未選択時: 入力中の内容を破棄し、割り込み 0x03 を送信
Ctrl+V (Cmd+V) クリップボードの内容を貼り付け(右クリックメニューからの貼り付けも同様)
1行: カーソル位置に挿入(送信はしない)
複数行: 最後の行以外を順に送信し、最後の行は入力欄に残す
ドラッグ選択 ターミナル内のテキストを選択

ログの例

[2026-10-25 18:22:06.563] ECLI> help
[2026-10-25 18:22:06.564] Available Commands:
[2026-10-25 18:22:06.566]   help        : Show available commands
[2026-10-25 18:22:06.568]   version     : Show firmware version
[2026-10-25 18:22:16.793] ECLI> version
[2026-10-25 18:22:16.795] ECLI Firmware v1.0.1
[2026-10-25 18:22:16.796] ECLI> 

ECLI> help の行の時刻は、プロンプトの表示時刻ではなく、コマンドを送信した時刻です。


接続するデバイス側の前提

  • シリアル設定: 8N1 固定(データ8bit / ストップ1bit / パリティなし)。ボーレートは 9600〜921600 bps から選択(デフォルト 115200 bps)。
  • 行区切りは LF で受信できること(受信データの CR は破棄されます)。
  • コマンドのエコーバックは、あってもなくても動作します(あれば自動で除去されます)。

使用技術


使い方

  1. このリポジトリをクローンまたはダウンロードします。
  2. Web Serial API対応ブラウザ(Google Chrome、Microsoft Edgeなど)で以下のいずれかのファイルを開きます。
  • web-serial-console.html (通常版:ソースコードの改変やデバッグをしたい方向け)
  • web-serial-console.min.html (圧縮版:軽量・高速動作。普段使い用)
  1. ボーレート(デフォルト: 115200 bps)を選択し、「接続」 ボタンをクリックします。
  2. 接続するシリアルデバイス(マイコンボードなど)を選択します。
  3. ターミナルにコマンドを入力して Enter で送信します。ログは 「ログ保存」 でファイルに保存できます。

Web Serial API は、Firefox や Safari など一部のブラウザでは利用できません。


注意事項・既知の制限

  • 受信ログは メモリ上にのみ保持されます。ページを閉じる・再読み込みすると消えるため、必要なログは先に「ログ保存」してください(コマンド履歴は LocalStorage に残ります)。
  • プロンプトを受信しないまま入力した行には、画面上のタイムスタンプは付きません(ログにのみ付与されます)。
  • 大量のデータを受信している最中に Enter を押すと、画面上の時刻の書き換え位置がずれる場合があります(ログは影響を受けません)。
  • シリアル設定は 8N1 固定です(変更するには HTML 内の serialPort.open() を編集してください)。
  • 複数行を貼り付けて連続送信すると、エコーバックの除去は最後に送った1行分しか追跡しないため、デバイスがエコーを返す場合は一部が画面に残ることがあります(行間の待ち時間 PASTE_LINE_DELAY_MS を長くすると軽減できます)。
  • 全角文字を貼り付けると、カーソル移動の位置が表示幅とずれる場合があります。

開発・改変する方へ

ソースコードは web-serial-console.html 1ファイルで、JavaScript は <script> 内にまとまっています。誰でも修正しやすいよう、コメントは Doxygen 形式で統一しています。

コメント規約

  • 関数・イベントハンドラ・グローバル変数は、/** で始まるブロックコメントに @brief / @details / @param / @return / @note / @warning などを使って記述します。
  • 変数の説明は、宣言行の末尾に ///< で記述します。
  • 関連する宣言は @defgroup でグループ化し、末尾に end of grp_xxx の目印コメントを付けます。
  • 関数内部の補足説明は、通常の // コメントで記述します。

コードの構成(グループ)

グループ 内容
grp_config 定数・状態管理変数
grp_term Xterm.js の初期化・サイズ追従・共通ヘルパー
grp_conn シリアルの接続・切断
grp_buttons ログ保存/消去、履歴消去、クイック送信ボタン
grp_rx 受信データ処理(CR破棄・エコー除去・空行抑止)、タイムスタンプ、ログ記録
grp_serial_io 受信ループ・送信処理
grp_history コマンド履歴の保存とクイック送信プルダウンの更新
grp_input キーボード入力(行編集・Enter送信・Ctrl+C・Ctrl+V 貼り付け)

実装上の注意

  • 画面(Xterm)とログ(rawLogBuffer)は、別々に行の状態を管理しています(画面: screenAtLineStart / ログ: window._termIsNewLine)。
  • restampPromptLine() と logUserCommand() は、画面の改行 (\r\n) を出力する前に呼び出す必要があります。
  • Doxygen は .html を直接解析しません。ドキュメントを生成する場合は、<script> の中身を .js として切り出すか、入力フィルタを使用してください。
  • term.attachCustomKeyEventHandler() に渡す関数は、async にしないでください。Xterm.js は戻り値を === false で判定するため、async 関数だと Promise が返り、return false が無視されます(Ctrl+V の貼り付けが動かなくなります)。
  • Ctrl+V は、キーハンドラで false を返して Xterm.js の既定処理(^V の送出)を止め、ブラウザ標準の paste イベントを termContainer の capture フェーズで受け取って処理しています。
  • バージョンは APP_VERSION 定数(grp_config)で管理しており、画面上部の見出しと起動メッセージに表示されます。更新時は、通常版・圧縮版 (web-serial-console.min.html)・README の「変更履歴」をそろえてください。
  • 貼り付けの設定値は PASTE_CONFIRM_MULTILINE(複数行ペースト時の確認ダイアログ)と PASTE_LINE_DELAY_MS(1行ごとの待ち時間)です。

変更履歴

v1.1.0 (2026-11-12)

  • Ctrl+V (Cmd+V) / Ctrl+Shift+V / 右クリックによる貼り付けに対応(複数行は確認ダイアログのあと順次送信)。
  • カスタムキーハンドラを同期関数に変更(async だと return false が無視されるため)。
  • 画面上部の見出しと起動メッセージにバージョンを表示。

v1.0.0

  • 初版。

ライセンス

このプロジェクトはMIT-0ライセンスのもとで公開されています。詳細はLICENSEファイルをご覧ください。

  • 商用利用・個人利用を問わず、完全自由に使用できます。
  • 著作権表示やライセンス文言の保持・記載義務すらありません。
  • ソースコードの改変、流用、再配布、自社製品への組み込み等、制限なくご活用いただけます。

About

A browser-based VT100/ANSI terminal emulator using the Web Serial API for embedded hardware debugging and communication. Web Serial APIを利用した、ブラウザ上で動作する組み込み開発・デバッグ向けのVT100/ANSI対応シリアルターミナルエミュレータ。

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages