.. _installation:

==================
Installation Guide
==================

Overview
--------

This section explains how to install **Addi-Pack**, set up your environment,
and verify that your ADDI-DATA cards are correctly detected.

This section will guide you through:

1. Installing the drivers and API libraries
2. Verifying that your ADDI-DATA card is correctly detected
3. Running your first sample


OS Dependencies
---------------

**Windows:**

- Visual Studio 2022 (or higher)
- Administrator rights during installation

**Linux:**

- dkms
- glibc-devel
- kernel-devel
- cmake
- make

.. note::
   On **CentOS**, you must enable the EPEL repository before installing Addi-Pack:

   .. code-block:: bash

      sudo dnf install epel-release
      sudo dnf install dkms glibc-devel kernel-devel cmake gcc-c++

   The **EPEL** (Extra Packages for Enterprise Linux) repository provides additional development tools not available in default CentOS/RHEL repositories.


**Installation**
----------------

**Inserting a PCI, PCIe or CPCI/CPCIs card**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Follow these general steps to install your ADDI-DATA PCI or PCIe card safely:

1. **Power Down and Unplug the PC**

   - Shut down your computer completely.
   - Unplug it from the power source before opening the case.

2. **Prepare Your Workspace**

   - Work on a clean, non-conductive surface.
   - Use an anti-static wrist strap if available, or regularly touch a grounded metal part of the case to discharge static electricity.

3. **Open the PC Case**

   - Remove the side panel or cover according to your PC manufacturer's instructions.

4. **Locate a Free PCI/PCIe Slot**

   - Identify a compatible free slot (PCI, PCIe, CompactPCI(CPCI) or CompactPCI Serial (CPCIs) depending on the card model).
   - Remove the corresponding metal bracket on the case.

5. **Insert the card Carefully**

   - Hold the card by its edges. Avoid touching the gold connectors or electronic components.
   - Align the card with the slot and press it down **evenly** and **firmly** on both ends until it is fully seated.
   - Do not force it, if it doesn’t fit, verify the alignment.

6. **Secure the card**

   - Use a screw to fasten the mounting bracket to the chassis.

7. **Check for Obstructions**

   - Make sure no cables or nearby components are pressing against the card.

8. **Close the Case and Reconnect Power**

   - Replace the case panel and reconnect the power cord.

9. **Power On and Verify Detection**

   - Start your computer.
   - On **Windows**, check the **Device Manager**.
   - On **Linux**, run ``lspci`` to verify the board is recognized.


**Windows**
~~~~~~~~~~~

