Home
FAQ
Player
Stage
Gazebo
Contrib
Documentation
Publications
Contributors
Users

Project
Download
Bugs/Feedback
Mailing lists

Radish

Old news
Old stuff

Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members | Related Pages

Driver Class Reference

#include <driver.h>

Inherited by Acoustics, Acts, AdaptiveMCL, AmtecPowerCube, Aodv, BumperSafe, Camera1394, CameraCompress, CameraV4L, canonvcc4, ClodBuster, Cmucam2, CMVisionBF, CRWIDevice, Dummy, ER, FakeLocalize, Festival, FixedTones, FlockOfBirds_Device, GarminNMEA, GzFiducial, GzLaser, GzPosition, GzPosition3d, GzSim, ImageSeq, InertiaCube2, Iwspy, Khepera, LaserBar, LaserBarcode, LaserCSpace, LaserFeature, LaserVisualBarcode, LaserVisualBW, LifoMCom, LinuxJoystick, LinuxWiFi, MapCspace, MapFile, MapScale, MicroStrain3DMG, Mixer, Nomad, NomadPosition, NomadSonar, Obot, P2OS, PassThrough, PTU46_Device, ReadLog, REB, RFLEX, SegwayRMP, ShapeTracker, SickLMS200, SickPLS, SimpleShape, SonyEVID30, Sphinx2, SrvAdv_LSD, SrvAdv_MDNS, StageDevice, UPCBarcode, VFH_Class, Waveaudio, Wavefront, and WriteLog.

List of all members.

Detailed Description

Base class for all drivers.

This class manages driver subscriptions, threads, and data marshalling to/from device interfaces. All drivers inherit from this class, and most will overload the Setup(), Shutdown() and Main() methods.


Public Member Functions

 Driver (ConfigFile *cf, int section, int interface, uint8_t access, size_t datasize, size_t commandsize, size_t reqqueuelen, size_t repqueuelen)
 Constructor for single-interface drivers.

 Driver (ConfigFile *cf, int section)
 Constructor for multiple-interface drivers.

virtual ~Driver ()
 Destructor.

int AddInterface (player_device_id_t id, unsigned char access, size_t datasize, size_t commandsize, size_t reqqueuelen, size_t repqueuelen)
 Add a new-style interface.

int AddInterface (player_device_id_t id, unsigned char access, void *data, size_t datasize, void *command, size_t commandsize, void *reqqueue, int reqqueuelen, void *repqueue, int repqueuelen)
 Add a new-style interface, with pre-allocated memory.

void SetError (int code)
 Set/reset error code.

virtual int Subscribe (player_device_id_t id)
 Subscribe to this driver.

virtual int Unsubscribe (player_device_id_t id)
 Unsubscribe from this driver.

virtual int Setup ()=0
 Initialize the driver.

virtual int Shutdown ()=0
 Finalize the driver.

virtual void Prepare ()
 Do some extra initialization.

void StartThread (void)
 Start the driver thread.

void StopThread (void)
 Cancel (and wait for termination) of the driver thread.

virtual void Main (void)
 Main method for driver thread.

virtual void MainQuit (void)
 Cleanup method for driver thread (called when main exits).

void Wait (void)
 Wait on the condition variable associated with this driver.

void DataAvailable (void)
 Signal that new data is available.

virtual void Update ()
 Update non-threaded drivers.

virtual void PutData (player_device_id_t id, void *src, size_t len, struct timeval *timestamp)
 Write data to the driver.

void PutData (void *src, size_t len, struct timeval *timestamp)
 Write data to the driver (short form).

virtual size_t GetData (player_device_id_t id, void *dest, size_t len, struct timeval *timestamp)
 Read data from the driver.

virtual void PutCommand (player_device_id_t id, void *src, size_t len, struct timeval *timestamp)
 Write a new command to the driver.

virtual size_t GetCommand (player_device_id_t id, void *dest, size_t len, struct timeval *timestamp)
 Read the current command for the driver.

