Rev 0.67
- apis-web Specification
- Contents
- 1. Terms and Abbreviation
- 2. Overview
- 3. Software Composition
- 4. Description of Functions
- 5. Communication Specifications
- 6. Collected Information
- 7. Configuration Files
- 8. Log Output
- 9. Error Handling
- 10. Security
- 11. Privacy
- 12. Open Source Software Licenses
- 13. Operating Environment
| Term | Description |
|---|---|
| apis-main | Software for power interchange developed by Sony CSL that enables autonomous decentralized control. |
| Grid Master | Name of service included in apis-main. Controls the DC grid to exchange electricity. |
| Hazelcast | In-memory distributed computing library that accelerates applications by distributing data across multiple machines and carrying out parallel processing. |
| Vert.x | A framework for implementing load balanced programs. Using Hazelcast, the Event Bus is clustered and processed with load balancing. |
| Verticle | The basic processing unit of a Vert.x program is called a Verticle. |
| Event Bus | The basic processing unit of a Vert.x program is called a Verticle. The Event Bus is an asynchronous interface for verticle-to-verticle communications. |
| Main Controller | Web application developed by Sony CLS for displaying the conditions of each node installed by apis-main and the conditions of power interchange in real time. |
| Budo | Name of automated power interchange software for centralized management and control prior to study of autonomous decentralized control of energy. |
apis-web is a software program that provides power interchange-related information to Web services (such as a visualization service) for the development, operation, and maintenance of power interchange. To get information from apis-main installed in multiple nodes connected on a communication lines such as Ethernet, apis-web forms a cluster by using Vert.x and Hazelcast framework functions. From Grid Master in the cluster, it gets hardware information such as the DC/DC converter and battery RSoC information of all nodes and power interchange information from any node. apis-web also has functions to generate power interchange and errors for debugging purposes.
Fig. 2-1
Fig. 3-1 shows the software architecture of apis-web. The Java Development Kit (JDK) is installed on the Linux operating system. apis-web runs on two JDK frameworks: event-driven load balancing platform Vert.x and in-memory distributed computing platform Hazelcast. (For versions of verified open source software used, see 12. Open Source Software Licenses.)
Fig. 3-1
apis-web provides three services, as shown in Fig. 3-2.
- Budo Emulator
This service provides information about power interchanges generated in a cluster to Web applications such as Main Controller. It also enables changing settings of apis-mains of all nodes or individual nodes for actions such as executing and stopping power interchanges. Programs such as Main Controller visualize the power interchange conditions within a cluster based on information received from apis-web. (The appellation “Emulator” comes from the service’s functions that emulate providing Budo information.)
- Emulator Emulator
This service provides hardware information to Web applications such as Main Controller. The hardware information includes conditions of DC/DC converters and batteries in all nodes obtained from each node’s apis-main. (The name “Emulator Emulator” comes from the fact that in developing this service to provide information about actual hardware to Web applications such as Main Controller, developers appropriated already developed Web API that had DC/DC converter and Battery hardware emulator functions. So from the standpoint of a Web application, the service emulates an emulator.)
- API Server
This service provides the following Web API primarily for purposes such as debugging.
- Deal Generator :
Web API to intentionally generate a power interchange execution command within a cluster. - Error Generator :
Web API to intentionally generate a chosen error handling command within a cluster. - Log Configurator :
Web API to dynamically change the level of the UDP log output to apis-main on the communication line.
Fig. 3-2
When apis-web started, a Hazelcast Cluster Manager implemented by the Vert.x framework is used to form clusters of multiple apis-mains on the communication line. A cluster is composed of apis-mains that have the same cluster name specified in their cluster.xml configuration files.
-
Budo Emulator gets the following information, sets the power interchange mode, and carries out shutdown processes for Grid Master and nodes. (The Global power interchange mode applies to all nodes. The Local power interchange mode applies to a particular node.)
- Grid Master:
Gets a list of all nodes in a cluster. - Any node:
Gets power interchange information and Global power interchange mode status and sets Global power interchange mode. - Particular node:
Gets local power interchange status, sets Local power interchange mode and shuts down particular node. - All nodes:
Shuts down all nodes.
- Grid Master:
-
There are four power interchange modes:
- Run (autonomous) :
Standard mode during power interchange operation, which enables the generation of power interchanges within a cluster. - Soft Stop (heteronomous) :
Mode in which existing power interchanges continue until completed and new power interchanges are not generated. Because a power interchange can be force generated by Deal Generator, this mode is primarily used for debugging purposes. - Force Stop (stop) :
Mode in which existing power interchanges are stopped and generations of new power interchanges, including forced generations by Deal Generator, are not carried out. This mode is used to force stop power interchanges in a cluster when a problem occurs. - Manual (manual) :
Mode for debugging. Used to manually operate the DC/DC converter and other equipment without affecting apis-main’s protection functions.
- Run (autonomous) :
This service can get hardware information such as conditions of DC/DC converters and batteries in all nodes participating in a cluster all at once.
When the Deal Generation Web API is executed, the window below opens in the browser. You can intentionally generate a power interchange execution command by entering power interchange information in JSON format and clicking the “Generate” button. This function is mainly used for debugging purposes.
When the Error Generation Web API is executed, the window below opens in the browser. You can generate selected error handling in a cluster by choosing the error categories and clicking the “Generate” button. This function is mainly used for debugging purposes.
The output of apis-main’s UDP log, which is outputted to the communication line, is turned off or its level of output is restricted based on considerations of the possibility of data breaches and the amount of data traffic. Output settings are configured in apis-main’s logging.properties file. If you wish to temporarily change the UDP log output level for debugging purposes, you can use the Log Configurator function. (The effects of this function are temporary. The output level of UDP log follows apis-main’s logging.properties file after apis-main is restarted.)
Web applications such as Main Controller can exchange information with apis-web using the following Web API. The following describes the Web API specifications.
Budo Emulator functions |
/shutdown | Instruct shutdown of all or individual nodes. |
| /setOperationMode | Set Global or Local operation mode. | |
| /deals | Get power interchange information. | |
| /unitIds | Get list of node IDs. | |
| /getStatus | Get status of Global operation mode. | |
| /active | Set Global operation mode (Run). | |
| /quiet | Set Global operation mode (Soft stop). | |
| /stop | Set Global operation mode (Force stop). | |
| /manual | Set Global operation mode (Manual). | |
Emulator Emulator functions |
/get/log | Get hardware information from all nodes, such as DC/DC converter conditions and battery RSoC. |
| API Server functions | /deal | Generate power interchange (for testing purposes). |
| /error | Generate error (for testing purposes). | |
| /log | Change the output level of apis-main’s UDP log. |
After receiving Web API (“/get/log”, ”/deals”, etc.) from a Web application such as Main Controller, apis-web sends a request to Grid Master in the cluster to gather needed information from the Event Bus and waits for Grid Master’s response. After receiving the request from apis-web, Grid Master returns hardware and power interchange information to apis-web based on the content of the request. After receiving the information, apis-web returns it to the requester—e.g. Main Controller—in JSON format.
Power interchange information that can be obtained by Web API “/get/log”, which is processed by Emulator Emulator, is as follows. The hardware information of all nodes can be obtained as a set.
| apis | version | Version of apis-main | |
| remaining_capacity_wh | Remaining battery capacity (Wh) | ||
| deal_interlock_capacity | In the case of setting one slot for one interchange, the number of slots that can carry out interchanges simultaneously. | ||
| operation_mode.global | Set operation mode of clusters globally. autonomous: Usual power interchange mode heteronomous: Continue existing power interchanges. Disable generation of new power interchanges. stop: Mode in which the power interchange is stopped manual: Manual mode (for testing purposes) |
||
| operation_mode.local | Set a node’s own operation mode. <Empty>: Follow operation_mode.global heteronomous: Continue existing power interchange. Disable generation of new power interchanges. stop: Mode in which the power interchange is stopped Set a node’s own operation mode. <Empty>: Follow operation_mode.global heteronomous: Continue existing power interchange. Disable generation of new power interchanges stop: Mode in which the power interchange is stopped |
||
| operation_mode.effective | Effective operation mode Determined by combining global and local operation modes |
||
| oesunit | communityId | Community ID | |
| clusterId | Cluster ID | ||
| id | Node ID | ||
| display | Node name | ||
| sn | Node serial number | ||
| budo | Under the previous system, this flag was used to indicate that automatic interchange has become active. However, in the current system, this flag is used to indicate whether or not operation_mode.effective is autonomous. Autonomous: 1 Otherwise: 0 |
||
| ip | IPv4 | ||
| Ipv6_ll | IPv6 link-local unicast address | ||
| Ipv6_g | IPv6 global unicast address | ||
| mac | MAC address | ||
| battery | rsoc | Relative remaining capacity (relative state-of-charge) (%) | |
| battery_operation_status | Flag for permitting/denying power interchange | ||
| time | Time of apis-main node | ||
| dcdc | status.status | Status | |
| status.alarm | Alarm number | ||
| status.stateAlarm | Alarm information | ||
| status.statusName | Name of DC/DC converter status | ||
| status.runningState | DC/DC converter action status | ||
| status.operationMode | Operation Mode | ||
| meter.wb | DC grid power (W) | ||
| meter.vg | DC grid voltage (V) | ||
| meter.ig | DC grid current (A) | ||
| meter.wb | Battery power (W) | ||
| meter.vb | Battery voltage (V) | ||
| meter.ib | Battery current (A) | ||
| meter.tmp | Internal temperature (℃) | ||
| vdis.dvg | DC grid’s target voltage (V) | ||
| vdis.drg | DC grid droop rate (%) | ||
| param.dig | DC grid upper-limit current (A) | ||
| param.ogv | DC grid’s excess voltage threshold (V) | ||
| param.ugv | DC grid’s low voltage threshold (V) | ||
| param.cib | Battery’s upper-limit current (A) | ||
| param.obv | Battery’s excess voltage threshold (V) | ||
| param.ubv | Battery’s low voltage threshold (V) | ||
Power interchange information that can be obtained by the Web API “/deals”, which is processed by the Budo Emulator, is as follows. Multiple pieces of information on power interchanges being carried out at that point in time can be obtained as a set of information.
| unitId | Node identification ID |
| negotiationId | Power interchange negotiation ID |
| requestUnitId | ID of node that requested the power interchange |
| acceptUnitId | ID of node that accepted the power interchange |
| requestDateTime | Date and time when power interchange was requested |
| acceptDateTime | Date and time when power interchange was accepted |
| requestPointPerWh | Points per watt-hour presented by the requesting side |
| acceptPontPerWh | Points per watt-hour presented by the accepting side |
| requestDealGridCurrentA | Value of the current in the interchange presented by the requesting side |
| acceptDealGridCurrentA | Value of the current in the interchange presented by the accepting side |
| type | Type of power interchange request (Charge/Discharge) |
| chargeUnitId | ID of charging node |
| dischargeUnitId | ID of discharging node |
| pointPerWh | Points per watt-hour during actual power interchange |
| chargeUnitEfficientGridVoltageV | Efficient grid voltage of charging node |
| dischargeUnitEfficientGridVoltageV | Efficient grid voltage of discharging node |
| dealGridCurrentA | Current value (A) during power interchange |
| requestAmountWh | Electrical energy presented by the requesting side |
| acceptAmountWh | Electrical energy presented by the accepting side |
| dealAmountWh | Electrical energy (Wh) during power interchange |
| dealId | ID assigned to power interchange information |
| createDateTime | Date and time when the power interchange information was created for the power interchange |
compensationTargetVoltage ReferenceGridCurrentA |
Target value (A) of current compensation at Voltage Reference node |
| activateDateTime | Date and time when the Constant Voltage node starts up |
| rampUpDateTime | Date and time when DC grid’s voltage ramp-up is complete |
| warmUpDateTime | Date and time when the Constant Current node starts up |
dischargeUnitCompensated GridCurrentA |
Discharge current (A) after current compensation |
chargeUnitCompensated GridCurrentA |
Charge current (A) after current compensation |
| startDateTime | Date and time when actual power interchange begins |
| cumulateDateTime | Date and time when interchanged power is actually accumulated |
| cumulateAmountWh | Total electrical power (watt-hour) after power is actually interchanged |
| stopDateTime | Date and time when actual power interchange stops |
| deactiveateDateTime | Date and time when post-power interchange processing is complete |
apis-web has multiple configuration files and key files. These files are described below.
The following basic information for configuring apis-web is set in a JSON-format file. The file is read once when apis-web starts up, so if a parameter is changed, apis-web must be restarted.
| programId | Program identification string |
| comminityId | Community identification string. Higher-level ID when organizing one or more clusters. Also used as seed for encryption, together with clusterId and the APIS version string. |
| clusterId | Cluster identification string Used as seed for encryption, together with comminityId and the APIS version string. |
| security.enabled | Setting for enabling/disabling encryption of shared memory and using SSL for the Event Bus |
| security.pemKeyFile | Secret key used for Event Bus SSL |
| security.pemCertFile | Certificate used for Event Bus SSL |
| bodoEmulator.port | Port number for Budo Emulator Port = 43830 |
| emulatorEmulator.port | Port number for Emulator Emulator Port = 43900 |
| apiServer.port | Port number for Generate Deal, Generate Error Port = 9999 |
| watchdog.enabled | Setting for enabling/disabling APIS alive information |
| watchdog.periodMsec | Watch dog reset cycle (ms) |
| watchdog.host | IP address accessed by the watch dog service at the interval specified by periodMsec |
| watchdog.port | Port number accessed by the watch dog service at the interval specified by periodMsec |
| watchdog.uri | URI of the watch dog service |
watchdog.requestTimeout Msec |
Timeout of watch dog service (ms) |
File in XML format that sets the parameters (such as cluster name, passwords, network settings, multicast settings, etc.) required by Hazelcast when forming clusters.
Encrypted and saved as cluster.xml.encrypted.
File containing settings related to the output of Java’s standard logging API java.util.logging (destination of log file, storage capacity of log file, log level configuration, etc.).
Script file for starting up apis-web. It is automatically run when the operating system starts up.
The command to start apis-web in start.sh is as follows:
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 192.168.0.1 &
The arguments after “java” are described here.
-
Djava.net.preferIPv4Stack=true
-> Option to bind IPv4 address. -
Duser.timezone=Asia/Tokyo
-> Time zone setting -
Djava.util.logging.config.file=./logging.properties
-> Option for specifying the logging configuration file. -
jar ./apis-web-2.23.0-a01-fat.jar
-> Option for specifying the execution of program encapsulated in the JAR file. -
conf ./config.json
-> Option for specifying the configuration file. -
cp ./
-> Option for specifying the location of cluster.xml file. -
cluster-host 192.168.0.1 &
->Option for specifying own IP address.
Script file for stopping apis-web.
After the shutdown function (stop) is executed via the Event Bus, apis-web’s own Java processes are forced to terminate if time out occurs. It is possible to specify the timeout in seconds in the script.
Secret key used when applying SSL to the Event Bus.
Certificate used for applying SSL to the Event Bus.
The standard Java API java.util.logging is used for log output. Logging is divided into the seven levels described below. APIS logging does not output the “CONFIG” and “FINER” levels. The destinations of the APIS action log, log levels to be saved, maximum log size, maximum number of records to be saved, etc. are set in the logging.properties file.
[java.util.logging Log Level]
-
SEVERE
→Level used when an error occurs during execution.
When a log of this level is outputted, it is considered that some sort of problem has occurred.
<Example> When there is access to a Web API (URL) that has not been provided. -
WARNING
→Level used to issue a warning for unexpected behavior during execution that is not an error.
<Example> Hardware information or other information in a node obtained from Grid Master is blank. -
INFO
→Level used for outputting normal system information during execution. For apis-web, this level is outputted after processing a significant event.
<Example> API-provided port, etc. -
CONFIG
→This log level outputs information related to settings. This level is not outputted in the log for apis-web. -
FINE
→This level is used for outputting normal behavior information during execution.
<Example> Number of acquisitions of node information from Grid Master -
FINER
→Starting and ending information for particular processes. This level is not outputted in the log for apis-web. -
FINEST
→This level is used to output normal behavior information during execution.
<Example> When a Vert.x Verticle is started.
The apis-web action log has three output destinations: UDP, console, and file. Enabling/disabling each output and applying restrictions on the output level as explained in the previous section can be set in logging.properties. Because UDP is outputted on the communication line, set the log after taking into consideration security against data breaches and the amount of data traffic. Set file output after taking into consideration the amount of non-volatile memory available.
When a problem occurs, logs are output to file, UDP, and console. However, there are no functions to reset or stop itself.
Exchanges between apis-web and Grid Master are carried out using Event Bus communication and Hazelcast frameworks, which are supported by the Vert.x and Hazelcast frameworks. Each type of communication is encrypted using the following methods for security.
-
Event Bus communication
- SSL public key cryptography (RSA)
- SSL self-signed certificate -
Hazelcast communication
- Symmetric key cryptography (AES 128-bit)
Personal information must be handled with care because the act of sending personal information to an external server without permission from the owner may be subject to the General Data Production Regulation (GDPR) and other regulations that protect personal information. Whether or not information that can be obtained by the Web API is considered personal information depends on the geographic region in which apis-web is deployed, so confirmation is necessary.
The following table shows the software used by apis-web and information about their open source software licenses. apis-web only links to Adopt OpenJDK libraries, so publishing the source code of apis-web is not required due to the application of GPLv2’s Classpath Exception. The licenses of other OSS software also do not require the source code of apis-web to be published.
■Software used by apis-web and information about their open source software licenses
| Software | Version | License | Revised code |
|---|---|---|---|
| Adopt OpenJDK | 11.0.4+11 | GPLv2 with Classpath Exception | No |
| Vert.x | 3.7.1 | Dual-licensed (Choose below) Eclipse Public License 2.0 Apache License, Version 2.0 |
No |
| Hazelcast | 3.6.3 | Apache License, Version 2.0 | No |
| Netty | 4.1.8 | Apache License, Version 2.0 | No |
| FasterXML/Jackson | 2.7.4 | Apache License, Version 2.0 | No |
| ReactiveX/RxJava | 1.3.0 | Apache License, Version 2.0 | No |
\*The software versions are subject to change.
The recommended hardware specifications for apis-web are as follows.
| CPU processor | 600 – 1000MHz, 64-bit single core, 32KB L1 cache or above ARMv8 recommended. (If using a CPU besides ARMv8, you need to confirm the behavior of APIS.) |
| DRAM | DDR3 1.6Gbps 1 GB or more |
| Internal storage | 8 GB or more |
| Ethernet | 20 Mbps, 1 port or more, support for IPv4 or IPv6 |
The recommended operating system specifications for the IoT Board used for apis-web are as follows.
| Type | 64-bit OS, Linux recommended (If using an operating system besides Linux, you need to confirm the behavior of APIS.) |
| Size | Depends on the internal storage capacity of the IoT Board (Storage of logs of APIS, etc., requires at least 3 GB.) |
| Operating software | AdoptOpenJDK (32/64-bit) |
| Open source software license | To prevent the effects of copyleft licenses such as GPL, an operating system that has open source software and apis-web in one execution file is prohibited (e.g. a real-time operating system). |
| Others | Ability to automatically execute apis-web and other software when the operating system starts up. |
| Ability to carry out ssh login/scp file transfer. | |
| Ability to periodically rename/compress/delete logs, such as by using logrotage. | |
| Ability to set static IPv4 addresses. | |
| Ability to synchronize the system time with the NTP server. |
