Skip to main content

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​

BoardExampleWhat it does
A 4-channel relayesp8266-relay4chFour relays r1 to r4
B lightd1-mini-led-button (ESP8266 D1 mini)One built-in LED on
c1 button controllerbutton-controller (D1 mini)Button 1 toggles relay 1 of A, button 2 toggles B
c2 button controllerbutton-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​

BoardSubscribes toSends as kept valuesCommands 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 setting name.
  • t= in $ui is 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 #search too. 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.

Controllertargetb1b2
c1relayArelayA:r1lampB:toggle
c2relayAallr2
ValueMeaningWhat is sent
relayA:r1Toggle relay 1 of AIf the last state had r1=1, r1=0 to relayA@
allToggle all of the targetall=0 if any is on, all=1 if all are off (one command)
lampB:toggleToggle Btoggle to lampB@, as it is
  • Sending b2=relayA:r4 to c1@ 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:

  1. 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.
  2. Button 1 (relayA:r1): r1 is 1, so c1 sends r1=0 to relayA@.
  3. A turns relay 1 off and sends r1=0;r2=0;r3=0;r4=1 on @$state.
  4. The server keeps this state and sends it to the subscribers c1, c2 and the app. All of them know the same state.
  5. 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, @$ui and @$state of each CID and shows four cards.
  • When a board turns off, the server sends close on <cid>@$state and the app removes its card. If A turns off, the controllers receive close too 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 applies r1 to r4 and B only r5; the keys must not overlap.
  • A group takes no commands. A controller button #room:r2 rewrites the whole string of #room$state with the key changed.
  • The app shows one card (#room), and members answer a search with #notify #room.

It does not fit this setup:

  • #room:all changes 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 close arrives. 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 deviceGroup channel
Cards in the appOne per deviceOne per group
ControlCommands (<cid>@), the device answers with its stateThe whole shared state #ch$state is rewritten
Simultaneous pressesThe device handles them in orderThe later write wins
Disconnect noticeThe server sends closeNone
TargetNeeds a fixed CID (device key login)Only the channel name must match