DP5 Programmer’s Guide

Amptek Inc.

14 Deangelo Drive, Bedford, MA 01730

PH: +1 781 275 2242 FAX: +1 781 275 3470

[email protected] www.amptek.com

Note: This document applies to the Amptek DP5, PX5, DP5G, and products derived from these (X123SDD, Gamma-Rad5).

Table of Contents

1Change List

Programmer’s Guide A5 is released with firmware version FW6.06.5, FPGA version FP5.13, and Visual Basic Demo v2.60.

1.1Programmer’s Guide Rev A7 (this document)

1.2Programmer’s Guide Rev A6 (this document)

1.3Programmer’s Guide Rev A5

1.4Programmer’s Guide Rev A4

1.5FW6.06.07/FP6.01

1.6FW6.06.06 / FP6.00

1.7FW6.06.05 / FP5.13

1.8FW6.06.04

1.9FW6.06.03

1.10FW6.06.02

1.11FW6.06.01

1.12FW6.06.00 / FP5.11

1.13FW6.05 / FP5.10

1.14FW6.04 / FP5.10

1.15FW6.03 / FP5.10

1.16FW6.02 / FP5.09

Feedback on this firmware, documentation, and VB demo should be sent to Dave Sperry, [email protected].

2Installation

2.1Uploading the new firmware FW 6.06 (and FP5.11)

This only needs to be performed if upgrading a DP5 or X123 from FW5.xx to FW6.xx. Only RS232 can be used to perform this upgrade. Once a DP5 has FW6.00 or later installed, the VB Demo application can be used to upload new firmware via any interface. After this upgrade is complete the DP5/X123 is no longer compatible with ADMCA, or the DP5Loader application; it must be used with the DPPMCA or new VB Demo applications.

[THIS SECTION IS OBSOLETE. A NEW FIRMWARE LOADER APPLICATION IS AVAILABLE ON THE AMPTEK WEBSITE, WWW.AMPTEK.COM/UPLOADER.ZIP.]

The ZIP file containing the firmware and utilities need to be unzipped on to a local hard drive.

1. Install the DP5Loader application by running SETUP.EXE from \DP5 Upload Utility\SWSETUP.

2. Connect the DP5/X123 to the PC with an RS232 cable. (The RS232 cable has a 9-pin ‘D’ connector on the PC end, and a 2.5mm stereo plug on the DP5 end.)

3. Apply power to the DP5.

4. Run the DP5Loader application.

5. Select the COM port the DP5/X123 is connected to. Click the ‘Check Device Communications’ button. If it locates the DP5/X123, then…

6. Select the Upload Type as FPGA, click ‘Upload FPGA/uC HEX File’, and select ‘_dp5_fpga_v511.mcs’ from wherever the ZIP file was unzipped

7. When the upload completes, it says the power needs to be cycled on the DP5 – this isn’t necessary, but the DP5Loader application has to be closed and reloaded.

8. Once DP5Loader is restarted, click ‘Check Device Comm…’ again. Then select ‘uC’ for Upload Type, click ‘Upload FPGA/uC HEX File’ and select ‘DP5_v6.06.00.hex’ from wherever the ZIP file was unzipped. Wait a few seconds after completion before removing power from the DP5/X123.

9. Now, when you power-cycle the DP5, it will be running the new firmware (and is no longer compatible with the DP5Loader application or ADMCA).

10. You can leave the RS232 cable connected to verify communications either with the VB Demo or with the DPPMCA application, before moving on to USB or Ethernet.

2.2Installing and running the VB Demo

1. Navigate to wherever the ZIP file was unzipped and locate the ‘Setup_v250’ folder.

2. Run ‘SETUP.EXE’ from this folder. This will install the VB5 demo application.

3. Run the application that was installed, ‘DP5_v250.exe’.

4. With the RS232 cable connected to the DP5, select the appropriate COM port.

5. Switch to the ‘spectrum’ tab, and click ‘Single Update’. It should acquire data from the DP5 (which is in an unconfigured state.) If the values above the spectrum update, and it displays ‘Spectrum OK’ in the lower left text box, then it is communicating.
   [Steps 6-8 allow configuring an IP address, if Ethernet will be used.]

6. Go back to the ‘Communication’ tab, and set the IP Address options on the right. Click ‘Send to DP5’ when done.

7. Now, you should be able to connect Ethernet to the DP5. The green light on the DP5 Ethernet jack should light and blink to indicate a valid link.

8. Restart the DP5_v250.exe application. (It needs to be restarted to change the communication interface.) Click the ‘Search for DP5s’ button. It should display a separate form, which after a short time should show the DP5, along with its IP address, etc. Click on it to pass the IP address back to the Communication tab.

9. Click the ‘spectrum’ tab, and click ‘auto update’. It should update the data, indicating that it is able to communicate via Ethernet.

