RelianceHID.hpp

Go to the documentation of this file.

/**
 * @copyright Pyramid Technologies Inc. 2017
 * @defgroup API RelianceCore API
 * @author Cory Todd
 * @date 9/19/2017
 * @brief Required header for integration into your project
 * 
 * @mainpage
 * RelianceCore API is a native C++ library for monitoring your Reliance Thermal Printer.
 * This library support status checks and a number of configuration options. 
 * 
 * Getting started requires 3 files:
 * 
 * - RelianceHID.dll
 * - RelianceHID.lib
 * - RelianceHID.hpp
 * 
 * 1. Place the DLL where your app can find it at run time
 * 2. Link the library during compilation time
 * 3. Include the header in your project
 * 
 * Sample usage:
 * @code
 * ...
 * #include <iostream>
 * #include <RelianceHID.hpp>
 * 
 * // Use namespace for brevity
 * using namespace reliancecore;
 * ...
 * 
 * // Create an initialize your printer
 * RelianceHID printer;
 * auto result = printer.initialize();
 * 
 * // result holds the initialization success/error messages
 * std::cout << result.message.c_str() << std::endl;
 * 
 * // Check the status
 * RelianceHID::RelianceStatus status;
 * result = printer.getStatus(&status);
 * 
 * // result holds the command success/error messages
 * std::cout << result.message.c_str() << std::endl;
 * 
 * if(status.ret == RelianceHID::ReturnCode::Okay)
 * {
 *      // explore the status struct, this contains complete status
 *      ...
 * }
 * 
 * @endcode
 * 
 * Please contact <mailto:support@pyramidacceptors.com> to request the right DLL version
 * for your system.
 * 
 */

#pragma once
#include <vector>
#include <string>
#include <memory>
#include <cstdint>

#if defined (_WIN32)
#if defined(RelianceCore_EXPORTS)
/// DLL Export macro
#define  RELIANCECORE_EXPORT __declspec(dllexport)
#else
/// DLL Export macro
#define  RELIANCECORE_EXPORT __declspec(dllimport)
#endif  /* RelianceCore_EXPORTS */
#else   /* defined (_WIN32) */
/// DLL Export macro
#define RELIANCECORE_EXPORT
#endif

/**
 * @brief API Revision Level
 */
#define RELIANCE_HID_VERSION ("1.4.0")

#if !defined(NAMESPACE_BEGIN) || defined(DOXYGEN_DOCUMENTATION_BUILD)
/**
* @brief Convenience macro for namespace declarations
*
* The macro ``NAMESPACE_BEGIN(reliancecore)`` will expand to ``namespace
* reliancecore {``. This is done to hide the namespace scope from editors and
* C++ code formatting tools that may otherwise indent the entire file.
* The corresponding ``NAMESPACE_END`` macro also lists the namespace
* name for improved readability.
*
* @param name The name of the namespace scope to open
*/
#define NAMESPACE_BEGIN(name) namespace name {
#endif
#if !defined(NAMESPACE_END) || defined(DOXYGEN_DOCUMENTATION_BUILD)
/**
* @brief Convenience macro for namespace declarations
*
* Closes a namespace (counterpart to ``NAMESPACE_BEGIN``)
* ``NAMESPACE_END(reliancecore)`` will expand to only ``}``.
*
* @param name The name of the namespace scope to close
*/
#define NAMESPACE_END(name) }
#endif

NAMESPACE_BEGIN(reliancecore)

/**
 *@class RelianceHID
 *
* @brief Primary interface for interacting with Reliance Thermal Printer
*
* @ingroup API
*/
class RelianceHID {

    RelianceHID(RelianceHID &) = delete;
    RelianceHID(const RelianceHID &&) = delete;

public:
    /**
    * @brief List of string arguments
    *
    * @ingroup API
    */
    using ArgList = std::vector<std::string>;

    /**
    * @struct RelianceStatus
    *
    * @ingroup API
    *
    * @brief Status response from Reliance printer
    */
    struct RelianceStatus {

        ///! Constructor
        RelianceStatus() = default;
        ///! Destructor
        ~RelianceStatus() = default;