size_t GetCommand (void *dest, size_t len, struct timeval *timestamp)
 Read the current command (short form).

virtual void ClearCommand (player_device_id_t id)
 Clear the current command buffer.

void ClearCommand (void)
 Clear the current command buffer.

virtual int PutConfig (player_device_id_t id, void *client, void *src, size_t len, struct timeval *timestamp)
 Write configuration request to the request queue.

virtual int GetConfig (player_device_id_t id, void **client, void *dest, size_t len, struct timeval *timestamp)
 Read the next configuration request from the request queue.

int GetConfig (void **client, void *dest, size_t len, struct timeval *timestamp)
 Read the next configuration request from the request queue.

virtual int PutReply (player_device_id_t id, void *client, unsigned short type, void *src, size_t len, struct timeval *timestamp)
 Write configuration reply to the reply queue.

int PutReply (void *client, unsigned short type, void *src, size_t len, struct timeval *timestamp)
 Write configuration reply to the reply queue.

int PutReply (player_device_id_t id, void *client, unsigned short type, struct timeval *timestamp)
 Write configuration reply to the reply queue.

int PutReply (void *client, unsigned short type, struct timeval *timestamp)
 Write configuration reply to the reply queue.

virtual int GetReply (player_device_id_t id, void *client, unsigned short *type, void *dest, size_t len, struct timeval *timestamp)
 Read configuration reply from reply queue.

virtual int Request (player_device_id_t id, void *requester, void *request, size_t reqlen, struct timeval *req_timestamp, unsigned short *reptype, void *reply, size_t replen, struct timeval *rep_timestamp)

Static Public Member Functions

void DataAvailableStatic (Driver *driver)

Public Attributes

player_device_id_t device_id
 Default device id (single-interface drivers).

int subscriptions
 Number of subscriptions to this driver.

int entries
bool alwayson
int error

Protected Member Functions

virtual void Lock (void)
virtual void Unlock (void)

Constructor & Destructor Documentation

Driver::Driver (  ConfigFile *  cf,
int  section,
int  interface,
uint8_t  access,
size_t  datasize,
size_t  commandsize,
size_t  reqqueuelen,
size_t  repqueuelen
) 
 

Constructor for single-interface drivers.

Parameters:
cf Current configuration file
section Current section in configuration file
interface Player interface code; e.g., PLAYER_POSITION_CODE
access Allowed access mode; e.g., PLAYER_READ_MODE
datasize Maximum size of the data packet.
commandsize Maximum size of the command packet.
reqqueuelen Length of the request queue.
repqueuelen Length of the reply queue.

Driver::Driver (  ConfigFile *  cf,
int  section
) 
 

Constructor for multiple-interface drivers.

Use AddInterface() to specify individual interfaces.

Parameters:
cf Current configuration file
section Current section in configuration file

virtual Driver::~Driver (   )  [virtual]
 

Destructor.

Member Function Documentation

int Driver::AddInterface (  player_device_id_t  id,
unsigned char  access,
size_t  datasize,
size_t  commandsize,
size_t  reqqueuelen,
size_t  repqueuelen
) 
 

Add a new-style interface.

Parameters:
id Player device id.
access Allowed access mode; e.g., PLAYER_READ_MODE
datasize Maximum size of the data packet.
commandsize Maximum size of the command packet.
reqqueuelen Length of the request queue.
repqueuelen Length of the reply queue.
Returns:
Returns 0 on success

int Driver::AddInterface (  player_device_id_t  id,
unsigned char  access,
void *  data,
size_t  datasize,
void *  command,
size_t  commandsize,
void *  reqqueue,
int  reqqueuelen,
void *  repqueue,
int  repqueuelen
) 
 

Add a new-style interface, with pre-allocated memory.

