kcsdi-plugin-api

Core library for KCSDI application plugin development, providing cross-platform communication capabilities and runtime management features.

Key Features

🌐 Dual-protocol support - Unified TCP Socket & Serial port communication
🚀 Full-duplex communication - Supports bidirectional real-time data transfer
🔧 Runtime management - Theme switching/multi-language support out-of-the-box

Installation

# npm
npm install kcsdi-plugin-api
# yarn
yarn add kcsdi-plugin-api
# bun
bun install kcsdi-plugin-api

Quick Start

Basic Communication Example

import { Socket, getElectronAPI } from 'kcsdi-plugin-api';
import { useEffect, useRef } from 'react';

function CommunicationComponent() {
  // Create TCP connection instance
  const tcpSocket = useRef(new Socket({
    protocol: 'tcp',
    host: '127.0.0.1',
    port: 8973,
  }));

  // Create serial port connection instance
  const serialSocket = useRef(new Socket({
    protocol: 'serial',
    path: 'COM4',
    baudRate: 115200,
  }));

  useEffect(() => {
    const handleMessage = (data: Uint8Array) => {
      console.log('Received data:', new TextDecoder().decode(data));
    };

    const handleError = (err: Error) => {
      console.error('Connection error:', err.message);
    };

    // Event subscription
    const socket = tcpSocket.current;
    // const socket = serialSocket.current;
    socket.on('open', () => console.log('Connection established'));
    socket.on('message', handleMessage);
    socket.on('error', handleError);

    // Initialize connection
    socket.open();

    return () => {
      // Cleanup
      socket.close();
      socket.removeAllListeners();
    };
  }, []);

  return <div>Communication Component</div>;
}

Runtime Configuration Management

function RuntimeConfig() {
  useEffect(() => {
    const electronAPI = getElectronAPI();
    
    // Theme change listener
    const clearTheme = electronAPI.onChangeTheme((newTheme) => {
      document.documentElement.setAttribute('data-theme', newTheme);
    });

    // Language change listener
    const clearLanguage = electronAPI.onChangeLanguage((newLanguage) => {
      i18n.changeLanguage(newLanguage);
    });

    return () => {
      clearTheme();
      clearLanguage();
    };
  }, []);

  return null;
}

API Reference

Socket Class

Constructor

new Socket(options: ITCPSocketConnectionOptions | ISerialSocketConnectionOptions)

Core Methods

| Method | Parameters | Returns | Description | |--------------|----------------------|-------------|----------------------| | open() | - | Promise | Establish connection | | close() | - | Promise | Close connection | | send() | string/Uint8Array | Promise | Send data |

Event System

| Event | Listener Param | Trigger Condition | |---------------|--------------------|------------------------| | open | - | Connection established | | message | Uint8Array | Data received | | error | Error | Error occurred | | close | - | Connection closed |

Electron Runtime API

interface IElectronAPI {
  // Get serial port list
  getSerialPorts: () => Promise<Array<{ path: string }>>;
  
  // Theme management
  onChangeTheme: (callback: (theme: string) => void) => () => void;
  
  // Multi-language support
  onChangeLanguage: (callback: (lang: string) => void) => () => void;
}

Best Practices

1. Connection Management
   Recommended to establish connection when component mounts and clean up on unmount:

   useEffect(() => {
     const socket = new Socket({...});
     socket.open();
        
     return () => socket.close();
   }, []);

2. Error Handling
   Always listen to error events to prevent uncaught exceptions:

   socket.on('error', (err) => {
     console.error(`[${socketId}] Error:`, err);
   });

3. Binary Data Handling
   Use built-in conversion utilities:

   // Send binary data
   socket.send(new Uint8Array([0x01, 0x02]));
      
   // Receive processing
   socket.on('message', (raw) => {
     const text = socket.uint8ArrayToString(raw);
   });

License

MIT