튜토리얼

실제로 동작하는 결과를 만드는 실습 중심 가이드

이 섹션에서는 OrbiSync를 활용해 단계별로 작동하는 결과를 만들어 봅니다. 초보자도 따라 할 수 있도록 번호 단계로 안내하며, 실제 제품 UI(대시보드·Pairing Code·다운로드) 기준으로 작성했습니다.

1. Getting Started with PC Node

PC Node를 처음 연결해서 대시보드에서 ONLINE을 확인하는 가장 기본 튜토리얼입니다.

1.1 대시보드에서 Node 다운로드

OrbiSync에 로그인한 뒤 대시보드로 이동합니다.
「Node 설치하기」 또는 Node 프로그램 다운로드 버튼을 클릭합니다.
사용 중인 OS(Windows / macOS / Linux)에 맞는 설치 파일을 다운로드합니다.

1.2 Pairing Code 입력

대시보드에서 「Node 추가하기」를 눌러 Pairing Code를 발급·확인합니다.
다운로드한 Node 프로그램을 실행합니다.
실행 후 나오는 입력창에 위에서 확인한 Pairing Code를 붙여넣기 후 등록합니다.

왜 필요한가: Pairing Code는 “이 PC를 내 OrbiSync 계정에 연결하는 일회용 키”입니다. 입력하면 서버 주소나 토큰을 따로 설정할 필요 없이 자동으로 등록됩니다.

1.3 ONLINE 확인

메뉴에서 내 장치 또는 데이터 조회로 이동합니다.
장치 상태 탭에서 방금 연결한 Node가 ONLINE으로 표시되는지 확인합니다.
마지막 연결 시간이 방금 시간으로 갱신되었는지 확인합니다.

1.4 터널 도메인 이해

