혹시 이런 상상 해본 적 있어? 내가 만든 웹사이트 버튼 하나로 책상 위 로봇 팔이 움직이고, 웹캠으로 찍은 내 얼굴 표정에 따라 LED 색깔이 바뀌는 거야. 공상 과학 영화에나 나올 법한 이야기 같다고? 놀랍게도, 이젠 이게 현실이 됐어. 바로 오늘 우리가 깊게 파고들 **Web Serial API** 덕분이지.

지금까지 웹(Web)은 스크린 안에 갇힌 세상이었어. 사용자가 마우스로 클릭하고 키보드로 입력하면, 웹페이지는 정해진 정보나 이미지를 보여주는 게 전부였지. 물론 WebGL 같은 기술로 화려한 3D 그래픽을 구현하고, WebRTC로 실시간 화상 채팅도 가능해졌지만, 여전히 '디지털 세상' 안에서의 이야기였어.

현실 세계의 '하드웨어'를 제어하려면 어땠을까? 보통은 C++, 파이썬, Java 같은 언어로 별도의 데스크톱 애플리케이션을 만들어야 했어. 사용자는 웹사이트 따로, 하드웨어 제어 프로그램 따로 설치하고 실행해야 하는 불편함을 겪었지. 웹 개발자가 하드웨어를 다루려면 완전히 새로운 개발 환경과 언어를 배워야 하는 높은 장벽이 있었고 말이야.

하지만 Web Serial API는 이 모든 판을 뒤집어 버렸어. 이제 우리가 가장 잘 아는 무기, **HTML, CSS, JavaScript만으로 웹 브라우저에서 직접! 시리얼 포트에 연결된 기기들과 통신**할 수 있게 된 거야. 이건 그냥 '신기한 기능 하나 추가'가 아니야. 웹의 경계를 허물고, 디지털과 현실을 잇는 거대한 다리를 놓은 것과 같아. 웹 개발의 패러다임이 바뀌는 순간이라고!

이 글에서는 Web Serial API가 정확히 무엇인지, 왜 이게 혁신적인지, 그리고 가장 중요한 '어떻게 사용하는지' 아주 쉽고 재미있게, 그리고 아주 깊게! 알려줄 거야. 아두이노로 LED를 켜고 끄는 간단한 예제부터 시작해서, 데이터 통신 시 발생할 수 있는 문제점과 해결법, 그리고 이 기술로 어떤 미친(?) 프로젝트들을 할 수 있을지에 대한 상상력까지 함께 나눠볼게. 준비됐어? 그럼, 브라우저 콘솔 창 열고 현실 세계로 접속해 보자고! 🚀

좋아, '웹에서 하드웨어를 제어한다'는 말에 가슴이 뛰기 시작했다면, 이제 그 마법의 주문인 'Web Serial API'의 정체를 파헤쳐 볼 시간이야. 이름이 좀 딱딱하게 들릴 수 있지만, 하나씩 뜯어보면 별거 아니야.

먼저 **'시리얼(Serial)'** 이라는 단어부터 이해해야 해. 우리 말로는 '직렬'이라고 하는데, 데이터가 한 줄로(one-by-one) 차례차례 전송되는 통신 방식을 말해. 마치 좁은 외길 터널을 자동차들이 한 대씩 순서대로 지나가는 모습이랑 비슷해. 한 번에 여러 데이터가 동시에 나가는 '병렬(Parallel)' 방식도 있지만, 시리얼 통신은 구조가 간단하고 먼 거리까지 안정적으로 데이터를 보낼 수 있어서 아두이노, 라즈베리파이 같은 마이크로컨트롤러나 3D 프린터, CNC, 각종 산업용 장비에서 아주 널리 쓰이고 있어.

컴퓨터에 있는 USB 포트도 사실상 내부적으로는 시리얼 통신을 사용해. 네가 아두이노를 USB 케이블로 컴퓨터에 연결하면, 컴퓨터는 이걸 'COM 포트'(윈도우)나 '/dev/tty...'(맥/리눅스) 같은 **가상 시리얼 포트**로 인식하게 돼. 그리고 이 포트를 통해 아두이노와 데이터를 주고받는 거지.

자, 그럼 **'Web Serial API'**는 뭘까? 바로 웹 브라우저가 이 시리얼 포트에 접근해서 데이터를 읽고 쓸 수 있도록 표준화된 방법을 제공하는 기술 명세(API)야. 여기서 API는 'Application Programming Interface'의 약자인데, 그냥 '프로그래밍할 때 가져다 쓸 수 있는 기능 모음' 정도로 생각하면 편해.

이 멋진 API는 구글 주도의 **'프로젝트 푸구(Project Fugu 🐡)'** 의 결과물 중 하나야. 프로젝트 푸구의 목표는 웹 앱이 네이티브 앱과 거의 동등한 수준의 기능을 갖도록 만드는 거야. 파일 시스템 접근, 클립보드 제어, 그리고 우리가 다루는 하드웨어 통신(Serial, USB, Bluetooth, HID) 같은 기능들을 웹 표준으로 가져오는 거지. 덕분에 이제 웹 개발자들은 상상력의 한계를 넓혀 훨씬 더 강력하고 다채로운 애플리케이션을 만들 수 있게 됐어.

가장 중요한 포인트는 **'보안'**이야. "아니, 웹사이트가 내 컴퓨터 포트를 마음대로 뒤져보면 어떡해?" 라는 걱정, 당연히 들 수 있지. 천만에! Web Serial API는 보안을 최우선으로 설계됐어.

• **사용자 동의는 필수:** 웹사이트가 시리얼 포트에 접근하려면, 반드시 사용자가 직접 특정 버튼을 클릭하는 등의 행동을 해야만 해. 그러면 브라우저가 "이 사이트가 시리얼 기기에 연결하려고 합니다. 허용하시겠습니까?" 라는 권한 요청 팝업을 띄워. 사용자가 여기서 명시적으로 '연결' 버튼을 눌러야만 다음 단계로 진행할 수 있어.
• **사용자가 기기 선택:** 권한을 허용하면, 컴퓨터에 연결된 시리얼 기기 목록이 나타나고, 사용자가 이 중에서 통신할 기기를 직접 선택해야 해. 웹사이트가 멋대로 아무 기기에나 접속할 수는 없어.
• **HTTPS는 기본:** Web Serial API는 보안 연결(HTTPS)이 적용된 페이지에서만 동작해. 중간에서 데이터를 가로채는 공격을 방지하기 위해서지.

