Skip to content

Q
qgroundcontrol
Switch branch/tag
Find file
Normal viewHistoryPermalink
README.TXT 10.7 KB
Newer Older
pixhawk's avatar
Initial import
4fa6562e
 
pixhawk committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 
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.