연동가이드

Serial API ​

토스 프론트에서 시리얼 포트 통신을 위한 API예요. 외부 장치와의 데이터 송수신을 지원해요.

Serial API를 통한 결제 처리

프론트에서 Serial API를 통해 결제를 처리하려면 멀티패드 연동 예제 소스를 참고해 주세요.

Methods ​

open ​

시리얼 포트를 열고 통신을 시작해요.

Parameters ​

파라미터타입필수기본값설명
optionsObject-시리얼 포트 설정
options.baudRatenumber9600통신 속도
options.interceptbooleanfalseVAN 결제 전문을 플러그인이 먼저 수신할지 여부

Example ​

js
/**
 * 시리얼 포트 열기
 * @param {Object} options 시리얼 포트 설정
 * @param {number} options.baudRate 통신 속도 (기본값: 9600)
 * @param {boolean} options.intercept VAN 결제 전문 인터셉트 여부 (기본값: false)
 */
await sdk.serial.open({ baudRate: 9600 });

Serial API를 통한 결제 처리에서는 VAN 결제 전문을 플러그인이 먼저 수신해야 하므로 intercept: true 설정이 필수예요.

js
await sdk.serial.open({ baudRate: 115200, intercept: true });

close ​

열려있는 시리얼 포트를 닫아요.

Example ​

js
/**
 * 시리얼 포트 닫기
 */
await sdk.serial.close();

write ​

시리얼 포트를 통해 데이터를 송신해요.

Parameters ​

파라미터타입필수기본값설명
dataObject✓-송신할 데이터 객체
data.dataUint8Array✓-송신할 데이터 배열

Example ​

js
/**
 * 시리얼 데이터 송신
 * @param {Object} data 송신할 데이터
 * @param {Uint8Array} data.data 송신할 데이터 배열
 */
await sdk.serial.write({ data: Uint8Array.from([0x04]) });

listen ​

시리얼 포트로부터 데이터를 수신해요.

Parameters ​

파라미터타입필수기본값설명
callbackFunction✓-수신된 데이터를 처리할 콜백 함수

콜백 함수 파라미터:

  • params.data (Uint8Array): 수신된 데이터 배열

Example ​

js
/**
 * 시리얼 데이터 수신 이벤트 리스너 등록
 * @param {Function} callback 수신된 데이터를 처리할 콜백 함수
 * @returns {Function} 이벤트 리스너 해제 함수
 */
const unlisten = sdk.serial.listen((params) => {
  console.log("수신된 데이터:", params.data); // Uint8Array
});

// 이벤트 리스너 해제
unlisten();

사용 예시 ​

시리얼 통신 관리 클래스 ​

js
class SerialManager {
  constructor() {
    this.isOpen = false;
    this.unlisten = null;
  }

  /**
   * 시리얼 포트 열기
   * @param {number} baudRate 통신 속도
   */
  async open(baudRate = 9600) {
    if (this.isOpen) {
      console.warn("이미 시리얼 포트가 열려있습니다.");
      return;
    }

    try {
      await sdk.serial.open({ baudRate });
      this.isOpen = true;
      this.setupEventListener();
    } catch (error) {
      console.error("시리얼 포트 열기 실패:", error);
      throw error;
    }
  }

  /**
   * 시리얼 포트 닫기
   */
  async close() {
    if (!this.isOpen) {
      console.warn("시리얼 포트가 열려있지 않습니다.");
      return;
    }

    try {
      await sdk.serial.close();
      this.isOpen = false;
      this.cleanupEventListener();
    } catch (error) {
      console.error("시리얼 포트 닫기 실패:", error);
      throw error;
    }
  }

  /**
   * 데이터 송신
   * @param {Uint8Array} data 송신할 데이터
   */
  async write(data) {
    if (!this.isOpen) {
      throw new Error("시리얼 포트가 열려있지 않습니다.");
    }

    try {
      await sdk.serial.write({ data });
    } catch (error) {
      console.error("데이터 송신 실패:", error);
      throw error;
    }
  }

  /**
   * 이벤트 리스너 설정
   */
  setupEventListener() {
    this.unlisten = sdk.serial.listen(this.handleData.bind(this));
  }

  /**
   * 이벤트 리스너 정리
   */
  cleanupEventListener() {
    if (this.unlisten) {
      this.unlisten();
      this.unlisten = null;
    }
  }

  /**
   * 수신 데이터 처리
   * @param {Object} params 수신된 데이터
   * @param {Uint8Array} params.data 수신된 데이터 배열
   */
  handleData(params) {
    console.log("수신된 데이터:", params.data);
    // 수신된 데이터에 따른 추가 처리 로직
  }
}

// 사용 예시
async function communicateWithDevice() {
  const serial = new SerialManager();

  try {
    // 시리얼 포트 열기
    await serial.open(9600);

    // 데이터 송신
    await serial.write(Uint8Array.from([0x04]));

    // 일정 시간 후 시리얼 포트 닫기
    setTimeout(async () => {
      await serial.close();
    }, 5000);
  } catch (error) {
    console.error("시리얼 통신 중 오류 발생:", error);
  }
}