MCA-3K Data Server (sipm-MDS) Reference

The USB interface implemented in the ARM M0+ MCU is a peripheral device and has the required control endpoint plus command IN and OUT endpoints (0x81, 0x1) plus data IN and OUT endpoints (0x82, 0x2). Here, IN and OUT are as seen by the host; hence, IN refers to the host reading data from the device.

Device driver

The device driver uses libusb0.1 as the user space usb-driver. Note that only one application can claim a device.

mca3k_device.py defines the 'mca' class. An object of that class holds all information necessary to operate an MCA-3K. Note that with the exception of its usb_handle, all information is considered transient and the class object is stateless. For each attached MCA-3K one mca object is created, and the bpi_usb.findall() function returns a dictionary of all attached MCA-3K mca objects.

The keys in this dictionary are the unique 32-character long serial numbers of the SAM L21 ARM M0+ processor. These serial numbers are built-in by the manufacturer and cannot be changed or erased. The device driver reads the ARM Version registers to retrieve the unique serial number of the device.

The device driver supports any number of attached MCA-3K units. For a device to be recognized as an MCA-3K it must have a USB vendor id of 0x1FA4 and a product ID of 0x103 (PMT-3000) or 0x203 (SiPM-3000).

Unless they require a customized driver, all MCA-3K have the same serial number ("armMorpho001", or "sipmMORPHO001") as seen by the operating system as it enumerates the devices on the USB bus. This prevents Windows from having to install a new driver copy for every new MCA-3K.

Table of device driver functions.
Device driver functions
Name	Description
scan_all	Scan for attached MCA-3K, but do not try to claim the devices and open them for communication. Use to count MCA-3K units or check if devices have been plugged in or unplugged.
find_all	Scan for attached MCA-3K units, claim the interface and open for USB communication. It returns a dictionary of mca objects, one object per attached MCA-3K
close_all	Close USB communication for all attached devices.
read_data	Read data from the DATA_IN endpoint. It can read data from their ARM MCU or the FPGA.
write_data	Write data to COMMAND_EP or DATA_EP. It can send data to the ARM MCU or the FPGA.

Data I/O

The MCA-3K USB communication uses the concept of a data port. The host first writes instructions to the command endpoint and then issues a usb bulk read to retrieve the data. The software inside the ARM MCU will populate the data_in buffer with the requested data. If the host requires more than 256 byte, the bpi_usb.read_data function will use multiple bulk-reads to satisfy the request.

The read and write functions are both completely agnostic of the data. Data are byte arrays and the two functions look do not look inside or try to interpret the data. Both take an mca object as their only argument.

The bpi_device.write_data function. It writes to the command_out or the data_out endpoint. Data are written in chunks of 256 bytes or less.
Function bpi_device.write_data(mca)
Arguments	Type	Description
mca.bytes_out	Byte array	array.array('B')
mca.num_bytes	Integer	Number of bytes to send; Maximum is to 2¹⁶-1=65535 bytes.
mca.write_ep	Integer	Endpoint; either mca.COMMAND_OUT_EP or mca.DATA_OUT_EP
mca.usb_write_timeout	Integer	USB write timeout in milli-seconds.
Returns
None	Integer	None, or possibly an error code for debugging purposes only.

The bpi_usb.read_data function. Data are read in chunks of 256 bytes or less.
Function bpi_device.read_data(mca)
Arguments	Type	Description
mca.bytes_in	Byte array	array.array('B'); Buffer to receive the data read from the device.
mca.num_bytes	Integer	Number of bytes to read; Maximum is to 2¹⁶-1=65535 bytes.
mca.read_ep	Integer	Endpoint; either mca.COMMAND_IN_EP or mca.DATA_IN_EP, where mca.COMMAND_IN_EP is used for debugging only.
mca.usb_read_timeout	Integer	USB read timeout in milli-seconds.
num_bytes	Integer	Number of bytes to read (up to 2¹⁶-1=65535).
Returns
None	Integer	None, or possibly an error code for debugging purposes only.