cpaczek/skylight 딥다이브
— 머리 위를 지나는 비행기를 천장에 실시간으로 쏘는 장치

1프로젝트 한줄 요약

비행기는 자기 위치·고도·속도·편명을 1초에 한 번꼴로 무선으로 떠들고 다닙니다. 이걸 ADS-B라고 부르는데, 누구나 받을 수 있는 공개 신호입니다. Skylight는 그 신호를 2만~3만 원짜리 USB 라디오(RTL-SDR)로 받아 해독한 뒤, 머리 위를 지나는 비행기를 천장을 향해 쏜 프로젝터 화면에 그립니다. 실제로 소리가 들리는 그 제트기가, 같은 순간 천장을 가로질러 미끄러지는 거죠.

배경은 완전한 검정입니다. 프로젝터의 사각형 테두리가 어둠 속으로 사라지고, 비행기와 별만 빛나도록 설계했습니다. 그리고 비행기 뒤에는 그 시각·그 위치의 진짜 하늘이 그려집니다 — 해, 위상까지 표현된 달, 밝은 별과 별자리 선, 그리고 TLE(궤도 데이터)로 계산한 인공위성과 ISS. 모든 설정은 누워서 휴대폰으로 조절합니다.

2왜 주목받는가

비행기 추적 프로젝트나 ADS-B 디코더는 예전부터 많았습니다. Skylight가 트렌딩에 오른 건 "기능"이 아니라 "경험과 완성도" 때문입니다. 천장에 별과 함께 비행기가 흐르는 데모 영상 한 편이 SNS에서 강한 인상을 남겼고, README가 "라디오 없이도 지금 당장 켜 볼 수 있게" 설계돼 진입장벽을 거의 0으로 낮췄습니다.

3기술 스택 전체 지도

Skylight의 가장 깔끔한 점은 처음부터 끝까지 TypeScript 하나로 묶여 있다는 것입니다. 라디오 신호를 받는 서버도, 천장에 그림을 그리는 화면도, 둘이 공유하는 수학 공식도 전부 같은 언어죠. 그리고 이걸 pnpm 워크스페이스라는 한 저장소 안 4개 패키지(shared·server·web·tracker)로 나눠 둡니다.

① 백엔드 — server/ (Node · Express · ws)

비행기 데이터를 모으고, 다듬고, 뿌리는 심장부입니다. 핵심 부품을 뜯어보면:

② 프론트엔드 — web/ (Vite · React · Canvas)

5개의 진입점이 한 빌드 안에 들어 있습니다. 천장에 비치는 화면, 손에 든 리모컨, 카메라 포인팅 파이프라인 디버그 UI(tracker.html), 실시간 피드+레이더 대시보드(tv.html), 그리고 스트림 뷰어(stream.html)입니다.

③ 공유 코어 — shared/ (순수 TypeScript)

서버와 화면이 똑같이 쓰는, DOM도 상태도 없는 순수 코드입니다. 타입 정의(aircraft.ts·messages.ts), 설정 스키마(config.ts), 그리고 좌표 변환 수학(geo.ts)이 들어 있죠. 서버와 클라이언트가 같은 공식을 쓰니 "위치 계산이 두 곳에서 어긋나는" 버그가 원천 차단됩니다.

④ 선택 사항: 하늘 카메라 서브시스템 — tracker/ (PTZ 카메라 자동 조준)

tracker는 4번째 패키지로, ADS-B 위치 데이터를 이용해 PTZ 카메라를 비행기 방향으로 자동 조준해 촬영하는 선택 사항 서브시스템입니다. 핵심 구성을 보면:

카메라 디버그 UI는 web/tracker.html에서, 실시간 피드+레이더 대시보드는 web/tv.html에서 확인할 수 있습니다. 라즈베리파이에는 pi-setup/skylight-tracker.service로 별도 systemd 서비스로 등록됩니다.

⑤ 인프라/배포 — pi-setup/ + scripts/ + Docker

라즈베리파이 OS 위 셸 스크립트 배포 외에 Docker(compose.yaml)도 공식 지원됩니다 — docker compose up -d --build 한 줄로 라디오 없이 서버+디스플레이를 컨테이너로 구동할 수 있습니다. 파이 셸 세트는 SD카드 헤드리스 프로비저닝(provision-sd.sh), 드라이버+디코더+앱 설치(install-on-pi.sh), 크롬 키오스크 자동시작(setup-kiosk.sh), systemd 서비스 등록(skylight-server.service), 그리고 개발 PC에서 파이로 코드를 밀어 넣는 deploy-to-pi.sh(rsync 기반)까지 한 세트입니다.

