OpenPET Software Interface

OpenPET provides a number of example Python scripts that can be used to operate the OpenPET system. However, developers may create their own scripts with additional functionality or rewrite the scripts in a different language. Please note that if these scripts are rewritten in a different language, the OpenPET library must also be rewritten or compiled such that it can be read by the new language. OpenPET uses Python’s logging functionality to print status messages throughout the script, but this is optional when recreating the script although it is useful.

Warning

While developers are given the freedom to rewrite in a different language or add onto the existing scripts, the basic configuration sequence laid out by these examples is crucial and should not be changed.

QuickUSB

Simple Scope Example

This is a basic example that acquires data in scope mode using QuickUSB. The sequence of steps are outlined and described below.

  1. Create an OpenPET object
op = OpenPET()
  1. Initialize QuickUSB with the desired module
op.qusb = op.init_qusb()

In this example, the default QuickUSB deviceIndex (0) is used. One can also use deviceIndex 2 by putting 2 as the function argument.

op.qusb = op.init_qusb(2)
  1. Set data acquisition duration in seconds, partial seconds are OK
op.d_acq_t = 10

Here, we set the acquisition time to 10 seconds.

  1. Set Scope mode settings payload
oscpayload = 0x02000101

In this example, we set the settings for scope mode to be 16 samples, 0 before trigger, and 2 trigger window. For more information on this payload, please see Command ID: 0x0005.

  1. Set target address and broadcast bit
trgt = 0x8003

In this example, we set the broadcast bit to 1 and the target to be DB 3.

  1. Set mode to scope mode (payload = 0x1)
op.openpet_cmd(0x0003, trgt, 0x00000001)
  1. Set scope mode settings
op.openpet_cmd(0x0005, trgt, oscpayload)

This sets the scope mode settings to the predefined values set in step 4. The target address is set in step 5. One can also read back the scope mode settings to check that they are correct as shown below.

cmd, srcp, dst, pyld = op.openpet_cmd(0x0006, trgt, 0)
  1. Acquire data
op.getdata()

In this example, the default settings of this function are used. Namely, the Acquisition Action is set to Reset and then Run by default at the beginning and set to Reset at the end.

Note

The default ADC and DAC configurations are used in this example.

Intermediate Scope Example

This next example is more complex than the previous one in that some configurations that were left as default are now manually changed. The basic structure remains the same.

  1. Create an OpenPET object
op = OpenPET()
  1. Initialize QuickUSB with the desired module
op.qusb = op.init_qusb()

In this example, the default QuickUSB deviceIndex (0) is used. One can also use deviceIndex 2 by putting 2 as the function argument.

op.qusb = op.init_qusb(2)
  1. (Optional) Change autogenerated file name
op.ofilename = "test.openpetd"
  1. Set data acquisition duration in seconds, partial seconds are OK
op.d_acq_t = 10

Here, we set the acquisition time to 10 seconds.

  1. Set the scope mode settings payload
osc_stg_pld = op.set_osc_stg_payload(win,btg,smp,fmt)

The arguments used here are integer variables that can be set to create the desired payload. For a more detailed explanation, see OpenPET Library Functions

  1. Set target address and broadcast bit
trgt = 0x8003

In this example, we set the broadcast bit to 1 and the target to be DB 3.

  1. Change ADC settings

Instead of keeping the default settings that are configured on powerup, the ADC settings can be changed by sending OpenPET commands. For example, the command below says to write to the “ADS5282” chip to output PAT_DESKEW fixed pattern on DB 6:

op.openpet_cmd(0x0104, 0x0006, 0x81140001)

One can also reset the ADC using the command ID 0x0103.

Additionally, the gain can be changed. More explanation on the payload for changing the gain can be found here. The example below changes the gain on DB 1 to 6dB for channels 4 to 7 with broadcasting.

op.openpet_cmd(0x0104, 0x0001, 0x80AC6666)
  1. Change DAC settings

The DAC settings can also be changed if desired. The example below tells the system to write to the DAC to set the energy threshold to 200mV on the set target address which in this case is DB 3.

op.openpet_cmd(0x0106, trgt, 0x8007E032)

There are also helper functions to determine what the payload should be for a given threshold value. First, set the timing and energy DAC mV threshold values. Then use the function get_dac_bits() to convert those mV threshold values into payloads. Once the payloads are created, the DAC can settings can be changed. An example of this process is below.

