EBPP

EBPP (Electric Blocks PandaPower) is a server that sends and receives simulation results for the mod Electric Blocks.

Table of Contents

• About the Project
  • Built With
• Installation
  • Docker Install
  • Manual Install
• Usage
  • Client Requests
  • Server Responses
• License
• Acknowledgements

About The Project

EBPP is a python HTTP server written using flask that receives power flow simulation requests, performs the simulation, and returns the results. We use pandapower to perform the simulations. This software is written specifically for use with the Electric Blocks mod, but could theoretically be used to call pandapower for other applications. The simulation software is decoupled from the actual server mod itself to allow for a single server to process simulations for multiple minecraft servers. EBPP does not track the state of the Minecraft world and so all calls are stateless. This means the Electric Blocks mod is responsible for tracking the state of blocks in the game. The mod must track connectivity, block state, and update events. It will then make requests to the server when needed. All Electric Blocks (except wires/lines) must be assigned a UUID. This allows EBPP to return the information results for each block in game.

Built With

• Python 3.8
• Flask
• PandaPower
• Docker (Optional)

Installation

When installing this software you have two options. The first option uses docker to automate the process. This option is easier to do, but requires that you have docker. The second option is the manual installation.

Docker Install

First make sure you have docker installed on your computer/server. Then build with this command:

docker build github.com/ElectricBlocks/ebpp -t ebpp

Once the docker image is finished building, you can run with the command:

docker run -d -p 1127:1127 ebpp

Manual Install

To install manually, make sure you have python3 installed and then run the following commands:

git clone https://github.com/ElectricBlocks/ebpp.git
cd ebpp
pip install -r requirements.txt

Once the python packages are installed, you can run with the command:

python ebpp.py

Usage

Once the server is running, you can test it by going to http://127.0.0.1:1127 in your web browser. Make sure you are not using SSL. You should receive a simple text welcome response.

The endpoint for using the API is http://127.0.0.1:1127/api. This API sends and receives info using JSON. All packets must include a status key that contains the request type.

Client Requests

KEEP_ALIVE checks if the server is responding to requests.

{
    "status": "KEEP_ALIVE"
}

SIM_REQUEST requests that server perform a simulation. Properties for each element will depend on the type. EBPP does not do error checking and will just pass these values onto PandaPower.

{
    "status": "SIM_REQUEST",
    "3phase": false,
    "elements": {
        "UUID": {
            "etype": "gen",
            "bus": "UUID of Bus",
            "p_mw": 1.0,
            "vm_pu": 120,
            "other_properties": "value",
            ...
        },
        ...
    }
}

Server Responses

KEEP_ALIVE lets client know that serer is responding to requests.

{
    "status": "KEEP_ALIVE",
    "response": "Keep alive request acknowledged"
}

SIM_RESULT results of the sim request. Results for each element will depend on type.

{
    "status": "SIM_RESULT",
    "elements": {
        "UUID": {
            "etype": "gen",
            "p_mw": 1.0,
            "vm_pu": 120.0,
            "other_results": "value",
            ...
        },
        ...
    }
}

JSON_ERROR clients request could not be parsed as json.

{
    "status": "JSON_ERROR",
    "response": "Some Error Message"
}

INVALID_ERROR clients request was able to be parsed, but an invalid status was given or there is some other issue with the request.

{
    "status": "INVALID_ERROR",
    "response": "Some Error Message"
}

PP_ERROR client's SIM_REQUEST was accepted by EBPP, but PandaPower returned an error.

{
    "status": "PP_ERROR",
    "response": "Some Error Message"
}

CONV_ERROR client's SIM_REQUEST was accepted by EBPP, but the PandaPower failed to converge on a stable result. The network is invalid or unstable.

{
    "status": "CONV_ERROR",
    "response": "Some Error Message"
}

This software is in heavy development. This will probably change and break. Sorry ¯\_(ツ)_/¯.

License

Distributed under the GNU Affero General Public License. See LICENSE.md for more information.

Acknowledgements

This software is developed by students at the University of Idaho for the Capstone Design class:

• Zachary Sugano - Project Lead - zachoooo
• Christian Whitfield - Team Member/Communications Lead - oceanwhit