Sensor and Device Connection Guide

This page describes how to connect sensors and IoT devices to Gravio, including the device-side setup procedure and the underlying communication protocols.

For information about how to use these devices from action flows (component properties, etc.), see the Gravio Action Reference. For Web UI configuration, also see the Gravio HubKit Web UI Guide.

Table of Contents

• 1. Gravio LED Matrix Gen2
• 1.1 Hardware Overview
• 1.2 Initial Setup
• 1.3 Control Interfaces
• 1.4 MQTT Protocol Specification
• 1.5 HTTP API Specification
• 1.6 Hybrid Mode (Layer Composition)
• 1.7 Using from Gravio HubKit

1. Gravio LED Matrix Gen2

The Gravio LED Matrix Gen2 is a 32×32 pixel full-color LED matrix display device. It can be controlled either over MQTT (via Wi-Fi) or via HTTP.

Available since Gravio HubKit 6.3.0: For details on the dedicated components for this device, see Gravio HubKit / Gravio Studio Change Log: Gravio Matrix Gen2 Components.

Important: This second-generation device is a completely different product from the original Gravio Matrix (Gen1). The hardware, connection method and device ID format are all different. When controlling it from Gravio HubKit, you must use the dedicated Gravio Matrix Gen2 components (the two product lines are not interchangeable). See the Gravio Action Reference for details.

1.1 Hardware Overview

Power

• USB Type-C cable
• 5 V / 1 A power adapter

Buttons and Switches

1.2 Initial Setup

1. Connect power (USB Type-C). The device boots automatically and displays:
2. The Gravio logo (about 2.5 seconds)
3. The device name Gravio Matrix Gen 2 (about 2.5 seconds)
4. If Wi-Fi is not configured or the device cannot connect to the configured network, it boots into AP (access point) mode. The screen shows the current SSID (for example, Gravio-MTX-XXXXXXXX).
5. From a PC or smartphone, connect to that SSID using the password graviohub.

6. Open http://192.168.6.1:8080 in a browser. The User Login screen appears. Sign in with the following default credentials:

7. Username: gravio

8. Password: gravio

1. After signing in, the device configuration page is displayed. Click Configure WiFi and follow the on-screen instructions to set the SSID and password of your Wi-Fi network. The device reboots automatically after saving.
2. After reboot, the device connects to the configured Wi-Fi and the display shows the assigned IPv4 address.
3. Open that IP address in a browser with port 8080 (for example, http://<assigned IP>:8080). The same User Login screen appears. Sign in with the same default credentials as above to access the configuration page, then use Config device to change MQTT broker settings, etc.

Default MQTT broker: A vendor-provided test broker is configured out of the box. For production use you must switch to the HubKit's built-in MQTT broker or your own broker.

1.3 Control Interfaces

The Gravio LED Matrix Gen2 can be controlled via either of the following interfaces. Use one or the other for a given device.

The JSON message format is identical between the two interfaces.

1.4 MQTT Protocol Specification

Topic Naming Convention

All topics follow the pattern matrix/<MAC>/..., where <MAC> is the 12-digit MAC address of the device (lowercase hex, no colons), for example aabbccddeeff.

Message Payloads

Status notification (Pub) — matrix/<MAC>/status

{
  "device_id": "aabbccddeeff",
  "status": "online",
  "uptime": 3600,
  "wifi_signal": -65,
  "app_version": "1.0.2",
  "hw_version": "1.0.2"
}

Set configuration — matrix/<MAC>/config/set

{
  "brightness": 50,
  "rotation": 2
}

Get configuration — matrix/<MAC>/config/get

{}

Display text — matrix/<MAC>/display/text

{
  "text": "Hello World",
  "size": 1,
  "R": 100,
  "G": 0,
  "B": 0,
  "areaX": 0,
  "areaY": 16,
  "areaW": 32,
  "areaH": 16,
  "scrollSpeed": 100
}

Display GIF — matrix/<MAC>/display/image/gif

• Payload: GIF file (binary)

Display BMP — matrix/<MAC>/display/image/bmp

• Payload: BMP file (binary)

Enable / disable hybrid mode — matrix/<MAC>/display/hybrid/on / off

{}

Clear — matrix/<MAC>/display/clear

{}

Reboot — matrix/<MAC>/reboot

{}

1.5 HTTP API Specification

Base URL

http://<device-ip>:8080

Endpoints

The body of a POST request is either a JSON string or raw image binary data. The JSON schema is identical to the MQTT messages described in §1.4 MQTT Protocol Specification.

Quick Test

After confirming the device IP from the screen, you can quickly test text display using curl:

curl -X POST http://192.168.2.155:8080/display/text \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello","size":1,"R":100,"G":0,"B":0,"areaX":0,"areaY":16,"areaW":32,"areaH":16,"scrollSpeed":100}'

1.6 Hybrid Mode (Layer Composition)

In hybrid mode, multiple display elements are layered on top of each other. For example, you can display a BMP image as the background with scrolling text on top.

Layers may be combined in any order or quantity (e.g. bmp → gif → bmp → bmp → text → text).

Procedure

1. Send display/clear to clear the screen
2. Send display/hybrid/on to enable hybrid mode
3. Send display/image/gif / display/image/bmp / display/text commands in any order; each one is composed on top of the previous content
4. Once all desired content has been sent, optionally send display/hybrid/off to leave hybrid mode

1.7 Using from Gravio HubKit

To control the device from a Gravio HubKit action flow, use the dedicated action components. The HTTP or MQTT connection method is selected via the component's ConnectionType property.

Using an MQTT Connection

1. Create an MQTT Connection profile under Base Property Profiles, holding the broker URL, port, username, password, certificates, etc.
2. In the action component, set ConnectionType to MQTT and select the profile created above as the MQTT Connection base property.
3. Set the DeviceId property to the device's MAC address (12 hex digits, no colons). The MAC address can be found on the device's web configuration page.

Using an HTTP Connection

1. Set the action component's ConnectionType to HTTP.
2. Set the IPAddress property to the device's IPv4 address (for example, 192.168.6.1). The IP address is displayed on the device's screen after initial setup completes.

For a full description of every property, see the Gravio Action Reference.