AI Analyzer

1 Introduction

1.1 Purpose

These manual supplies technical and operational guidance for AIAnalyzer, an application that captures customer-vision data on networked kiosks and uploads it to a Digital Signage Server.

1.2 Scope

For software engineers, support and field technicians who operate and maintain AIAnalyzer.

1.3 Prerequisites

• Operating system: Windows 10 / 11 (x64)
• Runtime: .NET 6 Desktop Runtime
• Network: Bidirectional TCP / UDP connectivity between kiosks and the Digital Signage Server
• Privileges: Local administrator rights for installation and service control
• Firewall: Inbound rules are automatically set up on the kiosk by Digital Signage Server (InventoryOS)

2 System Architecture

Subsystems

1. Client Application (AIAnalyzer.exe) – Runs on each AI Analyzer PC; captures, buffers, and uploads customer-vision tracks.
2. Digital Signage Server (InventoryOS) – Runs on the kiosk; provides client discovery, configuration, heartbeat monitoring, and remote updates.

Network Protocols

• UDP 4000 – client broadcast ➔ server (discovery)
• TCP 4001 – bidirectional (control, data, heartbeats)
• HTTPS 443 – client ➔ API endpoint (track upload)

3 Client Components

3.1 Classes

AuthorizationHeader
Computes a time-variant HMAC-SHA256 signature and attaches it to every Web-API request.

CustomerDataManager

• Appends new track records to daily JSON files CustomerTrackUploadInfo_yyyyMMdd.json.
• Batches and uploads accumulated files at the configured interval (x hours).
• Purges archived files older than 30 days.

CustomerVisionHandler

• Subscribes to TracksUpdated and CustomerTrackRemoved.
• Correlates kiosk product actions with active vision tracks.
• Flushes completed tracks to CustomerDataManager (50 ms cadence; 5 min TTL, Time to live).

CustomerVisionSensor

Capture loop:

1. GetFrame() via DocumentCaptureBase (OpenCV)
2. DetectFaces() via FaceOps
3. Track IDs with CentroidTracker
4. EstimateAgeAndGender() via PersonOps
5. Publish GotRawImage, TracksUpdated, CustomerTrackRemoved

Thresholds, frame-rate limits, and sleep intervals come from CustomerVisionConfig.json.

3.5 GlobalSettings
In-memory store for WebServiceEndpoint, LocationID, KioskID, and dynamic flags. Values load from WebServiceConfig.txt or are pushed by the server.

3.2 Program (Main)

• Enforces single instance via mutex.
• Purges files older than 30 days.
• Loads configuration, starts core managers, and loops until a server replies, then spawns ServerCommunicator.
• Handles Ctrl + C for graceful shutdown.

3.3 Star

Update & Watchdog

• Startup Script: guarantees AIAnalyzer.exe is running at boot.
• Scheduled Task: every 5 minutes; restarts the client if the process is not detected.

4 Server Components

4.1 UDP Discovery Listener

Replies to DISCOVER broadcasts on UDP 4000 with PORT:4001.

4.2 Digital Signage Server (InventoryOS)

• Configures firewall on startup.
• Maintains client registry, sends product actions, responds to heartbeats, and pushes settings (WebGetSettings).

4.3 Remote Update Service

Update workflow:

1. Compare SHA-256 of local AIAnalyzer.tar.gz with the remote repository (SSH/SFTP).
2. If mismatched, upload the new tarball to staging.
3. Stop the AIAnalyzer process (idempotent).
4. Extract with 7-Zip.
5. Reboot the AI Analyzer PC.

5 Deployment & Configuration

5.1 Client Installation

1. Run Inventory OS or just copy AIAnalyzer.exe and all DLLs to C:\InstantDVD\AIAnalyzer\.
2. (Optional) Place a CustomerVisionConfig.json in the root folder for custom track capture camera settings.

Important: Must have UDP and TCP allowed: UDP:4000 and TCP: 4001.

5.2 Server Installation

Push InventoryOS together with AIAnalyzer and set AIInsightSensorEnabled = true on the kiosk.

• Ensure UDP 4000 and TCP 4001 are open for inbound traffic.

6 Operation & Maintenance

• Log rotation: automatic deletion of files older than 30 days.
• Health monitoring: Scheduled Task checks AIAnalyzer.exe every 5 minutes.
• Error audit: review [ERROR] entries in D:\Log\*.log and server QuickLogs daily.
• Update check: InventoryOS compares SHA-256 hashes on startup and applies remote updates as required.

7 Troubleshooting Guide

Issue: No server discovery

• Symptom: Client remains in DISCOVER loop.
• Resolution:
  1. Verify kiosk NIC is on the correct subnet.
  2. Confirm UDP 4000 is allowed through the server firewall.
  3. Check settings for blocked broadcasts.

Issue: Upload failures

• Symptom: JSON files pile up in the data queue.
• Resolution:
  1. Make sure the Webservice is correct, and that the PC has internet.
  2. Validate the Authorization Header secret (should not happen).
  3. Inspect proxy or SSL-inspection devices.

Issue: No tracks recorded

• Symptom: Zero inserts in the database.
• Resolution:
  1. Ensure the camera is detected by the OS.
  2. Restart AIAnalyzer.exe; if still failing, inspect or replace the camera cable (folded or damaged cables are common culprits).
  3. If on-site access is limited, remote into the AI Analyzer PC.

8 Change Management

1. Build and push InventoryOS or build the release artefact AIAnalyzer.tar.gz and push it to the kiosk.
2. InventoryOS triggers the remote-update workflow on startup and whenever a new tarball is detected.

9 Web Service API

Endpoint
POST /TrackUpload (SOAP-over-HTTP)

Server Behaviour

1. Perform a duplicate check against existing CustomerTracks.
2. Insert header row and retrieve the identity key.
3. Insert child product rows within the same transaction, rollback on any failure.
4. Return true on full success, false otherwise.

Appendix – Port Reference

• UDP 4000 – client broadcast ➔ server (discovery)
• TCP 4001 – client ↔ server (control, heartbeats, settings)
• TCP 22 – server ➔ client (remote update via SSH/SFTP)
• TCP 443 – client ➔ WebServiceEndpoint (track uploads via HTTPS)

10 Support & Troubleshooting Guide

Issue 1: No Server Discovery

Symptom: Client remains in a continuous DISCOVER loop.
Resolution:

1. Confirm that UDP port 4000 and TCP 4001 is allowed through the server’s firewall.
2. Check for any devices or settings blocking broadcast traffic.

Issue 2: Upload Failures

Symptom: JSON files accumulate in the data queue but isn’t uploaded.
Resolution:

1. Verify that the Webservice endpoint is correct and that the client machine has Internet access.
2. Validate the Authorization Header secret (failures here are exceptionally rare).

Issue 3: No Tracks Recorded

Symptom: Zero inserts are recorded in neither Json nor database.
Resolution:

1. Ensure that the camera is recognized by the operating system.
2. Restart AIAnalyzer.exe. If the issue persists, inspect or replace the camera cable (folded or damaged cables are common culprits).
3. Establish a remote connection to the AI Analyzer workstation if on-site access is limited.