        /**
        * @enum SensorStatus
        *
        * @ingroup API
        * 
        * @brief Bit enumeration describes the state of each sensor
        */
        enum class SensorStatus : uint8_t {
            platenOn = 1 << 0,              ///< - 0: Platen off, - 1: Platen on
            cutterHome = 1 << 1,            ///< - 0: Cuter not home, - 1: Cutter home
            tachOk = 1 << 2,                ///< - 0: Tach okay, - 1: Tach error (ALWAYS 0)
            presenterPaperPres = 1 << 3,    ///< - 0: Paper not present - 1: Paper present
            pathPaperPres = 1 << 4,         ///< - 0: Paper not present - 1: Paper present
            paperPaperPres = 1 << 5,        ///< - 0: Paper not present - 1: Paper present
            notchPres = 1 << 6,             ///< - 0: Notch not present - 1: Notch present/detected
            armPaperPres = 1 << 7,          ///< - 0: Paper arm not installed - 1: Paper arm installed
        };

        /**
        * @enum ErrorStatus
        *
        * @ingroup API
        * 
        * @brief Bit enumberation describes each error state that can be reported by Reliance
        */
        enum class ErrorStatus : uint8_t {
            isJammed = 1 << 0,              ///< - 0: No jam, - 1: Jam has disabled printer
            isOverheated = 1 << 1,          ///< - 0: Normal system temp, - 1: Printer is overheated and disabled
            isCutterErr = 1 << 2,           ///< - 0: Cutter is okay, - 1: Cutter is in an error staes (e.g. stuck up)
            isOverVoltage = 1 << 3,         ///< - 0: System voltage okay, - 1: System over voltage
            isUnderVoltage = 1 << 4,        ///< - 0: System voltage okay, - 1: System under voltage 
            isPlatenOpen = 1 << 5,          ///< - 0: Platen (head) is closed, - 1: Platen (head) open
            _reserved = 1 << 6,             ///< Reserved
            isUnknownErr = 1 << 7,          ///< - 0: No unknown error, -1: Has an error, we don't know what

        };

        /**
        * @enum TicketState
        *
        * @ingroup API
        * 
        * @brief Reliance will always be in one of these states
        */
        enum class TicketState : uint8_t {
            Idle = 0,                       ///< Printer is not moving paper, no ticket in bezel
            Printing,                       ///< Printer is actively printing on paper
            Presenting,                     ///< Printing is complete and paper is in transit
            Presented                       ///< Printing is complete, transit is complete, paper is at bezel
        };

        uint8_t headVoltage[6];             ///< Print head voltage
        uint8_t headTempC;                  ///< Temperature of head, degrees C


        SensorStatus sensorStatus;          ///< Sensor status flags


        ErrorStatus errorStatus;            ///< Error status flags


        TicketState ticketState;            ///< Ticket status flag

        /// Raw voltages - ADC 12-bit
        uint16_t presenterADC;              ///< Presenter sensor 12-bit ADC value
        uint16_t pathRawADC;                ///< Path sensor 12-bit ADC value
        uint16_t paperADC;                  ///< Paper sensor 12-bit ADC value
        uint16_t notchADC;                  ///< Notch sensor 12-bit ADC value
        uint16_t armADC;                    ///< ARM sensor 12-bit ADC value


        /**
        * @brief Helper function to check if specified flag is set
        *
        * @ingroup API
        *
        * @param flag to check
        *
        * @return true if current SensorStatus contains flag
        */
        bool hasSensorFlag(SensorStatus flag);


        /**
        * @brief Helper function to check if specified flag is set
        *
        * @ingroup API
        *
        * @param flag to check
        *
        * @return true if current ErrorStatus contains flag
        */
        bool hasErrorFlag(ErrorStatus flag);


        /**
        * @brief Const function method to check if specified flag is set
        *
        * @ingroup API
        *
        * @param flag to check
        *
        * @return true if current SensorStatus contains flag
        */
        bool hasSensorFlag(SensorStatus flag) const;


        /**
        * @brief Const function method to check if specified flag is set
        *
        * @ingroup API
        *
        * @param flag to check
        *
        * @return true if current ErrorStatus contains flag
        */
        bool hasErrorFlag(ErrorStatus flag) const;