op.d_tdac_v = 100 # timing DAC threshold 100 mV range [0, 2500]mV
op.d_edac_v = 4096 # energy DAC threshold 100 mV range [0, 4096]mV
energydacpayload = 0x8007E000|op.get_dac_bits(dactype=1)
timingdacpayload = 0x8807E000|op.get_dac_bits(dactype=0)
op.openpet_cmd(0x0106, trgt, energydacpayload)
op.openpet_cmd(0x0106, trgt, timingdacpayload)
  1. Set Acquisition Action to Reset.
op.openpet_cmd(0x0007, trgt, 0)

This is used to clear previous buffers, FIFOs, and registers in firmware.

Warning

This does not reset external peripheral devices like DAC and ADC settings

  1. Set firmware threshold
op.openpet_cmd(0x0108, trgt, fwth)

This sets the firmware threshold to a specific value on the target detector board. To double check that the correct value was set, the payload can be read back using the following command.

cmd, srcp, dst, pyld = op.openpet_cmd(0x0109, trgt, 0)

For more information on how to set the firmware threshold, see Command ID: 0x0108.

  1. Set mode to scope mode (payload = 0x1)
op.openpet_cmd(0x0003, trgt, 0x00000001)

To double check that the mode was set correctly, one can read back the mode setting from the target or from a different detector board as shown below:

cmd, srcp, dst, pyld = op.openpet_cmd(0x0004, trgt, 0)
cmd, srcp, dst, pyld = op.openpet_cmd(0x0004, 0x0001, 0)
  1. Set scope mode settings
op.openpet_cmd(0x0005, trgt, osc_stg_pld)

The command above sets the scope mode settings to the previously generated payload. To double check that the settings are correct, read back scope mode settings.

cmd, srcp, dst, pyld = op.openpet_cmd(0x0006, trgt, 0)

If the scope mode settings are read back, there are two options. You can exit the system or reset the scope mode settings with the new values set by the firmware. Below is an example of setting the new values from the firmware.

w,b,s,f = op.resolve_osc_stg_payload(pyld) # Get values from payload that was read back
op.set_osc_stg_payload(w,b,s,f) # Set those new values
  1. Set trigger mask

In this example, we show how to set the hardware trigger mask. The command sequence below outlines the basic command flow. First, turn all the channels on and reset the TDC and calibrate it. After the TDC calibrates, give the command to run the TDC control register. To double check, one can read back the current TDC control register. All these commands are sent to the target detector board.

op.openpet_cmd(0x0009, trgt, 0xFFFFFFFF) # All channels are ON
op.openpet_cmd(0x0101, trgt, 0x00000080) # Write TDC reset
op.openpet_cmd(0x0101, trgt, 0x00000002) # Write TDC calibration
time.sleep(5) # TDC calibrate for 5 sec
op.openpet_cmd(0x0101, trgt, 0x00000004) # Write TDC ctrl
cmd, srcp, dst, pyld = op.openpet_cmd(0x0102, trgt, 0) # read back tdc ctrl
  1. Set Acquisition Action to Run

By default, the getdata() function will set the acquisition action to Run. However, it can also be done manually as shown here.

op.openpet_cmd(0x0007, trgt, 0x00000002)
  1. Acquire data

Since the default functionality of getdata is not being used in this example, the argument of getdata is 0. In this example, we manually set the Acquisition Action to Reset and Run instead of doing it in the getdata function.

op.getdata(0)
  1. Set Acquisition Action to Stop
op.openpet_cmd(0x0007, trgt, 0x00000001)

This command allows the user to tell the firmware to pause. This allows you to resume data acquisition without flushing the FIFOs in the FPGAs. However, if you do want to flush the FIFOs, simply set Action to reset and then run.

You can also check that the firmware has actually stopped by using the command below.

cmd, srcp, dst, pyld = op.openpet_cmd(0x0008, trgt, 0)

If the returned payload is correct, then it has stopped.

Simple Singles Example

This is a basic example that acquires data in singles mode using QuickUSB. The sequence of steps are outlined and described below.

  1. Create an OpenPET object
op = OpenPET()
  1. Initialize QuickUSB with the desired module
op.qusb = op.init_qusb()

In this example, the default QuickUSB deviceIndex (0) is used. One can also use deviceIndex 2 by putting 2 as the function argument.