10. Click the ‘Configuration’ tab. [Currently, the demo app can only send a text configuration file.] Click the ‘Send text configuration file’ button. For a SDD with 5V preamp, select the ‘SDD Config.txt’ configuration file from the location where the ZIP file was unzipped. (This file is for an Amptek SDD w/ 5V preamp: HV=-190, TEC=220K). This file can be edited to modify the DP5 parameters (make sure to save the changes before sending it!)
    
    Note 1: The VB5 source code for the demo is located in the Setup_v250\Source folder.
    
    

3Interfaces

The DP5 supports three communication interfaces: USB, Ethernet and RS232. Details about the specific interfaces are in the following sections.

Note: Attempting to use multiple interfaces simultaneously can result in unexpected behavior. In firmware prior to FW6.06.04 (DP5/PX5) or FW6.06.03 (DP5G), the Ethernet general UDP socket is disabled whenever the USB port is connected to a live host port. The socket is re-enabled if the USB cable is disconnected, or the host/hub to which the DP5 is physically connected is powered off. In FW6.06.04 (DP5/PX5) or FW6.06.03 (DP5G) and later, this is no longer the case – the UDP port is always open, regardless of whether USB is connected. [This was changed because noise on the unconnected USB connector caused Ethernet dropouts.]

The ‘Netfinder’ socket remains functional when USB is connected, and the contents of the Netfinder packet indicate if the UDP socket is unavailable because of USB.

The DP5G checks to see if either the USB or RS232 connectors are connected to a live port at power-up. If so, the Ethernet controller is not initialized (to save power), and will remain non-functional until the next power cycle.

3.1USB

The DP5 supports ‘full-speed’ (12Mbps) USB 2.0. Three endpoints are used: the ‘control’ endpoint (EP0); EP1 IN (for response packets from the DP5 to host PC); and EP2 OUT (for request packets from the host PC to DP5.)

Transfers on EP1 and EP2 are terminated by a ‘short packet’ (a packet smaller than the max packet size of 64 bytes), or a zero-length packet (‘ZLP’).

For the DP5, PX5, and DP5G, the USB Vendor ID (VID) and Product ID (PID) are:

VID: 0x10C4

PID: 0x842A

The DPPMCA application (and DP5 Visual Basic demo) use the WinUSB driver. This is a Microsoft product that is native to Vista and Windows 7 (32- and 64-bit), and installable on WinXP. The Visual Basic demo includes source code, and VC++ classes are available for those wishing to write their own communication software.

3.1.1Installing the WinUSB Driver

The WinUSB driver has been tested by WinQual and signed for WinXP 32/64, Vista 32/64, and Win7 32/64. It is available via Windows Update, which means that a PC with an Internet connection should be able to install the driver automatically. Directions for manually installing the driver are in the ‘WinUSB Driver Installation’ folder in the ZIP file.

The ZIP file includes the Microsoft document ‘WinUsb_HowTo.docx’, which describes the complex process of using Windows’ SetupAPI to find the device path, etc. [The VB demo demonstrates this technique, as well as setting pipe policies, opening pipes, sending and receiving data, etc.]

USB.h and USB100.h contain many structures, enums, etc. used by Windows’ USB implementation – these files (from DDK6001) are in the ZIP file.

Microsoft’s website gives information on how to call the specific WinUSB functions:

http://msdn.microsoft.com/en-us/library/ff540046(v=VS.85).aspx

3.1.2WinUSB GUIDs

The WinUSB driver utilizes two GUIDs:

Setup Class GUID: {6A4E9A2D-9368-4f01-8E60-B3F9CDBAB5E8}

Interface Class GUID: {5A8ED6A1-7FC3-4b6a-A536-95DF35D03448}

3.2Ethernet

The DP5 incorporates a 10base-T Ethernet controller and embedded TCP/IP stack to provide Ethernet support via a standard RJ45 jack. The DP5 supports auto-negotiation for half- and full-duplex. Only 10Mbit/s is supported.

PING and ARP are supported. A fixed IP address can be specified, or a dynamic address can be obtained from a DHCP server. (If ‘dynamic’ is selected, and the DP5 is unsuccessful in obtaining a lease from a DHCP server, it will fall back to its previously-programmed static address.) The IP configuration (fixed/dynamic, IP address, netmask, gateway, and port) can be programmed via any of the DP5 communication interfaces (Ethernet, USB or RS232).

Note: By default, the DP5/PX5/DP5G is configured to use a dynamic IP address. If no DHCP server is present, then the device falls back to the programmed static IP address. Prior to FW6.06.05, if no static IP address was programmed, then the device defaulted to 255.255.255.255, which is not a valid IP address. In this case, if a DHCP server isn’t available, then USB or RS232 must be used to assign a valid static IP address. As of January 2012, the VB Demo is the only application which can perform this. In FW6.06.05 and later, if no DHCP server is present and a static IP address hasn’t been programmed, the device will default to 192.168.1.10.

