cmt2.h

Go to the documentation of this file.

/* +------------------------------------------------------------------------+
   |                     Mobile Robot Programming Toolkit (MRPT)            |
   |                          https://www.mrpt.org/                         |
   |                                                                        |
   | Copyright (c) 2005-2019, Individual contributors, see AUTHORS file     |
   | See: https://www.mrpt.org/Authors - All rights reserved.               |
   | Released under BSD License. See: https://www.mrpt.org/License          |
   +------------------------------------------------------------------------+ */

#ifndef _CMT2_H_2006_04_13
#define _CMT2_H_2006_04_13

#ifndef _CMT_MONOLITHIC
#include "cmt1.h"
#include "cmtmessage.h"
#include "xsens_fifoqueue.h"
#endif

namespace xsens
{
//////////////////////////////////////////////////////////////////////////////////////////
/////////////////////////////////// Support  functions
//////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////////////////

//! Find a valid message in the given buffer. If nothing is found, the function
//! returns -1. Otherwise the index of the first character of the message is
//! returned.
int32_t findValidMessage(const uint8_t* buffer, const uint16_t bufferLength);

//////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////// Cmt2s
////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////////////////
/*! \brief Mid-level serial communication class.

    The class uses CMT level 1, but does not inherit from it. If software needs
   to access
    the level 1 component, it needs to be done through the getCmt1s() function.
*/
class Cmt2s
{
   private:
    //! This object cannot be copied, so this function is not implemented.
    Cmt2s(const Cmt2s& ref);

    /*! \brief The message received function.

        This function is automatically called every time a complete message was
       read from the
        connected COM port.
    */
    CmtCallbackFunction m_onMessageReceived{nullptr};
    //! Custom, user supplied parameter for the OnMessageReceived callback
    //! function, passed as the first argument
    int32_t m_onMessageReceivedInstance;
    //! Custom, user supplied parameter for the OnMessageReceived callback
    //! function, passed as the last argument
    void* m_onMessageReceivedParam;

    /*! \brief The message sent function.

        This function is automatically called every time a complete message was
       sent to the
        connected COM port.
    */
    CmtCallbackFunction m_onMessageSent{nullptr};
    //! Custom, user supplied parameter for the OnMessageSent callback function,
    //! passed as the first argument
    int32_t m_onMessageSentInstance;
    //! Custom, user supplied parameter for the OnMessageSent callback function,
    //! passed as the last argument
    void* m_onMessageSentParam;

   protected:
    //! The baudrate that was last set to be used by the port
    uint32_t m_baudrate;
    //! The CMT level 1 object that this class operates on
    Cmt1s m_cmt1s;
    //! The last result of an operation
    mutable XsensResultValue m_lastResult;
    //! Buffer for reading data until a valid message is read. Should be rarely
    //! used.
    uint8_t m_readBuffer[CMT_DEFAULT_READ_BUFFER_SIZE];
    //! The number of valid bytes in the readBuffer.
    uint16_t m_readBufferCount;
    //! Timeout in ms for blocking operations
    uint32_t m_timeout;
    //! The timestamp at which to end an operation
    uint32_t m_toEnd;

   public:
    //! Default constructor, initialize all members to their default values.
    Cmt2s();

    //! Destructor, de-initialize, free memory allocated for buffers, etc.
    ~Cmt2s();

    //! Close the serial communication port.
    XsensResultValue close(void);

    //! Return the baudrate that is currently being used by the port
    uint32_t getBaudrate(void) { return (m_baudrate = m_cmt1s.getBaudrate()); }
    /*! \brief Return a reference to the embedded Cmt1s object.

        Any manipulation of the object should be done through Cmt2s. Cmt2s
       integrity is
        not guaranteed if the Cmt1s object is manipulated directly.
    */
    Cmt1s* getCmt1s(void) { return &m_cmt1s; }
    //! Return the error code of the last operation.
    XsensResultValue getLastResult(void) const { return m_lastResult; }
    //! Retrieve the port that the object is connected to.
    XsensResultValue getPortNr(uint8_t& port) const;
    XsensResultValue getPortNr(int32_t& port) const;
    XsensResultValue getPortName(char* portname) const;
    //! Return the current timeout value in ms.
    uint32_t getTimeout(void) const { return m_timeout; }
    //! Return whether the communication port is open or not.
    bool isOpen(void) const { return (m_cmt1s.isOpen()); }
    //! Open a communication channel to the given serial port name.
    XsensResultValue open(
        const char* portName, const uint32_t baudRate = CMT_DEFAULT_BAUD_RATE);
#ifdef _WIN32
    //! Open a communication channel to the given COM port number.
    XsensResultValue open(
        const uint32_t portNumber,
        const uint32_t baudRate = CMT_DEFAULT_BAUD_RATE);
#endif
    /*! \brief Read a message from the COM port.

        The function reads data from the embedded Cmt1s object. The data is then
       converted
        into a Message object.
        If an error occurred, a nullptr pointer is returned and the error code
       can be
        retrieved with getLastError().
    */
    XsensResultValue readMessage(Message* rcv);

