/NRS

Neural Robotic System

Primary LanguageJavaGNU General Public License v2.0GPL-2.0

Neural Robotic System
=====================

NB: This is a recovered archive of some code used to run neural
simulations to control Khepera and Koala robots from the early 2000s,
released thanks to Tim Lukins, who said it was a shame no-one could
find it any longer no matter how useless it might be!

History
-------

The need for this program arose in the 1990's --- Barbara Webb, Tom
Scutt and others wrote software to carry out neural simulations for
modelling cricket phonotaxis. The code was completely rewritten
between 2000 and 2002 by Richard Reeve to be a more general purpose
tool for neural simulation, designed to connect to robots and sensors
for realtime control. It also acquired a scripting language to allow
runtime modification of networks to maximise ease of use. This was the
first Neural Robotic System (NRS).

The final iteration of this code was v1.2 which included what is
described below as NRS.nsim, NRS.tui, NRS.realtime, NRS.robot and
NRS.tracker. Initial versions of NRS.grapher and NRS.router were
developed at this time also, though they were not fully integrated
into the system. This system remains fully functioning, but various
problems were identified which would be difficult to resolve with the
current codebase, not least the idiosyncratic communication mechanisms
which combined with the lack of a design document to cause
difficulties for others to add extra functionalities to the codebase.

In 2003 it was decided to redesign the system, taking the best
elements of the old, but putting in a new properly structured
framework to allow components to be added with relative ease by other
programmers; this was partly because more programmers were available
to work on the code, and partly because desirable features were
discovered which it would have been difficult to add to the old system.

The communication mechanisms for the system evolved from discussions
over many years at the Telluride Neuromorphic Engineering workshop on
Address Event Representation and how to extend it.

Documentation
-------------

See the documentation in doc/ for full details on the system.

Preamble
--------

This software is free software released on the GNU General Public
License - see COPYING for license details. Whilst you are under no
further obligations than those outlined in the license, we would
greatly appreciate 3 things:

- Let us know if you use the code

- Let us know about any bugs, and return any bug-fixes and
  improvements you may make to us (at some point we intend to put the
  code on a public site to make this simpler)

- If you undertake research using this code and write a paper, we
  would appreciate being acknowledged - the NRS software developers in
  the Cricket Lab at the Institute of Perception, Action and
  Behaviour, University of Edinburgh

INSTALLATION
------------

The first time you extract the code from the git repository you need to run:

aclocal
glibtoolize
autoheader
automake --add-missing
autoreconf

This only needs to be done after you first check out the git code. For
other times when the makefiles need to be updated, just use
autoreconf. You will very likely have to install some packages at this
point. You also need to set the envirnoment variable XERCES to point
to the xercesImpl.jar file containing the Xerces Java implementation.

Then choose an installation directory and add <installdir>/bin to your
PATH enviroment variable, e.g. in your .bashrc add:

export PATH=$PATH:<installdir>/bin

To build the code you must:

-- create an object directory and enter it:

mkdir <objdir>
cd <objdir>

... if you've changed the Makefile.am file anywhere:

cd <srcdir>
autoreconf

... if you haven't run configure before:

cd <objdir>
<srcdir>/configure --prefix=<installdir> --disable-static

-- anyway:

cd <objdir>
make install

N.B. after building the documentation is available as:
<installdir>/share/nrs-2.0-alpha/doc/NRS.pdf

-- to run the code:

NRS.gui
NRS.component
NRS.nsim to run the component with the nsim plugin loaded, or
NRS.component nsim

-- or to get csl output from a component:

NRS.nsim --csl
NRS.component --csl nsim
NRS.component --csl libnsim.so

Compiling the Camera Tracking
=============================

By default the camera tracker component is not built when NRS is
built. To enable it, use the option --enable-camera when executing the
configure command.

Currently the camera tracker requires two external libraries be present
in order to compile successfully. These are ccvt and OpenCV. Versions
which have successfully worked previously are:

 * ccvt-0.3.tar.gz 
 * OpenCV-0.9.5.tar.gz

These should be available on the Internet somewhere, but also from the
site from which NRS was obtained.

To successfully build NRS with the camera tracking component, you will
need to do:

1. Obtain and install the above source code packages for ccvt and OpenCV

2. Compile these two libraries, and install locally

3. Update your OPENCV_LIBDIR, OPENCV_INCDIR, CCVT_LIBDIR and
   CCVT_INCDIR environment variables to reflect the installation paths
   you chose for each library if they are non-standard and configure
   the NRS sources, as indicated above, but including the
   --enable-camera option.

   Example:

  > OPENCV_INCDIR=/disk/cricketlab/include
  > OPENCV_LIBDIR=/disk/cricketlab/lib
  > CCVT_INCDIR=/disk/cricketlab/include 
  > CCVT_LIBDIR=/disk/cricketlab/lib

  > configure --prefix=/home/richardr/install --enable-camera

4. Continue building NRS as normal, i.e., make, make install, etc.