cccusb

Name

cccusb -- Swig wrapping of the CCCUSB C++ class.

Synopsis

cccusb::CCCUSB_enumerate

cccusb::usb_device_vector_get CCCUSB-enumeration index

cccusb::usb_device_vector_size CCUSB-enumeration

::cccusb::CCCUSB name usb-device

::cccusb::CCCUSB -args usb-device

::cccusb::CCCUSB ?name? -this ptrName

object c

object executeList readout-list maxread

object inhibit

object loadList listNum readout-list

object readDGGA

object readDGGB

object readDGGExt

object readDelays

object readDeviceSourceSelectors

object readFirmware

objectreadGlobalMode

object readLamTriggers

object readLedSelector

object readOutputSelector

object readScalerA

object readScalerB

object readScalerControl

object readUSBBulkTransferSetup

cccusb::CCCUSB_serialNo usb-device

object setDefaultTimeout ms

object simpleControl n a f

object simpleRead16 n a f

object simpleRead24 n a f

object simpleWrite16 n a f d

object simpleWrite24 n a f d

object uninhibit

object writeActionRegister value

object createReadoutList

object writeDGGA value

object writeDGGB value

object writeDGGExt value

object writeDelays value

object writeDeviceSourceSelectors value

object writeGlobalMode value

object writeLamTriggers value

object writeLedSelector value

object writeOutputSelector value

object writeScalerControl value

object writeUSBBulkTransferSetup value

object Z

object -delete

cccusb::string_to_char string-object

::cccusb::uint16_vector_get vector-object index

::cccusb::uint16_vector_size vector-object

DESCRIPTION

