apis-emulator Specification Document
Rev 0.61
- Contents
- 1. Terms and abbreviations
- 2. Overview
- 3. Software configuration
- 4. Functions
- 5. Communication specfications
- 6. Power storage system data
- 7. Configuration file
- 8. Log output
- 9. Sample data for solar radiation and household power consumption
- 10. Handling of abnormalities
- 11. Security
- 12. Privacy
- 13. OSS licensing
| Term | Explanation |
|---|---|
| apis-main | Software for energy sharing developed by Sony CSL that enables autonomous decentralized control |
| EMU | Energy Management Unit: A device for controlling a power storage system. |
The Emulator runs a computer emulation that reproduces the hardware system for energy sharing, including the battery system and the DC/DC converter, etc. The Emulator reads in data on the amount of solar radiation and the power consumption of residences and emulates the flow of energy such as the power generated and consumed by multiple residences, and battery system charging and discharging. The emulation conditions can be changed in real time by using a Web browser to access and change the hardware parameters. There is also a function for communication with apis-main, which reads storage battery data from the hardware emulation on the computer and operates the DC/DC converter to emulate energy sharing.
Figure 2-1
The Emulator software comprises a display module and a control module (Figure 3-1). The display module has a standard configuration, with the content structure defined by TPL templates, styled with CSS, and dynamic elements added with JavaScript. Those tools are used to construct browser screens that enable user access via the browser. For the controller module, the Python Bottle framework for creating Web apps is used to set up a Web server and Web API to enable access to processing by apis-main and the user. The Update Power Flow component is a computer emulation of the flow of power, including solar power generation, residential power consumption, and battery system charging and discharging, etc. The Input Data Manager component reads data such as amount of solar radiation and power demand data such as residential power consumption that is required for the emulation from a file in CSV format. The Initialize OES Unit component reads the parameters that are required for constructing the power storage system environment from a file in JSON format.
Figure 3-1
In the Emulator software connection configuration (Figure 3-2), user requests to Emulator via Web API and the request is received by the Bottle Web server. If the request is for display of the Emulator screen, the corresponding TPL template, CSS file, and JavaScript file are downloaded from the display module to the browser and the page is displayed. For other requests, the server collects the required information and returns it to the user. The Input Data Manager of the controller module reads the data required for emulation (amounts solar radiation and residential power consumption etc.) from a CSV file and stores it in variables and arrays. The Update Power Flow component uses the data compiled by Input Data Manager to emulate power flow, including power generation per unit time and power consumption, including hardware power loss, as well as the charging and discharging of the power storage system. The apis-main Controller Service communicates with the hardware environment generated on the computer via the Bottle Web Server Web API. Specifically, the battery system state of charge is obtained and the DC/DC Converter is controlled to implement mock energy sharing.
Figure 3-1
The Emulator screen presents information on the three power storage systems generated on the computer, E001, E002, and E003 (Figure 4-1). The number of power storage systems that can be displayed depends on the number of households for which power consumption data is read from the CSV file and the performance of the computer on which Emulator is running. If the Auto Refresh checkbox in the upper left corner of the screen is checked, the data for each power storage system is updated according to the emulation results.
Figure 4-1
The checkbox and buttons at the top of the screen shown in Figure 4-1 are explained below.
[Auto Refresh checkbox]
Checked: The displayed power storage system data is updated according to the emulation results every five seconds.
Not checked: The displayed data is not updated.
[Read All button]
Clicking this button updates all of the displayed power storage system data based on the emulation results.
[Set All button]
Clicking this button enables values for the items listed below to be entered to replace the current settings.
- Charge discharge power
- rsoc
- ups output power
- pvc charge power
- Powermeter all
- Powermeter p2
- Status
- Grid current
- Grid voltage
- Droop ratio
The entered values immediately replace the emulation parameters for all of the power storage systems. (For an explanation of the parameters, see Figure 4-2 and Figure 4-3.)
[Save All button]
This saves the parameters for all of the power storage systems in the emulation in the file jsontmp/lastSave.json. (Concerning the parameters that are saved, see section 6.1, “Parameters”.)
[Load Last button]
This reads the parameter values for all of the power storage systems from the jsontmp/lastSave.json file and uses them to replace the current emulation parameters.
[Reset button]
This reads the parameter values for all of the power storage systems from the jsontmp/fakeResponse.json file and uses them to replace the current emulation parameters. In doing so, required parameters are initialized.
[Add Unit button]
This adds one power storage system unit to the emulation each time it is clicked.
The power storage system ID is a serial number that is assigned when a unit is added. The serial number is incremented by one each time a unit is added. (For example, if E006 is the ID of the previously added unit, E007 will be assigned to the next unit that is added.)
When a unit is added, the default parameters are read from the jsontmp/standard.json file to initialize the required parameters.
[Remove Unit button]
This removes one power storage unit each time it is clicked.
Units are removed in order of highest assigned ID number.
[Set Acceleration Rate button]
This factor is used to change the progression of time in the emulation according to the number that is set in the field to the right of this button. (For example, if the number is set to 10, time in the emulation progresses 10 seconds for each second in the real world.)
The buttons in the individual power storge system information are explained below.
[Read]
This updates the information of the power storage system for which the button was clicked to the emulation result for the time at which the button was clicked.
[Set]
This replaces the emulation parameters with the values that are entered for the power storage system for which the button was clicked at the time the button was clicked. (For the parameters entered, see the explanation for the [Set All button].)
The information for a power storage system emulation created by Emulator is illustrated in Figure 4-2.
Figure 4-2
The Emulator information display for the power storage system alone is shown in Figure 4-3. Each item of information is explained below. (The numbers assigned in Figure 4-2 and Figure 4-3 are the same as the numbers in the following explanation.)
Figure 4-3
-
Charge-discharge power
The charge-discharge power of the power storage system [W] (absolute value) -
rsoc
Storage battery relative state of charge [%] -
ups output power
UPS output power [W] (corresponds to the residential power consumption) -
pvc charge power
Power output of the PVC [W] -
Powermeter all
Power consumption for the power storage system and residence [W] -
Powermeter p2
Power consumption of the power storage system [W] -
Status
Status of the DC/DC converter -
Grid current
DC Grid maximum current [A] -
Grid voltage
DC Grid target voltage [V] -
Droop ratio
DC Grid droop rate [%] -
Grid power
⑫ Grid current x ⑬ Grid voltage [W] -
Grid current
DC Grid current [A] -
Grid voltage
DC Grid voltage [V] -
Battery power
⑮ Battery current x ⑯ Battery voltage [W] -
Battery current
The storage battery current [A] -
Battery voltage
The storage battery voltage [V] -
Battery Status
② Battery relative state of charge [%] -
Operating power
DC/DC Converter loss [W]
Bottle is a Web server that performs various kinds of processing when it receives Web API requests from the user, apis-main, or a JavaScript script. The server IP address and port number are specified in the config.py file. (For more information, see section 7.1, “config.py”.
This reads the parameters required for constructing the power storage system environment from the jsontmp/standard.json file, changes the UnitID and other parameters that require individual changing, and stores the values in an array. The number of power storage systems to be generated on the computer is either passed in as the first parameter when invoking the Emulator or is determined by the number of displayNames registered in global_var.py.
This reads the solar radiation and residence power consumption data from the CSV files under data/input/Sample for use in the emulation. The samples include hourly solar radiation amounts for 365 days and residential power consumption per hour for 100 households for 365 days. The data that is read is stored in arrays.
The process described by steps (1) to (4) below is executed repeatedly by Emulator for computer emulation of the flow of power for a power storage system, including solar power generation, residential power consumption, and battery charging and discharging.
-
Change the UPS operation mode according to the state of charge of the battery. If the state of charge is low, change the mode to bypass and charge the battery from the grid.
-
Calculate the power for charging or discharging the battery from the power loss of the power storage system and the power generation and consumption, and update.
-
Advance the emulation world time according to the value set by the “Set Acceleration Rate button”. (For more information, see section 4.1, “Display module”.)
-
Calculate the values for solar power generation and residential power consumption over the time specified in step (3) and update the battery state of charge value.
The user performs browser operations to access Emulator via the Web API for information exchange. The Web API specifications are explained below.
| / | Present the screen for displaying or setting the parameters for all of the power storage systems in the emulation. |
| /restart | For the processing, see section 4.1, “Display module”, [Reset button]. |
| /add/unit | For the processing, see section 4.1, “Display module”, [Add Unit button]. |
| /remove/unit | For the processing, see section 4.1, “Display module”, [Remove Unit button]. |
| /get/log | Get the parameters for all of the power storage systems in the emulation. (For more information, see section 6.1, “Power storage system parameters”.) |
| /get/last | For the processing, see section 4.1, “Display module”, [Load Last button]. |
| /save | For the processing, see section 4.1, “Display module”, [Save All button]. |
| /get/emu/<oesid> | Get the EMU parameters for the power storage system specified by <oesid>. |
| /get/acc | Get the time acceleration rate of the emulation world. |
| /set/acc/<newacc> | Set the time acceleration rate of the emulation world to the value specified by . For the processing, see section 4.1, “Display module”, [Set Acceleration Rate button]. |
| /set/emu/<oesid> | Set the values specified by the query parameters as the EMU parameters for the power storage system specified by <oesid>. |
The apis-main performs browser operations to access Emulator via the Web API for information exchange. The Web API specifications are explained below.
| /get/unit/<oesid> | Get the parameters for the power storage system specified by <oesid>. (The parameters that can be obtained are the same as for /get/log.) |
| /get/dcdc/status/<oesid> | Of the DC/DC Converter parameters for the power storage system specified by <oesid>, get only the status. |
| /get/dcdc/<oesid> | Get all of the DC/DC Converter parameters for the power storage system specified by <oesid>. |
| /set/dcdc/<oesid> | Set the values specified by the query parameters as the DC/DC Converter parameters for the power storage system specified by <oesid>. |
| /set/dcdc/voltage/<oesid> | Set the value specified by the query parameter as the DC/DC Converter voltage parameter for the power storage system specified by <oesid>. |
| /set/dcdc/current/<oesunit> | Set the value specified by the query parameter as the DC/DC Converter current parameter for the power storage system specified by <oesid>. |
The power storage system information available to the user from the Web API “/get/log” endpoint is explained below. That information is collected as one set for all of the power storage system.
(The default parameters used when the power storage system is constructed are specified in the jsontmp/standard.json file.)
| emu | charge_discharge_power | Battery charge/discharge power [W] (absolute) |
| rsoc | The battery relative state of charge (%) that is used for display and control. | |
| battery_rsoc | The relative state of charge (%) of a real battery | |
| battery_voltage | Battery voltage [V] | |
| battery_current | Battery current [A] | |
| pvc_charge_voltage | PVC output voltage [V] | |
| pvc_charge_current | PVC output current [A] | |
| pvc_charge_power | PVC output power [W] | |
| ups_input_voltage | UPS input voltage [V] | |
| ups_output_voltage | UPS output voltage [V] | |
| ups_output_current | UPS output current [A] | |
| ups_output_power | UPS output power [W] | |
| ups_output_frequency | UPS output frequency [Hz] | |
| ups_operation_mode.parameter | Proportion of grid power use | |
| ups_operation_mode.mode | UPS operation mode | |
| ups_operation_mode.stop_mode | UPS operation mode after the battery has been depleted
|
|
| ups_operation_schedule | UPS operation schedule | |
| system_time.year | The year in the EMU system clock | |
| system_time.month | The month in the EMU system clock | |
| system_time.day | The day in the EMU system clock | |
| system_time.hour | The hour in the EMU system clock | |
| system_time.minute | The minute in the EMU system clock | |
| dischargeable_time.hour | Hours for which battery discharge is possible | |
| dischargeable_time.minute | Minutes for which battery discharge is possible | |
| dcdc | status.status | DC/DC Converter status |
| status.statusName | DC/DC Converter status information | |
| status.alarm | DC/DC Converter alarm number | |
| status.stateAlarm | DC/DC Converter alarm information | |
| status.runningState | DC/DC Converter operation status | |
| status.operationMode | Operation mode status | |
| powermeter.p1 | Power consumption of the power storage system and residence [W] (For more information, see Figure 4-2.) |
|
| powermeter.p2 | Power consumption to the power storage system [W] (For more information, see Figure 4-2.) |
|
| powermeter.v1 | The voltage at powermeter.p1 [V] | |
| powermeter.i1 | The current at powermeter.p1 [A] | |
| powermeter.kwh1 | The power at powermeter.p1 [kWh] | |
| powermeter.kwh2 | The power at powermeter.p2 [kWh] | |
| meter.vg | DC Grid voltage (V) | |
| meter.ig | DC Grid current (A) | |
| meter.wg | DC Grid power (W) | |
| meter.vb | Battery voltage (V) | |
| meter.ib | Battery current (A) | |
| meter.wb | Battery power (W) | |
| meter.tmp | Internal temperature (℃) | |
| vdis.dvg | DC Grid target voltage (V) | |
| vdis.drg | DC Grid Droop rate (%) | |
| param.dig | DC Grid maximum current (A) | |
| param.ogv | DC Grid overvoltage threshold (V) | |
| param.ugv | DC Grid low voltage threshold (V) | |
| param.cib | Battery maximum current (A) | |
| param.obv | Battery overvoltage threshold (V) | |
| param.ubv | Battery low voltage threshold (V) | |
| oesunit | on | Parameters used by the previous control system Not used by the APIS Emulator |
| ip | IPv4 Address of APIS installed devices | |
| display | Information displayed on the power storage system screen | |
| ipv6_ll | IPv6 link local address for APIS installed devices | |
| ipv6_g | IPv6 global address for APIS installed devices | |
| mac | MAC address for APIS installed devices | |
| sn | Serial number for APIS installed devices | |
| id | The power storage system ID | |
| budo | Parameters used by the previous control system Not used by the APIS Emulator |
|
| time | apis-main node time | The time for the power storage system on the Emulator |
This file contains the parameters that have been set for running the emulation.
| debug | A flag for selecting whether or not debugging messages are output True: Debugging messages are output. False: Debugging messages are not output. |
| dataSet | A data set such as residential power consumption or amount of solar radiation |
| sleeptime | The wait time between Update Power Flow loops |
| doUpdates | Flag for selecting whether or not the emulation is run True: The emulation is run. False: The mock hardware environment is constructed, but power flow emulation, etc. is not run. |
| saveIndividualToDB | Flag for selecting whether or not the power storage system parameters are to be stored in a database (DB) True: Store in DB False: Do not store in DB |
| saveToSummaryToCSV | Flag for selecting whether or not the data for power consumption and power flow, etc. is to be summarized and saved to a CSV file True: Save as CSV False: Do not save as CSV |
| saveIndividualToCSV | A flag for selecting whether or not the power system parameters are to be saved to a CSV file True: Save as CSV False: Do not save as CSV |
| constantSystemLoss | Power system constant loss |
| DCCstLoss | DC/DC Converter constant loss |
| DCChargeLoss | DC/DC Converter charging loss |
| DCDischargeLoss | DC/DC Converter discharging loss |
| battModeLoss_a | Loss relative to load for UPS battery mode (loss = battModeLoss_a x load) |
| battModeLoss_c | Constant loss in UPS battery mode |
| transLoss_a | Transformer loss relative to load for UPS battery mode (loss = transLoss_a x load) |
| transLoss_c | Transformer constant loss for UPS battery mode |
| bypassModeLoss_a | Loss relative to load for UPS bypass mode (loss = transLoss_a x load) |
| bypassModeLoss_c | Constant loss for UPS bypass mode |
| ACChargeLoss | Loss for charging with grid power (Powermeter.p2) |
| UPS_TRIGGER_BATT_OFF | A UPS setting for the threshold battery RSOC value below which supply from the battery is set to OFF |
| UPS_TRIGGER_BATT_ON | A UPS setting for the threshold battery RSOC value above which supply from the battery is set to ON |
| UPS_TRIGGER_AC_OFF | A UPS setting for the threshold battery RSOC value above which supply from the grid to the battery is set to OFF |
| UPS_TRIGGER_AC_ON | A UPS setting for the threshold battery RSOC value below which supply from the grid to the battery is set to ON |
| batteryVoltage | Battery voltage |
| ACChargeAmount | Limit for charging from grid power |
| default_Area | PV panel area |
| r | PV panel conversion efficiency |
| pr | PV panel performance factors Factors other than panel area and conversion efficiency that affect power generation, such as panel inclination angle, are represented collectively as a single variable. |
| batterySize | The power storage battery capacity |
| pvc_sol_reg | The PV size for each power storage system |
| dburl | The database URL |
| summaryPath | This specifies the location for saving the saveToSummaryToCSV data. |
| indivLogPath | This specifies the location for saving the saveIndividualToCSV data. |
| b_host | Bottle Web Server IP Address |
| b_port | Bottle Web Server port number |
| modes | DC/DC Converter status "0x0000": 'Waiting', "0x0002": 'Heteronomy CV Discharging', "0x0014": 'Grid Autonomy Mode', "0x0041": 'Heteronomy CV Charging - grid current limited' |
| modesOps | The DC/DC Converter operating mode status "0x0000": 'Waiting', "0x0002": 'Heteronomy CV', "0x0014": 'Grid Autonomy', "0x0041": 'Heteronomy CV' |
| modesRunning | The DC/DC Converter running status "0x0000": 'off', "0x0002": 'discharge', "0x0014": 'discharge', "0x0041": 'charge' |
The formula for calculating amount of generated power from the amount of solar radiation read from the CSV is shown below.
Generated power = Amount of solar power (CSV) x PV panel area (default_Area) x PV panel conversion efficiency (ｒ) x PV panel performance factor (pr)
Emulator uses the logging.config.fileConfig() method to initialize Logger. When invoked, that method reads the logging.conf file and uses pre-set values from the file to initialize Logger.
| loggers | keys: Logger instance name description |
| handlers | keys: Handler instance name description |
| formatters | keys: Formatter instance name description |
| loger_root | level: Specifies the message output level handlers: Specifies the applicable handler instance name |
handler_consoleHandler handler_infoFileHandler |
class: Specification of the implemented Handler class -StreamHandler: Outputs the specified stream -FileHandler: Outputs the specified file level: Outputs messages of the specified level or higher level formatter: The name of the Formatter used for message output args: The arguments used to instantiate Handler Set the Log output destination and folder for storing the Log file |
formatter_consoleFormatter formatter_infoFileFormatter |
format: Specifies various formats datefmt: Specifies the date format |
Log output uses the Python “logging” standard library module, which has the five output levels described below. The “critical” level is not used for Emulator. The destination for log output, the location of the folder in which log files are saved, and the log level for output or saving are specified as settings in the logging.conf file.
[Level]
-
CRITICAL
→ Indicates that a fatal problem has occurred, but this level is not output for Emulator. -
ERROR
→ Indicates that a problem has occurred during execution.
<Example> When input information cannot be read from a CSV file, etc. -
WARNING
→ Used for alert notifications
<Example> When parameters specified by the Web API are missing, etc. -
INFO
→ Used to output information on a normally-operating system.
<Example> Notification of behavioral information, such as “ramping up finish”. -
DEBUG
→ Information used for debugging.
<Example> Information used for debugging the Emulator, etc.
Emulator logs are output to a file. The log output destinations can be enabled or disabled and the log output level can be restricted by changing the settings in the logging.conf file as explained in the previous section.
The data for solar radiation and residential power consumption that is used in emulation is read from the respective CSV files located under data/input/Sample. Emulations can be run for various solar radiation and power consumption conditions by replacing the data in the CSV files.
The data format is shown below.
-
Amount of solar radiation
For each row, enter values for the hourly amount of solar radiation for 24 hours, beginning at 0:00 (a set of 24 data points). Enter data rows for 365 days. [unit: W/m2]
(For more information, refer to “data/input/Sample/sample_solar_data.csv”.) -
Residential power consumption
For each row, enter values for residence power consumption for every 30 minutes for 24 hours, beginning at 0:00 (a set of 48 data points). Enter data rows for 365 days to create a data set for one household. Create data sets for 100 households, continuing in the column direction. [unit: kW]
(For more information, refer to “data/input/Sample/sample_load_data.csv”.)
A log is output to a file when an abnormality occurs, but there is no function for the system to reset or stop itself.
Communication between User and Emulator is not secured, so Web server configuration for IP address access restriction may be necessary.
Communication between apis-main and Emulator is not secured, so Web server configuration for IP address access restriction may be necessary.
All of the information that can be obtained from the Emulator is generated mock data, so there is no association with personal data.
The software used by Emulator and the corresponding OSS license information are described below.
■Emulator software and licensing information
| Software | Version | License | Code Change |
|---|---|---|---|
| python | 3.6.9 | PSL License | None |
| requests | 2.24.0 | Apache License2.0 | None |
| numpy | 1.19.4 | BSD License | None |
| bottle | 0.12.8 | MIT License | None |
| netifaces | 0.10.9 | MIT License | None |
| wheel | 0.30.0 | MIT License | None |
| jQuery | 1.7.2 | MIT License or GPL v2 License (selectable) |
None |
*Software versions may change.