결론적으로 Web Serial API는, **사용자의 명시적인 허락 하에, 안전한 방식으로, 웹페이지가 시리얼 통신을 할 수 있게 해주는 다리**라고 정리할 수 있겠네. 이제 이 다리를 건너서 뭘 할 수 있는지 좀 더 구체적으로 알아볼까?

"오, 신기하네. 근데 뭐... 나랑은 별 상관없는 얘기 같은데?" 라고 생각하는 웹 개발자가 있다면, 그 생각 잠시만 접어둬. 이건 단순히 아두이노 가지고 노는 메이커들만의 장난감이 아니야. 너의 커리어와 프로젝트에 엄청난 기회가 될 수 있어.

1. 웹 개발자: 너의 영토가 현실 세계로 확장된다!

지금까지 너의 무대는 브라우저 안이었어. 하지만 이제 그 경계가 사라져. 네가 만들던 웹사이트가 현실의 사물과 상호작용하기 시작한다고 생각해봐.

• IoT 대시보드: 스마트팜의 센서 데이터(온도, 습도, 조도)를 받아서 실시간으로 웹 차트에 뿌려주고, 웹페이지의 버튼으로 물 펌프나 LED 조명을 제어하는 관리자 페이지를 만들 수 있어. 더 이상 데이터를 클라우드에 올리고 다시 받아오는 복잡한 과정 없이, 로컬 네트워크의 게이트웨이 장비와 직접 통신해서 말이야.
• 디바이스 설정 도구: 3D 프린터나 드론, 산업용 로봇 같은 장비들의 펌웨어를 업데이트하거나, 세부 설정을 변경하는 웹 기반 유틸리티를 만들 수 있어. 사용자는 더 이상 운영체제에 맞는 복잡한 설정 프로그램을 찾아 헤맬 필요가 없지. 그냥 장비를 USB에 꽂고, 너의 웹사이트에 접속하기만 하면 돼.
• 교육용 플랫폼: 코딩 교육 사이트에서 학생들이 작성한 코드를 실제 아두이노 보드에 즉시 업로드하고 결과를 눈으로 확인하게 할 수 있어. 시뮬레이션이 아닌 '진짜' 하드웨어를 움직여보는 경험은 학습 효과를 극대화할 거야.
• 인터랙티브 아트 & 전시: 미술관이나 전시회에서 관람객의 움직임이나 소리를 센서로 감지해서, 그에 맞춰 웹 기반 미디어 아트가 실시간으로 변화하는 작품을 만들 수 있어. 웹 기술과 현실의 예술이 만나는 환상적인 경험을 선사할 수 있지.

이 모든 게 네가 이미 알고 있는 JavaScript로 가능하다는 게 핵심이야. 새로운 언어를 배울 필요 없이, 너의 스킬셋을 그대로 활용해서 완전히 새로운 차원의 결과물을 만들어낼 수 있는 거지.

2. 메이커 & 하드웨어 엔지니어: GUI 개발, 더 이상 고통받지 말자!

아두이노나 라즈베리파이로 멋진 프로젝트를 만드는 친구들! 항상 마지막에 부딪히는 장벽이 있지? 바로 '사용자 인터페이스(UI)'야. C++로 만든 펌웨어는 완벽한데, 이걸 일반 사용자가 쉽게 제어할 수 있는 프로그램을 만드는 건 또 다른 세계의 이야기지. Processing, Qt, C# WinForms... 배우는 데만 한 세월이야.

이제 그럴 필요 없어! 세상에서 가장 강력하고 만들기 쉬운 GUI 툴킷인 HTML/CSS/JS를 사용하면 돼.

• 초고속 프로토타이핑: 네가 만든 센서의 값을 그냥 콘솔에 찍어보는 대신, 웹페이지에 예쁜 그래프로 실시간 시각화해봐. Chart.js 같은 라이브러리를 쓰면 몇 줄 안 되는 코드로 가능해. 버튼 몇 개, 슬라이더 몇 개 만들어서 파라미터를 실시간으로 바꿔보는 것도 순식간이지.
• 크로스플랫폼은 기본: 윈도우, 맥, 리눅스, 심지어 안드로이드(크롬 브라우저)에서도 똑같이 동작하는 제어판을 만들 수 있어. OS별로 따로 빌드하고 배포할 필요가 전혀 없지.
• 풍부한 생태계 활용: React, Vue, Svelte 같은 최신 프론트엔드 프레임워크를 사용해서 복잡하고 반응성이 뛰어난 UI도 쉽게 구축할 수 있어. 웹의 거대한 생태계를 내 하드웨어 프로젝트에 그대로 이식하는 거야.

이런 능력을 갖추면, 너의 프로젝트는 그냥 '나만 아는 장난감'이 아니라, 다른 사람들도 쉽게 사용하고 즐길 수 있는 '완성된 제품'에 가까워질 수 있어. 이런 특별한 기술을 가진 전문가를 찾는 곳도 많아지고 있지. 예를 들어 **재능넷** 같은 플랫폼에서 "웹 기반 하드웨어 제어 전문가"로 활동하며 너의 재능을 필요로 하는 사람들을 도와줄 수도 있을 거야.

3. 산업 현장: 유지보수와 관리의 혁신

공장이나 연구소에 있는 수많은 장비들을 생각해봐. 이 장비들은 대부분 시리얼 포트를 통해 상태를 모니터링하고 제어해. 지금까지는 각 장비 제조사가 제공하는 전용 소프트웨어를 특정 PC에 설치해서 사용해야 했어.

