= Aperios OPEN-R =

Aperios is a proprietary operating system from Sony, and OPEN-R is our interface to the robot.

See also [wiki:AperiosObjects Aperios Objects] for details of how we fit our code into Aperios.

== Overview ==

OPEN-R software is modular and object oriented (not in the C++/Java sense, but the COM/CORBA sense). Processing is performed by multiple objects running concurrently and communicating via interobject communication. Connections between objects are specified in an external description file (stub.cfg). Connection ports in objects are identified by service name. The system layer (access to sensors and actuators) is also implemented by inter-object communication.

An object is similar to a UNIX process in that it is implemented by an executable file and runs concurrently with other objects (N.B. we don't know how the task switching works on AIBO). However, unlike UNIX processes objects have multiple entry points. Objects exchange information using message passing. A message contains a selector and some data; the selector identifies which method of the object to run and the data provides arguments. Objects are internally single threaded - an object can process only one message at a time. Additional messages wait in a queue.

== Inter-object communication ==
When two objects communicate, the side that sends data is called the "subject",  and the side that receives data is called the "observer". (subject --data--> observer) 

When the observer is ready to receive data, the observer sends a "ASSERT-READY" message to the subject. Otherwise, the observer sends "DEASSERT-READY" to the subject. When the subject receives ASSERT-READY from the observer, the subject starts to send data to the observer. After the observer receives this data and is ready to receive the next data, the subject sends ASSERT-READY again.

== Core class ==
A core class is a C++ class that represents an object. Each object should be represented by only one core class.

Characteristics of a core class:
 * A core class inherits from the OObject class. 
 * A core class implements {{{DoInit()}}}, {{{DoStart()}}}, {{{DoStop()}}}, {{{DoDestroy()}}}. 
 * A core class has the necessary number of OSubject and OObserver. Example:
{{{
    OSubject* subject[numOfSubject]; 
    OObserver* observer[numOfObserver]; 
}}}
 * numOfSubject and numOfObserver are defined in def.h that is generated by the stubgen2 command. 

more coming...

== Stub ==
Stub is a specification of OPEN-R object. 
Every OPEN-R object you define, you must have a stub file and usually called stub.cfg. 
Currently, in our rUNSWift architecture, we have four (I think...) OPEN-R objects namely: 
 * vision 
 * actuator
 * wireless
 * GameController
Thus, we have four stub files and they reside in vision, actuatorControl, GameController and wireless directories respectively. 
Each OPEN-R object has several services that can be invoked between objects and each of these services is defined as 

"(Connection name)", (Member function 1), (Member fuction 2) 

* Connection name - The connection name consists of the following items. 
(Object name).(Subname).(Data name).(Service type)

Object Name - Any name you want, but usually the core class name. 

Subname - This is a service name and must be unique. Do not use the same subname that other serivces use. 

Data Name - This is the name corresponding to the data type used in inter-object communication. 

Service Type - S for subject and O for observer. 

* Member function 1 - This member function is called when a connection result is received. 

* Member function 2 - If this service is for observers, this function is called when a message is received from a subject. If this service is for subjects, this function is called when ASSERT-READY or DEASSERT-READY is received from an observer. 

Below is a snippet of stub.cfg in vision directory.
Explanation on this snippet is coming soon. 
{{{
ObjectName : Vision
NumOfOSubject   : 8
NumOfOObserver  : 7

Service : "Vision.SetIndication.int.S", 		null, null
...
Service : "Vision.Sensor.OSensorFrameVectorData.O", 	null, ResultSensor()
...
}}}

== OPEN-R Configuration Files ==

=== OBJECT.CFG ===
This file lists all of the objects that the dog will load and execute.

=== CONNECT.CFG ===
There needs to be a way to interconnect all the objects and their interfaces. These interfaces are defined in each object's respective stub.cfg file. Then by using a connect.cfg file, it will draw links between the interfaces on stub.cfg files.

=== DESIGNDB.CFG ===


== Building the bin file ==

== Some History ==
Currently, rUNSWift has different OPEN-R objects like vision, actuator and wireless. 
However, in 2002 rUNSWift, they only had one OPEN-R object that did everything. 
Since OPEN-R object is single threaded, there was a significant performance slow down in using wireless. 
When the object was handling wireless process (e.g. AIBOs communicating each other), it blocked out all the other requested services like vision and actuator.  
So, M. S. K. told me that 2002 rUNSWift decided not to use wireless at all! (interesting)
Which means AIBOs weren't communicating each other... which also means no team work between AIBOs in 2002? 

Thus, in 2003 or 2004? rUNSWift introduced other OPEN-R objects like wireless... So that when AIBOs communicate via wireless, wireless process won't block other processes, thereby smoothing actuator and vision processes.    

== Note ==
 * The senser data is sent every 32ms (frequency = 31.25Hz)   (open-r::Level2!ReferenceGuilde.pdf)
 * 3 types of data used for communication:
{{{
    OCommandVectorData
    OSensorFrameVectorData
    OFbkImageVectorData
}}}