op.qusb = op.init_qusb(2)
  1. Set data acquisition duration in seconds, partial seconds are OK
op.d_acq_t = 10

Here, we set the acquisition time to 10 seconds.

  1. Set Singles mode settings payload
oscpayload = 0x00000006

This sets the singles mode settings so that it will integrate over 6 ADC samples. For more information on this payload, please see Command ID: 0x0005.

  1. Set target address and broadcast bit
trgt = 0x8003

In this example, we set the broadcast bit to 1 and the target to be DB 3.

  1. Set mode to singles mode (payload = 0x2)
op.openpet_cmd(0x0003, trgt, 0x00000002)
  1. Set singles mode settings
op.openpet_cmd(0x0005, trgt, oscpayload)

This sets the scope mode settings to the predefined values set in step 4. The target address is set in step 5. One can also read back the scope mode settings to check that they are correct as shown below.

cmd, srcp, dst, pyld = op.openpet_cmd(0x0006, trgt, 0)
  1. Acquire data
op.getdata()

In this example, the default settings of this function are used. Namely, the Acquisition Action is set to Reset and then Run by default at the beginning and set to Reset at the end.

Note

The default ADC and DAC configurations are used in this example.

Ethernet

Simple Scope Example

This is a basic example that acquires data in scope mode using an Ethernet connection. The sequence of steps are outlined and described below.

  1. Create an OpenPET object
op = OpenPET()
  1. Initialize Ethernet
op.eth = op.init_eth(None,'10.10.10.2')

The destination IP is 10.10.10.2, and OpenPET will automatically find the correct ethernet interface.

  1. Set data acquisition duration in seconds, partial seconds are OK
op.d_acq_t = 10

Here, we set the acquisition time to 10 seconds.

  1. Set Scope mode settings payload
oscpayload = 0x02000101

In this example, we set the settings for scope mode to be 16 samples, 0 before trigger, and 2 trigger window. For more information on this payload, please see Command ID: 0x0005.

  1. Set target address and broadcast bit
trgt = 0x8003

In this example, we set the broadcast bit to 1 and the target to be DB 3.

  1. Set mode to scope mode (payload = 0x1)
op.openpet_cmd(0x0003, trgt, 0x00000001)
  1. Set scope mode settings
op.openpet_cmd(0x0005, trgt, oscpayload)

This sets the scope mode settings to the predefined values set in step 4. The target address is set in step 5. One can also read back the scope mode settings to check that they are correct as shown below.

cmd, srcp, dst, pyld = op.openpet_cmd(0x0006, trgt, 0)
  1. Acquire data
op.getdata()

In this example, the default settings of this function are used. Namely, the Acquisition Action is set to Rest and Run by default at the beginning and set to Reset at the end.

Note

The default ADC and DAC configurations are used in this example.

Intermediate Scope Example

Again, here is a more complex example using an Ethernet connection. The basic structure remains the same.

  1. Create an OpenPET object
op = OpenPET()
  1. Initialize Ethernet
op.eth = op.init_eth(None,'10.10.10.2')

The destination IP is 10.10.10.2, and OpenPET will automatically find the correct ethernet interface.

  1. (Optional) Change autogenerated file name
op.ofilename = "test.openpetd"
  1. Set data acquisition duration in seconds, partial seconds are OK
op.d_acq_t = 10

Here, we set the acquisition time to 10 seconds.

  1. Set the scope mode settings payload
osc_stg_pld = op.set_osc_stg_payload(win,btg,smp,fmt)

The arguments used here are integer variables that can be set to create the desired payload. For a more detailed explanation, see OpenPET Library Functions

  1. Set target address and broadcast bit
trgt = 0x8001

In this example, we set the broadcast bit to 1 and the target to be DB 1.

  1. Change ADC settings

Instead of keeping the default settings that are configured on powerup, the ADC settings can be changed by sending OpenPET commands. For example, the command below says to write to the “ADS5282” chip to output PAT_DESKEW fixed pattern on DB 6:

op.openpet_cmd(0x0104, 0x0006, 0x81140001)

One can also reset the ADC using the command ID 0x0103.

Additionally, the gain can be changed. More explanation on the payload for changing the gain can be found here. The example below changes the gain on DB 3 to 12dB for channels 8 to 11 without broadcasting.