Web Serial API를 도입하면, 현장 엔지니어는 그냥 태블릿 하나 들고 다니면서 장비에 USB 케이블을 연결하고, 웹 브라우저를 열어서 바로 장비의 상태를 진단하고 펌웨어를 업데이트할 수 있게 돼. 중앙 관제실에서는 모든 장비의 데이터를 웹 기반 대시보드에서 통합 모니터링할 수도 있지. 이건 유지보수 효율성을 엄청나게 높여주고, 비용을 절감하는 혁신적인 변화를 가져올 수 있어.

어때? Web Serial API가 그냥 신기한 기술을 넘어, 웹 개발의 새로운 블루오션이자, 다양한 분야의 문제를 해결할 수 있는 강력한 도구라는 게 느껴지지? 그럼 이제 진짜 코드를 만져볼 시간이 된 것 같아. 백문이 불여일견이니까!

이론은 충분히 들었으니 이제 손가락을 풀 시간이야. 가장 기본적이면서도 확실한 방법으로 Web Serial API의 작동 방식을 하나하나 뜯어보자. 우리의 든든한 친구, 아두이노와 함께라면 어렵지 않아!

모든 코드는 비동기(Asynchronous)로 동작한다는 걸 기억해. 하드웨어와의 통신은 언제 끝날지 모르기 때문에, 프로그램이 마냥 기다리면서 멈춰있으면 안 되잖아? 그래서 `Promise`와 `async/await` 문법을 적극적으로 사용할 거야. 이게 좀 낯설다면, '시간이 걸리는 작업 앞에는 `await`를 붙여서 기다려주고, 그 함수 앞에는 `async`를 붙여준다' 정도로만 일단 이해하고 넘어가도 좋아.

자, 이제 단계별로 API를 정복해 보자.

Step 1: 시리얼 포트 요청하고 선택하기

모든 것의 시작이야. 웹사이트가 시리얼 포트에 접근하기 위한 첫 번째 관문이지. 보안상의 이유로, 이 과정은 반드시 **사용자의 직접적인 행동(User Gesture)**, 예를 들면 버튼 클릭에 의해서만 시작될 수 있어. 그냥 페이지가 로드되자마자 몰래 포트를 스캔하는 건 절대 불가능해.

핵심 코드는 `navigator.serial.requestPort()` 야.

<!-- index.html -->
<button id="connectButton">아두이노에 연결하기</button>

<script>
  const connectButton = document.getElementById('connectButton');

  connectButton.addEventListener('click', async () => {
    // Web Serial API를 지원하는지 확인
    if ('serial' in navigator) {
      try {
        // 사용자에게 시리얼 포트를 선택하라는 메시지를 표시
        const port = await navigator.serial.requestPort();
        console.log("포트 선택 완료!", port);
        // 여기에 포트를 열고 통신하는 코드가 이어짐
      } catch (err) {
        // 사용자가 선택을 취소했거나 오류가 발생한 경우
        console.error("포트 선택 중 오류 발생:", err);
      }
    } else {
      alert("お使いのブラウザは Web Serial API をサポートしていません。");
    }
  });
</script>

이 코드를 실행하고 '아두이노에 연결하기' 버튼을 누르면 어떻게 될까? 브라우저가 다음과 같은 팝업창을 띄울 거야.

*(상상 속의 이미지: 브라우저 상단에 "이 사이트에서 시리얼 포트에 연결하려고 합니다." 라는 메시지와 함께 컴퓨터에 연결된 시리얼 장치 목록(예: "Arduino Uno (COM3)")이 표시되고, '연결'과 '취소' 버튼이 있는 팝업창)*

사용자가 여기서 자신의 아두이노를 선택하고 '연결'을 누르면, `requestPort()` 함수는 선택된 포트를 나타내는 `SerialPort` 객체를 반환해. 이 `port` 객체가 바로 우리가 앞으로 아두이노와 대화할 때 사용할 리모컨이야. 만약 사용자가 '취소'를 누르거나 창을 닫으면, `catch` 블록으로 에러가 전달돼.

Step 2: 포트 열고 통신 준비하기

리모컨(`port` 객체)을 손에 넣었으니 이제 전원을 켤 차례야. 바로 `port.open()` 메소드를 사용하는 거지. 포트를 열 때는 통신 규칙을 정해줘야 해. 그중 가장 중요한 게 **보드레이트(Baud Rate)** 야.

자, 아까 얻은 `port` 객체를 사용해서 포트를 열어보자.

// Step 1에서 이어지는 코드...
// const port = await navigator.serial.requestPort();

// 포트를 열고 통신 속도를 9600으로 설정
await port.open({ baudRate: 9600 });
console.log("포트가 성공적으로 열렸습니다!");

// 이제 데이터를 읽고 쓸 준비가 완료됨!

`port.open()` 역시 비동기 함수라서 `await`를 사용했어. 이 코드가 성공적으로 실행되면, 이제 웹페이지와 아두이노 사이에 보이지 않는 데이터 파이프라인이 연결된 거야. 이제 이 파이프라인으로 데이터를 흘려보내고 받아보자.

Step 3: 데이터 읽고 쓰기 (The Core!)

드디어 핵심 파트야. Web Serial API는 최신 웹 기술인 **스트림(Streams API)**을 기반으로 데이터를 처리해. 데이터를 한 번에 몽땅 가져오는 게 아니라, 물 흐르듯이 계속해서 들어오는 데이터 조각들을 처리하는 방식이지. 그래서 '읽기용 스트림'과 '쓰기용 스트림'이 따로 있어.

데이터 읽기 (아두이노 -> 웹페이지)

아두이노가 보내는 데이터를 웹페이지에서 받으려면, `port.readable` 스트림을 사용해야 해. 코드가 조금 복잡해 보일 수 있지만, 원리는 간단해. "계속해서 문을 두드리고, 새로운 데이터가 도착하면 화면에 보여줘" 라는 반복 작업을 하는 거야.

// 데이터를 계속해서 읽어오는 함수
async function readData(port) {
  // TextDecoder는 아두이노가 보낸 숫자 데이터(Uint8Array)를
  // 우리가 읽을 수 있는 문자열로 바꿔주는 번역기야.
  const textDecoder = new TextDecoderStream();
  const readableStreamClosed = port.readable.pipeTo(textDecoder.writable);
  const reader = textDecoder.readable.getReader();

  // 무한 루프를 돌면서 데이터를 계속 기다린다.
  while (true) {
    try {
      const { value, done } = await reader.read();
      if (done) {
        // reader가 닫혔을 때 루프를 빠져나온다.
        // (예: 포트가 닫혔을 때)
        reader.releaseLock();
        break;
      }
      // value에 수신된 데이터가 담겨있다.
      console.log("아두이노로부터 수신:", value);
    } catch (error) {
      console.error("데이터 읽기 오류:", error);
      break;
    }
  }
}

// 포트가 열린 후에 이 함수를 호출해주면 돼.
// await port.open({ baudRate: 9600 });
// readData(port);

여기서 중요한 개념 두 가지가 나와.

• `Uint8Array`: 아두이노에서 넘어오는 데이터의 기본 형태는 '부호 없는 8비트 정수 배열'이야. 쉽게 말해 0부터 255까지의 숫자들로 이루어진 데이터 덩어리지. 'Hello'라는 문자열도 사실은 `[72, 101, 108, 108, 111]` 같은 숫자들의 나열이야.
• `TextDecoder`: 그래서 이 숫자 덩어리(`Uint8Array`)를 우리가 알아볼 수 있는 글자(문자열)로 변환해주는 '번역기'가 필요해. 그게 바로 `TextDecoder`의 역할이야. `new TextDecoderStream()`을 사용하면 들어오는 데이터 스트림을 바로바로 텍스트 스트림으로 변환해줘서 아주 편리해.

위 코드는 `while (true)` 루프를 돌면서 `reader.read()`를 계속 호출해. 데이터가 들어올 때까지 `await`에서 멈춰 기다리다가, 데이터가 도착하면 `value`에 담아서 우리에게 주고, 다시 다음 데이터를 기다리는 식으로 동작해.

데이터 쓰기 (웹페이지 -> 아두이노)

웹페이지에서 아두이노로 명령을 보내는 건 읽기보다 훨씬 간단해. `port.writable` 스트림을 사용하면 돼.

// 아두이노로 데이터를 보내는 함수
async function writeData(port, data) {
  // TextEncoder는 우리가 보내려는 문자열을
  // 아두이노가 이해할 수 있는 숫자 데이터(Uint8Array)로 바꿔주는 번역기야.
  const textEncoder = new TextEncoder();
  const writer = port.writable.getWriter();

  await writer.write(textEncoder.encode(data));
  console.log(`아두이노로 전송: ${data}`);

  // writer 사용이 끝나면 반드시 lock을 해제해줘야 해.
  writer.releaseLock();
}

// 사용 예시: 'LED_ON' 이라는 문자열을 아두이노로 보낸다.
// writeData(port, 'LED_ON');

읽을 때와 반대지? 이번엔 `TextEncoder`라는 번역기를 사용해서 우리가 보내고 싶은 문자열(예: 'LED를 켜라!')을 아두이노가 알아들을 수 있는 숫자 덩어리(`Uint8Array`)로 변환한 뒤, `writer.write()`를 통해 슝~ 하고 보내는 거야. 아주 직관적이지?

Step 4: 뒷정리는 깔끔하게! 포트 닫기

통신이 모두 끝났다면, 우리가 사용했던 자원들을 깨끗하게 정리해주는 게 좋은 매너야. 특히 시리얼 포트는 한 번에 하나의 프로그램만 사용할 수 있기 때문에, 우리 웹페이지가 계속 붙잡고 있으면 다른 프로그램이 이 포트를 쓸 수 없게 돼. 사용자가 페이지를 벗어나거나, '연결 끊기' 버튼을 눌렀을 때 포트를 닫아주는 코드를 넣어주자.

// 포트를 닫는 함수
async function closePort(port) {
  // 위에서 만든 읽기 루프가 있다면 먼저 종료시켜야 해.
  // reader.cancel() 등을 호출해서 루프를 빠져나오게 만들자.
  // (자세한 내용은 실전 예제에서!)

  await port.close();
  console.log("포트가 닫혔습니다.");
}

// 사용자가 '연결 끊기' 버튼을 눌렀을 때 호출
// closePort(port);

`port.close()`를 호출하면, 아까 `while(true)`로 돌고 있던 읽기 루프의 `reader.read()`에서 `done`이 `true`가 되면서 루프가 자동으로 종료되고, 관련된 모든 자원들이 해제돼. 아주 잘 설계되어 있지?

자, 지금까지 Web Serial API의 핵심적인 네 단계를 모두 살펴봤어. 이제 이 지식들을 조합해서 실제로 눈에 보이는 결과물을 만들어 볼 시간이야. 다음 챕터에서는 웹 버튼으로 아두이노의 LED를 켜고 끄는, 아주 클래식하면서도 짜릿한 실전 예제를 만들어 볼 거야!

이제 진짜 재미있는 시간이야! 지금까지 배운 API 조각들을 모아서 실제로 작동하는 프로젝트를 만들어 보자. 우리의 목표는 아주 심플해. 웹페이지에 있는 버튼 두 개('ON', 'OFF')를 눌러서, 컴퓨터에 연결된 아두이노의 내장 LED를 켜고 끄는 것!

이 간단한 예제 하나만 제대로 이해하면, Web Serial API를 활용한 거의 모든 프로젝트에 응용할 수 있을 거야. 구조는 똑같고, 주고받는 데이터의 내용만 달라질 뿐이거든.

먼저 하드웨어 쪽부터 준비하자.

Part 1: 아두이노 코드 준비하기 (Arduino Sketch)

아두이노 IDE를 열고, 아래 코드를 입력한 다음 아두이노 보드에 업로드해줘. 아두이노 우노 보드에는 13번 핀에 기본 LED가 연결되어 있어서, 별도의 회로를 꾸밀 필요도 없어. 아주 편하지?

// 아두이노에 업로드할 코드 (led_control.ino)