4아키텍처 심화 분석

전체 데이터 흐름은 왼쪽(하늘)에서 오른쪽(천장)으로 한 방향으로 흐릅니다. 단, 휴대폰의 설정 변경만 거꾸로 거슬러 올라가죠.

핵심 설계 패턴 1 — 단일 진실원(Config) + 양방향 동기화

모든 설정은 shared/src/config.ts의 Config 객체 한 곳에만 존재합니다. 서버는 이걸 config.json에 저장하고, 누가(휴대폰이든 REST든) 바꾸면 ConfigStore가 구독자에게 알리고, Hub가 연결된 모든 화면에 새 설정을 방송합니다. 그래서 휴대폰에서 회전 슬라이더를 움직이면, 천장 화면이 즉시 같이 돕니다. 재부팅해도 파일에 남아 유지되죠.

// hub.ts — 새 화면이 접속하면 현재 상태로 '초기 동기화'
private onConnect(ws) {
  this.send(ws, { type: "config", config: store.get() });   // 지금 설정
  this.send(ws, { type: "aircraft", ...snapshot });          // 지금 비행기
  this.send(ws, { type: "status", status: getStatus() });    // 소스 상태
}
// 휴대폰이 patchConfig를 보내면 → store.patch → 구독자 → 전체 재방송

핵심 설계 패턴 2 — 두 소스 합치기(radio + API merge)

내 라디오는 머리 위 비행기를 잘 잡지만, 멀어지거나 착륙하면 신호를 놓칩니다. 그래서 라디오 모드에서도 공개 API를 보조로 같이 폴링해, hex(기체 고유 ID) 기준으로 합칩니다. 단 신선도(seen)를 비교하되 라디오에 2초 가산점을 줘서, 내가 직접 받은 신호가 우선하고 라디오가 놓친 순간에만 API가 빈자리를 메웁니다.

// datasource.ts — 라디오에 -2초 편향을 줘서 우선권 부여
const rSeen = (r.seen ?? 0) - 2;   // 로컬 라디오가 더 '신선'하게 보이도록
const aSeen = existing.seen ?? 999;
byHex.set(r.hex, rSeen <= aSeen ? r : existing);

핵심 설계 패턴 3 — '스티키 보강'으로 라벨 깜빡임 제거

항로 정보(목적지 등)는 비동기로 천천히 채워집니다. 그런데 다음 스냅샷에서 그 값이 잠깐 비면 라벨이 "목적지 → — → 목적지"로 깜빡이겠죠. Skylight는 hex별로 한 번 알아낸 값은 절대 빈값으로 되돌리지 않는 스티키(sticky) 맵을 둬서 이 깜빡임을 없앱니다. 그리고 10분 넘게 안 보인 기체는 맵에서 지워 메모리를 관리합니다.

핵심 설계 패턴 4 — 1Hz 데이터를 60fps로 만드는 '시간 트릭'

비행기 신호는 1초에 한 번 옵니다. 그대로 그리면 1초마다 뚝뚝 순간이동하겠죠. Skylight는 두 가지 기법으로 부드럽게 만듭니다. 첫째, 일부러 약간 과거를 그립니다 — 항상 직전 두 위치 사이를 보간(tween)할 수 있도록. 둘째, 그 사이 구간은 geo.ts의 deadReckon으로 진로·속도를 따라 위치를 추측 전진시켜 60fps로 채웁니다.

// geo.ts — 진로(track)와 속도(gs)로 dt초 뒤 위치를 추측 (추측항법)
export function deadReckon(m, trackDeg, gsKt, dtSec) {
  if (gsKt == null || gsKt <= 0) return m;
  const dist = gsKt * KT_TO_MS * dtSec;        // 노트→m/s 변환 후 거리
  const t = trackDeg * DEG;
  return { east: m.east + dist*Math.sin(t),
           north: m.north + dist*Math.cos(t) }; // 진행 방향으로 전진
}

핵심 설계 패턴 5 — '평평한 지구' 투영 + 올려다보기 보정

