Gravio HubKit Manual

Gravio HubKit External Integration Guide

Table of Contents

1. Webhook Integration

Gravio provides functionality to integrate with various external systems. Here, we'll explain how to receive messages from devices using Webhooks.

Webhook Setup Procedure

  1. Click the "Webhook" button to display the settings panel.

Webhook Button

  1. Register the Webhook URL in the settings panel. Click the "+" button to display the registration panel.

Webhook Registration Panel

  1. Enter and save the Webhook information:
  2. Name: Identifier for the Webhook
  3. Custom Path: Path string after "/webhook/urls/"
  4. Payload Format: Select the format of incoming data
  5. Authentication Type: None or BASIC authentication

Webhook Information Input

  1. Create a layer to record Webhook reception as data. Add a Webhook JSON layer to the area you're creating.

Add Webhook JSON Layer

  1. Bind the Webhook logical device to the created layer:
  2. Add the Webhook created in the registration panel.

Webhook Binding Settings

  1. Enable the added Webhook.

Webhook Enable

Webhook Configuration Details

Custom Path Specifications

Item Specification
Minimum length 8 characters
Maximum length 1000 characters
Allowed characters Alphanumeric, hyphen (-), underscore (_), slash (/)
Prohibited characters Spaces, tabs

Payload Format

Format HTTP Method Description
query-params GET Send data via URL query parameters
json POST Send data via JSON body

Authentication Type

Type Description
None Webhook accessible without authentication
BASIC authentication Requires username (4+ characters) and password (8+ characters)

Using Webhooks

Once the Webhook is enabled, you can receive messages from external devices. Received messages can be viewed in the data viewer. You can also set up actions triggered by received messages.

Webhook URL Format

Webhooks can be called using the following URL format:

https://<HubKit Host>/webhook/urls/<Custom Path>

For example, if HubKit's IP address is 192.168.1.100 and the custom path is sensor-data:

https://192.168.1.100/webhook/urls/sensor-data

Usage Examples (curl commands)

JSON format (POST):

curl -k -X POST https://192.168.1.100/webhook/urls/sensor-data \
  -H "Content-Type: application/json" \
  -d '{"temperature": 25.5, "humidity": 60}'

With BASIC authentication:

curl -k -X POST https://192.168.1.100/webhook/urls/sensor-data \
  -u username:password \
  -H "Content-Type: application/json" \
  -d '{"temperature": 25.5, "humidity": 60}'

query-params format (GET):

curl -k "https://192.168.1.100/webhook/urls/sensor-data?temperature=25.5&humidity=60"

Note: The -k option is required when using self-signed certificates. For production environments, it is recommended to configure proper SSL certificates.

2. MQTT Subscriber Integration

Gravio also supports MQTT subscribers. It receives messages sent by MQTT publishers through an MQTT broker by specifying topics.

MQTT Subscriber Setup Procedure

  1. In "Devices," select the MQTT type (DataKind) to add a new area and layer.
  2. For MQTT subscribers, choose whether the received data format is JSON or string.

MQTT Device Selection

  1. Click the settings button to display the MQTT subscriber and broker settings screen.

MQTT Settings Button

  1. Click the "+" button to display the topic entry settings screen.

MQTT Topic Entry Settings

  1. Click the list button to display the broker list screen.

  2. Click the "+" button to display the broker settings screen and enter broker information:

  3. Name: Broker identifier
  4. URL: MQTT broker URL
  5. Port: MQTT broker port number (standard is 1883)
  6. Authentication: Username, password, etc.

MQTT Broker Settings

  1. Enter broker information and click the add button.

MQTT Broker Information Input

  1. After the added broker information appears in the list, click the "Back" button.

MQTT Broker List

  1. Enter topic entry information and click save:
  2. Name: Topic identifier
  3. Broker: Previously registered broker
  4. Topic: MQTT topic to subscribe to
  5. Timeout: Connection timeout period
  6. QoS: Quality of Service level (0, 1, 2)

MQTT Topic Information Input

  1. The saved topic entry will be displayed in the list.

MQTT Topic List

  1. Click the "+" button to display the binding settings screen.

  2. Bind the configured MQTT to the layer.

    MQTT Binding Settings

  3. Finally, turn ON sensor data collection.

    MQTT Sensor Collection ON

3. i-PRO Integration

i-PRO is a surveillance camera sold by i-PRO Co., Ltd. Here's how to integrate with i-PRO in Gravio to receive AI-recognized data.

i-PRO Setup Procedure

  1. In "Devices," select the i-PRO type (DataKind) to add a new area and layer.
  2. For i-PRO, select from AI Crowd Detection Face Recognition, AI Motion Detection, or General as the data format to receive.

i-PRO Device Selection

  1. Click the settings button to display the i-PRO settings screen.

i-PRO Settings Button

  1. Enter the i-PRO camera name and MAC address, then click add:
  2. Copy the HubKit URL to clipboard for registration in i-PRO
  3. For registration details, refer to "i-PRO Camera Setup Guide"

i-PRO Information Input

  1. Click the "+" button to display the binding settings screen.

i-PRO Binding Settings Button

  1. Bind the configured i-PRO camera to the layer.

i-PRO Camera Binding

  1. Finally, turn ON sensor data collection.

i-PRO Sensor Collection ON

By following these steps, you can configure external system integration with Gravio HubKit.