Tekkotsu Homepage
Demos
Overview
Downloads
Dev. Resources
Reference
Credits

DataSource Class Reference

abstract base class for simulator data sources More...

#include <DataSource.h>

Inheritance diagram for DataSource:

Detailed Description

abstract base class for simulator data sources

Each subclass will implement loading data from some piece of hardware or network protocol.

The general flow of calls is:

If your data source provides sensor data for current output values, you should call providingOutput() for those outputs when registerSource() is called, and ignoringOutput() when you are no longer active (deregisterSource() or destructor is called). This prevents the Motion process from clobbering your readings with its own feedback.

Definition at line 35 of file DataSource.h.

List of all members.

Classes

struct  ImageHeader
 This structure should be written into the beginning of each image buffer sent via setImage(). More...

Public Member Functions

 DataSource ()
 constructor
 DataSource (const DataSource &ds)
 copy constructor, just in case your subclass wants it
DataSourceoperator= (const DataSource &)
 assignment operator, just in case your subclass wants it
virtual ~DataSource ()
 destructor
virtual unsigned int nextTimestamp ()=0
 Returns the simulator time of the next data segment.
virtual const std::string & nextName ()=0
 Returns a descriptive name of the next data segment for user feedback (e.g. a filename for logged data).
virtual bool advance ()=0
 Called when the simulator is stepping while paused or advancing a frozen data source, return true if successful, or false if no more data is available.
virtual void setFrozen (bool fr)
 Called by simulator if the user pauses a data source; calls doFreeze() or doUnfreeze() as appropriate.
virtual bool getFrozen () const
 returns frozen status
virtual void reset ()
 if called, indicates a request to restart/reinitialize the data source
virtual void registerSource ()
 User hook, called when the data source should claim which outputs it provides feedback (providingOuput()).
virtual void deregisterSource ()
 User hook, called when the data source should release its claim on outputs with feedback (ignoringOuput()).
virtual void enteringRealtime (const plist::Primitive< double > &)
 User hook, called when the controller is going to be running in realtime mode, which is probably the normal mode you'd expect.
virtual void leavingRealtime (bool)
 User hook, called when leaving realtime mode, which means you have no idea when motionCheck() is going to be called in terms of wall-clock time.
virtual void setImageQueue (MessageQueueBase *mq)
 Called by simulator during initialization to tell the DataSource where it should send image data (if this is selected as an active image data source).

Static Public Member Functions

static void setSensorState (SensorState *senState)
 Called by simulator during initialization to tell DataSources where the array of sensor values are stored (see sensorState).
static void setNeedsSensor (bool waiting)
 will be called by initialization code prior to first getData() if client code is going to block on getting the first sensor reading
static void setSensorFramerate (const plist::Primitive< float > *senFR)
 will be called by initialization code to provide a pointer to the sensor synchronization framerate sensorFramerate
static float getOutputValue (unsigned int i)
 returns the pending output value, which may not have been processed by the framework yet
static float getSensorValue (unsigned int i)
 returns the pending sensor value, which may not have been processed by the framework yet
static float getButtonValue (unsigned int i)
 returns the pending button value, which may not have been processed by the framework yet
static float getPIDDutyValue (unsigned int i)
 returns the pending duty cycle value, which may not have been processed by the framework yet

Protected Member Functions

void setImage (RCRegion *region)
 Sets the current image, for bulk data sources like cameras.
void setImage (const ImageHeader &header, const void *data)
 sets the current image, for bulk data sources like cameras
virtual RCRegiongetUnusedRegion (size_t minSize, size_t padding)
 Finds a one-reference entry in regions with capacity at least minSize, creating a new one of size minSize + padding if necessary.
virtual void doFreeze ()
 user hook for when frozen is set to true; advance() will be called by simulator at user discretion.
virtual void doUnfreeze ()
 user hook for when frozen is set to false; if enteringRealtime() has been called then you should resume sending data.

Static Protected Member Functions