In addition, in order to save power, the DP5G powers down the Ethernet controller when a USB or RS232 connection is detected at power-up. This means for a Gammarad (or other devices that can be powered via USB), external power should be applied, and then USB (or RS232) can be connected after approximately five seconds (or more).

Also, for whatever reason, the DP5/PX5/DP5G work poorly via Ethernet when directly connected to a PC’s Ethernet port. They work fine if connected to the PC via an Ethernet hub or switch.

3.2.1Ping

Prior to FW6.06.06, the Ethernet implementation had a 32-byte PING buffer. This worked with Windows, but not with the Linux default ping size of 56 bytes. In FW6.06.06, the PING buffer was increased to accommodate the Linux default ping size. Note that for Linux ping support with older firmware, the Linux default ping size can be overridden.

3.2.2Ethernet Ports

The DP5 supports two UDP ports for communication: one port is for general communications (fixed at UDP port 10001 in FW6.06, and possibly programmable in later firmware releases), and the other is for device discovery via the Silicon Labs Netfinder protocol (UDP port 3040.)

3.2.3General UDP Port

By default, the DP5 uses UDP port 10001 for communications. Once a packet exchange has taken place on this port, the socket is ‘bound’ to the IP address and source port of the host it exchanged packets with. Once the socket is bound, packets from other IP addresses will be ignored. After approx. 15 seconds of inactivity on the socket, the socket is reset so that it can once again connect to any IP.

To not allow other hosts to seize control of the DP5, the host can continue exchanging packets so that this timeout does not occur. “Interface keep-alive” Request Packets can be sent periodically, if there is no other periodic traffic, to keep the socket from resetting. Or an “Interface – lock” Request Packet can be sent, in which case the socket will not be reset until power is cycled on the DP5, or the host removes the lock by sending an “Interface keep-alive - allow sharing” or “Interface keep-alive - no sharing” Request Packet.

Broadcast packets can be received by the General UDP Port, which may be useful if multiple DP5s are on a subnet, and synchronization or centralized control is desired. (Request packets such as ‘Enable MCA’ and ‘Clear Spectrum’ could be useful as broadcasts.) As of firmware FW6.06, all Request Packets received by the DP5 will generate a Response Packet, which isn’t desirable for broadcasts. Future versions of the firmware may use the most significant bit of the PID2 packet ID to indicate a broadcast packet, so that DP5s will be able to suppress Response Packets. Also, a command or Request Packet will be added so that a DP5 can be configured whether to process or ignore broadcast packets. (This will allow some DP5s on a subnet to not participate in broadcasts, if this is desired.)

The existing protocol works over the Internet, but possibly not very well. As it uses raw UDP packets with no sequence numbers, and spectrum packets are large enough that they’re split into multiple UDP packets, theoretically the spectrum UDP packets could be received out of sequence, with no way to tell. Eventually, the firmware will have the option to encapsulate each UDP packet within the DP5 packet structure, and use the DP5 packet PIDs as sequence numbers. This should allow the protocol to be more robust when routed over the Internet – the packets will be able to be reordered if they arrive out of sequence, and it will be easier to detect dropped packets.

Timeouts

Generally, the DP5 sends the Response or ACK packet after it has completed the operation specified by the Request Packet. This is usually happens quickly, so that the response is sent with little delay. Since the DP5 always sends a Response or ACK Packet in response to receiving a Request Packet, it may be desirable to use a timeout interval to identify missed packets.

The Visual Basic demonstration software uses a timeout interval of 1000mS by default. However, there are a few packet types which require a longer timeout interval because they may take longer than 1s to execute:

3.2.4Netfinder UDP port 3040

The DP5 supports the Silicon Labs ‘Netfinder’ protocol on UDP port 3040. This allows DP5s to be ‘discovered’ – this is particularly useful if DHCP is used to assign dynamic IP addresses, as the DP5 may have an unknown address.

By broadcasting a Netfinder ‘Broadcast Identity Request’ to UDP port 3040, the host directs all DP5s that receive the broadcast to respond with an ‘Identity Reply’, which includes the DP5 serial number, IP address, MAC address, a text description (if one was programmed), the time the device has been powered, and the status of the interface. The host collects the responses from all the DP5s on the subnet, and can then determine which IP address to access based on DP5 serial number, description, etc.

The ‘Broadcast Identity Request’ is 6 bytes in size and is defined below. The format of the ‘Identity Reply’ is also listed below – its size is variable because it contains several variable-length null-terminated strings. Note that the 2^nd string, the description, comes from the DP5’s ‘Misc Data’ buffer. If the firmware finds a null-terminated string of 40 characters or less, it will send that as the description string. Otherwise, ‘(no description)’ is used. [Note: the DP5 will not respond to the Netfinder ‘standard’ 4-byte version of the ‘Broadcast Identity Request’ as defined by Silicon Labs.]