        /**
        * @brief Helper function returns true if status report indicates paper low
        *
        * @ingroup API
        *
        * @warning If no arm is attached to Reliance, the response will always be true
        * regardless of paper level.
        *
        * @return true if paper low. If false, no paper low warnings are present
        */
        bool isPaperLow();

        /**
        * @brief Helper function returns true if status report indicates paper is out
        *
        * @ingroup API
        *
        * @return true if there is no paper. If false, paper is present
        */
        bool isPaperOut();

        /**
        * @brief Returns the voltage given a raw ADC reading. This
        * assumes a 12-bit ADC
        *
        * @ingroup API
        */
        static float adc2Voltage(uint16_t adc);
    };

    /**
    * @enum ReturnCode
    *
    * @ingroup API
    * 
    * @brief Quick return code
    */
    enum class ReturnCode {
        Okay,               ///< Successful command
        Timeout,            ///< No response within timeout period
        BadResp,            ///< Response received but it was corrupt
        BadArg,             ///< Invalid argument provided to command builder
        DeviceNXE,          ///< No device found
        NoInit,             ///< Device is not initialized
    };

    /**
    * @struct Result
    *
    * @ingroup API
    * 
    * @brief Describes response from all RelianceHID printer commands
    */
    struct Result {
        ReturnCode ret;     ///< For command execution
        ArgList args;       ///< List of parameters passed with command, if any
        std::string command;///< Name of command
        std::string message;///< Parsed message may contain more info about errors or results
        int value = 0;      ///< Used for commands that return integer values
    };

    /**
    * @struct Revision
    *
    * @ingroup API
    * 
    * @brief Describes a firmware revision levels using semver syntax   
    */
    struct Revision {
        int major;          ///< Major revision, e.g. 1.x.x
        int minor;          ///< Minor revision, e.g. x.1.x
        int build;          ///< Build revision, e.g. x.x.1
    };

    /**
    * @brief Create instance of Reliance printer and bind to specified serial number
    *
    * @param sn serial number to attach to. If not provided, this connects to first available
    * reliance.
    */
    RELIANCECORE_EXPORT explicit RelianceHID(const std::string &sn = "");
    /**
     * @brief Destructor
     */
    RELIANCECORE_EXPORT ~RelianceHID();

    /**
    * @brief Attempt to connect to device
    *
    * @ingroup API
    *
    * @warning This must be called before executing any commands
    *
    * @return ret and message fields will be set with additional information
    */
    RELIANCECORE_EXPORT Result initialize();

    /**
    * @brief Read firmware revision from target
    *
    * @ingroup API
    *
    * @param rev out parameter
    *
    * @return ret and message fields will be set with additional information
    */
    RELIANCECORE_EXPORT Result getRevision(Revision *rev);

    /**
    * @brief Side effect free command to test for presence of printer
    *
    * @ingroup API
    *
    * @return ret and message fields will be set with additional information
    */
    RELIANCECORE_EXPORT Result ping();

    /**
    * @brief Immediately perform a hard reboot of the printer
    *
    * @ingroup API
    *
    * @warning You must call initialize after a reboot
    *
    * @return ret and message fields will be set with additional information
    */
    RELIANCECORE_EXPORT Result reboot();

    /**
    * @brief Get the current status of Reliance printer
    *
    * @ingroup API
    *
    * @param status will be written with current status
    *
    * @return ret and message fields will be set with additional information
    */
    RELIANCECORE_EXPORT Result getStatus(RelianceStatus *status);

    /**
    * @brief Gets the state of the USB virtual comm port feature
    *
    * @ingroup API
    *
    * @details When enabled, Reliance will enumerate an additional USB
    * interface as a CDC comm port. Check device manager or /dev/tty*
    * to find the OS assigned port name.
    *
    * @return Result.value -
    * 0 - Off (disabled)
    * 1 - On (enabled)
    */
    RELIANCECORE_EXPORT Result getVirtualCommsEnabled();

