DotMatrixLabs

Appearance

Plugin Lifecycle ​

Overview ​

This section contains all components and utilities for Plugin Lifecycle.

Components ​

ItemTypeDescription
PluginClassBase class for creating Dot X plugins.

Plugin ​

Base class for creating Dot X plugins.

Extend this class to create your own plugin. Override lifecycle methods like onLoad() and onUnload() to implement your plugin's behavior.

Use this.device.onUpdate() to respond to device value changes.

Example ​

typescript
import Plugin, { runPlugin } from '@dotmatrixlabs/dotx-plugin-sdk';

export default class MyPlugin extends Plugin {
  async onLoad() {
    console.log('Plugin loaded!');
    
    // Create settings UI
    await this.settingsPage.addSettings((settings) => {
      settings.addSection('general').setName('General');
      settings.addInput('apiKey')
        .setLabel('API Key')
        .setType('password')
        .setValue(this.config.get('apiKey', ''));
    });
    
    // Monitor device connections
    this.device.onConnect((device) => {
      console.log('Device connected:', device.name);
    });
    
    // Monitor device updates
    this.device.onUpdate((data) => {
      console.log('Device values updated:', data.changes);
    });
    
    // Show notification
    await this.ui.showToast({
      message: 'Plugin loaded successfully!',
      type: 'success'
    });
  }
  
  async onUnload() {
    console.log('Plugin unloading...');
  }
}

if (require.main === module) {
  runPlugin(MyPlugin);
}

Properties ​

  • actionmapper (ActionMapper): Action mapper for creating System Utilities buttons.
  • channelTargets (ChannelTargetsAPI): Channel targets API for reading apps, devices, and system features selected on channels.
  • config (PluginConfigStore): Local persistent configuration storage.

Store and retrieve plugin configuration data that persists across restarts.

  • device (DeviceAPI): Device management API for monitoring connections and updates.
  • settingsPage (any): Settings page builder for creating plugin settings UI.
  • ui (any): Global UI methods for showing toast notifications.

Methods ​

MethodParametersDescription
getConnectionStatus()-Gets the connection status of the plugin..
isConnected()-Checks if the plugin is connected to the host..
onLoad()-Called when the plugin is loaded and ready to run.
onUnload()-Called when the plugin is being unloaded or the application is shutting down.

getConnectionStatus() ​

typescript
getConnectionStatus(): string

Gets the connection status of the plugin.

Returns:

string - The connection status of the plugin

Example:

typescript
const connectionStatus = this.getConnectionStatus();
console.log('Connection status:', connectionStatus);

isConnected() ​

typescript
isConnected(): boolean

Checks if the plugin is connected to the host.

Returns:

boolean - True if the plugin is connected, false otherwise

Example:

typescript
const isConnected = this.isConnected();
console.log('Is connected:', isConnected);

onLoad() ​

typescript
onLoad(): Promise

Called when the plugin is loaded and ready to run.

Override this method to initialize your plugin, create settings UI, register action buttons, and set up any necessary resources.

Example:

typescript
async onLoad() {
  console.log('My plugin is loading...');
  
  // Initialize configuration
  this.config.init({
    schema: {
      settings: {
        type: 'object',
        properties: {
          apiKey: { type: 'string', default: '' }
        }
      }
    }
  });
  
  // Create settings UI
  await this.settingsPage.addSettings((settings) => {
    settings.addSection('general').setName('General');
    settings.addInput('apiKey')
      .setLabel('API Key')
      .setType('password');
  });
  
  // Add action button
  this.actionmapper
    .addSystemUtilButton('myAction')
    .setTitle('My Action')
    .onClick(({ selected, channel }) => {
      console.log(`Action triggered on channel ${channel}`);
    });
  
  console.log('Plugin loaded successfully!');
}

onUnload() ​

typescript
onUnload(): Promise

Called when the plugin is being unloaded or the application is shutting down.

Override this method to perform cleanup tasks like closing connections, saving state, or releasing resources.

Example:

typescript
async onUnload() {
  console.log('Cleaning up plugin resources...');
  
  // Save any pending data
  this.config.set('lastShutdown', new Date().toISOString());
  
  // Close connections
  if (this.mqttClient) {
    await this.mqttClient.end();
  }
  
  console.log('Plugin unloaded successfully');
}