// 대부분의 아두이노 보드에 내장된 LED는 13번 핀에 연결되어 있어.
// LED_BUILTIN 이라는 상수를 사용하면 보드 종류에 상관없이 알아서 찾아줘.
const int ledPin = LED_BUILTIN;

void setup() {
  // 시리얼 통신을 시작하고, 속도를 9600으로 설정한다.
  // 웹페이지의 baudRate와 반드시 같아야 해!
  Serial.begin(9600);

  // LED 핀을 출력 모드로 설정한다.
  pinMode(ledPin, OUTPUT);

  // 시리얼 모니터가 준비될 때까지 잠시 기다린다 (선택 사항).
  while (!Serial) {
    ; // wait for serial port to connect. Needed for native USB port only
  }
  
  Serial.println("아두이노 준비 완료! '1'을 보내면 LED가 켜지고, '0'을 보내면 꺼집니다.");
}

void loop() {
  // 시리얼 포트로 들어온 데이터가 있는지 확인한다.
  if (Serial.available() > 0) {
    // 데이터가 있다면, 한 바이트를 읽어온다.
    char receivedChar = Serial.read();

    // 읽어온 데이터가 '1'이면
    if (receivedChar == '1') {
      digitalWrite(ledPin, HIGH); // LED를 켠다.
      Serial.println("LED ON!"); // 웹페이지로 피드백을 보내준다.
    }
    // 읽어온 데이터가 '0'이면
    else if (receivedChar == '0') {
      digitalWrite(ledPin, LOW); // LED를 끈다.
      Serial.println("LED OFF!"); // 웹페이지로 피드백을 보내준다.
    }
  }
}

코드 내용은 아주 간단해.

1. `setup()` 함수에서 시리얼 통신을 9600 보드레이트로 시작하고, LED 핀을 출력용으로 설정해.
2. `loop()` 함수는 계속해서 반복 실행되면서 `Serial.available()`을 통해 웹페이지에서 보낸 데이터가 있는지 확인해.
3. 데이터가 도착하면 `Serial.read()`로 읽어서, 그 값이 '1'이면 `digitalWrite(ledPin, HIGH)`로 LED에 전원을 공급(켜기)하고, '0'이면 `digitalWrite(ledPin, LOW)`로 전원을 차단(끄기)해.
4. 그리고 `Serial.println()`을 사용해서 "LED ON!" 또는 "LED OFF!" 라는 메시지를 다시 웹페이지 쪽으로 보내줘. 우리가 보낸 명령이 잘 실행됐는지 피드백을 받는 거지.

자, 이제 아두이노는 웹페이지의 명령을 받을 준비를 마쳤어. 이제 웹페이지를 만들러 가자!

Part 2: 웹 프론트엔드 만들기 (HTML & JavaScript)

이제 사용자가 직접 누를 버튼과, 이 버튼들의 동작을 처리할 JavaScript 코드를 작성할 거야. `index.html` 파일을 하나 만들고 아래 내용을 모두 복사해서 붙여넣어 봐.

<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8">
  <title>Web Serial LED Control</title>
  <style>
    body { font-family: sans-serif; display: flex; flex-direction: column; align-items: center; padding-top: 50px; }
    button { font-size: 1.2em; padding: 10px 20px; margin: 5px; cursor: pointer; }
    #log { margin-top: 20px; width: 80%; max-width: 600px; height: 200px; border: 1px solid #ccc; overflow-y: scroll; padding: 10px; background-color: #f9f9f9; }
  </style>
</head>
<body>

  <h1>Web Serial API로 LED 제어하기</h1>

  <div>
    <button id="connectBtn">연결하기</button>
    <button id="disconnectBtn" disabled>연결 끊기</button>
  </div>

  <div style="margin-top: 20px;">
    <button id="ledOnBtn" disabled>💡 LED 켜기</button>
    <button id="ledOffBtn" disabled>⚫ LED 끄기</button>
  </div>

  <h3>아두이노 로그:</h3>
  <div id="log"></div>

  <script>
    const connectBtn = document.getElementById('connectBtn');
    const disconnectBtn = document.getElementById('disconnectBtn');
    const ledOnBtn = document.getElementById('ledOnBtn');
    const ledOffBtn = document.getElementById('ledOffBtn');
    const log = document.getElementById('log');

    let port;
    let reader;
    let writer;
    let isReading = false;

    // 로그 출력 함수
    function appendLog(message) {
      const p = document.createElement('p');
      p.textContent = `> ${message}`;
      log.appendChild(p);
      log.scrollTop = log.scrollHeight;
    }

    // 연결 버튼 클릭 이벤트
    connectBtn.addEventListener('click', async () => {
      if ('serial' in navigator) {
        try {
          port = await navigator.serial.requestPort();
          await port.open({ baudRate: 9600 });
          appendLog("아두이노에 성공적으로 연결되었습니다.");

          // UI 상태 업데이트
          connectBtn.disabled = true;
          disconnectBtn.disabled = false;
          ledOnBtn.disabled = false;
          ledOffBtn.disabled = false;

          // 데이터 읽기 시작
          isReading = true;
          readLoop();

        } catch (err) {
          appendLog(`연결 실패: ${err.message}`);
        }
      } else {
        appendLog("이 브라우저는 Web Serial API를 지원하지 않습니다.");
      }
    });

    // 연결 끊기 버튼 클릭 이벤트
    disconnectBtn.addEventListener('click', async () => {
      if (!port) return;
      
      isReading = false;
      if (reader) {
        await reader.cancel(); // 읽기 루프 중단
      }
      if (writer) {
        // writer는 releaseLock()으로 충분
      }
      
      await port.close();
      
      appendLog("연결이 끊어졌습니다.");
      
      // UI 상태 초기화
      connectBtn.disabled = false;
      disconnectBtn.disabled = true;
      ledOnBtn.disabled = true;
      ledOffBtn.disabled = true;
    });

    // 데이터 쓰기 함수
    async function sendCommand(command) {
      if (!port || !port.writable) {
        appendLog("포트가 열려있지 않습니다.");
        return;
      }
      writer = port.writable.getWriter();
      const encoder = new TextEncoder();
      await writer.write(encoder.encode(command));
      writer.releaseLock();
      appendLog(`명령 전송: ${command}`);
    }

    // LED 켜기/끄기 버튼 이벤트
    ledOnBtn.addEventListener('click', () => sendCommand('1'));
    ledOffBtn.addEventListener('click', () => sendCommand('0'));

    // 데이터 읽기 루프
    async function readLoop() {
      while (port.readable && isReading) {
        const textDecoder = new TextDecoderStream();
        const readableStreamClosed = port.readable.pipeTo(textDecoder.writable);
        reader = textDecoder.readable.getReader();

        try {
          while (true) {
            const { value, done } = await reader.read();
            if (done) {
              break;
            }
            appendLog(`수신: ${value.trim()}`);
          }
        } catch (error) {
          appendLog(`읽기 오류: ${error.message}`);
        } finally {
          reader.releaseLock();
        }
      }
    }
  </script>