    /**
    * @brief Enable or disable the USB virtual comm port feature
    *
    * @ingroup API
    *
    * @details When enabled, Reliance will enumerate an additional USB
    * interface as a CDC comm port. Check device manager or /dev/tty*
    * to find the OS assigned port name.
    *
    * @note A reboot of the printer is required in order for this to take effect
    *
    * @see RelianceHID#reboot
    *
    * @param enabled true or false
    *
    * @return ret and message fields will be set with additional information
    */
    RELIANCECORE_EXPORT Result setVirtualCommsEnabled(bool enabled);

    /**
    * @brief Gets the state of the startup ticket feature
    *
    * @ingroup API
    *
    * @details When enabled, Reliance will print its configuration to a ticket
    * on every power up. When disabled, this behavior is disabled.
    *
    * @note This only controls the startup ticket. The ticket that is printed when
    * you feed in paper cannot be disabled.
    *
    * @return ret and message fields will be set with additional information
    */
    RELIANCECORE_EXPORT Result getStartupTicketEnabled();

    /**
    * @brief Sets the state of the startup ticket feature
    *
    * @ingroup API
    *
    * @note When enabled, Reliance will print its configuration to a ticket
    * on every power up. When disabled, this behavior is disabled.
    *
    * @note This only controls the startup ticket. The ticket that is printed when
    *
    * @param enabled true or false
    *
    * @return ret and message fields will be set with additional information
    */
    RELIANCECORE_EXPORT Result setStartupTicketEnabled(bool enabled);

    /**
    * @brief Returns a list of ESC/POS commands the Reliance does not understand
    *
    * @ingroup API
    *
    * @details The list will be written to dst in the order cmd:arg where cmd is
    * a known ESC/POS prefix such as ESC, FS, or GS (1B, 1C, 1D) and the arg is the first
    * given parmeter. This is useful for legacy applications that send uncommon or customer
    * ESC/POS commands to their printers.
    *
    * @param dst vector to write log to
    *
    * @return ret and message fields will be set with additional information
    */
    RELIANCECORE_EXPORT Result getUnknownCommands(std::vector<int> &dst);


    /**
    * @brief Returns the current configured paper roll width
    *
    * @ingroup API
    *
    * @details Reliance supports paper rolls width from 58mm though 80mm. This
    * setting enables proper print margins for your chosen roll width.
    *
    * @return ret and message fields will be set with additional information.
    * Result#value set to paper width in mm
    */
    RELIANCECORE_EXPORT Result getPaperWidth();

    /**
    * @brief Change the paper roll width configuration
    *
    * @ingroup API
    *
    * @param width value between 58 and 80, inclusive
    *
    * @return ret and message fields will be set with additional information
    */
    RELIANCECORE_EXPORT Result setPaperWidth(int width);

    /**
    * @brief Returns the current motor configuration
    *
    * @ingroup API
    *
    * @details There are currently two motors, gen1 and gen2. The returned result
    * will populate the value field with 0, 1, etc. which represent these motor gens.
    *
    * @return ret and message fields will be set with additional information. 
    * Result#value set to motor generation code
    */
    RELIANCECORE_EXPORT Result getMotorGen();

    /**
    * @brief Change the motor configuration to another gen
    *
    * @ingroup API
    *
    * @warning This function should not be called under normal conditions. This 
    * is for service technicians that may be replacing motors in older units.
    *
    * @param gen 0 for gen1, 1 for gen 2
    *
    * @return ret and message fields will be set with additional information
    */
    RELIANCECORE_EXPORT Result setMotorGen(int gen);

    /**
    * @brief Returns the current motor current in milliamps
    *
    * @ingroup API
    *
    * @details This is the current that is applied to printer motor.
    *
    * @return ret and message fields will be set with additional information.
    * Result#value set to motor current value
    */
    RELIANCECORE_EXPORT Result getMotorCurrent();

    /**
    * @brief Change the motor current
    *
    * @ingroup API
    *
    * @warning This function should not be called under normal conditions. This
    * is for service technicians that may be replacing motors in older units.
    *
    * @param current milliamps to apply to printer motor (min: 50, max: 1500)
    *
    * @return ret and message fields will be set with additional information
    */
    RELIANCECORE_EXPORT Result setMotorCurrent(int current);

private:

    struct Impl;                    ///< Internal implementation
    std::unique_ptr<Impl> impl;
};
NAMESPACE_END(reliancecore)