apis-web仕様書
November 25, 2020 · View on GitHub
Rev 0.67
目次
6.1.Emulator Emulator /get/log
1.用語・略語
| 用語 | 説明 |
|---|---|
| apis-main | 自律分散制御を可能にするSony CSLが開発した電力相互融通ソフトウェアである。 (詳細はapis-main仕様書を参照。) |
| Grid Master | apis-mainに含まれるServiceの名称でDC Gridを制御し電力融通を実現する。 |
| Hazelcast | 複数のマシンにDataを分散し並列処理を行うことでアプリケーションを高速化するインメモリ分散コンピューティング運用ライブラリである。 |
| Vert.x | 負荷分散プログラムのフレームワーク。Hazelcastライブラリを利用してEvent Busをクラスタ化しネットワーク上で負荷分散処理を行う。 |
| Verticle | Vert.xのプログラムの最小単位をVerticleと呼ぶ。 |
| Event Bus | Vert.xのプログラムの最小単位をVerticleと呼び。そのVerticle間でお互いに通信するための非同期インターフェースをEvent Busと呼ぶ |
| Main Controller | apis-mainがインストールされた各ノードの状態や電力融通状態をリアルタイムで表示するSony CLSが開発したWebアプリケーションのソフトウェアである。 |
| Budo | 自律分散制御検討前の集中管理制御の自動電力融通ソフトウェアの名称である。 |
2.概要
apis-webは電力融通の開発や運用保守のためのWebサービス(可視化サービスなど)に、電力融通に関わる情報を提供するソフトウェアである。apis-webはEthernet等のコミュニケーションラインに接続された複数のノード上のapis-mainから情報を取得するためにVert.x, Hazelcastのフレームワーク機能を用いてクラスタを構築する。そしてクラスタ内に存在するGrid Masterから全ノードのDC/DC Converter、Battery RSOC等のハードウェア情報を取得し、任意のノードから電力融通情報を取得する。また、Debug用に電力融通やErrorを生成する機能も有する。
図2-1
3.ソフトウェア構成
3.1. ソフトウェアアーキテクチャ
図3-1はapis-webのソフトウェアアーキテクチャを示した図である。Linux OS上にJDK(Java Development Kit)、その上にイベントドリブンの負荷分散プラットフォームであるVert.xとインメモリ分散コンピューティングのHazelcastの2つのフレームワークを使用してapis-webを動作させている。 (動作確認済みOSSソフトウェアのVersionは12. OSSライセンス参照)
図3-1
3.2ソフトウェア構成
apis-webは図3-2で示すように以下の3つのServiceを提供する。
-
Budo Emulator
Main Controller等のWebアプリケーションに対してクラスタ内で発生した電力融通情報を提供し、apis-mainの全ノード及び個別ノードに対して電力融通の実行/停止等の設定変更を行うことが可能なServiceである。Main Controller等はapis-webから受け取った情報を元にクラスタ内の電力融通の状況を可視化する。(“Emulator”の名称はBudo情報の提供を模倣する機能から付けられた。) -
Emulator Emulator
Main Controller等のWebアプリケーションに対し、各apis-mainによって取得された全ノードのDC/DC ConverterやBattery等のハードウェア情報を提供するServiceである。(“Emulator Emulator”の名称は実機のハードウェア情報をMain Controller等のWebアプリケーションに提供するためのServiceを開発する際に、既に開発されていたDC/DC ConverterやBattery等のハードウェアEmulatorが持つWeb APIを流用したことによりWebアプリケーション側から見るとEmulatorを模すServiceになったことからEmulator Emulatorと付けられた。) -
Api Server
主にDebug等の目的で以下のWeb APIを提供するService である。
・Deal Generator : 意図的に電力融通の実行命令をクラスタ内に生成するためのWeb API
・Error Generator : 任意のError処理命令をクラスタ内に生成するためのWeb API ・Log Configurator : apis-mainのコミュニケーションラインへのUDP Log出力のLevelを動的に変更するための Web API
図3-2
4.機能説明
4.1.クラスタ構築
apis-webは起動時にHazelcastと呼ばれるVert.xフレームワークが使用するクラスタリングマネージャを用いてコミュニケーションライン上に存在する複数のapis-mainとクラスタを構築する。クラスタは設定ファイルであるcluster.xmlに記載される同一クラスタ名を持つapis-mainと構築される。
4.2.Budo Emulator
・Budo EmulatorはGrid Masterやノードに対して以下の情報取得や電力融通Mode設定、Shutdown処理を行う。(Global電力融通Modeは全ノードに対して、Local電力融通Modeは個別ノードに対して行うMode設定である。)
- Grid Master : クラスタ内の全ノードリスト取得
- 任意ノード : 電力融通情報取得、Global電力融通Modeステータス取得、Global 電力融通Mode設定
- 個別ノード : Local電力融通Modeステータス取得、Local電力融通Mode設定、個別Shutdown
- 全ノード : 全体Shutdown
・電力融通Modeは以下の4種類がある。
- Run(autonomous):
クラスタ内での電力融通生成を有効にする電力融通稼働時の標準Modeである。
- Soft Stop(heteronomous):
既存の電力融通は完了まで継続するが、新たな電力融通生成は行わないModeである。
Deal Generatorで強制的に電力融通を生成することは可能なため主にDebug用途として使用されるModeである。
- Force Stop(stop):
既存の電力融通を止め、Deal Generatorの強制的な電力融通生成も含めて新たな電力融通生成も行わないModeである。
不具合発生時など強制的にクラスタ内の電力融通を停止させる場合に使用されるModeである。
- Manual(manual):
apis-mainの保護機能の影響を受けることなくDC/DC Converter等をManualで動作させるために使用されるDebug用のModeである。
4.3.Emulator Emulator
クラスタに参加する全ノードのDC/DC ConverterやBattery等のハードウェア情報をGrid Master経由で一括して取得することができる。
4.4.Api Server
4.4.1.Deal Generator
Deal GenerationのWeb APIを実行するとブラウザ上に下記のWindowが開きJSON形式で電力融通情報を入力後”Generate”ボタンを押すことでクラスタ内に意図的に電力融通の実行命令を生成することができる。この機能は主にDebug等で用いられる。
4.4.2.Error Generator
Error GenerationのWeb APIを実行するとブラウザ上に下記のWindowが開きErrorのカテゴリを選択後”Generate”ボタンを押すことでクラスタ内に選択したError処理を生成することができる。この機能は主にDebug等で用いられる。
4.4.3.Log Configurator
コミュニケーションラインに出力されるapis-mainのUDP Logは情報漏洩や通信のトラフィック負荷を考慮してapis-mainのlogging.properties設定で出力Levelを制限されているか、出力がOFFとなっている。Debugの目的で一時的にapis-mainのUDP Logの出力Levelを変更する場合にはこの機能を使うことで動的に変更することができる。(この機能の効果は一時的でapis-main再起動後のUDP出力Levelはapis-main自身のlogging.properties設定に従う。)
5.通信仕様について
5.1.Web API
Main Controller等のWebアプリケーションは下記のWeb APIにてapis-webと情報のやり取りを行うことができる。以下にそのWeb APIの仕様を説明する。
Budo Emulator機能 | /shutdown | 全体or ノード毎のシャットダウン指示 |
| /setOperationMode | Global or Local のOperation Mode設定 | |
| /deals | 電力融通情報取得 | |
| /unitIds | ノードID一覧取得 | |
| /getStatus | Global Operation Mode取得 | |
| /active | Global Operation Mode設定 (Run) | |
| /quiet | Global Operation Mode設定 (Soft stop) | |
| /stop | Global Operation Mode設定 (Force stop) | |
| /manual | Global Operation Mode設定 (Manual) | |
Emulator Emulator機能 | /get/log | 全ノードのDC/DC ConverterやBattery RSoC等のハードウェア情報取得 |
| Api Server機能 | /deal | 電力融通生成 (評価用) |
| /error | Error生成 (評価用) | |
| /log | apis-mainのUDP Log 出力Level変更 |
5.2.apis-web – Grid Master間通信
Main Controller等のWeb アプリケーションからWeb API (“/get/log”, ”/deals”等)を受け取ったapis-webはクラスタ内のGrid Masterに対してEvent Bus上で各情報収集のためのRequestを投げGrid MasterからのReplayを待つ。apis-webからRequestを受け取ったGrid MasterはRequestの内容に応じてハードウェア情報や、電力融通情報をapis-webに返す。それらの情報を受け取ったapis-webはJSON形式でMain Controller等の要求元へ返す。
6.収集情報
6.1.Emulator Emulator /get/log
Emulator Emulator が処理するWeb API ”/get/log” で取得可能な電力融通情報は以下である。これらの情報を1セットとして全ノード分のハードウェア情報を取得できる。
| apis | version | apis-main version |
| remaining_capacity_wh | Battery残容量(Wh) | |
| deal_interlock_capacity | 1融通 1スロットとした場合に、同時に融通可能なスロット数 | |
| operation_mode.global | クラスタ全体のOperation Mode設定 autonomous : 通常の電力融通Mode heteronomous : 既存電力融通継続 新電力融通生成無効 stop : 電力融通停止Mode manual : 手動Mode (評価用) | |
| operation_mode.local | 自ノードのOperation Mode設定 空 : operation_mode.global に従う heteronomous : 既存電力融通継続 新電力融通生成無効 stop : 電力融通停止Mode | |
| operation_mode.effective | 有効Operation Mode globalとlocalのOperation Modeの組み合わせにて決定 | |
| oesunit | communityId | コミュニティID |
| clusterId | クラスタID | |
| id | ノードID | |
| display | ノード名称 | |
| sn | ノードシリアルNo. | |
| budo | 旧システムでは自動融通がActiveになっていることを示すフラグだったが、 現行システムではoperation_mode.effective がautonomousかそれ以外かを示すフラグとなっている。 autonomous : 1 それ以外 : 0 | |
| ip | IPv4 | |
| Ipv6_ll | IPv6リンクローカルユニキャスト | |
| Ipv6_g | IPv6グローバルユニキャスト | |
| mac | MAC address | |
| battery | rsoc | 相対残容量 (%) |
| battery_operation_status | 電力融通許可/不許可フラグ | |
| time | apis-mainノードの時間 | |
| dcdc | status.status | 状態 |
| status.alarm | Alarm番号 | |
| status.stateAlarm | Alarm情報 | |
| status.statusName | DC/DC Converter Status名称 | |
| status.runningState | DC/DC Converter動作 Status | |
| status.operationMode | Operation Mode | |
| meter.wb | DC Grid 電力 (W) | |
| meter.vg | DC Grid電圧 (V) | |
| meter.ig | DC Grid電流 (A) | |
| meter.wb | Battery電力 (W) | |
| meter.vb | Battery電圧 (V) | |
| meter.ib | Battery電流 (A) | |
| meter.tmp | 内部温度 (℃) | |
| vdis.dvg | DC Grid目標電圧値 (V) | |
| vdis.drg | DC Grid Droop率 (%) | |
| param.dig | DC Grid上限電流 (A) | |
| param.ogv | DC Grid過電圧閾値 (V) | |
| param.ugv | DC Grid低電圧閾値 (V) | |
| param.cib | Battery上限電流 (A) | |
| param.obv | Battery過電圧閾値 (V) | |
| param.ubv | Battery低電圧閾値 (V) | |
6.2.Budo Emulator /deals
Budo Emulator が処理するWeb API ”/deals” で取得可能な電力融通情報は以下である。これらの情報を1セットとしてその時点で実施されている電力融通の数分の情報を取得できる。
| unitId | ノード識別ID |
| negotiationId | 電力融通交渉ID |
| requestUnitId | 電力融通をRequestしたノードID |
| acceptUnitId | 電力融通をAcceptしたノードID |
| requestDateTime | 電力融通をRequestした日時 |
| acceptDateTime | 電力融通をAcceptした日時 |
| requestPointPerWh | Request側が提示した1Wh当たりのポイント |
| acceptPontPerWh | Accept側が提示した1Wh当たりのポイント |
| requestDealGridCurrentA | Request側が提示した融通の電流値 |
| acceptDealGridCurrentA | Accept側が提示した融通の電流値 |
| type | 電力融通Requestのタイプ(充電/放電) |
| chargeUnitId | 充電側のノードID |
| dischargeUnitId | 放電側のノードID |
| pointPerWh | 実際の電力融通時の1Wh当たりのポイント |
| chargeUnitEfficientGridVoltageV | 充電側ノードの効率が良いGrid電圧 |
| dischargeUnitEfficientGridVoltageV | 放電側ノードの効率が良いGrid電圧 |
| dealGridCurrentA | 電力融通時電流値(A) |
| requestAmountWh | Request側が提示した電力量 |
| acceptAmountWh | Accept側が提示した電力量 |
| dealAmountWh | 電力融通時電力量(Wh) |
| dealId | 電力融通情報に付与されたID |
| createDateTime | 電力融通の電力融通情報が作られた日時 |
compensationTargetVoltage ReferenceGridCurrentA | 電圧Referenceを担っているノードの電流補正のターゲット値 (A) |
| activateDateTime | Constant Voltageノード側の起動を開始した日時 |
| rampUpDateTime | DC Gridの電圧Ramp Upが完了した日時 |
| warmUpDateTime | Constant Currentノード側を起動した日時 |
dischargeUnitCompensated GridCurrentA | 電流補正後の放電電流 (A) |
chargeUnitCompensated GridCurrentA | 電流補正後の充電電流 (A) |
| startDateTime | 実際の電力融通を開始した日時 |
| cumulateDateTime | 実際に電力融通した電力を積算した日時 |
| cumulateAmountWh | 実際に電力融通した総電力量 (Wh) |
| stopDateTime | 実際の電力融通を停止した日時 |
| deactivateDateTime | 電力融通後の処理が完了した日時 |
7.設定ファイルについて
apis-webには複数の設定ファイルや鍵ファイル等が存在する。それらのファイルについて説明する。
7.1.config.json
json形式のファイルでapis-webの基本情報を設定する。起動時に一度だけ読み込まれるためパラメータを変更した場合はapis-webの再起動が必要となる。
| programId | プログラム識別文字列 |
| communityId | コミュニティ識別文字列で1つ以上のクラスタをまとめる上位概念のID、clusterId及びAPIS Version文字列と共に暗号化のSeedとして用いられる |
| clusterId | クラスタ識別文字列 communityId及びAPIS Version文字列と共に暗号化のSeedとして用いられる |
| security.enabled | 共有メモリ暗号化とEvent Bus SSL化の有効/無効設定 |
| security.pemKeyFile | Event Bus SSL化に使われる秘密鍵 |
| security.pemCertFile | Event Bus SSL化に使われる証明書 |
| bodoEmulator.port | Budo Emulator用Port番号 Port = 43830 |
| emulatorEmulator.port | Emulator Emulator用 Port番号 Port = 43900 |
| apiServer.port | Generate Deal, Generate Error 要Port番号 Port = 9999 |
| watchdog.enabled | APIS Alive情報有効無効設定 |
| watchdog.periodMsec | Watch Dog Reset周期 (ms) |
| watchdog.host | Watch DogがperiodMsec間隔でAccessするIP Address |
| watchdog.port | Watch DogがperiodMsec間隔でAccessするPort番号 |
| watchdog.uri | Watch DogサービスのURI |
watchdog.requestTimeout Msec | Watch DogのTimeout時間(ms) |
7.2.cluster.xml
xml形式のファイルでHazelcastがクラスタを構築する際に必要なパラメータ(クラスタ名称、パスワード、ネットワーク設定、マルチキャスト設定等)を設定する。
暗号化しcluster.xml.encrypted として保存される。
7.3.logging.properties
Javaの標準APIであるjava.util.loggingのLogの出力に関する設定(Logファイルの保存先、Log の保存容量、Log Levelの設定等)が記述されているファイル。
7.4.start.sh
apis-webを起動させるスクリプトファイル。OS起動時の自動実行で実行される。
以下にstart.sh内でのapis-webを起動させるコマンドを示す。
java -Djava.net.preferIPv4Stack=true -Duser.timezone=Asia/Tokyo -Djava.util.logging.config.file=./logging.properties -jar ./apis-web-2.23.0-a01-fat.jar -conf ./config.json -cp ./ -cluster -cluster-host 127.0.0.1 &
“java”の後の引き数の意味を以下に説明する。
-Djava.net.preferIPv4Stack=true
IPv4アドレスにバインドして起動するオプション。
-Duser.timezone=Asia/Tokyo
Timezone設定。
-Djava.util.logging.config.file=./logging.properties
Log構成ファイルを指定するオプション。
-jar ./apis-web-2.23.0-a01-fat.jar
JARファイルの中にカプセル化されたプログラムの実行を指定するオプション。
-conf ./config.json
構成ファイルを指定するオプション。
-cp ./
cluseter.xmlファイルの位置を指定するオプション。
-cluster-host 127.0.0.1
自身のIP Addressを指定するオプション。
7.5.stop-kill.sh
apis-webを停止させるスクリプトファイル。
Event Bus経由のShutdown機能(stop)を実施した後、それがタイムアウトした場合に自身の
Javaプロセスを強制終了させる処理を行う。スクリプトの中でタイムアウトを秒で指定することが可能である。
7.6.key.pem
Event BusのSSL化に使われる秘密鍵である。
7.7.cert.pem
Event BusのSSL化に使われる証明書である。
8.Log出力
8.1.Log Level
Log出力にはJava標準APIのjava.util.loggingを使っており以下の7つのLevelに分類されている。APISとしては”CONFIG”, “FINER”のLevelは使用しない。これらのAPISの動作Logはlogging.propertiesファイルに記載することでLogファイルの保存先、保存するLog Level、最大Logサイズ、最大保存Log数等の設定を行っている。
[java.util.logging Log Level]
-
SEVERE
実行中にErrorが発生した場合に使われるLevelである。
このLevelのLogが出力された場合には何等かの不具合が発生したと考えられる。
提供していないWeb API(URL)へのAccessがあった場合等。 -
WARNING
実行中にErrorではないが期待された動作でないため警告として知らせる目的で使われるLevelである。
Grid Masterから取得した各ノードのハードウェア情報等が空の場合。 -
INFO
実行中の正常系の情報を出力する際に用いられるLevelで、apis-webでは特に動作として重要なイベント処理を行った際に使われる。
API提供Port等。 -
CONFIG
設定に関するLog Levelであるがapis-webとしてはこのLevelの出力は行わない。 -
FINE
実行中の正常系の通常動作情報を出力する際に用いられるLevelである。
Grid Masterから取得した各ノードのハードウェア情報の取得件数等。 -
FINER
特定の処理についての開始及び終了の情報であるがapis-webとしてはこのLevelの出力は行わない。 -
FINEST
実行中の正常系の通常動作情報を出力する際に用いられるLevelである。
例> Vert.xのVerticle起動時等。
8.2.APIS動作Log出力先
apis-webの動作LogはUDP、Console、ファイルの3つの出力先がある。logging.propertiesの設定でそれぞれの出力の有無や前頁で述べた出力Levelの制限をかけることができる。UDPはコミュニケーションラインに出力されるため情報漏洩や通信のトラフィックを考慮して設定し、ファイルへの出力は不揮発性メモリの容量を考慮して設定する。
9.異常処理
不具合が発生するとFile, UDP, ConsoleにLogは出力するが、自らをリセットしたり、停止させたりする機能はない。
10.セキュリティ
10.1APIS間通信セキュリティ
apis-web - Grid Master間のやり取りはVert.x, Hazelcastフレームワーク がサポートするEvent Bus通信とHazelcast通信によって行われている。それぞれの通信ではセキュリティのため以下の方法で暗号化を行っている。
(1) Event Bus通信
-SSL公開鍵暗号方式 (RSA)
-SSL自己署名証明書
(2) Hazelcast通信
-共通鍵暗号方式(AES 128bit)
11.プライバシー
Web APIによって取得できる情報が、個人情報に該当するかはapis-webの導入地域によって異なるため確認が必要である。また、個人情報に該当する場合で、持ち主の許可なく外部のサーバに送信する行為はGDPR等の個人情報保護規制の対象になる可能性があるため注意が必要である。
12.OSSライセンス
以下にapis-webが使用するソフトウェアとそのOSSライセンスの情報を記載する。apis-webで使用するAdopt OpenJDKはライブラリのリンクのみを行っているためClasspath Exceptionが適用されGPLv2であってもapis-webのソースコードの公開を要求されない。その他のOSSソフトウェアもapis-webのソースコードの公開を要求するライセンスはない。
■apis-webで使用されるソフトウェアとそのOSSライセンス情報
| ソフトウェア | バージョン | ライセンス | コード改変 |
|---|---|---|---|
| Adopt OpenJDK | 11.0.4+11 | GPLv2 with Classpath Exception | 無 |
| Vert.x | 3.7.1 | デュアルライセンス(以下選択) Eclipse Public License2.0 Apache License2.0 | 無 |
| Hazelcast | 3.6.3 | Apache License2.0 | 無 |
| Netty | 4.1.8 | Apache License2.0 | 無 |
| FasterXML/Jackson | 2.7.4 | Apache License2.0 | 無 |
※諸事情によりソフトウェアバージョンは変更される可能性があります。
13.動作環境
13.1.ハードウェア要求
以下にapis-webのハードウェア要求を示す。
| CPUプロセッサ | 600～1000MHz, 64bit シングルコア, 32KB L1 cache以上 ARMv8推奨 (ARMv8以外のCPU採用の場合はAPISの動作確認を行う必要あり) |
| DRAM | DDR3 1.6Gbps 1GB 以上 |
| 内部ストレージ | 8GB以上 |
| イーサネット | 20Mbps 1ポート以上, IPv4 IPv6 サポート |
13.2.OS要求
以下にapis-web用IoT BoardのOS要求を示す。
| 種類 | 64bit OS, Linux 推奨 (Linux以外のOSの場合には採用前にAPIS動作確認を行う必要あり) |
| サイズ | IoT Boardの内部ストレージ容量次第 (APIS等のLog保存場所用に3GB以上は確保すること) |
| 動作ソフトウェア | AdoptOpenJDK (32/64bit) |
| OSSライセンス | GPL等のコピーレフト型ライセンスの影響を避けるため、それらのライセンスを持つソフトウェアとapis-webが1つの実行ファイルとなるOSは禁止 (例:RTOS) |
| その他 | OS起動時にapis-web等の自動実行が行えること |
| ssh login/scpファイル転送が行えること | |
| logrotage等でログを定期的にリネーム/圧縮/削除が行えること | |
| IPv4アドレスを固定できること | |
| ntp serverと時間の同期が行えること |