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.
- When the app sends
#search, it answers its own CID on#notify. - It announces its name with
$nameand its buttons or type with$ui. - It handles the commands that arrive on
<cid>@. - It sends its state with
$stateafter 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
| Tag | Sent by | Value | Stored by the server |
|---|---|---|---|
#search | App | none | no |
#notify | Device | its CID (a group: #channel) | no |
<cid>@$name | Device (required) | name or name:category | yes |
<cid>@$ui | Device (optional) | a button list on,off,toggle or the extended form t=light.1 | yes |
<cid>@$state | Device | on=1;level=70 | yes |
<cid>@$panel | Device (with p=1) | screen JSON | yes |
<cid>@$view | Device (with v=1) | picture JSON | yes |
<cid>@ | App → device | command: a button name, on, off, toggle, key=value | no |
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
#notifyonce on connect, then answer every#search. - Send
$nameand$uion 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
$paneland$viewbefore$ui, so they are stored when the app seesp=1,v=1and subscribes. - JSON is only for
$paneland$view.$name,$uiand$stateare 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
$nameunder 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
$namereplaces 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 value | Form | What the app shows |
|---|---|---|
ON,OFF,TOGGLE | button list | three buttons |
all=1,all=0 | button list | two buttons sending all=1, all=0 |
t=light.1 | extended | the screen and bulb picture of the official type light.1 |
t=switch4.1;b=all=1,all=0 | extended | the 4-gang switch screen and fallback buttons |
p=1;b=on,off | extended | the device's own screen ($panel) |
v=1;b=r1=1,r1=0 | extended | the 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.
| Key | Meaning | Example |
|---|---|---|
t | official type <name>.<major> | t=light.1 |
p | a screen of its own in $panel (only 1 turns it on) | p=1 |
v | a picture in $view (only 1 turns it on) | v=1 |
b | fallback button list (commas) | b=on,off,toggle |
- How the app picks the screen: with
p=1and a valid$panel, that screen → the screen of typet→ thebbuttons → no buttons. An unknown type or widget drops to the next step, so a device using a new widget also sendsb. - Values cannot contain
;or line breaks. Keep the whole$uiunder 128 bytes.
State and commands
- An extended-form device sends
$stateaskey=value;key=value, with keys set by its type (for exampleon=1forlight.1). Each type's keys and commands are at remocon.kr/types. - Always send
$stateafter handling a command, even if nothing changed or the command was unknown. The app's waiting indicator clears then. closebelongs to the server; devices do not send it.- A device with lowercase-letter-plus-digit keys holding 0/1 (
r1–r4,s1–s8) also takesall=1(all on) andall=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.
kind | Picture | Keys read (defaults) |
|---|---|---|
bulb | bulb | on, level (0–100), color (#rrggbb) |
fan | fan | on, speed (0–10) |
relays | a row of dots | keys: array of key names |
thermo | temperature and humidity | temp, hum |
blind | blind | position (0–100) |
text | text | key |
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 #.
| Tag | Value |
|---|---|
#ch$name | Group LED:Lab (the same for every member) |
#ch$ui | extended form only: t=switch2.1 or p=1 |
#ch$state | s1=0;s2=0 (shared) |
- Answer search with
#notify #ch. - Groups have no commands. The app writes the new
#ch$state; members subscribe to#ch$stateand 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
$uiis 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.hhelpers:formatName()(build name:category),formatNameSetting()(build$namefrom the board settingname),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()beforebegin(). The server does not send a board any message larger than its buffer. - On ESP boards, letting the board setting
namechange$namelets 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
- Turn the device on and open remocon.kr in a browser on the same router. Look for the card in its category tab.
- Check that the card's name, category and buttons match
$nameand$ui. - Press a button: the device acts and its state comes back to the card.
- 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>,$schemaand<cid>@uirequests are not used. - Devices of remocon-arduino 9.0.0 and earlier (
$nameasname:category, a button list in$ui, free text in$state) match today's button-list form and still show up.