# ツールを範囲ごとに

> エージェントが呼び出せるすべてのツールが何をするかを、それを名乗る機能の切り替えごとにまとめたものと、切り替えのいらないヘルプのツール。

ツールの名前は、変わらない snake_case の識別子です。エラーは構造化されていて、手が打てる形で返ります。失敗した呼び出しは、何が悪かったかに加えて、それを直すツールや手順を名指しした助言を返すので、エージェントは当てずっぽうではなく自分で直します。サーバーはすべてのエージェントに、アプリの動き方についての質問に答える前に `help_search` と `help_read` でヘルプを読むよう指示し、バックアップ（管理）の範囲が入っているときは、構成を変える前に構成のバックアップを作るようにも指示します。この一覧のうちどれがエージェントに実際に見えるかは、[範囲ごとに開くもの](agent-areas)が決めます。それに加えて、範囲のいらないヘルプのツールがあります。

## ヘルプ {#help}

2 つのヘルプのツールは、インストールに含まれているとおりのこのドキュメントを読みます。[ヘルプのパネル](app-window#contextual-help)が開くのと同じ記事で、ステーションにインストールされている版のために書かれたものです。範囲ごとの切り替えがどうであれ、全体を止めるスイッチが入っていれば endpoint とともに現れます。本文は公開されているドキュメントで、ステーションのことは何も見せないからです。どちらも、ランタイムが止まっている間も動き続けます。

| ツール | 何をするか |
| --- | --- |
| `help_search` | 質問の言葉から記事を探し、それぞれの slug、タイトル、要約、その言葉が触れる節を、よく合うものから順に返します（既定は 10 件、最大 50 件）。大文字と小文字、アクセントの違いは無視されます。検索語がなければ、すべての記事を並べます。 |
| `help_read` | 1 つの記事の全体を slug で指定してプレーンテキストで読みます。タイトル、要約、節の一覧、本文を返し、節はそれぞれ見出しの行に、表は 1 行ずつテキストの行に置き、リンク先の記事の slug も添えます。 |

どちらも既定ではステーションの表示言語で読むので、答えが名指しするページ、ボタン、欄は画面にあるものと同じです。どちらも `culture` で、インストールされたヘルプが含むほかの言語を指定できます。含まれていない言語は、含まれている言語の一覧とともに拒否され、ほかの言語が代わりに答えることはありません。ヘルプがない、または読めないインストールでは、どの呼び出しにも記事の代わりにその理由を返します。

## Connector：読み取り {#connector--read}

| ツール | 何をするか |
| --- | --- |
| `connector_browse` | Connector のページが描くツリーを、実時間の稼働状態とともに並べます。ステーションに追加したすべてのドライバーが、下に何もないものも含めて並び、機器、シリアル回線、ブローカーのいずれかを持つドライバーは常に追加済みです。Modbus RTU はドライバー、シリアル回線、機器、タグの順、MQTT はドライバー、ブローカー（セッションの状態付き）、機器、タグの順、そのほかのドライバーはドライバー、機器、タグの順で、機器ごとにそのフォルダーを隣に置きます。Generic serial and TCP は、シリアル回線を Modbus RTU と同じように、ネットワークの機器をほかのドライバーと同じように並べ、機器ごとに通信方式を添えます。SCPI instruments も、シリアル回線とそのほかの機器を同じように並べます。File の機器は、フォルダー、ファイル名、読み方（1 つのファイルか受信フォルダーか）、書式を持ちます。Database の機器はデータベースの種類（`databaseKind`）を持ちます。機器ごとに `error` を持ちます。その機器のページが表示するのと同じ一文で、ステーションの言語で書かれます。エラーがシリアル回線やブローカーのものならそこを指す一文、そうでなければ機器自身のエラー（接続しない、接続が拒まれる、ドライバーが警告する）、それもなければ読み取りを拒まれているタグの要約で、タグごとの理由は `tag_read` の `readFailure` です。機器にエラーがないときは `null` です。機器が接続されていないタグについて `tag_read` が返す一文は、ここを指しています。`tag_read`、`tag_write`、Logic の式が使うタグの別名（`Driver.Folders….Device.Tag`）も明かします。Connector が止まっている間、別名は null です。 |
| `tag_read` | 1 つのタグの実時間の値を別名で読みます。`valueRaw` は機器自身の値で、どの段階も通る前のものです。`value` は変換経路のすべての段階（小数桁の段階を含む）を通ったあとの工業値で、機器が 2.718281828459 と報告する Double は、小数桁が 2 なら 2.72 と読めます。ほかに品質、2 つの時刻、そして `substitution` があります。`substitution` は、その値が機器の報告したものではなく、設定した代替値かどうかを言います。`None`（測定値、または値がまったくない）、`NaNReplaced`（読み取りが NaN で、宣言した置き換えの値がその代わりに立った）、`LastGoodHeld`（読み取りに失敗し、最後に届いた読み取りが、その読み取りの生値と時刻とともに保持されている）、`ReadFailureReplaced`（読み取りに失敗し、宣言した置き換えの値が出ている）のどれかです。代替値は値として数えるので、上下限の異常が出ない限り品質は良いままですが、測定値であることは決してありません。`communicating` は、機器がまだ応答しているかどうかを言います。最後の読み取りが失敗したとき、またはまだ何も読んでいないときは `false` です。タグの読み出し周期に短い余裕を足した時間が新しい読み取りのないまま過ぎた読み取りは、失敗した読み取りとして扱われます。値、品質、`substitution` は失敗した読み取りのときと同じに答え（既定では値がなく品質は悪く、タグの方針しだいで保った読み取りか宣言した数値）、`communicating` は `false` になり、時刻は最後に届いた読み取りを示します。タグの上下限の外にある値は、接続の障害ではありません。品質は悪くなりますが、`communicating` は `true` のままです。`readFailure` は、読み取りが届かなかった理由を、タグのパネルが表示するのと同じ一文で、ステーションの言語で言います。タグ自身の読み取りが拒まれたときは機器またはドライバーが挙げた理由、タグの機器が接続されていないときはその機器を指す一文です。タグが読めているあいだは `null` で、届かなかった読み取りにまだ記録された理由がないときも `null` です。 |
| `modbus_server_status` | ステーション自身の [Modbus サーバー](connector-modbus-server)を報告します。オンかどうか（`enabled`）、`port`、`status`（Off、Listening、PortInUse、システムの言葉を `failure` に入れた Failed、または RuntimeStopped）、いま接続しているクライアント（同時に最大 `maximumClients`）、そしてレジスターマップの各行です。行ごとに `registerClass`、0 から数えた `register` と `lastRegister`、型と並べ方、`access`（ReadOnly か ReadAndWrite）、信号源（タグか変数を、アドレスと id で）、そしてクライアントがいまそこで読む `value` と `good`、またはクライアントに例外 04 を返す理由の `gap`（NoSource、SourceRemoved、NoGoodValue、NotRepresentable）を返します。ランタイムが止まっている間も使えます。 |
| `station_broker_status` | ステーション自身の [MQTT ブローカー](connector-mqtt-broker)を報告します。機器が発行する先のブローカーで、ステーションが読むブローカーではありません。オンかどうか（`enabled`）、`port`、`status`（Off、Listening、PortInUse、システムの言葉を `failure` に入れた Failed、または RuntimeStopped）、`authentication`（Anonymous か UsernamePassword、`username` と `hasPassword` 付きで、パスワードそのものは含みません）、いま接続している機器（同時に `maximumClients` 台まで）、そして `thisStationEntry` です。これはステーションがこのブローカーを読むための MQTT ドライバーのブローカー「このステーション」です。ランタイムが止まっていても使えます。 |
| `mqtt_publish_list` | ステーションが読む各 MQTT ブローカーに発行しているもの、つまり各ブローカーの[発行のカード](driver-mqtt#the-publish-card)を並べます。ブローカーの `publishTopicPrefix` と発行中かどうか、各行の信号源（アドレスで。信号源が削除されていれば `removed`）、`topic`、メッセージ（`value` か `alarm`）が付き、2 種類のメッセージは `payloads` で説明されます。ランタイムが止まっている間も使えます。 `access` が `ReadAndWrite` の行は、`writeTopic`（トピックに `/set` を続けたもの）で値を受け付け、信号源に書き込んで `MQTT <ブローカー名>` として診断ログに記録します。`payloads.write` はそのトピックが受け付けるものを示します。各ブローカーは `publishFormat` を伝えます。Sparkplug B のブローカーは `sparkplug`（グループ、ステーションのエッジノード ID、機器）を加え、その各行はどの機器とメトリックとして発行されるかを伝えます。`payloads.sparkplug` は Sparkplug B の出し方を伝えます（[Sparkplug B での発行](driver-mqtt#publishing-in-sparkplug-b)）。 |
| `remote_access_devices` | ネットワーク越しにステーションの画面を開いているのが誰かを伝えます。いまほかのコンピューターやタブレットから接続しているブラウザー（アドレス、ブラウザーとシステム、ページ、ユーザー、いつからか、それぞれがどの構成済みの端末か）と、構成済みの端末のそれぞれの開き方（開始画面、固定、誰としてサインインするか、戻るまでの分数、表示のみ、そして固定ユーザーや開始画面が変わったときに別の開き方をする理由）です。キーもそのハッシュも決して含みません。ランタイムが止まっている間も動きます。 |
| `server_status` | 内蔵の [OPC UA サーバー](connector-opcua-server) の稼働状態を伝えます。オンかどうか（`enabled`）、動いているかどうか、稼働時間、endpoint の URL、つながっているクライアントのセッション、そして構成したアドレス空間の大きさです。`available` は Connector のランタイムが読んでいるかどうかを示し（サーバーがオフの間も止まっている間も読みます）、`serverError` はサーバーの直前の起動が失敗した理由を示します。`list` はサーバーが提供するもの、そして提供するすべてです。タグ、Logic 変数、警報、機器のコマンドごとに 1 行あり、それぞれに `access` と、クライアントに設定する `node` があります。空の間は `servesNothing` が true です。 |

## Connector：構成 {#connector--configure}

| ツール | 何をするか |
| --- | --- |
| `driver_capabilities` | このアプリが扱えるすべてのドライバーを、機器に必要な接続の項目、タグのアドレス指定の方式（自由記述のアドレスと型付きの項目のいずれか、または両方）、機器検出への対応とその引数、時間の範囲、そして扱える値の型とともに並べ、ポートを名指さない機器につなぐときのポートである `defaultPort` も添えます。`added` は、そのドライバーがステーションに追加されているか、つまり Connector のツリーに描かれるかを示します。`device_upsert`、`serial_line_upsert`、`mqtt_broker_upsert` で機器、シリアル回線、ブローカーを作ると、そのドライバーが追加されます。AVEVA PI と HTTP は、機器が話す転送方式のポートにつなぐので、`defaultPortByTransport` も出します。既定の HTTPS では 443、暗号化しない接続では 80 です。Generic serial and TCP は `genericSerialTcp` を加えます。通信方式、バイトの入力のしかた、メッセージの終わり方、チェックサム、タグの取得方法、フィルター、取り出し方、値の読み書きのしかた、そして 2 つの具体例です。Omron は `omron` を加えます。2 つのプロトコルそれぞれの機器の項目、アドレスの書き方、データ型と、FINS のトランスポートと範囲、書き込み、機器検出です。SCPI instruments は `scpi` を加えます。通信方式、このコンピューターに VISA があるか（`visa.installed`）、終端文字、書き込みの確認、初期設定コマンド、クエリと書き込みコマンドの書き方と応答の読み方、機器検出、そして 2 つの具体例です。NI-DAQmx は `niDaqmx` を加えます。測定ごとのチャネルの例、単位、欄、許すデータ型とアクセスです。製品に含められないものを機器が必要とするドライバーは `prerequisite` を加えます（Fluke NetDAQ では Visual C++ 2005 ランタイム、OPC DA では OPC Core Components（OpcEnum と OPC DA のプロキシ／スタブ）、NI-DAQmx では National Instruments の NI-DAQmx、SCPI では VISA の機器だけに必要な 64 ビットの VISA（NI-VISA または Keysight IO Libraries Suite、2 つのページつき）、Database では ODBC デバイス用の 64 ビットの ODBC ドライバーまたはデータ ソースで、デバイスごとに判断され（`perDevice` が true）、そのため `installed` は null のままで、足りないものはデバイス自身のエラーが伝えます）。このコンピューターにそれがあるか（`installed`、ステーションに追加されたドライバーの場合）、公式のダウンロード ページ、ファイル、インストールの方法、よくあるつまずき、その後に起きることです。SNMP は `snmp` を加えます。バージョンとそれぞれが受け取る資格情報、SNMPv3 のセキュリティレベルとプロトコル、値の種類ごとの型、ドライバーが名前を知っているすべての標準オブジェクトとその OID、読み取りと書き込みの動き、機器検出、そして 2 つの具体例です。File は `file` を加えます。簡単な手順、フォルダーとその中だけで動く制限、ファイル名の形、1 つのファイルか受信フォルダーか、書式とそのアドレスの文法、タグが読むものとその型、テキストの設定、読み取りと書き込みの動き、機器検出、そして 3 つの具体例です。Database は `database` を加えます。各データベースとその欄と自身のポート、暗号化、タグの 2 つの読み方と 2 つの書き込み方、値は `@value` か `@now` としてだけステートメントに入るという規則、待ち時間、データベースのユーザーについての助言、機器検出、そして 4 つの具体例です。エージェントが `device_upsert` や `tag_upsert` の前に読む地図です。 |
| `serial_line_list` | 保存されているすべてのシリアル回線を、無効なものや空のものも含めて、その変わらない id とドライバーとともに並べます。Modbus RTU の回線では、伝送モードと、設定した値、自動の値、実効の値も並べます。 |
| `serial_line_upsert` | シリアル回線を作るか、変わらない id で更新します。`driver` は回線が属するドライバーで、`ModbusRtu`（既定）、`GenericSerialTcp`、`Scpi`、`Omron` のどれかで、作成時に決まります。汎用ドライバー、SCPI ドライバー、Omron ドライバーの回線は `mode`、`responseTimeoutMs`、`minimumTransactionIntervalMs` を拒否します。名前と有効の状態はいつでも変えられます。通信の最小間隔も、有効なままで変えられます。シリアルのポート、ボーレート、シリアルの形式、伝送モード、応答のタイムアウトは、保存されている回線が無効な間だけ変えられます。 |
| `serial_line_delete` | 変わらない id で回線を削除します。まだ機器を持っている回線は、その配下のすべての機器とタグを消してよいと呼び出しがはっきり認めない限り、拒否されます。 |
| `mqtt_broker_list` | 保存されているすべての MQTT ブローカーを、無効のものや空のものも含めて並べます。変わらない id、応答する場所、通信方式、ユーザー名、クライアント ID、キープアライブ、トピックの接頭辞、機器の台数が付きます。パスワードが保存されているかどうかは伝えますが、パスワードそのものは決して返しません。発行の形式（`publishFormat`）と Sparkplug B のグループ（`sparkplugGroupId`）も付きます。 |
| `mqtt_broker_upsert` | MQTT ブローカーを作るか、変わらない id で更新します。名前、有効かどうか、ホスト（`mqtt://` や `mqtts://` のアドレス全体は分解されます）、ポート、TLS、ユーザー名、パスワード、クライアント ID、キープアライブ、発行のカードがトピックを提案するときの接頭辞（`publishTopicPrefix`。空の文字列で既定値に戻ります）です。渡した引数だけが変わります。ブローカーはホストがあるときだけ有効にでき、別のブローカーが使っているクライアント ID は拒否されます。接続の変更を保存すると、ブローカーの下のすべての機器が共有するセッションがつなぎ直されます。`publishFormat`（`Json` か `SparkplugB`）で発行のカードの出し方を、`sparkplugGroupId` でステーションのエッジノードの Sparkplug B のグループを選びます（空の文字列で `GanterLab` に戻り、`/`、`+`、`#` を含むグループは拒否されます）。 |
| `mqtt_broker_delete` | 変わらない id でブローカーを削除します。まだ機器を持っているブローカーは、その配下のすべての機器とタグを消してよいと呼び出しがはっきり認めない限り、拒否されます。 |
| `mqtt_publish_upsert` | ブローカーの[発行のカード](driver-mqtt#the-publish-card)に行を作るか（`brokerId` と `source`。タグは `Connector.` と別名、変数は `Variables.` とパス、警報は `Alarms.` とパス）、`id` で行を編集します。`topic` は省略できます。省略すると、ブローカーの接頭辞の下に信号源の名前から提案されたトピックが付き、空の文字列でもう一度それを取り直します。1 つのブローカーは同じ信号源も同じトピックも 1 回だけ発行します。トピックには + も # も使えず、$ で始めることもできません。行がほかのブローカーに移ることはありません。 `access` は既定の `ReadOnly` か `ReadAndWrite` で、`ReadAndWrite` を受けるのは書き込むドライバー上の書き込みアクセスのあるタグか内部値の変数だけです。このときステーションは、行のトピックに `/set` を続けたトピックに発行されたものを書き込みます（[書き戻し](driver-mqtt#writing-back)）。行のトピックを、別の行のトピックに `/set` を続けたものにはできません。Sparkplug B のブローカーでは行はメトリックとして発行され（`row.sparkplug`）、`ReadAndWrite` は Sparkplug B のコマンドが送った値を受け付けます。 |
| `mqtt_publish_delete` | 発行のカードの行を `id` で削除します。ステーションはその発行をやめますが、タグ、変数、警報には触れません。 |
| `device_upsert` | ドライバーと名前で機器を作るか更新します（ドライバーは作成のあと変えられません）。渡された引数だけが変わります。接続の項目はドライバーごとです。機器をフォルダーに移すと、その古いタグのアドレスへの参照がすべて書き換わります。Generic serial and TCP の機器は `transport` と、メッセージとチェックサムのカードの項目を受け取り、`serialLineId` は自分のドライバーの回線だけを受け付けます。回線上の機器はホスト、ポート、フォルダーを拒否します。Omron の機器は `omronProtocol`（`Fins` か `NjNx`）と、FINS では FINS のカードの `fins*` の項目を受け付けます。名前で読む機器はポートを拒否します。SCPI の機器は `transport`（`Tcp`、`Visa`、または自分のドライバーの回線の `serialLineId` を伴う `SerialLine`）、`visaResource`、`terminator`、`responseTimeoutMs`、`writeCheck`、`setupCommands` を受け付けます。NI-DAQmx の機器は、NI MAX が付けた名前である `daqmxDevice` を受け付けます。SNMP の機器は `snmpVersion`、`snmpCommunity`（SNMPv1、SNMPv2c）、`username`、`password`、`snmpSecurityLevel`、`snmpAuthProtocol`、`snmpPrivacyProtocol`、`snmpPrivacyPassword`（SNMPv3）、`responseTimeoutMs`、`snmpRetries` を受け付け、それぞれの秘密が設定されているかを返しますが、秘密そのものは返しません。File の機器は `fileFolder`、`fileName`、`fileMode`（`SingleFile` か `Inbox`）、`fileFormat`、`fileEncoding`、`fileSeparator`、`fileDecimal`、`fileHeaderRow`、`fileWrites` を受け付け、書き込みがオンなら `fileHeaderText` と `fileLineEnd` も受け付けます。`file.fileStatus` として、動作中のドライバーが読んでいるファイルと、そこから読み取ったものを返します。Database の機器は `databaseKind` を受け付け、サーバーでは `host`、`port`、`databaseName`（SQL Server ではさらに `databaseInstance`、`databaseWindowsSignIn`、`databaseEncryption`）、SQLite では `databaseFile`、ODBC では `databaseOdbc` を、`username` と `password` とともに受け付けます。`database` として、アドレスと、機器がまだユーザーを待っているかどうかを返し、パスワードは決して返しません。0 から 65535 の外のポートは拒否されます。0 は、ドライバーがつなぐポートを表します。変更はその場で、動いているサーバーに取り込まれます。 |
| `device_delete` | 機器とそのすべてのタグを削除します。変更はその場で、動いているサーバーに取り込まれます。 |
| `tag_upsert` | 機器の上にタグを作るか更新します。アドレス指定はドライバーごとです（自由記述のアドレスと型付きの項目のいずれか、または両方。Generic serial and TCP では取得方法、要求、フィルター、取り出し方、書き込みの項目、SCPI instruments では `address` としてのクエリ、`valueField`、`writeTemplate`、NI-DAQmx では `address` としての物理チャネルと、測定の `daqmx*` の欄、SNMP では数字か標準名で書いた `address` としての OID、File では `address` としての列かパス、`fileSource`、`fileRow` とその欄、`fileWriteMode` と `fileLineTemplate`。自由形式のテキストの値は汎用ドライバーの `value*` の欄を使い、新しいタグは読み取りのみで作られます。Database では値の列を `address` として、`databaseSource`、`databaseTable`、`databaseRow` とその欄または `databaseQuery`、タグが書き込むときは `databaseWriteMode` と `databaseCommand` を使い、新しいタグはやはり読み取りのみで作られます）。応答は、組み立てられたバス上のアドレスと、`tag_read` のための別名を返します。無効な読み取りの段階も含みます。NaN のときの処理は数値のタグで、読み取りに失敗したときの見せ方はステーションが読むすべてのタグで扱い、そのうち `Replace` だけが数値とブールのタグに限られます。タグの新しい型が受け付けない `Replace` がすでに保存されていれば、代わりに既定が保存されます。型が数値でなくなると NaN のときの処理は `PassThrough` に、型が String、DateTime、Guid、ByteString になると読み取りに失敗したときの見せ方は `ShowError` になります。 |
| `tag_delete` | タグを削除します。その場で取り込まれます。 |
| `server_start` | 内蔵の OPC UA サーバーをオンにして起動します。その行の有効化と同じです。一覧を提供し、`server_stop` までは再起動をまたいでオンのままです。すでに動いていれば、何もしません。Connector 自身が動いていなければ、先にそれを起動して今の構成を実体化します。 |
| `server_stop` | サーバーをオフにして穏やかに止めます。無効化と同じです。OPC UA クライアントは切断され、`server_start` がもう一度オンにするまで何も公開しません。Connector は読み続け、タグの読み取り、Logic、記録も続きます。 |
| `server_restart` | オンの間に、サーバーだけを止めてから起動します。その間も Connector は読み続けます。オフのサーバーは拒みます。オンにするのは `server_start` だからです。機器とタグの変更は `connector_refresh` で反映します。 |
| `server_list_upsert` | OPC UA サーバーの[一覧](connector-opcua-served-nodes)に行を作るか、`id` で行を更新します。`source` はタグ（`Connector.` とエイリアス）、変数（`Variables.` とそのパス）、警報（`Alarms.` とそのパス）、機器のコマンド（機器のアドレス、ドット、コマンドの名前と `()`）のいずれかを指定し、信号源は一覧に 1 度しか載せられません。`access` は ReadOnly（どの新しい行でも既定）か ReadAndWrite で、ReadAndWrite を受けるのは書き込みアクセスのあるタグと内部値の変数だけです。そのときクライアントの書き込みは Logic の書き込みの漏斗を通り、クライアントのセッションとともに診断ログに記録されます。答えには行とその `node` が入ります。 |
| `server_list_delete` | `id` で一覧の行を削除します。クライアントはそのノードを見つけられなくなり、行が提供していた信号源には触れません。 |
| `modbus_server_configure` | Modbus サーバーをオンかオフにするか（`enabled`）、ページと同じように別の `port`（1 から 65535）へ移します。Web サーバー、エージェントアクセス、OPC UA サーバーに設定されたポートと、ほかのプログラムが押さえているポートは拒否され、Windows ファイアウォールが変更されることはありません。オンにすると、ポートに届くどのマシンもマップが提供するものを読めます。`modbus_server_status` と同じくサーバー全体を返します。 |
| `station_broker_configure` | ページと同じように、ステーション自身の MQTT ブローカーをオンかオフにし（`enabled`）、別の `port` へ移し、`authentication`、`username`、`password` を変えます。順序はポート、認証、そしてオンかオフです。Web サーバー、エージェントアクセス、OPC UA サーバー、Modbus サーバーに設定されたポートと、ほかのプログラムが使っているポートは拒まれます。Windows ファイアウォールは変えません。オンにすると、MQTT ドライバーにブローカー「このステーション」が加わります。`station_broker_status` と同じく、ブローカー全体を返します。 |
| `modbus_map_upsert` | Modbus サーバーのレジスターマップに行を作るか、`id` で行を更新します。`source` はタグをアドレス（`Connector.` と、`connector_browse` が並べるとおりのエイリアス）で、変数（`Variables.` とそのパス）、または警報（`Alarms.` とそのパス。常に ReadOnly で、`alarmValue` が示す状態 Active、Acked、State のいずれかを提供します）で指定します。`registerClass`（既定は HoldingRegister）、`register`（0 から数えます）、`type`（既定は Float、コイルとディスクリート入力では Boolean）、String の `length`、`mostSignificantByte` と `mostSignificantWord` は、Modbus のタグと同じ項目と規則に従います。`access` は ReadOnly（どの新しい行でも既定）か ReadAndWrite で、ReadAndWrite を受けるのは保持レジスターとコイルだけ、しかも書き込みを受ける信号源（書き込みアクセスのあるタグ、内部値の変数）に限られます。新しい行には `register` と `source` が必要です。マップが拒否した行には、理由とヒントが返ります。 |
| `modbus_map_delete` | レジスターマップの行を `id` で削除します。以後、そのレジスターを読むクライアントは例外 02 を受け取ります。その行が提供していたタグや変数には手を付けません。 |
| `remote_access_device_update` | リモートアクセスのページの行と同じように、構成済みの端末の名前、開始画面（ID か名前で指すダッシュボード、外すなら空で、外すと固定も外れます）、固定、操作のない分数（戻らないなら 0）、表示のみを変えます。端末が誰としてサインインするかはここでは変えません。それにはローカルユーザーの管理を持つ人が要ります。端末の構成と登録の解除はステーションの画面で行い、ツールでは決して行いません。`remote_access_devices` が一覧にするとおりの端末を返します。 |

## Connector：操作 {#connector--operate}

| ツール | 何をするか |
| --- | --- |
| `connector_refresh` | 動いているサーバーを、構成した機器に合わせて差分で整えます（追加、削除、作り直し）。完全な再起動は行いません。変更を当てる、より軽いやり方です。 |
| `device_discover` | ドライバーの機器検出のスキャンを走らせ、候補をそのタグとともに返します。何も保存しません。プロトコルが本当のスキャンに対応しているドライバーだけが参加します。すでに存在する候補には、その印が付きます。SNMP のスキャンは、`snmpCommunity` を添えた `target` か、設定済みの機器である `snmpDevice` をたどり、SNMPv3 エージェントは後者でスキャンします。File のスキャンは、設定済みの機器である `fileDevice`、またはスキャンのために入力した `fileFolder`、`fileName`、`fileMode`、`fileFormat` を読みます。Database のスキャンは、設定済みの機器である `databaseDevice` と、省略可能な `databaseTables`（テーブル名か `*` を使うパターン）を読みます。ドライバーのスキャンの範囲カードが拒否する `target` や、スキャンに必要なのに渡されない `target` は、どう書くべきかを添えて拒否されます。値、テーブル、オブジェクトの上限で止まった Database、File、SNMP のスキャンは、残りを見るために渡すものを添えて `cut` でそう伝えます。すべてを読んだリストには `cut` がありません。 |

## Logic：読み取り {#logic--read}

| ツール | 何をするか |
| --- | --- |
| `logic_browse` | 最上位を根とする Logic のアドレス空間、つまりすべての式が読むのと同じドットのツリーを見て回ります。System、Server、Connector、Variables、Alarms、Process、Assets です。操作者のフォルダーは、本物のアドレスの段です。子のポイントには、実時間の値と品質が含まれ、Connector のタグのポイントは、`logic_read` が報告するのと同じ `substitution` と `communicating` も持ちます。 |
| `logic_read` | ドットのアドレス（たとえば `Variables.Setpoint`）で 1 つのポイントを読み、実時間の値と品質を返します。Connector のタグのポイントは、`tag_read` が報告するのと同じ `substitution` と `communicating` も持ち、代替値や、応答をやめた機器からの読み取りと、実時間の測定値とは、これで見分けます。ほかのポイントはどちらも持ちません。途絶えた読み取りは、そこでは失敗した読み取りとして読めます。 |

## Logic：構成 {#logic--configure}

upsert は部分的です（渡さなかった引数はそのままです）。重ねた下書きはどれも、[Logic](logic) の編集画面と同じ検証を通ります。正しくない下書きは拒否され、途中まで適用された状態は残りません。

| ツール | 何をするか |
| --- | --- |
| `variable_upsert` | 変数を作るか更新します。式（アドレス空間の上の、読み取り専用の JavaScript の式 1 つ）か、内部値（書き込める、必要なら保持する値）です。名前が鍵で、それを変換したものがアドレスです。フォルダーの引数がそれを入れる場所を決め、古いアドレスへの参照をすべて書き換えます。 |
| `variable_delete` | パスで変数を削除します。保持していた値も一緒に消えます。それに結び付いていたチャネルは、取得元を失います。 |
| `action_upsert` | アクションを作るか更新します。書き込みの動詞をちょうど 2 つ持つ JavaScript の文の集まりで、内部値の変数への代入と、工業値としてのタグへの書き込みです。静的に検証されるだけで、保存のときに実行されることはありません。 |
| `action_delete` | 名前でアクションを削除します。それに結び付いていたトリガーは、何もしなくなります。 |
| `trigger_upsert` | 周期のトリガーを作るか更新します。`intervalMs`（最小 100）ごとに、結び付いたアクションがロジックのキューの上で発火します。実行が残っている間に来た発火は飛ばされます。アクションとの結び付きは緩く、名前によります。 |
| `trigger_delete` | トリガーを削除します。結び付いていたアクションには触れません。 |
| `alarm_upsert` | 警報を作るか更新します。ブール値の条件の式、優先度（Critical/High/Medium/Low）、オンとオフのディレイ、確認が必要かどうか、そして知らせ方です。条件や時間を変えて保存すると、動いている状態の移り変わりが戻ります。 |
| `alarm_delete` | パスで警報を削除します。出ている知らせは、先に消されます。 |
| `logic_folder_upsert` | 1 つの節（Variables、Alarms、Actions、Triggers。最大 3 段）の整理のためのフォルダーを、作り、名前を変え、入れ直します。Variables と Alarms では、フォルダーの道すじがアドレスの一部なので、名前の変更と移動は、その下のすべての式、スクリプト、条件、ダッシュボードのバインドを書き換えます。 |
| `logic_folder_delete` | フォルダーを削除します。中にあったものは何も壊れません。項目と下位フォルダーは 1 段上に入れ直され、参照は書き換えられます。移り先で名前がぶつかるときは、削除が拒否されます。 |

## Logic：操作 {#logic--operate}

ここにあるものはすべて、ページが乗るのと同じロジックの書き込みの経路に乗り、出どころ **MCP** として記録されます。書き込みはロジックを離れて、その機器自身の送り出しのキューへ渡され、答えを待つのは呼び出したツールのほうです。ですから返ってくるのは、送ったという事実ではなく、その値がどうなったかです。

| ツール | 何をするか |
| --- | --- |
| `variable_write` | 内部値の変数に値を書き込みます（その出力の型に合わせられ、保持する設定なら保持されます）。式の変数は計算される値なので、書き込みを拒みます。 |
| `tag_write` | 書き込めるタグに工業値を書き込みます。そのタグの値の変換経路を逆にたどり、機器の型に合わせ、設備に書き込みます。応答は、書き込みが通ったあとにタグが示すもの、つまり値、品質、`substitution`、`communicating` を、`tag_read` が報告するのと同じ形で返します。書き込みは受け取ったものの読み取りへの応答をやめた機器は、これでまだ応答している機器と見分けられます。読み取り専用のタグと読み取り専用のドライバーは、理由を添えて拒否されます。 |
| `action_run` | 1 つのアクションをアクションのレーンの上で実行し、その結果と所要時間を返します。無効なアクションは、走らずに失敗します。 |
| `alarm_ack` | 1 つの警報を確認します。操作者の応答にあたるもので、待っているものが何もなければ何もしません。 |
| `alarm_ack_all` | 応答を待っているすべての警報を、1 つのロジックのキューの項目として確認し、それぞれの遷移を記録します。 |

## ログ：読み取り {#logs--read}

| ツール | 何をするか |
| --- | --- |
| `logs_read` | プログラム全体の実時間のログの流れ（[イベント](events)のコンソールと同じものです）を、最低の重大度（Debug/Information/Warning/Error。既定は Information）、領域（App/Server/Connector/Logic/Process/Dashboard/Agent/Licensing）、コンポーネント、そして文脈の部分一致で絞って読みます。新しいものから返します（既定 100 件、最大 500 件）。エージェントの操作は、Agent の領域に記録されます。 |
| `event_history_read` | 再起動をまたいで残る、運転のイベントの時系列を読みます。警報の遷移、発生記録の遷移、インターロックの遷移です。種類（Alarm/Occurrence/Interlock）、両端を含む UTC の期間、そして水準（警報の優先度、発生記録の重大度、インターロックの遷移）で絞れます。新しいものから、既定 100 件、最大 500 件です。厳密に読み取り専用で、記録を消すことも削除することもできません。 |

## Process：読み取り {#process--read}

| ツール | 何をするか |
| --- | --- |
| `process_models` | [Process](process) のモデルを丸ごと並べます。チャネル、共有のグループ、解決した配線と実行の状態を持つユニット、手順、操作パネル、レシピ、判定、発生記録、そして全体共通のレポートのテンプレートのライブラリです。エージェントが何かを始める前に読む地図です。 |
| `process_runs` | 実行記録を、新しいものから並べます。id、名前、状態、総合判定、何が走ったか、誰が始めたか（Station/User/Automation/Agent）、時間、サイクルの進みです。実行中のものだけに絞ることも、名前やメタデータの値（シリアル番号、ロットなど）の一部で探すことも、件数を区切ることもできます（既定 50 件）。 |
| `process_run` | id で 1 件の実行記録の、固定された記録の全体を読みます。スナップショット、メタデータ、サンプルの件数を添えた判定済みの判定基準、発生記録の発生区間とイベント、実行時の値としてのレシピの書き込み、コメント、そして固定されたレポートとラベルの成果物と、その印刷の試みです。必要ならデータログの行数と時間の範囲も計算します。 |
| `process_samples` | 実行記録が記録したサンプルを、記録中でも終了後でも読みます。サンプルが 500 件までの区間は、記録されたとおりに返ります。サンプルごとに 1 点で、チャネルごとに 1 つの値です。それより長い区間は要約されて返ります。その長さを 500 の等しい区切りに分け、区切りごとに各チャネルの最小、最大、平均を載せるので、ピークは最大に残ります。応答はどちらの形かを示し、要約なら区切り 1 つの長さと、区切りがまとめたサンプルの件数も示します。`fromUtc` と `toUtc` で区間を狭められ、十分に狭い区間は記録されたとおりに返ります。`channels` は名前を挙げたチャネルだけを読みます。 |
| `unit_status` | ユニットの実時間の状態を伝えます。実行中かどうか（実行中ならその実行記録も）と、それぞれのチャネルの後ろにある今の工業値を、記録せずに読みます。 |

## Process：構成 {#process--configure}

| ツール | 何をするか |
| --- | --- |
| `process_view_configure` | モデルの操作パネルをちょうど 1 つ構成します。その隣に描く印と、View のページに出すかどうかです。Process のまとまりで MCP から書き換えられるのは、これだけです。残りは Process のページで編集します。 |

## Process：操作 {#process--operate}

エージェントが開始、終了、コメントした実行は、行った相手として**エージェント**を残します。試験台でたまたまサインインしている操作者の名前が付くことは、決してありません。

| ツール | 何をするか |
| --- | --- |
| `process_snapshot` | 手順の外で、ユニットのデータログの行を 1 つ取得します。呼ぶたびに、判定のない（総合判定 None の）、すでに完了した即時の実行記録が[履歴](histories)に新しくできます。 |
| `process_evaluate` | データログの行を 1 つ取得し、判定に照らして判断します。完了した即時の実行記録を作り、その総合判定を返します。 |
| `process_recipe_apply` | 即時のレシピを、Process の書き込みの経路と信号源のロックを通じて、ユニットに 1 度だけ当てます。設備に指令を出しますが、実行記録は作りません（書き込みは記録されます）。時間に沿ったレシピは拒否されます。 |
| `process_start` | ユニットの上で手順の実行を開始します。その手順が尋ねるメタデータの項目のための JSON のオブジェクトを添えます。渡した値はすべて記録されるか、何も始まらないかのどちらかです。手順が尋ねない項目、連番の項目への値（開始のときにアプリが組み立てます）、二度書かれた項目のどれかがあれば、開始は拒否されます。必須のメタデータが足りない、あるいは正しくない、ユニットがすでに実行中である、共有チャネルのロックがぶつかる、のいずれかでも同じです。新しい実行記録の id を返します。 |
| `process_stop` | 実行中の実行記録を止めます。終了処理の区画、固定された履歴のスナップショット、計算された総合判定が行われます。 |
| `process_hold` | 実行記録の時間に沿ったプロファイルを、最後の設定値で一時停止します。データログは記録を続けます。 |
| `process_resume` | 一時停止した実行記録の、時間に沿ったプロファイルを再開します。 |
| `process_abort` | 実行中か一時停止中の実行記録を中止します。終了処理が走り、スナップショットが書かれ、状態は中止に、総合判定は不合格になります。 |
| `process_comment` | 実行記録のファイルに、時刻付きのコメントを足します。実行中なら時系列のメモ、終わったあとなら実行後のメモです。 |
| `process_report` | 終わった実行記録の PDF のレポートを作る（あるいは作り直す）か、そのファイルの道すじを返します。全体共通のライブラリのテンプレートを名指しすると、その手順に設定されたものより優先されます。どちらもなければ、すべての節を含む既定の様式が使われます。実行中は拒否されます。 |
| `process_run_delete` | 記録された実行記録を永久に削除します。履歴の索引の指し先と、実行記録ごとのデータベースのファイルです。実行中は拒否されます。構成には触れません。 |

## ダッシュボード：構成 {#dashboard--configure}

これらのツールが読み取り、返すロールの名前は、どのステーションでも英語です。`Not signed in`、`Viewer`、`Operator`、`Maintainer`、`Developer` で、画面に出る言葉が何であっても変わりません。`Admin` は並べられません。いつでもすべてのダッシュボードを見るからです。管理者が名前を変えたロールは、その人が打ち込んだ名前で呼ばれます。

| ツール | 何をするか |
| --- | --- |
| `dashboard_list` | ダッシュボード（あるいはモデルを名指しすると、そのモデルの画面）を並べます。グリッドの大きさ、フォルダー、アイコン、起動時の印、ロールごとの見え方、そして位置、レイヤー、プロパティの JSON を持つすべてのコンポーネントに加えて、保存されているすべての接続網です。コンポーネントの種類のカタログも、種類ごとの既定の大きさと既定のプロパティの一式とともに返します。 |
| `dashboard_upsert` | 名前でダッシュボードを作るか更新します。グリッドの大きさ（コンポーネントがはみ出す縮小は拒否されます）、View のページの表示画面の欄にあるフォルダーとアイコン、起動時の印、全画面でのステータスバーの見え方、そしてロールごとの見え方です。モデルを名指しすると、代わりにそのモデルの画面を指します。開いているダッシュボードのページは、その変更をすぐ映します。 |
| `dashboard_delete` | 名前でダッシュボードとそのコンポーネントを削除します。モデルを名指しすると、代わりにそのモデルの画面を削除します。 |
| `component_upsert` | 種類でコンポーネントを足すか（別に言わなければ、その種類の既定の大きさで、空いている最初のます目に置きます）、id で更新します。置き場所はグリッドの中でなければなりません。重なりは許され、描く順は z のレイヤーが決めます。プロパティの JSON は、その種類の型付きの一式です。モデルを名指しすると、代わりにそのモデルの画面を指すので、そこで作った画面をここで組み立てられます。 |
| `component_delete` | id でコンポーネントを取り除きます。モデルを名指しすると、代わりにそのモデルの画面を指します。 |
| `connection_upsert` | シンボルの接続点を 2 つ、型付きの接続網でつなぎます。型、役割、向きは、キャンバスの編集画面とまったく同じようにシンボルのカタログから解決します。両端が違う型に解決するときは、型のない接続をはっきり許さない限り失敗します。すでに接続を持っている接続アンカーは拒否されます。モデルを名指しすると、代わりにそのモデルの画面を指します。 |
| `connection_delete` | id と、期待している版で接続網を 1 つ取り除くので、古い前提の削除が新しい編集を上書きするのではなく、拒否されます。モデルを名指しすると、代わりにそのモデルの画面を指します。 |

## 画面：自動操作 {#ui--automate}

これらのツールは、本物のアプリケーションのウィンドウを動かします。エージェントが、まねごとではなく操作者が見る画面そのものを確かめられるように、あります。操作は動いているシェルに送られるので、正しい進め方は、身ぶり 1 つごとに `ui_screenshot` を続けてその結果を見ることです。当てはまるものが複数あるときは、当てずっぽうの押下ではなく候補の一覧が返ります。

| ツール | 何をするか |
| --- | --- |
| `ui_state` | シェルの状態を伝えます。今のページ、行けるページ、テーマ、ウィンドウの大きさと見え方、そしてこの実体が画面を出している loopback のアドレスです。何よりも先に呼ぶ、見当をつけるための呼び出しです。 |
| `ui_navigate` | シェルのページを、どのステーションでも英語である安定した名前で開きます：`View`、`Process`、`Logic`、`Connector`、`Users`、`Validation`、`Events`、`Agent`、`Settings`、`Account`。ステーションの言語でナビゲーションバーが表示している名前も受け付けます。 |
| `ui_screenshot` | 画面に出ているとおりのウィンドウを PNG のファイルに取得し、その絶対の道すじを返します。通知領域に隠れているときは、先にウィンドウを戻します。ウィンドウの全体ではなく、名前の付いた画面の区画（一意で、見えている `data-doc-region` の領域）を 1 つ取得することもできます。区画がない、隠れている、複数当てはまるときは、黙って全体の取得に落ちるのではなく、見えている区画を並べて失敗します。 |
| `ui_scroll` | 今のページの主なスクロールの区画を、上端か下端へ、あるいは画面 1 枚分ずつスクロールし、その位置を返すので、長いページを端から端まで見渡せます。 |
| `ui_set_theme` | ステーションのテーマ（システム、明るい、暗い）を当てます。ステーションのウィンドウが描かれるテーマで、自分のテーマを選んでいないブラウザーはそれに従います。自分のテーマを選んだブラウザーはそれを保ちます。ステーションのウィンドウでテーマのキーを使って選んだときとまったく同じように保存されるので、行儀のよいエージェントは終わったら元の値に戻します。 |
| `ui_resize` | 元の大きさに戻したウィンドウを、機器に依らない単位で変えます。ウィンドウの最小の大きさに収められます。狭い配置を確かめるのに便利です。 |
| `ui_click` | 見えているボタン、リンク、チェックボックス、切り替えのうち、文字が一致するものを押します。チェックボックスと切り替えは、その項目の名前で見つけ、結果は落ち着いた状態を伝えます。複数当てはまるときは、1 つを選ばずに候補を返します。 |
| `ui_set_text` | 項目の名前で見つけた文字の入力欄に値を書き込み、人が入力したときと同じようにバインドを確定します。 |
| `ui_select` | 見えている文字で項目を選びます。スラッシュで区切った道すじはツリーをたどり、途中を展開していきます。区切りが 1 つのときは、今のページの一覧、タブ、コンボボックスの項目、グリッドの行にも当てはまります。 |

## バックアップ：管理 {#backups--manage}

| ツール | 何をするか |
| --- | --- |
| `backup_create` | 構成のデータベースのスナップショットを、動かしたままバックアップのフォルダーに作ります。メモを付けることもできます。記録された実行記録は構成の外にあるので、バックアップにも復元にも触れられません。 |
| `backup_list` | 構成のバックアップ（ファイル名、作成の時刻、大きさ、メモ）と、すでに予約されている復元があればそれも並べます。 |

**バックアップを削除するツールは、意図して置いていません。**残す残さないは操作者だけのもので、[バックアップ](settings-backups)のページで決めます。

## バックアップ：復元 {#backups--restore}

| ツール | 何をするか |
| --- | --- |
| `backup_restore` | **次回**のアプリケーションの起動で、今の構成をバックアップで置き換えるように予約します。動いているアプリでは何も変わりませんし、このツールがアプリを再起動することもありません。置き換えられる構成は、先に自動でスナップショットが取られますし、操作者は再起動までの間、設定から予約された復元を取り消せます。記録が進んでいる間は拒否されます。 |

## 設定：管理 {#settings--manage}

| ツール | 何をするか |
| --- | --- |
| `settings_read` | ステーションの表示と起動終了の設定を読みます。日付、時刻、数値の形式、小数の桁数、テーマ、閉じたときに通知領域へ入れるかどうか、クラッシュレポートの印です。 |
| `localization_set` | 表示の設定を更新します（部分的で、渡さなかった引数はそのままです）。表示だけの話で、保存、ドライバーの入出力、記録は、常に不変の形式を使います。 |
| `asset_list` | 利用者の素材（画像、アイコン、色）を、id、値、道すじとともに並べます。 |
| `asset_import` | ローカルのファイルの道すじから PNG か JPG を、アプリが持つ素材のライブラリに取り込み、新しい素材の id を返します。バイトは写されるので、そのあと元のファイルを動かしてもかまいません。 |
| `symbol_validate` | インラインのシンボルの内容（生の SVG か v2 のパッケージ）を、何も保存せずに検証します。取り込みとまったく同じことを試すだけで、エラー、無害化の警告、そして何が認識できたかのまとめを返します。このツールの説明は、[持ち運べるシンボルの決まり](ganter-symbols)の全体を運びます。 |
| `symbol_import` | インラインのシンボルの内容を、新しいユーザーシンボルの素材として取り込み、その id と `user:<guid>` の参照を返します。必ず新しい素材を作り、名前がぶつかるときは自動で接尾辞が付きます。 |

## 報告：下書き {#reports--draft}

| ツール | 何をするか |
| --- | --- |
| `report_draft` | エージェントが書いた内容を記入した状態で、ステーションのウィンドウに[ご報告のフォーム](account-feedback#a-report-drafted-by-an-agent)を開きます。`kind`（`DriverRequest`、`Bug`、`Suggestion`）、`summary`（120 文字までの 1 行。長すぎるものは切らずに拒否します）、`details`（任意）を受け取ります。タイトルバーの報告のボタンと同じように、先にウィンドウをキャプチャし、そのキャプチャにチェックを入れてご報告に添えます。フォームが開いたことと、何も送っていないことをすぐに答えます。 |

このツールは送信しません。ステーションにいる人がご報告を読み、必要なら直して「送信」を押します。結末はステーションのステータスバーに出て、エージェントには返りません。この範囲がオンの間、サーバーはすべてのエージェントに、Ganter Lab にないドライバーが必要なとき、プログラムの不具合に見える形で呼び出しが失敗したとき、改善を頼まれたときに、ご報告を申し出るよう伝えます。`driver_capabilities`、`device_upsert`、`device_discover` の説明も同じことを言います。

`reason` を付けて拒否し、そのときは何も開かず、何もキャプチャしません。

| `reason` | いつ |
| --- | --- |
| `not_permitted` | ステーションにサインインしているロールが「Ganter へのご報告の送信」を持っていないとき。 |
| `no_station_window` | フォームを開く自分のウィンドウがステーションにないとき。ページをブラウザーにだけ配るホストです。 |
| `no_credential` | セッションが送れないとき。サインインしていてもいなくてもデモのプロファイル、または資格情報を持っていない、ステーションの Ganter アカウントへのサインインです。 |
| `form_busy` | ステーションでご報告のフォームが開いているか、ご報告のキャプチャか送信の途中のとき。 |
| `draft_in_progress` | 人が書いている途中のご報告がフォームにあるとき。誰も変えていない、エージェントの前の下書きは、代わりに置き換えます。 |

Ganter アカウントにサインインしていないステーションは拒まれません。フォームが開き、ご報告がアカウントなしで送られるので Ganter から返信できないことを伝えます。

何かを変えるほかのツールと同じく、ランタイムが止まっている間は `Runtime stopped` と答えます。