몇 km 반경 안에서는 지구를 평평하다고 봐도 오차가 거의 없습니다. 그래서 위경도를 단순한 곱셈으로 "동/북 미터"로 바꾸고(llToMeters), 회전·미러를 적용해 화면 픽셀로 투영합니다(project). 중요한 반전 포인트: 프로젝터는 위로 쏘고 사람도 위를 보기 때문에 좌우가 뒤집힙니다. 그래서 기본값이 mirrorX: true이고, 정확한 회전·미러 값은 공식이 아니라 실제 머리 위 비행기를 보며 손으로 맞추는 '보정(calibration)'입니다.

5디렉토리 구조 해부

Skylight는 거대한 프로젝트가 아닙니다. 핵심 소스는 손에 꼽을 정도라, 아키텍처를 처음부터 끝까지 읽어 보기에 이상적인 교본입니다. 폴더별 역할을 지도로 그리면 이렇습니다.

6학습 포인트 (기술별)

① WebSocket 실시간 양방향 통신

서버는 ws로 1초마다 비행기를 밀어내고(push), 클라이언트는 끊기면 자동 재접속합니다. 새로 접속한 화면에 현재 상태를 먼저 한 번 보내 주는 '초기 동기화' 패턴, 그리고 한 클라이언트의 변경을 모두에게 다시 뿌리는 '브로드캐스트' 패턴을 깔끔하게 볼 수 있습니다.

② 폴링·정규화·소스 병합(데이터 파이프라인)

Poller는 서로 다른 두 소스(라디오/API)를 같은 readsb 스키마로 정규화하고, hex 기준으로 병합하며, 한 번 알아낸 값을 유지하는 스티키 캐시까지 갖췄습니다. "여러 불완전한 출처를 하나의 매끄러운 스트림으로 합치는" 실전 데이터 엔지니어링 패턴이죠.

③ 실시간 렌더링과 보간(애니메이션)

1Hz 데이터를 60fps로 만드는 "과거를 그려서 미래를 보간하는" 트릭과 deadReckon 추측항법은 게임·지도·트레이딩 차트 등 모든 실시간 시각화에 쓰이는 핵심 기법입니다. <canvas>에 직접 그려 React 리렌더 비용을 피하는 결정도 배울 점입니다.

④ 천문 계산(astronomy-engine · satellite.js · TLE)

위경도와 시각만으로 해·달·별·위성의 하늘 위치를 계산합니다. TLE(위성 궤도 데이터)를 받아 satellite.js로 ISS 위치를 푸는 부분은, 평소 접하기 어려운 우주·항법 도메인을 코드로 만져 보는 드문 기회입니다.

⑤ 설정을 '단일 진실원'으로 다루기

모든 설정이 Config 한 객체에 모이고, 파일에 저장되고, 변경이 구독으로 전파되는 구조는 규모가 큰 앱에서도 그대로 통하는 설계입니다. mergeConfig의 깊은 병합으로 부분 업데이트가 중첩 키를 날리지 않게 막는 디테일도 좋은 교본입니다.

⑥ 하드웨어 + 셀프호스팅 어플라이언스화

셸 스크립트만으로 라즈베리파이를 "켜면 켜지는 기기"로 만드는 과정(헤드리스 프로비저닝·systemd·키오스크)은 홈랩/셀프호스팅의 정석입니다. RTL-SDR·dump1090 조합은 그 자체로 무선·항공 취미의 입문 코스이기도 합니다.

7하드웨어/시스템 요구사항

중요한 점은 두 단계로 나뉜다는 것입니다. 코드만 돌려 보는 체험에는 하드웨어가 전혀 필요 없습니다.

0단계 — 체험(하드웨어 0개)

Node 20+ 와 pnpm만 있으면 됩니다. DATA_SOURCE=api pnpm dev 한 줄로 무료 공개 API에서 실제 비행기를 받아 브라우저에서 바로 봅니다.

완성 단계 — 천장 어플라이언스 부품표

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

• 저장소: github.com/cpaczek/skylight · 제품 키트 대기명단: skylightceiling.com
• 핵심 외부 도구: dump1090-fa · RTL-SDR Blog 드라이버 · rtl-sdr.com (입문)
• 데이터 소스: adsbdb (항로/기종) · airplanes.live (공개 API) · Celestrak (위성 TLE) · OurAirports (공항 좌표)
• 라이브러리: astronomy-engine · satellite.js · ws · Vite
• 배경 지식: WebSocket API (MDN) · Canvas API (MDN)