</body>
</html>

코드가 좀 길어졌지만, 우리가 앞에서 배운 내용들이 모두 들어있어. 차근차근 살펴보자.

1. HTML 구조: '연결/끊기', 'LED 켜기/끄기' 버튼들과 아두이노의 메시지를 보여줄 로그창(`div#log`)으로 이루어져 있어. 처음에는 제어 버튼들이 비활성화(`disabled`) 되어 있다가, 연결에 성공하면 활성화될 거야.
2. `connectBtn` 이벤트: '연결하기' 버튼을 누르면 `navigator.serial.requestPort()`로 포트를 요청하고, `port.open()`으로 연결을 시도해. 성공하면 UI 버튼 상태를 업데이트하고, `readLoop()` 함수를 호출해서 아두이노로부터 오는 메시지를 들을 준비를 시작해.
3. `disconnectBtn` 이벤트: '연결 끊기'를 누르면, 진행 중이던 읽기 루프를 `reader.cancel()`로 중단시키고, `port.close()`로 포트를 닫아. 그리고 UI를 다시 초기 상태로 되돌리지.
4. `sendCommand(command)` 함수: '1'이나 '0' 같은 명령어를 받아서 `TextEncoder`로 변환한 뒤, `writer.write()`를 통해 아두이노로 전송하는 역할을 해.
5. `ledOnBtn`, `ledOffBtn` 이벤트: 각 버튼을 누르면 `sendCommand` 함수를 호출해서 약속된 신호('1' 또는 '0')를 보내.
6. `readLoop()` 함수: 이 부분이 중요해. 연결이 유지되는 동안 계속해서 `port.readable`을 통해 데이터를 읽어. 아두이노에서 `Serial.println()`으로 보낸 메시지가 `value`에 담겨 들어오고, 이걸 `appendLog` 함수를 통해 화면의 로그창에 뿌려주는 거야. `trim()`을 써서 불필요한 공백이나 줄바꿈 문자를 제거해줬어.

이제 이 `index.html` 파일을 브라우저(크롬, 엣지 등)에서 열어봐. (보안 정책 때문에 로컬 파일을 바로 열면 동작하지 않을 수 있어. VS Code의 'Live Server' 같은 확장 프로그램을 사용해서 간단한 웹 서버 환경에서 여는 걸 추천해!)

자, 이제 떨리는 마음으로 '연결하기' 버튼을 눌러보자. 아두이노를 선택하고 '연결'을 누르면... 로그창에 "아두이노에 성공적으로 연결되었습니다." 라는 메시지가 뜰 거야. 이제 '💡 LED 켜기' 버튼을 눌러봐! 아두이노 보드의 주황색 LED에 불이 번쩍 들어오는 게 보일 거야! 로그창에는 "명령 전송: 1"과 "수신: LED ON!" 이라는 메시지가 차례로 찍히겠지. '⚫ LED 끄기' 버튼을 누르면 반대로 LED가 꺼지고 관련 로그가 찍힐 거고.

어때? 네가 만든 웹페이지가 현실 세계의 불빛을 제어하는 이 순간, 정말 짜릿하지 않아? 이게 바로 Web Serial API의 힘이야!

자, 이제 너는 웹으로 LED를 켜고 끄는 마법사가 됐어. 하지만 실제 프로젝트는 언제나 예제처럼 순탄하지만은 않지. 예상치 못한 문제에 부딪히고, 더 안정적이고 사용자 친화적인 프로그램을 만들어야 할 거야. 이 챕터에서는 실전에서 마주칠 법한 문제들과, 너를 한 단계 더 높은 레벨로 이끌어 줄 고급 팁들을 알려줄게.

1. 데이터가 잘려서 와요! (데이터 프레이밍)

이건 시리얼 통신을 해본 사람이라면 누구나 한 번쯤 겪는 문제야. 아두이노에서 `Serial.println("Hello World")` 라고 보냈는데, 웹에서는 "Hello Wo" 와 "rld" 처럼 데이터가 두 번에 나뉘어 들어오는 경우가 비일비재해. 왜냐하면 시리얼 통신은 데이터를 스트림, 즉 물 흐르듯이 보내기 때문에 네트워크 상황이나 버퍼 크기에 따라 데이터가 임의의 청크(조각)로 잘려서 도착할 수 있거든.

우리가 만든 LED 예제에서는 '1'이나 '0'처럼 한 글자만 보내거나, `println`으로 보낸 짧은 메시지를 `trim()`으로 처리해서 문제가 없어 보였지만, JSON 데이터처럼 길고 구조적인 데이터를 주고받기 시작하면 이건 아주 치명적인 문제가 돼.

해결책: 구분자(Delimiter)를 사용한 패킷 재조립

가장 일반적인 해결책은, 보내는 쪽과 받는 쪽이 서로 약속된 '구분자'를 사용하는 거야. "메시지 하나가 끝났음!"을 알리는 특별한 문자를 데이터 끝에 붙여 보내는 거지. 가장 흔하게 쓰이는 구분자는 **줄바꿈 문자(`\n`)**야.