    //! Set the callback function for when a message has been received or sent
    XsensResultValue setCallbackFunction(
        CmtCallbackSelector tp, int32_t instance, CmtCallbackFunction func,
        void* param);

    /*! \brief Set the default timeout value to use in blocking operations.

        This function sets the level 2 timeout value. The L1 value is set to
       half the given
        timeout value.
    */
    XsensResultValue setTimeout(const uint32_t ms = CMT2_DEFAULT_TIMEOUT);

    /*! \brief Wait for a message to arrive.

        The function waits for a message to arrive or until a timeout occurs.
        If the msgId parameter is set to a value other than 0, the function will
       wait
        until a message has arrived with that particular msgId.

        \note msgId 0 is the ReqDeviceID MID, but that is an outgoing only
       message. It is
        illogical to wait for a message that will never be sent to the host. So
       0 is a
        safe value for the 'all' messages option.

        \note If an error message is received, the contents are stored in the
       m_lastResult
        field and a nullptr value is returned immediately.
    */
    XsensResultValue waitForMessage(
        Message* rcv, const uint8_t msgId, uint32_t timeoutOverride,
        bool acceptErrorMessage);
    /*! \brief Send a message over the COM port.

        The function attempts to write the message over the connected COM port.
        \param msg  The message to send.
    */
    XsensResultValue writeMessage(Message* msg);
};

//////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////// Cmt2f
////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////////////////

/*! \brief The mid-level file communication class.

    The class uses CMT level 1, but does not inherit from it. If software needs
   to access
    the level 1 component, it needs to be done through the getCmt1f() function.
*/
class Cmt2f
{
   private:
    //! This object cannot be copied, so this function is not implemented.
    Cmt2f(const Cmt2f& ref);

   protected:
    //! The Cmt1f object that is used for the low-level operations
    Cmt1f m_cmt1f;
    //! The last result of an operation
    mutable XsensResultValue m_lastResult;

    /** When set to true, the file is read-only and attempts to write to it will
     * fail */
    bool m_readOnly;

   public:
    //! Default constructor
    Cmt2f();
    //! Destructor.
    ~Cmt2f();
    //! Close the file.
    XsensResultValue close(void);
    //! Close the file and delete it.
    XsensResultValue closeAndDelete(void);
    //! Create a new file with level 2 header
    XsensResultValue create(const char* filename);
    //! Create a new file with level 2 header
    XsensResultValue create(const wchar_t* filename);
    //! Get a reference to the embedded Cmt1f object
    Cmt1f* getCmt1f(void);

    //! Return the error code of the last operation.
    XsensResultValue getLastResult(void) const;
    //! Retrieve the filename that was last successfully opened.
    XsensResultValue getName(char* filename) const;
    //! Retrieve the filename that was last successfully opened.
    XsensResultValue getName(wchar_t* filename) const;
    //! Return whether the file is open or not.
    bool isOpen(void) const;
    //! Open a file and read the header
    XsensResultValue open(const char* filename, const bool readOnly = false);
    //! Open a file and read the header
    XsensResultValue open(const wchar_t* filename, const bool readOnly = false);
    //! Read the next message from the file, when msgId is non-zero, the first
    //! matching message will be returned
    XsensResultValue readMessage(Message* msg, const uint8_t msgId = 0);
    //! Get the current file size
    CmtFilePos getFileSize(void);
    //! Get the current read position
    CmtFilePos getReadPosition(void);
    //! Set the read position to the given position
    XsensResultValue setReadPosition(CmtFilePos pos);
    //! Write a message to the end of the file
    XsensResultValue writeMessage(const Message* msg);
};

}  // namespace xsens

#endif  // _CMT2_H_2006_04_13