Troubleshooting

Use this runbook to diagnose and resolve common integration issues when installing, configuring, or running seekcamera-python in your application.

This runbook covers the most frequent problems encountered when setting up seekcamera-python and integrating it with the Seek Thermal SDK, including SDK library discovery failures, Python dependency errors, camera connectivity issues, and log interpretation. It does not cover hardware defects, OEM core firmware updates, or issues specific to the Seek Thermal SDK's internal C implementation beyond what is observable from the Python bindings.

Before working through this runbook, confirm you have the following in place:

• Python 3.6 or later installed and accessible as python3
• seekcamera-python installed (via pip3 install seekcamera-python or a local editable install)
• Seek Thermal SDK 4.X installed on the host system — the minimum SDK runtime version required by your installed seekcamera-python release is:
  • seekcamera-python 1.0.0 → SDK 4.0.0+
  • seekcamera-python 1.1.0 / 1.1.1 → SDK 4.1.0+
  • seekcamera-python 1.2.0 → SDK 4.2.0+
• numpy >= 1 installed (pip3 install numpy)
• A Seek Thermal OEM core physically attached to the host system
• Sufficient permissions to access USB or other hardware interfaces on your OS

Work through the numbered steps below in order. Each step identifies a symptom, explains the likely cause, and tells you how to resolve it.

1. Verify the Seek Thermal SDK library is discoverable

Symptom: Importing seekcamera raises an OSError or similar error about a missing shared library (seekcamera.dll on Windows, libseekcamera.so on Linux).

Why this matters: The Python bindings use ctypes to load the native SDK library at import time. If the library is not in a location the loader checks, the import fails entirely.

On Linux, confirm the library exists in one of the following locations (checked in order of precedence):

$SEEKTHERMAL_LIB_DIR/
$LD_LIBRARY_PATH/
/lib/
/lib64/
/usr/lib/
/usr/lib64/

Run the following to check whether the library is found:

ldconfig -p | grep libseekcamera

If nothing is returned, either install the SDK .deb package or set the environment variable to point to the directory containing libseekcamera.so:

export SEEKTHERMAL_LIB_DIR=/path/to/sdk/lib

On Windows, confirm seekcamera.dll exists in one of these locations:

%SEEKTHERMAL_LIB_DIR%\
C:\Program Files\Seek Thermal\Seek Thermal SDK\4.X.X\x64-windows\lib

If it is missing from both, set the environment variable:

$env:SEEKTHERMAL_LIB_DIR = "C:\path\to\sdk\lib"

Success looks like: import seekcamera completes without error in a Python REPL.

2. Confirm SDK version compatibility

Symptom: The library loads but you encounter runtime errors or unexpected behavior immediately after initialization.

Why this matters: Each release of seekcamera-python requires a minimum SDK runtime version. A mismatch causes API incompatibilities that surface at runtime.

Check your installed seekcamera-python version:

pip3 show seekcamera-python

Cross-reference the version against the compatibility table in the prerequisites above, then verify the installed SDK version using the installer or package manager you used to install it. If the SDK is too old, install the required version from your Seek Thermal distribution package.

Success looks like: The seekcamera-python version and SDK runtime version satisfy the minimum version requirement in the table.

3. Verify Python dependencies are installed

Symptom: ImportError: No module named 'numpy' or similar errors when importing seekcamera or running a sample.

Why this matters: numpy >= 1 is a required runtime dependency. OpenCV (opencv-python >= 4) is additionally required if you are running the seekcamera-opencv sample.

Install required dependencies:

pip3 install numpy

If you are running sample applications, install all example dependencies at once:

pip3 install -r requirements.examples.txt

Success looks like: import numpy and (if needed) import cv2 complete without error.

4. Confirm the camera is physically connected and recognized by the OS

Symptom: Your application starts but no camera connect event fires, or the camera manager never discovers a device.

Why this matters: The SDK relies on the OS correctly enumerating the attached OEM core. If the hardware is not recognized at the OS level, the SDK cannot discover it.

On Linux, run:

lsusb

Look for a Seek Thermal device in the output. If it is absent, try a different USB port or cable, then run lsusb again.

On Windows, open Device Manager and check for the camera under the appropriate device category. Look for any warning icons indicating driver issues.

Also confirm your user account has permission to access the USB device. On Linux, you may need to add a udev rule or run your application with elevated privileges temporarily to test:

sudo python3 examples/seekcamera-opencv.py

