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
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends
Public Member Functions
goby::acomms::ModemDriverBase Class Reference

provides an abstract base class for acoustic modem drivers. This is subclassed by the various drivers for different manufacturers' modems. More...

#include <goby/acomms/modem_driver.h>

Inherited by goby::acomms::ABCDriver, and goby::acomms::MMDriver.

List of all members.

Public Member Functions

virtual ~ModemDriverBase ()
 Public Destructor.
Control
virtual void startup (const protobuf::DriverConfig &cfg)=0
 Starts the modem driver. Must be called before do_work().
virtual void shutdown ()=0
 Shuts down the modem driver.
virtual void do_work ()=0
 Allows the modem driver to do its work.
MAC Slots
virtual void handle_initiate_transmission (protobuf::ModemMsgBase *m)=0
 Virtual initiate_transmission method. Typically connected to MACManager::signal_initiate_transmission() using bind().
virtual void handle_initiate_ranging (protobuf::ModemRangingRequest *m)
 Virtual initiate_ranging method. Typically connected to MACManager::signal_initiate_ranging() using bind().

Static Public Member Functions

Static helpers
static void add_flex_groups (util::FlexOstream *tout)
 Set the output groups for the modem driver if using the util::FlexOstream class for human readable debugging out. Setting groups allows the util::FlexOstream class to differentiate between different types of debugging messages.

Public Attributes

MAC / Queue Signals
boost::signal< void(const
protobuf::ModemDataTransmission
&message)> 
signal_receive
 Called when a binary data transmission is received from the modem.
boost::signal< void(const
protobuf::ModemDataRequest
&msg_request,
protobuf::ModemDataTransmission
*msg_data) 
signal_data_request )
 Called when the modem or modem driver needs data to send. msg_request contains details on the data request, and the returned data should be stored in msg_data.
boost::signal< void(const
protobuf::ModemRangingReply
&message)> 
signal_range_reply
 Called when the modem receives ranging information (time of flight to another vehicle or LBL ranging beacons)
boost::signal< void(const
protobuf::ModemDataAck
&message)> 
signal_ack
 Called when the modem receives an acknowledgment of proper receipt of a prior data transmission. The frame number of the acknowledgment must match the frame number of the original message. The modem driver is only responsible for the base (source, destination, timestamp) and acknowledged frame number in ModemDataAck.
boost::signal< void(const
protobuf::ModemMsgBase
&msg_data)> 
signal_all_incoming
 Called after any message is received from the modem by the driver. Used by the MACManager for auto-discovery of vehicles. Also useful for higher level analysis and debugging of the transactions between the driver and the modem.
boost::signal< void(const
protobuf::ModemMsgBase
&msg_data)> 
signal_all_outgoing
 Called after any message is sent from the driver to the modem. Useful for higher level analysis and debugging of the transactions between the driver and the modem.

Protected Member Functions

Constructors/Destructor
 ModemDriverBase (std::ostream *log=0)
 Constructor.
Write/read from the line-based interface to the modem
void modem_write (const std::string &out)
 write a line to the serial port.
bool modem_read (std::string *in)
 read a line from the serial port, including end-of-line character(s)
void modem_start (const protobuf::DriverConfig &cfg)
 start the physical connection to the modem (serial port, TCP, etc.). must be called before ModemDriverBase::modem_read() or ModemDriverBase::modem_write()
void modem_close ()
 closes the serial port. Use modem_start to reopen the port.

Detailed Description

provides an abstract base class for acoustic modem drivers. This is subclassed by the various drivers for different manufacturers' modems.

See also:
driver_base.proto and modem_message.proto for definition of Google Protocol Buffers messages (namespace goby::acomms::protobuf).
Examples:
libmodemdriver/driver_simple/driver_simple.cpp.

Definition at line 42 of file driver_base.h.


Constructor & Destructor Documentation

goby::acomms::ModemDriverBase::ModemDriverBase ( std::ostream *  log = 0) [protected]

Constructor.

Parameters:
logpointer to std::ostream to log human readable debugging and runtime information

Definition at line 27 of file driver_base.cpp.


Member Function Documentation

Set the output groups for the modem driver if using the util::FlexOstream class for human readable debugging out. Setting groups allows the util::FlexOstream class to differentiate between different types of debugging messages.

Parameters:
toutpointer to util::FlexOstream stream object to add groups to.

Definition at line 110 of file driver_base.cpp.

virtual void goby::acomms::ModemDriverBase::do_work ( ) [pure virtual]

Allows the modem driver to do its work.

Should be called regularly to perform the work of the driver as the driver *does not* run in its own thread. This allows us to guarantee that no signals are called except inside this do_work method.

Implemented in goby::acomms::MMDriver, and goby::acomms::ABCDriver.

Examples:
libmodemdriver/driver_simple/driver_simple.cpp.
virtual void goby::acomms::ModemDriverBase::handle_initiate_ranging ( protobuf::ModemRangingRequest *  m) [inline, virtual]

Virtual initiate_ranging method. Typically connected to MACManager::signal_initiate_ranging() using bind().

Parameters:
mModemRangingRequest (defined in modem_message.proto) containing the details of the ranging request to be started: source, destination, type, etc.

Reimplemented in goby::acomms::MMDriver.

Definition at line 71 of file driver_base.h.

virtual void goby::acomms::ModemDriverBase::handle_initiate_transmission ( protobuf::ModemMsgBase *  m) [pure virtual]

