DocsClientsReadings and commands

Readings and commands

Your board sends readings to WBSKT, and WBSKT can send commands back. Both are short messages with a type and some data.

Send a reading

Pick a type that describes the message, like temperature or alert, and send the values with it. Each one carries the time it was made.

JsonDocument reading;
reading["celsius"] = readTemperature();
wbskt.send("temperature", reading);
await wbskt.SendAsync("temperature", new { celsius = ReadTemperature() });
client.send("temperature", {"celsius": read_temperature()})

Messages start workflows and show up in the client's activity in the console. To chart a value, report it as state, below.

Receive a command

Workflows and the console can send your board a command, like switching a heater on. Declare the commands your board takes, so the console can show a form for them, and say what to do when one arrives.

void setup() {
  WiFi.begin("home-wifi", "wifi-password");
  wbskt.addCommand("heater", "Switch the heater")
    .param("on", WbsktDataType::Boolean, true, "On");
  wbskt.onMessage([](const WbsktMessage& message) {
    if (strcmp(message.type, "heater") == 0) {
      bool on = message.payload["on"] | false;
      digitalWrite(HEATER_PIN, on ? HIGH : LOW);
    }
  });
  wbskt.begin();
}
wbskt.OnMessageReceived += (type, payload, commandId) =>
{
    if (type == "heater")
        heater.Switch(payload);
};
def handle(message):
    if message.type == "heater":
        relay.value = message.payload["on"]

client.on_message = handle

The library confirms delivery for you, so the console and your workflow runs show whether the command arrived.

Report what the board is doing

State is what your board is doing right now, like whether the heater is on. Report it when it changes: the console shows the latest value, and numbers are kept as readings for charts. How long depends on your plan.

JsonDocument state;
state["heater"] = "on";
wbskt.reportState(state);
await wbskt.ReportStateAsync(new Dictionary<string, object?>
{
    ["heater"] = "on"
});
client.report_state({"heater": "on"})

Good to know

  • A few types are reserved for WBSKT itself: capabilities, state.report and anything starting with sys.
  • Keep passwords and keys out of messages. Messages show up in your audit log.
  • Send readings when they change or every minute or so. Your board saves power and your charts stay readable.