If it works with sudo but not without, add a udev rule granting your user access to the device.

Success looks like: The device appears in lsusb / Device Manager, and your camera manager callback receives a connect event when you run your application.

5. Run a known-good sample application to isolate your code

Symptom: Your custom integration does not produce frames, but you are unsure whether the issue is your code or the environment.

Why this matters: The sample applications exercise the same core APIs and serve as a baseline. If a sample works, the problem is in your integration code, not the SDK or environment.

Run the simple sample from the repository root:

cd seekcamera-python
python3 examples/seekcamera-simple.py

Or, if OpenCV is installed:

python3 examples/seekcamera-opencv.py

Success looks like: The sample runs, connects to the camera, and either displays frames (OpenCV sample) or writes CSV output to disk (simple sample) without errors.

If the sample fails, revisit steps 1–4. If the sample succeeds but your code does not, compare your event handler and frame capture logic against the sample code.

6. Inspect log output for SDK error messages

Symptom: Something is wrong but the exact failure is not obvious from exceptions alone.

Why this matters: The SDK includes a logging interface that emits diagnostic messages. These messages often identify the root cause more precisely than the Python exception alone.

Enable verbose logging in your application by consulting the SDK's logging API (documented in the Seek Thermal SDK C Programming Guide included with the SDK). Capture the full log output when reproducing the issue — it will contain error codes and contextual information needed for further diagnosis or escalation.

Success looks like: Log output is captured and you can identify a specific error code or message that points to the cause.

7. Resolve pip3 install failures

Symptom: pip3 install seekcamera-python fails with a network error, permission error, or build error.

Why this matters: Installation failures prevent the library from being importable at all.

• Permission error: Use pip3 install --user seekcamera-python or install inside a virtual environment.

• Network error: Check your internet connection or corporate proxy settings. You can also clone the repository and install locally:

  Copy

  git clone https://github.com/seekthermal/seekcamera-python.git
  cd seekcamera-python
  pip3 install -e .
  

Success looks like: pip3 show seekcamera-python returns package metadata without errors.

After completing the relevant steps, confirm the following observable outcomes to be sure your environment is correctly set up:

1. Library loads cleanly:

   Copy

   python3 -c "import seekcamera; print('Import OK')"
   

   Expected output: Import OK with no exceptions.

2. Sample application runs end-to-end:

   Copy

   python3 examples/seekcamera-simple.py
   

   Expected: The application connects to the camera, captures at least one frame, and exits without unhandled exceptions.

3. No SDK library warnings in log output: When running your application, the SDK log should not contain messages about missing libraries, version mismatches, or device enumeration failures.

4. Camera connect event fires in your application: Your camera manager event callback receives a connect event within a few seconds of the camera being attached and the SDK being initialized.

The steps in this runbook are diagnostic and corrective rather than destructive, but if any changes you made cause new problems, reverse them as follows:

• Unset environment variables you added (SEEKTHERMAL_LIB_DIR, LD_LIBRARY_PATH additions) by closing the terminal session or explicitly unsetting them:

  Copy

  unset SEEKTHERMAL_LIB_DIR
  

  On Windows:

  Copy

  Remove-Item Env:SEEKTHERMAL_LIB_DIR
  

• Downgrade or reinstall seekcamera-python to the version you had before:

  Copy

  pip3 install seekcamera-python==<previous-version>
  

• Reinstall the previous SDK version using the installer package from your Seek Thermal distribution if you upgraded the SDK.

• Revert udev rule changes on Linux by removing the rule file you added from /etc/udev/rules.d/ and reloading:

  Copy

  sudo udevadm control --reload-rules
  

If you have worked through all steps and the issue persists, escalate to Seek Thermal support. When you do, provide the following information to enable faster diagnosis:

1. seekcamera-python version: output of pip3 show seekcamera-python
2. Seek Thermal SDK version: as reported by your SDK installer or package manager
3. Python version: output of python3 --version
4. Operating system and architecture: e.g., Ubuntu 22.04 x86_64, Windows 11 x64
5. Full error output: the complete traceback or error message you observe
6. Full SDK log output: captured with verbose logging enabled
7. Hardware details: which Seek Thermal OEM core you are using
8. Steps already attempted: which steps in this runbook you completed and what each one showed

Visit https://thermal.com for contact and support options. You can also open an issue on the seekcamera-python GitHub repository for community and maintainer assistance.