Note that because UDP packet reception is not guaranteed (packets aren’t automatically resent), occasionally not all responses will be received. It may be necessary to send multiple Identity Request packets to receive responses to all units. (This depends on how busy the network is, and how many DP5s are present.) Each subsequent Identity Request should use a different sequence ID – a DP5 will not respond to a repeated Identity Request with the same sequence ID.

Note that while the ‘Broadcast Identity Request’ packet is normally sent as a UDP broadcast packet (i.e. a destination IP of xxx.xxx.xxx.255), it can also be sent to a specific IP address. Also note that UDP broadcast packets generally are limited to the local subnet, and not routed beyond that.

The ‘Interface Sharing Request’ format is also listed below. If a Netfinder Identity Reply has indicated that a DP5 is in use, but that sharing is allowed, the host can send the ‘Interface Sharing Request’ to the Netfinder port of that DP5. The DP5 will use an ACK packet to indicate to its current host that a Sharing Request has been received. If that host wishes to grant the request, it does so by stopping transfers to the DP5’s UDP socket, which will allow the socket to reset itself and the new host to gain control of it. [No acknowledgement of the ‘Interface Sharing Request’ is sent by the DP5 – the host can resend it periodically, and either check the Interface Status in the Netfinder ‘Identity Reply’, or try sending packets to the DP5 UDP port to see if it responds.]

Broadcast Identity Request – 6 bytes

Identity Reply – variable length

Interface Sharing Request – 6 bytes

3.3RS232

The RS232 port on the DP5 operates at 115,200 baud, with 1 start bit, 8 data bits, no parity bit, and 1 stop bit. Neither hardware nor software handshaking is used. 57,600 or 19,200 baud operation can be selected; however, selecting these rates will disable the Ethernet port.

The RS232 interface employs a ‘gap timer’ on its receiver, to aid in synchronization – if the time between consecutive received bytes exceeds 100mS, all buffered bytes are discarded, and the DP5 will resume searching for the sync characters that signal the start of a new packet. No acknowledge packet will be sent to indicate this has occurred.

3.4Transfer times and data buffering deadtime

In response to a Spectrum (or spectrum + status) request packet, the DP5 will briefly shut off data acquisition, so that it can make a copy of the spectrum memory. When complete, the MCA is re-enabled and the acquisition continues. This ‘deadtime’ is a function of how many channels are selected (256, 512, etc.) and whether the FPGA is running at 20 or 80MHz. This ‘deadtime’ will occur each time the spectrum is read out, and this is reflected in the acquisition time; the acquisition timer is stopped during this ‘deadtime’, while the realtime timer continues to run.

[Note that there is no deadtime penalty for using the ‘ request spectrum and clear’ (or ‘request spectrum + status and clear’) form of the request packet – the clear function happens simultaneously with the buffering function, and does not add to the ‘deadtime’.]

The measured ‘deadtimes’ are:

The USB, Ethernet and RS232 transfer times were measured, using an oscilloscope. The transfer times include the time from when the request packet was started to when the response packet was completed. (i.e. the whole round-trip transfer was measured.)

The transfer times include the ‘deadtime’ due to buffering, listed above. The transfer times were measured with the 80MHz clock selected, and were measured using the ‘Request spectrum + status’ request packet. The transfers will run at the same rate with the 20MHz clock, except the ‘deadtime’ for buffering will be longer. So, for 20MHz timing, use the 80MHz timing, plus the difference between the 20MHz and 80MHz buffering ‘deadtime’.

4Packet Format

All communications with the DP5 follow a request/response format: the host sends a Request Packet to the DP5, and the DP5 returns a Response Packet. The Response Packet sent by the DP5 to the host will be:

1. a packet containing the requested data;

2. an acknowledge (ACK) packet, indicating the request packet was received and interpreted without error (if the request packet is not one for which data is returned);

3. an ACK packet, indicating the request packet contains an error in structure or content;

4. an ACK packet, indicating why the request can’t be executed;

5. an ACK packet, indicating that an ASCII command had a unrecognized command field or an invalid parameter field – the command in question will be echoed in the data field of the ACK packet.

6. an ACK packet, indicating the request packet was received and interpreted without error, and a sharing request was received from another computer via Ethernet;

All packets sent to and from the DP5 use the same basic packet format: a 6-byte header, which defines the type and length of the packet, an optional data field, and a 16-bit checksum. For packets sent to the DP5, the optional data field can be up to 512 bytes, for a maximum packet size of 520 bytes. For packets sent by the DP5 to the host PC, the maximum data field size is 32767 for a maximum packet size of 32775 bytes.

Packet Format

Fields:

Offset 0 & 1: Sync bytes – these fields have fixed values of 0xF5 and 0xFA.

