Network & Firewall Requirements

This document outlines the network connectivity and firewall configuration requirements for deploying the Hearo Hub system in partner facilities.

Overview

The Hearo system is a complete on-premises healthcare monitoring solution consisting of:

• Hub (Hearo-Hub-ZWave-JS) - Raspberry Pi gateway for Z-Wave sensors

• MediaMTX Server - WebRTC streaming server for camera feeds

• Hearo Home Tablet - Android/iOS tablet running patient interface

• Cameras - RTSP-enabled IP cameras (Amcrest, etc.)

All components operate as client-only systems with no inbound connection requirements.

Required Outbound Connections

1. Hearo Remote Dashboard API (HTTPS)

Port: 443 Protocol: HTTPS Destination: remote.hearo.ai

Purpose:

• Primary REST API communication with Hearo backend

• Configuration retrieval

• Sensor data synchronization

• Device management

• Heartbeat/health checks (every ~55 seconds)

Traffic Pattern: Continuous, lightweight HTTP requests

---

2. Azure Event Hub (HTTPS/AMQP over TLS)

Port: 443 Protocol: AMQP over TLS (uses HTTPS port) Destination: hearoeventhub.servicebus.windows.net

Purpose:

• Streaming sensor event logs

• Real-time sensor value changes

• High-throughput telemetry data

Traffic Pattern: Continuous streaming, batched every 200ms

Technical Details:

• Uses Azure Event Hubs SDK (@azure/event-hubs)

• Connects to two hubs:

  • mainhub - sensor logs

  • mainhub_value_changed - sensor value changes

---

3. PubNub Real-Time Messaging (HTTPS/WebSocket)

Port: 443 Protocol: HTTPS/WebSocket over TLS Destination: *.pubnub.com (global CDN endpoints)

Purpose:

• Receive real-time commands from dashboard (e.g., unlock door, turn on light)

• Publish hub status updates

• Bidirectional messaging for device control

• Configuration update notifications

Traffic Pattern:

• Persistent WebSocket connection

• Automatic reconnection on network interruption

• Heartbeat messages every 10 minutes

Technical Details:

• Subscribes to Location_{locationId} channel

• Publishes with UUID format: {locationId}-hhub

---

4. MQTT over TLS (Optional)

Port: 8883 Protocol: MQTTS (MQTT over TLS) Destination: Variable (dynamically configured via PubNub)

Purpose:

• Optional Z-Wave network configuration interface

• Used by admin tools for device pairing/management

• Only connects when explicitly triggered from dashboard

Traffic Pattern: On-demand, infrequent

Notes:

• Connection details sent dynamically via PubNub

• Not required for normal hub operation

• Used primarily during installation/troubleshooting

---

5. Video Calling (OpenTok/TokBox & Twilio)

Ports:

• TCP 443 (signaling)

• UDP 3478 (STUN)

• UDP 10000-65535 (media streams)

Protocol: HTTPS + WebRTC (STUN/TURN)

Destinations:

• *.tokbox.com (OpenTok - current)

• *.opentok.com (OpenTok - current)

• *.twilio.com (Twilio Video - upcoming)

• stun.l.google.com:19302 (Google STUN servers)

• turn.hearolife.com (Hearo TURN server)

Purpose:

• Video calling between caregivers and residents

• Used by Hearo Home tablet app

• Peer-to-peer audio/video streaming

Traffic Pattern: On-demand during video calls

Notes:

• Currently using OpenTok/TokBox (Vonage)

• Migrating to Twilio Video

• Whitelist both services during transition period

---

6. MediaMTX WebRTC Streaming