static ResourcegetSensorWriteLock ()
 subclasses should pass this to a MarkScope instance before they begin calling the static setXXXValue functions to prevent concurrent or partial updates
static void providingOutput (unsigned int i)
 subclasses should call this if they provide sensor updates which will contain a measurement of the current position of output i.
static void ignoringOutput (unsigned int i)
 subclasses should call this if they provided sensor updates containing the current position of output i, but are not going to do so any longer.
static void setOutputValue (unsigned int i, float v)
 sets the current value for an output, be sure to register with providingOutput() (and later ignoringOutput()) in order to avoid being clobbered by "blind" feedback from the Motion process
static void setSensorValue (unsigned int i, float v)
 sets the current value for a sensor
static void setButtonValue (unsigned int i, float v)
 sets the current value for a button
static void setPIDDutyValue (unsigned int i, float v)
 sets the current duty cycle value for a servo joint, i should be relative to PIDJointOffset
static unsigned int getSensorFrameNumber ()
 Returns a counter which is incremented each time the sensor data is copied into the framework.

Protected Attributes

std::list< RCRegion * > regions
 for efficiency, reuse old buffers via getUnusedRegion() -- oldest at front, most recently used at back
bool frozen
 indicates that data is going to be requested "sparsely"; advance() will be called by simulator at user discretion

Static Protected Attributes

static bool requiresFirstSensor = true
 if true, indicates that client code is going to wait for sensor readings returned by getData before executing
static const plist::Primitive
< float > * 
sensorFramerate = NULL
 Assigned by setSensorFramerate() during initialization, points to the synchronization framerate for sensors.

Private Attributes

MessageQueueBaseimageQueue
 assigned by setImageQueue(), calls to setImage() will send messages into this queue

Static Private Attributes

static SensorStatesensorState = NULL

Constructor & Destructor Documentation

DataSource (  ) 

constructor

Definition at line 37 of file DataSource.h.

DataSource ( const DataSource ds  ) 

copy constructor, just in case your subclass wants it

Definition at line 38 of file DataSource.h.

~DataSource (  )  [virtual]

destructor

Definition at line 40 of file DataSource.cc.


Member Function Documentation

virtual bool advance (  )  [pure virtual]

Called when the simulator is stepping while paused or advancing a frozen data source, return true if successful, or false if no more data is available.

Implemented in CameraSourceQTKit, CameraSourceQTSG, FileSystemDataSource, SensorStateAccessor, CameraDriverPtGrey, CameraDriverV4L2, CreateDriver, DataStreamDriver, DynamixelDriver, RGBSource, DepthSource, KobukiDriver, SkewlZoneDriver, and SSC32Driver.

Referenced by Simulator::run().

virtual void deregisterSource (  )  [virtual]

User hook, called when the data source should release its claim on outputs with feedback (ignoringOuput()).

It would be wise to call this from your destructor as well.

Reimplemented in CameraSourceQTKit, CameraSourceQTSG, FileSystemDataSource, FileSystemSensorSource, CameraDriverPtGrey, CameraDriverV4L2, CreateDriver, DataStreamDriver, DynamixelDriver, KobukiDriver, ImageSubscription, DepthSubscription, PListSensorDriver, SkewlZoneDriver, and SSC32Driver.

Definition at line 70 of file DataSource.h.

Referenced by DepthSource::~DepthSource(), and RGBSource::~RGBSource().

virtual void doFreeze (  )  [protected, virtual]
virtual void doUnfreeze (  )  [protected, virtual]
virtual void enteringRealtime ( const plist::Primitive< double > &   )  [virtual]

User hook, called when the controller is going to be running in realtime mode, which is probably the normal mode you'd expect.

You might be in realtime mode, but a debugger breakpoint will still pause things, or thread scheduling could hiccup, so try to be robust.
The argument is a reference to SharedGlobals::timeScale, so the data source can subscribe to changes in simulation speed if it can use that information. (We avoid direct dependency on the tekkotsu simulator so this code can be reused for other tools too.)