Offset 2 & 3: Packet ID fields 1 & 2 (PID1 & PID2) – these define the meaning of the packet, as summarized in Table 1, Table 2 and Table 3.

Offset 4 & 5: 16-bit length field (LEN) of the optional data field. If data field is not present, LEN=0.

If LEN =0:

Offset 6 & 7: 16-bit checksum: MSB, then LSB. This is a two’s-complement of the 16-bit sum of all bytes prior to the checksum. (i.e. the 16-bit sum of the checksum and all other bytes in the packet is 0.)

If LEN > 0:

Offset 6: The start of the data field, whose length is given by the 16-bit LEN field. The last byte is offset 5+LEN.

Offset 6+LEN, Checksum, as described above.

7+LEN:

4.1Request Packets (Host PC to DP5)

Table 1

4.1.1Request packet: “Request Status Packet”

Purpose: This request directs the DP5 to construct a status packet and send it to the host PC. The status packet can be requested with this request packet, or with one of the ‘Request Spectrum plus Status’ variants, in which case the status packet is included in the packet data field along with the spectrum data.

The status packet contains information about the current state of the spectrum, and of the DP5. Its format is listed with the “Status Packet” Response Packet.

Response: If no errors are detected, a “Status Packet” Response Packet will be returned.

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of the requested data.

4.1.2Spectrum Request Packets

Request packet: “Request Spectrum”

Request packet: “Request and clear Spectrum”

Request packet: “Request Spectrum plus Status”

Request packet: “Request and clear Spectrum plus Status”

Purpose: These requests direct the DP5 to take a ‘snapshot’ of the spectrum and corresponding status data and begin transmitting that data. If the ‘Request and Clear’ form of this packet is send, it will also clear the spectrum and associated status data, and if the MCA was enabled when this request was received, then a new acquisition will start.. [Where should the details about what status fields get cleared be discussed?]

Response: If no errors are detected, than either a ‘spectrum’ response packet, or a ‘spectrum plus status’ response packet will be sent by the DP5.

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of the requested data. If the FPGA failed initialization, then an FPGA error ACK packet will be returned.

4.1.3Request packet: “Request Digital Scope Data”

4.1.4Request packet: “Request Digital Scope Data & Re-arm Scope”

Purpose: These request that the DP5 send a 2048-byte digital scope packet. The second form of the command will also re-arm the digital scope.

Response: If no errors are detected, the DP5 will respond with a ‘2048-byte Scope Packet’ Response Packet (PID1=0x82, PID2=1) or a ‘2048-byte Scope Packet w/ Overflow’ Response Packet (PID1=0x82, PID2=3). (See the Response Packet descriptions for details.)

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of the requested data. Also, if no data is available because the scope hasn’t triggered, a “Scope data not available” ACK packet will be returned instead of the requested data.

4.1.5Request packet: “Request Misc Data”

Purpose: This requests that the DP5 send the 512-bytes of ‘miscellaneous data’ that is stored in the DP5’s non-volatile memory. (See also the “Write Misc Data” Request Packet for information on to write this data to the DP5.)

Response: If no errors are detected, the DP5 will respond with the “512-byte Misc Data” Response Packet (PID1=0x82, PID2=2).

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of the requested data.

4.1.6Request packet: “Request Ethernet Settings”

Purpose: This requests that the DP5 send the Ethernet settings that are stored in the DP5’s non-volatile memory. (See also the “Set Ethernet Settings” Request Packet for information on how to write these settings.)

Response: If no errors are detected, the DP5 will respond with the “Ethernet Settings” Response Packet (PID1=0x82, PID2=4).

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of the requested data. Additionally, if no Ethernet controller is detected on the DP5, the “CP2201 not found” ACK packet will be returned instead of the requested data.

4.1.7Request packet: “Request Diagnostic Data”

Purpose: This requests that the DP5 perform some diagnostic tests, and return a suite of diagnostic data.

Response: If no errors are detected, the DP5 will respond with the “Diagnostic Data” Response Packet (PID1=0x82, PID2=5). Note: the DP5 runs a full memory test on the 512KB SRAM, which takes some time. The DP5 will respond with the Response Packet a maximum of 2.5s after receiving the Request Packet.

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of the requested data.

4.1.8Request packet: “Request Netfinder Packet”

Purpose: This requests a Netfinder packet, but through the active communications port. [The ‘Netfinder packet’ is generally obtained via a broadcast on the TCP/IP Netfinder socket. See section 3.2.4 for details.]

Response: If no errors are detected, the DP5 will respond with the “Netfinder Packet” Response Packet (PID1=0x82, PID2=8).

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of the requested data.

4.1.9Request packet: “I²C Transfer”

Purpose: The data field of this Request Packet contains the description for an I²C transfer to be performed by the DP5. Read, Write and Combined I²C transfers are supported.

The format of the data field is listed below. The first 3 bytes are mandatory; following those are the bytes to be written, which can number from 0 to a maximum of 32. Therefore, the size of the data field (LEN) has a minimum of 3 and a maximum of 35.

