DataSource Class Reference
abstract base class for simulator data sources More...
#include <DataSource.h>
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:
- constructor - user creates an instance of a DeviceDriver (which creates the data source)
- registerSource() - the user selects the data source via SharedGlobals::StreamSimConfig::sources
- enteringRealtime() - if the simulator enters real time mode
- leavingRealtime() - if the simulator is paused, set to full-speed mode, or begins to shut down
- deregisterSource() - simulator is shutting down or otherwise deleting associated DeviceDriver
- destructor - deleting associated DeviceDriver
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.
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 | |
| DataSource & | operator= (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 RCRegion * | getUnusedRegion (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 Resource & | getSensorWriteLock () |
| 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 | |
| MessageQueueBase * | imageQueue |
| assigned by setImageQueue(), calls to setImage() will send messages into this queue | |
Static Private Attributes | |
| static SensorState * | sensorState = 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] |
user hook for when frozen is set to true; advance() will be called by simulator at user discretion.
Reimplemented in CameraSourceQTKit, CameraSourceQTSG, FileSystemDataSource, CameraDriverPtGrey, CameraDriverV4L2, CreateDriver, DataStreamDriver, DynamixelDriver, RGBSource, DepthSource, KobukiDriver, SkewlZoneDriver, SSC32Driver, DataCache, Subscription< PListSensorDriver >, and Subscription< ImageStreamDriver >.
Definition at line 199 of file DataSource.h.
Referenced by leavingRealtime(), and setFrozen().
| virtual void doUnfreeze | ( | ) | [protected, virtual] |
user hook for when frozen is set to false; if enteringRealtime() has been called then you should resume sending data.
Reimplemented in CameraSourceQTKit, CameraSourceQTSG, FileSystemDataSource, CameraDriverPtGrey, CameraDriverV4L2, CreateDriver, DataStreamDriver, DynamixelDriver, RGBSource, DepthSource, KobukiDriver, SkewlZoneDriver, SSC32Driver, DataCache, Subscription< PListSensorDriver >, and Subscription< ImageStreamDriver >.
Definition at line 200 of file DataSource.h.
Referenced by enteringRealtime(), and setFrozen().
| 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] |
sets the current value for a button
Definition at line 291 of file DataSource.h.
Referenced by SSC32Driver::advance(), CreateDriver::advance(), PListSensorDriver::readData(), FileSystemSensorSource::sendData(), and SensorStateAccessor::set().
| 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] |
sets the current value for a sensor
Definition at line 288 of file DataSource.h.
Referenced by SSC32Driver::advance(), CreateDriver::advance(), DynamixelDriver::provideValues(), PListSensorDriver::readData(), FileSystemSensorSource::sendData(), and SensorStateAccessor::set().
Member Data Documentation
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().
MessageQueueBase* imageQueue [private] |
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().
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().
SensorState * sensorState = NULL [static, private] |
Definition at line 211 of file DataSource.h.
Referenced by getButtonValue(), getOutputValue(), getPIDDutyValue(), getSensorFrameNumber(), getSensorValue(), getSensorWriteLock(), ignoringOutput(), providingOutput(), setButtonValue(), setOutputValue(), setPIDDutyValue(), setSensorState(), and setSensorValue().
The documentation for this class was generated from the following files:
