Viana + Cisco Meraki: Technical Documentation

Table of Contents:

1.0 Overview

1.1 Requirements Compliance

1.2 Product Infrastructure

1.3 Standard Use Cases

2.0 API Integration Instructions

2.1 Edge Device Integration

2.2 Edge Server Integration

2.3 Edgeless Integration

3.0 MV Sense API Requests

3.1 Unique Provider Identifier (UPI)

3.2 Request Headers

3.3 API Requests

3.3.1 GET Live Analytics

3.3.2 GET Network Devices

3.3.4 GENERATE Snapshot

3.3.5 GET Camera Sense

3.3.6 GET Camera Sense Object Detection Model

3.3.7 GET Device Camera Analytics Overview

3.3.8 GET Device Camera Analytics Zones

---

1.0 Overview

This document outlines the technical requirements to run Viana on Cisco Meraki MV security camera system.

1.1 Requirements Compliance

Requirements	Description	Compliance	Reference
API Integration Instructions	Instruction documentation of Meraki integration with Viana.	YES	API Integration Instructions (In this document)
Unique Provider Identifier (UPI)	Unique string of letters and numbers used across various API services.	YES	Unique User Agent(In this document)
API Requests	API requests typically required to run Viana on Meraki cameras.	YES	API Requests (In this document)
Frequently Asked Questions	FAQs concerning the setup, use cases, and compatibility of Viana.	YES	Viana FAQ

1.2 Product Infrastructure

Viana™ a meldCX product is a vision analytics software that uses AI technology to capture anonymous visual data through high-performance mapping and detection of faces, objects, and surfaces in compliance with GDPR.

Figure 1.0: Viana Infrastructure

 

1.3 Standard Use Cases

Anonymous Audience Measurement 

Viana lets you anonymously detect people inside your spaces, tracking important data such as age, gender, mood, and time spent inside – without capturing personal identifiable information (PII).

People Counting

Viana allows you to set capacity for your physical spaces, and tracks traffic and capacity of entrances and zones to let you know how many people have entered and are present in various zones.

Traffic Management

Viana’s high-speed computer vision capability can detect license plates of moving vehicles and capture traffic data such as entry and exit time, parking count and occupancy, visit duration.

SAMi for Environments 

Surface Awareness Management Intelligence or SAMi™ for Environments is a patented feature of Viana, which tracks hand to surface interactions and sends alerts once the threshold is reached.

Content at the Right Opportunity

Viana’s content triggering feature enables integration with content platforms, where “rules” can be set to trigger content on screens based on the attributes of people present within the field of view.

Behaviour Tracking

Viana’s advanced capability can track gestures like a customer needing a basket, or suspicious movements that look like shoplifting – allowing staff to be notified and take appropriate action quickly.

 

---

2.0 API Integration Instructions

2.1 Edge Device Integration

Figure 2.1: Edge Device Setup

The Standard setup is a minimal on-premise installation that allows fast deployments to virtually any location inside the client facility. This setup leverages the MV Sense API to perform inference-on-demand on Viana – Viana only takes action upon certain events triggered by the MV Sense. Therefore, real-time actions are possible as application processes can happen on Viana’s certified edge devices.

Integration Requirements:

• Live Video RTSP Link
• Properly Configured RTSP IP Cameras

Integration Instructions:

1. Enable External RTSP in Meraki Cameras.
2. Open the Viana Edge Control Center in the edge device.
3. On the Sensors tab, click on Add Sensor.
4. On the Connect Sensor page, input the preferred name and select IP Camera (RTSP) for Sensor Type.
5. Enter required details in the form: 
• In the Address field, input the RTSP address of the Meraki Camera
• Skip the Username and Password fields (Meraki cameras do not require these details)
• In the Model field, select Meraki
6. Once all the details are entered, click on Connect.
7. Save settings before exiting.

2.2 Edge Server Integration

Figure 2.2: Edge Server Setup

The Enterprise setup is a robust version of Viana capable of running on-premise. This enables performance of real-time actions through an AI capable edge server (eg. Cisco Hyperflex) able to run multiple cameras for multiple use cases. With the processing being on-premise, this allows for instant triggers that are relevant to time-sensitive actions and instant alerts.

Integration Requirements:

• Live Video RTSP Link
• Cisco Meraki API Key
• Properly Configured RTSP IP Cameras
• Properly Configured Viana Sensors

