MQTT interface

The firmware supports connecting to a hardcoded mqtt broker using MQTT over SSL.

• Generic topic format

  • <device_type>/<clientid>/<action_type>/<action>/<service>/[service_id]
    • <device_type> specifies the group of devices and should be used to identify the supported services. For example, sonoffb is used for SOnOff Basic switch and supports one relay, ota, etc.
    • <clientid> is mqtt client id, a unique for the device
    • <action_type> specified action type, one of [evt|est|cfg|cmd]
      • <evt> is sent right after mqtt connection and when specific event occurs, it could happen due to a command (relay switch change) or other trigger (sensor temperature change, etc).
      • <cmd> messages are sent to immediately trigger an action or set a configuration, feedback is received via evt messages
    • <action> is a specific action like state, onTimeout, etc.
    • <service> is a specific services supported and can be one of ota/scheduler/relay/thermostat/ops
    • <service_id> is a specific service id for services supporting multiple instances (relay/scheduler)

• Connection set-up:

  • ESP device MQTT client connects to MQTT broker using the following message:

  {
    username: <xxxx>;
    password: <xxxx>;
    server: <xxxx>;
    port: <xxxx>;
    clientid: <username>;
    keepalive: 30;
    lwt: {
      topic: <device_type>/<clientid>/evt/status/available;
      qos: 1;
      retain: 1;
      msg: "offline";
  }
  

  • right after connection, the device publishes his state using a message similar to lwt, in a way that another mqtt client can subscribe to topic <device_type>/<clientid>/evt/connection/state to know the device state:

  {
    topic: <device_type>/<clientid>/evt/status/available;
    qos: 1;
    retain: 1;
    msg: "online"
  }
  

  • right after connection, the device publishes his details:

  {
    topic: <device_type>/<clientid>/evt/config/available;
    qos: 1;
    retain: 1;
    msg:{"fw_version": "v123", "connect_reason": 33};
  }
  

• relay control

  • relays are configured in using make menuconfig and specifying number of relays(max 4) and GPIO port for for each of them
  • relay status for all relays is published right after MQTT connection
  • device subscribes to <device_type>/<clientid>/cmd/status/relay/<id> topic for relays control. Expected payload format is "on"|"off";
  • relay status evt message:

  {
    topic: <device_type>/<clientid>/evt/status/relay/<id>;
    qos: 1;
    retain: 1;
    msg: "on"|"off";
  }
  

  • device also subscribes to <device_type>/<clientid>/cmd/sleep/relay/<id> topic for relays control. Expected payload format is:

     <timeout>; //max seconds for on state (optional defense for accidental change to on, 0 to disable)
  
  

  • relay timeout evt message:

  {
    topic: <device_type>/<clientid>/evt/sleep/relay/<id>;
    qos: 1;
    retain: 1;
    msg: <seconds>;
  }
  
  

• thermostat

  • There are max 4 thermostats available, configured via make menuconfig

  • Mode control and state

    • device subscribes to <device_type>/<clientid>/cmd/mode/thermostat/n, accepted values: "heat"|"off";
    • status published on <device_type>/<clientid>/evt/mode/thermostat/n, accepted values: "heat"|"off";
    • action status published on <device_type>/<clientid>/evt/action/thermostat/n, accepted values: "idle heating"|"off";

  • Temperature control

  • device subscribes to <device_type>/<clientid>/cmd/temp/thermostat, accepted values: temperature value;

  • status published on <device_type>/<clientid>/evt/temp/thermostat, accepted values: temperature value;

  • temperature tolerance cmd device subscribes to <device_type>/<clientid>/cfg/tolerance/thermostat, accepted values: temperature value;

  • temperature tolerance status published on <device_type>/<clientid>/est/tolerance/thermostat, accepted values: temperature value;

  • current temperature published on <device_type>/<clientid>/evt/ctemp/thermostat, accepted values: temperature value;

• OTA (old topic format)

  • OTA command TBC
  • OTA status TBC

• scheduler control

  • there are maximum 2 scheduling slots (as start)
  • <device_type>/<clientid>/cmd/action/scheduler/<id> (with pair evt topic)
    • payload: action string from a hardcoded list:
      • relay_on/relay_off
      • ow_on/ow_off (open-window)
      • tbc
  • <device_type>/<clientid>/cmd/time/scheduler/<id>
    • payload:
      • dow (day of week, 1-Mo, ..., 7-Su, 0 repetition disabled) 1 char
      • UTC time: hh mm
      • examples:
        • 3 17 30 (Mo and Tu at 17:30)
        • 0 17 30 (once, next time at 17:30)
  • <device_type>/<clientid>/cmd/status/scheduler/<id>
    • string: ON|OFF (OFF timer is never checked, ON timer becomes off after first time passes and repeat is empty, otherwise it stays on)