Events and communication

Learn how to communicate between your plugin and the Dot X host application.

Overview

Your plugin communicates with the host through the SDK's high-level APIs. The SDK handles all connection management automatically — you just call the methods you need from onLoad().

Getting started

When you extend Plugin and call runPlugin(), your plugin automatically:

• Connects to the host application
• Registers itself using manifest.json
• Calls onLoad() only after registration is confirmed

You don't need to manage the connection yourself.

Reacting to device changes

Use this.device to listen for device events:

class MyPlugin extends Plugin {
  async onLoad() {
    // Device connected
    this.device.onConnect((device) => {
      console.log(`Connected: ${device.name} on ${device.port}`);
    });

    // Device disconnected
    this.device.onDisconnect((device) => {
      console.log(`Disconnected: ${device.name}`);
    });

    // Control values changed
    this.device.onUpdate(({ changes, sliders }) => {
      // Every control is included; skip the ones that did not move.
      for (const change of changes) {
        if (change.oldValue === change.newValue) continue;
        console.log(`Control ${change.index}: ${change.oldValue} → ${change.newValue}`);
      }
      console.log('All controls:', sliders);
    });

    // Query currently connected devices
    const devices = await this.device.getConnected();
    console.log(`${devices.length} device(s) connected`);
  }
}

Toast notifications

await this.ui.showToast({
  message: "Operation completed!",
  type: "success" // "info" | "success" | "warning" | "error"
});

Connection status

Your plugin is automatically connected when onLoad() is called. If you need to check status elsewhere:

// Wait for connection (rarely needed — onLoad guarantees it)
await this.waitForConnection();

// Check if connected
if (this.isConnected()) {
  console.log('Connected to host');
}

// Get detailed status
const status = this.getConnectionStatus();
// Returns: 'connected' | 'connecting' | 'disconnected' | 'destroyed'

Cleanup on shutdown

Use onUnload to clean up resources when your plugin shuts down:

class MyPlugin extends Plugin {
  private timer: NodeJS.Timeout | null = null;

  async onLoad() {
    this.timer = setInterval(() => { /* ... */ }, 1000);
  }

  async onUnload() {
    if (this.timer) clearInterval(this.timer);
  }
}

Error handling

Wrap API calls in try-catch and surface errors to the user via a toast:

try {
  await this.device.getConnected();
} catch (error) {
  await this.ui.showToast({
    message: "Failed to check devices. Please try again.",
    type: "error"
  });
}

Best practices

1. Keep onLoad fast — don't block initialization with long-running operations
2. Handle errors — always use try-catch for API calls
3. Clean up resources — implement onUnload to stop timers and close connections
4. Multiple listeners — you can call onConnect, onDisconnect, and onUpdate multiple times to register multiple callbacks