Integration Instructions:

1. Enable External RTSP in Meraki Cameras.
2. Obtain Cisco Meraki API Keys in the Cisco Meraki Dashboard Settings.
3. Login to https://portal.viana.ai 
• Go to Sensors page
• Configure sensor settings
4. Open the Viana Edge Control Center in the edge device.
5. On the Sensors tab, click on Add Sensor.
6. On the Connect Sensor page, input the preferred name and select IP Camera (RTSP) for Sensor Type.
7. Enter required details in the form: 
• In the Address field, input the RTSP address of the Meraki Camera
• Skip the Username and Password fields (Meraki cameras do not require these details)
• In the Model field, select Meraki
8. Once all the details are entered, click on Connect.
9. Save settings before exiting.

2.3 Edgeless Integration

Figure 2.3: Edgeless Setup

The Lite setup is edgeless, which leverages MV Sense API to perform inference-on-demand on the Viana Cloud Platform. The setup uses the MQTT support of the Meraki cameras to trigger the processing in the cloud. The setup is designed for use cases that work with a minor delay.

Integration Requirements:

• Cisco Meraki API Key
• Properly Configured Viana Sensors

Integration Instructions:

1. Obtain Cisco Meraki API Keys in the Cisco Meraki Dashboard Settings
2. Login to https://portal.viana.ai 
• Go to Sensors page
• Configure sensor settings
3. Save settings before exiting.

---

3.0 MV Sense API Requests

This section describes the API request formats required to run Viana software on Cisco Meraki MV security camera system.

3.1 Unique Provider Identifier (UPI)

Viana’s unique provider identifier (UPI) will appear at the header of every API request. The unique user agent string follows standard semantic versioning as shown below:

User-Agent: 'viana/0.0.0 meldCX

 

3.2 Request Headers

Each request will contain the following headers:

{
    Content-Type: 'application/json',
    Accept: 'application/json',  
    User-Agent: 'viana/3.0 meldCX', 
    X-Cisco-Meraki-API-Key 'OUR_API_KEY',
    X-VIANA-SERIAL: 'VIANA_DEVICE_SERIAL',  
}

Code Snippet: Request Headers

 

3.3 API Requests

Viana’s standard setup uses GET and POST API requests. To run Viana using Meraki MV Sense APIs, these endpoints are utilised from the Cisco Meraki Dashboard API:

• /devices/{{CAMERA_SERIAL}}/camera/analytics/live
• /networks/{{NETWORK_ID}}/devices
• /devices/{{CAMERA_SERIAL}}/camera/generateSnapshot
• /devices/{{CAMERA_SERIAL}}/camera/sense
• /devices/{{CAMERA_SERIAL}}/camera/sense/objectDetectionModels
• /devices/{{CAMERA_SERIAL}}/camera/analytics/overview
• /devices/{{CAMERA_SERIAL}}/camera/analytics/zones

3.3.1 GET Live Analytics

Documentation: https://developer.cisco.com/meraki/api-v1/#!get-device-camera-analytics-live

Request: GET https://api.meraki.com/api/v1/devices/{{CAMERA_SERIAL}}/camera/analytics/live

Response:

{
    "ts": "2021-04-13T05:46:23.302Z",
    "zones": {
        "0": {
            "person": 0
        }
    }
}

Code Snippet: Get Live Analytics API Call

 

3.3.2 GET Network Devices

Documentation: https://developer.cisco.com/meraki/api-v1/#!get-network-devices

Request: GET https://api.meraki.com/api/v1/networks/{{NETWORK_ID}}/devices

Response:

[
    {
        "lat": 37.4180951010362,
        "lng": -122.098531723022,
        "address": "",
        "serial": "Q2GV-6QL8-DMKE",
        "mac": "ac:17:c8:0c:15:0c",
        "lanIp": "10.4.14.40",
        "url": "https://n280.meraki.com/Sydney-camera/n/LCSjVbye/manage/nodes/new_list/189218140460300",
        "networkId": "L_720575940379283973",
        "tags": [],
        "name": "Skunk Works Office MV12W",
        "model": "MV12W",
        "firmware": "camera-4-8",
        "floorPlanId": null,
        "wirelessMac": "ac:17:c8:0c:15:0d"
    }
]

