GPSFamilyProtocol.h

Go to the documentation of this file.

#pragma once
 
#include <chrono>
#include <cstdint>
#include <memory>
#include <optional>
#include <span>
#include <string_view>
#include <utility>
#include <vector>
 
#include <QtCore/QByteArray>
#include <QtCore/QByteArrayView>
#include <QtCore/QLatin1StringView>
#include <QtCore/QString>
 
#include "GPSCommand.h"
#include "GPSProtocolEvent.h"
#include "GPSReceiverConfig.h"
#include "GPSStreamDemux.h"
#include "GPSType.h"
 
class GPSCommandChannel;
class GPSFamilyProtocol;
class GPSProtocolRuntime;
class QLoggingCategory;
 
using GPSLogCategory = const QLoggingCategory& (*)();
 
using GPSSignatureFunction = QLatin1StringView (*)(const GPSFrame& frame);
 
struct GPSConfig
{
    GPSBaseStationConfig base{};
    bool allowPersistentChanges = false;
    unsigned detectedBaud = 0;
 
    [[nodiscard]] unsigned linkBaud(unsigned requested, unsigned fallback) const
    {
        return requested ? requested : detectedBaud ? detectedBaud : fallback;
    }
};
 
struct GPSReceiverFamily
{
    GPSType type = GPSType::passive;
    GPSLogCategory logCategory = nullptr;
    GPSStreamConfig stream{};
    std::span<const unsigned> baudCandidates{};
    unsigned autoBaudRate = 0;
    std::unique_ptr<GPSFamilyProtocol> (*create)() = nullptr;
    GPSSignatureFunction signature = nullptr;
};
 
class GPSDecodeContext
{
public:
    Q_DISABLE_COPY(GPSDecodeContext)
 
    [[nodiscard]] uint64_t nowUs() const;
 
    [[nodiscard]] GPSStreamDemux& stream();
 
    // Events of the current decode, in publication order. Events are never coalesced: every position epoch is its own
    // event, and consumers decide whether to drop superseded ones.
 
    void publishPosition(const GPSDecodedPosition& report)
    {
        _batch.updates |= GPSReceiveUpdate::Position;
        _batch.events.emplace_back(report);
    }
 
    void publishSatellites(const GPSDecodedSatellites& report)
    {
        _batch.updates |= GPSReceiveUpdate::Satellites;
        _batch.events.emplace_back(report);
    }
 
    void publishSatelliteUsage(std::optional<int> count)
    {
        _batch.updates |= GPSReceiveUpdate::Satellites;
        _batch.events.emplace_back(GPSDecodedSatelliteUsage{nowUs(), count});
    }
 
    void publishIntegrity(GPSIntegrityReport& report)
    {
        report.timestampUs = nowUs();
        _batch.events.emplace_back(report);
        _batch.updates |= GPSReceiveUpdate::Activity;
    }
 
    void publishSurvey(GPSSurveyReport& status)
    {
        status.timestampUs = nowUs();
        _batch.events.emplace_back(status);
    }
 
    void publishSurvey(bool active, bool valid, std::chrono::seconds duration,
                       const GPSEllipsoidPosition& position = {})
    {
        GPSSurveyReport status{};
        status.position = position;
        status.duration = duration;
        status.valid = valid;
        status.active = active;
        publishSurvey(status);
    }
 
    void publishRTCM(std::span<const uint8_t> frame)
    {
        _batch.events.emplace_back(GPSRTCMFrame{QByteArrayView(frame).toByteArray()});
        _batch.updates |= GPSReceiveUpdate::Activity;
    }
 
    void publishAsReceived(GPSProtocolEvent event) { _batch.events.push_back(std::move(event)); }
 
    void markUpdates(GPSReceiveUpdates updates) { _batch.updates |= updates; }
 
    [[nodiscard]] bool replyPending() const;
 
    void resolveReply(GPSCommandOutcome outcome);
 
    void offerReply(std::string_view reply);
 
    [[nodiscard]] bool failed() const;
 
    void failControl(const QString& detail);
 
private:
    friend class GPSProtocolRuntime;
 
    explicit GPSDecodeContext(GPSCommandChannel& channel)
        : _channel(channel)
    {}
 
    [[nodiscard]] GPSEventBatch _takeBatch() { return std::exchange(_batch, {}); }
 
    void _recycle(std::vector<GPSProtocolEvent>&& storage)
    {
        storage.clear();
        if (_batch.events.empty() && _batch.events.capacity() < storage.capacity()) {
            _batch.events.swap(storage);
        }
    }
 
    GPSCommandChannel& _channel;
    GPSEventBatch _batch;
};
 
struct GPSNavigationDecode
{
    bool corrections = false;
};
 
class GPSFamilyProtocol
{
public:
    virtual ~GPSFamilyProtocol() = default;
 
    Q_DISABLE_COPY(GPSFamilyProtocol)
 
    
    [[nodiscard]] virtual bool configure(GPSCommandChannel& channel, GPSConfig config, unsigned& baud) = 0;
 
    [[nodiscard]] virtual bool probe(GPSCommandChannel& channel)
    {
        Q_UNUSED(channel)
        return false;
    }
 
    virtual GPSReceiveUpdates onFrame(const GPSFrame& frame, GPSDecodeContext& context) = 0;
 
    virtual void flush(GPSDecodeContext& context) { Q_UNUSED(context) }
 
    [[nodiscard]] virtual bool receiverReady() const { return true; }
 
    [[nodiscard]] virtual QString identity() const { return {}; }
 
    [[nodiscard]] virtual bool armDecodeOnly(const GPSConfig& config, GPSDecodeContext& context)
    {
        Q_UNUSED(config)
        Q_UNUSED(context)
        return false;
    }
 
    [[nodiscard]] virtual bool armNavigationDecode(GPSNavigationDecode decode, GPSDecodeContext& context)
    {
        Q_UNUSED(decode)
        Q_UNUSED(context)
        return false;
    }
 
    virtual GPSReceiveUpdates receive(GPSCommandChannel& channel, std::chrono::milliseconds timeout);
 
    virtual bool completeReceiveCycle(GPSReceiveUpdates handled) { return handled != GPSReceiveUpdates{}; }
 
    [[nodiscard]] virtual std::chrono::milliseconds nextReadSlice(std::chrono::milliseconds timeout) const
    {
        return timeout;
    }
 
    virtual void serviceStreaming(GPSCommandChannel& channel);
 
protected:
    GPSFamilyProtocol() = default;
};
 
[[nodiscard]] inline QString gpsReceiverIdentity(const QByteArray& model, const QByteArray& firmware)
{
    return QString::fromUtf8(model.isEmpty() || firmware.isEmpty() ? model + firmware : model + ' ' + firmware);
}
 
template <typename Protocol>
std::unique_ptr<GPSFamilyProtocol> gpsCreateProtocol()
{
    return std::make_unique<Protocol>();
}