kcsdi-plugin-api

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

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

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

• Error Handling
  Always listen to error events to prevent uncaught exceptions:

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

• 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