Unreal Engine Project "Heartbeat" – Readme

• Author: Copyright 2023 Roland Bruggmann aka brugr9
• Profile on UE Marketplace: https://www.unrealengine.com/marketplace/profile/brugr9
• Profile on Epic Developer Community: https://dev.epicgames.com/community/profile/PQBq/brugr9

---

Unreal Engine Project "Heartbeat" — Heart Rate Monitoring Integration

<div style='page-break-after: always'></div>

Description

An Unreal® Engine project as proof-of-concept for receiving physiological data from Polar® H10 heart rate monitor. A conceivable application could be an exercise game or a physical eSports tournament like «Arena Games Triathlon»™ (cp. [13]).

• Index Terms:

  • Physiological Measuring, Electrocardiogram, Heart Rate
  • Integration, Messaging, PubSub, Internet of Things, Machine to Machine

• Technology:

  • Unreal Engine, Polar H10 HR Sensor with Chest Strap, Polar Sensor Logger, Mosquitto
  • Bluetooth, USB, MQTT, JSON
  • Windows PowerShell, Chocolatey Package Manager, Android Debug Bridge, Wireshark

• Tags: UE, PolarH10, ECG, HR, HRM, PSL, ADB, BLE, USB, PubSub, MQTT, JSON, IOT, M2M

---

<div style='page-break-after: always'></div>

Table of Contents

<!-- Start Document Outline -->

• 1. Concept
• 2. Setup
  • 2.1. Firewall
  • 2.2. Wireshark
  • 2.3. Unreal Engine
    • 2.3.1. Plugin MQTT
    • 2.3.2. Demo Map and Demo Blueprint Overview
  • 2.4. Mosquitto
  • 2.5. Android Debug Bridge
  • 2.6. Polar Sensor Logger
• 3. Visualisation
  • 3.1. Messaging Startup
    • 3.1.1. Heartbeat Standby
    • 3.1.2. Heartbeat Update
  • 3.2. Messaging Teardown
• Appendix
  • Acronyms
  • Glossary
    • MQTT – Quality of Service
    • MQTT – Retain
    • HRM – Heart Rate Variability
    • HRM – RR Interval
  • A. References
  • B. Readings
  • C. Acknowledgements
  • D. Attribution
  • E. Disclaimer
  • F. Citation

<!-- End Document Outline --> <div style='page-break-after: always'></div>

1. Concept

We implement a general data flow as shown in listing 1.1.

Listing 1.1.: General Data Flow

Data Producer —(MQTT)→ MQTT-Broker —(MQTT)→ MQTT-Client

We use system components as follows (for the specific data flow see Listing 1.2.):

• Data Producer:
  • Polar H10 Heart Rate (HR) Sensor with Chest Strap (cp. [1])
  • Polar Sensor Logger (PSL) Android App (cp. [2])
• MQTT-Broker: Mosquitto as a Windows Service (cp. [6])
• MQTT-Client: Unreal Engine IoT plugin "MQTT"

Listing 1.2.: Specific Data Flow

Polar H10 –(Polar BLE SDK)→ Polar Sensor Logger –(MQTT)→ Mosquitto –(MQTT)→ Unreal Engine IoT-Plugin MQTT

The following shows the setup in reverse order of the data flow: Unreal Engine and Mosquitto on Windows—where we furthermore configure the firewall, use Wireshark and Android Debug Bridge, on Android we setup Polar Sensor Logger.

<div style='page-break-after: always'></div>

2. Setup

2.1. Firewall

MQTT standard port is 1883, we will use TCP as transport. In the Windows Defender Firewall we allow TCP port 1883, e.g., by using an administrative PowerShell (see listing 2.1.).

Listing 2.1.: Firewall Rule "Allow TCP Port 1883"

New-NetFirewallRule -DisplayName "Allow TCP Port 1883" -Direction inbound -Profile Any -Action Allow -LocalPort 1883 -Protocol TCP

2.2. Wireshark

We make use of Wireshark to monitor the MQTT messages sent over port 1883 (cp. [4] and [5]).

1. Launch an administrative PowerShell and install Wireshark, e.g., by using Chocolatey packet manager (cp. [3], see listing 2.2.).
2. Startup Wireshark and filter TCP port 1883 (see listing 2.3. and figure 2.1.).

Listing 2.2.: Use of Chocolatey to Install Wireshark

choco install wireshark

Listing 2.3.: Wireshark Filter TCP Port 1883

tcp.port == 1883

Figure 2.1.: Wireshark Dissecting Port 1883

<div style='page-break-after: always'></div>

2.3. Unreal Engine

