Overview

This guide explains how twins communicate with each other in PhyStack. There are two fundamentally different approaches, each suited to different use cases.

Two Ways to Communicate

PhyStack provides two communication methods between twins:

Start with Twin Messaging - it works across any network and covers most use cases. Only use Real-Time Channels when you specifically need streaming or sub-10ms latency.

Twin Messaging (Hub-Based)

Events and Actions are routed intelligently — locally within a device when possible, or through the cloud hub when apps are on different devices. This is the recommended approach for most applications.

import { connectPhyClient } from '@phystack/hub-client';

const client = await connectPhyClient();
const instance = await client.getInstance();

// Broadcast event to subscribers (fire-and-forget)
instance.emit('statusUpdate', { status: 'ready' });

// Send event to specific twin (fire-and-forget)
instance.to(targetTwinId).emit('notification', { message: 'Hello' });

// Send action to specific twin (request-response)
instance.to(targetTwinId).emit('calibrateSensor', { target: 25 }, (result) => {
  console.log('Result:', result.status);
});

// Receive messages
instance.on('command', (data, respond) => {
  console.log('Received:', data);
  if (respond) respond({ status: 'success', message: 'Command processed' });
});

Why use it:

• Works across any network (VPNs, firewalls, cellular)
• No connection setup required
• Hub handles routing and delivery
• Simple API

Limitations:

• 50-200ms latency per message
• Best for small JSON payloads
• Not suitable for streaming

See Twin Messaging for the complete guide.

Real-Time Channels (WebRTC)

DataChannels and MediaStreams establish direct peer-to-peer connections for real-time communication.

// Using client and instance from the setup above
const instance = await client.getInstance();

// Create a DataChannel for low-latency messaging
const channel = await instance.getDataChannel(targetTwinId);
channel.send({ sensorReading: 42.5 });
channel.onMessage((data) => console.log('Received:', data));

// Listen for incoming MediaStream (e.g. camera feed)
instance.onMediaStream((stream) => {
  videoElement.srcObject = stream.getStream();
});

Why use it:

• Sub-10ms latency
• High throughput for large data
• Native video/audio streaming
• Direct device-to-device

Limitations:

• Requires compatible network (same LAN, STUN support, or public IP)
• May not work through strict firewalls or VPNs
• Connection setup overhead
• More complex error handling

See Real-Time Channels for the complete guide.

Decision Guide

Comparison Table

Next Steps

• Twin Messaging - Events, Actions, and the Instance API
• Real-Time Channels - WebRTC DataChannels and MediaStreams