Node가 ONLINE이면 대시보드 또는 내 장치 화면에 터널 도메인(예: https://xxxx.orbisync.io)이 표시될 수 있습니다. 이 주소는 “외부에서 이 PC에 접속할 때 쓰는 URL”입니다. 단, PC에서 실제로 서비스(예: 웹서버)를 실행 중일 때만 접속이 가능합니다. 웹서버를 켜지 않으면 터널은 연결되어 있어도 해당 URL로 접속 시 응답이 없을 수 있습니다.

1.5 (선택) 로컬 웹서버 실행 후 터널 접속 확인

PC에서 간단한 웹서버를 실행한 뒤, 터널 도메인으로 접속해 봅니다. 자세한 내용은 아래 2. Exposing a Local Web Server via Tunnel을 참고하세요.

2. Exposing a Local Web Server via Tunnel (PC Node)

PC에서 실행 중인 웹서버를 터널 도메인으로 외부에서 접속하는 방법입니다. 공유기 포트포워딩 없이 OrbiSync 터널만으로 접속할 수 있습니다.

2.1 PC에서 간단한 웹서버 실행

먼저 PC에서 로컬 웹서버를 실행합니다. 아래 중 하나만 선택하면 됩니다.

Python으로 간단한 HTTP 서버 (가장 간단)

# 터미널에서 실행 (Python 3)
python -m http.server 8080

실행 후 브라우저에서 http://127.0.0.1:8080으로 접속해 동작을 확인합니다.

Node.js Express (선택)

Node.js가 설치되어 있다면 Express로 간단한 서버를 띄울 수 있습니다.

// app.js 예시
const express = require('express');
const app = express();
app.get('/', (req, res) => res.send('Hello from OrbiSync Tunnel'));
app.listen(8080, '127.0.0.1');

2.2 터널 도메인으로 접속 확인

PC Node가 ONLINE인지 확인합니다.
대시보드 또는 내 장치에서 해당 Node의 터널 도메인(예: https://xxxx.orbisync.io)을 확인합니다.
다른 기기(휴대폰·다른 PC) 또는 시크릿 창에서 위 터널 도메인 주소로 접속합니다.
로컬에서 보던 웹페이지가 보이면 터널을 통한 접속이 성공한 것입니다.

주의: 터널 접속이 되려면 PC에서 웹서버가 실행 중이어야 합니다. Node만 켜고 웹서버를 끄면 터널은 연결되어 있어도 해당 URL로 접속 시 응답이 없거나 오류가 납니다.

3. ESP32 Basic Tutorial (LED 제어 예제)

ESP32 보드에서 OrbiSync 라이브러리를 사용해 LED를 켜고 끄는 예제입니다. 터널 또는 대시보드에서 HTTP 요청을 보내 LED를 제어할 수 있습니다.

3.1 Arduino IDE 및 OrbiSync 라이브러리 설치

Arduino IDE를 설치합니다.
스케치 → 라이브러리 포함하기 → 라이브러리 관리에서 OrbiSync를 검색해 설치합니다.

3.2 WiFi 및 Pairing Code 설정

예제 스케치에서 사용 중인 WiFi SSID, 비밀번호, 대시보드에서 발급한 Pairing Code를 입력합니다.

const char* WIFI_SSID     = "your_wifi_ssid";
const char* WIFI_PASSWORD = "your_wifi_password";
const char* PAIRING_CODE  = "your_pairing_code";  // 대시보드에서 확인

3.3 LED ON/OFF HTTP 요청 처리 예제

OrbiSync 예제 중 “LED 제어” 또는 “Basic HTTP” 예제를 엽니다. 스케치에서는 보통 다음을 수행합니다:

WiFi 연결 후 OrbiSync Hub에 자동 등록
특정 경로(예: /led?state=on, /led?state=off)로 들어오는 HTTP 요청을 받아 GPIO로 LED 제어

실제 함수명·경로는 라이브러리 예제 코드를 따릅니다. 예시만 아래에 둡니다.

// 예시: GET /led?state=on 또는 /led?state=off 처리
void handleLedRequest(String state) {
  if (state == "on")  digitalWrite(LED_PIN, HIGH);
  if (state == "off") digitalWrite(LED_PIN, LOW);
}

3.4 업로드 후 대시보드/터널에서 요청 보내기

스케치를 ESP32에 업로드한 뒤 시리얼 모니터에서 WiFi·등록 완료 로그를 확인합니다.
대시보드 내 장치 또는 데이터 조회에서 해당 ESP32 Node가 ONLINE인지 확인합니다.
해당 Node의 터널 도메인을 확인한 뒤, 브라우저나 curl로 요청을 보냅니다.
- 예: https://your-node.orbisync.io/led?state=on → LED 켜기
- 예: https://your-node.orbisync.io/led?state=off → LED 끄기

LED가 켜지고 꺼지면 튜토리얼이 정상적으로 동작한 것입니다.

4. Event / Sensor Log Tutorial

Node(PC 또는 ESP32)에서 이벤트·센서 데이터를 보내고, 대시보드와 사용자 페이지에서 로그를 확인하는 방법입니다.

4.1 이벤트 전송 (ESP32 또는 PC Node)

OrbiSync 라이브러리(ESP32) 또는 PC Node SDK/API에서는 “이벤트 전송” 함수를 제공합니다. 예: 온도 값 전송, 버튼 클릭 이벤트, 하트비트 등. 사용 중인 라이브러리 문서에서 이벤트 전송 또는 로그 전송 예제를 참고해 호출하면 됩니다.

4.2 대시보드에서 이벤트 로그 확인

대시보드에서 해당 Node를 선택하거나, 데이터 조회 메뉴로 이동합니다.
이벤트 / 센서 로그 탭을 엽니다.
방금 전송한 이벤트가 시간순으로 표시되는지 확인합니다.

4.3 사용자 페이지(/user/data)에서 데이터 확인

로그인한 사용자는 데이터 조회 페이지(/user/data)에서 자신의 장치에 대한 이벤트·센서 로그를 볼 수 있습니다. 장치 상태, 이벤트/센서 로그, 파일 동기화 기록 탭으로 구분되어 있습니다.

5. File Sync Tutorial

PC Node의 파일 동기화 기능을 사용하는 방법과, 동기화 기록을 확인하는 방법입니다. (실제 제품에서 제공하는 메뉴·기능명에 맞게 사용하세요.)

5.1 PC Node 파일 동기화 사용 방법

PC Node가 ONLINE인 상태에서, 제품에서 안내하는 방식으로 “파일 동기화”를 설정합니다.
동기화할 로컬 폴더와 대상(클라우드 또는 다른 Node)을 지정합니다.
동기화가 실행되면 변경된 파일이 자동으로 업로드·다운로드됩니다.

구체적인 설정 경로(대시보드 메뉴, Node 설정 화면 등)는 현재 제품 매뉴얼을 참고하세요.

5.2 동기화 기록 확인 방법

데이터 조회 페이지(/user/data)에서 파일 동기화 기록 탭을 엽니다. 업로드·다운로드·수정·삭제 등 동기화 이력이 시간순으로 표시됩니다. 장치별·기간별 필터가 있다면 활용하면 됩니다.

6. Troubleshooting

Pairing 실패

코드 오타 – Pairing Code를 복사·붙여넣기로 입력하고, 앞뒤 공백이 들어가지 않았는지 확인하세요.
만료 – 코드는 유효 시간이 있습니다. 대시보드에서 새로 발급(재발급) 후 다시 입력하세요.
이미 사용됨 – 한 번 사용된 코드는 재사용할 수 없습니다. 새 코드를 발급받아 입력하세요.

Node가 ONLINE이 안 뜰 때

Node 프로그램이 종료되지 않고 실행 중인지 확인하세요.
PC/ESP32의 인터넷(WiFi·유선) 연결을 확인하세요.
Pairing Code를 올바르게 입력했는지, 필요하면 재발급 후 다시 시도하세요.
몇 분 지나도 OFFLINE이면 Node를 한 번 종료한 뒤 다시 실행해 보세요.

터널 접속이 안 될 때

웹서버 미실행 – 터널 도메인은 “PC/Node에서 실제로 서비스가 떠 있을 때”만 응답합니다. 로컬에서 웹서버(또는 해당 포트의 앱)를 실행한 뒤 다시 접속해 보세요.
Node가 ONLINE인지 먼저 확인하세요.
방화벽·회사 네트워크에서 WebSocket/HTTPS가 막혀 있지 않은지 확인하세요.

ESP32 업로드 오류

Arduino IDE에서 보드(ESP32 모델)와 포트가 올바르게 선택되었는지 확인하세요.
USB 케이블이 데이터 전송을 지원하는지, 드라이버(CP210x, CH340 등)가 설치되어 있는지 확인하세요.
업로드 시 BOOT 버튼을 눌러야 하는 보드라면, 안내에 따라 버튼을 눌렀다 놓은 뒤 업로드를 다시 시도하세요.

다음 단계

튜토리얼을 완료했다면 다음 문서도 참고해 보세요:

어떻게 동작하나요? – Hub, Node, Sync의 동작 원리와 아키텍처
빠른 시작 – PC Node 연결 요약
API & CLI 레퍼런스 – 상세 API 및 CLI 명령어

Tutorial Changes

튜토리얼 문서를 현재 제품 구조에 맞게 전면 수정하면서 아래와 같이 변경했습니다.

Hub 설치·Docker 관련 제거 – 사용자 Hub 설치, Docker, 수동 서버 설정은 더 이상 안내하지 않습니다. Hub는 OrbiSync 클라우드에서만 제공됩니다.
PC Node 등록 방식 변경 – request_slot.py, node_agent CLI, slot-id/token 수동 입력 등 구버전 등록 흐름 제거. “대시보드에서 다운로드 → 실행 → Pairing Code 입력”만 안내합니다.
Getting Started with PC Node 추가 – 대시보드 다운로드, Pairing Code, ONLINE 확인, 터널 도메인 이해, (선택) 로컬 웹서버 확인으로 재구성했습니다.
로컬 웹서버 터널 튜토리얼 정리 – “집 PC를 개발 서버로” 내용을 “Exposing a Local Web Server via Tunnel”로 바꾸고, Python http.server·Node.js Express 예시만 남겼습니다. 터널 접속 시 웹서버가 실행 중이어야 한다는 주의를 명시했습니다.
LibarSDK·CoAP Gateway 튜토리얼 제거 – 구버전 CoAP/HTTP API·AI 제어 예제는 제거했습니다. 대신 ESP32 Basic Tutorial (LED 제어)를 추가해 Arduino 라이브러리·WiFi·Pairing Code·LED ON/OFF HTTP 예제로 대체했습니다.
Event / Sensor Log 튜토리얼 추가 – 이벤트 전송 방법과 대시보드·/user/data에서 로그 확인하는 흐름을 추가했습니다.
File Sync 튜토리얼 추가 – PC Node 파일 동기화 사용 방법과 동기화 기록 확인 방법을 간단히 안내했습니다.
Troubleshooting 섹션 정리 – Pairing 실패, Node ONLINE 미표시, 터널 접속 실패(웹서버 미실행 포함), ESP32 업로드 오류로 재구성했습니다.