Skip to content

Commit dbaa908

Browse files
dsmitsdsmits
committed
Added quickstart
1 parent d2677c0 commit dbaa908

File tree

3 files changed

+148
-0
lines changed

3 files changed

+148
-0
lines changed

‎docs/assets/orchestrator_ui.png‎

155 KB
Loading

‎docs/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,11 @@ from the [LARA group](https://lara.uni-greifswald.de/team/) at the University of
99

1010
The vision is to cover all steps of laboratory work in a uniform framework with standardized communication protocols and data formats (like SiLA2, AnIML).
1111

12+
## Target Audience
13+
14+
People who have a robotic arm with several devices they can access via SiLA (or at least python) and look for a
15+
framework do describe, orchestrate and schedule workflows on these devices. Some programming skills are necessary.
16+
1217
## The LARA workflow
1318
LARA tries to cover all aspects of a common laboratory workflow, starting from the planning of the experiments until the final presentation of the results.
1419

‎docs/quickstart.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Quickstart
2+
## Simulated example
3+
The fastest way to try out the LARA suite is by running the simulated example provided by the
4+
[adaptation template](https://gitlab.com/OpenLabAutomation/adaption-template).
5+
6+
There are two ways to run the example: using Docker or running it directly with Python.
7+
8+
## Cloning the repository
9+
Whether you choose to run the example with Docker or Python, you first need to clone the repository:
10+
11+
```bash
12+
git clone https://gitlab.com/OpenLabAutomation/adaption-template.git
13+
cd adaption-template
14+
```
15+
16+
## Running with Docker
17+
Running the example with docker is straightforward, but it does require that you have the
18+
[Docker Desktop](https://docs.docker.com/get-started/get-docker/) or
19+
[Docker Engine](https://docs.docker.com/engine/install/) installed on your machine.
20+
21+
To run the example with Docker, go to the root directory of the cloned repository and run the following command:
22+
23+
```bash
24+
docker-compose up
25+
```
26+
27+
## Running with Python
28+
First, use your favourite tool to create and activate a new python environment with python 3.11 or higher.
29+
For example with pyvenv on linux:
30+
```bash
31+
python -m venv labautomation
32+
source labautomation/bin/activate
33+
```
34+
3. Install all necessary packages:
35+
- to install all mandatory dependencies run:
36+
```bash
37+
pip install -r requirements.txt -e .
38+
```
39+
- to also install the example sila servers (necessary for the demo examples to run) add:
40+
```bash
41+
pip install -r requirements_servers.txt
42+
```
43+
- to also install requirements for stronger scheduling algorithms add:
44+
```bash
45+
pip install -r requirements_mip_cp.txt
46+
```
47+
4. Install and set up the database
48+
49+
Installation: Run
50+
```bash
51+
git clone https://gitlab.com/OpenLabAutomation/lab-automation-packages/platform_status_db.git
52+
pip install -e platform_status_db/.
53+
```
54+
Setup: Run and follow the instructions to create an admin login to django. On windows you will have execute the steps manually.
55+
56+
```bash
57+
bash scripts/init_db.sh
58+
```
59+
60+
Fill the database: Run
61+
```bash
62+
python scripts/add_lab_setup_to_db.py
63+
```
64+
This adds the lab setup as described in platform_config.yml to the database.
65+
Rerun this script after you customized the config file.
66+
67+
## Startup
68+
Call from different console tabs
69+
70+
**Option 1:** In gnome terminal you could start all four of the following services in different tabs by running
71+
72+
```bash
73+
bash scripts/run_services.sh
74+
```
75+
76+
**Option 2:** Otherwise use individual commands (remember activating the virtual environment):
77+
78+
To start the scheduler:
79+
```bash
80+
labscheduler
81+
```
82+
To start the django database view (optional). If you changed directory, adapt the path:
83+
```bash
84+
run_db_server
85+
```
86+
To start the orchestrator:
87+
88+
```bash
89+
laborchestrator
90+
```
91+
92+
To start demo servers:
93+
```bash
94+
start_sila_servers
95+
```
96+
97+
## Usage
98+
You can access the GUI for different components:
99+
- database of present labware at [http://127.0.0.1:8000/job_logs/present_labware/](http://127.0.0.1:8000/job_logs/present_labware/)
100+
- orchestrator at [http://127.0.0.1:8050/](http://127.0.0.1:8050/)
101+
- the human interaction sila server: [http://127.0.0.1:8054/](http://127.0.0.1:8054/)
102+
- view and manual control of the robotic arm: [http://127.0.0.1:8055/](http://127.0.0.1:8055/)
103+
104+
To see how the example servers are controlled from the orchestrator, go to the the orchestrator GUI and load and start one of the
105+
example processes.
106+
- GreeterTest: Sends a Hello-World to the sila2-example-server
107+
- MoverTest: You can view the robots movements in the roboter GUI
108+
- HumanTest: you will have to finish the tasks in the human interaction GUI
109+
- InterestingExample: A more complex workflow with runtime decisions based on human interaction
110+
111+
<figure markdown="span">
112+
![Orchestrator UI](assets/orchestrator_ui.png)
113+
<figcaption>Orchestrator UI</figcaption>
114+
</figure>
115+
116+
117+
118+
### Loading and running a process
119+
120+
1. Go to the left dropdown menu and choose a process to load.
121+
2. Click on "Load Process"
122+
3. The corresponding workflow graph should appear below. You can zoom in/out and move it. Clicking on nodes dumps its
123+
data structure as string into the textfield above (you might have to move the graph a bit down, so it gets visible).
124+
4. Your loaded process should appear in the second dropdown menu. Choose it.
125+
5. Click on "Add Containers to DB". This creates entries for all labware in that process in the positions described in
126+
the process in case there isn`t already labware. Existing labware is considered to belong to that process. You can
127+
see all present labware in the database view which updates automatically.
128+
6. (Optional) Click on "Schedule Process" to get a predicted schedule. It will appear at gantt chart.
129+
7. Click on "Start Process". This will update the schedule and will execute steps accordingly.
130+
You can monitor the progress in the orchestrator GUI and the labware movements in the database view.
131+
132+
### Things to observe during the process
133+
While the process runs you can observe different features of our framework.
134+
135+
1. Live updates of the process in the orchestrator:
136+
1. The gantt chart has a moving bar of where in time you currently are
137+
2. Process step nodes in the graph turn to yellow while they are being executed and to green when they are finished. Pink means there was an error.
138+
3. Labware is shown by barcode in the gantt chart as soon as a barcode is read/assigned
139+
2. Live updates of the database
140+
1. In the database view which auto-reloads all labware is listed with barcode ans current position
141+
2. You can check and manipulate in the [admin view](http://127.0.0.1:8000/admin/) of the database what the results, duration, and starting times of which steps were and which labware was involved. The credentials are the ones you chose during the installation process for superuser.
142+
143+

0 commit comments

Comments
 (0)