|
| 1 | +# Sample Python Base Code (gRPC) |
| 2 | + |
| 3 | +[](https://clsframework.github.io/docs/introduction/) |
| 4 | +[](https://opensource.org/licenses/MIT) |
| 5 | + |
| 6 | +This repository contains a sample decision-making server for the RoboCup 2D Soccer Simulation, which allows you to create a team by using Python. This server is compatible with the [Cross Language Soccer Framework](https://arxiv.org/pdf/2406.05621). This server is written in Python and uses gRPC to communicate with the [proxy](https://github.com/CLSFramework/soccer-simulation-proxy). |
| 7 | + |
| 8 | +The Soccer Simulation Server sends the observations to the proxy, which processes the data, create state message and sends it to the decision-making server. The decision-making server then sends the actions to the proxy, and then the proxy convert actions to the server commands and sends them to the server. |
| 9 | + |
| 10 | +For more information, please refer to the [documentation](https://clsframework.github.io/). |
| 11 | + |
| 12 | +## Quick start |
| 13 | + |
| 14 | +### Preparation |
| 15 | + |
| 16 | +Install the pre-requisites using the command below: |
| 17 | + |
| 18 | +``` Bash |
| 19 | +sudo apt-get install fuse #Used to run AppImages |
| 20 | +``` |
| 21 | + |
| 22 | +Clone this repository & install the required python libraries (such as gRPC). Don't forget to activate your virtual environment! |
| 23 | + |
| 24 | +``` Bash |
| 25 | +git clone https://github.com/CLSFramework/sample-playmaker-server-python-grpc.git |
| 26 | +cd sample-playmaker-server-python-grpc |
| 27 | +# Activate venv/anaconda before this step! |
| 28 | +pip install -r requirements.txt |
| 29 | + |
| 30 | +./generate.sh # Generate the gRPC files |
| 31 | +``` |
| 32 | + |
| 33 | +To download RoboCup Soccer 2D Server using the commands below: |
| 34 | + |
| 35 | +``` Bash |
| 36 | +pushd scripts |
| 37 | +sh download-rcssserver.sh # Download the soccer simulation server |
| 38 | +popd |
| 39 | +``` |
| 40 | + |
| 41 | +Next, download the soccer proxy, which uses C++ to read and pre-processes state data and passes them to the Python server (this project) for decision-making. |
| 42 | + |
| 43 | +``` Bash |
| 44 | +pushd scripts |
| 45 | +sh download-proxy.sh #install C++ proxy |
| 46 | +popd |
| 47 | +``` |
| 48 | + |
| 49 | +Finally, to watch the game, download the monitor from [the original repository](https://github.com/rcsoccersim/rcssmonitor/releases) in order to view the games. |
| 50 | + |
| 51 | +### Running a game |
| 52 | + |
| 53 | +This section assumes you have installed the server & proxy using the scripts (as mentioned above) |
| 54 | +We must first run a RoboCup Server, in order to host the game: |
| 55 | + |
| 56 | +``` Bash |
| 57 | +cd scripts/rcssserver |
| 58 | +./rcssserver |
| 59 | +``` |
| 60 | + |
| 61 | +Then we must run the proxy & the decisionmaking server: |
| 62 | + |
| 63 | +``` Bash |
| 64 | +./start-team.sh |
| 65 | +``` |
| 66 | + |
| 67 | +Launch the opponent team, start the monitor app image. press <kbd>Ctrl</kbd> + <kbd>C</kbd> to connect to the server, and <kbd>Ctrl</kbd> + <kbd>K</kbd> for kick-off! |
| 68 | + |
| 69 | +### Tutorial Video (English) |
| 70 | + |
| 71 | +TDB |
| 72 | + |
| 73 | +### Tutorial Video (Persian) |
| 74 | + |
| 75 | +[](https://www.youtube.com/watch?v=97YDEumcVWU&t=0s) |
| 76 | + |
| 77 | +## How to change the code |
| 78 | + |
| 79 | +The `server.py` file contains the logic in 3 main functions: |
| 80 | +`GetPlayerActions` receives a game state, and returns a list of actions for a player for for that cycle. |
| 81 | +The actions we can output are equivalent to the Helios Base (Proxy), which are abstracted into multiple levels. |
| 82 | +You can use actions such as `DoDash`, `DoTurn`, `DoKick` which directly apply force, or use actions such as `GoToPoint`, `SmartKick`, `Shoot` or [more](https://clsframework.github.io/docs/idl/). |
| 83 | + |
| 84 | +Similarly, you can change `GetCoachActions` which is responsible for coach communication & substitutions. |
| 85 | + |
| 86 | +You can also use `GetTrainerActions` to move the players & the ball to make repeatable scenarios (when the server is in trainer mode). |
| 87 | + |
| 88 | +## Why & How it works |
| 89 | + |
| 90 | +Originally the RoboCup 2D Soccer Simulation teams used C++, as the main code base (Agent2D aka Helios Base) was written in this language due to its performance. |
| 91 | +Due to the popularity of python in Machine Learning & AI spaces we decided to create a python platform which would be equivalent to Agent 2D. |
| 92 | +However, using python alone was too slow as preprocessing sensor information & tasks such as localization took too long. |
| 93 | + |
| 94 | +For this reason we have split up the code into two segments: |
| 95 | +The data processing section in proxy, which creates a World Model (state), and passes it to python for planning to occur. This repository uses gRPC to pass along the World Model, but there is a sister-repo which is compatible with thrift. |
| 96 | + |
| 97 | +```mermaid |
| 98 | +sequenceDiagram |
| 99 | + participant SS as SoccerSimulationServer |
| 100 | + participant SP as SoccerSimulationProxy |
| 101 | + participant PM as PlayMakerServer |
| 102 | + Note over SS,PM: Run |
| 103 | + SP->>SS: Connect |
| 104 | + SS->>SP: OK, Unum |
| 105 | + SP->>PM: Register |
| 106 | + PM->>SP: OK, ClientID |
| 107 | + SS->>SP: Observation |
| 108 | + Note over SP: Convert observation to State |
| 109 | + SP->>PM: State |
| 110 | + PM->>SP: Actions |
| 111 | + Note over SP: Convert Actions to Low-Level Commands |
| 112 | + SP->>SS: Commands |
| 113 | +``` |
| 114 | + |
| 115 | + |
| 116 | +As seen in the figure, the proxy handles connecting to the server, receiving sensor information and creating a world-model, and finds the action to take via a remote procedure call to a decision-making server, which is this repository. |
| 117 | + |
| 118 | +## Configuration |
| 119 | + |
| 120 | +### RoboCup Server configuration |
| 121 | + |
| 122 | +You can change the configuration of the RoboCup server and change parameters such as players' stamina, game length, field length, etc. by modifying `~/.rcssserver/server.conf`. Refer to the server's documents and repo for a more detailed guide. |
| 123 | + |
| 124 | +### Modifying Proxy & Running proxy and server seperately |
| 125 | + |
| 126 | +If you want to modify the algorithms of the base (such as ball interception, shooting, localization, etc.) you must modify the code of the [proxy repo](https://github.com/CLSFramework/soccer-simulation-proxy). After re-building from source, you can run the proxy by using `./start.sh --rpc-type grpc` in the bin folder of the proxy, and run the gRPC server with `python3 server.py` in this repo's directory. It is highly recommended to launch the python server before the proxy. |
| 127 | + |
| 128 | +You can modify the rpc port by adding the argument `--rpc-port [VALUE]`, where the default is 50051. |
| 129 | + |
| 130 | +## Citation |
| 131 | + |
| 132 | +- [Cross Language Soccer Framework](https://arxiv.org/pdf/2406.05621) |
| 133 | +- Zare, N., Sayareh, A., Sadraii, A., Firouzkouhi, A. and Soares, A., 2024. Cross Language Soccer Framework: An Open Source Framework for the RoboCup 2D Soccer Simulation. arXiv preprint arXiv:2406.05621. |
0 commit comments