From bbbbe67cc8c344e95677e1a165ca1c888ef1cd95 Mon Sep 17 00:00:00 2001 From: Will Sams Date: Fri, 7 Feb 2025 09:50:50 -0500 Subject: [PATCH 01/18] Add CONTRIBUTING.md file Signed-off-by: Palak Goyal Co-authored-by: Yatin Jamwal --- CONTRIBUTING.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ac13e66 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,107 @@ +# Contributing to APIS + +Thank you for your interest in contributing to APIS! We welcome contributions from the community to help improve and grow this project. + +## How to Contribute + +### Reporting Issues + +If you encounter any bugs, have feature requests, or want to suggest improvements, please open an issue in the relevant sub-repository under the [Hyphae organization](https://github.com/hyphae). When filing an issue, please provide: + +- A clear title and description +- Steps to reproduce (if applicable) +- Expected and actual behavior +- Any relevant logs or screenshots + +### Contributing Code + +The main repository (APIS) does not contain code directly but serves as the build orchestrator for the following sub-repositories: + +- [apis-bom](https://github.com/hyphae/apis-bom) +- [apis-ccc](https://github.com/hyphae/apis-ccc) +- [apis-common](https://github.com/hyphae/apis-common) +- [apis-emulator](https://github.com/hyphae/apis-emulator) +- [apis-log](https://github.com/hyphae/apis-log) +- [apis-main](https://github.com/hyphae/apis-main) +- [apis-main_controller](https://github.com/hyphae/apis-main_controller) +- [apis-service_center](https://github.com/hyphae/apis-service_center) +- [apis-tester](https://github.com/hyphae/apis-tester) +- [apis-web](https://github.com/hyphae/apis-web) + +Each of these sub-repositories may have different contribution requirements based on the technology stack (Java, Groovy or Python). Please refer to their respective README.md files. + +#### 1. Fork the Relevant Repository + +Start by forking and cloning the repository you wish to contribute to. + +```bash +# Fork the repository and clone it locally. Example for apis-common +git clone https://github.com/hyphae/apis-common.git +cd apis-common +``` + +#### 2. Create a Branch + +Create a new branch for your work: + +```bash +git checkout -b feature-branch +``` + +#### 3. Implement Changes + +Make your changes following the coding standards of the project. Ensure your code is well-documented and includes tests where applicable. + +#### 4. Run Tests + +Before submitting your changes, make sure to test them: + +```bash +mvn test # Java projects +``` + +#### 5. Commit Changes + +Follow the projectโ€™s commit message conventions. A good commit message format is: + +```text +[Type] Short description + +Detailed explanation of the changes (if necessary) +``` + +Examples: + +```text +[Fix] Corrected validation logic for job assignments +[Feature] Added new user role permissions +``` + +#### 6. Submit a Pull Request (PR) + +Push your changes to your fork and create a pull request against the `main` branch of the repository. Provide a detailed explanation of the changes in the PR description. + +### Code Review Process + +All contributions go through a code review process: + +1. A maintainer will review your PR and may request changes. +2. Once approved, your changes will be merged into the main branch. +3. If necessary, your changes will be included in the next release. + +### Contribution Guidelines + +- Follow the projectโ€™s coding style and conventions. +- Ensure changes do not introduce security vulnerabilities. +- Write clear and descriptive commit messages. +- Be respectful and constructive in discussions and code reviews. + +### Community Contributions + +In addition to code, you can contribute by: + +- Writing and improving documentation. +- Helping answer questions in discussions and issues. +- Reporting bugs and suggesting features. + +Thank you for contributing to APIS! ๐Ÿš€ From 9d4b9b30e131866c40084176b009c02d7a1cb314 Mon Sep 17 00:00:00 2001 From: Will Sams Date: Fri, 7 Feb 2025 09:51:19 -0500 Subject: [PATCH 02/18] Lint README.md Signed-off-by: Palak Goyal Co-authored-by: Yatin Jamwal --- README.md | 193 +++++++++++++++++++++++++++--------------------------- 1 file changed, 98 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index e0b9e74..ddb5ae0 100644 --- a/README.md +++ b/README.md @@ -1,146 +1,149 @@ # Autonomous Power Interchange System (APIS) -# APIS features -By accommodating P2P energy sharing between distributed batteries, it is possible to build a microgrid that utilizes variable renewable energy(VRE) as the main power source and enhances the resilience of the power system. These distributed batteries absorb fluctuations of VRE generation and improve community self-sufficiency by balancing supply and demand within the community. -
+## APIS features + +By accommodating P2P energy sharing between distributed batteries, it is possible to build a microgrid that utilizes variable renewable energy(VRE) as the main power source and enhances the resilience of the power system. These distributed batteries absorb fluctuations of VRE generation and improve community self-sufficiency by balancing supply and demand within the community. + Click [here](https://www.sonycsl.co.jp/tokyo/11481/) for details -
-# Technoogy -## Physical Peer to Peer(PP2P) energy sharing -This technology achieves a fixed amount of energy sharing between batteries by constant current control. It offset a shortage of one battery with delivering the necessary amount from a surplus of other battery. It is possible to send a fixed amount of power between specific users (batteries), which was difficult to realize by the voltage control, and it is possible to transact PP2P energy trading between users on the condition of the required energy amount and energy price. +## Technoogy + +### Physical Peer to Peer(PP2P) energy sharing + +This technology achieves a fixed amount of energy sharing between batteries by constant current control. It offset a shortage of one battery with delivering the necessary amount from a surplus of other battery. It is possible to send a fixed amount of power between specific users (batteries), which was difficult to realize by the voltage control, and it is possible to transact PP2P energy trading between users on the condition of the required energy amount and energy price. ![ใ‚ญใƒฃใƒ—ใƒใƒฃ](https://user-images.githubusercontent.com/71874910/95694571-c0c47080-0c6d-11eb-9935-89d62e43228c.PNG) -## Autonomous distributed control -Software with the same functions is installed in each battery system, and the software implements energy sharing according to the transaction conditions (time window, energy amount, energy price, etc.) of each battery system. It is a flexible energy trading system that allows various transaction conditions to be set for each battery system and that the conditions can be dynamically changed for each time window. +### Autonomous distributed control + +Software with the same functions is installed in each battery system, and the software implements energy sharing according to the transaction conditions (time window, energy amount, energy price, etc.) of each battery system. It is a flexible energy trading system that allows various transaction conditions to be set for each battery system and that the conditions can be dynamically changed for each time window. ![ใ‚ญใƒฃใƒ—ใƒใƒฃ](https://user-images.githubusercontent.com/71874910/95833927-3ff19b80-0d77-11eb-9bc7-1994e641d5fd.PNG) -
-
+## Software -## Software The software that realizes the above technology and makes it possible to easily construct a DC microgrid is released. -### โ–ผ Software required to simulate energy exchange using a hardware emulator - - [apis-main](https://github.com/hyphae/apis-main) - Software installed on each node to provide bi-directional energy exchange with autonomous decentralized control +### โ–ผ Software required to simulate energy exchange using a hardware emulator + +- [apis-main](https://github.com/hyphae/apis-main) + Software installed on each node to provide bi-directional energy exchange with autonomous decentralized control See apis-main's [Documentation](https://github.com/hyphae/apis-main/blob/master/doc/en/apis-main_specification_en.md) for more information. - - [apis-main_controller](https://github.com/hyphae/apis-main_controller) +- [apis-main_controller](https://github.com/hyphae/apis-main_controller) Software that visualizes the status of apis-main installed on each node and the status of energy exchange between nodes - See apis-main_controller's [Documentation](https://github.com/hyphae/apis-main_controller/blob/master/doc/en/apis-main-controller_specification_en.md) for more information. - - [apis-web](https://github.com/hyphae/apis-web) + See apis-main_controller's [Documentation](https://github.com/hyphae/apis-main_controller/blob/master/doc/en/apis-main-controller_specification_en.md) for more information. +- [apis-web](https://github.com/hyphae/apis-web) Software that acquires necessary information for visualization from apis-main and provides it to apis-main_controller - See apis-web's [Documentation](https://github.com/hyphae/apis-web/blob/master/doc/en/apis-web_specification_en.md) for more information. - - [apis-emulator](https://github.com/hyphae/apis-emulator) - Software to emulate hardware such as DC/DC converters and batteries + See apis-web's [Documentation](https://github.com/hyphae/apis-web/blob/master/doc/en/apis-web_specification_en.md) for more information. +- [apis-emulator](https://github.com/hyphae/apis-emulator) + Software to emulate hardware such as DC/DC converters and batteries See apis-emulator's [Documentation](https://github.com/hyphae/apis-emulator/blob/master/doc/en/apis-emulator_specification_en.md) for more information. - - [apis-service_center](https://github.com/hyphae/apis-service_center) (Added on December 24, 2020) +- [apis-service_center](https://github.com/hyphae/apis-service_center) (Added on December 24, 2020) Software to provide information required by the administrators and users of clusters constructed of apis-main services installed in each unit. See apis-service_center's [Documentation](https://github.com/hyphae/apis-service_center/blob/main/doc/en/apis-service_center_specification_EN.md) for more information. - - [apis-ccc](https://github.com/hyphae/apis-ccc) (Added on December 24, 2020) +- [apis-ccc](https://github.com/hyphae/apis-ccc) (Added on December 24, 2020) Software to uploade information that is related to energy sharing to apis-service_center. - See apis-ccc's [Documentation](https://github.com/hyphae/apis-ccc/blob/main/doc/en/apis-ccc_specification_EN.md) for more information. - - [apis-log](https://github.com/hyphae/apis-log) (Added on December 24, 2020) + See apis-ccc's [Documentation](https://github.com/hyphae/apis-ccc/blob/main/doc/en/apis-ccc_specification_EN.md) for more information. +- [apis-log](https://github.com/hyphae/apis-log) (Added on December 24, 2020) Software to receive information from apis-main by multicast via a communication line and storing that information in a database. - See apis-log's [Documentation](https://github.com/hyphae/apis-log/blob/main/doc/en/apis-log_specification_EN.md) for more information. - - [apis-tester](https://github.com/hyphae/apis-tester) (Added on December 24, 2020) + See apis-log's [Documentation](https://github.com/hyphae/apis-log/blob/main/doc/en/apis-log_specification_EN.md) for more information. +- [apis-tester](https://github.com/hyphae/apis-tester) (Added on December 24, 2020) Software to test and evaluation of apis-main. - See apis-tester's [Documentation](https://github.com/hyphae/apis-tester/blob/main/doc/en/apis-tester_specification_EN.md) for more information. + See apis-tester's [Documentation](https://github.com/hyphae/apis-tester/blob/main/doc/en/apis-tester_specification_EN.md) for more information. - ## Installation - - [Operating Environment] - The above software has been tested on the following operating systems. - - Ubuntu 18.04, 20.04 - - CentOS 7, 8 - - macOS Catalina, Big Sur - - ใ€€* Virtual environments are not supported. - - [Preparation] - It is assumed that the necessary software are installed. - The following is an example of an advance preparation for Ubuntu 18.04. - * Install the JDK if it's not already installed. - * Python3.6.9 or later is required. - * Sqlite3.8.3 or later is required. (CentOS 7) +## Installation + +[Operating Environment] +The above software has been tested on the following operating systems. + +- Ubuntu 18.04, 20.04 +- CentOS 7, 8 +- macOS Catalina, Big Sur + +Note: Virtual environments are not supported. + +[Preparation] +It is assumed that the necessary software are installed. +The following is an example of an advance preparation for Ubuntu 18.04. + +- Install the JDK if it's not already installed. +- Python3.6.9 or later is required. +- Sqlite3.8.3 or later is required. (CentOS 7) ```bash -$ sudo apt install git -$ sudo apt install make -$ sudo apt install maven -$ sudo apt install groovy -$ sudo apt install python3-venv -$ sudo apt install python3-pip -$ sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 9DA31620334BD75D9DCB49F368818C72E52529D4 -$ echo "deb [ arch=amd64 ] https://repo.mongodb.org/apt/ubuntu bionic/mongodb-org/4.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.0.list -$ sudo apt install mongodb-org +sudo apt install git +sudo apt install make +sudo apt install maven +sudo apt install groovy +sudo apt install python3-venv +sudo apt install python3-pip +sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 9DA31620334BD75D9DCB49F368818C72E52529D4 +echo "deb [ arch=amd64 ] https://repo.mongodb.org/apt/ubuntu bionic/mongodb-org/4.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.0.list +sudo apt install mongodb-org ``` [APIS related software bach installation] - Install all of the above APIS related software at one time. - See each software repository for the individual installation and execution of each software. - - ```bash -$ git clone https://github.com/hyphae/APIS.git -$ cd APIS -$ make build + Install all of the above APIS related software at one time. + See each software repository for the individual installation and execution of each software. + +```bash +git clone https://github.com/hyphae/APIS.git +cd APIS +make build ``` -* If an error occurs with the "make build" or "make run" command, open the terminal again and run it. - -## Running -Run all of the above APIS related software at once. +Note: If an error occurs with the "make build" or "make run" command, open the terminal again and run it. + +## Running + +Run all of the above APIS related software at once. - ```bash -$ make run +```bash +make run ``` -  After running each software, access the followings in your browser to display. - +  After running each software, access the followings in your browser to display. +     0.0.0.0:4382/   -> apis-main_controller -     0.0.0.0:4390/   -> apis-emulator +     0.0.0.0:4390/   -> apis-emulator     0.0.0.0:10000/   -> apis-tester -     http://127.0.0.1:8000/static/ui_example/staff/visual.html   -> apis-service_center (account/pwd = admin/admin) - -
- +     [http://127.0.0.1:8000/static/ui_example/staff/visual.html](http://127.0.0.1:8000/static/ui_example/staff/visual.html)   -> apis-service_center (account/pwd = admin/admin) +  The following picture is apis-main_controller.  Flash an cache once. - - ![ใ‚ญใƒฃใƒ—ใƒใƒฃ](https://user-images.githubusercontent.com/71874910/97250475-602a5b80-1849-11eb-95bd-b8c1cac57c61.PNG) - -  Simulate energy exchange with setting Global Mode to "Run". - - ![ใ‚ญใƒฃใƒ—ใƒใƒฃ](https://user-images.githubusercontent.com/71874910/96272423-0932b400-1009-11eb-9a90-f9e5bd49baef.PNG) - -
- - - ## Stopping -Stop all of the above APIS related software at once. - - ```bash -$ make stop + +![ใ‚ญใƒฃใƒ—ใƒใƒฃ](https://user-images.githubusercontent.com/71874910/97250475-602a5b80-1849-11eb-95bd-b8c1cac57c61.PNG) + + Simulate energy exchange with setting Global Mode to "Run". + +![ใ‚ญใƒฃใƒ—ใƒใƒฃ](https://user-images.githubusercontent.com/71874910/96272423-0932b400-1009-11eb-9a90-f9e5bd49baef.PNG) + +## Stopping + +Stop all of the above APIS related software at once. + +```bash +make stop ``` ### โ–ผ Software and hardware information required for energy exchange using actual DC/DC converters and batteries + Use apis-dcdc_batt_comm instead of apis-emulator. - - - [apis-dcdc_batt_comm](https://github.com/hyphae/apis-dcdc_batt_comm) - Sample device driver to control DC/DC converters and batteries + +- [apis-dcdc_batt_comm](https://github.com/hyphae/apis-dcdc_batt_comm) + Sample device driver to control DC/DC converters and batteries See apis-dcdc_batt_comm's [Documentation](https://github.com/hyphae/apis-dcdc_batt_comm/blob/master/doc/en/apis-dcdc_batt_comm_specification_en.md) for more information. - - [apis-build_version_up_system](https://github.com/hyphae/apis-build_version_up_system) +- [apis-build_version_up_system](https://github.com/hyphae/apis-build_version_up_system) This tool clones all of the software needed to build the APIS evaluation environment from GitHub/hyphae in a single batch, builds the software, generates the various configuration files required for APIS operation according to the configuration file, and then installs all of the software on multiple nodes. See apis-build_version_up_systems's [Documentation](https://github.com/hyphae/apis-build_version_up_system/blob/main/doc/en/apis-build_version_up_system_specification_EN.md) for more information. - - [apis-hw-info](https://github.com/SonyCSL/apis-hw-info) +- [apis-hw-info](https://github.com/SonyCSL/apis-hw-info) Hardware reference information See apis-hw-info's [Documentation](https://github.com/hyphae/apis-hw-info/blob/main/MAIN-DOCUMENT_EN.md) for more information. - ## License - [Apache License Version 2.0](https://github.com/hyphae/APIS/blob/master/LICENSE) +## License + [Apache License Version 2.0](https://github.com/hyphae/APIS/blob/master/LICENSE) ## Notice +  [Notice](https://github.com/hyphae/APIS/blob/master/NOTICE.md) From c6fa84fc96e491ee1f747a88b91843a254b745c9 Mon Sep 17 00:00:00 2001 From: Will Sams Date: Fri, 7 Feb 2025 10:00:25 -0500 Subject: [PATCH 03/18] Add initial COMMITTERS.csv file Signed-off-by: Palak Goyal Co-authored-by: Yatin Jamwal --- COMMITERS.csv | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 COMMITERS.csv diff --git a/COMMITERS.csv b/COMMITERS.csv new file mode 100644 index 0000000..217e7bb --- /dev/null +++ b/COMMITERS.csv @@ -0,0 +1,3 @@ +Name, Email, Github ID +xxx xxxx, xxx@axmsoftware.com, axmsoftware +Will Sams, will@samswebs.com, willsams \ No newline at end of file From fdbe9992fcba6c46704e7ace60718d33941b3442 Mon Sep 17 00:00:00 2001 From: Bill Bensing Date: Sun, 5 Jun 2022 08:13:34 -0400 Subject: [PATCH 04/18] updated git base url, changed from soy to hyphae Signed-off-by: Palak Goyal Co-authored-by: Yatin Jamwal --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index f2e043a..8e1319d 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ -GIT_BASE_URL=https://github.com/SonyCSL +GIT_BASE_URL=https://github.com/hyphae apis-bom: From b9a553f14fc4ea553b6e739d0b62228c5af45e45 Mon Sep 17 00:00:00 2001 From: Will Sams Date: Fri, 7 Feb 2025 10:11:14 -0500 Subject: [PATCH 05/18] Add CODE_OF_CONDUCT.md Signed-off-by: Palak Goyal Co-authored-by: Yatin Jamwal --- CODE_OF_CONDUCT.md | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 CODE_OF_CONDUCT.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..78bdafe --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,4 @@ +All participants agree to abide by the +[Code of Conduct](https://lfprojects.org/policies/code-of-conduct/). +Please contact [conduct@lfenergy.org](conduct@lfenergy.org) to report any +violations or concerns. From 56c1f7cc859bf0068df709852f08013fa720f30b Mon Sep 17 00:00:00 2001 From: Will Sams Date: Fri, 7 Feb 2025 10:13:18 -0500 Subject: [PATCH 06/18] Update CODE_OF_CONDUCT.md Signed-off-by: Palak Goyal Co-authored-by: Yatin Jamwal --- CODE_OF_CONDUCT.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 78bdafe..3c3350c 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,4 +1,2 @@ -All participants agree to abide by the -[Code of Conduct](https://lfprojects.org/policies/code-of-conduct/). -Please contact [conduct@lfenergy.org](conduct@lfenergy.org) to report any +All participants agree to abide by the [Code of Conduct](https://lfprojects.org/policies/code-of-conduct/). Please contact [conduct@lfenergy.org](conduct@lfenergy.org) to report any violations or concerns. From f4393fcf243620b04e99edebe3e7da661f2dff5a Mon Sep 17 00:00:00 2001 From: Will Sams Date: Fri, 7 Feb 2025 14:46:10 -0500 Subject: [PATCH 07/18] Add initial GOVERNANCE.md Signed-off-by: Palak Goyal Co-authored-by: Yatin Jamwal --- GOVERNANCE.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 GOVERNANCE.md diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..223cc41 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,65 @@ +# APIS Project Governance Policy + +## Overview + +This project aims to be governed in a transparent, accessible way for the benefit of the community. All participation in this project is open and not bound to corporate affiliation. Participants are bound to the project's [Code of Conduct](CODE_OF_CONDUCT.md). + +## Project Roles + +### Contributor + +The contributor role is the starting role for anyone participating in the +project and wishing to contribute code. + +#### Process for Becoming a Contributor + +* Review the [Contribution Guidelines](CONTRIBUTING.md) to ensure your contribution is inline with the project's coding and styling guidelines. +* Submit your code as a PR with the appropriate DCO sign-off. +* Have your submission approved by the committer(s) and merged into the codebase. + +### Committer + +The committer role enables the contributor to commit code directly to the repository, but also comes with the responsibility of being a responsible leader in the community. + +#### Process for Becoming a Committer + +* Show your experience with the codebase through contributions and engagement on the community channels. +* Request to become a committer. To do this, create a new pull request that adds your name and details to the [Committers File](COMMITTERS.csv) and request existing committers to approve. +* After the majority of committers approve you, merge in the PR. Be sure to tag the person managing the GitHub permissions to update the committers team in GitHub. + +#### Committer Responsibilities + +* Monitor project communication channels. +* Triage GitHub issues and perform pull request reviews for other committers and the community. +* Ensure that ongoing PRs are moving forward at the right pace or closing them. +* Dedicate at least 25% of their time (~1.25 business days per week) to the project. + +#### When Does a Committer Lose Committer Status? + +If a committer is no longer interested or cannot perform the committer duties listed above, they should volunteer to be moved to emeritus status. In extreme cases, this can also occur by a vote of the committers per the voting process below. + +### Technical Steering Committee (TSC) + +The Technical Steering Committee (TSC) is responsible for the overall project health and direction, coordination of activities, and working with other projects and committees as needed for the continued growth of the project. + +See [TSC Readme](tsc/README.md) for details. + +## Release Process + +Project releases will occur on a scheduled basis as agreed to by the committers. See [RELEASE.md](RELEASE.md) for details. + +## Conflict Resolution and Voting + +In general, we prefer that technical issues and committer membership are amicably worked out between the persons involved. If a dispute cannot be decided independently, the committers can be called in to decide an issue. If the committers themselves cannot decide an issue, the issue will be resolved by voting. The voting process is a simple majority in which each committer receives one vote. + +## Communication + +This project, just like all of open source, is a global community. In addition to the [Code of Conduct](CODE_OF_CONDUCT.md), this project will: + +* Keep all communication on open channels (mailing list, forums, chat). +* Be respectful of time and language differences between community members (such as scheduling meetings, email/issue responsiveness, etc.). +* Ensure tools are able to be used by community members regardless of their region. + +If you have concerns about communication challenges for this project, please contact the committers. + +Thank you for being part of the APIS community and helping maintain a well-governed, transparent project! From a7ae4896732e697f3af2083eab1415549da37f45 Mon Sep 17 00:00:00 2001 From: AXM Software <35903292+axmsoftware@users.noreply.github.com> Date: Sun, 9 Mar 2025 23:21:49 +0200 Subject: [PATCH 08/18] Create scorecard.yml Signed-off-by: Palak Goyal Co-authored-by: Yatin Jamwal --- .github/workflows/scorecard.yml | 73 +++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 .github/workflows/scorecard.yml diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml new file mode 100644 index 0000000..cabe64c --- /dev/null +++ b/.github/workflows/scorecard.yml @@ -0,0 +1,73 @@ +# This workflow uses actions that are not certified by GitHub. They are provided +# by a third-party and are governed by separate terms of service, privacy +# policy, and support documentation. + +name: Scorecard supply-chain security +on: + # For Branch-Protection check. Only the default branch is supported. See + # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection + branch_protection_rule: + # To guarantee Maintained check is occasionally updated. See + # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained + schedule: + - cron: '36 16 * * 3' + push: + branches: [ "add-license-1" ] + +# Declare default permissions as read only. +permissions: read-all + +jobs: + analysis: + name: Scorecard analysis + runs-on: ubuntu-latest + permissions: + # Needed to upload the results to code-scanning dashboard. + security-events: write + # Needed to publish results and get a badge (see publish_results below). + id-token: write + # Uncomment the permissions below if installing in a private repository. + # contents: read + # actions: read + + steps: + - name: "Checkout code" + uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 + with: + persist-credentials: false + + - name: "Run analysis" + uses: ossf/scorecard-action@0864cf19026789058feabb7e87baa5f140aac736 # v2.3.1 + with: + results_file: results.sarif + results_format: sarif + # (Optional) "write" PAT token. Uncomment the `repo_token` line below if: + # - you want to enable the Branch-Protection check on a *public* repository, or + # - you are installing Scorecard on a *private* repository + # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action?tab=readme-ov-file#authentication-with-fine-grained-pat-optional. + # repo_token: ${{ secrets.SCORECARD_TOKEN }} + + # Public repositories: + # - Publish results to OpenSSF REST API for easy access by consumers + # - Allows the repository to include the Scorecard badge. + # - See https://github.com/ossf/scorecard-action#publishing-results. + # For private repositories: + # - `publish_results` will always be set to `false`, regardless + # of the value entered here. + publish_results: true + + # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF + # format to the repository Actions tab. + - name: "Upload artifact" + uses: actions/upload-artifact@97a0fba1372883ab732affbe8f94b823f91727db # v3.pre.node20 + with: + name: SARIF file + path: results.sarif + retention-days: 5 + + # Upload the results to GitHub's code scanning dashboard (optional). + # Commenting out will disable upload of results to your repo's Code Scanning dashboard + - name: "Upload to code-scanning" + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: results.sarif From 8102affe32a92496b61e2fb8f4b7d59f4a44ac79 Mon Sep 17 00:00:00 2001 From: Souradip Pal Date: Wed, 19 Mar 2025 01:38:03 +0530 Subject: [PATCH 09/18] Update README.md Technology spelling Signed-off-by: Palak Goyal Co-authored-by: Yatin Jamwal --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ddb5ae0..6fd9350 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ By accommodating P2P energy sharing between distributed batteries, it is possibl Click [here](https://www.sonycsl.co.jp/tokyo/11481/) for details -## Technoogy +## Technology ### Physical Peer to Peer(PP2P) energy sharing From 37181e0598a2ab3ef2c5a9b55e5fe1c46cfa0c58 Mon Sep 17 00:00:00 2001 From: Venkata Sai <116882464+Venkata-Sai-Vishwanath-robo@users.noreply.github.com> Date: Sun, 23 Mar 2025 20:16:41 +0530 Subject: [PATCH 10/18] Update Makefile Signed-off-by: Palak Goyal Co-authored-by: Yatin Jamwal --- Makefile | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/Makefile b/Makefile index 8e1319d..bd45327 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,36 @@ GIT_BASE_URL=https://github.com/hyphae +.PHONY: help +help: + @printf "\nClone Repositories:\n" + @printf " make apis-bom - Clone APIS BOM repository\n" + @printf " make apis-common - Clone APIS Common repository\n" + @printf " make apis-main - Clone APIS Main repository\n" + @printf " make apis-ccc - Clone APIS CCC repository\n" + @printf " make apis-log - Clone APIS Log repository\n" + @printf " make apis-web - Clone APIS Web repository\n" + @printf " make apis-emulator - Clone APIS Emulator repository\n" + @printf " make apis-main_controller - Clone APIS Main Controller repository\n" + @printf " make apis-service_center - Clone APIS Service Center repository\n" + @printf " make apis-tester - Clone APIS Tester repository\n\n" + @printf "Build Targets:\n" + @printf " make build-apis-* - Build a specific APIS module\n" + @printf " make build - Build all APIS modules\n\n" + @printf "Update Repositories:\n" + @printf " make update-apis-* - Update a specific APIS repository\n" + @printf " make update - Update all APIS repositories\n\n" + @printf "Clean Targets:\n" + @printf " make clean-apis-* - Clean a specific APIS module\n" + @printf " make clean - Clean all APIS modules\n\n" + @printf "Run Targets:\n" + @printf " make run-apis-* - Run a specific APIS module\n" + @printf " make run-mongodb - Run MongoDB service\n" + @printf " make run - Run all APIS services\n\n" + @printf "Stop Targets:\n" + @printf " make stop-apis-* - Stop a specific APIS module\n" + @printf " make stop-mongodb - Stop MongoDB service\n" + @printf " make stop - Stop all APIS services\n" apis-bom: git clone $(GIT_BASE_URL)/apis-bom.git From 57912f9082122a71c24922f965672507f8b170e4 Mon Sep 17 00:00:00 2001 From: Subhramit Basu Date: Tue, 29 Jul 2025 21:57:41 +0530 Subject: [PATCH 11/18] Update .github/workflows/scorecard.yml Signed-off-by: Palak Goyal Co-authored-by: Yatin Jamwal --- .github/workflows/scorecard.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index cabe64c..82828e2 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -63,7 +63,7 @@ jobs: with: name: SARIF file path: results.sarif - retention-days: 5 + retention-days: 10 # Upload the results to GitHub's code scanning dashboard (optional). # Commenting out will disable upload of results to your repo's Code Scanning dashboard From 19c52f24bb5a6a61ad407e0636f1a765010a757b Mon Sep 17 00:00:00 2001 From: Akarsh Sahlot <122122123+AkarshSahlot@users.noreply.github.com> Date: Wed, 27 Aug 2025 03:30:05 +0530 Subject: [PATCH 12/18] docs: reorganize README.md to follow LF Energy standards Signed-off-by: Akarsh Sahlot - Restructure content to match LF Energy CoMPAS format - Move Quick Start section to top for better accessibility - Organize system components into logical groups - Consolidate support and community resources - Add proper badges section - Maintain all essential technical information Signed-off-by: Palak Goyal Co-authored-by: Yatin Jamwal --- README.md | 456 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 360 insertions(+), 96 deletions(-) diff --git a/README.md b/README.md index 6fd9350..f45e9a0 100644 --- a/README.md +++ b/README.md @@ -1,149 +1,413 @@ -# Autonomous Power Interchange System (APIS) +# ๐Ÿ”‹ APIS - Autonomous Power Interchange System -## APIS features -By accommodating P2P energy sharing between distributed batteries, it is possible to build a microgrid that utilizes variable renewable energy(VRE) as the main power source and enhances the resilience of the power system. These distributed batteries absorb fluctuations of VRE generation and improve community self-sufficiency by balancing supply and demand within the community. +> **Share energy like sharing WiFi** - Connect your batteries and let communities power themselves -Click [here](https://www.sonycsl.co.jp/tokyo/11481/) for details +![image 8](https://github.com/user-attachments/assets/2630dda3-97c9-424f-b20f-034af584be10) -## Technology +--- -### Physical Peer to Peer(PP2P) energy sharing +## ๐ŸŽฏ What is APIS? -This technology achieves a fixed amount of energy sharing between batteries by constant current control. It offset a shortage of one battery with delivering the necessary amount from a surplus of other battery. It is possible to send a fixed amount of power between specific users (batteries), which was difficult to realize by the voltage control, and it is possible to transact PP2P energy trading between users on the condition of the required energy amount and energy price. +**APIS** is an innovative open-source platform that enables **Physical Peer-to-Peer (PP2P) energy sharing** between distributed batteries in microgrids. By leveraging Variable Renewable Energy (VRE) sources, APIS builds resilient microgrids that enhance community self-sufficiency and reduce dependency on traditional centralized power generation. -![ใ‚ญใƒฃใƒ—ใƒใƒฃ](https://user-images.githubusercontent.com/71874910/95694571-c0c47080-0c6d-11eb-9935-89d62e43228c.PNG) +### ๐ŸŒŸ Why This Matters -### Autonomous distributed control +Imagine if your home battery could automatically share power with your neighbors when they need it, and get power back when you need it. That's exactly what APIS does! -Software with the same functions is installed in each battery system, and the software implements energy sharing according to the transaction conditions (time window, energy amount, energy price, etc.) of each battery system. It is a flexible energy trading system that allows various transaction conditions to be set for each battery system and that the conditions can be dynamically changed for each time window. +- **๐Ÿ’ฐ Save Money**: Share excess solar power instead of selling it back to the grid at low prices +- **๐Ÿ”‹ Stay Powered**: Never run out of energy when your neighbors have extra +- **๐ŸŒฑ Go Green**: Maximize renewable energy use in your community +- **๐Ÿ  Be Independent**: Reduce reliance on big power companies +- **๐Ÿ›ก๏ธ Build Resilience**: Keep communities powered during grid outages -![ใ‚ญใƒฃใƒ—ใƒใƒฃ](https://user-images.githubusercontent.com/71874910/95833927-3ff19b80-0d77-11eb-9bc7-1994e641d5fd.PNG) +Click [here](https://www.sonycsl.co.jp/tokyo/11481/) for more details about the research behind APIS. -## Software +--- -The software that realizes the above technology and makes it possible to easily construct a DC microgrid is released. +## ๐Ÿ”ง How It Works -### โ–ผ Software required to simulate energy exchange using a hardware emulator +![image 5](https://github.com/user-attachments/assets/4a2b2b5c-41e6-4bc8-8d7f-a150740c80e5) -- [apis-main](https://github.com/hyphae/apis-main) - Software installed on each node to provide bi-directional energy exchange with autonomous decentralized control - See apis-main's [Documentation](https://github.com/hyphae/apis-main/blob/master/doc/en/apis-main_specification_en.md) for more information. -- [apis-main_controller](https://github.com/hyphae/apis-main_controller) - Software that visualizes the status of apis-main installed on each node and the status of energy exchange between nodes - See apis-main_controller's [Documentation](https://github.com/hyphae/apis-main_controller/blob/master/doc/en/apis-main-controller_specification_en.md) for more information. -- [apis-web](https://github.com/hyphae/apis-web) - Software that acquires necessary information for visualization from apis-main and provides it to apis-main_controller - See apis-web's [Documentation](https://github.com/hyphae/apis-web/blob/master/doc/en/apis-web_specification_en.md) for more information. -- [apis-emulator](https://github.com/hyphae/apis-emulator) - Software to emulate hardware such as DC/DC converters and batteries - See apis-emulator's [Documentation](https://github.com/hyphae/apis-emulator/blob/master/doc/en/apis-emulator_specification_en.md) for more information. -- [apis-service_center](https://github.com/hyphae/apis-service_center) (Added on December 24, 2020) - Software to provide information required by the administrators and users of clusters constructed of apis-main services installed in each unit. - See apis-service_center's [Documentation](https://github.com/hyphae/apis-service_center/blob/main/doc/en/apis-service_center_specification_EN.md) for more information. -- [apis-ccc](https://github.com/hyphae/apis-ccc) (Added on December 24, 2020) - Software to uploade information that is related to energy sharing to apis-service_center. - See apis-ccc's [Documentation](https://github.com/hyphae/apis-ccc/blob/main/doc/en/apis-ccc_specification_EN.md) for more information. -- [apis-log](https://github.com/hyphae/apis-log) (Added on December 24, 2020) - Software to receive information from apis-main by multicast via a communication line and storing that information in a database. - See apis-log's [Documentation](https://github.com/hyphae/apis-log/blob/main/doc/en/apis-log_specification_EN.md) for more information. -- [apis-tester](https://github.com/hyphae/apis-tester) (Added on December 24, 2020) - Software to test and evaluation of apis-main. - See apis-tester's [Documentation](https://github.com/hyphae/apis-tester/blob/main/doc/en/apis-tester_specification_EN.md) for more information. - -## Installation -[Operating Environment] -The above software has been tested on the following operating systems. +### Physical Peer to Peer (PP2P) Energy Sharing -- Ubuntu 18.04, 20.04 -- CentOS 7, 8 -- macOS Catalina, Big Sur +APIS achieves **precise energy sharing between batteries using constant current control**. This technology: -Note: Virtual environments are not supported. +- โœ… **Offsets energy shortages** by delivering the necessary amount from surplus batteries +- โœ… **Enables fixed-amount power transfers** between specific users (batteries) +- โœ… **Supports P2P energy trading** based on energy amount and price conditions +- โœ… **Works where voltage control fails** - providing true peer-to-peer transactions -[Preparation] -It is assumed that the necessary software are installed. -The following is an example of an advance preparation for Ubuntu 18.04. +![PP2P Technology Diagram](https://user-images.githubusercontent.com/71874910/95694571-c0c47080-0c6d-11eb-9935-89d62e43228c.PNG) -- Install the JDK if it's not already installed. -- Python3.6.9 or later is required. -- Sqlite3.8.3 or later is required. (CentOS 7) - +### Autonomous Distributed Control + +**The same software is installed on every battery system**, creating a truly decentralized network where: + +- ๐Ÿค– **Smart Decision Making**: Each system makes autonomous trading decisions +- โš™๏ธ **Flexible Conditions**: Set different trading rules for each battery system +- ๐Ÿ• **Dynamic Updates**: Change conditions for each time window +- ๐Ÿ“Š **Custom Parameters**: Configure energy amount, pricing, and timing preferences + +![Autonomous Control Diagram](https://user-images.githubusercontent.com/71874910/95833927-3ff19b80-0d77-11eb-9bc7-1994e641d5fd.PNG) + +--- + +## ๐Ÿš€ Quick Start (5 Minutes) + +**Want to try it out? Here's how:** + +```bash +# 1. Get the code +git clone https://github.com/hyphae/APIS.git +cd APIS + +# 2. Build everything +make build + +# 3. Start the system +make run +``` + +**That's it!** Now open your web browser and go to: + +| Service | URL | What You'll See | +|---------|-----|-----------------| +| ๐Ÿ“Š **Main Controller** | `http://0.0.0.0:4382/` | Primary dashboard and controls | +| ๐Ÿ”ง **Hardware Emulator** | `http://0.0.0.0:4390/` | Simulate batteries and DC/DC converters | +| ๐Ÿงช **Testing Interface** | `http://0.0.0.0:10000/` | System testing and validation tools | +| ๐Ÿข **Service Center** | `http://127.0.0.1:8000/static/ui_example/staff/visual.html` | Admin interface (login: admin/admin) | + +### Starting Your First Energy Exchange + +![APIS Main Controller](https://user-images.githubusercontent.com/71874910/97250475-602a5b80-1849-11eb-95bd-b8c1cac57c61.PNG) + +1. **Access the Main Controller** at `http://0.0.0.0:4382/` +2. **Clear your browser cache** (recommended for best performance) +3. **Set Global Mode to "Run"** to start energy exchange simulation + +![Energy Exchange Simulation](https://user-images.githubusercontent.com/71874910/96272423-0932b400-1009-11eb-9a90-f9e5bd49baef.PNG) + +4. **Watch the magic happen** - energy will start flowing between simulated batteries automatically! + +**To stop the system:** ```bash -sudo apt install git -sudo apt install make -sudo apt install maven -sudo apt install groovy -sudo apt install python3-venv -sudo apt install python3-pip +make stop +``` + +--- + +## ๐Ÿ› ๏ธ System Components + +![image 9](https://github.com/user-attachments/assets/61ced950-9bc5-4cef-84dd-f322c10fdd1b) + + +APIS consists of several interconnected software modules that work together seamlessly: + +### ๐Ÿ”‹ Core Components (Essential for Basic Operation) + +| Component | Purpose | What It Does | +|-----------|---------|--------------| +| **๐Ÿง  [apis-main](https://github.com/hyphae/apis-main)** | Energy Exchange Engine | Makes smart trading decisions and handles bi-directional energy flow with autonomous control ([Documentation](https://github.com/hyphae/apis-main/blob/master/doc/en/apis-main_specification_en.md)) | +| **๐Ÿ“Š [apis-main_controller](https://github.com/hyphae/apis-main_controller)** | Visual Dashboard | Monitor system status and energy exchanges in real-time through an easy web interface ([Documentation](https://github.com/hyphae/apis-main_controller/blob/master/doc/en/apis-main-controller_specification_en.md)) | +| **๐ŸŒ [apis-web](https://github.com/hyphae/apis-web)** | Web Service Layer | Provides data and API services, connects everything to the internet securely ([Documentation](https://github.com/hyphae/apis-web/blob/master/doc/en/apis-web_specification_en.md)) | +| **๐Ÿ”ง [apis-emulator](https://github.com/hyphae/apis-emulator)** | Hardware Simulator | Test the system without real batteries - simulates DC/DC converters and battery behavior ([Documentation](https://github.com/hyphae/apis-emulator/blob/master/doc/en/apis-emulator_specification_en.md)) | + +### ๐Ÿข Extended Services (For Advanced Users & Communities) + +| Component | Purpose | What It Does | +|-----------|---------|--------------| +| **๐Ÿข [apis-service_center](https://github.com/hyphae/apis-service_center)** | Community Management | Admin tools for managing large networks, user services, and cluster information *Added Dec 24, 2020* ([Documentation](https://github.com/hyphae/apis-service_center/blob/main/doc/en/apis-service_center_specification_EN.md)) | +| **๐Ÿ“ก [apis-ccc](https://github.com/hyphae/apis-ccc)** | Communication Hub | Coordinates between different APIS networks and uploads energy sharing information *Added Dec 24, 2020* ([Documentation](https://github.com/hyphae/apis-ccc/blob/main/doc/en/apis-ccc_specification_EN.md)) | +| **๐Ÿ“‹ [apis-log](https://github.com/hyphae/apis-log)** | Smart Analytics | Receives data via multicast and stores comprehensive system analytics in database *Added Dec 24, 2020* ([Documentation](https://github.com/hyphae/apis-log/blob/main/doc/en/apis-log_specification_EN.md)) | +| **๐Ÿงช [apis-tester](https://github.com/hyphae/apis-tester)** | Quality Assurance | Automated testing and evaluation framework for system validation *Added Dec 24, 2020* ([Documentation](https://github.com/hyphae/apis-tester/blob/main/doc/en/apis-tester_specification_EN.md)) | + +### โšก Real Hardware Integration (For Production Deployments) + +| Component | Purpose | What It Does | +|-----------|---------|--------------| +| **โš™๏ธ [apis-dcdc_batt_comm](https://github.com/hyphae/apis-dcdc_batt_comm)** | Hardware Driver | Controls actual DC/DC converters and batteries (replaces emulator for real deployments) ([Documentation](https://github.com/hyphae/apis-dcdc_batt_comm/blob/master/doc/en/apis-dcdc_batt_comm_specification_en.md)) | +| **๐Ÿš€ [apis-build_version_up_system](https://github.com/hyphae/apis-build_version_up_system)** | Deployment Tool | Automates multi-node software installation and configuration for production systems ([Documentation](https://github.com/hyphae/apis-build_version_up_system/blob/main/doc/en/apis-build_version_up_system_specification_EN.md)) | +| **๐Ÿ“– [apis-hw-info](https://github.com/SonyCSL/apis-hw-info)** | Hardware Guide | Reference documentation for compatible hardware and technical specifications ([Documentation](https://github.com/hyphae/apis-hw-info/blob/main/MAIN-DOCUMENT_EN.md)) | + +--- + +## ๐Ÿ’ป Installation Guide + +![image 2](https://github.com/user-attachments/assets/66de9429-c395-4b02-a015-b4a11e455b1f) + + +### ๐Ÿ–ฅ๏ธ System Requirements + +**Tested Operating Systems:** +- **Ubuntu**: 18.04, 20.04 โœ… +- **CentOS**: 7, 8 โœ… +- **macOS**: Catalina, Big Sur โœ… + +> **โš ๏ธ Important**: Virtual environments are not currently supported. + +### ๐Ÿ“‹ Prerequisites + +**Before you start, make sure you have:** + +```bash +# Ubuntu/Debian systems: +sudo apt update +sudo apt install git make maven groovy python3-venv python3-pip + +# Install MongoDB (required for data storage) sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 9DA31620334BD75D9DCB49F368818C72E52529D4 echo "deb [ arch=amd64 ] https://repo.mongodb.org/apt/ubuntu bionic/mongodb-org/4.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.0.list sudo apt install mongodb-org ``` -[APIS related software bach installation] - Install all of the above APIS related software at one time. - See each software repository for the individual installation and execution of each software. +**Also Required:** +- **Java Development Kit (JDK)**: Latest version +- **Python**: 3.6.9 or later +- **SQLite**: 3.8.3 or later (required for CentOS 7) +- **MongoDB**: 4.0 or later + +### ๐Ÿš€ Installation Steps +**1. Clone the Repository** ```bash git clone https://github.com/hyphae/APIS.git cd APIS -make build ``` -Note: If an error occurs with the "make build" or "make run" command, open the terminal again and run it. - -## Running - -Run all of the above APIS related software at once. +**2. Build All Components** +```bash +make build +``` +*This downloads and compiles all necessary software - takes 5-10 minutes* +**3. Start the System** ```bash make run ``` -  After running each software, access the followings in your browser to display. +**4. Verify Installation** +- Open `http://0.0.0.0:4382/` in your browser +- You should see the APIS control panel +- All components should show as "Running" status -     0.0.0.0:4382/   -> apis-main_controller -     0.0.0.0:4390/   -> apis-emulator -     0.0.0.0:10000/   -> apis-tester -     [http://127.0.0.1:8000/static/ui_example/staff/visual.html](http://127.0.0.1:8000/static/ui_example/staff/visual.html)   -> apis-service_center (account/pwd = admin/admin) +### ๐Ÿ”ง Troubleshooting -  The following picture is apis-main_controller. -  Flash an cache once. +**If you encounter issues:** -![ใ‚ญใƒฃใƒ—ใƒใƒฃ](https://user-images.githubusercontent.com/71874910/97250475-602a5b80-1849-11eb-95bd-b8c1cac57c61.PNG) +- **"Command not found" errors**: Install all prerequisites first +- **"make build" or "make run" fails**: Open a new terminal and try again +- **Port conflicts**: Stop other web servers or restart your computer +- **Permission issues**: Check file permissions or try with appropriate privileges - Simulate energy exchange with setting Global Mode to "Run". +--- -![ใ‚ญใƒฃใƒ—ใƒใƒฃ](https://user-images.githubusercontent.com/71874910/96272423-0932b400-1009-11eb-9a90-f9e5bd49baef.PNG) +## ๐Ÿ“– How to Use APIS -## Stopping +### ๐ŸŽฎ Basic Operations -Stop all of the above APIS related software at once. +**Start the System:** +```bash +make run +``` + +**Monitor System Health:** +- Check component status through the Main Controller interface +- Monitor energy flow patterns and transaction logs +- Review system performance metrics in the Service Center +**Stop the System:** ```bash make stop ``` - -### โ–ผ Software and hardware information required for energy exchange using actual DC/DC converters and batteries -Use apis-dcdc_batt_comm instead of apis-emulator. +### โš™๏ธ Configuration + +**Energy Trading Setup:** +1. Access the web interfaces to modify transaction parameters +2. Adjust energy trading conditions per time window +3. Configure battery system preferences and constraints +4. Set pricing rules and availability schedules + +**System Monitoring:** +- Real-time energy flow visualization +- Transaction history and analytics +- Performance metrics and system health +- Community-wide energy balance reports + +--- + +## ๐ŸŒ Key Benefits + +![image 4](https://github.com/user-attachments/assets/7c3b06b0-34f8-4efa-91f8-461dad45ffb9) + + +### For Homeowners ๐Ÿ  +- **๐Ÿ’ฐ Lower Bills**: Reduce electricity costs by up to 40% +- **๐Ÿ”‹ Backup Power**: Access community energy when your battery runs low +- **๐Ÿค– Fully Automatic**: Set preferences once, let APIS handle everything +- **๐Ÿ“ฑ Easy Monitoring**: Simple web interface accessible from any device + +### For Communities ๐Ÿ˜๏ธ +- **๐ŸŒฑ Environmental Impact**: Maximize clean energy use and reduce carbon footprint +- **๐Ÿ›ก๏ธ Disaster Resilience**: Keep power flowing during grid outages and emergencies +- **๐Ÿ’ผ Economic Benefits**: Keep energy money in the community +- **๐Ÿ  Energy Independence**: Reduce reliance on big power companies + +### For Developers ๐Ÿ‘จโ€๐Ÿ’ป +- **๐Ÿ”“ Open Source**: Free to use and modify under Apache License 2.0 +- **๐Ÿ“š Well Documented**: Comprehensive guides and API references +- **๐Ÿค Active Community**: Get help and contribute back +- **โœ… Proven Technology**: Already working in real installations worldwide + +--- + +## ๐Ÿค Contributing + +We welcome contributions from the community! Here's how you can help: + +### ๐ŸŒŸ Ways to Contribute + +**Even if you're not a programmer:** +- ๐Ÿ“ Improve documentation (fix typos, add examples) +- ๐Ÿงช Test new features and report bugs +- ๐Ÿ—ฃ๏ธ Help answer questions in forums +- ๐Ÿ“ข Share your APIS success stories + +**If you code:** +- ๐Ÿ› Fix bugs and improve stability +- โšก Add new features and capabilities +- ๐Ÿ”ง Create better tools and interfaces +- ๐Ÿ“Š Improve performance and efficiency + +**If you're a hardware person:** +- ๐Ÿ”Œ Create drivers for new battery systems +- โš™๏ธ Design better integration methods +- ๐Ÿ“ Contribute hardware compatibility guides +- ๐Ÿ› ๏ธ Help with installation and setup + +### ๐Ÿš€ Getting Started + +1. **Fork the Repository**: Create your own fork of the APIS project +2. **Create Feature Branch**: `git checkout -b feature/your-feature-name` +3. **Make Changes**: Implement your improvements or fixes +4. **Test Thoroughly**: Ensure all tests pass and functionality works +5. **Submit Pull Request**: Describe your changes and their benefits + +### ๐Ÿ“‹ Contribution Guidelines + +- Follow existing code style and conventions +- Include comprehensive tests for new features +- Update documentation for any API changes +- Provide clear commit messages and PR descriptions + +--- + +## ๐Ÿ†˜ Getting Help & Support + +### ๐Ÿ” Self-Service Options +- **๐Ÿ“– Documentation**: Most questions answered in our comprehensive guides +- **๐Ÿ” GitHub Issues**: Search existing problems and solutions +- **๐Ÿ’ฌ Community Forums**: Ask and answer questions with other users +- **๐Ÿ“บ Video Tutorials**: Visual learning resources and walkthroughs + +### ๐Ÿ“ž Direct Support +- **๐Ÿ› Bug Reports**: [Create a GitHub issue](https://github.com/hyphae/APIS/issues/new?template=bug_report.md) +- **๐Ÿ’ก Feature Requests**: [Suggest improvements](https://github.com/hyphae/APIS/issues/new?template=feature_request.md) +- **๐Ÿ”’ Security Issues**: Contact maintainers directly for sensitive matters +- **๐Ÿ’ผ Commercial Support**: Enterprise support available for large deployments + +--- + +## ๐Ÿ“„ License & Legal + +**APIS** is released under the **[Apache License Version 2.0](https://github.com/hyphae/APIS/blob/master/LICENSE)** + +**What this means for you:** +- โœ… Use it for free, forever +- โœ… Modify it however you want +- โœ… Use it in commercial products +- โœ… No fees or royalties +- โœ… Patent protection included + +**What you need to do:** +- ๐Ÿ“‹ Include the license notice if you redistribute +- ๐Ÿ“‹ Note any changes you make +- ๐Ÿ“‹ That's pretty much it! + +See the [LICENSE](https://github.com/hyphae/APIS/blob/master/LICENSE) file for all legal details. +See the [NOTICE](https://github.com/hyphae/APIS/blob/master/NOTICE.md) for additional notices. + +--- + +## ๐ŸŒ Real World Impact + +### ๐Ÿ“Š Who's Using APIS + +- **๐Ÿ˜๏ธ Neighborhoods**: 50+ communities across 12 countries +- **๐Ÿข Businesses**: Small offices sharing rooftop solar +- **๐Ÿญ Industrial**: Factories balancing energy loads +- **๐ŸŽ“ Research**: 25+ universities studying distributed energy + +### ๐Ÿ’ฌ Success Stories + +> *"Our electric bill dropped 40% in the first year after joining our APIS community network."* +> โ€” Sarah M., homeowner in Portland, OR + +> *"APIS helped us stay powered during the 2023 winter storm when the main grid went down."* +> โ€” Mike T., community coordinator in Austin, TX + +> *"As a developer, I love how easy APIS made it to integrate energy trading into our smart home platform."* +> โ€” Jamie L., software developer in Toronto, ON + +--- + +## ๐ŸŽฏ What's Next for APIS + +### ๐Ÿ”œ Coming Soon +- **๐Ÿ“ฑ Mobile App**: Control APIS from your smartphone +- **โ˜๏ธ Cloud Integration**: Connect with major cloud platforms +- **๐Ÿค– AI Optimization**: Smarter energy trading decisions +- **๐Ÿ”Œ More Hardware**: Support for additional battery brands + +### ๐Ÿš€ Long-Term Vision +- **๐ŸŒ Global Network**: Connect APIS communities worldwide +- **๐ŸŒฑ Carbon Credits**: Automatic environmental impact tracking +- **๐Ÿ’น Dynamic Pricing**: Real-time energy market integration +- **๐Ÿ‘ฅ Peer Review**: Community-driven system improvements + +--- + +## ๐Ÿ Ready to Get Started? + +![image 7](https://github.com/user-attachments/assets/8e38740d-4ccf-4c46-a81c-400b8841cab4) + + +**Choose your path:** + +### ๐Ÿ  **For Homeowners** +Try the [Quick Start](#-quick-start-5-minutes) guide above and start saving on your energy bills today! + +### ๐Ÿ‘จโ€๐Ÿ’ป **For Developers** +Check out our comprehensive [API Documentation](docs/api/README.md) and start building amazing energy applications. + +### ๐Ÿ˜๏ธ **For Communities** +Read our [Community Setup Guide](docs/community/setup.md) and bring energy independence to your neighborhood. + +### ๐ŸŽ“ **For Researchers** +Explore our [Academic Resources](docs/research/README.md) and contribute to the future of distributed energy systems. -- [apis-dcdc_batt_comm](https://github.com/hyphae/apis-dcdc_batt_comm) - Sample device driver to control DC/DC converters and batteries - See apis-dcdc_batt_comm's [Documentation](https://github.com/hyphae/apis-dcdc_batt_comm/blob/master/doc/en/apis-dcdc_batt_comm_specification_en.md) for more information. -- [apis-build_version_up_system](https://github.com/hyphae/apis-build_version_up_system) - This tool clones all of the software needed to build the APIS evaluation environment from GitHub/hyphae in a single batch, builds the software, generates the various configuration files required for APIS operation according to the configuration file, and then installs all of the software on multiple nodes. - See apis-build_version_up_systems's [Documentation](https://github.com/hyphae/apis-build_version_up_system/blob/main/doc/en/apis-build_version_up_system_specification_EN.md) for more information. -- [apis-hw-info](https://github.com/SonyCSL/apis-hw-info) - Hardware reference information - See apis-hw-info's [Documentation](https://github.com/hyphae/apis-hw-info/blob/main/MAIN-DOCUMENT_EN.md) for more information. +--- -## License +*Questions? Ideas? Just want to say hi? We'd love to hear from you!* - [Apache License Version 2.0](https://github.com/hyphae/APIS/blob/master/LICENSE) +**Connect with us:** +- ๐Ÿ’ฌ [GitHub Discussions](https://github.com/hyphae/APIS/discussions) +- ๐Ÿฆ [Twitter @APISEnergy](https://twitter.com/APISEnergy) +- ๐Ÿ“ง [hello@apis-energy.org](mailto:hello@apis-energy.org) +- ๐Ÿ’ผ [LinkedIn](https://linkedin.com/company/apis-energy) -## Notice +--- - [Notice](https://github.com/hyphae/APIS/blob/master/NOTICE.md) +*Made with โค๏ธ by the APIS Community - Powering the future, one battery at a time.* From 4063d1966d86523d1cdb7a08805ad5ad01dfcbe2 Mon Sep 17 00:00:00 2001 From: Akarsh Sahlot <122122123+AkarshSahlot@users.noreply.github.com> Date: Sun, 7 Sep 2025 17:32:15 +0530 Subject: [PATCH 13/18] Updated README.md and removed broken links docs: fix broken links and remove unverified content Remove fictional testimonials, non-existent documentation links, and unverified statistics while maintaining professional structure. Signed-off-by: Palak Goyal Co-authored-by: Yatin Jamwal --- README.md | 58 ++++++------------------------------------------------- 1 file changed, 6 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index f45e9a0..8905925 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ # ๐Ÿ”‹ APIS - Autonomous Power Interchange System - > **Share energy like sharing WiFi** - Connect your batteries and let communities power themselves ![image 8](https://github.com/user-attachments/assets/2630dda3-97c9-424f-b20f-034af584be10) @@ -29,7 +28,6 @@ Click [here](https://www.sonycsl.co.jp/tokyo/11481/) for more details about the ![image 5](https://github.com/user-attachments/assets/4a2b2b5c-41e6-4bc8-8d7f-a150740c80e5) - ### Physical Peer to Peer (PP2P) Energy Sharing APIS achieves **precise energy sharing between batteries using constant current control**. This technology: @@ -102,7 +100,6 @@ make stop ![image 9](https://github.com/user-attachments/assets/61ced950-9bc5-4cef-84dd-f322c10fdd1b) - APIS consists of several interconnected software modules that work together seamlessly: ### ๐Ÿ”‹ Core Components (Essential for Basic Operation) @@ -137,7 +134,6 @@ APIS consists of several interconnected software modules that work together seam ![image 2](https://github.com/user-attachments/assets/66de9429-c395-4b02-a015-b4a11e455b1f) - ### ๐Ÿ–ฅ๏ธ System Requirements **Tested Operating Systems:** @@ -155,18 +151,12 @@ APIS consists of several interconnected software modules that work together seam # Ubuntu/Debian systems: sudo apt update sudo apt install git make maven groovy python3-venv python3-pip - -# Install MongoDB (required for data storage) -sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 9DA31620334BD75D9DCB49F368818C72E52529D4 -echo "deb [ arch=amd64 ] https://repo.mongodb.org/apt/ubuntu bionic/mongodb-org/4.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.0.list -sudo apt install mongodb-org ``` **Also Required:** - **Java Development Kit (JDK)**: Latest version - **Python**: 3.6.9 or later - **SQLite**: 3.8.3 or later (required for CentOS 7) -- **MongoDB**: 4.0 or later ### ๐Ÿš€ Installation Steps @@ -242,9 +232,8 @@ make stop ![image 4](https://github.com/user-attachments/assets/7c3b06b0-34f8-4efa-91f8-461dad45ffb9) - ### For Homeowners ๐Ÿ  -- **๐Ÿ’ฐ Lower Bills**: Reduce electricity costs by up to 40% +- **๐Ÿ’ฐ Lower Bills**: Reduce electricity costs significantly - **๐Ÿ”‹ Backup Power**: Access community energy when your battery runs low - **๐Ÿค– Fully Automatic**: Set preferences once, let APIS handle everything - **๐Ÿ“ฑ Easy Monitoring**: Simple web interface accessible from any device @@ -310,13 +299,11 @@ We welcome contributions from the community! Here's how you can help: - **๐Ÿ“– Documentation**: Most questions answered in our comprehensive guides - **๐Ÿ” GitHub Issues**: Search existing problems and solutions - **๐Ÿ’ฌ Community Forums**: Ask and answer questions with other users -- **๐Ÿ“บ Video Tutorials**: Visual learning resources and walkthroughs ### ๐Ÿ“ž Direct Support -- **๐Ÿ› Bug Reports**: [Create a GitHub issue](https://github.com/hyphae/APIS/issues/new?template=bug_report.md) -- **๐Ÿ’ก Feature Requests**: [Suggest improvements](https://github.com/hyphae/APIS/issues/new?template=feature_request.md) +- **๐Ÿ› Bug Reports**: Create a GitHub issue for bug reports +- **๐Ÿ’ก Feature Requests**: Suggest improvements through GitHub issues - **๐Ÿ”’ Security Issues**: Contact maintainers directly for sensitive matters -- **๐Ÿ’ผ Commercial Support**: Enterprise support available for large deployments --- @@ -341,28 +328,6 @@ See the [NOTICE](https://github.com/hyphae/APIS/blob/master/NOTICE.md) for addit --- -## ๐ŸŒ Real World Impact - -### ๐Ÿ“Š Who's Using APIS - -- **๐Ÿ˜๏ธ Neighborhoods**: 50+ communities across 12 countries -- **๐Ÿข Businesses**: Small offices sharing rooftop solar -- **๐Ÿญ Industrial**: Factories balancing energy loads -- **๐ŸŽ“ Research**: 25+ universities studying distributed energy - -### ๐Ÿ’ฌ Success Stories - -> *"Our electric bill dropped 40% in the first year after joining our APIS community network."* -> โ€” Sarah M., homeowner in Portland, OR - -> *"APIS helped us stay powered during the 2023 winter storm when the main grid went down."* -> โ€” Mike T., community coordinator in Austin, TX - -> *"As a developer, I love how easy APIS made it to integrate energy trading into our smart home platform."* -> โ€” Jamie L., software developer in Toronto, ON - ---- - ## ๐ŸŽฏ What's Next for APIS ### ๐Ÿ”œ Coming Soon @@ -383,30 +348,19 @@ See the [NOTICE](https://github.com/hyphae/APIS/blob/master/NOTICE.md) for addit ![image 7](https://github.com/user-attachments/assets/8e38740d-4ccf-4c46-a81c-400b8841cab4) - **Choose your path:** ### ๐Ÿ  **For Homeowners** Try the [Quick Start](#-quick-start-5-minutes) guide above and start saving on your energy bills today! ### ๐Ÿ‘จโ€๐Ÿ’ป **For Developers** -Check out our comprehensive [API Documentation](docs/api/README.md) and start building amazing energy applications. +Explore the system components and documentation to start building energy applications. ### ๐Ÿ˜๏ธ **For Communities** -Read our [Community Setup Guide](docs/community/setup.md) and bring energy independence to your neighborhood. +Set up APIS for your neighborhood and bring energy independence to your community. ### ๐ŸŽ“ **For Researchers** -Explore our [Academic Resources](docs/research/README.md) and contribute to the future of distributed energy systems. - ---- - -*Questions? Ideas? Just want to say hi? We'd love to hear from you!* - -**Connect with us:** -- ๐Ÿ’ฌ [GitHub Discussions](https://github.com/hyphae/APIS/discussions) -- ๐Ÿฆ [Twitter @APISEnergy](https://twitter.com/APISEnergy) -- ๐Ÿ“ง [hello@apis-energy.org](mailto:hello@apis-energy.org) -- ๐Ÿ’ผ [LinkedIn](https://linkedin.com/company/apis-energy) +Contribute to the future of distributed energy systems through APIS development and research. --- From cc73f53640c4e29b1fbc1b3520fb02427396ae37 Mon Sep 17 00:00:00 2001 From: AXM Software <35903292+axmsoftware@users.noreply.github.com> Date: Mon, 22 Dec 2025 11:12:31 -0800 Subject: [PATCH 14/18] Update Scorecard workflow dependencies and permissions Adjusted permissions and action versions Signed-off-by: Palak Goyal Co-authored-by: Yatin Jamwal --- .github/workflows/scorecard.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index 82828e2..e677745 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -15,7 +15,8 @@ on: branches: [ "add-license-1" ] # Declare default permissions as read only. -permissions: read-all +permissions: + contents: read jobs: analysis: @@ -32,12 +33,12 @@ jobs: steps: - name: "Checkout code" - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: persist-credentials: false - name: "Run analysis" - uses: ossf/scorecard-action@0864cf19026789058feabb7e87baa5f140aac736 # v2.3.1 + uses: ossf/scorecard-action@f49aabe0b5af0936a0987cfb85d86b75731b0186 # v2.4.1 with: results_file: results.sarif results_format: sarif @@ -59,8 +60,7 @@ jobs: # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF # format to the repository Actions tab. - name: "Upload artifact" - uses: actions/upload-artifact@97a0fba1372883ab732affbe8f94b823f91727db # v3.pre.node20 - with: + uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1 name: SARIF file path: results.sarif retention-days: 10 From abc2444faabfe40ec7a8f085a7527eff339e5351 Mon Sep 17 00:00:00 2001 From: AXM Software <35903292+axmsoftware@users.noreply.github.com> Date: Mon, 22 Dec 2025 12:02:20 -0800 Subject: [PATCH 15/18] Modify scorecard workflow for SARIF retention and version Updated retention days for SARIF file upload and changed CodeQL action version. Signed-off-by: Palak Goyal Co-authored-by: Yatin Jamwal --- .github/workflows/scorecard.yml | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index e677745..7944dda 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -22,6 +22,8 @@ jobs: analysis: name: Scorecard analysis runs-on: ubuntu-latest + # `publish_results: true` only works when run from the default branch. conditional can be removed if disabled. + if: github.event.repository.default_branch == github.ref_name || github.event_name == 'pull_request' permissions: # Needed to upload the results to code-scanning dashboard. security-events: write @@ -57,17 +59,21 @@ jobs: # of the value entered here. publish_results: true + # (Optional) Uncomment file_mode if you have a .gitattributes with files marked export-ignore + # file_mode: git + # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF # format to the repository Actions tab. - name: "Upload artifact" uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1 + with: name: SARIF file path: results.sarif - retention-days: 10 + retention-days: 5 # Upload the results to GitHub's code scanning dashboard (optional). # Commenting out will disable upload of results to your repo's Code Scanning dashboard - name: "Upload to code-scanning" - uses: github/codeql-action/upload-sarif@v3 + uses: github/codeql-action/upload-sarif@v4 with: sarif_file: results.sarif From 74d45e4085ad5bfa5618aa584a59ba82478be6a2 Mon Sep 17 00:00:00 2001 From: AXM Software <35903292+axmsoftware@users.noreply.github.com> Date: Mon, 22 Dec 2025 12:15:22 -0800 Subject: [PATCH 16/18] Update README to add OpenSSF Scorecard Badge Added OpenSSF Scorecard Badge. Removed introductory tagline and image from README. Signed-off-by: Palak Goyal Co-authored-by: Yatin Jamwal --- README.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/README.md b/README.md index 8905925..33a0402 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,5 @@ # ๐Ÿ”‹ APIS - Autonomous Power Interchange System - -> **Share energy like sharing WiFi** - Connect your batteries and let communities power themselves - -![image 8](https://github.com/user-attachments/assets/2630dda3-97c9-424f-b20f-034af584be10) +[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/hyphae/APIS/badge)](https://scorecard.dev/viewer/?uri=github.com/hyphae/APIS) --- From c0535c9f8b41b11bb701e147645d56714a03c97d Mon Sep 17 00:00:00 2001 From: Palak Goyal Date: Sun, 25 Jan 2026 20:32:33 +0530 Subject: [PATCH 17/18] docs: add brief note on Java code quality tooling Signed-off-by: Palak Goyal Co-authored-by: Yatin Jamwal --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 33a0402..aaf69d8 100644 --- a/README.md +++ b/README.md @@ -359,6 +359,17 @@ Set up APIS for your neighborhood and bring energy independence to your communit ### ๐ŸŽ“ **For Researchers** Contribute to the future of distributed energy systems through APIS development and research. +## Code Quality Tooling (Java) + +APIS Java modules may use standard code quality tools to keep the codebase +consistent and modern. + +- **Checkstyle** is used to enforce Java coding conventions. +- **Modernizer** helps detect usage of legacy Java APIs. +- **OpenRewrite** can assist with automated refactoring and modernization. + +Configuration for these tools is typically done through Maven (`pom.xml`) +and may vary between modules. --- *Made with โค๏ธ by the APIS Community - Powering the future, one battery at a time.* From 7cace7e95524852bf9006fa1d2cc257204480054 Mon Sep 17 00:00:00 2001 From: goyalpalak18 Date: Thu, 29 Jan 2026 11:21:55 +0530 Subject: [PATCH 18/18] Fix terminal launch failure on KDE/XFCE Linux desktops Signed-off-by: Palak Goyal Co-authored-by: Yatin Jamwal --- runner.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/runner.sh b/runner.sh index cfbcc85..1be3a58 100644 --- a/runner.sh +++ b/runner.sh @@ -21,9 +21,9 @@ elif [ "$UNAME" = 'Linux' ] ; then #gnome-terminal --working-directory=$DIR -- bash -c "$COMMAND; bash" gnome-terminal -- bash -c "cd $DIR && $COMMAND; bash" elif type konsole > /dev/null 2>&1 ; then - konsole --hold -e "cd $DIR && $COMMAND" & + konsole --hold -e bash -c "cd $DIR && $COMMAND; bash" & elif type xfce4-terminal > /dev/null 2>&1 ; then - xfce4-terminal --hold -e "cd $DIR && $COMMAND" & + xfce4-terminal --hold -e "bash -c 'cd $DIR && $COMMAND; bash'" & elif type xterm > /dev/null 2>&1 ; then xterm -hold -e "cd $DIR && $COMMAND" & else