Hardware‎ > ‎The Critterbot Robot‎ > ‎

Disco Docs


Basics
  • Disco is a distributed computing platform that provides a method for passing data between black boxes(Components) in different processes or on different computers.
  • Disco is primarily composed of Processes and Components.  Processes (Disco Processes will always be capitalized in this description) are operating system processes, each one can be started from the command line, runs independantly, and is scheduled by the operating system.  Running within a Process there can be zero or more Components.  A Component is the primary module or unit within Disco.  You will be writing and editing Components.
  • Disco uses one master Process, called Control.  Control acts as a nameserver and command center for controlling all other Processes.  Besides these functions, Control is identical to any other Process.  The Control Process is defined by the executable that you run, to start the Control process you run Control.bin.  To start any other Process you run Process.bin.
  • Because all Processes depend on Control, if multiple Processes will be started Control must always be started first.  Each additional Process started connects to Control to get information about what it should be doing, and who it should be talking to.
  • Processes are differentiated by name.  Each Process has a name that is used to define some configuration information and which Components should be run within it.  The Control Process is always referred to by the name Control.
  • Control references an XML configuration file to find information about how things will be configured.  This file allows you to define the different names of Processes, the Components they run, and what Connections are made between them.  This XML file is live, and changes made to it while Control is running are implemented immediately.
  • Connections allow the transfer of data between different Processes.  They are by default TCP network connections, and this is currently the only supported connection.  UDP or shared memory connections may be avaliable in the future.
  • The basic unit of data within Disco is the Drop, or DataDrop.  A Drop is a simple wrapper class which contains some amount and arrangment of data.  This data can by anything (for example, a linked list of Drops, an image file, or just a single int.)  You can specify different types and constructions of Drops for moving different types of data around.
  • Within a Process Drops are contained in Rivers.  Rivers are circular queues unique to each type of Drop.  All Components within a Process have access to the same River structures, and can read and write Drops to the Rivers.
  • When a new Drop is added to the River it immediately becomes available to all other Components in the same Process.
  • Using Connections, the Drops from one Process' River can be shared with any other Process.  This allows Components in different Processes to send and receive data from each other.  Connections are unidirectional since an infinite loop of sending the same Drop back and forth would result otherwise.
  • Components are extensions of the Component class, and may implement any of the Think, Act, Sense, Wake, and Hatch methods as defined by Component.  The Think method is by far the most commonly used.  Act and Sense are used to interact with hardware or files and generally refer to a specific file descriptor (FID.)  Wake allows a Component to exert some control of process sleeping. Hatch allows Components to spawn and destroy other Components.  We will focus on Think here.
  • A Process calls each of its Component's Think methods in order, as defined in the XML.  If one Component's Think method blocks for a long time, perhaps waiting forsome input, all other Components in the Process will not be called until it returns.  Additionally, Drops sent to or from other Processes via Connections cannot be processed until all Component's Think methods have been called once.  This means in general a properly written Think method will not block or take any longer to return than necessary
  • Once a Process has called all of its Components' Thinks, it can be configured to run them again immediatly or wait a certain period of time before running them again.  This is defined in the XML file.
  • Drops are also extentions of the Drop class.  Each Drop has its data (and possibly methods for manipulating the data) and methods for serializing and de-serializing the data over a network connection or as strings.

Compiling
  • The directories that are considered when looking for Components to compile are defined in the Makefile in the top level Disco directory.  It is suggested you add your own directory for your agent code so you can track it with your own repository or whatnot.  The recommended location is in "disco/source/yourdirname".  Add this directory to the Makefile by adding the line "SOURCE_DIRS+=source/yourdirname" with the rest of the SOURCE_DIR definitions.
  • To create your own Component you need to define a .cpp file and optionally (but high recommended) a .h file named for your component.  These should be created in your source directory.  For example, if I want a Component called Bender, I would create a Bender.cpp and Bender.h file in "disco/source/mysourcedir".  By default the makefile will not compile all available Components, you have to specify which ones you want compiled.  To do this, add the name of your component on a seperate line to "disco/make/Component.use".
  • It is easiest to create a Component based on a template.  We have provided the file CritterAgent.cpp and CritterAgent.h in the "disco/source/critterbot" directory.  One option to start is the copy and rename this files to your directory with the name of the Component you would like to create.  You will also need to replace all instances of "CritterAgent" within both files with the new name of the file, so the class name matches the file name.
  • Running "make" from either "disco" or "disco/bin" should now attempt to compile your new Component.
  • If you want to just compile your component type "make Blah.o" or from main, "make source/mysourcedir/Blah.o", or from source, "make mysourcedir/Blah.o"
  • Creating a new Drop follows the same basic steps.
  • Once everything is compiled, all of the Components listed in Component.use are compiled into two large executables, Control.bin and Process.bin, found in the "disco/bin" directory.
Running
  • Control.bin is the master executable, and must be contactable via a TCP connection by all other executables, each of which is run using Process.bin.  Control takes the following flags:
  • "-x " followed by the name of the name of the xml file to use for configuration.  This defaults to looking for a file named "test.xml"
  • "-u " followed by a string with the URL to contact Control on.  Generally Control will automatically discover it's IP address and use this, however there are some instances where it fails and returns localhost.  This will prevent other Processes from connecting correctly.  To override this you can specifiy the IP address of the machine you are on here
  • "-s" followed by nothing tells Control to start connected Process's Components without user input.
  • "-p " followed by a port number.  Processes by default try and connect to Control at the default port.  This overrides the default port, and you will need to specify this option for each Process you want to connect to this instance of Control.  This allows you run multiple copies of Control on one machine and thus run two or more independant instances of Disco which can have different XML files and have no communication with each other.
  • For example "./Control.bin -n robot.xml -u 10.0.1.20" tells Control to use the configuration file robot.xml and that it is running on a computer with the IP address 10.0.1.20.
  • After you have started Control you can start any number of Processes to connect to it.  Processes take the following flags:
  • "-n " followed by the name of the Process that this should be.  This needs to be one of the Process names listed in the XML file.
  • "-u " followed by the URL to connect to Control on.  This can be localhost if Control is running on the same machine.
  • "-p " followed by the port to connect to Control on.  This is only specified if you started Control with -p.
  • For example, "./Process.bin -n UberAgent -u 10.0.1.20"  starts the Process named UberAgent and tries to connect to Control at 10.0.1.20.
  • Processes do not start automatically, unless you specify the "-s" option on Control, each time you connect a process to Control you must type "send" in the console running Control to start any unstarted Processes.  Any changes you make to the XML file should also be followed by typing "send" in Control.
Comments