> For the complete documentation index, see [llms.txt](https://catchdocs.gitbook.io/catch-customer-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://catchdocs.gitbook.io/catch-customer-documentation/catch-control/overview.md).

# Overview

<figure><img src="https://3191043691-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdTGfthZOwExKcXtWjteP%2Fuploads%2FdYGSWqEuI7F8m6awAJqY%2Fimage.png?alt=media&amp;token=f63ebea2-b093-45b6-a620-936e2ddf3ceb" alt=""><figcaption></figcaption></figure>

Catch Control is an application that coordinates the flow of data between existing infrastructure on computers controlling digital advertising screens and Catch's platform components.

In overview, a [Provisioned](https://catchdocs.gitbook.io/catch-customer-documentation/catch-control/provisioning/what-is-provisioning.md) installation of Catch Control handles several communication channels:

## Media Player Communication

`Catch Control` communicates with the (typically 3rd party) software (`Media Player`) that is responsible for playing the media files shown on the advertising screens.

* Retrieves foreign content identifiers from the `Media Player`, and maps (`resolves`) them to the corresponding Catch content identifier (`catchable_id`).
* Retrieves and maintains state information from the `Media Player` and subsequently builds and maintains an internal timeline `playstate` of the content that is currently being played, and any guaranteed upcoming items, if known.
* If supported by the `Media Player`, or other pre-existing piece of infrastructure, `Catch Control` may optionally send audience measurement or audience prediction data to a specified `API` which may be associated with or attributed to a single item (`playback`) in the `playstate`
* If supported by the `Media Player`, or other pre-existing piece of infrastructure, `Catch Control` may optionally send notifications of events (`triggers`) of events happening within the catch platform, for example, user engagements or Catch system status.&#x20;

## Gateway Device Communication

`Catch Control` communicates with Catch Media Gateway devices (`gateway`) devices over USB or `VCOM Ports`:

* Performs operational tasks on the device
  * Attempts to detect the model of gateway device(s) connected, by interrogating connected devices' `VID` and `PID` and/or `COM Port` Names.
    * If successful it:
      * checks the firmware version(s) running on the connected device
      * compares the running firmware version with the firmware version bundled with the `Catch Control` release
      * Attempts to perform firmware update(s) on the device, if the bundled version is higher than the running version
      * If multiple devices are connected, it will communicate with the device with the most recently released model number, or at random if all model numbers are the same.
      * Initialise the services provided by the device (e.g `Catch` or `Flow`)
        * If any service cannot be successfully initialised, the chip controlling that service is reset, and the process repeats from the detection stage until successful. A reset counter, included in the `heartbeat` is incremented, and the last reset time is updated.
    * If unsuccessful in initialising a detected device, or in detecting a candidate device, a flag is included in a later `heartbeat` to the cloud to that effect, which can be viewed in `OOH Studio` by operational staff.
* Sends playstate information to the Catch service running on the connected device, allowing the device to broadcast synchronised playstates over BLE
* Sends measurement session `start` and `stop` triggers to the `Flow` service - in sync with each `playback`
* Retrieves the result of the Flow measurement session for further processing
* Receives catch event notifications from the `Catch` service on the device for further processing
* Processes BLE and WiFi wireless measurement results from the `Flow` service in numerous ways:&#x20;
  * Further categorises detections as high and low-quality detections in accordance with the (configurable) ignored devices policy, using parameters such as average signal strength (`RSSI)` and number of packets seen in the measurement period.&#x20;
  * The categorised wireless insights from the single `playback` are transformed using the (configurable) [human model](broken://spaces/ae4DBqfPZXEwzwi6g7SZ) equation into estimated human ad impressions. This human ad impression estimation is reported to:
    * Catch cloud services, annotated to the `playback` record.
    * Optionally, this result may also be sent to 3rd party (local or remote) listeners, for example, the `Media Player`
  * Results from multiple measurement sessions over extended time periods are processed locally, analysed, and processed in accordance with the (configurable) dwell and ambient policy definition to filter out omnipresent devices within each ad play measurement, as well as measuring the time individual devices spend in the range of the measurement device (dwell).
    * Device counts falling within the ambient category are appended to the `playback`
    * Dwell time reports are generated every 15 minutes and sent to a Catch Cloud Service

### Cloud Communication (Unprovisioned)

Depending on the method of installation of Catch Control, a customer may elect to add a `deploy.key` file to the installation directory. This key is a customer-specific identifer, allowing the catch control instance to communicate with the cloud in an unprovisioned state.

If this file is present **and** a `provisioning.json` file is **not** present, Catch control will ping Catch Cloud services every 5 minutes, with a report of identifiers and characteristics of the PC running Catch Control. A `fingerprint` is also included, a hash uniquely representing the contents of this report. Should any key/value change, the `fingerprint` will also change:

This system report aims to capture a set of (ideally persistent) identifiers about the PC itself, such as its MAC addresses, COM ports, as well as information retrieved from any detected `Media Player` instance running on that machine.

The data contained in these reports are visible to the customer in their `OOH Studio` dashboard before the instance is provisioned, and are designed to help customers identify remote PC installations based on other information they may have to hand to help map installations in the field to a corresponding catch `location_id`

Catch Control will continue to send these pings every 5 minutes until a ping response is received with a  provisioning instruction, or until the instance manually provisioned by other means. The provisioning repsonse contains the catch `location_id` that the instance should provision itself as, and is set as a mappaing between the `fingerprint` and `loaction_id` in OOH studio.

<details>

<summary>Example Unprovisioned Ping</summary>

```json
{
    "fingerprint": "59aec06ca1da2a2a1dfb1ada9bf7403edd8d30fe557c52b8dc36a7e87a9eb71c",
    "deploy_key": "$CUSOMER_DEPLOYMENT_KEY",
    "info": {
        "broadsign.installationID": "973839786",
        "broadsign.sources": [
            {
                "metadata": {
                    "height": 1024,
                    "name": "UK_MainAds",
                    "width": 768
                },
                "ref": "source:broadsign:963227264"
            },
            {
                "metadata": {
                    "height": 274,
                    "name": "UK_Widget",
                    "width": 768
                },
                "ref": "source:broadsign:963227265"
            },
            {
                "metadata": {
                    "height": 68,
                    "name": "UK_Header",
                    "width": 768
                },
                "ref": "source:broadsign:963227266"
            }
        ],
        "catchControl.candidateDevices": [
            "0131A52C (type: bloodaxe/oreo, ports: COM7, COM8)"
        ],
        "system.arch": "amd64",
        "system.cpus": 4,
        "system.name": "Player8",
        "system.net.ipAddresses": [
            "192.168.200.167"
        ],
        "system.net.macAddresses": [
            "00:69:23:16:00:0b"
        ],
        "system.os": "windows",
        "system.osVersion": "10.0.22631",
        "system.serialPorts": [
            {
                "name": "COM7",
                "pid": "EA70",
                "product": "Silicon Labs Dual CP2105 USB to UART Bridge: Standard COM Port (COM7)",
                "serial": "0131A52C",
                "usb": true,
                "vid": "10C4"
            },
            {
                "name": "COM1",
                "pid": "",
                "product": "Communications Port (COM1)",
                "serial": "",
                "usb": false,
                "vid": ""
            },
            {
                "name": "COM2",
                "pid": "",
                "product": "Communications Port (COM2)",
                "serial": "",
                "usb": false,
                "vid": ""
            },
            {
                "name": "COM3",
                "pid": "",
                "product": "Communications Port (COM3)",
                "serial": "",
                "usb": false,
                "vid": ""
            },
            {
                "name": "COM4",
                "pid": "",
                "product": "Communications Port (COM4)",
                "serial": "",
                "usb": false,
                "vid": ""
            },
            {
                "name": "COM5",
                "pid": "",
                "product": "Communications Port (COM5)",
                "serial": "",
                "usb": false,
                "vid": ""
            },
            {
                "name": "COM6",
                "pid": "",
                "product": "Communications Port (COM6)",
                "serial": "",
                "usb": false,
                "vid": ""
            },
            {
                "name": "COM8",
                "pid": "EA70",
                "product": "Silicon Labs Dual CP2105 USB to UART Bridge: Enhanced COM Port (COM8)",
                "serial": "0131A52C",
                "usb": true,
                "vid": "10C4"
            }
        ],
        "system.timezone": {
            "name": "BST",
            "offset": 3600
        },
        "system.username": "Player8\\admin"
    },
    "location_assignment": null,
    "created_at": {
        "date": "2024-03-31 02:03:47.468837",
        "timezone_type": 2,
        "timezone": "Z"
    },
    "last_seen_at": {
        "date": "2024-05-29 12:18:32.584984",
        "timezone_type": 2,
        "timezone": "Z"
    }
}
```

</details>

### Cloud Communication (Provisioned)

During normal operations, when `Catch Control` is `provisioned` it performs authenticated comms with the cloud:

* Requests to map content observed from the `Media Player` to a corresponding `catchable_id`
  * Previously successful mappings are re-requested for re-mapping on a (configurable) 1 hour interval
  * Never before successful mapping requests are requested on a (configurable) 1 minute interval
* `heartbeats` are reports, sent every 2 minutes containing:
  * A set of `playbacks` since the last heartbeat, annoted with aggregated `Flow` data and human modelleed audience data (if calculated)
  * A system snapshot
  * All logs since the last heartbeat (at the log level policy being observed locally)
