ws2812_stream_decoder.h

Go to the documentation of this file.

 
#pragma once
 
#include "fl/channels/rx.h"
#include "fl/stl/noexcept.h"
#include "fl/stl/result.h"
#include "fl/stl/span.h"
#include "fl/stl/stdint.h"
 
namespace fl {
namespace channels {
namespace rx {

constexpr u32 kFlexPwmGapNs = 5000;

inline u32 flexPwmStaticMidpointNs(const ChipsetTiming4Phase& timing) FL_NO_EXCEPT {
    return (timing.t0h_max_ns + timing.t1h_min_ns) / 2u;
}

inline bool flexPwmIsMidpointSample(u32 high_ns) FL_NO_EXCEPT {
    return high_ns >= 100u && high_ns <= 1500u;
}

inline u32 flexPwmAdaptiveMidpointNs(const ChipsetTiming4Phase& timing,
                                     u32 high_min, u32 high_max,
                                     u32 samples) FL_NO_EXCEPT {
    if (samples >= 16 && high_max > high_min + 200u) {
        return (high_min + high_max) / 2u;
    }
    return flexPwmStaticMidpointNs(timing);
}

inline int flexPwmBitFromMidpoint(u32 high_ns, u32 midpoint_ns) FL_NO_EXCEPT {
    return (high_ns >= midpoint_ns) ? 1 : 0;
}

inline int flexPwmBitFromHigh(u32 high_ns, const ChipsetTiming4Phase& timing) FL_NO_EXCEPT {
    if (high_ns >= timing.t0h_min_ns && high_ns <= timing.t0h_max_ns) {
        return 0;
    }
    if (high_ns >= timing.t1h_min_ns && high_ns <= timing.t1h_max_ns) {
        return 1;
    }
    return -1;
}

inline u32 flexPwmTickDeltaNs(u16 t0, u16 t1, u32 ns_per_tick_q16) FL_NO_EXCEPT {
    const u16 delta = static_cast<u16>(t1 - t0);
    return static_cast<u32>((static_cast<u64>(delta) * ns_per_tick_q16) >> 16);
}

inline u32 flexPwmNsPerTickQ16(u32 counter_hz) FL_NO_EXCEPT {
    return static_cast<u32>((static_cast<u64>(1000000000ULL) << 16) / counter_hz);
}

fl::result<u32, DecodeError>
decodeFlexPwmEdges(const ChipsetTiming4Phase& timing,
                   fl::span<const EdgeTime> edges,
                   fl::span<u8> bytes_out) FL_NO_EXCEPT;

class Ws2812StreamDecoder {
  public:
    static constexpr u32 kCalibrationBits = 64;
    static constexpr u32 kExceptionBandNs = 150;
    static constexpr u32 kMaxExceptions = 32;
 
    struct Stats {
        u32 pairs = 0;             
        u32 bits = 0;              
        u32 errors = 0;            
        u32 fullBytes = 0;         
        u32 calibratedMidpointNs = 0;
        u32 frameMidpointNs = 0;   
        u32 exceptions = 0;        
        u32 exceptionsDropped = 0; 
        bool inexact = false;      
        bool gapBitShift = false;  
        bool overrun = false;      
    };

    void reset(const ChipsetTiming4Phase& stream_timing, u32 ns_per_tick_q16,
               fl::span<u8> out, fl::span<EdgeTime> diag_edges) FL_NO_EXCEPT;

    void push(fl::span<const u16> captures) FL_NO_EXCEPT;

    void markOverrun() FL_NO_EXCEPT { mStats.overrun = true; }

    void flush() FL_NO_EXCEPT;

    void finish(const ChipsetTiming4Phase& timing) FL_NO_EXCEPT;

    fl::result<u32, DecodeError> copyTo(fl::span<u8> out) const FL_NO_EXCEPT;
 
    const Stats& stats() const FL_NO_EXCEPT { return mStats; }
    size_t diagEdgeCount() const FL_NO_EXCEPT { return mDiagCount; }
 
  private:
    enum class Mode : u8 { Midpoint, FromHigh };
    struct Pending {
        u32 high_ns;
        Mode mode;
    };
    struct Exception {
        u32 bit_pos;     // position of the bit (or where it was dropped)
        u32 high_ns;
        Mode mode;
        bool stream_valid;  // FromHigh: classified (not dropped) while streaming
    };
 
    void emitPair(u16 rise, u16 fall, bool has_low, u32 low_ns) FL_NO_EXCEPT;
    void emitEdge(bool high, u32 ns) FL_NO_EXCEPT;
    void pushBit(u32 high_ns, Mode mode) FL_NO_EXCEPT;
    void classify(u32 high_ns, Mode mode) FL_NO_EXCEPT;
    void calibrate() FL_NO_EXCEPT;
    void appendBit(int bit) FL_NO_EXCEPT;
 
    void record(u32 high_ns, Mode mode, bool stream_valid) FL_NO_EXCEPT;
 
    ChipsetTiming4Phase mTiming = {};
    u32 mNsPerTickQ16 = 0;
    fl::span<u8> mOut;
    fl::span<EdgeTime> mDiag;
    size_t mDiagCount = 0;
 
    bool mHavePrev = false;
    bool mStarted = false;
    u16 mPrevRise = 0;
    u16 mPrevFall = 0;
 
    u32 mEdgeIndex = 0;  // index in the equivalent batch edge list
    u32 mHighMin = 0xFFFFFFFFu;
    u32 mHighMax = 0;
    u32 mHighSamples = 0;
 
    bool mCalibrated = false;
    u32 mMidpoint = 0;
    Pending mPending[kCalibrationBits];
    u32 mPendingCount = 0;
 
    Exception mExceptions[kMaxExceptions];
    u32 mExceptionCount = 0;
 
    u8 mCurByte = 0;
    u32 mBitCount = 0;
    u32 mBitPos = 0;  // bits appended so far
    bool mFlushed = false;
    bool mPartialWritten = false;
 
    Stats mStats;
};
 
}  // namespace rx
}  // namespace channels
}  // namespace fl