Parameters:
id Player device id.
access Allowed access mode; e.g., PLAYER_READ_MODE
data Pointer to pre-allocated data storage.
datasize Maximum size of the data packet.
command Pointer to pre-allocated command storage.
commandsize Maximum size of the command packet.
reqqueue Pointer to pre-allocated request queue storage.
reqqueuelen Length of the request queue.
repqueue Pointer to pre-allocated reply queue storage.
repqueuelen Length of the reply queue.
Returns:
Returns 0 on success

void Driver::SetError (  int  code  )  [inline]
 

Set/reset error code.

virtual int Driver::Subscribe (  player_device_id_t  id  )  [virtual]
 

Subscribe to this driver.

The Subscribe() and Unsubscribe() methods are used to control subscriptions to the driver; a driver MAY override them, but usually won't.

Parameters:
id Id of the device to subscribe to (the driver may have more than one interface).
Returns:
Returns 0 on success.

Reimplemented in Khepera, P2OS, REB, and RFLEX.

virtual int Driver::Unsubscribe (  player_device_id_t  id  )  [virtual]
 

Unsubscribe from this driver.

The Subscribe() and Unsubscribe() methods are used to control subscriptions to the driver; a driver MAY override them, but usually won't.

Parameters:
id Id of the device to unsubscribe from (the driver may have more than one interface).
Returns:
Returns 0 on success.

Reimplemented in Khepera, P2OS, REB, and RFLEX.

virtual int Driver::Setup (   )  [pure virtual]
 

Initialize the driver.

This function is called with the first client subscribes; it MUST be implemented by the driver.

Returns:
Returns 0 on success.

Implemented in AdaptiveMCL, LifoMCom, ClodBuster, ER, Khepera, P2OS, REB, RFLEX, SegwayRMP, CRWIBumperDevice, CRWILaserDevice, CRWIPositionDevice, CRWIPowerDevice, CRWISonarDevice, and StageDevice.

virtual int Driver::Shutdown (   )  [pure virtual]
 

Finalize the driver.

This function is called with the last client unsubscribes; it MUST be implemented by the driver.

Returns:
Returns 0 on success.

Implemented in AdaptiveMCL, LifoMCom, ClodBuster, ER, Khepera, P2OS, REB, RFLEX, SegwayRMP, CRWIBumperDevice, CRWILaserDevice, CRWIPositionDevice, CRWIPowerDevice, CRWISonarDevice, and StageDevice.

virtual void Driver::Prepare (   )  [inline, virtual]
 

Do some extra initialization.

This method is called by Player on each driver after all drivers have been loaded, and immediately before entering the main loop, so override it in your driver subclass if you need to do some last minute setup with Player all set up and ready to go.

Todo:
I think this can be deprecated.

void Driver::StartThread (  void   ) 
 

Start the driver thread.

This method is usually called from the overloaded Setup() method to create the driver thread. This will call Main().

void Driver::StopThread (  void   ) 
 

Cancel (and wait for termination) of the driver thread.

This method is usually called from the overloaded Shutdown() method to terminate the driver thread.

virtual void Driver::Main (  void   )  [virtual]
 

Main method for driver thread.

Most drivers have their own thread of execution, created using StartThread(); this is the entry point for the driver thread, and must be overloaded by all threaded drivers.

Reimplemented in ClodBuster, ER, Khepera, P2OS, REB, RFLEX, CRWIBumperDevice, CRWILaserDevice, CRWIPositionDevice, CRWIPowerDevice, and CRWISonarDevice.

virtual void Driver::MainQuit (  void   )  [virtual]
 

Cleanup method for driver thread (called when main exits).

Overload this method and to do additional cleanup when the driver thread exits.

void Driver::Wait (  void   ) 
 

Wait on the condition variable associated with this driver.

This method blocks until new data is available (as indicated by a call to PutData() or DataAvailable()). Usually called in the context of another driver thread.

void Driver::DataAvailable (  void   ) 
 

Signal that new data is available.

Calling this method will release any threads currently waiting on this driver. Called automatically by the default PutData() implementation.

