.. _maintenance:

=======================
Maintenance Information
=======================

This section provides detailed guidance for **maintaining, updating, and troubleshooting** Addi-Pack installations.
It also includes information about compatibility, driver management, and release history.


Maintenance & Update Guide
--------------------------

.. admonition:: Goal

   Help you keep Addi-Pack up-to-date and ensure stable, reliable operation of your ADDI-DATA hardware.

This guide covers:

- Updating drivers and libraries
- Verifying DKMS and kernel module status
- Ensuring backward compatibility
- Accessing log and diagnostic files


Updating Addi‑Pack
~~~~~~~~~~~~~~~~~~

Addi-Pack provides **automatic update support** on all platforms.

**Linux**
^^^^^^^^^

1. Download the new `.deb` or `.rpm` package from your official distribution point (NAS, GitLab CI, etc.).
2. Uninstall the previous version:

   .. code-block:: bash

      sudo dpkg -r addipack             # For DEB-based distros
      sudo rpm -e addipack              # For RPM-based distros

3. Install the new version:

   .. code-block:: bash

      sudo dpkg -i addipack-2025.10.1.deb
      sudo rpm -i addipack-2025.10.1.rpm

4. Reboot your system or reload the kernel modules:

   .. code-block:: bash

      sudo modprobe -r apcie1032
      sudo modprobe apcie1032

Windows
-------

1. Uninstall the previous version via **Add/Remove Programs** or from the **Installer**.
2. Run the new `.exe` installer with **Administrator rights**.
3. Reboot your PC to reload the drivers and services (optional).


.. note::
   Always close your development environment (Visual Studio, Python interpreter, etc.)
   before updating Addi‑Pack to avoid file locks.


Environment Variable
~~~~~~~~~~~~~~~~~~~~

The ``AddiPack_ROOT`` environment variable is automatically created during installation.
It defines the root path used by Addi-Pack tools and libraries to locate:

- C/C++ API libraries
- Python bindings (if installed)
- Sample and utility directories

Normally, no manual action is required.
However, you can verify or adjust it for troubleshooting or custom installations.

**Windows:**

.. code-block:: powershell

   echo $Env:AddiPack_ROOT

**Linux:**

.. code-block:: bash

   echo $AddiPack_ROOT

If needed, the variable can be redefined manually:

**Windows (PowerShell):**

.. code-block:: powershell

   setx AddiPack_ROOT "C:\Program Files\AddiData\AddiPack"

**Linux:**

.. code-block:: bash

   echo "AddiPack_ROOT=/usr/local/addidata/addipack" | sudo tee -a /etc/environment
   source /etc/environment

.. tip::
   The installer automatically updates this variable during upgrades.


Uninstalling Addi‑Pack
~~~~~~~~~~~~~~~~~~~~~~

**Linux:**

.. code-block:: bash

   sudo apt remove addipack
   # or
   sudo dnf remove addipack

**Windows:**

Go to *Add or Remove Programs* → select **ADDI-DATA Addi-Pack** → *Uninstall*.

.. note::
   Uninstalling Addi-Pack doesn't remove user projects or log files.
   For log file locations, see the section below: *Locating Log Files*.
   However, installing a new version **replaces the official Addi-Pack source files** located in:

   - ``C:\Users\Public\Addi-Data\AddiPack\`` (Windows)
   - ``/opt/addi-data/AddiPack/`` (Linux)


Locating Log Files
~~~~~~~~~~~~~~~~~~

All sample applications and tests automatically create structured log files
to help diagnose configuration or runtime issues.

**Default locations:**

- **Linux:** `$HOME/.addi-data/`
- **Windows:** `%USERPROFILE%\\AppData\\Local\\addi-data\\`

Each log includes:

- Timestamp and card identifier
- Function calls and return codes
- Error messages and driver responses

.. tip::
   Logs can be safely shared with ADDI-DATA support for debugging.
   Sensitive information such as PCI addresses is anonymized.


Backward Compatibility
~~~~~~~~~~~~~~~~~~~~~~

Addi-Pack follows a date-based versioning scheme:

``YYYY.MM.PATCH``

- ``YYYY``: Release year (e.g., 2025)
- ``MM``: Release month (e.g., 09)
- ``PATCH``: Incremented for bug fixes or hotfixes within the same month

This versioning ensures clear traceability of releases and simplifies long-term maintenance.

**Compatibility Rules:**

- Versions with the same ``YYYY.MM`` are **backward compatible** (only patches differ).
- A bump in ``YYYY.MM`` may introduce new features.


Troubleshooting & Common Issues
-------------------------------

**Frequently Asked Questions:**

+-------------------------------------------------------+----------------------------------------------------------+
| **Question**                                          | **Answer**                                               |
+=======================================================+==========================================================+
| Why is my card not detected after installation?       | Check PCI/PCIe connection, power supply, and run the     |
|                                                       | application with administrator/root rights.              |
+-------------------------------------------------------+----------------------------------------------------------+
| Why do I see "No device found" when running a sample? | Make sure the Addi-Pack driver is loaded (`lsmod | grep  |
|                                                       | addipack`) and that the card is correctly inserted.      |
+-------------------------------------------------------+----------------------------------------------------------+
| Why are interrupts not triggering in my application?  | Ensure the interrupt mask, event type, and logic mode    |
|                                                       | are correctly configured.                                |
+-------------------------------------------------------+----------------------------------------------------------+
| Why does my timer or counter fail to start?           | The reload value might be too small or the timebase      |
|                                                       | might be invalid for the selected device.                |
+-------------------------------------------------------+----------------------------------------------------------+
| Can I use Python and C++ at the same time?            | Yes, but not on the same device handle. You must create  |
|                                                       | separate handles per language or process.                |
+-------------------------------------------------------+----------------------------------------------------------+

.. tip::
   If a card is still not detected, verify PCI/PCIe enumeration using:

   .. code-block:: bash

      lspci | grep ADDI

   or on Windows:

   *Device Manager → System devices → ADDI-DATA PCIe card*.


.. only:: not simplepdf

   Changelog
   =========

   **v2025.12.01 – Initial Release**

   - Unified driver architecture for Windows (KMDF), Linux (DKMS) and RTX
   - Shared API across C, C++, and Python
   - Cross-platform installer for Debian, Ubuntu, CentOS, and Windows
   - Supported cards:

     - APCI-1032 / APCIe-1032
     - APCI-1500 / APCIe-1500
     - APCI-1564 / APCIe-1564


Contact & Support
-----------------

For technical assistance or bug reports:

- 📧 **info@addi-data.com**
- 🌐 **https://www.addi-data.com**

When contacting support, always include:

- The **card model** (e.g. APCIe-1500)
- The **OS and kernel version**
- The **Addi-Pack version**
- Any **log files** related to your issue
- The **Serial Number** of your product(s)