Note: The DP5 uses Slave Addresses of 0x20 and 0x4C. The optional PC5 uses Slave Addresses of 0x1F, 0x34, 0x50 and 0x6D. Transfers should not be attempted using these Slave Addresses. Also, the value in offset 0 is the 7-bit address – this value will be shifted left one bit, and the appropriate R/W bit merged in, before it’s transmitted on the I²C bus.

Response: If no errors are detected, the DP5 will respond either with an ACK OK packet (if NOBR=0), or with an I²C Response Packet with the bytes read from the I²C slave (if NOBR > 0).

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of the requested data or the ACK OK packet. If the I²C master didn’t detect the I²C ACK at the proper time, an ‘I²C ERROR’ ACK packet will be returned. A BAD PARAMETER ACK packet will be returned if there are structure problems with the request. (NOBR=NOBW=0; LEN not equal to NOBW+3; NOBR > 32; NOBW > 32; or SA = 0).

4.1.10Request packet: “Request List-Mode Data”

Purpose: This requests that the DP5 send available List-mode data.

Response: . A ‘List-mode data’ Response Packet (PID1=0x82, PID2=9) will be returned, with between 0 and 1020 records (0 to 4092 bytes.) If the List-mode FIFO is full, a ‘List-mode data, FIFO full’ Response packet (PID1=0x82, PID2=10) is returned, which will contain 1024 records. [The FIFO size may be increased in future FPGA versions; hence, the two different response packets, rather than having the application monitor the returned data size.]

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of the requested data. Additionally, if the firmware has been upgraded for List-mode support, but the FPGA hasn’t, a ‘Feature not supported by this FPGA version’ ACK packet will be returned instead of the List-mode data Response Packet.

Note: The ‘Clear Spectrum’ Request Packet clears the List-mode FIFO, in addition to clearing the spectrum buffer.

4.1.11Request packet: “Request Option PA calibration data” [MCA8000D only]

Purpose: This requests the MCA8000D Option PA calibration data, if available.

Response: If the MCA8000D has the Option PA calibration installed, then an Option PA Calibration Data Response Packet will be returned.

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of the requested data. Additionally, if the Option PA calibration has not been performed on this MCA8000D, a ‘Calibration data not present’ ACK packet will be returned instead of the Option PA Calibration Data Response Packet.

4.1.12Request packet: “Request 32-bit SCA Counters”

4.1.13Request packet: “Latch + Request 32-bit SCA Counters”

4.1.14Request packet: “Latch + Clear + Request 32-bit SCA Counters”

Purpose: These request that the DP5 send 64 bytes of SCA counter data (16 SCAs x 32 bits each). The data is read from the SCA counter latches, so the SCAs must have been latched, either via the ‘Latch’ form of these requests, a ‘Latch SCA’ Request Packet (which is TBD in FW6.01), or a hardware signal (also TBD.) The ‘Clear’ form of these requests will clear the SCA counters after the data has been latched.

Response: If no errors are detected, the DP5 will respond with a “64-byte SCA Packet” Response Packet (PID1=0x83, PID2=1).

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of the requested data.

4.1.15Request packet: “Text Configuration”

Purpose: This sends a Text Configuration packet to the DP5, which the DP5 interprets and executes. (See the section on ASCII Commands for information on individual commands.) The commands are packed into the Data field, with the following rules:

1. Alphabetic characters must be uppercase.

2. Each command consists of a 4-character command, followed by “=”, followed by the parameter (max of 10 characters), and terminated by a semicolon (Ex: “TPEA=10;”)

3. Units may be included with the parameter, but they are ignored, and count towards the 10-character maximum length for the parameter. (Ex: “TPEA=10US;”)

4. The commands are packed together with no whitespace of any kind (tabs, spaces, CR/LF, etc.)

5. For some commands, the ordering is important. See the ‘ASCII Commands’ section for more discussion of this.

6. If all commands fit in the max 512 byte data field, then the configuration can be sent as a single packet. If they don’t fit, then additional Text Configuration packets can be sent. Generally, the ASCII Command “RESC=Y;” would be the first command of the first packet, and it would not appear in later packets. If additional packets are needed, ensure that commands are not chopped between packets – only complete command/parameter strings are allowed.

Here’s an example of the data field:

RESC=YES;CLCK=AUTO;TPEA=10US;TFLA=0US;CUSP=50%;
RESL=3000US;PDMD=NORM;THSL=1.00%;THFA=40;

Response: If no errors are detected, the DP5 will respond with an ACK OK packet. This indicates that all commands were recognized and executed without error.

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of the requested data. If one or more errors are detected while parsing the Text Configuration, an ‘Unknown/Bad Parameter’, ‘Unrecognized Command’, or ‘PC5 Not Present’ ACK packet will be returned, and the data field will contain the ASCII command and parameter which caused the error. If more than one error was detected, only the last error & command will be returned.

