QG4/lib/openjaus

RELEASE NOTES: OpenJAUSv3.3 (07/10/08)

==========================================



OpenJAUSv3.3 beta is an open source implementation of the JAUS Reference

Architecture Version 3.3. The latest code, documentation and support groups 

are available at the OpenJAUS web site:  http://www.openjaus.com/.



This release contains the following projects:



libjaus:		A C99 compliant library that contains JAUS constructs, data 

				types and messages.

libopenJaus:	A C/C++ library containing a runtime JAUS node manager library,

				node manager communication interface, and component framework 

				library.

ojNodeManager:	The OpenJAUS node manager executable with text interface

ojVehicleSim:	A collection of JAUS components that work together to simulate

				a JAUS ground vehicle subsystem. These components provide a set

				of services that are commonly used in real ground vehicle

				implementations.



If you experience problems in compiling or developing with this code, please

read the tutorials and online FAQ before contacting the OpenJAUS development

group. Please attempt to locate where the problem exists and determine how the

problem can be replicated before seeking additional support. Code patches can be

uploaded at the OpenJAUS web site: http://www.openjaus.com.





Target Operating Environment:

-----------------------------



	This software is designed to be cross platform compatible. The code base has 

been tested on a variety of operating systems and development environments including: 

Linux (Ubuntu & Fedora Core) w/gnu toolchain, Mac OS X w/gnu toolchain, and Windows w/MS 

Visual Studio. All test machines have been little endian byte order based. The libjaus 

library is C99 compliant and should be compatible with any standard C compiler for any 

processing platform. The libopenJaus library has some operating system dependent 

abstractions, which may require different implementations for systems not using Linux 

or Windows. The library was implemented with POSIX standard programming interfaces where 

applicable, to provide a more standardized approach to multi-threading and mutex 

implementation.





Installation (GNU Toolchain / Linux & Macintosh OS X):

------------------------------------------------------



Requirements:

	make

	gcc

	g++



To build the library and executable code:

	Execute the command: "make" in the root OpenJAUSv3.3.0 directory. The make

command will use the Makefile found in that directory to recursively make each

of the subprojects. Individual Makefiles are located in each subproject

directory to allow for building one project at a time if desired.



Installation:

	It is up to the individual developer to decide how to link their code with

the OpenJAUS libraries. Some developers may prefer to install the OpenJAUS

header files and libraries to globally accessible directories. For example, on a

Linux system: /usr/include/ and /usr/lib/. To minimize system invasiveness, 

OpenJAUS  does not install itself into system directories, rather, all code and 

binaries remain in the folders included in the release download.



	To execute code developed with these libraries it is recommended that the

developer configure the dynamic linker runtime bindings to reference the 

OpenJAUS library directories /libjaus/lib/ and /libopenJaus/lib/. This is done

by editing the systems ld.so.conf (most likely located at /etc/ld.so.conf) to

include these directories and then by running the command: "ldconfig". Another 

option to this method would be to simply include the files libjaus.so and 

libopenJaus.so in the executable's working directory.



	*Note: The default build of the libraries includes all symbols and debug 

information within the shared object (.so) files. This is to facilitate

efficient  development and use of a run-time debugger. To reduce the size of the

installed  libraries, the information can be removed by using the "strip"

command. 





Installation (Microsoft Visual Studio / Windows):

------------------------------------------------------



Requirements:

	Microsoft Visual Studio

	Pthreads-win32 (included in distribution)

	pdcurses (included in distribution)



To build the library and executable code:



In the top level directory, open the Microsoft Visual Studio solution 

file "OpenJAUSv3.3.0.sln." This solution contains 4 individual projects: 

libjaus, libopenJaus, ojNodeManager and ojVehicleSim. These projects correspond 

to the descriptions above. Once open, the solution should be able to be 

built. Each project has the appropriate dependencies setup using relative paths, 

therefore it should compile for the developer in any configuration. Also, project 

references have been setup, so a referenced code base will be compiled prior to 

the compilation of any child project.



Once built, the ojNodeManager should run in a console window if it is set

as the default project. Ensure that the nodeManager.conf file is configured correctly.

The ojVehicleSim should run as well if it is set to the default project, however it 

is important that the ojNodeManager be running first.



The libraries libjaus and libopenJaus can be linked against other projects using 

the .lib files. To run projects built against them, ensure the appropriate .dll 

