MLR_Modem.h

//
// MLR_Modem.h
//
// The original program
// (c) 2019 Reimesch Kommunikationssysteme
// Authors: aj, cl
// Created on: 13.03.2019
// Released under the MIT license
//
// (c) 2026 CircuitDesign,Inc.
// Interface driver to Circuit Design SLR/MLR modems.
//
 
#pragma once
#include <Arduino.h>
#include "common/SerialModemBase.h"
 
static constexpr uint32_t MLR_DEFAULT_BAUDRATE = 19200;
 
enum class MLR_Modem_Response
{
    // internal state of modem
    Idle,       
    ParseError, 
    Timeout,    
 
    // serial commands
    ShowMode,           
    SaveValue,          
    Channel,            
    SerialNumber,       
    MLR_Modem_DtIr,     
    DataReceived,       
    RssiLastRx,         
    RssiCurrentChannel, 
    UserID,             
    CarrierSenseRssi,   
    FactoryReset,       
    BaudRate,           
    GenericResponse     
};
 
// Use common ModemError for compatibility
using MLR_Modem_Error = ModemError;
 
enum class MLR_ModemMode : uint8_t
{
    FskBin = 0,  
    FskCmd = 1,  
    LoRaBin = 2, 
    LoRaCmd = 3, 
};
 
enum class MLR_ModemSpreadFactor : uint8_t
{
    Chips128 = 0,  
    Chips256 = 1,  
    Chips512 = 2,  
    Chips1024 = 3, 
    Chips2048 = 4, 
    Chips4096 = 5, 
};
 
enum class MLR_ModemParserState
{
    Start = 0,
 
    ReadCmdFirstLetter,  
    ReadCmdSecondLetter, 
    ReadCmdParam,        
 
    ReadRawString, 
 
    RadioDrSize,    
    RadioDrPayload, 
 
    ReadCmdUntilCR, 
    ReadCmdUntilLF, 
};
 
struct MLR_Modem_Event
{
    MLR_Modem_Error error;   
    MLR_Modem_Response type; 
    int32_t value;           
    const uint8_t *pPayload; 
    uint16_t payloadLen;     
 
    // --- Constructors ---
    // 1. Default
    MLR_Modem_Event() : error(ModemError::Ok), type(MLR_Modem_Response::Idle), value(0), pPayload(nullptr), payloadLen(0) {}
 
    // 2. Helper for simple status events
    MLR_Modem_Event(ModemError err, MLR_Modem_Response t)
        : error(err), type(t), value(0), pPayload(nullptr), payloadLen(0) {}
 
    // 3. Helper for events with a value (RSSI, SN, etc.)
    MLR_Modem_Event(ModemError err, MLR_Modem_Response t, int32_t val)
        : error(err), type(t), value(val), pPayload(nullptr), payloadLen(0) {}
 
    // 4. Helper for data reception
    MLR_Modem_Event(ModemError err, MLR_Modem_Response t, int32_t val, const uint8_t *p, uint16_t l)
        : error(err), type(t), value(val), pPayload(p), payloadLen(l) {}
};
 
typedef void (*MLR_Modem_AsyncCallback)(const MLR_Modem_Event &event);
 
class MLR_Modem : public SerialModemBase
{
public: // methods
    MLR_Modem_Error begin(Stream &pUart, MLR_Modem_AsyncCallback pCallback = nullptr);
 
    MLR_Modem_Error SetChannel(uint8_t channel, bool saveValue);
 
    MLR_Modem_Error GetChannel(uint8_t *pChannel);
 
    MLR_Modem_Error SetMode(MLR_ModemMode mode, bool saveValue);
 
    MLR_Modem_Error GetMode(MLR_ModemMode *pMode);
 
    MLR_Modem_Error SetSpreadFactor(MLR_ModemSpreadFactor sf, bool saveValue);
 
    MLR_Modem_Error GetSpreadFactor(MLR_ModemSpreadFactor *pSf);
 
    MLR_Modem_Error SetEquipmentID(uint8_t ei, bool saveValue);
 
    MLR_Modem_Error GetEquipmentID(uint8_t *pEI);
 
    MLR_Modem_Error SetDestinationID(uint8_t di, bool saveValue);
 
    MLR_Modem_Error GetDestinationID(uint8_t *pDI);
 
    MLR_Modem_Error SetGroupID(uint8_t gi, bool saveValue);
 