Clone UE project "Heartbeat" using git, e.g., by git clone https://github.com/brugr9/Heartbeat51.git and startup the project.

2.3.1. Plugin MQTT

In the UE Heartbeat project we use the plugin "Built-In > IOT > MQTT" (see Figure 2.2.1.). Note: As of UE 5.1, the plugin is beta and not yet documented.

Figure 2.2.1.: Unreal Engine Plugins Browser Tab with Built-in IOT Plugin "MQTT"

In the "Project Settings > Plugin > MQTT"

• we use the "Connection > Default URL" values Host localhost, Port 1883 and Scheme MQTT.
• To be able to process data from a maximum heart rate of 210 bpm or from 210 messages per minute resp., we set the "Bandwith > Publish Rate" to double (Nyquist–Shannon sampling theorem), i.e. 420 messages per minute, which corresponds to 7 messages per second (7Hz). To ensure that the transmission of MQTT meta data is also guaranteed, we round up to the next 10Hz, i.e. 10 messages per second. (cp. figure 2.2.2.).

Figure 2.2.2.: Unreal Engine Project Settings, Plugins - MQTT

<div style='page-break-after: always'></div>

2.3.2. Demo Map and Demo Blueprint Overview

Map Map_PSL_Demo holds a Blueprint BP_PSL_Demo instance and additionally a TextRenderActor instance, which is assigned to the BP_PSL_Demo variable TextRender as Object Reference (see figure 2.3.).

Figure 2.3.: Map_PSL_Demo with instances of Blueprint BP_PSL_Demo and TextRenderActor in the Outliner and in the Viewport

<div style='page-break-after: always'></div>

Blueprint BP_PSL_Demo has components and variables as follows (see figure 2.4.):

• Scene Components:
  • Static Mesh Component HeartMesh
• Actor Components:
  • Rotating Movement Component
  • Timeline Component HeartbeatTimeline (see figure 2.5.):
    • External Curve: Default Asset Curve Template PulseOut
    • Lenght: 1.00
    • Looping: on
• Variables:
  • String MyTopic, default value set to psl/hr
  • MQTT-Client Object Reference MyClient
  • MQTT-Subscription Object Reference MySubscription
  • TextRenderActor Object Reference TextRender (public)
  • Timer Handle TextRenderVisibilityTimer

Figure 2.4.: Blueprint BP_PSL_Demo, Variable TextRender

Figure 2.5.: Blueprint BP_PSL_Demo, Timeline Component HeartbeatTimeline

<div style='page-break-after: always'></div>

Blueprint BP_PSL_Demo has events as follows (see figure 2.6.):

• Gameplay: EventBeginPlay, EventEndPlay
• Messaging: OnConnect, OnDisconnect, OnMessage, Teardown Messaging
• Visualisation:
  • Main: HeartbeatStandby, HeartbeatUpdate, HeartbeatDeactivate
  • Helpers: TextRenderBlink, HeartbeatReset
• Testing: Testing01, Testing02, Testing03

Blueprint BP_PSL_Demo has Event Graph sections as follows (see figure 2.6.):

• 'Startup Messaging' (color green, cp. section 3.1.)
• 'Teardown Messaging' (color violet, cp. section 3.2.)
• 'Testing' (color yellow, not documented here)
• 'Heartbeat' (color red, cp. section 3.1. and 3.2.)

Figure 2.6.: Blueprint BP_PSL_Demo, Event Graph Overview

<div style='page-break-after: always'></div>

2.4. Mosquitto

Install Mosquitto MQTT-Broker (cp. [6]) and start the Windows Service "Mosquitto Broker" (see figure 2.9.).

Figure 2.9.: Mosquitto Broker as Windows Service

2.5. Android Debug Bridge

On the Android device enable USB Debugging mode (cp. [7]):

1. Launch the Settings application.
2. Tap the About Phone option (generally found near the bottom of the list).
3. Then tap the Build Number option 7 times to enable Developer Mode. You will see a toast message when it is done.
4. Now go back to the main Settings screen and you should see a new Developer Options menu you can access.
5. Go in there and enable the USB Debugging mode option.
6. Connect the Android device to the PC by USB cable.

On the PC using an administrative PowerShell setup "Android Debug Bridge" ADB (cp. [7]):

1. Install "Android Debug Bridge", e.g., by using Chocolatey packet manager (cp. [3], see listing 2.4.)
2. Startup the "Android Debug Bridge" with mapping TCP port 1883 bidirectional (cp. [8], see listing 2.5.)

Listing 2.4.: Use of Chocolatey to Install Android Debug Bridge

choco install adb

Listing 2.5.: Android Debug Bridge Startup

adb reverse tcp:1883 tcp:1883
`