files are available either locally or globally on the system.



*Note: Use of these libraries has only been tested in the Debug configuration 

to date. This is due to the added value of retaining debug information for developers 

of both the OpenJAUS code base and applications based upon that. The creation of release 

targets, if desired, is left up to the individual developer. 





Configuring and Running the Node Manager:

-----------------------------------------



	The node manager executable is currently designed to require manual

configuration. This means the user must edit the text file nodeManager.conf to

enter the appropriate JAUS identification numbers and names, and enter the 

correct IP addresses for the intended hardware communication interfaces. The

user is also required to configure the node manager to enable or disable node

level and subsystem level communication. These configurations will vary 

depending on the intended design of the JAUS system on which the node manager is

being used. Examples of different JAUS system setups are beyond the scope of 

this document. The user is encouraged to read the JAUS reference architecture

and online OpenJAUS tutorials for a more detailed explanation.



Format:

	The nodeManager.conf file is made up of section tags and key - value pairs.

The tags are identified within straight braces, ex: "[SECTION]". The key value

pairs are delimited by a colon and a space character, ex: "key: value".



	To configure the JAUS node manager properties, edit the "SubsystemId" and

"NodeId" values found under the [JAUS] section tag. Each node manager on a 

subsystem's node network should be configured with a unique NodeId number. 

Likewise each subsystem on a network of JAUS subsystems should have a unique

SubsystemId number. Failure to make these values unique results in erratic and

undefined behavior when multiple node managers are running at the same time. 

Only one node manager process should be run at any given time on a single node.

	Set the "Subsystem_Identification" and "Node_Identification" values to any

text string that you would like for your particular system setup. These values

are not required to be unique, as they are only used for text description.



	To configure communication interface settings the user is only required to

edit the [Node_Communications] and [Subsystem_Communications] sections. By 

default, component communications are always on and the configuration needs to 

be kept fixed to use the loopback IP address 127.0.0.1. 

	Each communications section has one or more sets of transport interfaces

settings, for example "JAUS_UDP" and "OpenJAUS_UDP". This allows for multiple

transport interfaces to be used at a given communications level (component,

node, or subsystem). At present only the JAUS_UDP interface type is used at the

node and component level. However, this allows for other common transport types

such as TCP or Serial to be included in the future.

	The user has the option to enable/disable a given transport interface, or

enable/disable an entire level of communication either node or subsystem. The

node manager will startup a transport interface if both it and its 

communications level is enabled. To enable a communications level, simply set

the value of the "Enabled" key to "true". To disable a level, set the value to 

"false". These values are case sensitive, ex: "TRUE" or "True" would not work.

	When each JAUS_UDP interface starts, it attempts to open the network

interface specified with the user configured IP address. If such an interface

exists on the system, the node manager will open the JAUS port 3794 on that 

interface. If not, the node manager will fail at startup and an error message

will appear. To configure each JAUS_UDP interface simply set the key 

"JAUS_UDP_IP" value to the IP address of the network interface that you would

like it to use. The remaining key values should be left configured as in the

release download. Changing these values will lead to undefined behavior. They

are included only for completeness, and allow for future changes to be made if

necessary.





Further Information:

--------------------

Tutorials: http://www.openjaus.com/tutorials.html

Forums: http://www.openjaus.com/trac/openjaus/discussion

Support contracting: 



Known Issues:

-------------



*  There is no standalone API documentation, which describes all data

   structures, functions, or default behavior. Please read the tutorials for 

   detailed information on how to perform common tasks. The header files are 

   organized by function breakdown and allow for easy access to data structure

   definitions and function prototypes. Often the functions you seek can be

   found quickly by browsing the include/ directories.



*  A "ToString" method for each JAUS message and data structure is lacking from 

   this implementation and thus makes displaying critical information to the

   user more cumbersome.





Copyright Notices

-----------------



Portions of the Windows distribution are based on pdcurses and Pthreads-win32. 

These binaries packages have their own copyright. They are redistributed with the 

OpenJAUS codebase as a convenience to developers. More information about these 

packages can be found on their respective websites below:



Pthreads-win32: http://sourceware.org/pthreads-win32/

pdcurses: http://pdcurses.sourceforge.net/



The remainder of the code is copyright OpenJAUS.com and is distributed under the 

BSD license. See the LICENSE file for details.