This set of commands is a Tcl wrapper around the CCCUSB C++ class (see CCCUSB(3ccusb). The interface consists of several static methods and object sub commands.

The static methods include methods that support device enumeration and construction. Enumeration returns data types that require additional static methods to unpack. See DEVICE ENUMERATION below.

Command lists (see cccusbreadoutlist(3ccusb)) can be executed in immediate mode or loaded. At present the usb bulk read function is not supported so a pure Tcl data taking system cannot yet be written. If you want support for that, request it as that can be added easily enough.

Immediate list execution also produces data types that require additional static member functions to unpack. See LIST EXECUTION below for more information.

COMMAND DETAILS

cccusb::CCCUSB_enumerate

Produces an enumeration of the powered up CC-USB devices attached to the host. The result of this command is a wrapped std::vector<usb_device*> See DEVICE ENUMERATION for recipes for using this result.

cccusb::usb_device_vector_get CCCUSB-enumeration index

Gets a specific element of the return value from cccusb::CCCUSB_enumerate. CCCUSB-enumeration is the value returned from that command. index is the index into the vector. Indices start from 0. See DEVICE ENUMERATION below for some enumeration recipes.

cccusb::usb_device_vector_size CCUSB-enumeration

Returns the size of the enumeration vector CCCUSB-enumeration. This parameter is a value returned from cccusb::CCCUSB_enumerate

See DEVICE ENUMERATION below for some device enumeration recipes.

::cccusb::CCCUSB name usb-device

Constructs a CCCUSB object whose command will be name. usb-device is an element from a device enumeration that was gotten from cccusb::CCCUSB_enumerate.

For recipes involving device enumeration and construction see DEVICE ENUMERATION below.

::cccusb::CCCUSB -args usb-device

Constructs a CCCUSB object with a unique object instance command name chosen by the constructor. usb-device is an element of an enumeration returned from cccusb::CCCUSB_enumerate.

Normally this is used in constructs like e.g:


set controller [cccusb::CCCUSB -args $device]
$controller c
$controller z
                            

For more enumeration and construction recipes see DEVICE ENUMERATION below.

::cccusb::CCCUSB ?name? -this ptrName

Constructs CCCUSB object from an object pointer ptrName. Object pointers are gotten either by requesting the -this from another object or, in the CCUSBReadout framework by being passed in from the framework to a Tcl driver.

If the optional name is provided it will be the object instance command. If not the object instance command will be the value of ptrName

For example.


proc example pointer {
   cccusb::CCCUSB controller -this $pointer
   controller c
   
   cccusb::CCCUSB -this $pointer
   $pointer z
}
                            

object c

Performs a C cyle on the dataway connected to object. object is a CCCUSB object constructed by any of the methods described above.

object executeList readout-list maxread

Executes a cccusbreadoutlist::CCCUSBReadoutList (see cccusbreadoutlist(3ccusb)). readout-list is the name of the list and maxread the maximum number of 16 bit words that can be read by this list (written data is inline in the list). object is a CCCUSB object constructed by any of the methods described above.

The return value is the name of an encapsulated std::vector<uint16_t>. See EXECUTING LISTS for recipes for executing lists and getting data from the result. See as well cccusb::uint16_vector_get, cccusb::uint16_vector_size.

object inhibit

Sets the inhibit line on the CAMAC crate controlled by object. object is a CCCUSB object constructed by any of the methods described above.

object loadList listNum readout-list

Loads a cccusbreadoutlist::CCCUSBReadoutList object for later execution in response to an event or scaler trigger.

object is a CCCUSB object constructed by any of the methods described above. listNum is the number of the list to be loaded. The list numbers is either 0 for the event list or 1 for the scaler list.

readout-list is a cccusbreadoutlist::CCUSBReadoutList object instance name. See cccusbreadoutlist(3ccusb) for information about how to create these.

The command returns 0 on successful completion, a negative number is returned on failure.

object readDGGA

Reads the DGGA register of the CC-USB module represented by object. object is a CCCUSB object constructed by any of the methods described above. The DGGA register controls the width and delay of one of the CC-USB's gate and delay generators. See section 3.3.7 of the CC-USB manual for more information about this register.

object readDGGB

Same as readDGGA but reads the B gate and delay register control register.

object readDGGExt

Reads the CC-USB Gate and delay generated extended range register. See Section 3.3.7 of the CC-USB manual. object is a CCCUSB object constructed by any of the methods described above.

object readDelays

Reads the delays register of the CC-USB. See Section 3.3.3 of the CC-USB manual for a description of this register. object is a CCCUSB object constructed by any of the methods described above.

object readDeviceSourceSelectors

Reads the CCUSB device source selectors register. This is described in section 3.3.6 of the CC-USB manual. object is a CCCUSB object constructed by any of the methods described above.

object readFirmware

Reads the CC-USB firmware id register. The bit fields of this register are described by section 3.3.1 of the CC-USB manual. object is a CCCUSB object constructed by any of the methods described above.

objectreadGlobalMode

Reads the CC-USB global mode register. This register iis described in section 3.3.2 of the CC-USB manual. object is a CCCUSB object constructed by any of the methods described above.

object readLamTriggers

Reads the LAM trigger register. The CC-USB manual calls this register the LAM Mask register and describes it in section 3.3.9. object is a CCCUSB object constructed by any of the methods described above.

object readLedSelector

Reads the LED Selector register. This register is descsribed in section 3.3.5 of the CC-USB manual. object is a CCCUSB object constructed by any of the methods described above.

object readOutputSelector

Reads the output selector register. This register is described in section 3.3.5 of the CC-USB manual. object is a CCCUSB object constructed by any of the methods described above.

object readScalerA

Read the counts in Scaler A. The scalers are described in Section 3.3.8 of the CC-USB manual with how to define what makes them count described in section 3.3.6. object is a CCCUSB object constructed by any of the methods described above.

object readScalerB

Same as readScalerA however the B scaler is read.

object readScalerControl

Read the Scaler readout control register. The CC-USB manual refers to this as the ACS (Auxiliary Camac Stack) register in some places and the Scaler Readout Control register in others. It is described in section 3.3.4 of the manual. object is a CCCUSB object constructed by any of the methods described above.

object readUSBBulkTransferSetup

Reads the USB Bulk transfer setup register. This is described in section 3.3.10 of the CC-USB manual. object is a CCCUSB object constructed by any of the methods described above.

cccusb::CCCUSB_serialNo usb-device

Reads the serial number of the device selected by usb-device. usb-device is a usb device object that comes from one of the elements of the enumerator returned by cccusb::CCCUSB_enumerate. The serial number is returned as a string object handle that must be converte via cccusb::string_to_char. For more information about device enumeration and serial number strings see DEVICE ENUMERATION below.

object setDefaultTimeout ms

Most CC-USB operations require a USB bulk transfer to the CC-USB and a transfder from the CC-USB. These transfers are done with a timeout so that if the target does not respond, the request eventually does terminate. This sets the timeout for those requests to be ms milliseconds. object is a CCCUSB object constructed by any of the methods described above.

object simpleControl n a f

Performs a non-data transfer operation. n specifies the CAMAC slot that will be the target of this operation. a specifies the subaddress and f specifies the function code. The function code must be in one of the ranges: [8..15] [24..31]. The command returns a mask of the Q and X responses from the dataway. See VARIABLES below for the Q and X bits in this mask.

object is a CCCUSB object constructed by any of the methods described above.

object simpleRead16 n a f

Performs a 16 bit read from the module and sub address specified by n and a. The CAMAC function code f must be in the range [0..7].

The command returns the data in the lower 16 bits of the value and the Q/X resonse in the upper byte (bits 24 through 31). Thus to extract the Q/X:


set data [c simpleRead16 1 0 0]
set qx [expr {$data >> 24}]
set data [expr {$data & 0xffff}]
                                

See VARIABLES below for information about the how to extract the Q and X bits from the qx variable in the example above.

object is a CCCUSB object constructed by any of the methods described above.

object simpleRead24 n a f

Same as simpleRead16 above, however the data transferred is 24 bits wide. The Q/X response is still in bits 24 through 31. The example below shows how to extract the data and the Q/X resopnse:


set data [c simpleRead16 1 0 0]
set qx [expr {$data >> 24}]
set data [expr {$data & 0xffffff}]
                                

object is a CCCUSB object constructed by any of the methods described above.

object simpleWrite16 n a f d

Performs a write of the 16 bit data d to the module and subaddress specified by n and a via the CAMAC function code f. f must be in the range [16..23]. The command returns the Q and X mask. See VARIABLES below for information about which bits are Q and which X.

object is a CCCUSB object constructed by any of the methods described above.

object simpleWrite24 n a f d

Same as simpleWrite16 however the bottom 24 bits of d are transferred.

object uninhibit

Removes the dataway inhibit. object is a CCCUSB object constructed by any of the methods described above.

object writeActionRegister value

Writes the CC-USB action register. This register is described in section 3.2.1 of the CC-USB manual. object is a CCCUSB object constructed by any of the methods described above.

object writeDGGA value

Writes value to the control register for Gate and Delay A. This register is described in section 3.3.7 of the CC-USB manual. object is a CCCUSB object constructed by any of the methods described above.

object writeDGGB value

Same as writeDGGA however the control register for gate and delay generator B is written.

object writeDGGExt value

Writes value to the gate and delay extended delay register. See section 3.3.7 of the CC-USB manual for a description of this registers. object is a CCCUSB object constructed by any of the methods described above.

object writeDelays value

Writes value to the delays register. This register is described in section 3.3.3 of the CC-USB manual. object is a CCCUSB object constructed by any of the methods described above.

object writeDeviceSourceSelectors value

Writes value to the device source selector register. This register is described in section 3.3.6 of the CC-USB manual. object is a CCCUSB object constructed by any of the methods described above.

object writeGlobalMode value

Writes value to the global mode register. See section 3.3.2 of the CC-USB manual for a description of this register. object is a CCCUSB object constructed by any of the methods described above.

object writeLamTriggers value

Writes value to the LAM triggers register. The CC-USB manual refers to this register as the LAM Maks register and describes it in section 3.3.9 object is a CCCUSB object constructed by any of the methods described above.

object writeLedSelector value

Writes value to the LED selector register. This register is described in section 3.3.5 of the CC-USB manual. object is a CCCUSB object constructed by any of the methods described above.

object writeOutputSelector value

Writes value to the output selectors register of the CC-USB. This register is described in section 3.3.5 of the CC-USB manual. object is a CCCUSB object constructed by any of the methods described above.

object writeScalerControl value

Writes value to the scaler control register/ACS Control register. This register is described in section 3.3.4 of the CC-USB manual. object is a CCCUSB object constructed by any of the methods described above.

object writeUSBBulkTransferSetup value

Writes value to the USB bulk transfer setup register. Section 3.3.10 of the CC-USB manual describes this register. object is a CCCUSB object constructed by any of the methods described above.

object Z

Performs a Z cycle on the camac dataway. object is a CCCUSB object constructed by any of the methods described above.

object -delete

Deletes a swig wrapper for a CCCUSB wrapper.

cccusb::string_to_char string-object

Returns a Tcl string equivalent of a std::string object identifier string-objecdt. std::string object identifiers are returned from the serialNo method. See DEVICE ENUMERATION below for more information.

::cccusb::uint16_vector_get vector-object index

Returns element index of vector-object where that is an object identifier for a std::vector<uint16_t>. This is required to fetch items out of the data that comes back from the executeList command. For more information see EXECUTING LISTS below.

::cccusb::uint16_vector_size vector-object

Returns the size of vector-object where vector-object is an object identifier for a std::vector<uint16_t>. This is typically used when processing data from running a list. See EXECUTING LISTS Below for more information.

DEVICE ENUMERATION

The USB bus is a hotplug bus. Device enumeration is the process of determining the set of devices plugged into the USB bus at a point in time. The goal of device enumeration is normally to access a specific device of the desired device type. In our case we are interested in creating a CCCUSB object connected to CC-USB with a specific serial number.

If you are using the CCUSBReadout framework, you normally don't need to do this. The framework has already enumerated and opened the device and is passes you the appropriate object id. If you are writing a pure Tcl CC-USB application, you will need to read and understand this section.

The starting point of device enumeration is the cccusb::CCCUSB_enumerate command. This returns an object id for a std::vector<usb_device*>. This is unfortunately not directly accessible in Tcl.

the cccusb package provides two commands to tear apart the return from a call to cccusb::CCCUSB_enumerate:

cccusb::usb_device_vector_size

which returns the size of the returned vector

cccusb::usb_device_vector_get

Which fetches a specific usb_device pointer object id.

Once you have a usb_device pointer object id you can do two things with it. You can obtain the serial number string of the associated CC-USB controller or create a CCCUSB object with which you can perform operations on the controller and the CAMAC modules in its crate.

Normally you want to do both, you want to enumerate the controllers and either match them against a desired serial number or display them for the user to choose. The example below enumerates the CC-USB's and displays their serial numbers on stdout:

Example 1. Listing CC-USB Serial numbers (Tcl).


lappend auto_path /usr/opt/daq/10.1/lib
package require cccusb

set e [cccusb::CCCUSB_enumerate]

set ccount [cccusb::usb_device_vector_size $e]
for {set i 0} {$i < $ccount} {incr i} {
    set usbdev [cccusb::usb_device_vector_get $e $i]
    set serial [cccusb::string_to_char [cccusb::CCCUSB_serialNo $usbdev]]
    puts $serial
}
                

Note how cccusb::usb_device_vector_size and cccusb::usb_device_vector_get are used to get usb_device* object ids. Note as well how a specific object id is then passed to cccusb::CCCUBS_serialNo and the output of that converted to a Tcl string via cccusb::string_to_char

The next example demonstrates a Tcl proc that returns a CCCUSB object command name that is connected to a specific CC-USB specified by serial number or generates an error if that serial number does not exist.

Example 2. Creating a CCCUSB object by serial number (Tcl).


lappend auto_path /usr/opt/daq/10.1/lib
package require cccusb
...
proc openCamac serialNo {
    set e [cccusb::CCCUSB_enumerate]
    set ccount [cccusb::usb_device_vector_size $e]
    for {set i 0} {$i < $ccount} {incr i} {
        set usbdev [cccusb::usb_device_vector_get $e $i]
        set serial [cccusb::string_to_char [cccusb::CCCUSB_serialNo $usbdev]]
        if {$serial eq $serialNo} {
            return [cccusb::CCCUSB -args $usbdev]
        }
    }
    error "No CC-USB with serial number $serialNo is available"
 
}
                

The pattern of this code follows the pattern of the previous example. The only difference is that when the serial number matches the requested serialNo parameter, a CCCUSB object is created. SWIG is allowed to choose the object command (the -args option does that), which is returned to the caller.

EXECUTING LISTS

The CC-USB has the ability to execute list of camac instructions. Immediate list execution is supported by the cccusb package via the executeList command. Lists can also be downloaded to CC-USB memory for execution in data acquisition mode in response to event and scaler triggers. This is supported via the loadList command.

This section describes how to use executeList and how to access any data read by those lists (written data is stored in the list itself). Please refer to CCCUSBReadoutList(3ccusb) for reference material on the Tcl package for constructing these lists.

In order to execute a list on an existing CCCUSB class/command you must

The code fragment below shows how to extract data from the returned data. In it, assume that the variable c holds a CCCUSB object command and the variable l holds the object command of a CCCUSBReadoutList object. The creates a hexadecimal dump of the returned words:


set result [$c executeList $l 1000];   # No more than 1000 wds to read.
set nRead [cccusb::uint16_vector_size $result]
for {set i 0} {$i < $nRead} {incr i} {
     puts [format %x [cccusb::uint16_vector_get $result $i]]
}
                

Note that the executeList requires a number which is the maximum number of uint16_t values that will be read by the list. This is used to allocate the read buffer. The actual count of the words read is then used to fill the vector returned by that command.

VARIABLES

The cccusb package exports the following variables:

cccusb::CCCUSB_X

Contains the mask of the X response in a Q/X word. For the simple control and write operations, you can directly test these bits against the command return value. For simple read operations, you need to take the return value and shift right 24 bits before checking for this bit.

cccusb::CCCUSB_Q

Contain the max of the Q response. See above for how to use it to check for Q responses in operations.

SEE ALSO

CCCUSB(3ccusb) cccusbreadoutlist(3ccusb) CCCUSBReadoutList(3ccusb)