Skip to content

Commit

Permalink
Outline readme file
Browse files Browse the repository at this point in the history
  • Loading branch information
@Dale-Koenig
Dale-Koenig committed Mar 10, 2023
1 parent 5a92d86 commit 0923419
Show file tree
Hide file tree
Showing 6 changed files with 96 additions and 151 deletions.
247 changes: 96 additions & 151 deletions supplementary/alica_ros1/alica_ros_turtlesim/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Turtlesim Tutorial
# Turtlesim Tutorials

## 1. Overview

This tutorial is an extension of the [turtlesim ROS package](http://wiki.ros.org/turtlesim). By following this tutorial, you will learn
This collection of tutorials is an extension of the [turtlesim ROS package](http://wiki.ros.org/turtlesim). By following these tutorials, you will learn

- some of the core concepts of the ALICA language
- how to achieve multi-agent collaboration with the ALICA framework
Expand All @@ -13,216 +13,161 @@ In this tutorial, you will create an application as shown in the picture below.

## 2. Prerequisite

It is assumed that you are running the Ubuntu 20.04.5 LTS. these tutorials may work on other distributions but may require additional work or cleverness.

You need to be familiar with following topics and tools:

- [ROS Noetic](http://wiki.ros.org/noetic/Installation/Ubuntu)
- [catkin_tools](https://catkin-tools.readthedocs.io/en/latest/installing.html)

## 3. The ALICA Language - Basics and Core Concepts
These tutorials will assume you have a working and configured ROS workspace and are able to build ros packages.

We will only give you a brief explanation on the ALICA core concepts. For the interested reader, we recommend to consider the [documentation](https://rapyuta-robotics.github.io/alica/) of the ALICA framework for more detailed information.
Begin by cloning the alica repository into your workspace and building the turtlesim package and its dependencies

### Plan
```
cd ${CATKIN_WS}/src
git clone https://github.com/rapyuta-robotics/alica.git
apt-get update
apt-get install -y python3-catkin-tools libboost-all-dev
rosdep install -y --from-paths . --ignore-src --skip-keys='rclcpp ament_cmake' --rosdistro noetic
catkin build alica_ros_turtlesim
source ${CATKIN_WS}/devel/setup.bash
```

A plan is a state machine in tree structure. Plans can include plans and states and each state can include `Behaviour`s. The ALICA engine assigns entrypoints of the plan tree to the agents, e.g., robots based on `Role`, `Task`, `Constraints` and `Utility function`.
The ALICA engine manages state transitions based on the developers code. The developer can create plans using the ALICA plan designer.
Additionally, you will need to set up the ALICA plan designer. However, lets start out by running some of the tutorials.

### Behaviour
## 3. Running tutorials

The developer can write robot behaviours in C++ for each state. In this tutorial, there are the `Teleport2RandomPosition`, `GoTo` etc. behaviours.
The turtles are teleported to random position with `Teleport2RandomPosition` and they go to their target position with the `GoTo` behaviour.
Make sure you have build

### Role
```bash
cd catkin_ws
source /opt/ros/$(ls /opt/ros)/setup.bash
catkin build alica_ros_turtlesim
source ./devel/setup.bash
```

A role is a task preference of the agent and it describes physical difference among agents , e.g., differences between a robotic arm and an AGV. In this tutorial all agent have same role: `Turtle`
For each tutorial, you need to first launch the turtlesim environment

### Task
`roslaunch alica_ros_turtlesim env.launch`

A task is assigned to an agent based on the `Role` of that agent and based on the `Utility function` of the plan. A task identifies an entry point of a state machine. The ALICA engine realises multi-agent collaboration by assigning tasks to agents. In this tutorial, there are the `Leader` and the `Follower` task. One turtle is assigned the `Leader` task and it moves to the centre. The other turtles are assigned the `Follower` task and they align in a circle.
The environment is a simulator node allowing us to spawn and visualize turtles, but to control the turtles we need to launch an alica application.
Tutorial applications can be launched with:
`roslaunch alica_ros_turtlesim turtle.launch master_plan:=<TUTORIAL_NAME> turtles:=<NUM_TURTLES>`

### Constraints
The master_plan argument tells the ALICA application which plan to use as the master plan.
Each tutorial has its own master plan.
We will learn more about this when actually going through the tutorials.

Developers can set constraints to plans. The ALICA engine can solve constraints and return corresponding answers. In this tutorial, the turtles align in a circle defined by distance constraints.
### 3.1 RotatingTurtleTutorial

### Worldmodel
This is a basic application where a ALICA controls a turtle to rotate in place.
Make sure you have the simulation running, and launch the alica application with

The world model represents the model of the world from the perspective of an agent. Further, the world model can be an interface between the ALICA engine and other software, e.g., ROS and lower API.
`roslaunch alica_ros_turtlesim turtle.launch master_plan:=RotatingTurtleTutorial`

![coreconcept](doc/coreconcept.png)
You should see a turtle rotating in the center of the screen as below:

## 4. Setup of the Catkin Workspace
TODO (picture)

We need to create a catkin workspace by executing the following steps in a terminal.
### 3.2 MoveSequenceTutorial

1. Check out the required repositories:
In this tutorial the turtle will move to the four corners of the map in a sequence.
Make sure you have the simulation node running, and launch the alica application with

```
mkdir -p catkin_ws/src
cd catkin_ws/src
git clone https://github.com/rapyuta-robotics/alica.git
```
`roslaunch alica_ros_turtlesim turtle.launch master_plan:=MoveSequenceTutorial`

2. Remove existing turtlesim files. You will reproduce these files (You can jump to step 8. "Build and Run" for testing application before deleting the files):
TODO (picture, or ideally gif)

```
cd src/alica/supplementary
rm -r alica_ros_turtlesim/etc/
```
Moreover, in this tutorial a topic is available to tell the turtle to change behavior.
The turtle also can do the rotate behavior from the previous behavior.
Publishing on the turtle's `rotate` topic will toggle the turtle to rotate in place instead.

## 5. Setup of the ALICA Plan Designer
`rostopic pub turtle1/rotate std_msgs/Empty "{}"`

The ALICA plan designer is a user interface to design applications with the ALICA framework.
Publishing on the `move` topic will then toggle the behavior back so that the turtle moves between corners.

### 5.1 Start the ALICA plan designer by following steps
`rostopic pub turtle1/move std_msgs/Empty "{}"`

The Plan Designer is a web application and can be started by using docker-compose.
When toggling, you may notice that the turtle always starts from the bottom left corner regardless of how far it proceeded before rotating.
This will be explained more in the tutorial.

For starting the Plan Designer, use the docker-compose file placed in alica/supplementary/alica_designer_runtime/
by navigating into the folder and executing the following command:
## 3.3 RandomMoveTutorial

```
docker-compose up
```
In this tutorial the turtle will continuously choose a random point on the map, move there, then pause for a short period of time before choosing a new random point and repeating.
We run this in the same way as with the previous tutorials, but lets spawn more than one turtle this time

You can open the Plan Designer with a browser of your choice by visiting the url
http://localhost:3030.
`roslaunch alica_ros_turtlesim turtle.launch master_plan:=MoveSequenceTutorial turtles:=3`

When you start the Plan Designer the first time, its main window should look like this:

![Empty Plan Designer](doc/Empty-PlanDesigner.png)

## 6. Create the Tutorial Plans with the Plan Designer

In this section, you will create plans using the ALICA plan designer.

### 6.1 Create the TaskRepository
TODO: picture/gif

1. In the top right corner, click on "More" and select "Task".
2. Go to the tab "Task Repository", enter `TaskRepository` as the name of your
TaskRepository and click on "Create New".
3. Repeat step 1.
4. In the tab "Task", enter `DefaultTask` for the Task Name, select the TaskRepository `TaskRepository` in the
drop down menu and click on "Create New".
## 3.4 FourCornersTutorial

### 6.2 Create the Master Plan
This tutorial requires multiple turtles to be meaningful, and is meant to be run with four turtles
Each turtle will try to go to one corner of the map.
The corners are not fixed.
ALICA communication ensures that each turtle goes to a different corner.
Additional turtles (beyond 4) will fail to assign to a turtle and will sit in place instead.

![master_plan](doc/master_plan.png)
The turtles can be launced with

1. Click on the menu button "Plan" in the top right corner. This will open a window
for creating a new plan on the right side of your browser window.
2. Enter 'Master' as the plan name and check the Master Plan checkbox at the bottom.
3. Set the frequency of the plan to 0.
4. Set the library name to libalica-turtlesim (Note: for all alica elements fill in the library name as libalica-turtlesim with the exceptions being:
Conditions- All(Any)Child(Success)Failure should have library name as alica_standard_library & the behaviour WaitForTrigger should have library name as libalica-ros-utils)
5. Click on "Create New" to create the Master Plan.
`roslaunch alica_ros_turtlesim turtle.launch master_plan:=FourCornersTutorial turtles:=4`

On the top left you will see a tab for your newly created Master Plan.
TODO: Randomize start locations using TeleportToRandomPosition behavior, then use utility function to make turtles go to the closest corner, so that we can see that each turtle will sometimes go to a differnet corner

6. Add two states and set their names to `SpawnTurtle` and `Simulation`.
7. Add a transition from `SpawnTurtle` to `Simulation`
TODO: picture/gif, but maybe we finalize behavior first.

1. Hover over the state `SpawnTurtle`.
2. Click and hold while your cursor is on the plus symbol inside the circle appearing
at the top of the state.
3. Drag your mouse to the `Simulation` state. Let go of your mouse when your cursor is on the plus symbol
inside the circle appearing at the top of the state `Simulation`.
4. Select the transition from `SpawnTurtle` to `Simulation`, press delete to delete the generated condition and create a new one.
5. Select the `Condition` icon on the top right corner to create a new condition & fill in the details
6. Drag the condition to the transition that it needs to be attached to
## 3.5 SurroundLeaderTutorial

8. Create an entrypoint. Select `DefaultTask` as a Task and click on "Select".
9. Connect the entrypoint with the `SpawnTurtle` state.
10. Set the "Minimum Cardinality" of the entrypoint to 1 and the "Maximum Cardinality" to 2147483647.
11. Similarly create the other plans, behaviours & conditions as shown in the figure
In this tutorial one turtle will decide to be the leader and move to the center.
The other turtles will attempt to make an evenly spaced ring around the leader.
The turtles can be launched with

### 6.3 MakeFormation plan
`roslaunch alica_ros_turtlesim turtle.launch master_plan:=FourCornersTutorial turtles:=5`

![make_formation](doc/make_formation_plan.png)
Feel free to try launching with more turtles (but be careful not to kill your CPU).

1. Create the `MakeFormation` plan in the same way as the Master plan
2. Create two states `Move2Center` and `AlignCircle`.
3. Create two entrypoints with new tasks `Leader` and `Follower`.
4. For the Leader entrypoint, select it and set the value of "Minimum Cardinality" and "Maximum Cardinality" both to 1.
5. For the Follower entrypoint, select it and set the value of "Minimum Cardinality" to 0 and the value of "Maximum Cardinality" to 2147483647.
6. Connect the `LeaderTask` Task-Entrypoint to `Move2Center` and the `FollowerTask` Task-EntryPoint to `AlignCircle`.
7. Create the `GoTo` behaviour with a frequency of 30 and add it to the `Move2Center` state and the `AlignCircle`.
8. Select the `MakeFormation` plan and add a RuntimeCondition with the name `CircleRuntimeCondition`.
9. Click on the edit button of the CircleRuntimeConditon, select the Quantifiers tab.
10. Choose `MakeFormation` as the "Entity Name". Enter `x` and `y` separately into the "Sorts" field
and click on "Create New".
11. Close the edit window of CircleRuntimeConditon.
## 4. Setup of the ALICA Plan Designer

### 6.4 Simulation plan
Now we want to try implementing these tutorials ourselves, but first we need to setup the plan designer.

![Simulation](doc/Simulation.png)
The [ALICA Plan Designer](https://github.com/rapyuta-robotics/alica/tree/devel/supplementary/alica_designer_runtime) is a user interface to design applications with the ALICA framework.

1. Create the Simulation plan state machine as shown in the figure above by following the a similar procedure as outlined above for other plans
2. Additionally, in the Simulation plan, select Blackboard in the right bottom menu. Click on setup blackboard. A blackboard is essentially a data store for plans/behaviours & can be used to pass data from parent to child or child to parent via key mapping
3. Add 2 blackboard keys: `join_formation_topic` & `leave_formation_topic` as shown in the figure below

![Blackboard setup](doc/blackboard_setup.png)
The Plan Designer is a web application and can be started by using docker-compose.

4. Select the `WaitForTrigger` behaviour attached to the `WaitForTrigger` state by clicking on it & setup the blackboard for the behaviour in the same way
5. Add a single key called `topic` with type std::string & access type as input. Close the window
6. Select the table like icon next to the `WaitForTrigger` behaviour name & setup the blackboard key mapping from `Simulation` plan (parent) to `WaitForTrigger` behaviour (child)
7. Map the key `join_formation_topic` in `Simulation` plan to the `topic` key in the `WaitForTrigger` behaviour
8. This is an example of passing parameters from parent to child. Essentially, here the Simulation plan passes the ROS topic name on which the `WaitForTrigger` behaviour should listen for the trigger (user input). The trigger in this case is publishing an Empty msg on the join_formation_topic topic
9. Since `WaitForTrigger` behaviour is attached to 2 states in this plan, the key mapping needs to be setup for both instances. For the instance attached to the `MakeFormation` state, map the `leave_formation_topic` key to the `topic` key
### 4.1 Starting the plan designer

### 6.4 Create the RoleSet
Navigate to alica/supplementary/alica_designer_runtime/ and execute the following command:

1. In the top right corner click on "More" and select "Role".
2. Select the "Roleset" tab and create a RoleSet with the name `RoleSet` and check the
'Default Role Set' checkbox.
3. Repeat step 1. and create a role with the name `Turtle`. Select `RoleSet` as your Role Set.
4. Go to the tab `Task Priorities`, click on `Apply Task Priority`. Select the task `Follower` and set the
priority to 0.1.
```
docker-compose up
```

## 7. Logic
You can open the Plan Designer with a browser of your choice by visiting the url
http://localhost:3030.

The logic for the plans, behaviours, conditions & constraints is implemented as part of 3 libraries -
When you start the Plan Designer the first time, its main window should look like this:

1. alica_standard_library: contains utility conditions that can be reused in different alica applications
2. libalica-ros-utils: contains a utility behaviour that is used to demonstrate its reuse in different alica applications
3. libalica-turtlesim: contains the plans, behaviours, conditions & constraints used specifically by the application
![Empty Plan Designer](doc/Empty-PlanDesigner.png)

The alica engine loads the implementation of these elements through dynamic loading & creator classes. Eg. A behaviour
is implemented as a class derived from BasicBehaviour defined in the engine & the engine creates instances of this class as required by using the DynamicBehaviourCreator. This creator makes use of a factory method exported by the library to create the class instance. The export & import of
the symbols is done using the boost dll library. Have a look at the code to see how to export plan, behaviour, condition & constraint implementations
### 4.2 (Optional) Github integration

## 8. Build and Run
The ALICA plan designer can be connected to your github account to allow importing from or exporting directly to github branches.

### 8.1 Build
More instructions are available in the plan designer's readme.

follow the standard ros build step.
## 5. Tutorials

```bash
cd catkin_ws
source /opt/ros/$(ls /opt/ros)/setup.bash
catkin build alica_ros_turtlesim
source ./devel/setup.bash
```
Each tutorial depends on having done the previous tutorials.

### 8.2 Run
It may be possible to skip, but only if you know what you are doing.

Run application with roslaunch. video
[Tutorial 1: RotatingTurtleTutorial](docs/rotating_turtle.md)

- Launch turtlesim
`roslaunch alica_ros_turtlesim env.launch`
- Turtle node (you can launch multiple turtles by setting the `turtles` launch arg)
`roslaunch alica_ros_turtlesim turtle.launch turtles:=2`
- Make formation by asking any number of robots to join the formation
`rostopic pub turtle<x>/join_formation std_msgs/Empty "{}"`
where x is the turtle number
- Can ask a robot to leave the formation using
`rostopic pub turtle<x>/leave_formation std_msgs/Empty "{}"`
where x is the turtle number
[Tutorial 2: MoveSequenceTutorial](docs/move_sequence.md)

## 9. Troubleshooting
[Tutorial 3: RandomMoveTutorial](docs/random_move.md)

### 9.1 Unknown quantifier type encountered
[Tutorial 4: FourCornersTutorial](docs/four_corners.md)

If you get the following error message when starting a turtle
`Unknown quantifier type encountered!`, have a look at the
file `etc/plans/Move.pml` and make sure the value of the field
`quantifierType` is set to `"all"`.
[Tutorial 5: SurroundLeaderTutorial](docs/surround_leader.md)
Binary file removed supplementary/alica_ros1/alica_ros_turtlesim/doc/coreconcept.png
View file
Binary file not shown.
Binary file removed supplementary/alica_ros1/alica_ros_turtlesim/doc/plan-designer_project_config.png
View file
Binary file not shown.
Binary file removed supplementary/alica_ros1/alica_ros_turtlesim/doc/plan_designer_config.png
View file
Binary file not shown.
Binary file removed supplementary/alica_ros1/alica_ros_turtlesim/doc/roleset.png
View file
Binary file not shown.
Binary file removed supplementary/alica_ros1/alica_ros_turtlesim/doc/runtime_condition.png
View file
Binary file not shown.

0 comments on commit 0923419

Please sign in to comment.