아두이노에서 `Serial.println()`을 사용하면 데이터 끝에 자동으로 줄바꿈 문자(\r\n)가 붙어서 보내지므로, 우리는 웹에서 데이터를 읽을 때 줄바꿈 문자가 나올 때까지 데이터를 계속 모으다가, 줄바꿈 문자를 만나면 "아, 메시지 하나가 다 왔구나!" 하고 판단해서 처리하면 돼.

이걸 구현하기 위해 `readLoop` 함수를 좀 더 똑똑하게 만들어 보자. `TransformStream`을 사용하면 이 작업을 아주 우아하게 처리할 수 있어.

// LineBreakTransformer.js - 줄바꿈 기준으로 데이터를 잘라주는 똑똑한 변환기
class LineBreakTransformer {
  constructor() {
    // 아직 완성되지 않은 데이터 조각을 저장할 컨테이너
    this.container = '';
  }

  transform(chunk, controller) {
    // 새로 들어온 데이터(chunk)를 기존 컨테이너에 추가
    this.container += chunk;
    // 줄바꿈 문자를 기준으로 컨테이너를 나눈다.
    const lines = this.container.split('\n');
    // 마지막 조각은 아직 완성되지 않았을 수 있으므로 다시 컨테이너에 저장
    this.container = lines.pop();
    // 완성된 라인들을 다음 스트림으로 보낸다.
    lines.forEach(line => controller.enqueue(line));
  }

  flush(controller) {
    // 스트림이 닫힐 때, 컨테이너에 남아있는 데이터가 있다면 마저 보낸다.
    controller.enqueue(this.container);
  }
}

// readLoop 함수를 이렇게 개선할 수 있다.
async function readLoop() {
  while (port.readable && isReading) {
    const textDecoder = new TextDecoderStream();
    // 이 부분이 핵심! textDecoder와 reader 사이에 우리만의 변환기를 끼워넣는다.
    const readableStream = textDecoder.readable.pipeThrough(new TransformStream(new LineBreakTransformer()));
    reader = readableStream.getReader();

    try {
      while (true) {
        const { value, done } = await reader.read();
        if (done) {
          break;
        }
        // 이제 value에는 항상 온전한 한 줄의 메시지가 들어온다!
        appendLog(`수신: ${value}`);
      }
    } catch (error) {
      appendLog(`읽기 오류: ${error.message}`);
    } finally {
      reader.releaseLock();
    }
  }
}

이렇게 `LineBreakTransformer`를 만들어두면, 데이터가 아무리 잘게 쪼개져서 들어와도 항상 완벽한 한 줄 단위로 데이터를 처리할 수 있게 돼. JSON 데이터를 주고받을 때도 아주 안정적으로 파싱할 수 있지. 이건 정말 필수적인 실전 테크닉이니 꼭 기억해둬!

2. 어? 기기가 뽑혔어요! (연결 끊김 감지)

사용자가 실수로 USB 케이블을 뽑거나, 기기 전원이 꺼지면 어떻게 될까? 우리 코드는 아무것도 모른 채 계속 데이터를 읽거나 쓰려고 하다가 에러를 뿜어낼 거야. 사용자 경험이 아주 나빠지겠지.

Web Serial API는 이런 상황에 대비할 수 있는 두 가지 방법을 제공해.

방법 1: `port.readable` 이나 `port.writable` 이 `null` 이 되는 것 확인

기기가 물리적으로 연결 해제되면, `port` 객체 자체는 남아있지만, 데이터를 읽고 쓸 수 있는 스트림인 `port.readable`과 `port.writable`이 `null`이 돼. 그래서 우리의 `readLoop`는 자연스럽게 `while (port.readable && isReading)` 조건문에서 `false`가 되어 루프를 탈출하게 돼. 이건 이미 우리 코드에 반영되어 있는 방어 로직이야.

방법 2: `navigator.serial`의 'disconnect' 이벤트 리스닝

더 적극적인 방법은, 아예 브라우저 전체에서 시리얼 기기의 연결 해제 이벤트를 감지하는 거야.

navigator.serial.addEventListener('disconnect', (event) => {
  // event.target에 연결이 끊긴 port 객체가 담겨 온다.
  // 만약 현재 우리가 연결해서 사용 중인 포트라면,
  if (port && event.target === port) {
    appendLog("앗! 기기 연결이 끊어졌습니다. 재연결해주세요.");
    // 연결 끊기 버튼을 눌렀을 때와 동일한 정리 로직을 수행
    // (예: disconnectBtn.click() 강제 호출)
  }
});

이 코드를 추가해두면, 사용자가 케이블을 뽑는 순간 즉시 "앗! 기기 연결이 끊어졌습니다." 같은 친절한 메시지를 보여주고, UI 상태를 안전하게 초기화할 수 있어. 훨씬 프로페셔널해 보이지?

3. 매번 포트 선택하기 귀찮아요! (이전 포트에 자동 재연결)

사용자가 우리 웹페이지를 껐다가 다시 켰을 때, 또다시 '연결하기' 버튼을 누르고 팝업창에서 기기를 선택하는 과정을 반복해야 한다면 좀 귀찮을 거야. Web Serial API는 이 문제를 해결하기 위해 `navigator.serial.getPorts()` 라는 아주 유용한 함수를 제공해.

이 함수는 이전에 이 사이트에서 사용자가 **최소 한 번 이상 허용했던** 포트들의 목록을 반환해줘. 이걸 이용하면 페이지가 로드될 때 이전에 연결했던 포트가 여전히 컴퓨터에 연결되어 있는지 확인하고, 그렇다면 사용자에게 "이전 기기에 다시 연결할까요?" 라고 물어보거나, 아예 자동으로 연결해 줄 수 있어.

// 페이지가 로드될 때 자동으로 이전에 허용된 포트를 확인하는 함수
async function checkForPreviouslyApprovedPorts() {
  const previouslyApprovedPorts = await navigator.serial.getPorts();
  if (previouslyApprovedPorts.length > 0) {
    // 이전에 허용된 포트가 있다면, 첫 번째 포트에 자동으로 연결 시도
    const firstPort = previouslyApprovedPorts[0];
    // 여기서 사용자에게 "다시 연결할까요?" 라고 물어보는 UI를 보여주면 더 좋음
    // 여기서는 바로 연결을 시도
    port = firstPort;
    await port.open({ baudRate: 9600 });
    appendLog("이전에 연결했던 아두이노에 자동으로 다시 연결되었습니다.");
    // ... UI 업데이트 및 읽기 루프 시작 로직 ...
  }
}

