Rev 0.63
- apis-ccc Specification Document
- Contents
- 1. Terms and Abbreviations
- 2. Overview
- 3. Software Composition
- 4. Detailed Description of Actions
- 5. Data Acquisition
- 6. Configuration Files
- 7. Logging Functions
- 8. Error Handling
- 9. Security
- 10. Privacy
- 11. OPEN-SOURCE Software Licenses
- 12. Operating Environment
| Term | Explanation |
|---|---|
| apis-main | Software developed by Sony CSL for energy sharing that enables autonomous decentralized control. (For more information, refer to the apis-main Specification Document.) |
| Grid Master | Name of a service included in apis-main. Controls the DC grid for energy sharing. |
| Mediator Service | A service that negotiates for the services of an apis-main with the Mediator Services of other apis-main and activates the Grid Master that creates energy sharing data. |
| Hazelcast | An in-memory distributed computing library that accelerates applications by distributing data across multiple machines and conducting parallel processing. |
| Vert.x | A framework for program load balancing. The Hazelcast library is used for event bus clustering and load-balancing on the network. |
| 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. |
| Scenario | This is a file in JSON format that describes the charging or discharging requirements for the state of charge of each battery required for energy sharing. |
| Policy | This is a file in JSON format that is used by apis-main and sets the parameters that are required for safe execution of the control algorithms that are needed for maintaining overall operational order. |
apis-ccc is client software for uploading information that is related to energy sharing to external services such as a server and downloading node configuration files from a server for operation and maintenance. It constructs clusters by using the functions of the Vert.x and Hazelcast frameworks to obtain information from apis-main that is running on multiple nodes that are connected via Ethernet or other communication lines. From the Grid Master in the cluster, it then obtains information on the hardware of each node, software information related to apis-main, and node-specific information. In that way, information on any node can be obtained. apis-ccc also has a function for downloading configuration files upon request from apis-main.
Figure 2-1
The apis-ccc software architecture is illustrated in Figure 3-1. apis-ccc runs on two frameworks, the Vert.x event-driven load distribution platform and the Hazelcast in-memory distributed computing framework. Both frameworks run on top of the Java Development Kit (JDK) on Linux. (Operation has been confirmed on the OSS software version 12. Refer to the OSS license.)
Figure 3-1
The four services provided by apis-ccc (Figure 3-2) are described below.
-
Unit Data Reporting
This service collects information from Grid Master at regular intervals, including hardware information such as the DC/DC converter and battery of each node and software information that is related to apis-main, etc., and node-specific information. It sends that information to external services such as a server. -
Deal Reporting
This service collects information on total energy sharing from any Mediator Service and sends that information to external services such as a server. (The Mediator Service is selected by Vert.x.) -
Scenario Acquisition
This service collects scenario files from a server or other external services according to periodic accesses from apis-mains and sends the files to the requesting apis-mains. -
Policy Acquisition
This service collects policy files from a server or other external services according to periodic accesses from the apis-mains and sends the files to the requesting apis-mains.
Figure 3-2
The Unit Data Reporting apis-ccc service sends requests via the event bus to Grid Master, which is a service of apis-main, at intervals of unitDataReporting.periodMsec to obtain software and hardware information for all nodes and node-specific information in JSON format. (See section 6.1, “config.json”.) The obtained information is sent in JSON format by the HTTP POST method to external services such as a server, where it is stored in a MongoDB database. (Concerning hardware information, see section 5.1, “Data Acquired by Unit Data Reporting”.)
Figure 4-1
The Deal Reporting apis-ccc service sends requests via the event bus to a Mediator Service, which is a service of apis-main, at intervals of dealReporting.periodMsec (see section 6.1, “config.json”) to obtain energy sharing data in JSON format. The obtained information is sent in JSON format by the HTTP POST method to external services such as a server, where it is stored in MongoDB. (The Mediator Service is specified by Vert.x. It obtains all energy sharing data from memory that is shared with Hazelcast and sends the data to the Deal Reporting service.)
Separately from the periodic Deal Reporting processing, the Mediator Services of the participating apis-mains apply a trigger when the energy sharing is completed to execute processing that saves the energy sharing completion data to the MongoDB database via the Deal Reporting service.
Figure 4-2
The apis-ccc Scenario Acquisition service receives requests for scenario files from the Scenario Keeping service of the apis-main User Service via the event bus at intervals specified in the scenario files. The requests are sent together with the service ID and other such information. The Scenario Acquisition service that has received the request sends that information to a server or other such external service by the HTTP POST method. The service that receives the information matches the ID and other information and returns a scenario file in JSON format in the HTTP POST response to the Scenario Acquisition service. Upon receiving the response, the Scenario Acquisition service sends the scenario file in JSON format to the requesting Scenario Keeping service via the event bus.
Figure 4-3
The apis-ccc Policy Acquisition service receives requests for scenario files from the Policy Keeping service of the apis-main User Service via the event bus at intervals specified in the Policy files. The requests are sent together with the service ID and other such information. The Policy Acquisition service that has received the request sends that information to a server or other such external service by the HTTP POST method. The service that receives the information matches the ID and other information and returns a scenario file in JSON format in the HTTP POST response to the Policy Acquisition service. Upon receiving the response, the Policy Acquisition service sends the scenario file in JSON format to the requesting Policy Keeping service via the event bus. Because the same policy file must be used for the entire cluster, it is necessary to prevent changes to the policy file by the apis-main programs of different nodes. For that reason, it is implemented as a function, and the administrator must temporarily halt automatic interchange within the cluster and perform it as a maintenance task.
Figure 4-4
The Deallog Acquisition apis-ccc service acquires the power accommodation history information for one day in JSON format at the time set in deallogAcquisition.executionTime (see section 6.1 "config.json") once a day. Create the acquired information as a deal file and store it in an external service such as a server.
The hardware information for each node that is obtained from the Grid Master by the Unit Data Reporting service via the event bus is described below. The items of information are obtained as a single set for all nodes.
| apis | version | apis-main version |
| remaining_capacity_wh | Battery state of charge (Wh) | |
| deal_interlock_capacity | The number of slots that can carry out interchanges simultaneously when one slot is set for one interchange | |
| operation_mode.global | Set operation mode of clusters globally. autonomous: Usual energy sharing mode heteronomous: Continue existing energy sharings. Disable generation of new energy sharings. stop: Energy sharing is stopped manual: Manual mode (for testing) |
|
| operation_mode.local | Set the operation mode for a node. <Empty>: According to operation_mode.global heteronomous: Continue existing energy sharing. Disable generation of new energy sharings. stop: Energy sharing is stopped. |
|
| operation_mode.effective | Effective operation mode Determined by combining global and local operation modes |
|
| oesunit | communityId | The community ID |
| clusterId | The cluster ID | |
| id | The node ID | |
| display | The node name | |
| sn | The node serial number | |
| budo | In the previous system, this flag was used to indicate that automatic interchange is active. 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 state of charge (%) |
| battery_operation_status | Flag that indicates whether or not energy sharing is possible | |
| time | apis-main node time | |
| dcdc | status.status | The status |
| status.alarm | Alarm number | |
| status.stateAlarm | Alarm information | |
| status.statusName | DC/DC converter status name | |
| status.runningState | DC/DC converter running status | |
| status.operationMode | The 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 target voltage (V) | |
| vdis.drg | DC grid droop rate (%) | |
| param.dig | DC grid upper-limit current (A) | |
| param.ogv | DC grid excess voltage threshold (V) | |
| param.ugv | DC grid low voltage threshold (V) | |
| param.cib | Battery upper-limit current (A) | |
| param.obv | Battery excess voltage threshold (V) | |
| param.ubv | Battery low voltage threshold (V) | |
The hardware information of each node that the Deal Reporting service acquires from Grid Master via the event bus is described below. The hardware information for all nodes can be acquired as a single set.
| unitId | Node ID |
|---|---|
| negotiationId | Energy sharing negotiation ID |
| requestUnitId | ID of node that requested the energy sharing |
| acceptUnitId | ID of node that accepted the energy sharing |
| requestDateTime | Date and time of energy sharing request |
| acceptDateTime | Date and time of energy sharing acceptance |
| 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 energy sharing presented by the requesting side |
| acceptDealGridCurrentA | Value of the current in the energy sharing presented by the accepting side |
| type | Type of energy sharing request (Charge/Discharge) |
| chargeUnitId | ID of charging node |
| dischargeUnitId | ID of discharging node |
| pointPerWh | Points per watt-hour during actual energy sharing |
| chargeUnitEfficientGridVoltageV | Efficient grid voltage of charging node |
| dischargeUnitEfficientGridVoltageV | Efficient grid voltage of discharging node |
| dealGridCurrentA | Current value (A) during energy sharing |
| requestAmountWh | Electrical energy presented by the requesting side |
| acceptAmountWh | Electrical energy presented by the accepting side |
| dealAmountWh | Electrical energy (Wh) during energy sharing |
| dealId | ID assigned to energy sharing information |
| createDateTime | Date and time when the energy sharing information was created |
compensationTargetVoltage ReferenceGridCurrentA |
Target value (A) of current compensation at the voltage reference node |
| activateDateTime | Date and time when the constant voltage node starts up |
| rampUpDateTime | Date and time when DC grid 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 energy sharing begins |
| cumulateDateTime | Date and time when interchanged power actually accumulates |
| cumulateAmountWh | Total electrical power (watt-hour) after actual energy sharing |
| stopDateTime | Date and time when actual energy sharing stops |
| deactiveateDateTime | Date and time when post-energy sharing processing is complete |
The various apis-ccc configuration files and key files are described below.
The following basic information for configuring apis-ccc is set in a JSON-format file. The file is read once when apis-ccc starts up, so if a parameter is changed, apis-ccc must be restarted.
| programId | Program identification string |
| comminityId | Community identification string; higher-level ID when organizing more than one cluster. Also used as an encryption seed, together with clusterId and the apis-main version string. |
| clusterId | Cluster identification string; used as an encryption seed, together with communityId and the apis-main 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 |
dealReporting. periodMsec |
The period for reporting energy sharing information to a server or other external services |
| dealReporting.host | The IP address of the external server or other service that sends the energy sharing data |
| dealReporting.port | The port number of the external server or other service that sends the energy sharing data |
| dealReporting.ssl | The state of SSL communication for the external server or other service that sends the energy sharing data Enabled: True Disabled: False |
| dealReporting.uri | The URI of the external server or other service that sends the energy sharing data |
dealReporting.request TimeoutMsec |
The timeout time for HTTP requests of the external server or other service that sends the energy sharing data |
unitDataReporting .periodMsec |
The period for reporting hardware data to the external server or other service that sends the hardware data |
| unitDataReporting.host | The IP address of the external server or other service that sends the hardware data |
| unitDataReporting.port | The port number of the external server or other service that sends the hardware data |
| unitDataReporting.ssl | The state of SSL communication for the external server or other service that sends the hardware data Enabled: True Disabled: False |
| unitDataReporting.uri | The URI of the external server or other service that sends the hardware data |
unitDataReporting. requestTimeoutMsec |
The timeout time for HTTP requests of the external server or other service that sends the hardware data |
| scenarioAcquisition.host | The IP address of the external server or other service that acquires the scenario file |
| scenarioAcquisition.port | The port number of the external server or other service that acquires the scenario file |
| scenarioAcquisition.ssl | The state of SSL communication for the external server or other service that acquires the scenario file. Enabled: True Disabled: False |
| scenarioAcquisition.uri | The reporting URI of the external server or other service that acquires the scenario file |
scenarioAcquisition. requestTimeoutMsec |
The timeout time for HTTP requests of the external server or other service that acquires the scenario file |
| scenarioAcquisition.accessInfoS3.accessKey | The S3 Access Key for acquires the scenario file |
| scenarioAcquisition.accessInfoS3.secretAccessKey | The S3 Secret Access Key for acquires the scenario file |
| scenarioAcquisition.accessInfoS3.regionName | The S3 Region for acquires the scenario file |
| scenarioAcquisition.accessInfoS3.endpointUrl | The S3 Endpoint for acquires the scenario file |
| scenarioAcquisition.accessInfoS3.bucketName | The S3 Bucket for acquires the scenario file |
| scenarioAcquisition.accessInfoS3.folderName | The S3 Folder for acquires the scenario file |
| scenarioAcquisition.accessInfoS3.filePrefix | The Prefix of File for acquires the scenario file |
| scenarioAcquisition.accessInfoS3.fileExtension | The Extension of File for acquires the scenario file |
| policyAcquisition.host | The IP address of the external server or other service that acquires the policy file |
| policyAcquisition.port | The port number of the external server or other service that acquires the policy file |
| policyAcquisition.ssl | The state of SSL communication for the external server or other service that acquires the policy file. Enabled: True Disabled: False |
| policyAcquisition.uri | The reporting URI of the external server or other service that acquires the policy file |
policyAcquisition.request TimeoutMsec |
The timeout time for HTTP requests of the external server or other service that acquires the policy file |
| watchdog.periodMsec | Watchdog reset period (ms) |
| deallogAcquisition.host | The IP address of MongoDB for acquires the deallog |
| deallogAcquisition.port | The port number of MongoDB for acquires the deallog |
| deallogAcquisition.ssl | The state of SSL communication for the external server of MongoDB for acquires the deallog Enabled: True Disabled: False |
| deallogAcquisition.database | The Database Name of MongoDB for acquires the deallog |
| deallogAcquisition.collection | The Collection Name of MongoDB for acquires the deallog |
| deallogAcquisition.executionTime | The execution time once a day for acquires the deallog（Format : HHmmss） |
| deallogAcquisition.acquisitionTime | The time of setting range for acquires the deallog（Format : HHmmss） |
| deallogAcquisition.accessInfoS3.accessKey | The S3 Access Key for storage the acquired deallog file |
| deallogAcquisition.accessInfoS3.secretAccessKey | The S3 Secret Access Key for storage the acquired deallog file |
| deallogAcquisition.accessInfoS3.regionName | The S3 Region for storage the acquired deallog file |
| deallogAcquisition.accessInfoS3.endpointUrl | The S3 Endpoint for storage the acquired deallog file |
| deallogAcquisition.accessInfoS3.bucketName | The S3 Bucket for storage the acquired deallog file |
| deallogAcquisition.accessInfoS3.folderName | The S3 Folder for storage the acquired deallog file |
| deallogAcquisition.accessInfoS3.filePrefix | The Prefix of File for storage the acquired deallog file |
| deallogAcquisition.accessInfoS3.fileExtension | The Extension of File for storage the acquired deallog file |
| watchdog.host | IP address accessed by the watchdog service at the interval specified by periodMsec |
| watchdog.port | Port number accessed by the watchdog service at the interval specified by periodMsec |
| watchdog.uri | Watchdog service URI |
watchdog.request TimeoutMsec |
Timeout of the watchdog service (ms) |
This file contains the parameter settings that are required for construction of Hazelcast clusters in XML format (cluster name, password, network settings, multicast settings, etc.).
The file is encrypted for storage as cluster.xml.encrypted.
This file contains settings that are related to log output of the standard java.util.logging API (log file location, log capacity, logging level, etc.).
This shell script is executed automatically to start up apis-ccc when the OS boots up.
The command in start.sh that starts up apis-ccc is shown below.
java -Djava.net.preferIPv4Stack=true -Duser.timezone=Asia/Tokyo -Djava.util.logging.config.file=./logging.properties -jar ./apis-ccc-2.23.0-a01-fat.jar -conf ./config.json -cp ./ -cluster -cluster-host 127.0.0.1 &
The arguments that follow ‘java’ in the command are explained below.
-
Djava.net.preferIPv4Stack=true
-> Option for binding to an IPv4 address -
Duser.timezone=Asia/Tokyo
-> Time zone setting -
Djava.util.logging.config.file=./logging.properties
-> Option for specifying the log configuration file -
jar ./apis-ccc-2.23.0-a01-fat.jar
-> Option for specifying execution of the program encapsulated in a JAR file -
conf ./config.json
-> Option for specifying the configuration file -
cp ./
-> Option for specifying the location of the cluster.xml file -
cluster-host 127.0.0.1
-> Option for specifying the local IP Address
This file holds a shell script that stops execution of the apis-ccc process.
After executing the shutdown function (stop) via the event bus, the script forcefully terminates its own Java process when a timeout occurs. The timeout time can be set in units of seconds within the script.
This is the secret key used for SSL protection of the event bus.
This is the certificate used for SSL protection of the event bus.
The standard Java java.util.logging API is used for logging. Of the seven available log levels described below, the “CONFIG” and “FINER” levels are not used for APIS. The APIS operation logs are described in the logging.properties file, where the log file location, log levels, maximum log size, and maximum number of logs are set.
[java.util.logging Log Level]
- SEVERE
- This level is used when an execution error occurs.
Log output at this level can be considered an indication that a problem has occurred.- < Example >
- Communication with an external server has failed.
- < Example >
- WARNING
- This level is used to issue a warning when there is unexpected behavior that is not an execution error.
- < Example >
- The hardware data on each node in the response from the Grid Master is empty.
- < Example >
- INFO
- This level is used to output information during normal execution. For apis-ccc, it is used when event processing that is particularly important to operation is performed.
- < Example >
- Connection information for a server or other external service
- < Example >
- CONFIG
- This level relates to configuration settings, but is not output for apis-ccc.
- FINE
- This level is used for output of ordinary operation information during normal system operation.
- < Example >
- Information to be sent to a server or other external services
- < Example >
- FINER
- This level is for information related to the starting and stopping of specific processes, but is not output for apis-ccc.
- FINEST
- This level is used for output of ordinary operation information during normal system operation.
- < Example >
- When Vert.x Verticle is started up, etc.
- < Example >
The apis-ccc operation logs are output to three destinations: UDP, console, and file. The log output destinations and output levels can be set in the logging.properties file. UDP is used for security of data output to the communication line and line traffic. Output to file should be considered for the capacity of non-volatile storage.
When a problem occurs, the log is output to file, UDP, and console, but there is no function for the process to reset or stop itself.
The apis-ccc and the Grid Master communicate via the event bus and Hazelcast communication supported by the Vert.x and Hazelcast frameworks. For security, communication by both methods is encrypted by the methods listed below.
(1) Event bus communication
- SSL public-key cryptography (RSA)
- SSL self-signed certificate
(2) Hazelcast communication
- Shared-key cryptography (128-bit AES)
It is necessary to check whether or not the information that can be obtained via apis-ccc is personal information, because what is considered to be personal information varies with the region of introduction. Caution is required, because the act of sending personal information to an external server without the permission of the information owner may be subject to personal information protection regulations such as GDPR.
The software used by apis-ccc and the relevant open-source software licensing information is listed in the table below. Because Adopt OpenJDK is used by apis-ccc only as a linked library, it is not necessary to open the apis-ccc source code, even under GPL v2 with Classpath Exception applied. For the other software, also, no license requires the apis-ccc source code to be published.
■ Open-source software licensing of software used by apis-ccc
| Software | Version | License | Code Change |
|---|---|---|---|
| Adopt OpenJDK | 11.0.4+11 | GPLv2 with Classpath Exception | None |
| Vert.x | 3.7.1 | Dual license (select from the following) Eclipse Public License 2.0 Apache License 2.0 |
None |
| Hazelcast | 3.6.3 | Apache License 2.0 | None |
| Netty | 4.1.8 | Apache License 2.0 | None |
| FasterXML/Jackson | 2.7.4 | Apache License 2.0 | None |
*Software versions may change for various reasons.
The hardware requirements for apis-ccc are described below.
| CPU processor | 600 to 1000 MHz, 64 bit single-core, 32 KB L1 cache or more ARMv8 recommended |
| DRAM | DDR3, 1.6 Gbps, 1 GB or more |
| Internal storage | 8 GB or more |
| Ethernet | 20 Mbps, 1 port or more, IPv4 and IPv6 support |
The OS requirements for IoT boards used with apis-ccc use are described below.
| Type | 64-bit OS, Linux recommended (If an OS other than Linux is used, it is necessary to confirm APIS operation.) |
| Size | Depends on the capacity of the IoT Board (3 GB reserved for storing APIS logs, etc.) |
| Operating software | AdoptOpenJDK (32/64-bit) |
| Other | It shall be possible to run apis-ccc automatically when the OS boots. |
| ssh login/scp file transfer shall be possible. | |
| Logs can be periodically renamed, compressed, or deleted with logrotage, etc. | |
| A fixed IPv4 address shall be possible. | |
| Time synchronization with an ntp server shall be possible. |