    MLR_Modem_Error GetGroupID(uint8_t *pGI);
 
    MLR_Modem_Error GetUserID(uint16_t *pUserID);
 
    MLR_Modem_Error GetRssiLastRx(int16_t *pRssi);
 
    MLR_Modem_Error GetRssiCurrentChannel(int16_t *pRssi);
 
    MLR_Modem_Error SetCarrierSenseRssiOutput(uint8_t ciValue, bool saveValue);
 
    MLR_Modem_Error GetCarrierSenseRssiOutput(uint8_t *pCiValue);
 
    MLR_Modem_Error GetSerialNumber(uint32_t *pSn);
 
    MLR_Modem_Error FactoryReset();
 
    MLR_Modem_Error GetBaudRate(uint8_t *pBaudRate);
 
    MLR_Modem_Error SetBaudRate(uint32_t baudRate, bool saveValue);
 
    MLR_Modem_Error SendRawCommand(const char *command, char *responseBuffer, size_t bufferSize, uint32_t timeoutMs = 500);
 
    MLR_Modem_Error SendRawCommandAsync(const char *command, uint32_t timeoutMs = 500);
 
    MLR_Modem_Error TransmitData(const uint8_t *pMsg, uint8_t len);
 
    MLR_Modem_Error TransmitDataAsync(const uint8_t *pMsg, uint8_t len);
 
    MLR_Modem_Error GetRssiCurrentChannelAsync();
 
    // /**
    //  * \brief Gets the contact function for DIO1..DIO8.
    //  */
    // MLR_Modem_Error GetContactFunction(uint8_t *pContactFunction);
 
    // /**
    //  * \brief Sets the contact function for DIO1..DIO8.
    //  */
    // MLR_Modem_Error SetContactFunction(uint8_t contactFunction, bool saveValue);
 
    MLR_Modem_Error GetSerialNumberAsync();
 
    MLR_Modem_Error GetPacket(const uint8_t **ppData, uint8_t *len);
 
    void SetAsyncCallback(MLR_Modem_AsyncCallback pCallback) { m_pCallback = pCallback; }
 
    bool HasPacket() { return m_drMessagePresent; }
 
    void DeletePacket() { m_drMessagePresent = false; }
 
    MLR_Modem_Error SoftReset();
 
    void Work() { update(); }
 
protected:
    // --- SerialModemBase Virtual Overrides ---
    ModemParseResult parse() override;
    void onRxDataReceived() override;
    void onCommandComplete(ModemError result) override;
    const char *getLogPrefix() const override { return "[MLR"; }
 
private: // methods
    // Internal parser state machine handlers
    ModemParseResult m_HandleReadStart();
    ModemParseResult m_HandleReadCmdFirstLetter();
    ModemParseResult m_HandleReadCmdSecondLetter();
    ModemParseResult m_HandleReadCmdParam();
    ModemParseResult m_HandleRadioDrSize();
    ModemParseResult m_HandleRadioDrPayload();
    ModemParseResult m_HandleReadCmdUntilCR();
    ModemParseResult m_HandleReadCmdUntilLF();
 
    // Internal: Dispatches an event to the async callback
    void dispatchAsyncEvent(ModemError error, MLR_Modem_Response responseType, int32_t value = 0, const uint8_t *pPayload = nullptr, uint16_t len = 0);
 
    // Internal helpers using Base methods
    ModemError m_HandleMessageHexByte(uint8_t *pValue, uint32_t responseLen, const char *responsePrefix);
    ModemError m_HandleMessageHexWord(uint16_t *pValue, uint32_t responseLen, const char *responsePrefix);
 
    ModemError m_HandleMessage_RS(int16_t *pRssi);
    ModemError m_HandleMessage_RA(int16_t *pRssi);
 
    ModemError m_HandleMessage_SN(uint32_t *pSerialNumber);
    // check if the received message is "*IZ=OK"
    ModemError m_HandleMessage_IZ();
 
private: // data
    MLR_Modem_Response m_asyncExpectedResponse; 
    MLR_ModemParserState m_parserState;         
 
    // special receive buffer and data for '@DR' command
    bool m_drMessagePresent;             
    uint8_t m_drMessageLen;              
    uint8_t m_drMessage[300];            
 
    // information response (*IR=...)
    bool m_irMessagePresent;             
    uint8_t m_irValue;                   
 
    MLR_ModemMode m_mode;                
    MLR_Modem_AsyncCallback m_pCallback; 
};