DotMatrixLabs

Appearance

Plugin Examples ​

Common patterns to get you started quickly.

Hello World ​

ts
import Plugin, { runPlugin } from "@dotmatrixlabs/dotx-plugin-sdk";

class HelloWorld extends Plugin {
  async onLoad() {
    await this.ui.showToast({ message: "Hello from plugin!", type: "success" });
  }
}

if (require.main === module) runPlugin(HelloWorld);

Settings page ​

Use this.settingsPage.addSettings() to build a settings UI with the builder DSL:

ts
class MyPlugin extends Plugin {
  async onLoad() {
    await this.settingsPage.addSettings((s) => {
      s.addSection('general').setName('General');

      s.addInput('apiKey')
        .setLabel('API Key')
        .setType('text')
        .setPlaceholder('Enter your API key')
        .setRequired(true)
        .onChange(({ value }) => {
          this.config.set('apiKey', value);
        });

      s.addSwitch('enabled')
        .setLabel('Enable feature')
        .setValue(this.config.get('enabled', true))
        .onChange(({ value }) => {
          this.config.set('enabled', value);
        });
    });
  }
}

See the SettingsBuilder Components reference for all available field types.

Reacting to device changes ​

ts
class MyPlugin extends Plugin {
  async onLoad() {
    this.device.onConnect((device) => {
      this.ui.showToast({ message: `${device.name} connected`, type: 'success' });
    });

    this.device.onDisconnect((device) => {
      this.ui.showToast({ message: `${device.name} disconnected`, type: 'warning' });
    });

    this.device.onUpdate(({ changes }) => {
      // 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}`);
      }
    });
  }
}

Persistent config ​

ts
class MyPlugin extends Plugin {
  async onLoad() {
    this.config.init({
      defaults: { broker: '192.168.1.1', port: 1883 }
    });

    const broker = this.config.get<string>('broker');
    this.config.set('broker', '10.0.0.1');
  }
}

Action mapper button ​

Register a button in the System Utilities panel:

ts
class MyPlugin extends Plugin {
  async onLoad() {
    this.actionmapper
      .addSystemUtilButton('myAction')
      .setTitle('Do Thing')
      .setIcon('fas fa-lg fa-bolt')
      .onClick(({ selected, channel }) => {
        this.ui.showToast({ message: `Clicked on channel ${channel}`, type: 'info' });
      });
  }
}

Toast notifications ​

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

Next steps ​