Device setup example: relays and button controllers
This setup applies the rules of Build a Remocon device to four example boards. The app (remocon.kr) and other boards with buttons control the same devices, and all of them see the same state.
The setup
| Board | Example | What it does |
|---|---|---|
| A 4-channel relay | esp8266-relay4ch | Four relays r1 to r4 |
| B light | d1-mini-led-button (ESP8266 D1 mini) | One built-in LED on |
| c1 button controller | button-controller (D1 mini) | Button 1 toggles relay 1 of A, button 2 toggles B |
| c2 button controller | button-controller (ESP32-C3) | Button 1 toggles all of A, button 2 toggles relay 2 of A |
All four boards connect from the same router (the same public IP), so they share a home channel and #search reaches all of them. The two controllers run the same sketch on a D1 mini (buttons D5, D6) and an ESP32-C3 (buttons GPIO9 BOOT, GPIO10).
One CID per device
A and B are each one device. When a button is pressed, a controller sends a command to the target device's CID. The device handles it and sends its own state, and every controller and app subscribed to that state receives the same value.
Why fixed CIDs
An anonymous connection gets a new CID on every reconnection (?k3vd → ?p2xq), which would break the target CID written in a controller's settings. So A and B log in with a device key and use the fixed CID registered on the server. Enter the device key over USB on the board settings page. This page calls the fixed CIDs relayA and lampB.
The controllers may stay anonymous: nobody sends commands to a controller's CID. To change a controller's settings from the app, the app finds its CID with a search.
What each board does
| Board | Subscribes to | Sends as kept values | Commands it takes |
|---|---|---|---|
A relayA | #search | @$name = Relay4CH:HOME@$ui = t=relay4.1@$state = r1=1;r2=0;r3=0;r4=1 | r1=0, all=1, all=0 |
B lampB | #search | @$name = D1-mini:HOME@$ui = t=light.1@$state = on=1 | on, off, toggle |
| c1, c2 | #search, relayA@$state (c1 also lampB@$state) | @$name = Button Control:HOME@$ui = b1,b2@$state = target=relayA;link=1;b1=relayA:r1;b2=lampB:toggle | b1 (press), b2=r3 (setting), target=… |
- In
$name, the part before the first:is the name and the rest is the app's category. Change both with the board settingname. t=in$uiis an official type; with a type the app draws that type's screen. A device without a type, such as a controller, sends a button list in$ui.- Controllers are devices that answer
#searchtoo. They appear in the app, which can press their buttons or change what the buttons do.
Button settings
The board settings target, b1 and b2 decide what a controller's buttons do. A value is target:action; without target: the target setting is used.
| Controller | target | b1 | b2 |
|---|---|---|---|
| c1 | relayA | relayA:r1 | lampB:toggle |
| c2 | relayA | all | r2 |
| Value | Meaning | What is sent |
|---|---|---|
relayA:r1 | Toggle relay 1 of A | If the last state had r1=1, r1=0 to relayA@ |
all | Toggle all of the target | all=0 if any is on, all=1 if all are off (one command) |
lampB:toggle | Toggle B | toggle to lampB@, as it is |
- Sending
b2=relayA:r4toc1@from the app or the CLI changes the setting remotely. The controller checks the value, saves it and answers with its state. - A controller sends no toggle before it has the target's
$state: it decides on or off from the last state.
What happens on a press
Pressing button 1 of c1:
- c1 already has
relayA@$state=r1=1;r2=0;r3=0;r4=1. It is a kept value, so it arrived as soon as c1 subscribed. - Button 1 (
relayA:r1):r1is 1, so c1 sendsr1=0torelayA@. - A turns relay 1 off and sends
r1=0;r2=0;r3=0;r4=1on@$state. - The server keeps this state and sends it to the subscribers c1, c2 and the app. All of them know the same state.
- When c2 changes relay 1 next, it already knows
r1=0.
Sending a command is not the end. The state in step 3 is the actual result. That is why a device sends its state once even when nothing changed or the command is unknown.
Pressing button 1 of c2 sends all=0 to relayA@, because r4 is on; A turns all four relays off and sends its state once.
Finding and disconnecting
- When the app sends
#search, A, B, c1 and c2 all answer#notify <own CID>. The app subscribes to@$name,@$uiand@$stateof each CID and shows four cards. - When a board turns off, the server sends
closeon<cid>@$stateand the app removes its card. If A turns off, the controllers receiveclosetoo and know A is gone.
With a group channel
The rules also have a group channel that several boards share. With A and B as members of group #room:
- Shared state
#room$state=r1=1;r2=0;r3=0;r4=1;r5=1. A appliesr1tor4and B onlyr5; the keys must not overlap. - A group takes no commands. A controller button
#room:r2rewrites the whole string of#room$statewith the key changed. - The app shows one card (
#room), and members answer a search with#notify #room.
It does not fit this setup:
#room:allchanges every key of the group, so it toggles B (r5) too. A alone cannot be switched.- When two controllers write at almost the same time, the later string overwrites the earlier change.
- A group has no owner, so no
closearrives. Nobody learns that A turned off, and the app removes the card only after a search that nobody answers.
Use a group when several boards should follow the same output together (lights in several rooms acting as one switch). The examples are esp32-group-led and wifi-simple. When boards do different things, give each device its own CID as above.
Comparison
| One CID per device | Group channel | |
|---|---|---|
| Cards in the app | One per device | One per group |
| Control | Commands (<cid>@), the device answers with its state | The whole shared state #ch$state is rewritten |
| Simultaneous presses | The device handles them in order | The later write wins |
| Disconnect notice | The server sends close | None |
| Target | Needs a fixed CID (device key login) | Only the channel name must match |