Virtual initiate_transmission method. Typically connected to MACManager::signal_initiate_transmission() using bind().

Parameters:
mModemMsgBase (defined in modem_message.proto) containing the details of the transmission to be started. This does *not* contain data, which will be requested when the driver calls the data request signal (ModemDriverBase::signal_data_request)

Implemented in goby::acomms::MMDriver, and goby::acomms::ABCDriver.

Examples:
libmodemdriver/driver_simple/driver_simple.cpp.
bool goby::acomms::ModemDriverBase::modem_read ( std::string *  in) [protected]

read a line from the serial port, including end-of-line character(s)

Parameters:
inpointer to string to store line
Returns:
true if a line was available, false if no line available

Definition at line 49 of file driver_base.cpp.

void goby::acomms::ModemDriverBase::modem_start ( const protobuf::DriverConfig &  cfg) [protected]

start the physical connection to the modem (serial port, TCP, etc.). must be called before ModemDriverBase::modem_read() or ModemDriverBase::modem_write()

Parameters:
cfgConfiguration including the parameters for the physical connection. (protobuf::DriverConfig is defined in driver_base.proto).
Exceptions:
driver_exceptionProblem opening the physical connection.

Definition at line 67 of file driver_base.cpp.

void goby::acomms::ModemDriverBase::modem_write ( const std::string &  out) [protected]

write a line to the serial port.

Parameters:
outreference to string to write. Must already include any end-of-line character(s).

Definition at line 37 of file driver_base.cpp.

virtual void goby::acomms::ModemDriverBase::startup ( const protobuf::DriverConfig &  cfg) [pure virtual]

Starts the modem driver. Must be called before do_work().

Parameters:
cfgStartup configuration for the driver and modem. DriverConfig is defined in driver_base.proto. Derived classes can define extensions (see http://code.google.com/apis/protocolbuffers/docs/proto.html#extensions) to DriverConfig to handle modem specific configuration.

Implemented in goby::acomms::MMDriver, and goby::acomms::ABCDriver.

Examples:
libmodemdriver/driver_simple/driver_simple.cpp.

Member Data Documentation

boost::signal<void (const protobuf::ModemDataAck& message)> goby::acomms::ModemDriverBase::signal_ack

Called when the modem receives an acknowledgment of proper receipt of a prior data transmission. The frame number of the acknowledgment must match the frame number of the original message. The modem driver is only responsible for the base (source, destination, timestamp) and acknowledged frame number in ModemDataAck.

You should connect one or more slots (a function or member function) to this signal to handle acknowledgments. Use the goby::acomms::connect family of functions to do this. This signal will only be called during a call to do_work. ModemDataAck is defined in modem_message.proto.

Definition at line 100 of file driver_base.h.

boost::signal<void (const protobuf::ModemMsgBase& msg_data)> goby::acomms::ModemDriverBase::signal_all_incoming

Called after any message is received from the modem by the driver. Used by the MACManager for auto-discovery of vehicles. Also useful for higher level analysis and debugging of the transactions between the driver and the modem.

If desired, you should connect one or more slots (a function or member function) to this signal to listen on incoming transactions. Use the goby::acomms::connect family of functions to do this. This signal will only be called during a call to do_work. ModemMsgBase is defined in modem_message.proto.

Definition at line 106 of file driver_base.h.

boost::signal<void (const protobuf::ModemMsgBase& msg_data)> goby::acomms::ModemDriverBase::signal_all_outgoing

Called after any message is sent from the driver to the modem. Useful for higher level analysis and debugging of the transactions between the driver and the modem.

If desired, you should connect one or more slots (a function or member function) to this signal to listen on outgoing transactions. Use the goby::acomms::connect family of functions to do this. This signal will only be called during a call to do_work. ModemMsgBase is defined in modem_message.proto.

Definition at line 112 of file driver_base.h.

boost::signal<void (const protobuf::ModemDataRequest& msg_request, protobuf::ModemDataTransmission* msg_data) goby::acomms::ModemDriverBase::signal_data_request)

Called when the modem or modem driver needs data to send. msg_request contains details on the data request, and the returned data should be stored in msg_data.

You should connect one or more slots (a function or member function) to this signal to handle data requests. Use the goby::acomms::connect family of functions to do this. This signal will only be called during a call to do_work. ModemDataRequest and ModemDataTransmission are defined in modem_message.proto.

Examples:
libmodemdriver/driver_simple/driver_simple.cpp.

Definition at line 88 of file driver_base.h.

boost::signal<void (const protobuf::ModemRangingReply& message)> goby::acomms::ModemDriverBase::signal_range_reply

Called when the modem receives ranging information (time of flight to another vehicle or LBL ranging beacons)

You should connect one or more slots (a function or member function) to this signal to handle ranging replies. Use the goby::acomms::connect family of functions to do this. This signal will only be called during a call to do_work. ModemRangingReply is defined in modem_message.proto.

Definition at line 94 of file driver_base.h.

boost::signal<void (const protobuf::ModemDataTransmission& message)> goby::acomms::ModemDriverBase::signal_receive

Called when a binary data transmission is received from the modem.

You should connect one or more slots (a function or member function) to this signal to receive incoming messages. Use the goby::acomms::connect family of functions to do this. This signal will only be called during a call to do_work. ModemDataTransmission is defined in modem_message.proto.

Examples:
libmodemdriver/driver_simple/driver_simple.cpp.

Definition at line 82 of file driver_base.h.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends