Logitech Hackathon Resources

This page contains resources for Logitech hackathon challenges. Have fun!

View on GitHub

LogiInsight Webcam — PC Python SDK

Version 1.5.2 · Windows, macOS and Linux · Python 3.9+

This SDK is for the LogiInsight webcam in your hackathon kit. The AI-enabled examples (face box, face mesh, AI JSON over USB networking) only work with that camera, because the AI runs inside it. With any other webcam (Logitech MX Brio, your own webcam, a laptop’s built-in camera) you can at most look at the video: the on-device AI results do not exist there. Use a desktop library such as MediaPipe for those cameras.

Python SDK and examples for the LogiInsight hackathon webcam. From a normal PC you can:

Download

The full reference is API reference. Using an AI assistant? See section 7.

No Conda / Anaconda. Use uv or plain pip + venv, as shown below.


1. Install

Unzip the download, then run the commands in the logiinsight_api folder. Pick one way.

uv (recommended) — install uv

uv sync                      # creates .venv and installs the dependencies
uv run python example_IR.py  # run any script through uv

pip + venv

# Linux / macOS
python3 -m venv .venv && source .venv/bin/activate
# Windows
#   py -m venv .venv
#   .venv\Scripts\activate
pip install -r requirements.txt

Dependencies: paramiko, numpy, opencv-python (the normal build, not opencv-python-headless, because the examples open windows), and for the microphone sounddevice, scipy and matplotlib.

Linux only: the microphone needs the PortAudio system library, otherwise importing sounddevice fails with PortAudio library not found:

sudo apt install libportaudio2

2. Plug in and check the video (no network setup needed)

Connect the camera with a USB 3 cable. Video works immediately. The camera shows up under these names (they start with the product name, LVNext by default):

Camera name What it is Used by this SDK
… Camera RGB sensor: MJPG / YUY2 / NV12 rgb_ai_capture.py, rgb_ai_live.py
… CPD Camera near-infrared sensor, MJPG, portrait frames example_IR.py
… Hello Camera Windows Hello stream not used: ignore it, camera apps cannot open it

The camera is also a USB microphone, so camera apps such as PotPlayer or Zoom list LVNext Microphone next to the cameras. That is expected (see the microphone section below).

uv run python example_IR.py          # live near-infrared view with contrast / threshold modes

If the wrong camera opens (for example a laptop’s built-in webcam), pass --device <index>; try 0, 1, 2 … until the picture is right.

Microphone (no network setup either)

The camera is also a USB microphone (LVNext Microphone by default). It sends 2 channels to the PC: raw 16-bit samples at 48 kHz, no noise suppression or other processing. Record 10 seconds and save a .wav plus a power-spectrum .png:

uv run python example_audio.py             # files go to ./audio_captures/
uv run python example_audio.py --list      # which input devices exist

Allow microphone access for your terminal (macOS: System Settings → Privacy & Security → Microphone; Windows: Settings → Privacy & security → Microphone).

The camera has 2 microphones, 2 cm apart. Some systems or audio APIs list the same microphone with 6 channels (on Windows, WASAPI shows 2 while MME / DirectSound / WDM-KS show 6). If you see 6 channels, keep channels 1 and 4 (counting from 1): those are the two microphones, and the others carry nothing useful. A 2-channel entry gives you the two microphones directly. example_audio.py records and plots every channel it is offered, so just look at channels 1 and 4. More in API reference.


3. Connect to the camera for the AI data (SSH/SFTP), step by step

rgb_ai_capture.py and rgb_ai_live.py read the AI results over SSH/SFTP through a virtual Ethernet adapter that the camera creates (USB NCM). The camera side is already set up and has the fixed address 192.168.1.10. On your PC you only do the following, once. The user name and password are on the card in your kit.

Step 1 — Plug in the camera with the USB 3 cable and give it a minute to start.

Step 2 — Find the new network adapter.

OS How
Windows Press Ctrl + R, type ncpa.cpl, press Enter. This opens Network Connections. A new Ethernet adapter appears when you plug in the camera (its name may contain USB, NCM or LVNext; it says Unidentified network). No new adapter? See “Windows does not show the adapter” below.
macOS System Settings → Network. A new entry appears when you plug in (for example LVNext or USB 10/100 LAN).
Linux ip -br link — look for the new adapter (usb0 or enx…).

