68.7. Writing C++ slow controls device drivers

68.7.2.1.1. The driver class and its implementation

Let's start by looking at the class definition for the driver itself. First we'll give a brief overview of the methods the driver must define. Then we will look at the implementation of each method with an eye towards what the method is expected to do.

class SampleDriver : public CControlHardware           
{
private:
  CControlModule* m_pConfig;                           
public:
  SampleDriver(std::string name);
  virtual ~SampleDriver ();

  // Forbidden methods

private:                                              
  SampleDriver(const SampleDriver& rhs);
  SampleDriver& operator=(const SampleDriver& rhs);
  int operator==(const SampleDriver& rhs);	    
  int operator!=(const SampleDriver& rhs);	    


public:
  virtual void onAttach(CControlModule& configuration); 
  virtual void Initialize(CCCUSB& camac);	            
  virtual std::string Update(CCCUSB& camac);            
  virtual std::string Set(CCCUSB& camac,                
			  std::string parameter, 
			  std::string value);              
  virtual std::string Get(CCCUSB& camac,                
			  std::string parameter);          
  virtual void clone(const CControlHardware& rhs);	    

};
                        

Note that all the methods that are labeled as virtual are pure vitual in the base class. This means that actual, concrete, device drivers must implement them. If one of these methods does not make much sense for your driver, you can implement it as a method that does nothing, but you must implement all virtual methods.

Let's look at the implementation of each of the methods of the class with an eye to the expectations placed on each method by the framework and to what a real driver might have to do to meet those expectations.

SampleDriver::SampleDriver(std::string name) :
  CControlHardware(name),             
  m_pConfig(0)                        
{
  
}
SampleDriver::~SampleDriver()
{}                                   

                        

Usually OnAttach saves a pointer to the CControlModule and defines configuration parameters and their constraints. Our driver is no exception. A normal driver will need to at least define a slot parameter so that the driver instance knows how to address the module it is controlling.

void
SampleDriver::onAttach(CControlModule& configuration) 
{
  m_pConfig = &configuration;                         
  m_pConfig->addIntegerParameter("anint");                
  m_pConfig->addIntListParameter("test", 16);             
  m_pConfig->addBooleanParameter("abool");                
}
                        

Since we have no hardware we don't need to do this:

void
SampleDriver::Initialize(CCCUSB& camac)
{
}
                        

The only remark I want to make here is that the parameter camac allows the method to perform single short CAMAC operations. It also allows the method to execute immediate lists that were built up in a CCCUSBReadoutList object.

The implementation of Update is:

std::string
SampleDriver::Update(CCCUSB& camac)
{
    return "OK";
}
                        

I want to clarify:

1. The camac parameter allows this method to perform CAMAC operations. The method can build immediate lists using the CCCUSBReadoutList and execute them with the camac parameter as well.

2. The return value of the method should either be the string OK which is passed back to the client and indicates the initialization was successful or ERROR which should be followed by an error message that is human readable, indicating the initialization failed. The client usually strips off the ERROR part and displays the remainder.

   A sample error return might be: ERROR No X response, be sure the slot parameter is correct

3. Driver code can be assured that there is no active run when this method is called.

Our driver instance uses its configuration parameters as the settable parameters rather than hardware. Note that when called the Set method can be assured that data taking is not active. If there is an active run, the framework pauses it before calling Set and resumes it when that method returns.

Therefore the implemntation is:

std::string
SampleDriver::Set(CCCUSB& camac, std::string parameter, std::string value)
{
  try {
    m_pConfig->configure(parameter, value);   
  }
  catch(std::string msg) {
    std::string error = "ERROR ";             
    error += msg;

    return error;
  }
  return "OK";                                 
}
                        

Our device uses its configuration parameters to simulate a device state. In a normal driver the driver would interact with the hardware to return the desired state.

Here's our driver's Get implementation:

std::string
SampleDriver::Get(CCCUSB& camac, std::string parameter)
{
  try {
    return m_pConfig->cget(parameter);    
  } catch(std::string msg) {
    std::string error = "ERROR - ";       
    error += msg;
    return error;
  }
  
}
                        

void
SampleDriver::clone(const CControlHardware& rhs)
{
}
                        

If you do try to take on a real implementation of clone you will need to set your internal state to be the same as the object rhs, remember that internal state includes the internal state of superclasses.

The rhs is an object that is guaranteed to be the type as your driver.

68.7.2.1.2. The creator class and its implementation

The creator class is normally a very simple class. It has only two requirements:

• It must be derived from CModuleCreator

• It must provide a functor method (operator()) that creates a named instance of the driver object.

Here is the entire creator for our driver:

class SampleCreator : public CModuleCreator {     
public:
  CControlHardware* operator()(std::string name);
};

CControlHardware*
SampleCreator::operator()(std::string name)
{
  return new SampleDriver(name);                
}
                        

68.7.2.1.3. Driver initialization

Drive initialization is normally relatively simple:

• If you decide to make your driver an actual Tcl package that can be loaded by the package require command, the package must be registered with the Tcl interpreter via a call to Tcl_PkgProvide

• An instance of the creator must be registered with the module factory.

In addition, since at load time the Tcl interpreter computes the name of the initialization function from the name of the shared library or package, the initialization function must:

• Conform to the naming conventions specified in the documentation of the Tcl Load Command.

• Have a C binding via the extern "C" construct so that C++ does not decorate the function name with the function signature.

extern "C" {                                 
int
Sampledriver_Init(Tcl_Interp* pInterp)       
{
  int status;
  
  status = Tcl_PkgProvide(pInterp, "Sampledriver", "1.0");    
  if (status != TCL_OK) {                   
    return status;
  }
  
  CModuleFactory* pFact = CModuleFactory::instance(); 
  pFact->addCreator("sample", new SampleCreator);     
  
  return TCL_OK;
}
}