Code Snippet: Get Network Devices API Call

 

3.3.4 GENERATE Snapshot

Documentation: https://developer.cisco.com/meraki/api-v1/#!generate-device-camera-snapshot

Request: POST https://api.meraki.com/api/v1/devices/{{CAMERA_SERIAL}}/camera/generateSnapshot

Response:

{
    "url": "https://spn4.meraki.com/stream/jpeg/snapshot/d72c450f51846535VHOGIzY2JkMDM5OTAzZjFhMTUyNWE1Y2ZjYTM1ODFkNmU2YzNhNjcxMTZhNzRiMjllMzc0MDU3YjljZmY2ZGJmNU23T1eksSeHJjZaRpOt3XQv8kQZzvnxbOF21n9C-j3SmicUvCXfcP21q387-jThmOYE4AQt0OEBmC8CWbNPYeM9suyV0VwOKjCuAHzwSb-aAWt6BL6EAfdpjkSUexmdzGEczvrU_yyntnw8DDQmxhO7LhmwmHmdfBBxrgAWS7QN_hWEuCpb9-qSOydGlUP0xdSWSMFhMyeLn8gZ76nIlcY",
    "expiry": "Access to the image will expire at 2021-04-12T23:58:38-07:00"
}

Code Snippet: Generate Snapshot API Call

 

3.3.5 GET Camera Sense

Documentation: https://developer.cisco.com/meraki/api-v1/#!get-device-camera-sense

Request: GET https://api.meraki.com/api/v1/devices/{{CAMERA_SERIAL}}/camera/sense

Response:

{
    "senseEnabled": true,
    "mqttBrokerId": "720575940379279394",
    "mqttTopics": [
        "/merakimv/Q2GV-6QL8-DMKE/720575940379279394",
        "/merakimv/Q2GV-6QL8-DMKE/raw_detections",
        "/merakimv/Q2GV-6QL8-DMKE/light"
    ],
    "detectionModelId": "0"
}

Code Snippet: Get Camera Sense API Call

3.3.6 GET Camera Sense Object Detection Model

Documentation: https://developer.cisco.com/meraki/api-v1/#!get-device-camera-sense-object-detection-models

Request: GET  https://api.meraki.com/api/v1/devices/{{CAMERA_SERIAL}}/camera/sense/objectDetectionModels

Response:

[
    {
        "id": "0",
        "description": "Body (default)"
    },
    {
        "id": "1",
        "description": "Body (experimental)"
    }
]

Code Snippet: Get Camera Sense Object Detection Model API Call

 

3.3.7 GET Device Camera Analytics Overview

Documentation: https://developer.cisco.com/meraki/api-v1/#!get-device-camera-analytics-overview

Request: https://api.meraki.com/api/v1/devices/{{CAMERA_SERIAL}}/camera/analytics/overview

Response:

[
    {
        "startTs": "2021-04-13T05:27:58.555Z",
        "endTs": "2021-04-13T06:27:58.555Z",
        "zoneId": 0,
        "entrances": 15,
        "averageCount": 0.037396226415094325
    },
    {
        "startTs": "2021-04-13T05:27:58.555Z",
        "endTs": "2021-04-13T06:27:58.555Z",
        "zoneId": 720575940379279394,
        "entrances": null,
        "averageCount": null
    }
]

Code Snippet: Get Device Camera Analytics Overview API Call

3.3.8 GET Device Camera Analytics Zones

Documentation: https://developer.cisco.com/meraki/api-v1/#!get-device-camera-analytics-zones

Request: GET https://api.meraki.com/api/v1/devices/{{CAMERA_SERIAL}}/camera/analytics/zone

Response:

[
    {
        "zoneId": "0",
        "type": "occupancy",
        "label": "Full Frame",
        "regionOfInterest": {
            "x0": "0.00",
            "y0": "0.00",
            "x1": "1.00",
            "y1": "1.00"
        }
    },
    {
        "zoneId": "720575940379279394",
        "type": "occupancy",
        "label": "table",
        "regionOfInterest": {
            "x0": "0.54",
            "y0": "0.52",
            "x1": "0.79",
            "y1": "0.90"
        }
    }
]

Code Snippet: Get Device Camera Analytics Zones API Call

 

CONTACT US

If you have any questions about Viana™  please reach out to us at [e-mail].