Metadata-Version: 2.4
Name: sis315x
Version: 0.2.1
Summary: Interface for the SIS315x USB/Ethernet to VME interface card family
Project-URL: Homepage, https://www.struck.de/sis3153.html
Author-email: Christian Ther <christian.ther@struck.de>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Other Environment
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.13
Requires-Dist: numpy>=2.4.4
Description-Content-Type: text/markdown

# SIS315x

This module provides a lightweight Python interface for the SIS3153 (USB 3.0/Ethernet) and SIS3150 (USB 2.0) VME bus master/system controller cards, thereby enabling access to a VME system via USB.

It is assumed that the device driver included with the device is already installed on the system and ready for use. Drivers are available for Windows (32-bit/64-bit) and Linux (32-bit/64-bit).
For more information on installing the driver, please refer to the SIS3153 / SIS3150 [documentation](https://www.struck.de/dokuwiki/doku.php).

## Installation

> [!NOTE]
> Python version >= 3.13.0 is required

From [PyPI](https://pypi.org/project/sis315x):
```
pip3 install sis315x
```
 
## Examples

The following example demonstrates how to access the local registers of a SIS3153:
```
from sis315x import Sis315x, Sis315xError

interface = Sis315x('usb')

try:
    interface.open()
except Sis315xError as e:
    print(e)
    exit()

# read from register SIS3153_SERIAL_NUMBER_REG (0x2)
sn = interface.read_register(0x2)
print('Serial number: %s' % str(sn&0xFFFF))

# write to register SIS3153_CONTROL_STATUS (0x0)
# switch user LED A on
interface.write_register(0x0, 0x1)

interface.close()
```

The following brief example illustrates how to access the VME system:
```
from sis315x import Sis315x, Sis315xError

interface = Sis315x('usb')

try:
    interface.open()
except Sis315xError as e:
    print(e)
    exit()

interface.reset_vme_system()

vme_base_addr = 0x48000000

# write to register 0x4
# use A32-D32
interface.write_vme('a32_d32', vme_base_addr + 0x4, 0x11223344)

# read from register 0x4
# use A32-D32
print(hex(interface.read_vme('a32_d32', vme_base_addr + 0x4)))

interface.close()
```

The following code snippet shows how to access the VME system via block transfer:
```
import numpy
from sis315x import Sis315x, Sis315xError

interface = Sis315x('usb')

try:
    interface.open()
except Sis315xError as e:
    print(e)
    exit()

vme_base_addr = 0x38000000

mem_size = 0x2000000 # 32MByte
wr_data = numpy.array(numpy.random.randint(0, 0xFFFFFFFF, int(mem_size/4-1), dtype=numpy.uint32))
rd_data = numpy.zeros(int(mem_size/4-1), dtype=numpy.uint32)

interface.reset_vme_system()

# write to memory
# use A32-BLT32
interface.write_vme('a32_blt32', vme_base_addr, wr_data)

# read from memory
# use A32-BLT32
interface.read_vme('a32_blt32', vme_base_addr, rd_data)

if not numpy.array_equal(wr_data, rd_data):
    print('ERROR: Data discrepancy detected!')

interface.close()
```

Additional examples of register accesses (`base-test.py`) and VME accesses (`vme-test.py`) can be found in the [`tests`](https://pypi.org/project/sis315x/#files) folder.

## Supported VME Mods

Overview of supported VME read/write modes. A list of the corresponding mode names required as parameters for the `read_vme()` and `write_vme()` functions is provided below.

### VME master read cycles:

- CRCSR, A16, A24, A32
- D8/D16/D32/BLT32/MBLT64/2eVME/2eSST160/2eSST267/2eSST320

### VME master write cycles:

- CRCSR, A16, A24, A32
- D8/D16/D32/BLT32/MBLT64/2eVME/2eSST160/2eSST267/2eSST320

### VME IACK

The register SIS3153_VME_INTERRUPT_STATUS (0x12) reflects the status of the VME IRQ line. An interrupt acknowledge cycle (IACK cycle) can be triggered as follows. The interrupt vector is returned:
```
irq_vector = interface.read_iack(vme_irq_level)
```

### Mode names

Corresponding mode names required as parameters for `read_vme()` and `write_vme()`:

| Address width | Mode names |
| ------------- | ---------- |
| CRCSR | crcsr_d8, crcsr_d16, crcsr_d32 |
| A16 | a16_d8, a16_d16, a16_d32 | 
| A24 | a24_d8, a24_d16, a24_d32, a24_blt32, a24_blt32_fifo, a24_mblt64, a24_mblt64_fifo, a24_d32_dma, a24_d32_dma_fifo |
| A32 | a32_d8, a32_d16, a32_d32, a32_blt32, a32_blt32_fifo, a32_mblt64, a32_mblt64_fifo, a32_d32_dma, a32_d32_dma_fifo, a32_2evme, a32_2evme_fifo, a32_2esst160, a32_2esst160_fifo, a32_2esst267, a32_2esst267_fifo, a32_2esst320, a32_2esst320_fifo |