1. **Download the installer**

   Download the latest installer (``.exe``) from the official ADDI-DATA website (https://www.addi-data.com/drivers).

2. **Run the installer**

   - Run ``AddiPack-2025.x-Windows-x86_64.exe`` with administrative privileges.
   - Follow the on-screen steps.

3. **Verify the environment variable**

   The installer adds an environment variable that points to the directory in program files. It's name is AddiPack_ROOT.
   You can verify the existence of said variable via the following command.

   .. code-block:: powershell

      echo $env:AddiPack_ROOT

4. **Check device detection**

    From PowerShell:

   .. code-block:: powershell

      cd "$env:AddiPack_ROOT\samples\bin\x64\generic"
      .\get_devices_info.exe

   You should see a list of detected devices.

   For a detailed explanation and sample output, see the :ref:`verify_installation <verify_installation>` section.

**Linux (Debian / Ubuntu)**
~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. **Download the package**

   Download the latest package (``.deb``) from ADDI-DATA website (https://www.addi-data.com/drivers).

   Example: ``AddiPack-2025.09.1-Linux-x86_64.deb``

2. **Install dependencies**

   .. code-block:: bash

      sudo apt update
      sudo apt install build-essential dkms cmake

3. **Install Addi-Pack**

   .. code-block:: bash

      sudo dpkg -i AddiPack-2025.09.1-Linux-x86_64.deb

4. **Check device detection**

   Compile and run a sample:

   .. code-block:: bash

      cd $AddiPack_ROOT/samples/get_devices_info
      cmake -B build && cmake --build build
      ./build/get_devices_info

.. note::
   The variable ``$AddiPack_ROOT`` is automatically set during installation.
   On Linux, the default path is: ``/opt/addi-data/addipack``

.. tip::
   If your card is not detected, check if the kernel module is loaded:

   .. code-block:: bash

      lsmod | grep addi

   Example output if loaded correctly:

   .. code-block:: text

      apcie1032             40960  0
      apcie1564             40960  0


**CentOS Stream 10**
~~~~~~~~~~~~~~~~~~~~

CentOS  uses RPM packages and requires EPEL to be enabled.

1. **Enable EPEL repository**

   .. code-block:: bash

      sudo dnf install epel-release

2. **Install dependencies**

   .. code-block:: bash

      sudo dnf install dkms glibc-devel kernel-devel cmake make gcc-c++

3. **Install Addi-Pack**

   Download the latest package (``.rpm``) from ADDI-DATA website (https://www.addi-data.com/drivers).

   Example: ``AddiPack-2025.09.1-Linux-x86_64.rpm``

   .. code-block:: bash

      sudo rpm -ivh AddiPack-2025.09.1-Linux-x86_64.rpm

4. **Check device detection**

   Compile and run a sample:

   .. code-block:: bash

      cd $AddiPack_ROOT/samples/get_devices_info
      cmake -B build && cmake --build build
      ./build/get_devices_info

.. warning::
   Some CentOS systems use old Python versions.
   Upgrade your Python version to 3.8+ (previous versions aren't supported by API)

   .. code-block:: bash

      sudo dnf install python38


.. _verify_installation:

**Verify Installation**
~~~~~~~~~~~~~~~~~~~~~~~

After installing Addi-Pack and inserting the hardware, you should verify that the device is correctly detected by the system.

You can perform this check using either the CLI sample or the Python API, depending on your workflow.

Using the CLI sample
^^^^^^^^^^^^^^^^^^^^

The `get_devices_info` utility, located in the `samples` directory, lists all detected ADDI-DATA devices and displays their hardware properties.
To run it, follow the OS-specific commands shown in the installation sections above.

A typical output looks like:

.. code-block:: text

   ========== Device 0 (0) ==========
   Product Name: APCIe-1032
   Bus: 3 | Device: 0 | Vendor ID: 0x15B8 | Device ID: 0x1032
   Interrupt: 11 | Bus Type: PCIe

   BAR0: 0xFE800000
   BAR3: 0xFE840000

   Digital Inputs: 32 | Outputs: 0 | Digital Ports: 2 | Interrupt Mask: 0x0000FFFF

This confirms that the driver is loaded, and the device is properly detected.

.. note::
   If no device is listed, make sure that:

   - The card is correctly inserted and securely fastened,
   - The driver was installed with Administrator rights.

 .. warning::
   If ``AddiPack_ROOT`` is missing or incorrect, CMake, Python, or SDK tools may fail to locate Addi-Pack components.


Using Python
^^^^^^^^^^^^

You can also check for detected devices programmatically using the `addipack` Python module:

.. code-block:: python

   from addipack import DeviceDiscovery
   devices = DeviceDiscovery.get_devices()
   for dev in devices:
      print(dev)

This will list the same devices returned by the CLI utility, with detailed information accessible via the API.


**Ready-to-use Samples**
------------------------

After installation, explore our samples located in ``$AddiPack_ROOT/samples``. Binaries are directly available for Windows users under ``bin/x64/generic`` or ``bin/win32/generic`` if using a 32 bits PC. Each sample source code is available under their respective subfolder.

+------------------------+------------------------------------------------------------+
| **Folder Name**        | **Purpose**                                                |
+========================+============================================================+
| ``get_devices_info``   | Lists all detected cards and their capabilities.           |
|                        | (only available in C)                                      |
+------------------------+------------------------------------------------------------+
| ``digital_io``         | Contains two samples, one for inputs                       |
|                        |  and the other one for outputs.                            |
+------------------------+------------------------------------------------------------+
| ``timer``              | Demonstrates timer start, stop and read operations.        |
+------------------------+------------------------------------------------------------+
| ``counter``            | Show pulse counting and interrupt handling.                |
+------------------------+------------------------------------------------------------+
| ``watchdog``           | Demonstrates watchdog timer setup and expiration behavior. |
+------------------------+------------------------------------------------------------+


Installation Known Issues
-------------------------

+---------------------------------------+-------------------------------------------------------------+
| **Issue**                             | **Solution**                                                |
+=======================================+=============================================================+
| Driver conflicts (Windows)            | Uninstall any previous AddiPack driver version, reboot.     |
+---------------------------------------+-------------------------------------------------------------+
| Driver conflicts (Linux)              | Remove conflicting drivers such as Comedi, then reload the  |
|                                       | Addi-Pack DKMS module.                                      |
+---------------------------------------+-------------------------------------------------------------+
| Card not detected                     | Check hardware slot, BIOS, or driver status.                |
|                                       | Try moving the card to a different slot if available.       |
+---------------------------------------+-------------------------------------------------------------+
| Dependency errors (Linux)             | Install dkms, glibc-devel, and kernel headers.              |
+---------------------------------------+-------------------------------------------------------------+
| Missing environment variable          | Add ``AddiPack_ROOT`` to ``/etc/environment`` manually.     |
+---------------------------------------+-------------------------------------------------------------+
| Unsigned driver warning (Windows 11)  | Use the official signed installer.                          |
+---------------------------------------+-------------------------------------------------------------+
| Wrong permissions on device files     | Adjust permissions with ``chmod``, or configure udev rules. |
+---------------------------------------+-------------------------------------------------------------+


Next sections:

- Continue to :ref:`api_guide` to start developing with Addi-Pack.
- Learn driver and interrupt mechanisms in :ref:`driver_concepts`.
- Try real interactive examples in :ref:`samples`.