Reimplemented in FileSystemDataSource, CreateDriver, DynamixelDriver, KobukiDriver, SkewlZoneDriver, and SSC32Driver.

Definition at line 77 of file DataSource.h.

float getButtonValue ( unsigned int  i  )  [static]

returns the pending button value, which may not have been processed by the framework yet

Definition at line 292 of file DataSource.h.

Referenced by SensorStateAccessor::print().

virtual bool getFrozen (  )  const [virtual]

returns frozen status

Definition at line 57 of file DataSource.h.

Referenced by Simulator::cmdAdvance().

float getOutputValue ( unsigned int  i  )  [static]

returns the pending output value, which may not have been processed by the framework yet

Definition at line 286 of file DataSource.h.

Referenced by SSC32Driver::advance(), MirageDriver::motionStarting(), and MirageDriver::updateAllOutputs().

float getPIDDutyValue ( unsigned int  i  )  [static]

returns the pending duty cycle value, which may not have been processed by the framework yet

Definition at line 295 of file DataSource.h.

unsigned int getSensorFrameNumber (  )  [static, protected]

Returns a counter which is incremented each time the sensor data is copied into the framework.

You could use this to determine if user code has gotten a chance to see a detection flag of some sort before clearing it again

Definition at line 297 of file DataSource.h.

Referenced by DynamixelDriver::provideValues().

float getSensorValue ( unsigned int  i  )  [static]

returns the pending sensor value, which may not have been processed by the framework yet

Definition at line 289 of file DataSource.h.

Referenced by SensorStateAccessor::print(), and DynamixelDriver::provideValues().

Resource & getSensorWriteLock (  )  [static, protected]

subclasses should pass this to a MarkScope instance before they begin calling the static setXXXValue functions to prevent concurrent or partial updates

Definition at line 279 of file DataSource.h.

Referenced by SSC32Driver::advance(), DynamixelDriver::pingServos(), DynamixelDriver::provideValues(), PListSensorDriver::readData(), and FileSystemSensorSource::sendData().

RCRegion * getUnusedRegion ( size_t  minSize,
size_t  padding 
) [protected, virtual]

Finds a one-reference entry in regions with capacity at least minSize, creating a new one of size minSize + padding if necessary.

If the first one-reference entry is too small, it will be freed and a new one created instead.

Definition at line 80 of file DataSource.cc.

Referenced by ImageStreamDriver::readImage(), and setImage().

void ignoringOutput ( unsigned int  i  )  [static, protected]

subclasses should call this if they provided sensor updates containing the current position of output i, but are not going to do so any longer.

You don't need to call this if you didn't previously call providingOutput().

Definition at line 56 of file DataSource.cc.

Referenced by PListSensorDriver::deregisterSource(), FileSystemSensorSource::deregisterSource(), SSC32Driver::ignoreOutput(), SkewlZoneDriver::ignoreOutput(), DynamixelDriver::ignoreOutput(), and CreateDriver::ignoreOutput().

virtual void leavingRealtime ( bool   )  [virtual]

User hook, called when leaving realtime mode, which means you have no idea when motionCheck() is going to be called in terms of wall-clock time.

Argument set to true if entering full speed mode, which indicates everything should run at full native "frame rate", and may indicate more data will be processed than normal, CPU speed permitting. However, if false, almost certainly indicates updates will be sparse, trigger by user 'step' commands. May be called multiple times if changing between full-speed mode and paused

A non-realtime mode might be triggered if the user wants to pause the simulator/controller to step through something... No guarantees though! The debugger might catch a breakpoint and stop things, and this won't be called!

Reimplemented in FileSystemDataSource, CreateDriver, DynamixelDriver, KobukiDriver, SkewlZoneDriver, and SSC32Driver.

Definition at line 87 of file DataSource.h.

virtual const std::string& nextName (  )  [pure virtual]

Returns a descriptive name of the next data segment for user feedback (e.g. a filename for logged data).

