Note: Goby version 1 (shown here) is now considered obsolete. Please use version 2 for new projects, and consider upgrading old projects.

Goby Underwater Autonomy Project  Series: 1.1, revision: 163, released on 2013-02-06 14:23:27 -0500
goby-util: Overview of Utility Libraries

Table of Contents for goby-util: Overview of Utility Libraries.

Overview

The goby-util libraries are intended to provide functions and classes for handling "utility" tasks, such as logging, string manipulation, scientific calculations, etc. Wherever possible, a high quality open source peer reviewed solution is used (such as the C++ STL, boost). However, many of these libraries are very full-featured complex and are simplified here for Goby specific tasks.

Logging

Because Goby is designed first and foremost as an engineering testbed and scientific research architecture, comprehensive logging is extremely important for debugging both at runtime and post-mission. Thus, Goby provides a logging utility (goby::util::FlexOstream) based on C++ STL streams that provides highly configurable runtime (i.e. terminal window) and/or post-mission (text log file) logging. The syntax inside the code should be familiar to any C++ programmer, as any std::ostream functions can be used. The goby-acomms API classes all have a constructor which can take a pointer to std::ostream object that will be used to log. Thus, for runtime debugging one might instantiate them with std::cout:

goby::acomms::DCCLCodec dccl(&std::cout);

In which case you get output (to std::cout, aka the terminal window) that looks like:

[ 2011-Mar-01 04:06:35.169817 ]               {dccl_enc}: cryptography enabled with given passphrase
[ 2011-Mar-01 04:06:35.170610 ]               {dccl_enc}: starting encode for TEST
[ 2011-Mar-01 04:06:35.170683 ]               {dccl_enc}: 	B: bool: true
...

The timestamp (in Universal Coordinated Time) is given, with a group name (dccl_enc = DCCL Encoder) and finally the message. These groups are provided by using the manipulator "group". Text in the stream is a member of the given group until the next flush (std::endl or std::flush). For example:

// prints [ 2011-Mar-01 04:06:35.169817 ]               {my_group}: my message
std::cout << group("my_group") << "my message" << std::endl; // endl flushes my_group

Several other manipulators are provided:

Configurable extension of std::ostream - liblogger

goby::util::FlexOstream extends std::ostream to provide a number of extra logging features. This is generally the preferred logger (instead of std::cout, etc.) for goby applications. Use goby::util::glogger() in the same way you would use std::cout or a std::ofstream object. These features include:

The best way to get used to goby:util::glogger() is to compile and play with the flexostream_simple.cpp example.

A handful of examples:

glogger-example.png
Graphical user interface logger mode:

glogger-gui.png
Simultaneous terminal window and file logging:

flexostream_simple quiet|warn|verbose|debug|gui test.txt

test.txt:

[ 2011-Mar-01 05:33:26.224050 ]               {}: (Warning): this is warning text
[ 2011-Mar-01 05:33:26.224277 ]               {}: this is normal text
[ 2011-Mar-01 05:33:26.224320 ]               {}: this is light blue text (in color terminals)
[ 2011-Mar-01 05:33:26.224362 ]               {}: (Debug): this is debug text
[ 2011-Mar-01 05:33:26.224388 ]               {a}: this text is related to a
[ 2011-Mar-01 05:33:26.224429 ]               {b}: this text is related to b
[ 2011-Mar-01 05:33:26.224471 ]               {c}: (Warning): this warning is related to c

TCP and Serial port communications - liblinebasedcomms

liblinebasedcomms provides a common interface (goby::util::LineBasedInterface) for line-based (defined as blocks of text offset by a common delimiter such as "\\r\\n" or "\\n") text communications over a TCP or serial connection. liblinebasedcomms using the boost::asio library to perform the actual communications.

You should create the proper subclass for your needs:

 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends