cmt3.h

Go to the documentation of this file.

/* +------------------------------------------------------------------------+
   |                     Mobile Robot Programming Toolkit (MRPT)            |
   |                          http://www.mrpt.org/                          |
   |                                                                        |
   | Copyright (c) 2005-2018, Individual contributors, see AUTHORS file     |
   | See: http://www.mrpt.org/Authors - All rights reserved.                |
   | Released under BSD License. See details in http://www.mrpt.org/License |
   +------------------------------------------------------------------------+ */
 
#ifndef _CMT3_H_2006_04_14
#define _CMT3_H_2006_04_14
 
#ifndef _CMT_MONOLITHIC
#include "cmt2.h"
#include "cmtpacket.h"
#endif
 
namespace xsens
{
//////////////////////////////////////////////////////////////////////////////////////////
//////////////////////////////////// Support  classes
///////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////////////////
 
//////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////// Cmt3
////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////////////////
 
/*! \brief High-level communication class.
 
        The class uses CMT level 2, but does not inherit from it. If software needs
   to access
        the level 2 components, it needs to be done through the getCmt2s() and
   getCmt2f() functions.
 
        All device identification is done through device Ids in CMT level 3.
*/
class Cmt3
{
        //// data & structures ////
   protected:
        /** The (optional) CMT level 2 serial object that this class operates on. */
        Cmt2s m_serial;
        /** The (optional) CMT level 2 logfile object that this class operates on.
         */
        Cmt2f m_logFile;
        /** ms per sample = 1000 / sample frequency. */
        double m_rtcMsPerSample;
        // double m_sampleFrequency;            //!< The sample frequency of the port,
        // computed from sampling period and output skip factor.
        /** The sample period of the port. */
        uint16_t m_period;
        /** The skip factor of the port. */
        uint16_t m_skip;
        /** The start of the RTC counter, the time of arrival of sample 0. */
        TimeStamp m_rtcStart;
        /** The long sample counter (normal counter wraps at 64k). */
        uint32_t m_rtcCount;
        /** The last received sample counter, used to determine wrap-around. */
        CmtMtTimeStamp m_rtcLastSc;
        /** The baudrate that was last set to be used by the port. */
        uint32_t m_baudrate;
        /** The config mode timeout. */
        uint32_t m_timeoutConf;
        /** The measurement mode timeout. */
        uint32_t m_timeoutMeas;
        /** The last result of an operation. */
        mutable XsensResultValue m_lastResult;
        /** The index of the first formatting item. */
        uint16_t m_firstItem;
        /** The number of times a goto config is attempted before the function
         * fails. */
        uint16_t m_gotoConfigTries;
        /** Keeps track of whether the connected device is measuring or being
         * configured. */
        bool m_measuring;
        /** Automatically scan for device details during open. Default is true
         * (recommended). */
        bool m_detailedScan;
        /** Indicates whether to read from the log file or from the serial port. */
        bool m_readFromFile;
        /** Indicates if the rtc is initialised or not. */
        bool m_rtcInitialized;
        /** Indicates whether to write all received messages to the logfile or not,
         * automatically set to true by createLogFile. */
        bool m_logging;
        /** Contains the last error reported by hardware. */
        XsensResultValue m_lastHwError;
        /** Contains the Device ID of the device that caused the last hardware
         * error. */
        CmtDeviceId m_lastHwErrorDeviceId;
 
   public:
        /** Indicates if the RTC should be computed or not (to save CPU time). */
        bool m_useRtc;
        /** Cached eMTS data. */
        void* m_eMtsData[CMT_MAX_DEVICES_PER_PORT];
 
   protected:
        /** The configuration of the connected devices. */
        CmtDeviceConfiguration m_config;
 
        //// functions
        //////////////////////////////////////////////////////////////////////////////////////
   protected:
        /** This object cannot be copied, so this function is not implemented. */
        Cmt3(const Cmt3& ref);
        /** Internal function to compute the RTC value. */
        void fillRtc(Packet* pack);
        /** \brief Find a device Id in the list and return its busId. \details
         * CmtDeviceId 0= busId 0= broadcast. A CMT_BID_INVALID value is also
         * possible and indicates that the devId was not found. */
        uint8_t getBusIdInternal(const CmtDeviceId devId) const;
 
   public:
        /** Default constructor, initializes all members to their default values. */
        Cmt3();
        /** Destructor, de-initializes, frees memory allocated for buffers, etc. */
        ~Cmt3();
 
        /** \brief Close the communication port. \details This function places the
         * device in configuration mode and closes the communication port, ending
         * all further communication with the device. */
        XsensResultValue closePort(bool gotoConfigFirst = true);
        /** \brief Get an Xbus Master's battery level. \details The battery level is
         * a value between 0 and 255 that indicates the voltage of the batteries.
         * The scale is not linear and the values should not be used as an absolute
         * voltage. The amount of time remaining for measurement given any battery
         * level greatly depends on the type of batteries used, the number of
         * sensors attached to the Xbus Master and the used output options. */
        XsensResultValue getBatteryLevel(uint8_t& level);
        /** \brief Get the baudrate used by a port. \details This function returns
         * the baud rate at which the port is currently connected. The function will
         * return an error when no port is connected. \see getSerialBaudrate
         * setSerialBaudrate setBaudrate */
        XsensResultValue getBaudrate(uint32_t& baudrate);
        /** \brief Get the state of the bluetooth communication. \details This
         * function tells whether the Bluetooth connection of the Xbus Master is on
         * (1) or off (0). \note This function is only valid in configuration mode.
         */
        XsensResultValue getBluetoothState(bool& enabled);
        /** \brief Retrieve the BusId of a device. \details The function checks its
         * internal list for a match of deviceId. If it is found, the corresponding
         * BusId is returned in busId. Otherwise, a 0 is placed in busId and
         * XRV_NOTFOUND result is returned. */
        XsensResultValue getBusId(
                uint8_t& busId, const CmtDeviceId deviceId = CMT_DID_MASTER) const;
        /** \brief Get the state of the Xbus power. \details This function tells
         * whether the Xbus of the connected Xbus Master is currently switched on
         * (1) or not (0). When it is switched off, the attached MT devices have no
         * power and communication with them is not possible. Before going to
         * measurement mode, use setBusPowerState to restore power. \see
         * setBusPowerState \note This function is only valid in configuration mode.
         */
        XsensResultValue getBusPowerState(bool& enabled);
 