Todo:
Fix the semantics of DataAvailable() and Wait(). As currenly implemented, we Wait() on devices, but call DataAvailable() on drivers. For drivers with multiple interfaces, this means than threads blocked on a wait will resume when any* of the driver's interfaces is updated (not the expected behavior).

void Driver::DataAvailableStatic (  Driver *  driver  )  [static]
 

virtual void Driver::Update (  void   )  [inline, virtual]
 

Update non-threaded drivers.

This method is called once per loop (in Linux, probably either 50Hz or 100Hz) by the server. Threaded drivers can use the default implementation, which does nothing. Non-threaded drivers should do whatever they have to do, and call PutData() when they have new data.

Reimplemented in AdaptiveMCL, and StageDevice.

virtual void Driver::PutData (  player_device_id_t  id,
void *  src,
size_t  len,
struct timeval *  timestamp
)  [virtual]
 

Write data to the driver.

This method will usually be called by the driver.

Parameters:
id Id of the device to write to (drivers may have multiple interfaces).
src Pointer to data source buffer.
len Length of the data (bytes).
timestamp Data timestamp; if NULL, the current server time will be used.

void Driver::PutData (  void *  src,
size_t  len,
struct timeval *  timestamp
)  [inline]
 

Write data to the driver (short form).

Convenient short form of PutData() for single-interface drivers.

virtual size_t Driver::GetData (  player_device_id_t  id,
void *  dest,
size_t  len,
struct timeval *  timestamp
)  [virtual]
 

Read data from the driver.

This function will usually be called by the server.

Parameters:
id Specifies the device to be read.
dest Pointer to data destination buffer.
len Size of the data destination buffer (bytes).
timestamp If non-null, will be filled with the data timestamp.
Returns:
Returns the number of bytes written to the destination buffer.

Reimplemented in StageDevice.

virtual void Driver::PutCommand (  player_device_id_t  id,
void *  src,
size_t  len,
struct timeval *  timestamp
)  [virtual]
 

Write a new command to the driver.

This function will usually be called by the server.

Parameters:
id Specifies the device to be written.
src Pointer to command source buffer.
len Length of the command (bytes).
timestamp Command timestamp; if NULL, the current server time will be used.

Reimplemented in StageDevice.

virtual size_t Driver::GetCommand (  player_device_id_t  id,
void *  dest,
size_t  len,
struct timeval *  timestamp
)  [virtual]
 

Read the current command for the driver.

This function will usually be called by the driver.

Parameters:
id Specifies the device to be read.
dest Pointer to command destination buffer.
len Length of the destination buffer (bytes).
timestamp If non-null, will be filled with the command timestamp.
Returns:
Returns the number of bytes written to the destination buffer.

size_t Driver::GetCommand (  void *  dest,
size_t  len,
struct timeval *  timestamp
)  [inline]
 

Read the current command (short form).

Convenient short form for single-interface drivers.

virtual void Driver::ClearCommand (  player_device_id_t  id  )  [virtual]
 

Clear the current command buffer.

This method is called by drivers to "consume" commands.

Parameters:
id Specifies the device to be cleared .

void Driver::ClearCommand (  void   )  [inline]
 

Clear the current command buffer.

Convenient short form of ClearCommand(), for single-interface drivers.

virtual int Driver::PutConfig (  player_device_id_t  id,
void *  client,
void *  src,
size_t  len,
struct timeval *  timestamp
)  [virtual]
 

Write configuration request to the request queue.

Unlike data and commands, requests are added to a queue. This function will usually be called by the server.

Parameters:
id Specifies the device to be written.
client A generic pointer for routing replies (advanced usage only).
src Pointer to source buffer.
len Length of the source buffer (bytes).
timestamp Command timestamp; if NULL, the current server time will be used.
Returns:
Returns 0 on success (queues may overflow, generating an error).

Reimplemented in LifoMCom.

virtual int Driver::GetConfig (  player_device_id_t  id,
void **  client,
void *  dest,
size_t  len,
struct timeval *  timestamp
)  [virtual]
 

Read the next configuration request from the request queue.