4.1.16Request packet: “Text Configuration Readback”

Purpose: This sends a Text Configuration Readback Request Packet to the DP5, which the DP5 uses as a ‘template’ to read back the current configuration. The data field is the same format as for the Text Configuration Request Packet – a list of ASCII command and parameters, separated by semicolons. The DP5 strips off any parameters and replaces them with the current settings for each command specified. The result is returned in the Configuration Readback Response Packet. It is possible to send a text configuration packet via the Text Configuration Request Packet (PID1=0x30 / PID2=2), and then reuse the same packet data field for the Text Configuration Readback Request Packet (PID1=0x30 / PID2=3) to read back the actual settings that the DP5 derived from the Text Configuration packet.

The “=” and parameter are optional for each command listed; the minimum required is the 4-character commands, separated by semicolons. There is one exception to this – the SCAI (SCA Index) command. As this is a directive to the command processor rather than a true command, the ‘=’ and parameter are required. Here is an example data field, to read back the low and high thresholds for SCA1 & SCA2:

“SCAI=1;SCAL;SCAH;SCAI=2;SCAL;SCAH;”

Also note that the ‘RESC’ (Reset Configuration) has no meaning in the context of Configuration Readback – if included, it will return ‘RESC=?;’.

Any number of commands may be read back, as long as they fit within the maximum data field of 512 bytes. As of FW6.01, there is no error handling for the condition where the generated Response Packet exceeds the maximum data field size, so limiting the size of the Request Packet data field is a good idea, to avoid this issue.

Response: If no errors are detected, the DP5 will respond with a Configuration Readback Response Packet (PID1=0x82 / PID2 = 7). Any command which is not recognized in the data field will return “CMDA=??;”, where ‘CMDA’ is the unknown command. [This is returned in the Response Packet with the rest of the commands.]

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of the requested data. If one or more errors are detected while parsing the Text Configuration, an ‘Unknown/Bad Parameter’, ‘Unrecognized Command’, or ‘PC5 Not Present’ ACK packet will be returned, and the data field will contain the ASCII command and parameter which caused the error. If more than one error was detected, only the last error & command will be returned.

4.1.17Request packet: “Clear Spectrum”

Purpose: This commands the DP5 to clear the MCA (spectrum), and all associated values (see section 4.2.1 for a list of what fields in the status packet are cleared by this command.)

. (slow counts, fast counts, acquisition time, etc.) If the acquisition was enabled when this command was received, it will continue to be enabled after the spectrum is cleared. It also resets the List-mode FIFO to empty.

Response: If no errors are detected, the DP5 will respond with ACK OK packet.

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of ACK OK.

4.1.18Request packet: “Enable MCA/MCS”

Purpose: This commands the DP5 to enable the MCA. If the acquisition was stopped due to a “Disable MCA/MCS” command or because the ‘Preset Time’ expired, this command will re-enable the acquisition, without clearing anything. If the acquisition was stopped due to ‘Preset Counts’ being reached, then this command will have no effect until the spectrum is cleared. (See ASCII Commands PREC & PRET.)

Response: If no errors are detected, the DP5 will respond with ACK OK packet.

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of ACK OK.

4.1.19Request packet: “Disable MCA/MCS”

Purpose: This commands the DP5 to disable the MCA, effectively pausing the acquisition.

Response: If no errors are detected, the DP5 will respond with ACK OK packet.

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of ACK OK.

4.1.20Request packet: “Arm Digital Scope”

Purpose: This commands the DP5 to arm its internal digital oscilloscope. Once armed, a trigger condition will cause the digital scope to capture 2048 samples. After arming the digital scope, the application software can either:

1. Monitor the ‘Oscilloscope data ready’ bit (offset 35: bit D2 in the status data) to determine when the scope has triggered, then send a “Request Digital Scope Data” request packet to get the data.

2. Repeatedly send a “Request Digital Scope Data” request packet – the DP5 will respond with a “Scope data not available” ACK packet if the trigger hasn’t occurred yet. It will respond with the “2048-byte scope packet” or “2048-byte scope packet w/ overflow” after the scope has triggered.
   
   (See the DACO, SCOE, SCOT & SCOG ASCII commands for more information on the Digital Scope.)

Response: If no errors are detected, the DP5 will respond with ACK OK packet.

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of ACK OK.

4.1.21Request packet: “Autoset Input Offset”

Purpose: This commands the DP5 to search for an appropriate input offset (i.e. the DC offset of the input signal as seen by the input ADC.) Generally, the ‘default’ input offset should work with most detectors. (See the INOF ASCII command.) In order for the Autoset Input Offset function to work properly:

1. The input polarity must be set properly (see the AINP ASCII command.)

2. HV & detector temperature (if applicable) must be reasonably stable.