Port: 443 (signaling via PubNub) Protocol: WebRTC Destination: Uses PubNub for signaling (already covered in #3)

Purpose:

• Streams camera feeds from on-premises MediaMTX server to dashboard

• WebRTC peer connection for low-latency video

• Allows remote viewing of local cameras

Traffic Pattern: Active when caregivers view camera feeds remotely

Technical Details:

• Uses STUN: stun.l.google.com:19302

• Uses TURN: turn.hearolife.com (credentials embedded)

• Signaling via PubNub channels

• No additional ports required beyond standard WebRTC UDP range

---

7. Local Network Devices

Ports: 80, 443, 554 (RTSP) Protocol: HTTP/HTTPS/RTSP Destination: Local IP addresses (same subnet as hub)

Purpose:

• Amcrest camera integration (HTTP/HTTPS)

• RTSP streams from cameras to MediaMTX

• Yeelight smart bulbs (local control)

• Other local IoT devices

Traffic Pattern: Local network only, no internet routing required

---

Inbound Connection Requirements

None required. All Hearo components operate in client mode and initiate outbound connections only.

Important Notes on NAT/Firewall Behavior

WebRTC (Video Calling & Camera Streams):

• Will work with zero inbound ports via TURN relay (turn.hearolife.com)

• Works better with outbound UDP allowed - enables direct peer-to-peer when possible

• If UDP is blocked, video still works but routes through TURN server (higher latency, more bandwidth on your TURN server)

• Modern stateful firewalls typically allow return traffic on outbound UDP automatically

MQTT (Admin Tools):

• Hub connects TO broker on port 8883 (client mode)

• All commands flow over that single persistent connection

• No inbound ports needed

Summary: The system is designed to work behind strict firewalls with only outbound TCP allowed. Allowing outbound UDP improves video quality but isn't required.

---

Firewall Configuration Recommendations

Minimum Required (Sensor/Hub Only)

ALLOW OUTBOUND TCP:
  - Port 443 to remote.hearo.ai
  - Port 443 to *.servicebus.windows.net
  - Port 443 to *.pubnub.com

Recommended (Full System with Video)

ALLOW OUTBOUND TCP:
  - Port 443 to remote.hearo.ai
  - Port 443 to *.servicebus.windows.net
  - Port 443 to *.pubnub.com
  - Port 443 to *.tokbox.com (video calling)
  - Port 443 to *.opentok.com (video calling)
  - Port 443 to turn.hearolife.com (TURN server)
  - Port 8883 to any (MQTTS for admin tools)

ALLOW OUTBOUND UDP:
  - Port 3478 to stun.l.google.com (STUN)
  - Ports 10000-65535 to any (WebRTC media streams)

Simplified (Less Restrictive Firewalls)

If your firewall allows stateful connection tracking:

ALLOW OUTBOUND TCP:
  - Port 443 to any
  - Port 8883 to any (optional)

ALLOW OUTBOUND UDP:
  - Port 3478 to any (STUN)
  - Ports 10000-65535 to any (WebRTC)

Firewall Rule Examples

Cisco ASA

access-list OUTSIDE_IN extended permit tcp any host remote.hearo.ai eq 443
access-list OUTSIDE_IN extended permit tcp any host hearoeventhub.servicebus.windows.net eq 443
access-list OUTSIDE_IN extended permit tcp any host *.pubnub.com eq 443

iptables (Linux)

iptables -A OUTPUT -p tcp --dport 443 -d remote.hearo.ai -j ACCEPT
iptables -A OUTPUT -p tcp --dport 443 -d hearoeventhub.servicebus.windows.net -j ACCEPT

Windows Firewall

New-NetFirewallRule -DisplayName "Hearo Hub - Dashboard API" -Direction Outbound -Action Allow -Protocol TCP -RemoteAddress remote.hearo.ai -RemotePort 443

---

Network Architecture

┌─────────────────┐
│   Hearo Hub     │
│  (Raspberry Pi) │
└────────┬────────┘
         │
         │ All outbound connections
         │
    ┌────▼─────────────────────────────┐
    │      Partner Firewall            │
    │  (HTTPS 443 outbound required)   │
    └────┬─────────────────────────────┘
         │
    ┌────▼──────────────────────────────────┐
    │           Internet                    │
    │                                       │
    │  ┌─────────────────┐                 │
    │  │ remote.hearo.ai │                 │
    │  └─────────────────┘                 │
    │                                       │
    │  ┌──────────────────────────────┐    │
    │  │ Azure Event Hub              │    │
    │  │ hearoeventhub.servicebus.net │    │
    │  └──────────────────────────────┘    │
    │                                       │
    │  ┌─────────────────┐                 │
    │  │ PubNub CDN      │                 │
    │  └─────────────────┘                 │
    └───────────────────────────────────────┘

---

Proxy/SSL Inspection Considerations

HTTPS/TLS Inspection

If your network uses SSL/TLS inspection (MITM proxy), ensure:

• Valid CA certificates are installed on the hub

• Azure Event Hub AMQP connections can pass through

• WebSocket upgrades for PubNub are not blocked

Environment Variable Override

For development environments with self-signed certificates:

IGNORE_TLS=true  # Disables TLS verification (dev only)

⚠️ WARNING: Do not use IGNORE_TLS=true in production environments.

---

Troubleshooting

Connection Issues

1. Hub not connecting to dashboard

   • Verify remote.hearo.ai is reachable on port 443

   • Check hub logs: docker logs hearo-hub

2. Sensor data not appearing in dashboard

   • Verify Azure Event Hub connectivity

   • Check for proxy/firewall blocking AMQP protocol

3. Commands not reaching hub

   • Verify PubNub connectivity (*.pubnub.com:443)

   • Check for WebSocket blocking in firewall

Testing Connectivity

From the hub device:

# Test dashboard API
curl -v https://remote.hearo.ai

# Test Azure Event Hub (DNS resolution)
nslookup hearoeventhub.servicebus.windows.net

# Test PubNub
curl -v https://ps.pndsn.com/time/0

---

Bandwidth Requirements

Hub + Sensors Only

• Typical usage: 5-10 Kbps (mostly idle)

• Peak usage: 50-100 Kbps (during sensor events)

• Monthly data: ~100 MB

With Video Calling (per active call)

• Audio/Video: 500 Kbps - 2 Mbps per call

• Duration: Varies (typically 5-15 minutes)

With Camera Streaming (per active stream)

• WebRTC stream: 1-3 Mbps per camera

• Duration: On-demand viewing only

Recommended Internet Connection

• Minimum: 5 Mbps down / 2 Mbps up

• Recommended: 10+ Mbps down / 5+ Mbps up (for multiple concurrent video streams)

---

Security Notes

1. No inbound ports - Hub is not externally accessible

2. All traffic encrypted - HTTPS/TLS for all connections

3. Certificate pinning - Azure/PubNub SDKs validate certificates

4. No sensitive data in logs - Connection strings/keys stored securely

---

Support

For questions about network configuration or firewall issues:

• Technical Support: [support contact]

• Documentation: See WARP.md in this repository

• Hub Software: Hearo-Hub-ZWave-JS/ directory

---

Last Updated: December 2025 Hub Software Version: 2.0.3