apis-ccc Specification

Rev 0.63

apis-ccc Specification Document
Contents
1. Terms and Abbreviations
2. Overview
3. Software Composition
- 3.1. Software Architecture
- 3.2. .apis-ccc Services
4. Detailed Description of Actions
5. Data Acquisition
- 5.1. Data Acquired by Unit Data Reporting
- 5.2. Data Acquired by Deal Reporting
6. Configuration Files
7. Logging Functions
- 7.1.Log Level
- 7.2. Output Destinations of APIS Action Logs
8. Error Handling
9. Security
- 9.1. Inter-APIS Communication Security
10. Privacy
11. OPEN-SOURCE Software Licenses
12. Operating Environment
- 12.1. Recommended Hardware Specifications
- 12.2. Recommended Operating System Specifications

1. Terms and Abbreviations

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.

2. Overview

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

3. Software Composition

3.1. Software Architecture

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

3.2. .apis-ccc Services

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

4. Detailed Description of Actions

4.1. Unit Data Reporting

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

4.2. Deal Reporting

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

4.3. Scenario Acquisition

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

4.4. Policy Acquisition

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

4.5. Deallog Acquisition

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.

5. Data Acquisition

5.1. Data Acquired by Unit Data Reporting

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	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)

5.2. Data Acquired by Deal Reporting

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

6. Configuration Files

The various apis-ccc configuration files and key files are described below.

6.1. config.json

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)

6.2. cluster.xml

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.

6.3. logging.properties

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.).

6.4. start.sh

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

6.5. stop-kill.sh

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.

6.6. key.pem

This is the secret key used for SSL protection of the event bus.

6.7. cert.pem

This is the certificate used for SSL protection of the event bus.

7. Logging Functions

7.1.Log Level

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.

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.

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

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

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.

7.2. Output Destinations of APIS Action Logs

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.

8. Error Handling

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.

9. Security

9.1. Inter-APIS Communication Security

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)

10. Privacy

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.

11. OPEN-SOURCE Software Licenses

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.

12. Operating Environment

12.1. Recommended Hardware Specifications

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 (If a CPU other than ARMv8 is used, it is necessary to confirm APIS operation.)
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

12.2. Recommended Operating System Specifications

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!