 |
RCL - RoboCLuedo
v1.0
Francesco Ganci - S4143910 - Experimental Robotics Lab - Assignment 1
|
|
RCL - RoboCLuedo
v1.0
Francesco Ganci - S4143910 - Experimental Robotics Lab - Assignment 1
|
Francesco Ganci - 4143910 - Robotics Engineering - A.A. 2021/2022
Documentation:
For a practical point of view on this project,
- See the practical example
This project contains a ROS implementation of the control program of a robot which can play to a very limited and simplified version of the well-known game CLuedo. Here is implemented only the logic structure of the system, which can be easily extended and possiblty "mounted" on a real robot.
A behavioural architecture is implemented here. The robot "moves" among the rooms of a house in order to find who, where, and with what DrBlack was killed. The project also employs artificial intelligence techniques in order to solve the case. The robot interacts with a particular node, called Oracle, which is responsible for giving "hints" to the robot. The oracle knows the solution of the case, and checks the solution proposed by the robot each time it is ready to make a charge. If the proposed solution is correct, the program stops.
The project is distributed into two different packages:
It contains the main part of the architecture. You can configure how it works from the config folder, and test it using the launch files (see below in this document).
This package contains the messages and the services for the project. Please refer to the documentation.
In order to run the project you need to install the followings:
No Py client is required: the client was re-implemented in C++, see ArmorTools in the documentation.
With the above mentioned depts installed, building the project is straightforward:
0. I always recommend to create a clean workspace before downloading the project.
srccatkin_make on the entire workspaceSometimes, for some strange reason, catkin_make gets stuck and doesn't compile the entire workspace. In order to force catkin to compile everythin, there's a script compile.sh attached to this repository. It simply calls catkin for each package of the project.
There are at least two ways to run the architecture.
You can run the entire program from the launch file I provided for you:
Before starting, remember to launch the ROS master:
First of all, you need to set some stuff on the parameter server. You can easily do it from the launch file you can find in robocluedo/config:
Done this, there are a couple of nodes to start. I suggest you to run aRMOR before the other nodes. Don't load anything: the arch. will load everything after starting. You could notice some warnigs: ignore them.
Then, launch the auxiliary nodes. The node cluedo_armor_interface will set up the aRMOR service loading the ontology file you can find in robocluedo/config/cluedo_owl_ontology. This node manages and simplifies the usage of the ontology, and provides services specific for this project.
Now, run the node cluedo_random_room, a simple server which chooses one room among the ones in the list you can find at robocluedo/config/cluedo_items:
Run now the movement controller. This is a stub implementation: it should be replaced with a real movement controller, with no need to alter the interface of the architecture. Actually, it is a blocking service which can also cause the Oracle to send a hint to the robot.
The cluedo oracle is the referee of the game. Its interface should be external to this project: the actual oracle can be easily replaced. The oracle reads three files of items (see the folder robocluedo/config/cluedo_items), and prepares the case, choosing the solution in advance. You can retrieve the solution from the output on the console.
The last node you should run is the robocluedo_main, which implements the FSM, so the center of the architecture. The node makes the whole architecture running: the robot starts to work.
That's all folks!
All the configuration elements are located in the folder robocluedo/config. Here you can find:
parameter.launch which contains all the parameters to be defined before running the architecturecluedo_items containing all the entities for the gamecluedo_ontology containing the base ontology (the file cluedo_ontology.owl) ...cluedo_ontology/last_ontology where the node robocluedo_main, through the interface robocluedo_armor_interface, exports the ontology from the last execution of the robot. For debug purposes, you can inspect them, but first I suggest you to take a look at the documentation about ArmorCluedo and in particular the section "DISCARD HYPOTHESIS" from the example 3 of ArmorCluedo.Here is the structure of the folder config:
The program need three test files:
cluedo_path_where : the path of the file text containing all the PLACEscluedo_path_what : the the path of the file text containing all the WEAPONscluedo_path_who : the path of the file text containing all the PERSONsEach file has a very simple structure: each line corresponds to an item of a given class. No parsing is needed: the program just imports them, reading line per line.
Regarding the ontology:
cluedo_path_owlfile : the path where the base ontology is locatedcluedo_path_owlfile_backup : the path where to export the actual ontologyItems are loaded dynamically into the ontology, i.e. when the Oracle gives to the robot a property containing an item which it hasn't seen before.
Another value is:
cluedo_max_hypotheses : the number of IDs generated by the OracleEach hint has an ID; this lets to simplify the code of the node cluedo_armor_interface, otherwise the robot should assign a ID and expand the hint in a combinatorial way, making the research of complete hypotheses more difficult to execute.
During the development of the application, they are been implemented several nodes which have the only purpose to test parts of the applications. Here is the complete list of the launch files and the type of test performed:
test_armor.launch : the C++ node test_armor.cpp performs a simple reasoning task on the ontology interacting directly with the aRMOR service. It offers many handy functions which simplify the communication with aRMOR: it is meant to be modified and recompiled several times. If you want to alter it, of course you can: please follow the examples.test_armor_tools.launch : the previous test is too much 'direct' and doesn't use ArmorTools neither ArmorCluedo. The node test_armor_tools.cpp offers a more rigorous testing using the C++ client (see the documentation). Unfortunately it is still in Italian (most of the part).test_cluedo_armor_interface.launch : this simple test performs a rapid sequence of operations on cluedo_armor_interface, a simple pattern of reasoning.test_cluedo_oracle.launch : simple test for the hint request in cluedo_oracle.cpp; perform the request of a hint 25 times.test_cluedo_random_room.launch : same pattern as the previous, perform the request of a room for 50 times.test_oracle_plus_interface.launch : joint test between cluedo_oracle and cluedo_armor_tools; the node asks to the Oracle a hint for a number of times, and each time the oracle replies. the hint is given to aRMOR through cluedo_armor_interface. All the features of both cluedo_armor_interface and cluedo_oracle are tested here.Here is a short presentation of the work done in this project.
This is a behavioural architecture without the sense part. Here is the UML diagram of the whole project:
Let's introduce the architecture node by node. If you want to know more about the central node, jump to the next section about the finite state machine.
implementation here
This is a simple node which chooses randomly a place from the PLACEs file. it is used when the robot is searching for clues. It exposes only one service.
implementation here
This is a "stub" node, i.e. it represents a logical role but it does nothing. It represents the act part of the behavioural architecture; it can be replaced with a real movement controller easily.
Note that that the this node has also a channel connected with the Cluedo Oracle. The principle: the robot would receive one hint when it enters in the room, so the movement controller sends a signal every time the robot "reaches" a position. The signal is a message through the topic, which the oracle could accept or not.
implementation here
This node implements a sort of referee for the game. It knows the solution of the case, and can check, through service, the solutions proposed by the node robocluedo_main. Sometimes it can also give hints, i.e. propositions which the robot collects and associates in order to formulate a possible solution to be checked. The solution could be incorrect, so every time the robot has a solution, it must check it using a service of the oracle.
The solution is generated in this way. First of all, the oracle chooses the ID of the solution. Then, after read the item files, the oracle bulds a shuffled list of hint items. For each ID, the node generates from zero to MAX_SIZE_HINT. It should be possible (but very seldom) that one ID has not related hints.
implementation here
The node implements a simplified and specific interface which lets other nodes to work with aRMOR without using direct calls to the aRMOR service.
The interface has four services (all the names of the services are under **/cluedo_armor**):
implementation here
This class implements the most common mid-level methods for dealing with aRMOR without direct calls to the service. See the implementation for further details, and in particular the examples for more details.
Other useful documents:
implementation here
The class extends the class ArmorToold, adding more handy specific mid-level methods for working with CLuedo individuals, properties and hypotheses. It adds also some workarounds needed in order tomake reliable the operations on aRMOR and overcoming some issues in commands DISJOINT and REMOVE. Please refer to the documentation if you want more details about all these aspects.
Here are some useful documents:
The python ROS node robocluedo_main implements the behaviour of the robot. The ROS framework SMACH is employed here in order to implement the Finite State Machine.
Here is the FSM diagram:
Note that the robot could receive a message each time it enters in the room, only one message because the buffer is actually a single variable instead of a list of hints (see the todo list in the documentation). The behavour of the robot can be summarized as follows:
Clearly it is a oversimplified game dynamic: the real CLuedo doesn't work in this way...
In order to show you how the project works I think it is more useful to present you a possible log from the project, using this test configuration:
You can find both the log and the end ontology from the folder /logs/test_20211109. In this example, the program was launched using the main launch file, that suppresses some logs, for example the ones from the cluedo_armor_interface. Only the logs belonging to the oracle and the robocluedo_main node are visible, since I think they're the most relevant nodes in the architecture.
Before starting, all the secundary components start running, and the config files are loaded.
In particular the Oracle prepares the case and chooses the solution. In this case, the generated solution has ID zero, and we know what is from the log:
The main node waits for the services and the topics, until all the nodes are ready.
When all the nodes are ready, the robot can start moving.
Here is a representation of what happened up to now:
At the beginning, the robot has no informations: the ontology is empty, so it chooses randomly a room asking to the node cluedo_random_room in search of clues. Each time it enteres in one room, it receives at most one hint, or also nothing in some cases. The robot keeps behave in this way until at least one hypothesis becomes complete. In the following piece of log, the typical job of the robot while is looking for clues:
A representation of what is happening in the common cycle above mentioned. The worst case scenario is assumed.
In the example, there are no wrong charges unfortunately, but it is reasonable to suppose that, on a more complex setup (many elements in the list, many IDs, ...) the robot could fail sometimes. Here is the final piece of the log, which shows how the robot behaves when it is ready to present a charge.
If the number of hypotheses would have been 2, the robot have been choosen randomly from the available ones. Here there's only one hypothesis, and it will be so every time because the robot "thinks" every time it enters in a room, and at most one hint can be sent to the robot: if the oracle would send more than one hint at time, the robot have had ore elements to elaborate.
The actual position is not the one mentioned in the hypothesis, so the robot first moves towards the room, and when is there, makes the charge. The solution is correct, so the program ends.
The last part of the log can be resumed with this diagram:
This was a very simple example, aimed at make you understand how this project works. Inside the directory logs you can find some more interesting examples with the default setup.
The robot works in a well-known space, at least from the logical point of view. Maybe the space would be unknown, but the robot knows in advance at least the names of the rooms.
The oracle sends at most one hint each time the robot enters in a room. For multiple hints, it is necessary to extend the buffering from a single-var buffer type to a list type. The changes to do are few, and the logic can work fine also relaxing this working condition.
In this implementation the oracle sends in a precise instant the hint, but this is not a constraint: the oracle can send the hint when it wants, because there's only one state which needs to check the state of the buffer. If the oracle would be replaced with another one which doesn't use the */hint_signal* but publishes the message in every instant, the architecture should work well.
The ID of the hypothesis is provided by the oracle. Modifying this working hypothesis requires to change a bit the node robocluedo_main, but also reimplement the algorithm for adding the hypotheses in the ontology, so non-trivial changes to cluedo_armor_interface. It should be implemented an algorithm which, given some properties, can generate all the hypotheses which contains those properties. Providing the ID instead simplifies the workflow, because the interface already knows how to organize the hypotheses, so the problem is reduced to find the right ID among the ones provided by the oracle.
You can find some of the possible improvements directly in the documentation of the code; see the section todo.
About the architecture:
About how the game is managed:
About the Knowledge Base:
About the quality of the code:
Designed and developed by Francesco Ganci, S4143910
1.8.17