3. An appropriate input offset might not be found if this command is initiated while the input count rate is high.

Support: This request is supported by the DP5 and PX5, but not the DP5G. (The DP5G does not have a variable input offset.)

Response: If no errors are detected, the DP5 will respond with ACK OK packet. The DP5 sends the ACK packet immediately, and does not wait for the Autoset function to complete. The result of this command is in the status data (offset 36: bit D7) – it returns “Auto Input Offset locked” or “Auto Input Offset searching”. Status can be polled until the result indicates ‘locked’.

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of ACK OK.

4.1.22Request packet: “Autoset Fast Threshold”

Purpose: This commands the DP5 to search for an appropriate fast threshold setting. In order for the Autoset Fast Threshold function to work properly, no input counts can be present (other than noise.)

Response: If no errors are detected, the DP5 will respond with ACK OK packet. The DP5 sends the ACK packet immediately, and does not wait for the Autoset function to complete. The result of this command is in the status data (offset 35: bit D6) – it returns “Auto Fast Threshold not locked” or “Auto Fast Threshold locked”. Status can be polled until the result indicates ‘locked’. The fast threshold determined by this function is returned by the readback of the ‘THFA’ command, using the ‘Text Configuration Readback’ Request Packet. Note that this setting is overwritten when a new configuration packet is received with the “THFA” or “RESC” commands.

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of ACK OK.

4.1.23Request packet: “Write IO3-0”

Purpose: This commands the DP5 to set the four IO lines IO3-0 with the data byte in offset 6, as shown below. Note that these outputs are open-drain, with a weak pullup. They can sink 20mA, but only source 100uA (typ) at 3.3V. (These are outputs from a Maxim MAX7328 operating at 3.3V – see the datasheet for more info.)

Response: If no errors are detected, the DP5 will respond with ACK OK packet.

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of ACK OK.

4.1.24Request packet: “Write 512-byte Misc Data”

Purpose: This commands the DP5 to store the 512-byte data field in non-volatile memory. The data can be binary, ASCII, etc. (It could contain the description or location of the unit as an ASCII string, for example.) It is read back with the “Request Misc Data” Request Packet.

Response: If no errors are detected, the DP5 will respond with ACK OK packet. Note this command requires a FLASH memory erase operation – the ACK packet could be delayed as much as 400mS from the request packet.

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of ACK OK.

4.1.25Request packet: “Set DCAL”

Purpose: This commands the DP5 to set the non-volatile calibration value for the detector temperature measurement diode. The setting is an unsigned integer in the range of 0-4095, in the format LSB followed by MSB. The nominal value is 1.000V, which corresponds to a setting of 0x555. (The conversion factor is 732uV/count.) This value can be read back via the “Request Diagnostic Packet” Request Packet. The setting is stored in the DP5 non-volatile memory. If a PC5 is present, it is also stored in the PC5 non-volatile memory.

Support: This request is supported by the DP5 and PX5, but not the DP5G.

Response: If no errors are detected, the DP5 will respond with ACK OK packet.

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of ACK OK.

4.1.26Request packet: “Set PZ Correction”

Purpose: This commands the DP5 to set the non-volatile correction factor for the Pole-Zero. This allows digital fine-tuning of the analog PZ time constant. (This calibration value is set at the factory and shouldn’t need to be changed.) This value can be read back via the “Request Diagnostic Packet” Request Packet. The interpretation of the PZ Correction value (‘setting’) is:

Setting of 0-127: the correction factor is (1024+setting)/1024 (i.e. 100% to 112.4%)

Setting of 128-255: the correction factor is (768+setting)/1024 (i.e. 87.5% to 99.9%)

Examples: setting = 0 -> 100% correction factor;
setting =10 -> 101% correction factor;
setting =250-> 99.4% correction factor

The PX5 has two software-selectable pole-zero filters. This command sets the calibration for the 3.2uS pole-zero. The DP5 and DP5G have a single pole-zero; this command sets the calibration for it.

Note: This command won’t take effect until the next configuration request packet is received.

Response: If no errors are detected, the DP5 will respond with ACK OK packet.

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of ACK OK.

4.1.27Request packet: “Set uC Temperature Calibration”

Purpose: This commands the DP5 to set the non-volatile offset calibration for the DP5 temperature measurement. It is an 8-bit signed value, and is added to the measured temperature; the result appears in the status data as ‘board temperature’ (offset 34). This value can be read back via the “Request Diagnostic Packet” Request Packet. [The temperature sensor is internal to the microcontroller; this calibration value allows compensation for the fact that the uC die is always hotter than the board.]

Response: If no errors are detected, the DP5 will respond with ACK OK packet.

Possible errors: If the request packet is malformed or corrupted: CHKSUM, LEN, or PID error ACK packets can be returned instead of ACK OK.

4.1.28Request packet: “Set ADC Calibration”