fsc2: 6.16 Event Counter Functions

6.16 Event Counter Functions

Currently only a module for one event counter exists:

ni6601: National Instruments GPCT 6601, allows counting and creation of pulses

To use the module in an experiment put its name into the DEVICES section of the EDL script.

Use of this card requires that a kernel module and an additional library (both coming with fsc2) have been successfully installed.

List of event counter functions:

`counter_name()'
`counter_start_continuous_counter()'
`counter_start_timed_counter()'
`counter_timed_count()'
`counter_intermediate_count()'
`counter_final_count()'
`counter_start_buffered_counter()'
`counter_get_buffered_counts()'
`counter_stop_counter()'
`counter_single_pulse()'
`counter_continuous_pulses()'
`counter_dio_read()'
`counter_dio_write()'

Descriptions of event counter functions:

`counter_name()'

Returns a string with the name of the event counter being used.

`counter_start_continuous_counter()'

This functions starts one of the counters of the card. The counter will count until it is stopped by a call of the EDL function counter_stop_counter(). It requires at least one argument, the counter to be used, which needs to be specified by one of the symbolic names between CH0 and CH3 (please don't use numbers directly, the mapping between the symbolic values and channel numbers is non-trivial). If the requested counter is already running the function will fail.

If called without a further argument the counter will count events on its default input. Alternatively, as a second argument the source of events to be counted can be specified by one of the following symbolic names: DEFAULT_SOURCE (which is what would be used if no second argument is specified), SOURCE_0 to SOURCE_3 (the default input sources for channel 0 to 3), NEXT_GATE (the gate input for the adjacent counter, where the adjacent counter for channel 0 is channel 1 and vice versa, and channels 2 and 3 also make up a pair) and TIMEBASE_1 and TIMEBASE_2 (the internal timebases of 20 MHz and 100 kHz).

The function can only be used in the EXPERIMENT section of an EDL script.

`counter_start_timed_counter()'

This function starts one of the counters of the card. The counter will count for a specified time and then stops automatically. It requires at least two arguments, the counter to be used, specified by a symbolic name between CH0 and CH3. If the requested counter is already running the function will fail. The second required argument is the length of time the counter is supposed to count. This time must be between 100 ns and about 214.748 s and must be an integer multiple of 50 ns.

Please note:: This function requires not only one counter channel, i.e. the one passed to the function as the first argument, but also a second, adjacent counter. If CH0 is specified as the counter channel also CH1 will be needed and vice versa, and if CH2 is specified also CH3 is required and vice versa. If the adjacent counter is already in use for some other purpose the function fails.

If called without a further argument the counter will count events on its default input. Alternatively, as a second argument, the source of events to be counted can be specified by one of the following symbolic names: DEFAULT_SOURCE (which is what would be used if no second argument is specified), SOURCE_1 to SOURCE_3 (the default input sources for channel 0 to 3), NEXT_GATE (the gate input for the adjacent counter, where the adjacent counter for channel 0 is channel 1 and vice versa, and channels 2 and 3 also make up a pair) and TIMEBASE_1 and TIMEBASE_2 (the internal timebases of 20 MHz and 100 kHz).

The function can only be used in the EXPERIMENT section of an EDL script.

`counter_timed_count()'

This function is very similar to the previous function, counter_start_timed_counter(), i.e. it runs a counter for a specified of time, but in contrast it waits for the requested duration of time and only then returns with the masured count. In every other respect, e.g. the required arguments etc. it is identical to the previous function.

The largest value that can be returned is 2147483647, i.e. 2^31 - 1.

The function can only be used in the EXPERIMENT section of an EDL script.

`counter_intermediate_count()'