        /** \brief Return a reference to the embedded Cmt2f (logfile) object.
         * \details Any manipulation of the object should be done through Cmt3.
         * Cmt3's integrity is not guaranteed if the Cmt2f object is manipulated
         * directly. \see refreshCache */
        Cmt2f* getCmt2f(void);
        /** \brief Return a reference to the embedded Cmt2s (comm port) object.
         * \details Any manipulation of the object should be done through Cmt3.
         * Cmt3's integrity is not guaranteed if the Cmt2s object is manipulated
         * directly. \see refreshCache */
        Cmt2s* getCmt2s(void);
 
        /** \brief Get device configuration. \details This function retrieves the
         * complete device configuration of a single device. \note This information
         * is cached by Cmt3, so it is available in measurement mode. */
        XsensResultValue getConfiguration(CmtDeviceConfiguration& configuration);
        /** \brief Retrieve data size. \details This function retrieves the number
         * of bytes that are in a data message as sent by the given device. */
        XsensResultValue getDataLength(
                uint32_t& length, const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Retrieve total device count. \details This function retrieves the
         * total number of connected (master + slave) devices or 0 if not connected.
         */
        uint32_t getDeviceCount(void) const;
        /** \brief Retrieve the DeviceId of a device given its Bus ID. \details This
         * function retrieves the DeviceId for the device with the given Bus ID.
         * When no devices are connected, a 0 ID is supplied. */
        XsensResultValue getDeviceId(
                const uint8_t busId, CmtDeviceId& deviceId) const;
        /** \brief Return device mode. \details This function retrieves the
         * output-related settings of the device, such as the sample rate and output
         * settings. \see setDeviceMode \note This function actually reads the
         * device mode from the cached configuration, so it is available in
         * measurement mode. \see refreshCache */
        XsensResultValue getDeviceMode(
                CmtDeviceMode& mode, const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Return device mode2. \details This function retrieves the
         * output-related settings of the device, such as the period, skip factor
         * and output settings. \see setDeviceMode \note This function actually
         * reads the device mode from the cached configuration, so it is available
         * in measurement mode. \see refreshCache */
        XsensResultValue getDeviceMode2(
                CmtDeviceMode2& mode, const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Retrieve the eMts data of the specified sensor(s). \details This
         * function can be used to read proprietary data from one or more Motion
         * Trackers. This data is required by higher level functions in combination
         * with Configuration data to convert Raw data into Calibrated and
         * Orientation data. The eMTs data is quite large, but it is cached. The
         * first request should be done in configuration mode, but following
         * requests can be done in measurement mode. When requesting eMTS data for a
         * single sensor, the buffer should be at least CMT_EMTS_SIZE bytes long.
         * When using CMT_DID_BROADCAST, the eMTS data of all connected sensors is
         * placed into the buffer sequentially. In the latter case, the buffer
         * should be able to hold at least sensorcount * CMT_EMTS_SIZE bytes. */
        XsensResultValue getEMtsData(
                void* buffer, const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Return the error mode of the device. \details This function
         * returns the error mode of the device. The error mode determines how the
         * device handles errors. See the low-level communication documentation for
         * more details. \see setErrorMode \note This function is only valid in
         * configuration mode. */
        XsensResultValue getErrorMode(
                uint16_t& mode, const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Return Firmware revision. \details This function retrieves the
         * firmware version that is currently installed in the device. \note This
         * function is only valid in configuration mode. */
        XsensResultValue getFirmwareRevision(
                CmtVersion& revision, const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Return the heading offset. \details This function retrieves the
         * heading offset in radians used by the device. The valid range is -pi to
         * +pi. The heading offset is used as a final correction on the output
         * orientation. \see setHeading getMagneticDeclination
         * setMagneticDeclination \note This function is only valid in configuration
         * mode. */
        XsensResultValue getHeading(
                double& heading, const CmtDeviceId deviceId = CMT_DID_MASTER);
 
        /** \brief Return the error code of the last user function call. */
        XsensResultValue getLastResult(void) const { return m_lastResult; }
        /** \brief Return the last Hardware error code. \details This function
         * returns the XsensResultValue of the last problem reported by hardware (if
         * any). Hardware problems are all 'error' messages returned by a sensor.
         * \param did If any problems were found, the responsible device ID will be
         * returned in this parameter. \see clearHwError */
        XsensResultValue getHwError(CmtDeviceId& did) const
        {
                did = m_lastHwErrorDeviceId;
                return m_lastHwError;
        }
        /** \brief Reset the hardware error code. \details Use this function to
         * reset the hardware error code reported by getHwError. \see getHwError */
        void clearHwError(void)
        {
                m_lastHwErrorDeviceId = 0;
                m_lastHwError = XRV_OK;
        }
 
        /** \brief Return the location ID of a sensor. \details This function
         * retrieves the location ID stored in the device. \see setLocationId \note
         * This function is only valid in configuration mode. */
        XsensResultValue getLocationId(
                uint16_t& locationId, const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Retrieve the read position of the log file. \details This
         * function will return the current read position in the open log file in
         * bytes from the start. \note The read and write positions of log files are
         * completely independent of each other. \remarks To change the read
         * position, either use resetLogFileReadPos or manipulate the log file
         * through getCmt2f. \see resetLogFileReadPos getCmt2f */
        XsensResultValue getLogFileReadPosition(CmtFilePos& pos);
 
        /** \brief Retrieve the size of the open log file in bytes. */
        XsensResultValue getLogFileSize(CmtFilePos& size);
        /** \brief Retrieve the name of the open log file or an empty string if no
         * logfile is open */
        XsensResultValue getLogFileName(char* filename);
        /** \brief Retrieve the name of the open log file or an empty string if no
         * logfile is open */
        XsensResultValue getLogFileName(wchar_t* filename);
        /** \brief Return the stored magnetic declination. \details This function
         * retrieves the stored local magnetic declination in radians. The valid
         * range is -pi to +pi. The magnetic declination is used in the sensor
         * fusion process to determine the output orientation. \see getHeading
         * setHeading setMagneticDeclination \note This function is only valid in
         * configuration mode. */
        XsensResultValue getMagneticDeclination(
                double& declination, const CmtDeviceId deviceId = CMT_DID_MASTER);
        CmtDeviceId getMasterId(void);  //! \brief Return the device Id of the first
        //! device (master). \details \note The
        //! deviceId is read from the cached
        //! configuration data, so it is also
        //! available in measurement mode.
 
        /** \brief Retrieve number of MT devices. \details This function will return
         * the number of connected MT devices. Effectively, this returns the device
         * count minus any Xbus Masters. */
        uint16_t getMtCount(void) const;
        XsensResultValue getMtDeviceId(const uint8_t index, CmtDeviceId& deviceId)
                const;  //! \brief Return the device Id of an MT device. \details This
        //! function returns the ID of the index'th MT (non-Xbus Master)
        //! device connected to this object. \note The deviceId is read
        //! from the cached configuration data, so it is also available
        //! in measurement mode.
        /** \brief Return the port number that this object is connected to. \details
         * If CMT is reading from a log file, an error will be returned. */
        XsensResultValue getPortNr(uint8_t& port) const;
        /** \brief Return product code. \details This function retrieves the product
         * code of the given device. \param productCode The buffer that will store
         * the product code. This buffer should be at least 20 bytes. \remarks The
         * product code is NOT necessarily NULL-terminated. If it is less than 20
         * characters it will be, but if the product code is 20 characters it won't
         * be. The recommended method is to create a buffer that is 21 bytes long
         * and set the last byte to 0 before calling this function. \note This
         * function is only valid in configuration mode. */
        XsensResultValue getProductCode(
                char* productCode, const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Return current sample frequency. \details This function
         * determines the sample frequency of the device from the cached sample rate
         * and skip factor and returns it. For devices connected to an Xbus Master,
         * the values used by the Xbus Master are returned. \see setDeviceMode
         * getDeviceMode */
        uint16_t getSampleFrequency(void);
        /** \brief Return the baud rate used for serial communication. \details This
         * function retrieves the baud rate that is used when the device is
         * connected by a serial connection. In most cases this is the same as
         * getBaudrate, but when an Xbus Master is connected by a Bluetooth
         * connection, it doesn't have to be. \see setSerialBaudrate setBaudrate
         * getBaudrate \note This function is only valid in configuration mode. */
        XsensResultValue getSerialBaudrate(uint32_t& baudrate);
        /** \brief Retrieve the inbound synchronization settings of the master MT
         * device. \details This function retrieves the current inbound
         * synchronization settings of the master MT device (sync mode, skip factor
         * and offset). This function does not work for Xbus Masters and should not
         * be used for sensors connected to an Xbus Master. \see setSyncInSettings
         * getSyncOutSettings setSyncOutSettings getSyncMode setSyncMode \note This
         * function is only valid in configuration mode. */
        XsensResultValue getSyncInSettings(CmtSyncInSettings& settings);
        /** \brief Retrieve the inbound synchronization mode of an MT device.
         * \details This function retrieves the current inbound synchronization mode
         * of the MT device. This function does not work for Xbus Masters and should
         * not be used for sensors connected to an Xbus Master. \see setSyncInMode
         * setSyncInSettings getSyncInSettings getSyncInSkipFactor
         * setSyncInSkipFactor getSyncInOffset setSyncInOffset getSyncOutSettings
         * setSyncOutSettings getSyncMode setSyncMode */
        XsensResultValue getSyncInMode(uint16_t& mode);
        /** \brief Retrieve the inbound synchronization skip factor of an MT device.
         * \details This function retrieves the current inbound synchronization skip
         * factor of the MT device. This function does not work for Xbus Masters and
         * should not be used for sensors connected to an Xbus Master. \see
         * setSyncInSkipFactor setSyncInSettings getSyncInSettings getSyncInOffset
         * setSyncInOffset getSyncOutSettings setSyncOutSettings getSyncMode
         * setSyncMode */
        XsensResultValue getSyncInSkipFactor(uint16_t& skipFactor);
        /** \brief Retrieve the inbound synchronization offset of an MT device.
         * \details This function retrieves the current inbound synchronization
         * offset of the MT device. This function does not work for Xbus Masters and
         * should not be used for sensors connected to an Xbus Master. \see
         * setSyncInOffset setSyncInSettings getSyncInSettings getSyncInSkipFactor
         * setSyncInSkipFactor getSyncOutSettings setSyncOutSettings getSyncMode
         * setSyncMode */
        XsensResultValue getSyncInOffset(uint32_t& offset);
        /** \brief Retrieve the sync mode of the Xbus Master. \details This function
         * requests the current synchronization mode used by the specified Xbus
         * Master. This function is not valid for MT devices. \see setSyncMode
         * getSyncInSettings setSyncInSettings getSyncOutSettings setSyncOutSettings
         * \note This function is only valid in configuration mode. */
        XsensResultValue getSyncMode(uint8_t& mode);
        /** \brief Retrieve the outbound synchronization settings of the master MT
         * device. \details This function retrieves the current outbound
         * synchronization settings of the MT device (sync mode, skip factor, offset
         * and pulse width). This function does not work for Xbus Masters and should
         * not be used for sensors connected to an Xbus Master. \see
         * setSyncOutSettings getSyncInSettings setSyncInSettings getSyncMode
         * setSyncMode \note This function is only valid in configuration mode. */
        XsensResultValue getSyncOutSettings(CmtSyncOutSettings& settings);
        /** \brief Retrieve the outbound synchronization mode of an MT device.
         * \details This function retrieves the current outbound synchronization
         * mode of the MT device. This function does not work for Xbus Masters and
         * should not be used for sensors connected to an Xbus Master. \see
         * setSyncOutMode setSyncOutSettings getSyncOutSettings getSyncOutPulseWidth
         * setSyncOutPulseWidth getSyncOutSkipFactor setSyncOutSkipFactor
         * getSyncOutOffset setSyncOutOffset getSyncInSettings setSyncInSettings
         * getSyncMode setSyncMode */
        XsensResultValue getSyncOutMode(uint16_t& mode);
        /** \brief Retrieve the outbound synchronization pulse width of an MT
         * device. \details This function retrieves the current outbound
         * synchronization pulse width of the MT device. This function does not work
         * for Xbus Masters and should not be used for sensors connected to an Xbus
         * Master. \see setSyncOutPulseWidth setSyncOutSettings getSyncOutSettings
         * setSyncOutMode getSyncOutMode getSyncOutSkipFactor setSyncOutSkipFactor
         * getSyncOutOffset setSyncOutOffset getSyncInSettings setSyncInSettings
         * getSyncMode setSyncMode */
        XsensResultValue getSyncOutPulseWidth(uint32_t& pulseWidth);
        /** \brief Retrieve the outbound synchronization skip factor of an MT
         * device. \details This function retrieves the current outbound
         * synchronization skip factor of the MT device. This function does not work
         * for Xbus Masters and should not be used for sensors connected to an Xbus
         * Master. \see stSyncOutSkipFactor setSyncOutSettings getSyncOutSettings
         * setSyncOutMode getSyncOutMode getSyncOutPulseWidth setSyncOutPulseWidth
         * getSyncOutOffset setSyncOutOffset getSyncInSettings setSyncInSettings
         * getSyncMode setSyncMode */
        XsensResultValue getSyncOutSkipFactor(uint16_t& skipFactor);
        /** \brief Retrieve the outbound synchronization offset of an MT device.
         * \details This function retrieves the current outbound synchronization
         * offset of the MT device. This function does not work for Xbus Masters and
         * should not be used for sensors connected to an Xbus Master. \see
         * setSyncOutOffset setSyncOutSettings getSyncOutSettings setSyncOutMode
         * getSyncOutMode getSyncOutPulseWidth setSyncOutPulseWidth
         * getSyncOutSkipFactor setSyncOutSkipFactor getSyncInSettings
         * setSyncInSettings getSyncMode setSyncMode */
        XsensResultValue getSyncOutOffset(uint32_t& offset);
        /** \brief Return the configuration mode timeout. \details When in config
         * mode, the system uses a different message timeout than in measurement
         * mode, since configuration messages can take longer to process than
         * measurement mode messages. This function can be used to determine the
         * current config mode timeout in ms. \see setTimeoutConfig
         * getTimeoutMeasurement setTimeoutMeasurement */
        uint32_t getTimeoutConfig(void) const;
        /** \brief Return the measurement mode timeout. \details When in measurement
         * mode, the system uses a different message timeout than in config mode,
         * since measurement mode messages should be faster to process than config
         * mode messages. This function can be used to determine the current
         * measurement mode timeout in ms. \see setTimeoutMeasurement
         * getTimeoutConfig setTimeoutConfig */
        uint32_t getTimeoutMeasurement(void) const;
        /** \brief Return the UTC time of the last received sample. \details This
         * function is only valid for MTi-G sensors. In measurement mode it will
         * retrieve the UTC time of the last received sample. In Config mode, it
         * will retrieve the most recent UTC time. In config mode, the time returned
         * will be requested diectly from the GPS subsystem, with several layers of
         * messaging between the original source and the host. In measurement mode,
         * the UTC time is requested from the GPS subsystem periodically and
         * estimated (with a very high precision) for the remaining samples. So in
         * config mode, the time will probably jitter more than in measurement mode.
         */
        XsensResultValue getUtcTime(CmtUtcTime& utc, const CmtDeviceId deviceId);
        /** \brief Return the dual-output mode of the XM. \details This function
         * retrieves the dual mode output mode of the Xbus Master. The dual output
         * mode of the Xbus Master defines whether it will send data on the serial
         * connection (at the same baud rate as the bluetooth connection) when it is
         * connected via Bluetooth. When set to 0, the serial communication is
         * disabled, data is sent over the serial bus. \note When dual-mode is
         * enabled, the Xbus Master will NOT receive command messages on the serial
         * bus. \see setXmOutputMode */
        XsensResultValue getXmOutputMode(uint8_t& mode);
        /** \brief Place all connected devices into Configuration Mode. \details
         * This function places the sensors in configuration mode. \note This
         * function has no effect when reading from a log file */
        XsensResultValue gotoConfig(void);
        /** \brief Place all connected devices into Measurement Mode. \details This
         * function places the sensors in measurement mode. \note This function has
         * no effect when reading from a log file */
        XsensResultValue gotoMeasurement(void);
        /** \brief Perform an initBus request. \details See the low-level
         * documentation for more information on the InitBus message. \see
         * refreshCache setBusPowerState */
        XsensResultValue initBus(void);
        /** \brief Return whether the Cmt3 object is writing to a log file or not */
        bool isLogging(void) const { return m_logging; }
        /** \brief Return whether the communication port is open or not. */
        bool isPortOpen(void) const { return (m_serial.isOpen()); }
        /** \brief Return whether the main device is an Xbus Master or not. */
        bool isXm(void) const;
 
        XsensResultValue openPort(
                const char* portName,
                const uint32_t baudRate =
                        CMT_DEFAULT_BAUD_RATE);  //! \brief Open a communication channel to
//! the given COM port number. \details
//! This function is first passed through
//! to the Cmt2s object. Then, the device
//! settings are retrieved and stored
//! locally. This function automatically
//! places the device(s) in config mode,
//! using gotoConfig. \see gotoConfig
//! closePort
#ifdef _WIN32
        XsensResultValue openPort(
                const uint32_t portNumber,
                const uint32_t baudRate =
                        CMT_DEFAULT_BAUD_RATE);  //! \brief Open a communication channel to
//! the given COM port number. \details
//! This function is first passed through
//! to the Cmt2s object. Then, the device
//! settings are retrieved and stored
//! locally. This function automatically
//! places the device(s) in config mode,
//! using gotoConfig. \see gotoConfig
//! closePort
#endif
        /** \brief Peek(take a look) at the message ID of the next message. \details
         * This function can only be used when reading from a log file. It will find
         * the next message in the file and place its message ID in the messageId
         * parameter. Afterwards, the read position of the file will be restored.
         * \remarks This function is mostly useful when dealing with a file that has
         * more than just data messages. By using the peek function, it is possible
         * to decide whether a readDataPacket should be called or for example
         * getBatteryLevel or getGpsStatus. When the peek function is not used and
         * for example getBatteryLevel is called, all messages between the current
         * read position and the first battery level message in the file will be
         * skipped. An alternative would be to get the read position, call the
         * desired function (get battery level) and restore the read position, but
         * then the moment at which the (battery level, UTC time, satellite info,
         * etc) data becomes available will not be known. */
        XsensResultValue peekLogMessageId(uint8_t& messageId);
        /** \brief Retrieve a data message. \details This function will attempt to
         * read a data message from the open port or from the log file, depending on
         * the system state. When acceptOther is set to true, the first received
         * message will be returned. If a data message is successfully read, XRV_OK
         * will be returned. If another message is read, XRV_OTHER will be returned
         * and the received message will be placed in the Packet. Otherwise, an
         * appropriate error will be returned. */
        XsensResultValue readDataPacket(Packet* pack, bool acceptOther = false);
        XsensResultValue requestData(Packet* pack);  //!\brief Request a data
        //! message and wait for it to
        //! arrive. \details This
        //! function is only useful when
        //! the skip factor is set to
        //! 0xFFFF.
        /** \brief Reset all connected sensors. */
        XsensResultValue reset(void);
        /** \brief Perform an orientation reset on a device. \details This function
         * performs an orientation reset. See the MT documentation for more
         * information about Orientation resets. \note If you wish to save the
         * setting to the device, perform the CMT_RESETORIENTATION_STORE operation
         * while in Config mode after having performed the appropriate orientation
         * reset in measurement mode. */
        XsensResultValue resetOrientation(
                const CmtResetMethod method,
                const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Restore the device to factory default settings. \details This
         * function completely restores the selected device to the default settings
         * (115k2 baud rate, 100Hz sample frequency, factory defined scenarios).
         * \note This function is only available in configuration mode. */
        XsensResultValue restoreFactoryDefaults(
                const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Set the baudrate and possibly reconnect. \details Use this
         * function to change the baudrate of the device. This actually tries to
         * change the baud rate of the current connection. When reconnect is set to
         * true, the device receives a Reset message and the port is reopened at the
         * new baudrate. Otherwise, make sure to perform a Reset manually, since the
         * new baudrate will not be set until a Reset has been performed. \note To
         * change the baudrate of the serial connection while connected via
         * Bluetooth, use setSerialBaudrate. \see getBaudrate setSerialBaudrate
         * getSerialBaudrate \note This function is only available in configuration
         * mode. */
        XsensResultValue setBaudrate(
                const uint32_t baudrate, bool reconnect = true);
        /** \brief Set the Bluetooth state of the Xbus Master. \details This
         * function sets the state of the bluetooth communication to on or off.
         * \note This function is only available in configuration mode. */
        XsensResultValue setBluetoothState(const bool enabled);
        /** \brief Switch the Xbus Master bus power on or off. \details Use this
         * function to switch the Xbus Master Xbus power on or off. \remarks This
         * function can be used to save a lot of power when not measuring, while
         * still keeping a connection to the system. However, there is a relatively
         * long startup time when restoring power as the sensors are reinitialized.
         * \note You will need to perform an initBus and possibly a refreshCache
         * call after switching the power back on with this function. \note This
         * function is only available in configuration mode. \see initBus
         * refreshCache */
        XsensResultValue setBusPowerState(const bool enabled);
        /** \brief Set the complete output mode of a device. \details This function
         * updates the complete output mode of the specified device. It only updates
         * values that are different than those reported by the device unless force
         * is set to true. The function will automatically update only the part of
         * the device mode that is relevant for the device. So it is possible to
         * configure all devices, including an Xbus Master with the same mode (only
         * the Xbus Master will update its period, while the Motion Trackers will
         * update their output mode and settings). \note This function is only
         * available in configuration mode. \see getDeviceMode getDeviceMode2
         * setDeviceMode2 */
        XsensResultValue setDeviceMode(
                const CmtDeviceMode& mode, bool force,
                const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Set the complete output mode2 of a device. \details This function
         * updates the complete output mode of the specified device. It only updates
         * values that are different than those reported by the device unless force
         * is set to true. The function will automatically update only the part of
         * the device mode that is relevant for the device. So it is possible to
         * configure all devices, including an Xbus Master with the same mode (only
         * the Xbus Master will update its period, while the Motion Trackers will
         * update their output mode and settings). \note This function is only
         * available in configuration mode. \see getDeviceMode2 getDeviceMode
         * setDeviceMode */
        XsensResultValue setDeviceMode2(
                const CmtDeviceMode2& mode, bool force,
                const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Set the error mode of the device. \details This function sets the
         * error mode of the device. The error mode determines how the device
         * handles errors. See the low-level communication documentation for more
         * details. \note This function is only available in configuration mode.
         * \see getErrorMode */
        XsensResultValue setErrorMode(const uint16_t mode);
        /** \brief Set the number of times the gotoConfig function will attempt a
         * gotoConfig before failing. \details This is especially useful when using
         * RS485 communication or when for some reason the communication lines are
         * not reliable. */
        XsensResultValue setGotoConfigTries(const uint16_t tries);
        /** \brief Set the heading offset. \details This function sets the heading
         * offset in radians used by the device. The valid range is -pi to +pi. The
         * heading offset is used as a final correction on the output orientation.
         * \note This function is only available in configuration mode. \see
         * getHeading getMagneticDeclination setMagneticDeclination */
        XsensResultValue setHeading(
                const double heading, const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Set the location ID of a sensor. \details This function sets the
         * location ID stored in the device. \note This function is only available
         * in configuration mode. \see getLocationId */
        XsensResultValue setLocationId(
                uint16_t locationId, const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Set the stored magnetic declination. \details This function sets
         * the stored local magnetic declination in radians. The valid range is -pi
         * to +pi. The magnetic declination is used in the sensor fusion process to
         * determine the output orientation. \note This function is only available
         * in configuration mode. \see getHeading setHeading getMagneticDeclination
         */
        XsensResultValue setMagneticDeclination(
                const double declination, const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Set the inbound synchronization settings of an MT device.
         * \details This function sets the current inbound synchronization settings
         * of the MT device (sync mode, skip factor and offset). This function does
         * not work for Xbus Masters and should not be used for sensors connected to
         * an Xbus Master. \note This function is only available in configuration
         * mode. \see getSyncInSettings getSyncOutSettings setSyncOutSettings
         * getSyncMode setSyncMode */
        XsensResultValue setSyncInSettings(const CmtSyncInSettings& settings);
        /** \brief Set the inbound synchronization mode of an MT device. \details
         * This function sets the current inbound synchronization mode of the MT
         * device. This function does not work for Xbus Masters and should not be
         * used for sensors connected to an Xbus Master. \see getSyncInMode
         * setSyncInSettings getSyncInSettings getSyncInSkipFactor
         * setSyncInSkipFactor getSyncInOffset setSyncInOffset getSyncOutSettings
         * setSyncOutSettings getSyncMode setSyncMode */
        XsensResultValue setSyncInMode(const uint16_t mode);
        /** \brief Set the inbound synchronization skip factor of an MT device.
         * \details This function sets the current inbound synchronization skip
         * factor of the MT device. This function does not work for Xbus Masters and
         * should not be used for sensors connected to an Xbus Master. \see
         * getSyncInSkipFactor setSyncInSettings getSyncInSettings getSyncInOffset
         * setSyncInOffset getSyncOutSettings setSyncOutSettings getSyncMode
         * setSyncMode */
        XsensResultValue setSyncInSkipFactor(const uint16_t skipFactor);
        /** \brief Set the inbound synchronization offset of an MT device. \details
         * This function sets the current inbound synchronization offset of the MT
         * device. This function does not work for Xbus Masters and should not be
         * used for sensors connected to an Xbus Master. \see getSyncInOffset
         * setSyncInSettings getSyncInSettings getSyncInSkipFactor
         * setSyncInSkipFactor getSyncOutSettings setSyncOutSettings getSyncMode
         * setSyncMode */
        XsensResultValue setSyncInOffset(const uint32_t offset);
        /** \brief Set the sync mode of the Xbus Master. \details This function sets
         * the current synchronization mode used by the specified Xbus Master. This
         * function is not valid for MT devices. \note This function is only
         * available in configuration mode. \see getSyncMode getSyncInSettings
         * setSyncInSettings getSyncOutSettings setSyncOutSettings */
        XsensResultValue setSyncMode(const uint8_t mode);
        /** \brief Set the outbound synchronization settings of an MT device.
         * \details This function sets the current outbound synchronization settings
         * of the MT device (sync mode, skip factor, offset and pulse width). This
         * function does not work for Xbus Masters and should not be used for
         * sensors connected to an Xbus Master. \note This function is only
         * available in configuration mode. \see setSyncOutSettings
         * getSyncInSettings setSyncInSettings getSyncMode setSyncMode */
        XsensResultValue setSyncOutSettings(const CmtSyncOutSettings& settings);
        /** \brief Set the outbound synchronization mode of an MT device. \details
         * This function sets the current outbound synchronization mode of the MT
         * device. This function does not work for Xbus Masters and should not be
         * used for sensors connected to an Xbus Master. \see getSyncOutMode
         * setSyncOutSettings getSyncOutSettings getSyncOutPulseWidth
         * setSyncOutPulseWidth getSyncOutSkipFactor setSyncOutSkipFactor
         * getSyncOutOffset setSyncOutOffset getSyncInSettings setSyncInSettings
         * getSyncMode setSyncMode */
        XsensResultValue setSyncOutMode(const uint16_t mode);
        /** \brief Set the outbound synchronization pulse width of an MT device.
         * \details This function sets the current outbound synchronization pulse
         * width of the MT device. This function does not work for Xbus Masters and
         * should not be used for sensors connected to an Xbus Master. \see
         * getSyncOutPulseWidth setSyncOutSettings getSyncOutSettings setSyncOutMode
         * getSyncOutMode getSyncOutSkipFactor setSyncOutSkipFactor getSyncOutOffset
         * setSyncOutOffset getSyncInSettings setSyncInSettings getSyncMode
         * setSyncMode */
        XsensResultValue setSyncOutPulseWidth(const uint32_t pulseWidth);
        /** \brief Set the outbound synchronization skip factor of an MT device.
         * \details This function sets the current outbound synchronization skip
         * factor of the MT device. This function does not work for Xbus Masters and
         * should not be used for sensors connected to an Xbus Master. \see
         * setSyncOutSkipFactor setSyncOutSettings getSyncOutSettings setSyncOutMode
         * getSyncOutMode getSyncOutPulseWidth setSyncOutPulseWidth getSyncOutOffset
         * setSyncOutOffset getSyncInSettings setSyncInSettings getSyncMode
         * setSyncMode */
        XsensResultValue setSyncOutSkipFactor(const uint16_t skipFactor);
        /** \brief Set the outbound synchronization offset of an MT device. \details
         * This function sets the current outbound synchronization offset of the MT
         * device. This function does not work for Xbus Masters and should not be
         * used for sensors connected to an Xbus Master. \see getSyncOutOffset
         * setSyncOutSettings getSyncOutSettings setSyncOutMode getSyncOutMode
         * getSyncOutPulseWidth setSyncOutPulseWidth getSyncOutSkipFactor
         * setSyncOutSkipFactor getSyncInSettings setSyncInSettings getSyncMode
         * setSyncMode */
        XsensResultValue setSyncOutOffset(const uint32_t offset);
        /** \brief Set the default timeout value to use in blocking operations on
         * the communication port. */
        XsensResultValue setTimeout(const uint32_t ms)
        {
                return (m_lastResult = m_serial.setTimeout(ms));
        }
        /** \brief Set the configuration mode timeout. \details When in config mode,
         * the system uses a different message timeout than in measurement mode,
         * since configuration messages can take longer to process than measurement
         * mode messages. This function can be used to set the config mode timeout
         * in ms. \note This function is only available in configuration mode. \see
         * getTimeoutConfig getTimeoutMeasurement setTimeoutMeasurement setTimeout
         */
        XsensResultValue setTimeoutConfig(
                const uint32_t timeout = CMT3_DEFAULT_TIMEOUT_CONF);
        /** \brief Set the measurement mode timeout. \details When in measurement
         * mode, the system uses a different message timeout than in config mode,
         * since measurement mode messages should be faster to process than config
         * mode messages. This function can be used to set the measurement mode
         * timeout in ms. \note This function is only available in configuration
         * mode. \see getTimeoutMeasurement getTimeoutConfig setTimeoutConfig
         * setTimeout */
        XsensResultValue setTimeoutMeasurement(
                const uint32_t timeout = CMT3_DEFAULT_TIMEOUT_MEAS);
        /** \brief Set the dual-output mode of the XM. \details This function sets
         * the dual mode output mode of the Xbus Master. The dual output mode of the
         * Xbus Master defines whether it will send data on the serial connection
         * (at the same baud rate as the bluetooth connection) when it is connected
         * via Bluetooth. When set to 0, the serial communication is disabled, data
         * is sent over the serial bus. \note When dual-mode is enabled, the Xbus
         * Master will NOT receive commands on the serial bus. \note This function
         * is only available in configuration mode. \see getXmDualOutputMode */
        XsensResultValue setXmOutputMode(const uint8_t mode);
        /** \brief Switch the connected Xbus Master. \details This function tell the
         * connected Xbus Master to power down. This differs from setBusPowerState,
         * because this function actually powers down the Xbus Master itself, while
         * setBusPowerState only powers down the bus controlled by the Xbus Master.
         * After This function is called, the Xbus Master must be manually switched
         * on to make it operational again. \see setBusPowerState */
        XsensResultValue setXmPowerOff(void);
        /** Update device information stored on host PC. \details Some device
         * information is cached on the host PC for faster access. The Cmt3
         * automatically tries to keep the cache up to date. But when unexpected
         * things happen, such as custom messages that change the settings, or a
         * power-cycle, then the user may need to tell Cmt3 to update its cache.
         * When both a file and a port are open, the file parameter can be used to
         * indicate what data source to read from (true is file, false is port).
         * \note This function is only available in configuration mode. */
        XsensResultValue refreshCache(const bool file = false);
        /** \brief Wait for a data message to arrive. \details The function waits
         * for a data message to arrive or until a timeout occurs. The function will
         * also accept error messages. */
        XsensResultValue waitForDataMessage(Packet* pack);
        /** \brief Create a log file for incoming messages. \details This function
         * creates a log file for recording incoming messages. The Cmt3 object must
         * be connected to a communication port or the function will fail. \param
         * filename The name of the file to use as a log file. A fully qualified
         * (local) path+filename is recommended. \param startLogging When set to
         * true (default), Cmt3 will immediately start logging incoming messages to
         * the file, otherwise setLogMode must be called first before logging is
         * started. \remarks If a writable file of the same name already exists in
         * the target location, it will be overwritten without warning. \see
         * closeLogFile isLogFileOpen openLogFile setLogMode \note This function is
         * available in configuration AND in measurement mode. */
        XsensResultValue createLogFile(
                const char* filename, bool startLogging = false);
        /** \brief Create a log file for incoming messages. \details This function
         * creates a log file for recording incoming messages. The Cmt3 object must
         * be connected to a communication port or the function will fail. \param
         * filename The name of the file to use as a log file. A fully qualified
         * (local) path+filename is recommended. \param startLogging When set to
         * true (default), Cmt3 will immediately start logging incoming messages to
         * the file, otherwise setLogMode must be called first before logging is
         * started. \remarks If a writable file of the same name already exists in
         * the target location, it will be overwritten without warning. \see
         * closeLogFile isLogFileOpen openLogFile setLogMode \note This function is
         * available in configuration AND in measurement mode. */
        XsensResultValue createLogFile(
                const wchar_t* filename, bool startLogging = false);
        /** \brief Close an open log file. \details This function closes the logfile
         * if it was open. \param del When set to true, the file will be deleted
         * after closing if it is not read-only. This is mostly useful for temporary
         * log-files.   \see createLogFile isLogFileOpen openLogFile setLogMode */
        XsensResultValue closeLogFile(bool del = false);
        /** \brief Return whether or not(true or false) the supplied file is open.
         * \details When the filename parameter is nullptr or empty "", the function
         * will simply return whether a log file is open. Otherwise, the supplied
         * name will be checked against the name of the open log file as well.
         * \return true if the log file is open, false if it isn't \see closeLogFile
         * createLogFile openLogFile setLogMode */
        bool isLogFileOpen(const char* filename) const;
        /** \brief Return whether or not(true or false) the supplied file is open.
         * \details When the filename parameter is nullptr or empty "", the function
         * will simply return whether a log file is open. Otherwise, the supplied
         * name will be checked against the name of the open log file as well.
         * \return true if the log file is open, false if it isn't \see closeLogFile
         * createLogFile openLogFile setLogMode */
        bool isLogFileOpen(const wchar_t* filename) const;
        /** \brief Open a log file for input. \details This function opens the
         * supplied log file for reading. The function will fail if a serial
         * connection is currently open. \param filename The name of the file to
         * open. It is recommended to use a fully qualified path+filename. \note
         * This function is only available in configuration mode. \see closeLogFile
         * createLogFile isLogFileOpen setLogMode */
        XsensResultValue openLogFile(const char* filename);
        /** \brief Open a log file for input. \details This function opens the
         * supplied log file for reading. The function will fail if a serial
         * connection is currently open. \param filename The name of the file to
         * open. It is recommended to use a fully qualified path+filename. \note
         * This function is only available in configuration mode. \see closeLogFile
         * createLogFile isLogFileOpen setLogMode */
        XsensResultValue openLogFile(const wchar_t* filename);
        /** \brief Set whether to read from comm port or file. \details While it is
         * not possible to open a port or file while the other is open, it is
         * possible to create a log file while a port is open. In some rare cases it
         * may be required to log data and read it back while the port remains open
         * and then continue logging in the same file. This is not recommended.
         * Instead, log to a file, close it and then open it in another Cmt3 object.
         * However, if you must do this, then this function can be used to specify
         * that you want to switch between reading from the log file (true) or port
         * (false). */
        XsensResultValue setDataSource(bool readFromFile);
        /** \brief Set the logging mode. \details This function sets the logging
         * mode to enabled (true) or disabled (false). When enabled, all received
         * messages are logged to the file. \remarks Some information that is cached
         * on the host PC will generate faked messages in the log file. Eg.
         * getConfiguration and some others. */
        XsensResultValue setLogMode(bool active);
        /** \brief Restart reading from the start of the open log file. \details
         * This function resets the read position to the start of the open log file.
         * Only the read position is affected, the write position remains the same.
         * \see openLogFile */
        XsensResultValue resetLogFileReadPos(void);
        XsensResultValue writeMessageToLogFile(
                const Message& msg);  //! \brief Write the specified message to the open
        //! log file. \details This function can be used
        //! to add custom messages to a log file. \note A
        //! typical log file will only contain acknowledge
        //! messages, not request messages. \see
        //! createLogFile
        /** \brief Retrieve a list of the available scenarios. \details Use this
         * function to retrieve a list of all scenarios available in a Motion
         * Tracker. See the supplied documentation for more information about
         * scenarios. \param scenarios A buffer for storing the available scenarios.
         * The supplied buffer should be able to contain at least 6 scenarios, but
         * for future devices a larger buffer is advised. Use
         * CMT_MAX_SCENARIOS_IN_MT+1. The list is terminated by a scenario that has
         * type 0. \remarks The type of any of the returned scenarios can be safely
         * supplied to the setScenario function. \see getScenario setScenario \note
         * This function is only available in configuration mode. */
        XsensResultValue getAvailableScenarios(
                CmtScenario* scenarios, const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Get the currently active scenario from a Motion Tracker. \details
         * This function retrieves the scenario currently used by the specified
         * device when outputting orientation and/or position data. \see
         * getAvailableScenarios setScenario \note This function is only available
         * in configuration mode. */
        XsensResultValue getScenario(
                uint8_t& scenarioType, uint8_t& scenarioVersion,
                const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Specify the scenario to use in the sensor. \details This function
         * specifies the scenario that the sensor should use for converting raw data
         * into orientation and/or position data. This must be one of the scenarios
         * in the list supplied by getAvailableScenarios. \see getAvailableScenarios
         * getScenario \note This function is only available in configuration mode.
         */
        XsensResultValue setScenario(
                const uint8_t scenarioType,
                const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Retrieve the currently used magnitude of the gravity vector.
         * \details The magnitude of the gravity vector is used to determine
         * absolute acceleration from measured acceleration. \see
         * setGravityMagnitude \note This function is only available in
         * configuration mode. */
        XsensResultValue getGravityMagnitude(
                double& magnitude, const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Set the currently used magnitude of the gravity vector. \details
         * The magnitude of the gravity vector is used to determine absolute
         * acceleration from measured acceleration. Use this function to set tit to
         * a custom value in m/s2. The default value of 9.812687357684514m/s2 should
         * be fine for most places on earth, but in some cases the gravity may be
         * drastically different from standard Earth gravity (eg. space, deep
         * subterranean/submarine, polar regions, gravitational anomalies. See also
         * <A
         * HREF="http://www.abc.net.au/science/news/stories/s911917.htm">http://www.abc.net.au/science/news/stories/s911917.htm</A>
         * and <A
         * HREF="http://en.wikipedia.org/wiki/Earth%27s_gravity#Comparative_gravities_in_various_cities_around_the_world">http://en.wikipedia.org/wiki/Earth%27s_gravity#Comparative_gravities_in_various_cities_around_the_world</A>)
         * \note Correct orientation output cannot be guaranteed when an incorrect
         * value is supplied for the gravity. Changing this value is at your own
         * risk. \see getGravityMagnitude \remarks In future versions, the MTi-G may
         * be able to estimate the local gravity magnitude on its own. \note This
         * function is only available in configuration mode. */
        XsensResultValue setGravityMagnitude(
                const double magnitude, const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Get the currently used GPS lever arm. \details Use this function
         * to retrieve the vector currently used as the GPS lever arm in meters. The
         * GPS lever arm is the relative position of the GPS antenna to the MTi-G
         * unit. The arm is specified in the object coordinate system. See the
         * manual for more information on coordinate systems, alignment resets and
         * the lever arm. \see setGpsLeverArm \note This function is only available
         * in configuration mode. \note This function is only available for MTi-G
         * devices. */
        XsensResultValue getGpsLeverArm(
                CmtVector& arm, const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Request the status of the GPS satellites in orbit. \details This
         * function requests the GPS satellite status information from the GPS
         * subsystem. In config mode, this information is requested from the GPS
         * subsystem immediately, which can cause a relatively long delay (250ms)
         * before a reply is received. In measurement mode, the satellite status is
         * regularly polled internally and the latest status is returned immediately
         * when this function is called. */
        XsensResultValue getGpsStatus(
                CmtGpsStatus& status, const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Set the currently used GPS lever arm. \details Use this function
         * to set the vector currently used as the GPS lever arm. The GPS lever arm
         * is the relative position of the GPS antenna to the MTi-G unit. The arm is
         * specified in the object coordinate system and in meters. See the manual
         * for more information on coordinate systems, alignment resets and the
         * lever arm. \see getGpsLeverArm \note This function is only available in
         * configuration mode. \note This function is only available for MTi-G
         * devices. */
        XsensResultValue setGpsLeverArm(
                const CmtVector& arm, const CmtDeviceId deviceId = CMT_DID_MASTER);
        /** \brief Store important components of the XKF filter state to
         * non-volatile memory. \details This function allows you to store some
         * critical components of the internal XKF filter state to non-volatile
         * memory. The stored settings will be used to initialize the filter
         * whenever the sensor is switched to Measurement mode. \note This function
         * is only available in Config mode. */
        XsensResultValue storeXkfState(const CmtDeviceId deviceId = CMT_DID_MASTER);
};
 
}  // end of xsens namespace
 
#endif  // _CMT3_H_2006_04_14