Step 3 — Give that adapter a fixed address: IP 192.168.1.20, subnet mask 255.255.255.0, and leave router/gateway and DNS empty (so your Wi-Fi internet keeps working).

OS How
Windows In Network Connections (ncpa.cpl): right-click the new adapter → Properties → Internet Protocol Version 4 (TCP/IPv4) → Properties → Use the following IP address: IP 192.168.1.20, mask 255.255.255.0, gateway and DNS empty → OK → OK.
macOS Select the new entry → Details… → TCP/IP → Configure IPv4: Manually, IP 192.168.1.20, mask 255.255.255.0, router empty → OK.
Linux sudo ip addr add 192.168.1.20/24 dev <adapter> and sudo ip link set <adapter> up

Step 4 — Test the link: ping 192.168.1.10 must answer. (Windows: if the first ping times out and the others answer, that is fine.)

Step 5 — Give the SDK your user name and password (from the card). Do not write them into code or files. Set them as environment variables in the terminal you will run Python in:

export LOGIWEBCAM_USER='<user name on your card>'            # Linux / macOS
export LOGIWEBCAM_PASSWORD='<password on your card>'
set LOGIWEBCAM_USER=<user name on your card>                 &:: Windows (cmd)
set LOGIWEBCAM_PASSWORD=<password on your card>

(--user and --password exist too, but then the password shows in your shell history.)

Step 6 — Let the checker look at everything:

uv run python check_connection.py

It tests each step above (address, Wi-Fi clash, port 22, login, AI results, firmware) and prints [PASS], [WARN] or [FAIL] with the exact fix for your OS. Fix the first [FAIL] and run it again.

Step 7 — Run an RGB example:

uv run python rgb_ai_capture.py --face-mesh          # 10 annotated PNG+JSON pairs in ./captures
uv run python rgb_ai_capture.py --face-mesh --frames 30
uv run python rgb_ai_live.py --face-mesh             # live window with overlays (q / ESC quits)
uv run python rgb_ai_live.py --face-mesh --format NV12   # RGB as NV12 (MJPG is the default, YUY2 also works)

Optional: try the login manually

sftp <user name on your card>@192.168.1.10           # type the password when asked
sftp> ls /files/logi_conf                            # the AI files are here
sftp> bye

If your computer complains REMOTE HOST IDENTIFICATION HAS CHANGED because you used another device at this address before, run ssh-keygen -R 192.168.1.10 once and try again. The Python SDK is not affected.

Windows does not show the adapter

Press Ctrl + R, type devmgmt.msc. If a device called CDC NCM sits under Other devices: right-click it → Update driver → Browse my computer for drivers → Let me pick from a list of available drivers on my computer → Network adapters → Microsoft → UsbNcm Host Device. Step-by-step with pictures: Device drivers for CDC-NCM devices. Also try another USB 3 cable or port.

It works on Ethernet but not with Wi-Fi on (macOS, sometimes Windows)


4. Scripts

Script Purpose Needs SSH
rgb_ai_capture.py RGB: capture frames + AI JSON, save annotated PNG/JSON pairs (--format picks the RGB format: MJPG, YUY2 or NV12; --device-snapshot for exactly paired frames) yes
rgb_ai_live.py RGB: live window with face box / mesh overlays (--format picks MJPG, YUY2 or NV12; --no-overlay shows the raw picture) yes
example_IR.py Near-infrared live view: raw, contrast stretch, clahe, threshold, otsu (keys: m mode, +/- threshold, s save, q quit) no
example_audio.py Microphone: record 10 s (--duration), save a multi-channel .wav and a per-channel power-spectrum .png, print RMS / peak / strongest frequency no
check_connection.py Step-by-step check of the SSH/SFTP link, with fixes yes
logiwebcam.py The client library (LogiWebcamClient) —
camera_utils.py Camera discovery / opening helpers used by the IR example —
audio_utils.py Microphone discovery, multi-channel capture, power spectrum, WAV / PNG export —

All scripts stop cleanly on Ctrl+C (the camera is released and windows are closed).

uv run python example_IR.py --mode clahe
uv run python example_IR.py --width 1024 --height 1280

5. Things worth knowing

Why the picture and the JSON can differ (synchronization)

