Remocon 장치 만들기
remocon.kr 웹앱, IOSignal Desktop, 안드로이드 앱은 같은 규칙으로 장치를 찾고 제어합니다. 이 규칙만 따르면 Arduino 보드든 Node.js 프로그램이든 앱에 장치 카드로 나타납니다. 이 페이지는 2026-11-15부터 쓰는 지금의 규칙(장치 규칙 v2)을 설명합니다.
장치가 할 일은 네 가지입니다.
- 앱이
#search를 보내면#notify로 자기 CID를 답합니다. $name으로 이름,$ui로 버튼이나 타입을 알립니다.<cid>@로 오는 명령을 처리합니다.- 명령을 처리할 때마다
$state로 상태를 보냅니다.
#으로 시작하는 태그는 같은 홈채널(서버가 본 같은 공인 IP)에만 전달되므로, 앱과 장치는 같은 공유기에서 같은 서버에 접속해야 서로 찾습니다(홈채널). 장치 연결이 끊기면 서버가 <cid>@$state에 close를 보내고, 앱은 그 장치를 목록에서 뺍니다.
태그
| 태그 | 누가 보냄 | 값 | 서버 보관 |
|---|---|---|---|
#search | 앱 | 없음 | 아니오 |
#notify | 장치 | 자기 CID (그룹은 #채널) | 아니오 |
<cid>@$name | 장치 (필수) | 이름 또는 이름:분류 | 예 |
<cid>@$ui | 장치 (선택) | 버튼 목록 on,off,toggle 또는 확장형 t=light.1 | 예 |
<cid>@$state | 장치 | on=1;level=70 | 예 |
<cid>@$panel | 장치 (p=1일 때) | 화면 JSON | 예 |
<cid>@$view | 장치 (v=1일 때) | 그림 JSON | 예 |
<cid>@ | 앱 → 장치 | 명령: 버튼 이름, on, off, toggle, key=value | 아니오 |
장치는 송신 태그에 자기 CID를 쓰지 않고 @$name처럼 보냅니다. 서버가 보낸 장치의 CID를 붙여 <cid>@$name으로 전달합니다(CID 발행).
접속 순서
접속(ready)할 때마다 다음 순서로 보냅니다.
#search 구독 → ($panel, $view) → $name → $ui → $state → #notify
- 접속할 때 한 번
#notify를 보내고, 그 뒤로는#search가 올 때마다 답합니다. $name과$ui는 접속할 때마다 보냅니다. 서버는 보관 값을 지우지 않으므로 예전에 보낸 값을 덮어써야 합니다. 버튼도 화면도 없는 장치는$ui를 생략할 수 있지만, 예전에 보낸 적이 있으면 빈 값을 한 번 보내 지웁니다.$panel,$view는$ui보다 먼저 보냅니다. 앱이$ui의p=1,v=1을 보고 구독할 때 이미 보관되어 있어야 합니다.- JSON은
$panel,$view에만 씁니다.$name,$ui,$state는 짧은 글자입니다.
이름 $name
전등1 이름만 (앱의 "미분류" 탭)
전등1:방1 이름과 분류
무지개조명:2층 거실
- 첫 번째
:에서 나눕니다. 앞은 이름, 뒤 전부는 분류입니다. 이름에는:를 쓸 수 없고 분류에는 써도 됩니다. 사람이 입력한 이름을 보낼 때는 이름 속의:를 공백으로 바꿉니다. - 앞뒤 공백은 지웁니다. 줄바꿈은 쓸 수 없습니다. 이름이 비면 앱은 "이름 없는 장치"로 보여 줍니다.
- 분류는 보여 주기 전용입니다. 앱의 탭과 카드 보조 글씨로만 쓰이고, 검색 범위·명령 대상·권한·그룹 채널과는 관계없습니다. 분류가 없으면 "미분류" 탭에 나옵니다.
- 길이: 이름과 분류는 각각 30바이트(한글 약 10자) 이하,
$name전체는 64바이트 이하를 권장합니다. 다른 보드가 이 이름을 읽으려면 메시지가 그 보드의 수신 버퍼(Arduino 기본 80바이트)에 들어가야 합니다. 앱은 128바이트에서 자릅니다. - 로그인한 장치는 서버에 등록한 이름이 먼저 보관되어 있고, 장치가
$name을 보내면 그 값으로 바뀝니다.
버튼과 타입 $ui
$ui는 두 형식 중 하나입니다. 값의 앞뒤 공백을 지우고 처음 ; 앞까지를 봤을 때 t=, p=, v= 중 하나로 시작하면 확장형, 아니면 버튼 목록입니다.
$ui 값 | 형식 | 앱에 보이는 것 |
|---|---|---|
ON,OFF,TOGGLE | 버튼 목록 | 버튼 3개 |
all=1,all=0 | 버튼 목록 | 버튼 2개. 누르면 all=1, all=0 |
t=light.1 | 확장 | 공식 타입 light.1의 화면과 전구 그림 |
t=switch4.1;b=all=1,all=0 | 확장 | 4구 스위치 화면과 대체 버튼 |
p=1;b=on,off | 확장 | 장치가 보낸 자체 화면($panel) |
v=1;b=r1=1,r1=0 | 확장 | 장치가 보낸 그림($view)과 버튼 |
버튼 목록: 쉼표로 나눈 버튼 이름입니다. 앱은 버튼을 누르면 이름 그대로(대소문자 포함) <cid>@로 보냅니다. 이름에 ;와 줄바꿈은 쓸 수 없고 =는 써도 됩니다.
확장형: ;로 나눈 key=value이며 첫 키는 t, p, v 중 하나여야 합니다. 모르는 키는 무시됩니다.
| 키 | 뜻 | 예 |
|---|---|---|
t | 공식 타입 <이름>.<major> | t=light.1 |
p | $panel에 자체 화면이 있음 (1일 때만) | p=1 |
v | $view에 그림이 있음 (1일 때만) | v=1 |
b | 대체 버튼 목록 (쉼표) | b=on,off,toggle |
- 앱이 화면을 고르는 순서:
p=1이고$panel이 유효하면 그 화면 →t의 타입 화면 →b버튼 → 버튼 없음. 앱이 모르는 타입이나 위젯이면 다음 단계로 내려가므로, 새 위젯을 쓰는 장치는b를 함께 보냅니다. - 값에
;와 줄바꿈은 쓸 수 없습니다.$ui전체는 128바이트 이하를 권장합니다.
상태와 명령
- 확장형 장치의
$state는key=value;key=value이고, 키는 타입이 정합니다(예:light.1은on=1). 각 타입의 키와 명령은 remocon.kr/types에 있습니다. - 명령을 처리한 뒤 반드시
$state를 보냅니다. 값이 그대로이거나 모르는 명령이어도 보냅니다. 앱의 대기 표시가 그때 풀립니다. close는 서버가 쓰는 값이므로 장치가 보내지 않습니다.r1r4,s1s8처럼 소문자+숫자 키에 0/1 값을 가진 장치는all=1(모두 켜기)과all=0(모두 끄기)도 받고, 처리 뒤 상태를 한 번 보냅니다.- 버튼 목록만 쓰는 장치는
$state에 자유 문자열(OFF,000)을 보내도 됩니다. 앱은 원문을 보여 주고 버튼만 제공하며, 켜짐 표시나 그림은 그릴 수 없습니다. - 장치는 명령을
@로 받습니다. 문자열로 쓰기 전에 TEXT 형식인지 확인합니다.
공식 타입
이름은 <이름>.<major>이고, 하위 호환이 깨질 때만 major가 올라갑니다.
light.1, dimmer.1, rgb-light.1, relay4.1, fan.1, thermo-hygrometer.1, media-remote.1, switch2.1, switch3.1, switch4.1, switch8.1, iris.1, iris.2, camera.1
각 타입의 화면, 상태 키, 명령, 기본 그림은 remocon.kr/types에서 볼 수 있습니다. 맞는 타입이 있으면 t=만 보내도 앱이 화면과 그림을 그립니다.
자체 화면 $panel과 그림 $view
맞는 공식 타입이 없거나 다른 화면이 필요하면 화면 JSON을 @$panel에 보내고 $ui에 p=1을 넣습니다. 형식은 타입 파일과 같고(schema: 1, title, controls), 보통 400~600바이트라 송신 버퍼와 RAM이 넉넉한 ESP 보드에서 씁니다.
$view는 조작이 아니라 장치의 모습입니다. JSON 객체 하나이며 kind가 그림 종류, 나머지 값은 그림이 읽을 $state 키 이름입니다. 예: {"kind":"bulb","on":"s1","level":"b1"}. $ui에 v=1을 넣으면 앱이 구독합니다.
kind | 그림 | 읽는 키 (기본값) |
|---|---|---|
bulb | 전구 | on, level(0~100), color(#rrggbb) |
fan | 선풍기 | on, speed(0~10) |
relays | 동그라미 여러 개 | keys: 키 이름 배열 |
thermo | 온도·습도 숫자 | temp, hum |
blind | 블라인드 | position(0~100) |
text | 글자 | key |
공식 타입을 쓰는 장치는 $view를 보내지 않아도 타입의 기본 그림이 나옵니다. 앱이 모르는 kind는 그리지 않습니다. 512바이트 이하로 둡니다.
그룹 채널
여러 보드가 상태 하나를 함께 쓰면 앱에는 카드 하나로 보입니다. ID가 #으로 시작하는 채널을 씁니다.
| 태그 | 값 |
|---|---|
#ch$name | 그룹 LED:실험실 (구성원 모두 같은 값) |
#ch$ui | 확장형만: t=switch2.1 또는 p=1 |
#ch$state | s1=0;s2=0 (공유) |
- 검색에는
#notify #ch로 답합니다. - 그룹에는 명령이 없습니다. 앱이
#ch$state를 새 값으로 쓰고, 구성원은#ch$state를 구독해 자기 키만 적용합니다. 접속할 때 공유 상태를 덮어쓰지 않습니다(보관된 값이 구독과 함께 옵니다). - 그룹의
$ui가 버튼 목록 형식이면 앱이 제어하지 않습니다. 예제마다 채널 이름을 겹치지 않게 합니다.
Arduino 예제
esp32-cid-led 예제의 핵심입니다. Remocon 라이브러리의 RemoconUi.h에 이름 도우미가 있습니다.
#include <IOSignal.h>
#include <RemoconUi.h>
IOSignal io;
bool ledOn = false;
void sendState() { io.signal("@$state", ledOn ? "on=1" : "on=0"); }
void onReady() {
io.subscribe("#search");
char name[64];
remocon::formatName(name, sizeof(name), "ESP32-LED", "HOME"); // "ESP32-LED:HOME", ':'·';' 정리
io.signal("@$name", name);
io.signal("@$ui", "on,off,toggle");
sendState();
io.signal("#notify", io.cid);
}
void onMessage(char* tag, uint8_t type, uint8_t* payload, size_t size) {
if (strcmp(tag, "#search") == 0) { io.signal("#notify", io.cid); return; }
if (strcmp(tag, "@") != 0) return;
const bool text = type == IOSignal::TEXT && payload && size > 0 && payload[size - 1] == 0;
const char* command = text ? (const char*)payload : "";
if (strcmp(command, "on") == 0) ledOn = true;
else if (strcmp(command, "off") == 0) ledOn = false;
else if (strcmp(command, "toggle") == 0) ledOn = !ledOn;
digitalWrite(LED_PIN, ledOn ? HIGH : LOW);
sendState(); // 모르는 명령이어도 보냅니다
}
void setup() {
// ... Wi-Fi 연결 ...
io.onReady(onReady);
io.onMessage(onMessage);
io.begin(&client, "io.remocon.kr", 55488);
}
RemoconUi.h도우미:formatName()(이름:분류 만들기),formatNameSetting()(보드 설정name값으로$name만들기),isExtendedUi(),nameOf(),categoryOf(),nameIs()(다른 장치의$name비교),cleanName().- 다른 장치의 이름·상태를 읽는 보드는
begin()전에io.setRxBuffer()로 수신 버퍼를 늘립니다. 서버는 버퍼보다 큰 메시지를 그 보드에 보내지 않습니다. - ESP 보드는 보드 설정의
name항목으로$name을 바꿀 수 있게 하면 펌웨어를 고치지 않고 이름과 분류를 바꿀 수 있습니다. - 다른 예제(그룹, 릴레이, 자체 화면을 쓰는 iris RGB 등)는 Arduino 시작하기와 arduino.remocon.kr에 있습니다.
Node.js 예제
보드 없이 PC에서 장치를 만들어 볼 수도 있습니다. 같은 공유기의 브라우저로 remocon.kr을 열면 "책상 전등" 카드가 "거실" 탭에 나타납니다.
import { IO } from 'iosignal';
const io = new IO('wss://io.remocon.kr/ws');
let on = false;
const sendState = () => io.signal('@$state', on ? 'on=1' : 'on=0');
io.on('ready', () => {
io.subscribe('#search');
io.signal('@$name', '책상 전등:거실'); // 이름:분류
io.signal('@$ui', 't=light.1'); // 공식 타입
sendState();
io.signal('#notify', io.cid);
});
io.on('#search', () => io.signal('#notify', io.cid));
io.on('@', (tag, command) => {
if (command === 'on') on = true;
else if (command === 'off') on = false;
else if (command === 'toggle') on = !on;
sendState(); // 모르는 명령이어도 보냅니다
});
ready 핸들러의 subscribe()와 직접 수신 @의 동작은 JS 구독과 수명주기과 클라이언트 API를 참고하세요.
확인하기
- 장치를 켜고 같은 공유기의 브라우저로 remocon.kr을 엽니다. 카드가 분류 탭에 나오는지 봅니다.
- 카드의 이름, 분류, 버튼이
$name,$ui와 맞는지 확인합니다. - 버튼을 눌러 장치가 동작하고 상태가 카드에 돌아오는지 확인합니다.
- 장치를 끄면 카드가 사라지는지 확인합니다.
CLI로도 확인할 수 있습니다. iosignal-cli를 장치와 같은 서버에 연결합니다.
sub #notify
pub #search → #notify로 장치 CID가 옵니다
sub ?k3vd@$name,?k3vd@$ui,?k3vd@$state
pub ?k3vd@ toggle → ?k3vd@$state가 바뀝니다
나타나지 않으면 장치 문제 해결을 보세요.
예전 방식
- 예전 타입 이름
remocon/<이름>/v<major>,$schema,<cid>@ui요청은 쓰지 않습니다. - remocon-arduino 9.0.0 이하 장치(
$name이름:분류, 버튼 목록$ui, 자유 문자열$state)는 지금 규칙의 버튼 목록 형식과 같아서 그대로 보입니다.