Transfer.h

Go to the documentation of this file.

// The experiment transfer, as the phyphox docs specify it (bluetooth-low-energy.md, "Phyphox
// service"): a header packet `phyphox` + u32 size + u32 CRC-32 (big endian), then the document
// in MTU-sized notifications on cddf0002. Started by the app subscribing to cddf0002 OR by the
// app writing 1 to cddf0003, whichever comes first; a second trigger while a transfer runs is
// ignored; a disconnect aborts.
//
// Flow control (plan §3.4): the transport reports whether the stack accepted a packet. A
// refused packet is re-sent after PHYPHOX_BLE_TRANSFER_RETRY_DELAY_MS, the pause doubling per
// consecutive refusal up to PHYPHOX_BLE_TRANSFER_RETRY_MAX_MS; no retry count and no fixed
// pacing delay anywhere — the Server's stall watchdog is the only thing that abandons a
// transfer.
//
// This class is transport-independent: it only hands out the next packet and takes the
// verdict back. The Server drives it from poll() / the transport's callbacks.
#ifndef PHYPHOX_BLE_CORE_TRANSFER_H
#define PHYPHOX_BLE_CORE_TRANSFER_H
 
#include <stdint.h>
#include "Config.h"
 
namespace phyphox {
 
class ByteSource {
public:
    virtual ~ByteSource() {}
    virtual uint32_t size() const = 0;
    virtual uint32_t crc() const = 0;
    virtual uint32_t read(uint32_t offset, uint8_t* out, uint32_t n) const = 0;
};
 
class BufferSource : public ByteSource {
public:
    void set(const uint8_t* bytes, uint32_t len);
    uint32_t size() const override { return len_; }
    uint32_t crc() const override { return crc_; }
    uint32_t read(uint32_t offset, uint8_t* out, uint32_t n) const override;
private:
    const uint8_t* bytes_ = nullptr;
    uint32_t len_ = 0;
    uint32_t crc_ = 0;
};
 
class TransferSession {
public:
    enum State : uint8_t { IDLE, HEADER, BODY, DONE, ABORTED };
 
    void begin(const ByteSource& source, uint16_t payload);
    void holdUntil(uint32_t untilMs) { retryAt_ = untilMs; }
    void abort() { state_ = ABORTED; }
    void reset() { state_ = IDLE; pending_ = false; }   
    bool active() const { return state_ == HEADER || state_ == BODY; }
    State state() const { return state_; }
 
    uint16_t nextPacket(uint8_t* out, uint32_t nowMs);
    void accepted();
    void refused(uint32_t nowMs);
 
    uint32_t bytesSent() const { return offset_; }
    uint32_t lastProgressMs() const { return lastProgress_; }
    void noteProgress(uint32_t nowMs) { lastProgress_ = nowMs; }
    uint16_t packetsSent() const { return packets_; }
    uint16_t retries() const { return retries_; }
 
private:
    const ByteSource* source_ = nullptr;
    State state_ = IDLE;
    uint16_t payload_ = PHYPHOX_BLE_DEFAULT_MTU;
    uint32_t offset_ = 0;        
    uint16_t lastLen_ = 0;       
    uint16_t packets_ = 0;
    uint16_t retries_ = 0;       
    uint32_t retryAt_ = 0;       
    uint32_t lastProgress_ = 0;
    bool pending_ = false;       
};
 
} // namespace phyphox
 
#endif