Skip to main content

Build a Remocon device

The remocon.kr web app, IOSignal Desktop and the Android app find and control devices with the same rules. An Arduino board or a Node.js program that follows them shows up in the app as a device card. This page describes the current rules (device rules v2, from 2026-11-15).

A device does four things.

  1. When the app sends #search, it answers its own CID on #notify.
  2. It announces its name with $name and its buttons or type with $ui.
  3. It handles the commands that arrive on <cid>@.
  4. It sends its state with $state after every command.

Tags starting with # reach only the same HOME CHANNEL (the same public IP as the server sees it), so the app and the device find each other when they connect to the same server from the same router (HOME CHANNEL). When a device disconnects, the server sends close to <cid>@$state and the app drops it from the list.

Tags​

TagSent byValueStored by the server
#searchAppnoneno
#notifyDeviceits CID (a group: #channel)no
<cid>@$nameDevice (required)name or name:categoryyes
<cid>@$uiDevice (optional)a button list on,off,toggle or the extended form t=light.1yes
<cid>@$stateDeviceon=1;level=70yes
<cid>@$panelDevice (with p=1)screen JSONyes
<cid>@$viewDevice (with v=1)picture JSONyes
<cid>@App → devicecommand: a button name, on, off, toggle, key=valueno

The device does not write its own CID in the tag; it sends @$name, and the server delivers it as <cid>@$name with the sender's CID (CID publish).

Connection order​

On every connect (ready), send in this order:

subscribe #search → ($panel, $view) → $name → $ui → $state → #notify

  • Send #notify once on connect, then answer every #search.
  • Send $name and $ui on every connect. The server never clears stored values, so old ones must be overwritten. A device with no buttons and no screen can skip $ui, but if it ever sent one, it sends an empty value once to clear it.
  • Send $panel and $view before $ui, so they are stored when the app sees p=1, v=1 and subscribes.
  • JSON is only for $panel and $view. $name, $ui and $state are short text.

Name $name​

