본문으로 건너뛰기

Remocon 장치 만들기

remocon.kr 웹앱, IOSignal Desktop, 안드로이드 앱은 같은 규칙으로 장치를 찾고 제어합니다. 이 규칙만 따르면 Arduino 보드든 Node.js 프로그램이든 앱에 장치 카드로 나타납니다. 이 페이지는 2026-11-15부터 쓰는 지금의 규칙(장치 규칙 v2)을 설명합니다.

장치가 할 일은 네 가지입니다.

  1. 앱이 #search를 보내면 #notify로 자기 CID를 답합니다.
  2. $name으로 이름, $ui로 버튼이나 타입을 알립니다.
  3. <cid>@로 오는 명령을 처리합니다.
  4. 명령을 처리할 때마다 $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$states1=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를 참고하세요.

확인하기​

  1. 장치를 켜고 같은 공유기의 브라우저로 remocon.kr을 엽니다. 카드가 분류 탭에 나오는지 봅니다.
  2. 카드의 이름, 분류, 버튼이 $name, $ui와 맞는지 확인합니다.
  3. 버튼을 눌러 장치가 동작하고 상태가 카드에 돌아오는지 확인합니다.
  4. 장치를 끄면 카드가 사라지는지 확인합니다.

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)는 지금 규칙의 버튼 목록 형식과 같아서 그대로 보입니다.