You get the AI results by a different route than the video: the video comes over USB (UVC), the AI JSON is a file the camera updates and that you read over SSH/SFTP. The AI also runs a little behind the video (it analyses a frame while the next ones are already streaming). So when you draw the latest JSON on the frame you just received, the box can sit slightly behind a moving face. That is expected, not a bug. It is most visible with fast motion.

If you need the box to match the picture exactly:

uv run python rgb_ai_capture.py --face-mesh --device-snapshot

This switches on the camera’s snapshot mode (enable_yuv_snapshot). The camera then saves, together with each JSON, the very frame the AI analysed; the SDK reads both and pairs them by an 8-byte timestamp in the file header (yuv_capture_timestamp_ms in the JSON), so image and JSON always belong together. The price: one snapshot takes about 2 seconds at 1920×1080, and the picture is the frame the AI saw, which is not necessarily the frame the live video showed at that moment — so the live image and the snapshot of the same instant can look different. The camera’s storage is small, so the examples switch the snapshot mode off again when they finish. Leave it off when you do not need it: while it is on, the camera’s log (/files/LogiApp.log) grows very fast.

If you do not want the camera’s built-in AI

Switch it off (the camera then runs no AI model; the JSON keeps updating, but its faces list stays empty):

from logiwebcam import LogiWebcamClient

with LogiWebcamClient() as cam:           # user name and password come from the environment
    cam.set_ai_config(enable_face_detection=False, enable_face_mesh=False)

This call is the only way to switch the AI off: opening the RGB camera as YUY2 or NV12 does not stop it (the AI runs on MJPG, YUY2 and NV12). The setting stays until a program changes it; the RGB examples switch face detection back on when they start.


6. Troubleshooting

Run python check_connection.py first; it finds most problems below.

Symptom Fix
No near-infrared (CPD) camera found Check the cable, close apps that use the camera, check the OS camera permission; try --device 0, 1, 2 …
IR example shows a colour or landscape picture Wrong camera: choose another --device.
SSH user name and password … required Set LOGIWEBCAM_USER and LOGIWEBCAM_PASSWORD (section 3, step 5) in the same terminal.
Authentication failed Compare with the card in your kit; copy the values exactly. In Windows cmd no quotes after set; in macOS/Linux use single quotes.
Failed to connect to 192.168.1.10 The adapter has no 192.168.1.x address yet (section 3), Wi-Fi uses the same subnet, or macOS needs the Local Network permission (see above).
AI JSON never changes / timestamp_ms frozen No program is reading the RGB stream (the AI only runs while it is open). On camera firmware 1.5.1 the stream must also be MJPG (--format MJPG, the default).
One stream does not start, the picture freezes or the frame rate drops when RGB and IR are open together RGB as MJPG slows the IR stream to about 1 fps: open RGB as NV12 or YUY2 (--format NV12). Depending on your system the opening order can matter: close both and open them in the other order (RGB first is the usual choice).
faces is always empty Face detection is switched off (set_ai_config(enable_face_detection=False)): switch it on again, or run rgb_ai_capture.py / rgb_ai_live.py, which do.
Cannot open … camera on Linux ls /dev/video*; add your user to the video group, log out and in.
macOS: black window / no frames Allow Camera access for the terminal app, then restart it.
The video freezes after the AI has run for a long time (about 10 minutes or more), or the camera feels hot The camera overheated. Unplug it, let it cool down, plug it in again. Run your experiments in shorter sessions and stop programs you are not using.
PortAudio library not found (Linux) sudo apt install libportaudio2
example_audio.py: no microphone found / silent channels Allow Microphone access for the terminal app; run --list and choose the camera’s entry with --device; on Windows the entries differ in channel count. With 6 channels keep channels 1 and 4 (see the microphone section); the other channels may be silent.

More in API reference.


7. Using an AI assistant with these docs

You can let a coding assistant (ChatGPT, Claude, Copilot, …) help you. Give it the documentation links instead of pasting files; most assistants can fetch them:

For example, start your chat with: *“Read these pages first, then help me write code for the LogiInsight webcam: . The camera's AI results come from an SSH/SFTP JSON file, the video from OpenCV."*

Never paste the user name or password from your kit card into a chat with an assistant or into a file you share. The code reads them from the LOGIWEBCAM_USER and LOGIWEBCAM_PASSWORD environment variables, and your assistant’s code should do the same.

License

MIT, see the LICENSE file in the zip. Copyright (c) 2026 Logitech Europe S.A.