<commit_before># MarioNetDevice における外部アプリケーションインターフェイス

## 概要

MarioNetDeviceでは端末固有の制御などを外部アプリケーションで行えるようにしています。
インターフェイスはZeroMQを通じて提供されるため、MQTT通信部分やGPIO、PLCを扱う部分はMarioNetDevice本体にまかせ、外部アプリケーション側では言語やフレームワークの種類に依存する事なく各種イベントの受信、コマンドの発行を用いてシステムを構築する事が可能です。

外部アプリケーションにはZeroMQを通して次の２つのイベントが転送されます。

* MQTT Subscribeイベント
* GPIO,PLCなどのアナログ・デジタルI/Oイベント

また、外部アプリケーション側からMarioNetDeviceに対してGPIO出力やMQTT Publishなどのコマンドを発行する事ができます。

## Subscribeイベントの待機

### MarioNetDeviceの提供するZeroMQポートへのconnect

外部アプリケーションからMarioNetDeviceのイベントを受け取るには、ZeroMQポートにconnectする必要が有ります。connectする為に必要な情報は下記の通りです。

* ZMQ Endopoint
    * tcp://127.0.0.1:6788

### Subscribe

MarioNetDeivce側から送られてくるデータのフォーマットは以下の通りです。
データフォーマットは5つのパートに分かれ、各パートは":@:"で区切られます。

__ [イベント種別]:@:[送信元デバイスID]:@:[データ種別]:@:[データ番号]:@:[ペイロード] __

**********************************************

イベント種別は以下の2種類です。

* I/Oイベント: "io"
* Subscribeイベント: "sub"

**********************************************

データ種別は以下の２種類です。

* デジタルデータ: "digital"
* アナログデータ: "analog"

**********************************************

データ番号は、受信データの送信元デバイス内でデータに割り振られた番号です。例としてアナログ0番目の場合は通常"0"となります。

また、デジタル信号の場合は8点毎に割り振られたデジタルポート番号となります。
例として、デジタル0番目から7番目までのデータは、”ポート0”のデータとして[0,0,0,1,1,1,0,1]のように8点分のデジタルビットの配列として送られます。

**********************************************

ペイロードは各種データの実際の値、および付帯情報をJSONフォーマットで表現したものです。
フォーマットはデータ種別毎に異なります。

アナログデータ
```json
{
  "type": "ai",         // ai固定
  "id": "my-deivce-id", // デバイスID
  "no": 2,              // アナログ番号
  "val": 521            // アナログ値
}
```

デジタルデータ
```json
{
  "type": "di",               // di固定
  "id": "my-deivce-id",       // デバイスID
  "no": 2,                    // デジタルポート番号
  "status": [0,0,0,1,1,1,0,1] // アナログ値
}
```<commit_msg>fix document<commit_after># MarioNetDevice における外部アプリケーションインターフェイス

## 概要

MarioNetDeviceでは端末固有の制御などを外部アプリケーションで行えるようにしています。
インターフェイスはZeroMQを通じて提供されるため、MQTT通信部分やGPIO、PLCを扱う部分はMarioNetDevice本体にまかせ、外部アプリケーション側では言語やフレームワークの種類に依存する事なく各種イベントの受信、コマンドの発行を用いてシステムを構築する事が可能です。

外部アプリケーションにはZeroMQを通して次の２つのイベントが転送されます。

* MQTT Subscribeイベント
* GPIO,PLCなどのアナログ・デジタルI/Oイベント

また、外部アプリケーション側からMarioNetDeviceに対してGPIO出力やMQTT Publishなどのコマンドを発行する事ができます。

## Subscribeイベントの待機

### MarioNetDeviceの提供するZeroMQポートへのconnect

外部アプリケーションからMarioNetDeviceのイベントを受け取るには、ZeroMQポートにconnectする必要が有ります。connectする為に必要な情報は下記の通りです。

* ZMQ Endopoint
    * tcp://127.0.0.1:6788

### Subscribe

MarioNetDeivce側から送られてくるデータのフォーマットは以下の通りです。
データフォーマットは5つのパートに分かれ、各パートは":@:"で区切られます。

```
<イベント種別>:@:<送信元デバイスID>:@:<データ種別>:@:<データ番号>:@:<ペイロード>
```

**********************************************

**イベント種別**

イベント種別は以下の2種類です。

* I/Oイベント: "io"
* Subscribeイベント: "sub"

**********************************************

**データ種別**

データ種別は以下の２種類です。

* デジタルデータ: "digital"
* アナログデータ: "analog"

**********************************************

**データ番号**

データ番号は、受信データの送信元デバイス内でデータに割り振られた番号です。例としてアナログ0番目の場合は通常"0"となります。

また、デジタル信号の場合は8点毎に割り振られたデジタルポート番号となります。
例として、デジタル0番目から7番目までのデータは、”ポート0”のデータとして[0,0,0,1,1,1,0,1]のように8点分のデジタルビットの配列として送られます。

**********************************************

**ペイロード**

ペイロードは各種データの実際の値、および付帯情報をJSONフォーマットで表現したものです。
フォーマットはデータ種別毎に異なります。

アナログデータ
```json
{
  "type": "ai",         // ai固定
  "id": "my-deivce-id", // デバイスID
  "no": 2,              // アナログ番号
  "val": 521            // アナログ値
}
```

デジタルデータ
```json
{
  "type": "di",               // di固定
  "id": "my-deivce-id",       // デバイスID
  "no": 2,                    // デジタルポート番号
  "status": [0,0,0,1,1,1,0,1] // アナログ値
}
```
{'fraction_non_alphanumeric': 0.22666666666666666, 'fraction_numerical': 0.02434782608695652, 'mean_word_length': 6.07172131147541, 'pattern_counts': {'":': 18, '<': 8, '<?xml version=': 0, '>': 8, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2707123', 'n_tokens_mistral': 2393, 'n_tokens_neox': 2305, 'n_words': 135}