Alex2ESP/src/Alex2ESP.h

/*
 * @title Alex2ESP Library
 * @author David
 * @license MIT
 * @contributors chaos511
 *
 * @description Companion library of the Alex2MQTT Alexa skill: the devices a sketch declares become Alexa
 * endpoints through the MQTT broker at alex2mqtt.stormysdream.club.
 *
 *   <root>/discover                      in   answered with one discovery object per device on <root>/discover_r
 *   <root>/<endpointId>/alexaDirective   in   the directive, handed to the device's ReportState / Event handler
 *   <root>/<endpointId>/alexaResponce    out  the report the handler built with buildStatusMessage()
 */

#ifndef ALEX2ESP_H
#define ALEX2ESP_H

#include <Arduino.h>
#include <AsyncMqttClient.h>
#include <ArduinoJson.h>
#include "AlexaBridgeLogic.h"
#include "AlexaDevice.h"
#include "AlexaInterface.h"
#include "AlexaLimits.h"
#include "AlexaLog.h"
#include "AlexaTransport.h"
#include "AlexaUtils.h"
#include <deque>

enum class Alex2ESPState
{
    UNINITIALIZED, // begin() has not been called
    INITIALIZED,   // begin() has been called; the first connect waits for the clock
    CONNECTING,
    SUBSCRIBING,   // session open, the subscriptions are not acknowledged yet
    CONNECTED,     // subscribed: discovery requests and directives arrive
    DISCONNECTED
};

class Alex2ESP : public AlexaTransport
{
public:
    // Constructor
    Alex2ESP();

    // Begin function for initialization: MQTT username, MQTT password, root topic (the same order as alex2node).
    // The username and the password are not copied: they have to stay valid for as long as the client is used.
    // Starts SNTP; loop() opens the MQTT session once the clock is set, or after 5 s without an answer.
    void begin(const char *username, const char *password, const char *rootTopic);
    Alex2ESPState getState() const;

    // Call from the sketch's loop(): connects, answers discovery requests and hands directives to the devices.
    // It does not block; the handlers of the sketch run inside it.
    void loop();

    AsyncMqttClientDisconnectReason getDisconnectReason() const;

    // Returns the device with this endpointId, creating it on first use. The pointer stays valid for the lifetime
    // of the client: devices live in a std::deque, which never relocates its elements when another one is added.
    // Call it after begin(): a device takes the root topic of its reports when it is created.
    AlexaDevice *getDevice(const String &name, const String &endpointId);

    // What the library prints on Serial: AlexaLogLevel::NONE, ERROR, INFO (the default) or DEBUG
    void setLogLevel(AlexaLogLevel level);

    // false before begin(): the sketch sets the clock itself (its own configTime() with a time zone, an RTC).
    // begin() then leaves SNTP alone; the library only reads time().
    void setTimeSource(bool useSntp);

    // AlexaTransport: what the devices' reports are sent and stamped with
    AlexaSendResult publish(const char *topic, JsonDocument &doc) override;
    void timestamp(char *buffer, size_t size) override;

private:
    static const unsigned long CLOCK_WAIT_MS = 5000;       // How long the first connect waits for SNTP
    static const unsigned long RECONNECT_INTERVAL_MS = 5000;
    static const unsigned long DISCOVERY_WINDOW_MS = 5000; // How long the backend keeps collecting a discovery answer
    static const unsigned long DISCOVERY_RETRY_MS = 20;    // Pause before a refused discovery publish is tried again

    AsyncMqttClient mqttClient; // MQTT client instance
    String rootTopic;           // Root topic for communication
    String discoverTopic;       // The topic we listen on for discovery messages
    String discoverTopicSend;   // The topic we send discovery messages
    String directiveFilter;     // The subscription that delivers the directives of every endpoint

    std::deque<AlexaDevice> devices; // Collection of devices (deque: pointers handed out by getDevice stay valid)

    Alex2ESPState state;
    AsyncMqttClientDisconnectReason disconnectReason;
    bool useSntp;
    unsigned long beginTime;         // millis() when begin() ran
    unsigned long lastReconnectTime;
    uint16_t discoverSubscription;   // Packet ids of the two SUBSCRIBEs, to match their acknowledgements
    uint16_t directiveSubscription;
    uint8_t subscriptionsPending;

    bool discoveryRequested;            // Set by the MQTT callback, taken by loop()
    bool discoveryActive;               // An answer is going out
    bool discoveryDeferred;             // The answer had to pause: the MQTT client or the heap was full
    size_t discoveryNext;               // Next device to announce
    size_t discoveryAnnounced;          // Devices announced in this answer
    unsigned long discoveryStarted;     // millis() when the Discover arrived
    unsigned long discoveryLastAttempt; // millis() of the publish that was refused

    AlexaDirectiveBuffer directive; // The directive that waits for loop(), or is still arriving
    AlexaRecentIds recentIds;       // messageIds of the last directives handled

    // Internal event handlers (called by the MQTT client from the network context: they only take notes)
    void onMqttConnect(bool sessionPresent);
    void onMqttDisconnect(AsyncMqttClientDisconnectReason reason);
    void onSubscribe(uint16_t packetId, uint8_t qos);
    void onMessage(char *topic, char *payload, AsyncMqttClientMessageProperties properties, size_t length, size_t index, size_t total);

    //loop processing function
    void connectWhenClockIsSet();
    void handleMqttReconnection();
    void continueDiscovery();
    void publishDiscovery();
    void processDirective();

    AlexaDevice *findDevice(const char *endpointId, size_t length);
    AlexaSendResult trySend(const char *topic, JsonDocument &doc, size_t *length);
    void logRefusal(const char *topic, AlexaSendResult result, size_t length);
};

#endif // ALEX2ESP_H