MB85RS64V.hpp

/*
 * MB85RS64V.hpp
 *
 * STM32 HAL driver for the Fujitsu (RAMXEED) MB85RS64V 64 Kbit (8 KB) SPI FRAM,
 * as found on Adafruit's SPI Non-Volatile FRAM breakout (product 1897).
 *
 * Written from the MB85RS64V datasheet (DS501-00015-4v0-E): command set, timing
 * and status register. Modeled on the shape of this site's other STM32 HAL
 * drivers (an SPI handle plus a chip-select port and pin passed to the
 * constructor). It is an independent implementation, not a port.
 *
 *  Created on: Oct 3, 2026
 *      Author: johng
 */
 
#ifndef MB85RS64V_MB85RS64V_HPP_
#define MB85RS64V_MB85RS64V_HPP_
 
#include "main.h"
#include <cstddef>
#include <cstdint>
 
class MB85RS64V {
public:
    static constexpr uint16_t SIZE_BYTES = 8192;
 
    static constexpr size_t ID_LENGTH = 4;
 
    static constexpr uint8_t STATUS_WEL  = 0x02;    
    static constexpr uint8_t STATUS_BP0  = 0x04;    
    static constexpr uint8_t STATUS_BP1  = 0x08;    
    static constexpr uint8_t STATUS_WPEN = 0x80;    
 
    enum class BlockProtect : uint8_t {
        None      = 0,  
        UpperQuarter = STATUS_BP0,  
        UpperHalf = STATUS_BP1, 
        All       = STATUS_BP1 | STATUS_BP0 
    };
 
    MB85RS64V(SPI_HandleTypeDef *hspi, GPIO_TypeDef *csPort, uint16_t csPin, uint32_t timeoutMs = 100,
            uint8_t maxAttempts = 3);
 
    bool begin();
 
    bool readId(uint8_t *id);
 
    bool read(uint16_t address, uint8_t *buffer, size_t length);
 
    bool write(uint16_t address, const uint8_t *data, size_t length);
 
    bool writeEnable();
 
    bool writeDisable();
 
    bool readStatus(uint8_t *status);
 
    bool writeStatus(uint8_t status);
 
    bool setBlockProtect(BlockProtect area);
 
    HAL_StatusTypeDef lastStatus() const { return _lastStatus; }
 
private:
    enum : uint8_t {
        OP_WREN  = 0x06,
        OP_WRDI  = 0x04,
        OP_RDSR  = 0x05,
        OP_WRSR  = 0x01,
        OP_READ  = 0x03,
        OP_WRITE = 0x02,
        OP_RDID  = 0x9F
    };
 
    SPI_HandleTypeDef *_spi;
    GPIO_TypeDef *_csPort;
    uint16_t _csPin;
    uint32_t _timeoutMs;
    uint8_t _maxAttempts;
    HAL_StatusTypeDef _lastStatus = HAL_OK;
    bool _lastRetryable = false;
 
    void csLow();
    void csHigh();
    bool spiConfigOk() const;
    bool transmit(const uint8_t *data, uint16_t length);
    bool receive(uint8_t *data, uint16_t length);
    bool sendCommand(uint8_t opcode);
    bool isTransient(HAL_StatusTypeDef status) const;
 
    template <typename Command>
    bool run(Command command) {
        for (uint8_t attempt = 0; attempt < _maxAttempts; attempt++) {
            if (command()) {
                return true;
            }
            csHigh();   // end whatever was in progress before trying the whole command again
            if (!_lastRetryable) {
                break;  // a retry cannot fix this one: fail right away
            }
        }
        Error_Handler();
        return false;
    }
};
 
#endif /* MB85RS64V_MB85RS64V_HPP_ */