Just use your class name if you don't have a useful name for individual samples.

Implemented in BufferSource, CameraSourceQTKit, CameraSourceQTSG, FileSystemDataSource, SensorStateAccessor, CameraDriverPtGrey, CameraDriverV4L1, CameraDriverV4L2, CreateDriver, DataStreamDriver, DynamixelDriver, RGBSource, DepthSource, KobukiDriver, SkewlZoneDriver, SSC32Driver, DataCache, Subscription< PListSensorDriver >, and Subscription< ImageStreamDriver >.

virtual unsigned int nextTimestamp (  )  [pure virtual]

Returns the simulator time of the next data segment.

Should be in the future if nothing new since last data segment, otherwise should be the timestamp of the most recent data segment (older segments are skipped), return -1U if there is no more data

Implemented in BufferSource, CameraSourceQTKit, CameraSourceQTSG, FileSystemDataSource, SensorStateAccessor, CameraDriverPtGrey, CameraDriverV4L1, CameraDriverV4L2, CreateDriver, DataStreamDriver, DynamixelDriver, RGBSource, DepthSource, KobukiDriver, SkewlZoneDriver, SSC32Driver, and DataCache.

DataSource& operator= ( const DataSource  ) 

assignment operator, just in case your subclass wants it

Definition at line 39 of file DataSource.h.

void providingOutput ( unsigned int  i  )  [static, protected]

subclasses should call this if they provide sensor updates which will contain a measurement of the current position of output i.

Definition at line 45 of file DataSource.cc.

Referenced by SSC32Driver::provideOutput(), SkewlZoneDriver::provideOutput(), DynamixelDriver::provideOutput(), CreateDriver::provideOutput(), PListSensorDriver::readData(), and FileSystemSensorSource::registerSource().

virtual void registerSource (  )  [virtual]

User hook, called when the data source should claim which outputs it provides feedback (providingOuput()).

Does not indicate the data source should start sending updates yet — wait for enteringRealtime() or advance() to be called

Reimplemented in CameraSourceQTKit, CameraSourceQTSG, FileSystemDataSource, FileSystemSensorSource, CameraDriverPtGrey, CameraDriverV4L2, CreateDriver, DataStreamDriver, DynamixelDriver, KobukiDriver, ImageSubscription, DepthSubscription, SkewlZoneDriver, and SSC32Driver.

Definition at line 66 of file DataSource.h.

virtual void reset (  )  [virtual]

if called, indicates a request to restart/reinitialize the data source

For example, a FileSystemDataSource would go back to the beginning of its list, and a network-based source would close and reopen the connection

Definition at line 62 of file DataSource.h.

void setButtonValue ( unsigned int  i,
float  v 
) [static, protected]
virtual void setFrozen ( bool  fr  )  [virtual]

Called by simulator if the user pauses a data source; calls doFreeze() or doUnfreeze() as appropriate.

You probably don't want to override this function -- that's what doFreeze() doUnfreeze are for!

Definition at line 56 of file DataSource.h.

void setImage ( const ImageHeader header,
const void *  data 
) [protected]

sets the current image, for bulk data sources like cameras

This version copies the data into an RCRegion and calls setImage(RCRegion*). For efficiency with large blocks of data, if possible you should use getUnusedRegion and write your results directly there to call setImage(RCRegion*) instead and save a copy if possible.

Image data should be in 8-bit per channel interleaved format.

Definition at line 72 of file DataSource.cc.

void setImage ( RCRegion region  )  [protected]

Sets the current image, for bulk data sources like cameras.

You should not modify data in region until you pass a new region here. However even then, the previous region may still be in processing. Check region reference counts to determine when an old region is available for recycling, or otherwise dereference them after calling this so they will be deallocated after use.

Image data should be in 8-bit per channel interleaved format and the data should be prepended by an ImageHeader structure so the receiver knows how to interpret the data.

Recommended to just use getUnusedRegion() to handle region recycling for you.