Lamp1 name only (the app's "uncategorized" tab)
Lamp1:Room1 name and category
Rainbow:2F living room
  • Split at the first :. Before it is the name, everything after is the category. A name cannot contain :; a category can. When sending a name a person typed, replace : in it with a space.
  • Leading and trailing spaces are removed; line breaks are not allowed. An empty name shows as an unnamed device.
  • The category is for display only: the app's tabs and the small text on the card. It does not affect search, command targets, permissions or group channels. Without a category the device goes to the "uncategorized" tab.
  • Length: keep the name and the category under 30 bytes each and the whole $name under 64 bytes. Another board reading this name needs the message to fit its receive buffer (Arduino default 80 bytes). The app cuts at 128 bytes. Korean characters are 3 bytes each.
  • A logged-in device starts with the name registered on the server; its own $name replaces it.

Buttons and type $ui​

$ui has two forms. Trim the value and look at the part before the first ;: if it starts with t=, p= or v=, it is the extended form, otherwise a button list.

$ui valueFormWhat the app shows
ON,OFF,TOGGLEbutton listthree buttons
all=1,all=0button listtwo buttons sending all=1, all=0
t=light.1extendedthe screen and bulb picture of the official type light.1
t=switch4.1;b=all=1,all=0extendedthe 4-gang switch screen and fallback buttons
p=1;b=on,offextendedthe device's own screen ($panel)
v=1;b=r1=1,r1=0extendedthe device's picture ($view) and buttons

Button list: button names separated by commas. A pressed button is sent to <cid>@ exactly as named, case included. Names cannot contain ; or line breaks; = is allowed.

Extended form: key=value pairs separated by ;, and the first key must be t, p or v. Unknown keys are ignored.

KeyMeaningExample
tofficial type <name>.<major>t=light.1
pa screen of its own in $panel (only 1 turns it on)p=1
va picture in $view (only 1 turns it on)v=1
bfallback button list (commas)b=on,off,toggle
  • How the app picks the screen: with p=1 and a valid $panel, that screen → the screen of type t → the b buttons → no buttons. An unknown type or widget drops to the next step, so a device using a new widget also sends b.
  • Values cannot contain ; or line breaks. Keep the whole $ui under 128 bytes.

State and commands​

  • An extended-form device sends $state as key=value;key=value, with keys set by its type (for example on=1 for light.1). Each type's keys and commands are at remocon.kr/types.
  • Always send $state after handling a command, even if nothing changed or the command was unknown. The app's waiting indicator clears then.
  • close belongs to the server; devices do not send it.
  • A device with lowercase-letter-plus-digit keys holding 0/1 (r1–r4, s1–s8) also takes all=1 (all on) and all=0 (all off) and sends its state once afterwards.
  • A device with only a button list may send free text in $state (OFF, 000). The app shows it as is with the buttons, but cannot show on/off or draw a picture.
  • Devices receive commands on @. Check that the payload is TEXT before reading it as a string.

Official types​

Names are <name>.<major>; the major number changes only when compatibility breaks.

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

Each type's screen, state keys, commands and default picture are at remocon.kr/types. With a matching type, sending t= alone is enough for the app to draw the screen and picture.

Own screen $panel and picture $view​

When no official type fits or another screen is needed, send screen JSON to @$panel and put p=1 in $ui. It has the same format as a type file (schema: 1, title, controls) and is usually 400–600 bytes, so it suits ESP boards with enough send buffer and RAM.

$view is not a control but how the device looks. It is one JSON object: kind is the picture, and the other values name the $state keys the picture reads. For example {"kind":"bulb","on":"s1","level":"b1"}. With v=1 in $ui the app subscribes to it.

kindPictureKeys read (defaults)
bulbbulbon, level (0–100), color (#rrggbb)
fanfanon, speed (0–10)
relaysa row of dotskeys: array of key names
thermotemperature and humiditytemp, hum
blindblindposition (0–100)
texttextkey

A device with an official type gets the type's default picture without sending $view. The app does not draw an unknown kind. Keep it under 512 bytes.

Group channels​

Several boards sharing one state appear as one card. They use a channel whose ID starts with #.

TagValue
#ch$nameGroup LED:Lab (the same for every member)
#ch$uiextended form only: t=switch2.1 or p=1
#ch$states1=0;s2=0 (shared)
  • Answer search with #notify #ch.
  • Groups have no commands. The app writes the new #ch$state; members subscribe to #ch$state and apply their own key. Do not overwrite the shared state on connect (the stored value arrives with the subscription).
  • The app does not control a group whose $ui is a button list. Give each example its own channel name.

Arduino example​

The core of the esp32-cid-led example. The Remocon library's RemoconUi.h has the name helpers.

#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", cleans ':' and ';'
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(); // also for unknown commands
}

void setup() {
// ... connect Wi-Fi ...
io.onReady(onReady);
io.onMessage(onMessage);
io.begin(&client, "io.remocon.kr", 55488);
}
  • RemoconUi.h helpers: formatName() (build name:category), formatNameSetting() (build $name from the board setting name), isExtendedUi(), nameOf(), categoryOf(), nameIs() (compare another device's $name), cleanName().
  • A board that reads other devices' names or states enlarges its receive buffer with io.setRxBuffer() before begin(). The server does not send a board any message larger than its buffer.
  • On ESP boards, letting the board setting name change $name lets people rename and recategorize the device without new firmware.
  • More examples (groups, relays, the iris RGB board with its own screen) are on Get started with Arduino and arduino.remocon.kr.

Node.js example​

You can also build a device on a PC without a board. Open remocon.kr in a browser on the same router and a "Desk lamp" card appears in the "Living room" tab.

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', 'Desk lamp:Living room'); // name:category
io.signal('@$ui', 't=light.1'); // official type
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(); // also for unknown commands
});

For subscribe() in the ready handler and direct messages on @, see JS subscriptions and lifecycle and the client API.

Check it​

  1. Turn the device on and open remocon.kr in a browser on the same router. Look for the card in its category tab.
  2. Check that the card's name, category and buttons match $name and $ui.
  3. Press a button: the device acts and its state comes back to the card.
  4. Turn the device off: the card disappears.

You can also check with the CLI. Connect iosignal-cli to the same server as the device.

sub #notify
pub #search → the device CID arrives on #notify
sub ?k3vd@$name,?k3vd@$ui,?k3vd@$state
pub ?k3vd@ toggle → ?k3vd@$state changes

If it does not appear, see device troubleshooting.

Older forms​

  • The old type names remocon/<name>/v<major>, $schema and <cid>@ui requests are not used.
  • Devices of remocon-arduino 9.0.0 and earlier ($name as name:category, a button list in $ui, free text in $state) match today's button-list form and still show up.