Unlike data and commands, requests are added to and removed from a queue. This method will usually be called by the driver.

Parameters:
id Specifies the device to be read.
client Pointer to a generic pointer for routing replies (advanced usage only).
dest Pointer to destination buffer.
len Length of the destination buffer (bytes).
timestamp If non-null, will be filled with the request timestamp.
Returns:
Returns 0 if there are no pending requests, otherwise returns the number of bytes written to the destination buffer.

int Driver::GetConfig (  void **  client,
void *  dest,
size_t  len,
struct timeval *  timestamp
)  [inline]
 

Read the next configuration request from the request queue.

Convenient short form of GetConfig(), for single-interface drivers.

virtual int Driver::PutReply (  player_device_id_t  id,
void *  client,
unsigned short  type,
void *  src,
size_t  len,
struct timeval *  timestamp
)  [virtual]
 

Write configuration reply to the reply queue.

This method will usually be called by the driver.

Parameters:
id Specifies the device to be written.
client A generic pointer for routing replies (advanced usage only).
type Reply type; e.g., PLAYER_MSGTYPE_RESP_ACK or PLAYER_MSGTYPE_RESP_NACK.
src Pointer to source buffer.
len Length of the source buffer (bytes).
timestamp Command timestamp; if NULL, the current server time will be used.
Returns:
Returns 0 on success (queues may overflow, generating an error).

int Driver::PutReply (  void *  client,
unsigned short  type,
void *  src,
size_t  len,
struct timeval *  timestamp
)  [inline]
 

Write configuration reply to the reply queue.

Convenient short form of PutReply() for single-interface drivers.

int Driver::PutReply (  player_device_id_t  id,
void *  client,
unsigned short  type,
struct timeval *  timestamp
)  [inline]
 

Write configuration reply to the reply queue.

Convenient short form of PutReply(): empty reply

int Driver::PutReply (  void *  client,
unsigned short  type,
struct timeval *  timestamp
)  [inline]
 

Write configuration reply to the reply queue.

Convenient short form of PutReply(): empty reply for single-interface drivers.

virtual int Driver::GetReply (  player_device_id_t  id,
void *  client,
unsigned short *  type,
void *  dest,
size_t  len,
struct timeval *  timestamp
)  [virtual]
 

Read configuration reply from reply queue.

This function will usually be called by the server.

Parameters:
id Specifies the device to be read.
client A generic pointer for routing replies (advanced usage only).
type Reply type; e.g., PLAYER_MSGTYPE_RESP_ACK or PLAYER_MSGTYPE_RESP_NACK.
dest Pointer to destination buffer.
len Size of the destination buffer (bytes).
timestamp If non-null, will be filled with the data timestamp.
Returns:
Returns the number of bytes written to the destination buffer.

virtual int Driver::Request (  player_device_id_t  id,
void *  requester,
void *  request,
size_t  reqlen,
struct timeval *  req_timestamp,
unsigned short *  reptype,
void *  reply,
size_t  replen,
struct timeval *  rep_timestamp
)  [virtual]
 

A helper method for internal use; e.g., when one driver wants to make a request of another driver.

virtual void Driver::Lock (  void   )  [protected, virtual]
 

virtual void Driver::Unlock (  void   )  [protected, virtual]
 

Member Data Documentation

player_device_id_t Driver::device_id
 

Default device id (single-interface drivers).

int Driver::subscriptions
 

Number of subscriptions to this driver.

int Driver::entries
 

Total number of entries in the device table using this driver. This is updated and read by the Device class.

bool Driver::alwayson
 

If true, driver should be "always on", i.e., player will "subscribe" at startup, before any clients subscribe. The "alwayson" parameter in the config file can be used to turn this feature on as well (in which case this flag will be set to reflect that setting).

int Driver::error
 

Last error value; useful for returning error codes from constructors

The documentation for this class was generated from the following file:
Generated on Tue May 3 14:15:49 2005 for Player by doxygen 1.3.6