op.openpet_cmd(0x0104, 0x0003, 0x08A8CCCC)
  1. Change DAC settings

The DAC settings can also be modified. The example below tells the system to write to the DAC to set the energy threshold to 200mV on the set target address which in this case is DB 1.

op.openpet_cmd(0x0106, trgt, 0x8007E032)

There are also helper functions to determine what the payload should be for a given threshold value. First, set the timing and energy DAC mV threshold values. Then use the function get_dac_bits() to convert those mV threshold values into payloads. Once the payloads are created, the DAC can settings can be changed. An example of this process is below.

op.d_tdac_v = 100 # timing DAC threshold 100 mV range [0, 2500]mV
op.d_edac_v = 4096 # energy DAC threshold 100 mV range [0, 4096]mV
energydacpayload = 0x8007E000|op.get_dac_bits(dactype=1)
timingdacpayload = 0x8807E000|op.get_dac_bits(dactype=0)
op.openpet_cmd(0x0106, trgt, energydacpayload)
op.openpet_cmd(0x0106, trgt, timingdacpayload)
  1. Set Acquisition Action to Reset.
op.openpet_cmd(0x0007, trgt, 0)

This is used to clear previous buffers, FIFOs, and registers in firmware.

Warning

This does not reset external peripheral devices like DAC and ADC settings

  1. Set firmware threshold
op.openpet_cmd(0x0108, trgt, fwth)

This sets the firmware threshold to a specific value on the target detector board. To double check that the correct value was set, the payload can be read back using the following command.

cmd, srcp, dst, pyld = op.openpet_cmd(0x0109, trgt, 0)

For more information on how to set the firmware threshold, see Command ID: 0x0108.

  1. Set mode to scope mode (payload = 0x1)
op.openpet_cmd(0x0003, trgt, 0x00000001)

To double check that the mode was set correctly, one can read back the mode setting from the target or from a different detector board:

cmd, srcp, dst, pyld = op.openpet_cmd(0x0004, trgt, 0)
  1. Set scope mode settings
op.openpet_cmd(0x0005, trgt, osc_stg_pld)

The command above sets the scope mode settings to the previously generated payload. To double check that the settings are correct, read back scope mode settings.

cmd, srcp, dst, pyld = op.openpet_cmd(0x0006, trgt, 0)

If the scope mode settings are read back, there are two options. You can exit the system or reset the scope mode settings with the new values set by the firmware. Below is an example of setting the new values from the firmware.

w,b,s,f = op.resolve_osc_stg_payload(pyld) # Get values from payload that was read back
op.set_osc_stg_payload(w,b,s,f) # Set those new values
  1. Set trigger mask

In this example, we show how to set the trigger mask. The command sequence below outlines the basic command flow. First, turn all the channels on and reset the TDC and calibrate it. After the TDC calibrates, give the command to run the TDC control register. To double check, one can read back the current TDC control register. All these commands are sent to the target detector board.

op.openpet_cmd(0x0009, trgt, 0xFFFFFFFF) # All channels are ON
op.openpet_cmd(0x0101, trgt, 0x00000080) # Write TDC reset
op.openpet_cmd(0x0101, trgt, 0x00000002) # Write TDC calibration
time.sleep(5) # TDC calibrate for 5 sec
op.openpet_cmd(0x0101, trgt, 0x00000004) # Write TDC ctrl
cmd, srcp, dst, pyld = op.openpet_cmd(0x0102, trgt, 0) # read back tdc ctrl
  1. Set Acquisition Action to Run

By default, the getdata() function will set the acquisition action to Run. However, it can also be done manually as shown here.

op.openpet_cmd(0x0007, trgt, 0x00000002)
  1. Acquire data

Since the default functionality of getdata is not being used in this example, the argument of getdata is 0. In this example, we manually set the Acquisition Action to Reset and Run instead of doing it in the getdata function.

op.getdata(0)
  1. Set Acquisition Action to Stop
op.openpet_cmd(0x0007, trgt, 0x00000001)

This command allows the user to tell the firmware to pause, allowing you to resume data acquisition without flushing the FIFOs in the FPGAs. However, if you do want to flush the FIFOs, simply set Action to reset and then run.

You can also check that the firmware has actually stopped by using the command below.

cmd, srcp, dst, pyld = op.openpet_cmd(0x0008, trgt, 0)

If the returned payload is correct, then it has stopped.