The function returns the current value of a counter. The counter may still be running, in which case each call of the function will return an updated value according to the number of events that happened between invocations of the function. The function requires one argument, the counter for which the current value is to be returned. It must be specified by one of the symbolic names between CH0 and CH3 (please don't use numbers directly, the mapping between the symbolic values and channel numbers is non-trivial).

The largest value that can be returned for a counter is 2147483647, i.e. 2^31 - 1.

The function can only be used in the EXPERIMENT section of an EDL script.

`counter_final_count()'

This function waits for an counter to stop and only then returns the final value of the counter. Trying to call this function on a counter that has been started by the function counter_start_continuous_counter() and hasn't already been stopped will fail, because such a counter will never stop by itself.

The function requires one argument, the counter for which the current value is to be returned. It must be specified by one of the symbolic names between CH0 and CH3 (please don't use numbers directly, the mapping between the symbolic values and channel numbers is non-trivial).

The largest value that can be returned for a counter is 2147483647, i.e. 2^31 - 1.

The function can only be used in the EXPERIMENT section of an EDL script.

`counter_start_buffered_counter()'

The function starts a counter, counting repeatedly for a specified time, restarting from 0 at the end of the specified time. It can run in continuous or non-continuous mode. In the first case acquisitions will repeated until the counter is explicitely stopped while in the second case the counter stops after a certain number of data points have been acquired.

The first argument the function expects is the number of the counter It must be specified by one of the symbolic names between CH0 and CH3 (please don't use numbers directly, the mapping between the symbolic values and channel numbers is non-trivial). If the requested counter is already running the function will fail. Moreover, only a single counter can be used as a buffered counter at once.

Please note:: This function requires not only one counter channel, i.e. the one passed to the function as the first argument, but also a second, adjacent counter. If CH0 is specified as the counter channel also CH1 will be needed and vice versa, and if CH2 is specified also CH3 is required and vice versa. If the adjacent counter is already in use for some other purpose the function fails.

The second required argument is the length of time the counter is suppose to count before being reset to 0. This time must be between 100 ns and about 214.748 s and must be an integer multiple of 50 ns.

If called without a further argument the counter will count events on its default input and will run in continuous mode.

Alternatively, if the third argument is a number (or symbolic name) it is taken to be the source of events to be counted which can be specified by one of the following symbolic names: DEFAULT_SOURCE (which is what would be used if no second argument is specified), SOURCE_1 to SOURCE_3 (the default input sources for channel 0 to 3), NEXT_GATE (the gate input for the adjacent counter, where the adjacent counter for channel 0 is channel 1 and vice versa, and channels 2 and 3 also make up a pair) and TIMEBASE_1 and TIMEBASE_2 (the internal timebases of 20 MHz and 100 kHz).

If the third argument or, if a source was specified, the fourth argument must be a string, either "CONTINUOUS" or "NON-CONTINUOUS", telling if the counter sshould run in continuous or non-continuous mode.

If it is to be run in non-continuous mode another argument is required, the number of data points to acquire, which obviously must be larger than 0.

Also in continuos mode another argument can be specified, the number of points to be used for the internal buffers (or 0 to explicitely tell the program to use a default value which is either 1 second worth of data or 1024 points, whatever is larger).

Using a buffered counter should be done only with some care and after running several checks. There are two potential problems: if the time teh counter is running between resets is too short for the computer to keep up the acquisition automatically gets stopped and when trying to fetch data the EDL-script will automatically abort. Moreover, when running in continuous mode, also the internal buffer may overflow if data are produced at a high rate and not fetched from within the script fast enough. Also in this case the script will abort when trying to fetch data. It's rather difficult to estimate what is too fast since it may depend a lot on the resources of the computer used and ho much workload there is. Careful tests with the system under usual load is recommended before using buffered counting for important experiments.

The data acquired by a buffered counter have to be fetched via the function counter_get_buffered_counts().

When done with a buffered counter it is required that the function counter_stop_counter() is called.

The function can only be used in the EXPERIMENT section of an EDL script.

`counter_get_buffered_counts()'

This function is for fetching data from a buffered counter. A buffered counter produces a (possibly conntinuos if running in continuous mode) stream of data which get returned by this function.

The second argument must be the maximum number of points to be fetched. This may be 0, indicating in the case of a continuously running acquisition that there is going to be another argument, indication for how long to wait for more data at most, in which case as many data get returned as were available during that time. For a non-continuous buffered acquisition (when no time limit is specified) a zero number of points means that all (remaining) data points are to be returned, with the function waiting for the counter to stop.

The third argument is the time the function waits for data. It must be given in continuous mode when the number of points is set to 0, otherwise it is optional. It is a time in seconds with a maximum of about 4294 s and a granularity of microseconds. If given the function returns only as many points as became available during that time. It can be be 0.0 to indicate that the function should not wait at all and only return the data points available at the time of the call. If the argument is missing the function only returns when as many data as requested have become available or all data are fetched..

The function returns an array of data points to the EDL-script. The length of the array depends on the the specified maximum number of points and the maximum time to wait for points. The length can also be 0 either because no points were available at all within the specified time limit or because all data points already had been fetched (in the case of a non-continuous acquisition).

The largest value that can be returned is 2147483647, i.e. 2^31 - 1.

If during the call it is detected that either the computer could not keep up with the rate data were acquired or, in continuous mode, the internal buffers did overflow, the experiment gets aborted.

The function can only be used in the EXPERIMENT section of an EDL script.

`counter_stop_counter()'

This function can be used to stop a counter independently of the purpose (i.e. counting or pulse train creation, see below) it was started for. It requires one argument, the counter to be stopped. It must be specified by one of the symbolic values between CH0 and CH3 (please don't use numbers directly, the mapping between the symbolic values and channel numbers is non-trivial).

The function can only be used in the EXPERIMENT section of an EDL script.

`counter_single_pulse()'

Beside being used as event counters the counters can also be used to create pulses on its default output port. This function can be used to create a single pulse on the output port. It requires two arguments, the first being the counter to be used, specified by a symbolic value between CH0 and CH3. If the requested counter is already running the function will fail. The second argument is the length of the pulse, which must be between 100 ns and about 214.748 s and must be an integer multiple of 50 ns.

The function can only be used in the EXPERIMENT section of an EDL script.

`counter_continuous_pulses()'

This function allows to create a continuous train of pulses. It requires at least two arguments, the first being the counter to be used, specified by a symbolic value between CH0 and CH3. If the requested counter is already running the function will fail. The second argument is the length of the pulse, which must be between 100 ns and about 214.748 s and must be an integer multiple of 50 ns.

If no third argument is specified the distance between pulses will be identical to the pulse length (resulting in a pulse frequency of twice the value of the second argument). By specifying a third argument (with the same restrictions as for the second argument) the distance between pulses can be set.

To stop creation of pulses (and to free the counter for other uses) the function counter_stop_counter() must be called.

The function can only be used in the EXPERIMENT section of an EDL script.

`counter_dio_read()'

Beside counters the card also can do digital input and output. There are 8 lines that can be monitored or set. Using this function the current state of any subset of these 8 lines can be determined. If the function is called without an argument the state of all lines is returned, with the lowest bit of the number returned being the state of the lowest numbered DIO line, the seond-lowest bit of the number standing for the second-lowest numbered DIO line etc. If all lines are set the returned value is thus 255.

If an integer argument gets passed to the function it is taken as a mask, determining which of the DIO lines are to be treated as input lines. The lowest bit of the mask stands for the lowest numbered DIO line, the second-lowest bit of the mask for the second-lowest DIO line etc. Thus, by specifying a mask of value of 1 the state of only the DIO line numbered 0 would be returned, for a mask of value of 2 the state of DIO line 1, for 4 DIO line 2 etc. By adding values for different DIO lines a subset of the DIO lines can be specified. Simple arithmetics show that the value of the mask must be between 0 (no DIO lines selected) and 255 (all DIO lines selected, which is the default). All bits in the resulting return value for which bits in the mask ae not set will be returned as being set to 0.

The function can only be used in the EXPERIMENT section of an EDL script.

`counter_dio_write()'

The 8 DIO lines of the card can not only be monitored (see the previous function, counter_dio_read()) but also set, which this function is to be used for. The function requires at least one integer argument, defining the states of the DIO lines to be set to. To output a high voltage at one of the DIO lines the corresponding bit of the value must be set. The lowest bit of the value corresponds to the lowest numbered DIO line, the second-lowest bit to the second-lowest numbered DIO line etc. To only set the lowest numbered DIO line the value passed to the function would have to be 1, to set only the second-lowest numbered DIO line the value would be 2, to set only the third-lowest numbered DIO line a value of 4 would be used. By combining these values for the different DIO lines a certain output pattern can be set for all DIO lines. Obviously, the allowed values are restricted to the range between 0 (all DIO lines in low state) to 255 (all DIO lines in high state).

Without a second argument all 8 DIO lines are switched to output mode and the states of the lines set according to the value of the first argument. But by passing the function a mask value as the second argument only a certain subset of the DIO lines will be set to output mode, thus allowing to have some of the DIO lines for output, while the can be used as input lines. Each set bit in the mask will switch the corresponding lines to output state while not changing mode for the lines for which no bit is set in the mask. Bits in the first argument for which no bit is set in the second argument will be not used, i.e. don't influence the state of the DIO lines.

The function can only be used in the EXPERIMENT section of an EDL script.

This document was generated by Jens Thoms Toerring on September 6, 2017 using texi2html 1.82.