This page has been created for the AISB Tutorial/Hackathon event, part of AISB2017 at the University of Bath, but may be used by anyone wanting to get practical hands-on experience with reactive planning for robot control.

Before reading this page, please read the Instinct Planner page for background information on reactive planning in general, and Instinct in particular. This page is a quick crib sheet to get you up and running with the various components of the Instinct toolkit, and also the ABOD3 tool for graphical real time plan execution.

Creation and Editing of Instinct plans using Dia

Instinct Plans can be written textually, or more conveniently drawn using Dia. Dia is an open source drawing tool, rather like Microsoft Visio. It has a simple interface to Python, and we have used this to create an export script that will convert an appropriately formatted diagram of an Instinct plan into a textual plan file that can be loaded by the Instinct planner. The Dia interface to Python is not supported on Mac, so you need a Windows PC to get this to work. I have used Dia with both Windows 7 and Windows 10. The full details on how to use Python with Dia are here http://dia-installer.de/howto/python_win32/ . Essentially, these are the steps to enable Instinct Plans to be drawn and exported:

1.  Install Python 2.3 Later versions do not work with Dia, but you can happily have multiple versions installed, and the documentation advises that they do not interfere with one another. The Python download is here http://python.org/ftp/python/2.3.5/Python-2.3.5.exe
2. Download and install Dia for Windows here http://dia-installer.de When installing Dia, make sure that you select the Python plug-in.
3. Copy instinctgen.py from Instinct/extras/ (on Github https://github.com/rwortham/Instinct) to C:\Program Files (x86)\Dia , or wherever Dia is installed on your PC.
4. You can now open a .dia drawing such as DiaPlan3.dia from Instinct-RobotWorld/plans/ from Github at https://github.com/rwortham/Instinct-RobotWorld.
5. To export this to the textual .inst format, simply choose File->Export… and then at the bottom of the export screen choose Determine file type: Instinct Plan Generation (*.inst). This .inst file is human readable in a text editor. All the lines starting // are comments. The remainder are commands for the Instinct planner, and together they load the plan. Note that the export of each plan element is in no particular order, and changes as the diagram is edited.
6. Note that there is currently no import facility to create plan diagrams from a .inst file, therefore the .dia file must be considered the master plan file.

Install and Run the Instinct Robot World

The Instinct Robot World is written in C++, using the Microsoft Visual Studio IDE. The latest code has been produced using Visual Studio Community 2015. However, you do not need Visual Studio to run the executable. As a minimum you need to download the InstinctRobotWorld.exe executable from the root of the GitHub repository and also copy the /plans subdirectory and its contents.

Compiling Instinct Robot World (optional)

Full source is available on Github at https://github.com/rwortham/Instinct-RobotWorld . In order to compile and modify the Instinct Robot World using the Visual Studio C++ IDE, you also need to download the Instinct Planner source files from GitHub at https://github.com/rwortham/Instinct. I generally put these files in C:\Users\[username]\Documents\Arduino\libraries\Instinct as I use the Planner as an Arduino library too. The same source files compile without modification with Visual C++ and the Arduino AVR compiler. You may need to modify the INCLUDE locations within the IDE to pick up the Instinct.h include file. You may also need to update the locations of the Instinct Planner source files so that the IDE can find them.

Basic steps to run Instinct Robot World

Defaults are provided in the editable fields, to help you get going easily.

1. Click Add Robots. This will add 6 robots into the world. They are all in the same location, and each is identified with a single character on the display. You can add hundreds of robots at one time, up to a total of 1000.
2. Click Start. The robots will start moving, making 8 plan cycles per second. The maximum is 1000 plan cycles per second.
3. Use Stop/Step/Reset, change the Ticks/sec and watch the statistics change over time.
4. More robots can be added at any time, either with the same, or with differing plans.
5. When you add the robot(s) you can choose to log the planner processing out to a log file, which will be written to /logs (you will need to create this directory). The checkboxes allow the selection of which events to log. Typically select all of them.
6. Each robot can have two plans (the second monitor plan file is optional). The first plan controls the robot, and the second ‘Monitor Plan’ alters the behaviour of the first plan.
7. You can specify a host file and port for each planner, and this will write the log output over TCP/IP. This can be used with the Instinct-Server, or with ABOD3. By default, both listen on port 3000, and if they run on the same machine, specify localhost as the host name. If you add multiple robots to the world at one time, only the first one created will use these parameters.
8. Disable the dynamic display using the Show World checkbox. The robots continue to operate, but the display of them is suppressed. This gives a performance improvement on slower PCs.

Instinct Server

The Instinct Server is a simple command line Java program, available on Github at https://github.com/rwortham/Instinct-Server. It may be run from the InstinctServer.cmd file. As a minimum you need the InstinctServer.jar file, /cmd and /logs subdirectories and a cmdfile.txt file in the /cmd directory. You also need Java 1.8 or above installed.

1. The program is simply a multithreaded TCP/IP server, and expects connections from either the R5 robot or the Instinct Robot World. When a connection is made to the server, it waits until is receives the text “Robot Ready…”.
2. It then reads cmd/cmdfile.txt and sends the commands in this file to the robot. This file can also contain includes using the @ symbol. This is typically how the plan file is sent to the robot. Lines starting // are comments and are not sent to the robot.
3. The Instinct Server writes the data it receives from the robot to a log file, in the /logs subdirectory. The Instinct Server also slightly modifies the data before writing it to the log file. It replaces the plan element IDs with their textual names, making the file much easier to read. This information is in the plan file.
4. You can also display this data on screen by entering the “!” command. You can type commands at any time and these will be sent to the robot.
5. Finally, type exit to stop the server. If there are still robots connected you may need to use Ctrl+C to kill all the threads still executing in the program.

R5 Robot

Some information on the R5 robot is available here and worth reading if you are interested in creating a new reactive plan for R5. The full source code for R5 is available on Github at https://github.com/rwortham/R5 . A typical plan file is available in /extras/Plan6.dia , and this gives rise to the behaviour of the R5 robot in this video https://youtu.be/sCd1GNJe6Jw . The robot should be available at the Hackathon event to allow you to try out your own plans.

ABOD3

ABOD3 is written by Andreas Theodorou. It is available on Github at https://github.com/RecklessCoding/ABOD3 . Andreas will be at the hackathon to provide support for ABOD3 and also to get feedback as it’s used.

The ABOD3 real time transparency adapter for Instinct receives data over TCP/IP in exactly the same way as the Instinct-Server, however it displays plan execution graphically, rather than just logging it to a file. 

In future, Instinct plans may be able to be created and edited by a later version of ABOD3.

At the Hackathon

At the hackathon event I’d like to explain a little about how to create reactive plans using Dia, and how to run them using the Instinct Robot World. I’m interested in feedback on how easy it is to understand the concepts, and to design, create and debug Instinct plans. We can also move on to creating and modifying plans for the R5 robot.

Visual C++ programmers are welcome to download the Instinct Robot World code and enhance it to create their own senses and behaviours, in addition to designing plans.

Arduino programmers can download Instinct and use it for their own autonomous applications (bring your own Arduino!).