// 스크립트 시작 부분에서 이 함수를 호출
// checkForPreviouslyApprovedPorts();

이 기능을 추가하면 사용자는 한 번만 기기를 선택하면, 그 다음부터는 웹사이트에 접속하는 것만으로 바로 하드웨어를 제어할 수 있게 돼. 사용자 경험이 수직 상승하는 마법이지!

4. 에러 핸들링은 꼼꼼하게!

우리 예제 코드에도 `try...catch`가 포함되어 있지만, 실제 애플리케이션에서는 에러 처리를 훨씬 더 세심하게 해야 해. 예를 들어, `port.open()`이 실패하는 경우는 사용자가 포트 선택을 취소한 경우 외에도, 다른 프로그램이 이미 해당 포트를 사용 중일 때도 발생할 수 있어. `writer.write()`는 기기 연결이 갑자기 끊겼을 때 `NetworkError`를 발생시킬 수 있지.

모든 비동기 API 호출(`requestPort`, `open`, `close`, `read`, `write`)은 `try...catch`로 감싸고, 발생할 수 있는 에러의 종류에 따라 사용자에게 적절한 피드백을 주는 습관을 들이는 것이 중요해. "알 수 없는 오류가 발생했습니다." 보다는 "다른 프로그램이 이 기기를 사용 중인 것 같습니다." 라는 메시지가 훨씬 유용하겠지?

이런 꿀팁들을 잘 활용하면, 너의 Web Serial API 프로젝트는 단순한 '신기한 장난감'을 넘어, 안정적이고 사용하기 편리한 '웰메이드 애플리케이션'으로 거듭날 수 있을 거야. 이런 디테일이 바로 전문가와 아마추어를 가르는 차이니까!

우리는 지금까지 Web Serial API의 기본부터 실전 예제, 그리고 전문가를 위한 팁까지 알아봤어. 이제 너는 웹으로 현실을 제어하는 새로운 힘을 손에 넣었지. 그렇다면 이 힘으로 무엇을 할 수 있을까? 이 기술의 미래는 어디를 향하고 있을까? 마지막으로 우리의 상상력을 한껏 펼쳐보자.

Web Serial API는 혼자가 아니야. '프로젝트 푸구'라는 이름 아래, 웹을 네이티브 앱처럼 강력하게 만들어 줄 다른 형제 API들이 함께 발전하고 있어. 이들과의 시너지는 상상 이상의 결과물을 만들어낼 거야.

이 기술들이 서로 결합되면 어떤 일이 벌어질까?

• 궁극의 홈 오토메이션 대시보드: Web Serial API로 조명과 커튼을 제어하고, Web Bluetooth로 실내 온도/습도 센서와 스마트 워치의 데이터를 읽어오고, WebUSB로 IP 카메라 영상을 스트리밍하는 모든 기능이 통합된, 클라우드 서버 없이 오직 내 집 안에서만 동작하는 완벽한 개인용 스마트홈 허브를 웹페이지 하나로 만들 수 있어.
• 차세대 인터랙티브 게임: WebHID로 연결된 커스텀 컨트롤러의 조작에 따라 게임 캐릭터가 움직이고, 게임 속 이벤트(피격, 아이템 획득 등)가 발생하면 Web Serial API를 통해 컨트롤러에 연결된 모터가 진동하거나 LED가 번쩍이는, 현실과 가상이 완벽하게 연동되는 게임을 만들 수 있어.
• 스마트 헬스케어 플랫폼: Web Bluetooth로 심박수 센서나 혈당 측정기의 데이터를 실시간으로 수집하고, WebRTC를 통해 의사와 원격으로 상담하면서, Web Serial API로 연결된 물리치료 기기를 의사가 원격으로 제어해주는 재택 의료 서비스도 상상해 볼 수 있지.
• 나만의 음악 스튜디오: Web Serial API나 WebUSB로 미디(MIDI) 컨트롤러, 신디사이저, 이펙터 같은 실제 음악 장비들을 연결하고, Web Audio API를 사용해 웹 기반의 DAW(디지털 오디오 워크스테이션)를 만드는 거야. 하드웨어와 소프트웨어가 완벽하게 통합된, 설치가 필요 없는 나만의 음악 작업 환경이 탄생하는 거지.

이 모든 아이디어들이 더 이상 먼 미래의 이야기가 아니야. 이미 많은 개발자와 메이커들이 이 기술들을 활용해 놀라운 프로젝트들을 만들어내고 있어. 중요한 것은 기술 그 자체가 아니라, 이 기술로 무엇을 해결하고, 어떤 새로운 경험을 만들어낼 것인가에 대한 너의 아이디어와 상상력이야.

혹시 멋진 아이디어는 있는데 직접 구현할 기술이나 시간이 부족할 수도 있어. 그럴 땐 좌절하지 마. **재능넷**과 같은 재능 공유 플랫폼에는 너의 상상력을 현실로 만들어 줄 수 있는 실력 있는 웹 개발자, 하드웨어 전문가들이 많이 있어. 아이디어를 공유하고 협업하며 함께 멋진 결과물을 만들어보는 것도 좋은 방법이야.

이제 웹은 더 이상 스크린 안에 갇혀 있지 않아. Web Serial API는 그 문을 여는 첫 번째 열쇠일 뿐이야. 이 열쇠를 손에 쥔 너는 이제 웹 개발자를 넘어, 디지털과 현실을 잇는 아키텍트가 될 수 있어.

지금 바로 책상 서랍 속에 잠자고 있는 아두이노를 꺼내봐. 그리고 브라우저를 열어. 너의 코드가 현실 세계에 어떤 놀라운 변화를 가져올지, 직접 확인해 볼 시간이야. 세상은 너의 다음 프로젝트를 기다리고 있어!