Definition at line 180 of file DataSource.h.

Referenced by ImageStreamDriver::readData(), FileSystemImageSource::sendData(), and setImage().

virtual void setImageQueue ( MessageQueueBase mq  )  [virtual]

Called by simulator during initialization to tell the DataSource where it should send image data (if this is selected as an active image data source).

Each image data source (if we get around to supporting such concurrent sources) will have a separate message queue

Definition at line 96 of file DataSource.h.

static void setNeedsSensor ( bool  waiting  )  [static]

will be called by initialization code prior to first getData() if client code is going to block on getting the first sensor reading

Definition at line 99 of file DataSource.h.

Referenced by Simulator::plistValueChanged(), and Simulator::run().

void setOutputValue ( unsigned int  i,
float  v 
) [static, protected]

sets the current value for an output, be sure to register with providingOutput() (and later ignoringOutput()) in order to avoid being clobbered by "blind" feedback from the Motion process

Definition at line 280 of file DataSource.h.

Referenced by SSC32Driver::advance(), DynamixelDriver::provideValues(), PListSensorDriver::readData(), and FileSystemSensorSource::sendData().

void setPIDDutyValue ( unsigned int  i,
float  v 
) [static, protected]

sets the current duty cycle value for a servo joint, i should be relative to PIDJointOffset

Definition at line 294 of file DataSource.h.

Referenced by DynamixelDriver::provideValues(), PListSensorDriver::readData(), and FileSystemSensorSource::sendData().

static void setSensorFramerate ( const plist::Primitive< float > *  senFR  )  [static]

will be called by initialization code to provide a pointer to the sensor synchronization framerate sensorFramerate

Definition at line 102 of file DataSource.h.

Referenced by Simulator::Simulator(), and Simulator::~Simulator().

static void setSensorState ( SensorState senState  )  [static]

Called by simulator during initialization to tell DataSources where the array of sensor values are stored (see sensorState).

This would need to point into a shared memory region if using multi-process model, hence we can't just use process-local static allocation.

Definition at line 92 of file DataSource.h.

Referenced by sim::sim().

void setSensorValue ( unsigned int  i,
float  v 
) [static, protected]

Member Data Documentation

bool frozen [protected]

indicates that data is going to be requested "sparsely"; advance() will be called by simulator at user discretion

Definition at line 201 of file DataSource.h.

Referenced by FileSystemDataSource::advance(), enteringRealtime(), getFrozen(), leavingRealtime(), FileSystemDataSource::resetPoller(), and setFrozen().

assigned by setImageQueue(), calls to setImage() will send messages into this queue

Definition at line 214 of file DataSource.h.

Referenced by setImage(), and setImageQueue().

std::list<RCRegion*> regions [protected]

for efficiency, reuse old buffers via getUnusedRegion() -- oldest at front, most recently used at back

Definition at line 197 of file DataSource.h.

Referenced by getUnusedRegion(), and ~DataSource().

bool requiresFirstSensor = true [static, protected]

if true, indicates that client code is going to wait for sensor readings returned by getData before executing

Definition at line 204 of file DataSource.h.

Referenced by SSC32Driver::advance(), and setNeedsSensor().

const plist::Primitive< float > * sensorFramerate = NULL [static, protected]

Assigned by setSensorFramerate() during initialization, points to the synchronization framerate for sensors.

It is pointless to exceed this framerate for sensor updates, so if you have control over the polling rate, set it to this value.

Definition at line 208 of file DataSource.h.

Referenced by SSC32Driver::doFreeze(), CreateDriver::doFreeze(), SSC32Driver::doUnfreeze(), CreateDriver::doUnfreeze(), SSC32Driver::plistValueChanged(), CreateDriver::plistValueChanged(), and setSensorFramerate().


The documentation for this class was generated from the following files:

Tekkotsu Hardware Abstraction Layer 5.1CVS
Generated Mon May 9 05:01:41 2016 by Doxygen 1.6.3