Rev 0.6
- apis-service_center Specification
- Contents
- 1. Terms and Abbreviations
- 2. Overview
- 3. Software Composition
- 4. User Interface
- 5. Service Center Server
- 6. Registration to the Service Center
- 7. Communication Specifications
- 8. Configuration Files
- 9.Logging functions
- 10.Error Handling
- 11. Security
- 12. Privacy
- 13. OPEN-SOURCE Software Licenses
| Term | Explanation |
|---|---|
| apis-main | Software for energy sharing developed by Sony CSL that enables autonomous decentralized control. (For more information, refer to the apis-main specification document.) |
| apis-ccc | Client software for uploading information related to energy sharing to servers or other external services and downloading node configuration files from servers. (For more information, refer to the apis-ccc Specifications Document.) |
| apis-log | Software that receives information that is multicast via the communication line by apis-main and other software, converts it to JSON format, and writes it to a database. (For more information, refer to the apis-log specification document.) |
| Grid Master | Name of service included in apis-main. Controls the DC grid for energy sharing. |
| 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. |
| Vert.x | A framework for implementing load-balancing programs. Using Hazelcast, the event bus is clustered and load-balanced. |
Service Center is a Web application that provides information required by the administrators and users of clusters constructed of apis-main services installed in each unit. For administrators, the status and energy sharing information for each unit that is needed mainly for operation is displayed in real time. The energy sharing history, notifications of abnormalities, and availability ratio for each unit are also provided. For users, the status and energy sharing information for the user’s units are displayed as notification of energy sharing system operation. The energy sharing history and a scenario function for setting and changing the rules for performing energy sharing are also provided. Service Center groups clusters into communities for management (Figure 2-1).
Figure 2-1
The software architecture for the Service Center is illustrated in Figure 3-1. The implementation basically follows the rules of the Django framework and comprises multiple applications that provide various functions for administrators and users. The functions are accessed at different URL endpoints. The administrator and user interfaces have a standard configuration, and communication with the applications on the Service Center server is done with a Web page constructed using JavaScript and HTML styled with CSS. Web pages are provided as static sample files for single Django Service Center applications, but the static file can be cut out and deployed on any Web server, so the user interface part and the Service Center part can be placed on independent servers.
staff = administrators; resident = users
Figure 3-1
The connection diagram for the Service Center software is illustrated in Figure 3-2. Administrators can use the administration functions by accessing the administrator URLs via HTTP and entering an account name and password. Users can similarly access user functions via user URLs. After login, JavaScript is downloaded to provide functions that the administrator or user can interact with. The apis-ccc and apis-log services collect energy sharing data and execution logs from the apis-main installations in the cluster and store the data in a database. The Service Center applications access the database as needed to provide the functions to the administrator or user. (For more information on apis-main, apis-ccc, and apis-log, see their respective specification documents.)
Figure 3-2
The Service Center login screen (Figure 4-1) is presented when the administrator or user URL is first accessed. To use admin functions, it is necessary to access the administrator URL and enter an administrator account name and password. Similarly, users must access the user URL and provide a user account name and password to use user functions. Once the account name and password have been entered, the browser can save the login information, so subsequent logins are more convenient.
The Service Center that can be downloaded from GitHub can be accessed with the usernames and passwords listed below.
[Administrator]
username: admin
password: admin
[User]
username: e001 (e002, e003, e004, etc.)
password: e001 (e002, e003, e004, etc.)
Figure 4-1
When the admin URL is accessed, a screen is presented for selection of a community and the clusters that belong to it. Pull-down menus are provided for selecting communities and clusters. The registered information is displayed as soon as the pull-down menus for community, cluster, and unit are clicked.
*Click on a menu item to display the screen for other communities or clusters.
Figure 4-2
Figure 4-3
Clicking on the “Display” pull-down menu (Figure 4-4) presents a list of the four options described below.
[Display]
-VISUAL:
Displays the energy sharing and status of each unit in real time.
-AVAILABILITY:
Specifying a time period produces a display of the average availability for all units for that period and the availability for each unit.
-DEAL:
Shows the energy sharing history for the entire cluster.
-MONITORING:
Presents the screen for failure management, and alive monitoring on or off for the apis-main service of each unit and for apis-ccc and apis-log, which collect data and store it in the database.
Figure 4-4
VISUAL displays the energy sharing information and status of each unit in real time. The display for four units (house001 to house004) is shown in Figure 4-5. Dotted lines connect from house002 to house001 and to house003, representing that energy sharing is in progress from house002 to both house001 and house003. The crown symbol indicates that house001 is the Grid Master. (Concerning the Grid Master and the energy sharing mechanism, refer to the apis-main Specification Document.)
The Service Center example can be downloaded from GitHub using the following URL.
http://127.0.0.1:8000/static/ui_example/staff/visual.html
Figure 4-5
AVAILABILITY displays the average availability for all of the units in a cluster and the availability for each unit.
Entering a time period, such as <“2020-01-01” – “2020-01-07”>, and clicking the “Aggregate” button results in a display of the average rates for all of the units in the first cluster in the list and the rates for each unit in the cluster (Figure 4-6).
The Service Center example can be downloaded from GitHub using the following URL.
http://127.0.0.1:8000/static/ui_example/staff/availability.html
Figure 4-6
Clicking on the “Details” button on the right side of each unit line displays the individual information for that unit (Figure 4-7).
Figure 4-7
DEAL displays the energy sharing history. When a date (E.g.: ”2020-01-01”) is entered and the “Aggregate” button is clicked, the energy sharing data for all units for each hour of that date is presented as a bar graph (Figure 4-8). The segmented line in the graph represents the averages of all units in the cluster for the power exchange period.
The Service Center example can be downloaded from GitHub using the following URL.
http://127.0.0.1:8000/static/ui_example/staff/deal.html
Figure 4-8
Clicking on the “Details” button below the summary brings up energy sharing information as shown in Figure 4-9.
Figure 4-9
Clicking on the “Details” button to the right of each line of energy sharing information displays more information on that transaction (Figure 4-10).
Figure 4-10
MONITORING displays the on/off screen for the alive monitoring and failure detection functions for the apis-main, apis-ccc, and Grid Master services in the cluster (Figure 4-11 and Figure 4-12). Alive monitoring and failure detection can be toggled on or off by checking or unchecking the checkbox on the right side of each line. Display in green indicates the ON state; display in red indicates the OFF state.
The Service Center example can be downloaded from GitHub using the following URL.
http://127.0.0.1:8000/static/ui_example/staff/monitoring.html
Figure 4-11
Figure 4-12
Clicking on the “Details” button to the right of each line of failure information displays more information on that failure (Figure 4-13).
Figure 4-13
When the user URL is accessed, a screen is presented for selection of a community and the clusters that belong to it in the same way as for the administrator URL. Pull-down menus are provided for selecting communities and clusters. For the user screen, there is an additional “Unit” pull-down menu for selecting a unit ID for which information will also be displayed. The registered information is displayed as soon as the pull-down menu is clicked.
Figure 4-14
Clicking on the “Display” pull-down menu (Figure 4-15) presents a list of the three options described below.
[Display]
-VISUAL:
Displays the energy sharing and status of the specified unit in real time.
-DEAL:
Displays the energy sharing history for the specified unit.
-SCENARIO:
Changes the operation rules that determine behavior in energy sharing.
Figure 4-15
For users, VISUAL displays the energy sharing information and status of only the user’s unit in real time. The state in which there is no energy sharing is shown on the left side of Figure 4-16 and the state in which there is energy sharing is shown on the right side. When energy sharing is displayed, only as many units for which energy sharing is in progress are shown; to protect personal information, other unit information is not shown. Energy sharing is being conducted with the two other units that appear as shadows in the image on the right side of Figure 4-16.
The Service Center example can be downloaded from GitHub using the following URL.
http://127.0.0.1:8000/static/ui_example/resident/visual.html
Figure 4-16
For the user, DEAL displays the energy sharing history. When a date (E.g.: ”2020-01-01”) is entered and the “Aggregate” button is clicked, the energy sharing data for all units for each hour of that date is presented as a bar graph (Figure 4-17). The segmented line in the graph represents the averages of all units in the cluster for the power exchange period.
The Service Center example can be downloaded from GitHub using the following URL.
http://127.0.0.1:8000/static/ui_example/resident/deal.html
Figure 4-17
Clicking on the “Details” button below the summary brings up energy sharing information as shown in Figure 4-18.
Figure 4-18
Clicking on the “Details” button to the right of each line of energy sharing information displays more information on that transaction (Figure 4-19).
Figure 4-19
SCENARIO enables the user to change the action rules that determine the behavior of the unit for energy sharing by selecting from the displayed scenarios that represent energy sharing action rules. In the example shown in Figure 4-20, four scenario options are presented, but the number of options presented can be increased by the administrator. (For information on scenario registration, see section 6, “Registration of information to the Service Center”.)
The Service Center example can be downloaded from GitHub using the following URL.
http://127.0.0.1:8000/static/ui_example/resident/scenario.html
Figure 4-20
To choose a scenario, click on the “Choose” button on the right side of the line for that scenario. Clicking on the “Detail” button allows the user to check the JSON file for the scenario (Figure 4-21). (For information on the scenario JSON files, refer to the apis-main Specification Document.)
Figure 4-21
Service Center comprises the Django applications described below.
- ”api” application
- The API bundles all the applications for publication.
- ”apis_log” application
- This application contains the models for apis-log and retrieves data from the MongoDB database according to requests from various applications.
- ”community” application
- This application contains the models for community, cluster, and unit, and retrieves data from the SQLite database according to requests from various applications.
- ”core” application
- This application manages login and logout and authenticates administrators and users.
- ”deal” application
- This application contains the models for energy sharing deals and retrieves energy sharing data from the MongoDB database.
- ”downtime” application
- This application contains the models for down time and retrieves unit data from the MongoDB database.
- ”monitoring” application
- This application contains the models for failure monitoring and performs alive monitoring and failure detection based on information stored in the MongoDB database by apis-log.
- ”scenario” application
- This application contains the models for scenarios. It retrieves the rules that determine requests and acceptances for energy sharing for each level of battery state of charge from the SQLite database and distributes that information to the apis-main of each unit.
- ”unit_data” application
- This application contains the models for unit data and retrieves unit data for each unit from the MongoDB database.
The applications are explained in detail in the following sections.
The file structure for the api application is described below. (Basically, the structure follows the rules for the Django framework.)
▼static/ui_example
Contains sample files of HTML screens for users or administrators.
-
/resident
- css
A folder that holds all of the CSS files for user pages. - js
A folder that holds all of the JavaScript files for user pages. - deal.html
The HTML file for the user DEAL display page. - scenario.html The HTML file for the user SCENARIO display page.
- visual.html
The HTML file for the user VISUAL display page.
- css
-
/staff
- css
A folder holds all of the CSS files for administrator pages. - js
A folder that holds all of the JavaScript files for administrator pages. - availability.html
The HTML file for the administrator AVAILABILITY display page. - deal.html
The HTML file for the administrator DEAL display page. - monitoring.html
The HTML file for the administrator MONITORING display page. - visual.html
The HTML file for the administrator VISUAL display page.
- css
▼static/api
These are test HTML files for evaluating the client.js program. They can be used to evaluate the session function and getting data from the database.
- resident/client_example.html
- staff/client_example.html
▼templates/api
A folder that holds all of the template files for JavaScript. The placement of files for users and administrators is shown below.
-
resident/client.js
This JavaScript file is downloaded to the user’s browser together with the JavaScript file under static/ui_example to serve as the interface to the various Service Center applications. -
staff/client.js
This JavaScript file is downloaded to the user’s browser together with the JavaScript file under static/ui_example to serve as the interface to the various Service Center applications.
▼urls
-
_init_.py
-
The urls description file below the “api” application.
The files described in urls are located at the Web API access points listed below.- /api/core/xxx
→ The urls.py file under the “core” application. - /api/staff/xxx
→ The staff.py file under the urls folder below the “api” application. - /api/resident/xxx
→ The resident.py file under the urls folder below the “api” application. - /api/misc/xxx
→ The misc.py file under the urls folder below the “api” application.
- /api/core/xxx
-
-
misc.py
-
The urls description file below the “api” application.
The files described in urls are located at the Web API endpoints listed below.- /api/misc/scenario/xxx
→ The misc.py of the urls folder below the scenario application.
- /api/misc/scenario/xxx
-
-
resident.py
-
The urls description file below the “api” application.
The files described in urls are located at the Web API endpoints listed below.- /api/resident/client.js
→ This renders the resident/client.js template under the “api” application. - /api/resident/community/xxx
→ The resident.py file under the “community” application. - /api/resident/unitData/xxx
→ The resident.py of the urls folder under the “unit_data” application. - /api/resident/deal/xxx
→ The resident.py of the urls folder under the “deal” application. - /api/resident/scenario/xxx → The resident.py of the urls folder under the “scenario” application.
- /api/resident/client.js
-
-
staff.py
-
The urls description file below the “api” application.
The files described in urls are located at the Web API endpoints listed below.- /api/staff/client.js → This renders the staff/client.js template under the “api” application.
- /api/staff/community/xxx → The staff.py of the urls folder under the “community” application.
- /api/staff/unitData/xxx → The staff.py of the urls folder under the “unit_data”.
- /api/staff/deal/xxx
→ The staff.py of the urls folder under the “deal” application. - /api/staff/downtime/xxx
→ The staff.py of the urls folder under the “downtime” application. - /api/staff/monitoring/xxx
→ The staff.py of the urls folder under the “monitoring” application.
-
▼_init_.py
An empty file generated automatically by the Django framework.
▼admin.py
An empty file generated automatically by the Django framework.
▼apps.py
This file is registered in INSTALLED_APPS in config/settings/base.py and describes the processing executed on start-up. It defines the ApiConfig class.
▼modelst.py
An empty file generated automatically by the Django framework.
▼tests.py
An empty file generated automatically by the Django framework.
▼views.py
An empty file generated automatically by the Django framework.
The file structure for the “apis_log” application is described below. (Basically, the structure follows the rules for the Django framework.)
▼_init_.py
An empty file generated automatically by the Django framework.
▼admin.py
An empty file generated automatically by the Django framework.
▼apps.py
This file is registered in INSTALLED_APPS in config/settings/base.py and describes the processing executed at start-up. It defines the ApisLogConfig class.
▼modelst.py
The following models are defined as classes.
- ApisLog
This is a model that represents the APIS execution log.
It specifies Community, Cluster, and Unit and conditions such as time period, retrieves information that matches the conditions from the MongoDB database, and returns the information.
▼tests.py
An empty file generated automatically by the Django framework.
▼views.py
An empty file generated automatically by the Django framework.
The file structure for the “community” application is shown below. (Basically, the structure follows the rules for the Django framework.)
▼fixtures
- example.json
This JSON file is used for batch registration of Community, Cluster, or Unit information, etc. in the SQLite database.
▼migrations
This file is created automatically when migration of a model defined in model.py is performed.
▼urls
-
resident.py
- The urls description file under the “community” application.
The following Web API access points are the locations of the functions that do the actual processing.- /api/resident/community/outline
→ The resident_outline function in the views.py file under the “community” application.
- /api/resident/community/outline
- The urls description file under the “community” application.
-
staff.py
- The urls description file under the “community” application.
The following Web API access points are the locations of the functions that do the actual processing.- /api/staff/community/outline
→ The outline function in the views.py file under the “community” application.
- /api/staff/community/outline
- The urls description file under the “community” application.
▼_init_.py
An empty file generated automatically by the Django framework.
▼admin.py
Defines the UnitAdmin class, which enables creation or editing of models defined in models.py on the admin screen.
▼apps.py
Registered in the INSTALLED_APPS of config/settings/base.py and describes the processing executed at start-up. Defines the CommunityConfig class.
▼models.py
The following models are defined as classes.
- Community
A model that represents a community. - Cluster
A model that represents a cluster. - Unit
A model that represents a unit.
The following functions are defined.
-
outline Retrieves the hierarchical structure of Community, Cluster, and Unit for the specified date. (for administrators)
-
resident_outline
Retrieves the hierarchical structure of Community, Cluster, and Unit. (for users)
▼tests.py
An empty file generated automatically by the Django framework.
▼views.py
The following functions are defined.
-
outline
This is an administrator function that retrieves the hierarchical structure of Community, Cluster, and Unit for the specified date from the SQLite database and returns it in JSON format. -
resident_outline
This is a user function that retrieves the hierarchical structure of Community, Cluster, and Unit from the MongoDB database and returns it in JSON format.
The file structure for the “core” application is shown below. (Basically, the structure follows the rules for the Django framework.)
▼fixtures
- example.json
This JSON file is used when batch-saving administrator and user information in the SQLite database.
▼migrations
A file that is generated automatically upon migration of models defined in model.py.
▼_init_.py
An empty file generated automatically by the Django framework.
▼admin.py
Defines the MyUserChangeForm, and MyUserAdmin classes to enable registration ad editing of the models defined in models.py from the admin screen.
▼apps.py
Registered in the INSTALLED_APPS of config/settings/base.py and describes the processing executed at start-up. Defines the CoreConfig class.
▼decorators.py
This file defines decorator functions for checking permissions for the execution of the functions defined in the application vies.py file.
-
login_required Execution is permitted only when logged in.
-
staff_required
Execution permitted only for users that have admin privileges. -
resident_required
Execution is permitted only for users that have resident privileges. -
staff_with_community_cluster_required
Execution is permitted only when a user that has admin privileges has sent the correct Community ID and Cluster ID. -
resident_with_community_cluster_unit_required
Execution is permitted only when a user that has resident privileges has sent the correct Community ID, Cluster ID, and Unit ID. -
nosession_community_cluster_unit_required
Execution is permitted only when a user that has admin privileges has sent authentication information and the correct Community ID, Cluster ID, and Unit ID.
▼models.py
The following classes are defined.
- User
Defines the user model.
▼mongodb.py
The following models are defined as classes.
- MongoDBManager
This overrides the Django Model Manager for MongoDB
▼tests.py
An empty file generated automatically by the Django framework.
▼urls.py
-
The urls description file under the “core” application.
The following Web API access points are the locations of the classes and functions that do the actual processing.-
/api/core/login
→ The MyLoginView class in the views.py folder of the “core” application. -
/api/core/logout
→The MyLogoutView class in the views.py folder of the “core” application. -
/api/core/session
→ The session function in the views.py folder of the “core” application. -
/api/core/csrftoken
→”The csrftoken function in the views.py folder of the “core” application.
-
▼utils.py
This file defines utility functions that are used by the various applications.
-
pymongo_no_id_projection
This performs processing to remove the _id attribute from the result when using MongoDB via PyMongo. -
pymongo_result_conv
Converts the naïve UTC datetime value returned by PyMongo to aware. -
parse_iso8601_extended
Parses ISO8601 format datetime strings. -
parse_iso8601_extended_timezone
Parses ISO8601 format time zone strings.
▼views.py
The following classes are defined.
-
MyLoginView
A class that performs login functions. -
MyLogoutView
A class that performs logout functions.
The following functions are defined.
-
session
A function that does session processing. -
csrftoken
A function that performs token processing for countering CSRF.
The file structure for the “deal” application is shown below. (Basically, the structure follows the rules for the Django framework.)
▼urls
-
resident.py
-
The urls description file under the “deal” application. The following Web API access points are the locations of the functions that do the actual processing.
-
/api/resident/deal/liveList → The resident_live_list function in the views.py file under the “deal” application.
-
/api/resident/deal/live
→ The resident_list function in the views.py file under the “deal” application. -
/api/resident/deal/datetimeRange → The resident_datetime_range function in the views.py file under the “deal” application.
-
/api/resident/deal/sumOfCumulateAmountWhsByHour
→ The resident_sum_of_cumulate_amount_whs_by_hour function in the views.py file under the “deal” application.
-
-
-
staff.py
-
The urls description file under the “deal” application.
The following Web API access points are the locations of the functions that do the actual processing.-
/api/staff/deal/liveList
→ The live_list function in the views.py file under the “deal” application. -
/api/staff/deal/live
→ The list function in the views.py file under the “deal” application. -
/api/staff/deal/datetimeRange
→ The datetime_range function in the views.py file under the “deal” application. -
/api/staff/deal/sumOfCumulateAmountWhsByHour → The sum_of_cumulate_amount_whs_by_hour function in the views.py file under the “deal” application.
-
-
▼_init_.py
An empty file generated automatically by the Django framework.
▼admin.py
An empty file generated automatically by the Django framework.
▼apps.py
Registered in the INSTALLED_APPS of config/settings/base.py and describes the processing executed at start-up. Defines the DealConfig class.
▼models.py
The following models are defined as classes.
- Deal
A model that represents energy sharing information.
The following functions are defined.
- ensure_indices Creates an index on a MongoDB collection.
▼tests.py
An empty file generated automatically by the Django framework.
▼views.py
The following functions are defined.
-
live_list
This function creates a list of information on currently running energy sharing for the cluster specified by Community ID and Cluster ID and returns the information in JSON format. -
list
This function creates a list of information on energy sharing that was performed for the cluster specified by Community ID and Cluster ID and returns the information in JSON format. -
datetime_range
This function creates a list of information on energy sharing that was performed for the cluster specified by Community ID and Cluster ID in the specified time period and returns the information in JSON format. -
sum_of_cumulate_amount_whs_by_hour
This function creates a list of information on cumulative energy sharing for the cluster specified by Community ID and Cluster ID for each hour, and returns the information in JSON format. -
resident_live_list
This function creates a list of information on currently running energy sharing for the unit specified by Community ID, Cluster ID, and Unit ID and returns the information in JSON format. -
resident_list
This function creates a list of information on energy sharing performed for the unit specified by Community ID, Cluster ID, and Unit ID and returns the information in JSON format. -
resident_datetime_range
This function creates a list of information on energy sharing that was performed for the cluster specified by Community ID, Cluster ID, and Unit ID in the specified time period and returns the information in JSON format.
The file structure for the “downtime” application is shown below. (Basically, the structure follows the rules for the Django framework.)
▼urls
- staff.py
-
The urls description file under the “downtime” application.
The following Web API access points are the locations of the functions that do the actual processing.-
/api/staff/downtime/unitIdList
→ The unit_id_list function in the views.py file under the “downtime” application. -
/api/staff/downtime/list
→ The list function in the views.py file under the “downtime” application.
-
-
▼_init_.py
An empty file generated automatically by the Django framework.
▼admin.py
An empty file generated automatically by the Django framework.
▼apps.py
Registered in the INSTALLED_APPS of config/settings/base.py and describes the processing executed at start-up. Defines the DowntimeConfig class.
▼job.py
Defines functions used by the “downtime” application.
-
init
An initialization function that creates a new thread and executes the loop function in the daemon mode. -
loop
A function that creates an infinite loop for execution of the _do_all function at the time intervals specified by DOWNTIME.interval_sec in config/settings/base.py after initially waiting for the time specified by DOWNTIME.initial_wait_sec in config/settings/base.py. -
do_all A function for performing downtime accumulation processing that creates a new thread and executes the _do_units function for all clusters of all communities.
-
do_units
A function for performing downtime accumulation processing that executes the _do_unit function for of the units in one cluster. -
do_unit
A function for performing downtime accumulation processing that obtains the unit data for the unit specified by Community ID, Cluster ID, and Unit ID, and updates the downtime appropriately according to the time and apis.operation_mode.effective attributes. -
find_unit_data
A function that retrieves the Unit Data, and if last_time is specified, filters the data to include only the values for which the time attribute is greater than last_time. -
get_last_time
Retrieves the time of the Unit data that was processed last. -
save_last_time
Saves the time of the Unit data that was processed last. -
get_active_down_datetime
Retrieves the active downtime that has no recoveryDataTime. -
save_active_down_datetime
Saves the active downtime that has no recoveryDataTime. -
save_recovery_datetime
Saves recoveryDataTime and terminates the active downtime. -
handle_exception
Describes processing for when exceptions are thrown in program execution.
▼models.py
The following models are defined as classes.
- Downtime
A model that represents “downtime”.
Defines a method that returns the downtime that matches specified conditions.
- DowntimeStatus
A model that represents the state of cumulative “downtime” processing.
Defines a method that returns a list of unit IDs that possess a processing state.
The following functions are defined.
- ensure_indices Creates an index on a MongoDB collection.
▼tests.py
An empty file generated automatically by the Django framework.
▼views.py
The following functions are defined.
-
unit_id_list This function creates a list of unit IDs for the cluster specified by Community ID and Cluster ID that have a processing state and returns the list in JSON format.
-
list
This function creates a list of downtimes filtered by time period for the unit specified by Community ID, Cluster ID, and Unit ID and returns the list in JSON format.
The file structure for the “monitoring” application is shown below. (Basically, the structure follows the rules for the Django framework.)
▼job
Jobs perform alive monitoring and failure detection based on information from the MongoDB for apis-main, apis-ccc, and other such software.
-
_init_.py
The init function of job/_init_.py is executed when the Service Center server is run by specifying the MonitoringConfig class in apps.py in the INSTALLED_APPS of config/settings/base.py. The init function executes the Invoker class of each job instance in the background. -
abstract.py
Defines Invoker, Monitor, Notifier parent classes that inherit from Django framework Thread. -
apis_ccc_alive.py
Defines the parent alive Monitor class that inherits from the Invoker, Monitor, and Notifier classes of abstract.py and is used by apis-ccc for alive monitoring. -
apis_ccc_severe.py
Defines the parent failure detection Monitor class that inherits from the Invoker, Monitor, and Notifier classes of abstract.py and is used by apis-ccc for failure detection monitoring. -
apis_log_severe.py
Defines the parent alive Monitor class that inherits from the Invoker, Monitor, and Notifier classes of abstract.py and is used by apis-log for alive monitoring. -
apis_main_alive.py
Defines the parent alive Monitor class that inherits from the Invoker, Monitor, and Notifier classes of abstract.py and is used by apis-main for alive monitoring. -
apis_main_severe.py
Defines the parent failure detection Monitor class that inherits from the Invoker, Monitor, and Notifier classes of abstract.py and is used by apis-main for failure detection monitoring. -
config.py
Defines functions used by the monitoring application. -
grid_master_alive.py
Defines the alive Monitor class that inherits from the Invoker, Monitor, and Notifier classes of abstract.py and is used by the Grid Master.
▼migrations
This file is generated automatically when migration of a model defined in model.py is performed.
▼urls
- staff.py
-
The urls description file under the “monitoring” application. The following Web API access points are the locations of the functions that do the actual processing.
-
/api/staff/monitoring/failure/openList
→ The failure_open_list function in the views.py file under the “monitoring” application. -
/api/staff/monitoring/failure/list
→ The failure_list function in the views.py file under the “monitoring” application. -
/api/staff/monitoring/job/list
→ The job_list function in the views.py file under the “monitoring” application. -
/api/staff/monitoring/job/activate
→ The job_set_is_active (is_active=True) function in the views.py file under the “monitoring” application. -
/api/staff/monitoring/job/deactivate
→ The job_set_is_active(is_active=False) function in the views.py file under the “monitoring” application.
-
-
▼_init_.py
An empty file generated automatically by the Django framework.
▼admin.py
Defines the FailureAdmin, CommunitySettingAdmin, and JobSettingAdmin classes, which enable creation or editing of models defined in models.py on the admin screen.
▼apps.py
Registered in the INSTALLED_APPS of config/settings/base.py and describes the processing executed at start-up. Defines the MonitoringConfig class.
▼models.py
The following models are defined as classes.
-
Failure
A model representing failures. -
CommunitySetting
A model representing the settings for a community. -
JobSetting
A model representing settings for monitoring processing for a cluster.
▼tests.py
An empty file generated automatically by the Django framework.
▼views.py
The following functions are defined.
-
failure_open_list
This function creates an open list of failure information for the cluster specified by Community ID and Cluster ID and returns the information in JSON format. -
failure_list
This function creates a list of information on failures for the cluster specified by Community ID and Cluster ID filtered by time period and returns the information in JSON format. -
job_list
This function creates a list of active jobs for the cluster specified by Community ID and Cluster ID and returns the information in JSON format. -
job_set_is_active
This function sets jobs in a cluster specified by Community ID and Cluster ID to active or inactive.
The file structure for the “scenario” application is shown below. (Basically, the structure follows the rules for the Django framework.)
▼fixtures
- example.json A JSON file that is used for batch registration of scenario data in an SQLite database.
▼migrations
This file is created automatically when migration of a model defined in model.py is performed.
▼urls
-
misc.py
-
A urls description file under the “scenario” application. The following Web API access points are the locations of the functions that do the actualprocessing.
-
/api/apis/scenario/currentData
→ The misc_current_data function in the views.py file under the “scenario”application. -
/api/apis/scenario/update
→ The misc_update function in the views.py file under the “scenario” application.
-
-
-
resident.py
-
A urls description file under the “scenario” application. The following Web API access points are the locations of the functions that do the actual processing.
-
/api/resident/scenario/availableList → The resident_availableList function in the views.py file under the “scenario” application.
-
/api/resident/scenario/current → The resident_current function in the views.py file under the “scenario” application.
-
/api/resident/scenario/choose → The resident_choose function in the views.py file under the “scenario” application.
-
-
▼_init_.py
An empty file generated automatically by the Django framework.
▼admin.py
Defines the ScenarioAdmin and ChoiceAdmin classes, which enable creation or editing of models defined in models.py on the admin screen.
▼apps.py
Registered in the INSTALLED_APPS of config/settings/base.py and describes the processing executed at start-up. Defines the ScenarioConfig class.
▼models.py
The following models are defined as classes.
-
Scenario
A model that represents scenarios. -
Choice
A model that represents scenario options.
▼tests.py
An empty file generated automatically by the Django framework.
▼views.py
The following functions are defined.
-
resident_availableList
A function that returns scenario information that can be selected for the specified unit. -
resident_current
A function that returns the scenario information that is currently selected for the specified unit. -
resident_choose
Selects the scenario for the specified unit.
Selects the scenario for the unit specified by scenarioId.
If not specified, sets the unselected state. -
misc_current_update
Returns the actual data part of the currently selected scenario for the specified unit. -
misc_update
Registers the dedicated scenario for the specified unit.
The file structure for the “unit_data” application is shown below. (Basically, the structure follows the rules for the Django framework.)
▼urls
-
resident.py
-
The urls description file under the “unit_data” application.
The following Web API access points are the locations of the functions that do the actual processing.- /api/resident/unit_data/latestSet
→ The resident_latest_set function in the views.py file under the “unit_data” application.
- /api/resident/unit_data/latestSet
-
-
staff.py
-
The urls description file under the “unit_data” application.
The following Web API access points are the locations of the functions that do the actual processing.-
/api/staff/unit_data/unitIdList
→ The unit_id_list function in the views.py file under the “unit_data” application.” -
/api/staff/unit_data/latestSet
→ The latest_set function in the views.py file under the “unit_data” application.”
-
-
▼_init_.py
An empty file generated automatically by the Django framework.
▼admin.py
An empty file generated automatically by the Django framework.
▼apps.py
Registered in the INSTALLED_APPS of config/settings/base.py and describes the processing executed at start-up. Defines the UnitDataConfig class.
▼models.py
The following models are defined as classes.
- UnitData
A model that represents Unit Data.
The following functions are defined.
- ensure_indices
Creates an index on a MongoDB collection.
▼tests.py
An empty file generated automatically by the Django framework.
▼views.py
The following functions are defined.
-
unit_id_list
Returns a list of IDs for the unit data of the specified community and cluster. -
latest_set
Returns the latest set of Unit Data for the specified community and cluster in JSON format. -
resident_latest_set
Returns the latest set of Unit Data for the specified unit in JSON format. -
to_resident_format
Converts Unit Data to the format for users.
The registration of communities, clusters, units and users to the Service Center is explained in this section.
Access 127.0.0.1:8000/admin to bring up the Django administration screen shown below.
Figure 6-1
“Groups” under “AUTHENTIFICATION AND AUTHORIZATION” is the default setting for Django and enables various restriction on access to each type of data. For this Service Center, however, use of that function is not assumed.
To register a new community, select “Communities” under “COMMUNNITY” to bring up the screen shown below and then enter the appropriate information as described below.
For “Code:” enter the same “communityId” as is specified in the config.json file for apis-main.
Name: Enter freely.
Figure 6-2
To register a new cluster, select “Clusters” under “COMMUNNITY” to bring up the screen shown below and then enter the appropriate information as described below.
For “Community:”, select the name of a community created with “Communities”.
For “Code:”, enter the same “clusterId” as is specified in the config.json file for apis-main.
Name: Enter freely.
Figure 6-3
To register a new unit, select “Units” under “COMMUNNITY” to bring up the screen shown below and then enter the appropriate information as described below.
For “Cluster:”, select the name of a cluster created with “Clusters”.
For “Code:”, enter the same “unitId” as is specified in the config.json file for apis-main.
Name: Enter freely.
For “Available from:”, enter the date on which use of the unit is to begin. (Optional)
(This is relevant to downtime, etc.)
For “Available to:”, enter the date on which use of the unit is to end. (Optional)
(This is relevant to downtime, etc.)
Users: Select a user to associate with the unit. (Optional)
(User registration is explained below.)
Figure 6-4
To register a new administrator or user, select “Users” under “CORE” to bring up the screen shown below and then enter the appropriate information as described below.
Username: Enter freely.
Password: Enter freely.
Figure 6-5
When finished, click on the “SAVE” button to bring up the screen shown below.
To create an administrator account, check the “Staff status” item.
Figure 6-6
To register a new email address for notification of failures within a community, select “Community Setting” under “MONITORING” to bring up the screen shown below.
For “Community Id:”, select a community code that was created with “Communities”.
For “Notify to:”, enter an email address at which to receive notification of failures.
Figure 6-7
To view a list of failures, select “Failures” under “MONITORING” to bring up the screen shown below. It is possible to display all of the failure information for all communities and all clusters at one time, but considering the huge amount of data, filtering as shown below is available.
Figure 6-8
To display a list of failures, select “Job settings” under “MONITORING” to bring up the screen shown below, which enables you to set registered job functions such as alive processing and failure detection on or off. This is the same as the ON/OFF function that can be accessed at the following URL.
http://127.0.0.1:8000/static/ui_example/staff/monitoring.html
Figure 6-9
To select a scenario for each unit, select “Choices” under “SCENARIO” to bring up the screen shown below.
For “Community Id:”, select the code of a community that was created with “Communities”.
For “Cluster Id:”, enter the code of a cluster that was created with “Communities”.
For “Unit Id:”, enter the code of a unit that was created with “Communities”.
Created: Enter the date.
Scenario: Select a registered scenario.
Figure 6-10
To register a new scenario, select “Scenarios” under “SCENARIO” to bring up the screen shown below.
Figure 6-11
Click on the “ADD SCENARIO” button to bring up the screen shown below.
For “Community Id:”, select the code of a community that was created with “Communities”. (*1)
For “Cluster Id:”, enter the code of a cluster that was created with “Communities”. (*1)
For “Unit Id:”, enter the code of a unit that was created with “Communities”. (*1)
Created: Enter the date.
Name: Enter the name of the new scenario.
Description: Enter a description of the scenario.
Data: Enter the scenario in JSON format.
(For how to create a scenario, refer to the sample and the apis-main Specification Document.)
(*1) If not specified, can be used by all units.
If communityId only is specified, can be used by all of the units in that community.
If communityId and clusterId are specified, can be used by all of the units in that cluster.
If communityId, clusterId, and unitId are specified, can be used only by that unit.
Figure 6-12
The Web API can be used for information exchange with Service Center. The specifications are explained below. (The reverse proxy path of the Web server is indicated by “/”.)
The GitHub sample can be accessed by adding the URL of the Web API after “http://127.0.0.1:8000/”.
Only the Web API endpoints listed below are accessed by the POST method; all others are accessed by the GET method. A POST leads to an example of access by curl; a GET leads to an example of access by Web browser.
(For a GET access with curl rather than with a Web browser, -H ‘Cookie: sessionid=xxxxxx’ is required.)
/api/core/login
/api/misc/scenario/currentData
/api/misc/scenario/update
| /api/core/login | Performs login processing for administrators and users. < Access example > (When a POST method is used, entry from a terminal is assumed.) Access the following URL and get the csrftoken and csrminddle from the cookie. curl -i 'http://localhost:8000/api/core/csrftoken' Then, execute the following command. curl -i 'http://localhost:8000/api/core/login' -H 'Cookie: csrftoken=xxxxxx' -F 'username=oes' -F 'password=oes' -F 'csrfmiddlewaretoken=xxxxxxxx' |
| /api/core/logout | Performs logout processing for administrators and users. (It is not possible to log out without having logged in and passed the session token.) < Access example > http://127.0.0.1:8000/api/core/logout < Return example > None |
| /api/core/session | Perform the Web session processing for Service Center. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/core/session < Return example > { "sessionid": "gs0vyzrs6puevlus2kw072t0y3vdnjwf", "expiry_age": 1209600, "expiry_date": "2020-12-07T13:42:42.274Z", "user": { "username": "admin", "last_name": "", "first_name": "", "email": "" } } |
| /api/core/csrftoken | Performs token processing to counter CSRF. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/core/csrftoken < Return example > { "csrfmiddlewaretoken": "xxxxxxxxxxxxxxxxxxxx" } |
| /api/staff/client.js | A JavaScript program that is downloaded to the browser of an administrator to serve as an interface with the various Service Center applications. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/staff/client.js < Return example > Refer to /api/staff/client.js |
| /api/staff/community/outline | [Admin Web API] Retrieves the hierarchical structure of communities, clusters, and units for the specified date and time from the MongoDB database and returns the result in JSON format. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/staff/community /outline < Return example > { "communities": { "oss_community": { "id": "oss_community", "name": "OSS Community", "clusters": { "oss_cluster": { "communityId": "oss_community", "id": "oss_cluster", "name": "OSS Cluster", "units": { "E001": { "communityId": "oss_community", "clusterId": "oss_cluster", "id": "E001", "name": "E001", "available_from": null, "available_to": null }, "E002": { "communityId": "oss_community", "clusterId": "oss_cluster", "id": "E002", "name": "E002", "available_from": null, "available_to": null }, } } } } |
| /api/staff/unitData/unitIdList | [Admin Web API] Returns a list of IDs for the unit data specified by Community ID and Cluster ID and returns it in JSON format. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/staff/unitData/unitIdList ?communityId=oss_community &clusterId=oss_cluster < Return example > [ "E001", "E002" ] |
| /api/staff/unitData/latestSet | [Admin Web API] Returns the most recent set of unit data for the specified unit in JSON format. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/staff/unitData/latestSet ?communityId=oss_community &clusterId=oss_cluster < Return example > { "E001": { "emu": { "charge_discharge_power": 299.2, "system_time": { "month": 12, "minute": 5, "day": 20, "hour": 23, "year": 2014 }, "pvc_charge_current": 0, "ups_input_voltage": 102.8, "rsoc": 46.56, "battery_current": -6.23, "battery_voltage": 52.1, "pvc_charge_voltage": 0.28, "ups_operation_mode": { "parameter": 80, "mode": 2, "stop_mode": 2 }, "ups_operation_schedule": 1, "ups_output_power": 130.0, "battery_rsoc": 34, "ups_output_frequency": 60, "pvc_charge_power": 0.0, "ups_output_current": 11.7, "dischargeable_time": { "minute": 0, "hour": 0 }, "ups_output_voltage": 102.8 }, "dcdc": { "status": { "status": "0x0000", "alarmState": "Light alarm", "operationMode": "Waiting" }, "meter": { "wg": 0, "tmp": 26.59, "vb": 48, "wb": -4.5, "vg": 0, "ib": -0.09, "ig": 0 }, "vdis": { "dvg": 350.0, "drg": 0.0 }, "param": { "dig": 0.0 } }, "oesunit": { "communityId": "oss_community", "clusterId": "oss_cluster", "id": "E001", "display": "E001", "sn": "1", "budo": "1", "ip": "169.254.209.84", "ipv6_ll": "NA", "ipv6_g": "NA", "mac": "8c:85:90:b2:14:ef" }, "time": "2019-12-31T20:36:10Z", "battery": { "rsoc": 46.56, "battery_operation_status": null }, "apis": { "version": "3.0.0", "remaining_capacity_wh": 2234, "deal_interlock_capacity": 2, "is_grid_master": true, "operation_mode": { "global": "autonomous", "local": null, "effective": "autonomous" } }, "datasetId": 1606189298143 }, } |
| /api/staff/deal/liveList | [Admin Web API] Returns a list of energy sharing data for energy sharing that is currently in progress in the cluster specified by Community ID and Cluster ID and returns the list in JSON format. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/staff/deal/liveList ?communityId=oss_community &clusterId=oss_cluster < Return example > [ { "unitId": "E003", "negotiationId": "d2db0d7a-5836-4a13-90bf-416ab4654a2c", "requestUnitId": "E003", "acceptUnitId": "E001", "requestDateTime": "2020-01-01T06:05:40Z", "acceptDateTime": "2020-01-01T06:05:40Z", "requestPointPerWh": 10.0, "acceptPointPerWh": 10.0, "requestDealGridCurrentA": 1.0, "acceptDealGridCurrentA": 1.0, "type": "charge", "chargeUnitId": "E003", "dischargeUnitId": "E001", "pointPerWh": 10.0, "chargeUnitEfficientGridVoltageV": 312.0, "dischargeUnitEfficientGridVoltageV": 312.0, "dealGridCurrentA": 1.0, "requestAmountWh": 1358, "acceptAmountWh": 536, "dealAmountWh": 50, "dealId": "f6f9743d-d6f0-4611-a5c9-b166c43acf95", "createDateTime": "2020-01-01T06:05:40Z", "compensationTargetVoltageReferenceGridCurrentA": -2.0, "activateDateTime": "2020-01-01T06:09:10Z", "warmUpDateTime": "2020-01-01T06:09:10Z", "dischargeUnitCompensatedGridCurrentA": -1.0, "chargeUnitCompensatedGridCurrentA": 1.0, "startDateTime": "2020-01-01T06:09:10Z", "cumulateDateTime": "2020-01-01T06:10:50Z", "cumulateAmountWh": 7.1944447, "communityId": "oss_community", "clusterId": "oss_cluster", "reportTime": 1606138146 } ] |
| /api/staff/deal/list | [Admin Web API] Returns a list of energy sharing data for energy sharing performed in the cluster specified by Community ID and Cluster ID and returns the list in JSON format (also filtered for the time period specified by datetimeFrom and datatimeTo). < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/staff/deal/list ?communityId=oss_community &clusterId=oss_cluster < Return example > [ { "unitId": "E004", "negotiationId": "592f2616-4c5e-4c40-a364-589b9c054221", "requestUnitId": "E004", "acceptUnitId": "E001", "requestDateTime": "2019-12-31T15:19:10Z", "acceptDateTime": "2019-12-31T15:18:30Z", "requestPointPerWh": 10.0, "acceptPointPerWh": 10.0, "requestDealGridCurrentA": 1.0, "acceptDealGridCurrentA": 1.0, "type": "charge", "chargeUnitId": "E004", "dischargeUnitId": "E001", "pointPerWh": 10.0, "chargeUnitEfficientGridVoltageV": 312.0, "dischargeUnitEfficientGridVoltageV": 312.0, "dealGridCurrentA": 1.0, "requestAmountWh": 646, "acceptAmountWh": 716, "dealAmountWh": 50, "dealId": "95bafe56-76b7-403f-8e6d-7f6e9af55d21", "createDateTime": "2019-12-31T15:19:10Z", "compensationTargetVoltageReferenceGridCurrentA": -2.0, "activateDateTime": "2019-12-31T15:22:50Z", "warmUpDateTime": "2019-12-31T15:22:50Z", "dischargeUnitCompensatedGridCurrentA": -1.0, "chargeUnitCompensatedGridCurrentA": 1.0, "startDateTime": "2019-12-31T15:22:50Z", "cumulateDateTime": "2019-12-31T15:34:30Z", "cumulateAmountWh": 50.361103, "stopDateTime": "2019-12-31T15:34:30Z", "deactivateDateTime": "2019-12-31T15:34:30Z", "communityId": "oss_community", "clusterId": "oss_cluster", "reportTime": 1606056822 } ] |
| /api/staff/deal/datetimeRange | [Admin Web API] Returns a list of time periods for the dates and times when energy sharing was performed in the cluster specified by Community ID and Cluster ID, and returns the data in JSON format. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/staff/deal/datetimeRange ?communityId=oss_community &clusterId=oss_cluster < Return example > { "min": "2019-12-31T15:19:10Z", "max": "2020-01-09T09:08:10Z" } |
/api/staff/deal/ sumOfCumulateAmountWhsByHour |
[Admin Web API] Returns a list of the cumulative amounts of energy sharing data by the hour in the cluster specified by Community ID and Cluster ID, and returns the data in JSON format. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/staff/deal /sumOfCumulateAmountWhsByHour ?communityId=oss_community &clusterId=oss_cluster&timezone=%2B09%3A00 < Return example > { "0": 306.48328000000004, "1": 107.983345, "6": 215.96669, "7": 107.983345, "9": 316.74445000000003, "10": 1427.327889, "11": 414.934751, "12": 8.180555, "15": 107.49028799999999, "16": 315.454191, "17": 1481.980689, "18": 1947.715443, "19": 1184.748663 } |
| /api/staff/downtime/unitIdList | [Admin Web API] This creates a list of IDs of units in the cluster specified by Community ID and Cluster ID, and have the processing status for the time period. It returns the list in JSON format. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/staff/downtime /unitIdList?communityId=oss_community &clusterId=oss_cluster&datetimeFrom =2020-01-01T15%3A00%3A00.000Z
< Return example > [ "E001", "E002", "E003", "E004" ] |
| /api/staff/downtime/list | [Admin Web API] Returns a list of downtimes for the cluster specified by Community ID, Cluster ID, and time period and returns the list in JSON format. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/staff/downtime /list?communityId=oss_community &clusterId=oss_cluster&datetimeFrom =2020-01-01T15%3A00%3A00.000Z &datetimeTo=2020-01-02T15%3A00%3A00.000Z < Return example > [ { "clusterId": "oss_cluster", "communityId": "oss_community", "recoveryDateTime": "2019-12-31T15:12:20Z", "unitId": "E001", "downDateTime": "2019-12-31T15:07:20Z" }, { "clusterId": "oss_cluster", "communityId": "oss_community", "recoveryDateTime": "2019-12-31T15:12:20Z", "unitId": "E004", "downDateTime": "2019-12-31T15:07:20Z" } ] |
| /api/staff/monitoring/failure/openList | [Admin Web API] Returns a list of open failure information for the cluster specified by Community ID and Cluster ID and returns the list in JSON format. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/staff/monitoring /failure/openList?communityId=oss_community &clusterId=oss_cluster < Return example > [ { "id": 53, "type": "apis_ccc_alive", "community_id": "oss_community", "cluster_id": "oss_cluster", "program_id": "apis-ccc", "unit_id": null, "detected": "2020-11-24T03:27:51.696Z", "closed": null, "description": "The program may not be running." } ] |
| /api/staff/monitoring/failure/list | [Admin Web API] Returns a list of all failure data specified by Community ID and Cluster ID and returns the list in JSON format (also filtered for the time period specified by datetimeFrom and datatimeTo). < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/staff/monitoring /failure/list?communityId=oss_community &clusterId=oss_cluster < Return example > [ { "id": 6, "type": "apis_ccc_alive", "community_id": "oss_community", "cluster_id": "oss_cluster", "program_id": "apis-ccc", "unit_id": null, "detected": "2020-11-23T15:42:17.781Z", "closed": "2020-11-24T03:08:09.412Z", "description": "The program may not be running." } ] |
| /api/staff/monitoring/job/list | [Admin Web API] Creates a list of Active/ Inactive Units in the cluster specified by Community ID and Cluster ID, and returns the list in JSON format. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/staff/monitoring /job/list?communityId=oss_community &clusterId=oss_cluster < Return example > [ { "type": "apis_main_alive", "isActive": true }, { "type": "apis_ccc_alive", "isActive": false }, { "type": "apis_ccc_severe", "isActive": true }, { "type": "apis_log_severe", "isActive": false } ] |
| /api/staff/monitoring/job/activate | [Admin Web API] Sets the jobs in the cluster specified by Community ID and Cluster ID to Active. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/staff/monitoring /job/activate?communityId=oss_community &clusterId=oss_cluster&type=apis_ccc_severe < Return example > OK |
| /api/staff/monitoring/job/deactivate | [Admin Web API] Sets the jobs in the cluster specified by Community ID and Cluster ID to Inactive <E.g.> A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/staff/monitoring /job/deactivate?communityId=oss_community &clusterId=oss_cluster&type=apis_ccc_severe < Return example > OK |
| /api/resident/client.js | [User WebAPI] A JavaScript program that is downloaded to the browser of a user to serve as an interface with the various Service Center applications. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/resident/client.js < Return example > Refer to /api/resident/client.js |
| /api/resident/community/outline | [User WebAPI] Retrieves the hierarchical structure of communities, clusters, and units for the specified date and time from the MongoDB database and returns the result in JSON format. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/resident/community /outline < Return example > { "communities": { "oss_community": { "id": "oss_community", "name": "OSS Community", "clusters": { "oss_cluster": { "communityId": "oss_community", "id": "oss_cluster", "name": "OSS Cluster", "units": { "E001": { "communityId": "oss_community", "clusterId": "oss_cluster", "id": "E001", "name": "E001", "available_from": null, "available_to": null } } } |
| /api/resident/unitData/latestSet | [User WebAPI] Returns the most recent set of unit data for the specified unit in JSON format. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/resident/unitData /latestSet?communityId=oss_community &clusterId=oss_cluster&unitId=E001 < Return example > { "E001": { "emu": { "charge_discharge_power": 22.8, "system_time": { "month": 12, "minute": 5, "day": 20, "hour": 23, "year": 2014 }, "pvc_charge_current": 0, "ups_input_voltage": 102.8, "rsoc": 29.99, "battery_current": -0.48, "battery_voltage": 52.1, "pvc_charge_voltage": 0.28, "ups_operation_mode": { "parameter": 80, "mode": 5, "stop_mode": 2 }, "ups_operation_schedule": 1, "ups_output_power": 130.0, "battery_rsoc": 34, "ups_output_frequency": 60, "pvc_charge_power": 0.0, "ups_output_current": 11.7, "dischargeable_time": { "minute": 0, "hour": 0 }, "ups_output_voltage": 102.8 }, "dcdc": { "status": { "status": "0x0000", "alarmState": "Light alarm", "operationMode": "Waiting" }, "meter": { "wg": 0, "tmp": 26.59, "vb": 48, "wb": -4.5, "vg": 0, "ib": -0.09, "ig": 0 }, "vdis": { "dvg": 350.0, "drg": 0.0 }, "param": { "dig": 0.0 } }, "oesunit": { "communityId": "oss_community", "clusterId": "oss_cluster", "id": "E001", "display": "E001", "sn": "1", "budo": "1", "ip": "192.168.3.36", "ipv6_ll": "NA", "ipv6_g": "NA", "mac": "f0:23:b9:60:09:21" }, "time": "2020-01-01T15:37:40Z", "battery": { "rsoc": 29.99, "battery_operation_status": null }, "apis": { "version": "3.0.0", "remaining_capacity_wh": 1439, "deal_interlock_capacity": 2, "is_grid_master": true, "operation_mode": { "global": "autonomous", "local": null, "effective": "autonomous" } }, "datasetId": 1606141567737 } } |
| /api/resident/deal/liveList | [User WebAPI] Returns a list of energy sharing data for energy sharing that is currently in progress in the unit specified by Community ID, Cluster ID and Unit ID, and returns the list in JSON format. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/resident/unitData /liveList?communityId=oss_community &clusterId=oss_cluster&unitId=E001 < Return example > [ { "createDateTime": "2020-01-01T17:23:10Z", "dealId": "41044395-bde7-46e6-acce-0bbd447f3dbf", "dischargeUnitId": "E001", "chargeUnitId": "******", "type": "charge", "requestUnitId": "******", "requestAmountWh": 1420, "acceptUnitId": "E001", "dealAmountWh": 50, "startDateTime": "2020-01-01T17:26:40Z", "cumulateAmountWh": 7.1944447 }, |
| /api/resident/deal/list | [User WebAPI] Returns a list of energy sharing data for energy sharing that was performed in the unit specified by Community ID, Cluster ID and Unit ID, and returns the list in JSON format (also filtered for the time period specified by datetimeFrom and datatimeTo). < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/resident/unitData /list?communityId=oss_community &clusterId=oss_cluster&unitId=E001 < Return example > [ { "createDateTime": "2019-12-31T15:19:10Z", "dealId": "95bafe56-76b7-403f-8e6d-7f6e9af55d21", "dischargeUnitId": "E001", "chargeUnitId": "******", "type": "charge", "requestUnitId": "******", "requestAmountWh": 646, "acceptUnitId": "E001", "dealAmountWh": 50, "startDateTime": "2019-12-31T15:22:50Z", "cumulateAmountWh": 50.361103, "stopDateTime": "2019-12-31T15:34:30Z", "deactivateDateTime": "2019-12-31T15:34:30Z" } ] |
| /api/resident/scenario/availableList | [User WebAPI] Returns a list of the scenarios that can be used by the unit specified by Community ID, Cluster ID, and Unit ID, and returns the list in JSON format. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/resident/scenario /availableList?communityId=oss_community &clusterId=oss_cluster&unitId=E002 < Return example > [ { "id": 1, "community_id": null, "cluster_id": null, "unit_id": null, "created": "2020-11-26T04:26:59.166Z", "name": "HIGH_PRIORITY", "description": "Low rsoc, High priority", "data": "{ }, { "id": 2, "community_id": null, "cluster_id": null, "unit_id": null, "created": "2020-11-26T04:26:59.167Z", "name": "LOW_PRIORITY", "description": "High rsoc, Low priority", "data": "{ } ] |
| /api/resident/scenario/current | [User WebAPI] Returns a list of the scenarios that are currently selected for the unit specified by Community ID, Cluster ID, and Unit ID, and returns the list in JSON format. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/resident/scenario /current?communityId=oss_community &clusterId=oss_cluster&unitId=E002 < Return example > { "id": 1, "community_id": null, "cluster_id": null, "unit_id": null, "created": "2020-11-26T04:26:59.166Z", "name": "HIGH_PRIORITY", "description": "Low rsoc, High priority", "data": "{ } |
| /api/resident/scenario/choose | [User WebAPI] Returns a list of the scenarios that are currently selected for the unit specified by Community ID, Cluster ID, Unit ID, and Scenario ID, and returns the list in JSON format. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/resident/scenario /choose?communityId=oss_community &clusterId=oss_cluster&unitId=E002&scenarioId=2 < Return example > OK |
| /api/resident/deal/datetimeRange | [User WebAPI] Returns a list of time periods for the dates and times when energy sharing was performed in the cluster specified by Community ID and Cluster ID, and returns the data in JSON format. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/resident/deal /datetimeRange?communityId=oss_community &clusterId=oss_cluster&unitId=E001 < Return example > { "min": "2019-12-31T15:19:10Z", "max": "2020-01-09T09:08:10Z" } |
/api/resident/deal/ sumOfCumulateAmountWhsByHour |
[User WebAPI] Returns a list of the cumulative amounts of energy sharing data by the hour in the cluster specified by Community ID and Cluster ID, and returns the data in JSON format. < Access example > A GitHub sample can be accessed with the following URL. http://127.0.0.1:8000/api/resident/deal /sumOfCumulateAmountWhsByHour ?communityId=oss_community &clusterId=oss_cluster&unitId=E001 &timezone=%2B09%3A00 < Return example > { "0": 306.48328000000004, "1": 107.983345, "2": 305.763837, "6": 215.96669, "7": 107.983345, "9": 265.397236, "10": 1122.612606, "11": 212.427805, "12": 8.180555, "14": 102.161094, "15": 358.543009, "16": 106.99723, "17": 1016.948719, "18": 1591.284881, "19": 678.744472 } |
| /api/misc/scenario/currentData | [Scenario setting Web API] Returns the scenario specified by Community ID, Cluster ID, Unit ID, username, and password in JSON format. < Access example > A GitHub sample can be accessed with the following URL. (When it is a POST, entry from a terminal is assumed.) curl http://127.0.0.1:8000/api/misc/scenario /currentData -d username=e001 -d password=e001 -d communityId=oss_community -d clusterId=oss_cluster -d unitId=E001 < Return example > { "#": "High rsoc, Low priority", "refreshingPeriodMsec": 30000, "acceptSelection": { "#_strategy": "amount", "strategy": "pointAndAmount", "#": "end" }, "00:00:00-24:00:00": { "batteryStatus": { "3600-": "excess", "2400-3600": "sufficient", "0-2400": "scarce", "-0": "short" }, "request": { "excess": { "discharge": { "limitWh": 2400, "pointPerWh": 10 } }, "sufficient": { }, "scarce": { }, "short": { "charge": { "limitWh": 2400, "pointPerWh": 10 } } }, "accept": { "excess": { "discharge": { "limitWh": 2400, "pointPerWh": 10 } }, "sufficient": { "discharge": { "limitWh": 2400, "pointPerWh": 10 } }, "scarce": { "charge": { "limitWh": 3600, "pointPerWh": 10 } }, "short": { "charge": { "limitWh": 3600, "pointPerWh": 10 } } } } } |
| /api/misc/scenario/update | [Scenario setting Web API] This overwrites the scenario specified by Community ID, Cluster ID, Unit ID, username, password, and data (scenario name). If the scenario specified by data does not exist, a new one is created. < Access example > A GitHub sample can be accessed with the following URL. (When it is a POST, entry from a terminal is assumed.) curl http://127.0.0.1:8000/api/misc/scenario /update -d username=e001 -d password=e001 -d communityId=oss_community -d clusterId=oss_cluster -d unitId=E001 -d data=senario1 -d {Scenario JSON} < Return example > None |
Each application folder is accompanied by a config folder. The settings folders inside the config folders contain settings.py packages that are created by default when a Django project is created. Django parameters can be set by specifying a file in the settings folder as an argument when invoking Django as shown below.
--settings=config.settings.apis-service_center-demo
The above argument sets Django to start up with the settings specified in config/settings/apis-service_center-demo.py. The settings files in the folder are basically written according to the rules of the Django framework, but the parameters that are used in a unique way are explained below.
- MONGODB_DATABASES
The MongoDB databases are set up as described here.
The parameters an in config/settings/apis-service_center-demo.py.
The “downtime”, “unit_data”, “deal”, and “apis_log” are what is referred to as app_labels in Django. They must be the same as the various “database” setting in the config.json file for apis-ccc.
| downtime | HOST | localhost | The database IP Address |
| PORT | 27018 | The database port number | |
| NAME | apis_demo | he name of the “downtime” database collection | |
| unit_data | HOST | localhost | The database IP addres |
| PRT | 27018 | The database port number | |
| NAME | apis_demo | The name of the “downtime” database collection | |
| deal | HOST | localhost | The database IP Address |
| PRT | 27018 | The database port number | |
| NAME | apis_demo | The database collection name This must match the “collection” setting in unitDataReporting in the apis-ccc config.json file. |
|
| apis_log | HOST | localhost | The database IP address |
| PRT | 27018 | The database port number | |
| NAME | apis_demo | The database collection name This must match the “collection” setting in mongoDbWriter in the file.apis-log config.json file. |
- DOWNTIME
Sets the cumulative processing for the “downtime” application.
The parameters of config/settings/base.py are described below.
| initial_wait_sec | 5 | The time to wait immediately after the accumulation processing of the “downtime” application begins |
| interval_sec | 300 | The accumulation time interval for the “downtime” |
| unit_data_fetch_limit | 1000 | The upper limit for a single retrieval when data is accumulated at each interval\_sec. |
| data_loss_tolerance_sec | 120 | When the Unit Data time interval exceeds this value, it is judged to be data loss. |
- MONITORING
The “monitoring” processing is set.
The parameters in config/settings/base.py are described below.
| initial_wait_sec | 5 | ||
| interval_sec | apis_main_alive | 60 | The time interval for apis-main alive monitoring Alive monitoring is performed for the apis-main of each unit recorded in the Mongo DB database for which ‘^uri: ' output by the apis-main is checked. |
| apis_ccc_alive | 60 | The time interval for apis-ccc alive monitoring Alive monitoring is performed for each apis-ccc recorded in the MongoDB database for which '^reporting unit data' output by the apis-ccc is checked. |
|
| grid_master_alive | 60 | The time interval for Grid Master alive monitoring Alive monitoring is performed for each Grid Master recorded in the MongoDB database for which ‘^gridMasterUnitId:’ output by the Grid Master is checked. |
|
| apis_main_severe | 60 | The time interval for apis-main failure monitoring Failure monitoring is performed for the apis-main of each unit recorded in the MongoDB database for which ‘SEVERE’ level output by the apis-main is checked. |
|
| apis_ccc_severe | 60 | The time interval for apis-ccc failure monitoring Failure monitoring is performed for each apis-ccc recorded in the MongoDB database for which ‘SEVERE’ output by the apis-ccc is checked. |
|
| apis_log_severe | 60 | The time interval for apis-log failure monitoring Failure monitoring is performed for each apis-log recorded in the MongoDB database for which ‘SEVERE’ output by the apis-log is checked. |
|
| thread_blocking_limit_msec | 300000 | The Vert.x Thread Blocking Log is checked and if the blocked threads value exceeds this limit, the alive described above is judged to have failed. | |
| notify_from | [email protected] | The ‘From:’ of the notification email. | |
| default_notify_to | [email protected] | This address is used if the ‘To:’ of the notification email is not specified in the MONITORING Community Settings. | |
The log output settings are under LOGGING in config/settings/base.py. Logs are output to the three destinations listed below.
-
“console”
Output to the console is enabled by setting DEBUG = True in base.py. -
“file”
The Python standard library logging module is used and log levels of WARNING and higher are output. The file output destination is set in the following file.
/tmp/apis_service_center-warning.log -
“mail_admin”
Output to email is enabled by setting DEBUG = False in base.py.
When the Service Center itself fails, a log is output to a file and the console, but there is no function for the process to reset or stop itself.
HTTP communication with Service Center is not secured by SSL or other such means, so IP address restrictions or other such means are applied in the Web server settings as needed.
It is necessary to check whether or not the information that can be obtained via the Web API is personal information, because what is considered to be personal information varies with the region in which the Service Center is introduced. 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-service_center and the relevant open-source software licensing information is listed in the table below.
■ Open-source software licensing of software used by Service Center
| Software | Version | License | Code Change |
|---|---|---|---|
| python | 3.6.9 | PSL License | None |
| Django | 2.2.11 | BSD License | None |
| python-dateutil | 2.8.1 | Choose either Apache License 2.0 or BSD License | None |
| pymongo | 3.11.0 | Apache License 2.0 | None |
| sqlparse | 0.3.1 | BSD License | None |
| pytz | 2020.1 | MIT License | None |
| jQuery | 3.4.1 | Choose either MIT License or GPL v2 License | None |
| jQuery UI | 1.12.1 | Choose either MIT License or GPL v2 License | None |
JQuery Data Tables |
1.10.20 | MIT License | None |
| js-cookie | 2.2.1 | MIT License | None |
gstatic charts loader |
Latest | Apache License 2.0 | None |
*Software versions may change for various reasons.