path: root/include/mts/MTS_IO_ICellularRadio.h

#ifndef MTS_IO_ICELLULARRADIO_H
#define MTS_IO_ICELLULARRADIO_H

#include <string>
#include <vector>
#include <functional>

#include <json/json.h>

#include <mts/MTS_AutoPtr.h>
#include <mts/MTS_IO_SerialConnection.h>

#define EXPORT __attribute__((visibility("default")))

namespace MTS {
    namespace IO {
        class EXPORT ICellularRadio
        {
            public:
                typedef std::function<bool(const std::string&/*iterationData*/, const std::string&/*allData*/)> IsNeedMoreData;
                typedef std::function<void(const Json::Value&)> UpdateCb;

                //Registration Values
                enum REGISTRATION : uint8_t {
                    NOT_REGISTERED = 0,
                    REGISTERED = 1,
                    SEARCHING=2,
                    DENIED=3,
                    UNKNOWN=4,
                    ROAMING=5
                };

                enum SERVICEDOMAIN : uint8_t {
                    NO_SERVICE = 0,
                    CS_ONLY = 1,
                    PS_ONLY = 2,
                    CSPS = 3
                };

                enum ACTIVEBAND : uint8_t {
                    GSM_850 = 0,
                    GSM_900 = 1,
                    DCS_1800 = 2,
                    PCS_1900 = 3
                };

                enum CODE : uint8_t {
                    SUCCESS = 0,
                    ERROR,
                    FAILURE,
                    NO_RESPONSE,
                    NOT_APPLICABLE,
                    INVALID_ARGS
                };

                enum SIMSTATUS : uint8_t {
                    READY = 0,
                    LOCKED,
                    BLOCKED,
                    NOT_INSERTED
                };

                enum CELLULAR_MODES : uint8_t {
                    CELLULAR_MODE_NA = 0, // NOT AVAILABLE
                    CELLULAR_MODE_2G = 1 << 0, // GSM
                    CELLULAR_MODE_3G = 1 << 1, // WCDMA
                    CELLULAR_MODE_4G = 1 << 2, // LTE
                    CELLULAR_MODE_5G = 1 << 3  // 5G
                };

                enum UE_MODES_OF_OPERATION : uint8_t {
                    UNKNOWN_MODE = 0, // current mode of operation is not available
                    PS_MODE1, // only EPS (LTE) services are allowed, the usage is "voice centric"
                    PS_MODE2, // only EPS (LTE) services are allowed, the usage is "data centric"
                    CS_PS_MODE1, // both EPS and non-EPS services are allowed, the usage is "voice centric"
                    CS_PS_MODE2, // both EPS and non-EPS services are allowed, the usage is "data centric"
                    CS_MODE1, // only non-EPS services are allowed, the usage is "voice centric"
                    CS_MODE2 // only non-EPS services are allowed, the usage is "data centric"
                };

                enum PDP_CONTEXT_AUTH_TYPE : uint8_t {
                    NONE = 0,
                    PAP,
                    CHAP,
                    PAP_CHAP
                };

                static CODE convertModelToType(const std::string& sModel, std::string& sType);
                static CODE convertModelToMtsShortCode(const std::string& sModel, std::string& sCode, ICellularRadio *radioObj = NULL);
                static CODE convertServiceDomainToString(SERVICEDOMAIN eSd, std::string& sSd);
                static CODE convertActiveBandToString(ACTIVEBAND eBand, std::string& sBand);
                static CODE convertUeModeToString(ICellularRadio::UE_MODES_OF_OPERATION mode, std::string& sMode);
                static CODE convertStringToUeMode(const std::string& sMode, ICellularRadio::UE_MODES_OF_OPERATION& mode);

                static std::string sendCommand(MTS::AutoPtr<MTS::IO::Connection>& apIo,
                                               const std::string& sCmd,
                                               IsNeedMoreData& isNeedMoreData,
                                               int32_t timeoutMillis = 100,
                                               const char& ESC = CR);
                static std::string sendCommand(MTS::AutoPtr<MTS::IO::Connection>& apIo,
                                               const std::string& sCmd,
                                               const std::vector<std::string>& vBail = DEFAULT_BAIL_STRINGS,
                                               int32_t timeoutMillis = 100,
                                               const char& ESC = CR);

                //! Wait for response from the radio without sending any data to it
                static std::string waitResponse(MTS::AutoPtr<MTS::IO::Connection>& apIo,
                                                IsNeedMoreData& isNeedMoreData,
                                                int32_t timeoutMillis = 100);
                static std::string waitResponse(MTS::AutoPtr<MTS::IO::Connection>& apIo,
                                                const std::vector<std::string>& vBail = DEFAULT_BAIL_STRINGS,
                                                int32_t timeoutMillis = 100);

                static CODE test(MTS::AutoPtr<MTS::IO::Connection>& apIo, uint32_t timeoutSeconds = 30);
                static std::string extractModelFromResult(const std::string& sResult);
                static std::string getCodeAsString(CODE code);

                static const char *DEFAULT_RADIO_PORT;
                static const char *DEFAULT_RADIO_DIR;

                static const char *VALUE_UNKNOWN;
                static const char *VALUE_UNAVAILABLE;
                static const char *VALUE_NOT_SUPPORTED;

                //Special Payload Characters
                static const char ETX;  //Ends socket connection
                static const char DLE;  //Escapes ETX and DLE within Payload
                static const char CR;
                static const char NL;
                static const char CTRL_Z;

                static const char *RSP_OK;
                static const char *RSP_ERROR;
                static const char *RSP_CONNECT;

                static const char *VALUE_NOT_REGISTERED;
                static const char *VALUE_REGISTERED;
                static const char *VALUE_SEARCHING;
                static const char *VALUE_DENIED;
                static const char *VALUE_ROAMING;

                //Static Data
                static const char *KEY_TYPE;          //!< GSM or CDMA
                static const char *KEY_CODE;          //!< Product Code : H5, H6, C2, EV3, G3
                static const char *KEY_MODEL;         //!< Model : HE910, CE910, DE910, GE910
                static const char *KEY_MANUFACTURER;  //!< Manufacturer: Telit
                static const char *KEY_HARDWARE;      //!< Radio Hardware Version
                static const char *KEY_FIRMWARE;      //!< Radio Firmware Version
                static const char *KEY_FIRMWARE_BUILD;//!< Radio Firmware Build
                static const char *KEY_VENDOR_FIRMWARE;  //!< Radio Vendor Firmware Version
                static const char *KEY_IMEI;          //!< International Mobile Station Equipment Identity
                static const char *KEY_MEID;          //!< Mobile Equipment Identifier
                static const char *KEY_IMSI;          //!< International Mobile Subscriber Identity
                static const char *KEY_MSID;          //!< Mobil Station ID (MSID) aka MIN aka MSIN aka Last few digits of IMSI
                static const char *KEY_MDN;           //!< Mobile Directory Number : Actual phone number dialed to reach radio
                static const char *KEY_CARRIER;       //!< Cellular Service Provider (Home Network)
                static const char *KEY_ICCID;         //!< Integrated Circuit Card Identifier
                static const char *KEY_MSL;           //!< Master Subsidy Lock
                static const char *KEY_SUPPORTED_CELL_MODES;  //!< Comma-separated list of all supported cellular modes (2g,3g,4g)
                static const char *KEY_SIM_CARRIER_CODE;  //!< Unique carrier identifier based on the SIM card information.
                static const char *KEY_SIM_MCC;       //!< MCC of the home network from the SIM.
                static const char *KEY_SIM_MNC;       //!< MNC of the home network from the SIM.
                static const char *KEY_VOICE_ENABLED; //!< Enable/Disable support of voice calls
                static const char *KEY_SMS_ONLY;      //!< Enable/Disable "SMS only" registration flag


                //Network Status Data
                static const char *KEY_ROAMING;       //!< Indicates whether or not using Home Network
                static const char *KEY_DATETIME;      //!< Date and Time from tower
                static const char *KEY_SERVICE;       //!< Service Connection Type [GPRS, EGPRS, WCDMA, HSDPA, 1xRTT, EVDO]
                static const char *KEY_CELL_MODE;     //!< Specifies the cellular mode that is currently used by the modem [2g, 3g, 4g]
                static const char *KEY_NETWORK;       //!< Cellular Service Provider
                static const char *KEY_NETWORK_REG;   //!< Network Registration
                static const char *KEY_CID;           //!< Cellular ID (Tower) in HEX
                static const char *KEY_LAC;           //!< Location Area Code in HEX
                static const char *KEY_RAC;           //!< Routing Area Code in HEX
                static const char *KEY_RSSI;          //!< Received Signal Strength Indication
                static const char *KEY_RSSIDBM;       //!< Received Signal Strength Indication in dBm
                static const char *KEY_MCC;           //!< Mobile Country Code
                static const char *KEY_MNC;           //!< Mobile Network (Operator) Code
                static const char *KEY_CHANNEL;       //!< ARFCN or UARFCN Assigned Radio Channel
                static const char *KEY_TXPWR;         //!< Transmit Power
                static const char *KEY_PSC;           //!< Active Primary Synchronization Code (PSC)
                static const char *KEY_ECIO;          //!< Active Ec/Io (chip energy per total wideband power in dBm)
                static const char *KEY_RSCP;          //!< Active RSCP (Received Signal Code Power in dBm)
                static const char *KEY_DRX;           //!< Discontinuous reception cycle length (ms)
                static const char *KEY_MM;            //!< Mobility Management State
                static const char *KEY_RR;            //!< Radio Resource State
                static const char *KEY_NOM;           //!< Network Operator Mode
                static const char *KEY_ABND;          //!< Active Band
                static const char *KEY_BLER;          //!< Block Error Rate (percentage)
                static const char *KEY_SD;            //!< Service Domain
                static const char *KEY_DEBUG;         //!< Debug Information

                static const char *KEY_MIP;                //!< Mobile IP Information
                static const char *KEY_MIP_ID;             //!< MIP Profile ID
                static const char *KEY_MIP_ENABLED;         //!< MIP Profile Enabled/Disabled
                static const char *KEY_MIP_NAI;            //!< Network Access Identifier
                static const char *KEY_MIP_HOMEADDRESS;    //!< Home Address
                static const char *KEY_MIP_PRIMARYHA;      //!< Primary Home Agent
                static const char *KEY_MIP_SECONDARYHA;    //!< Secondary Home Agent
                static const char *KEY_MIP_MNAAASPI;       //!< Mobile Node Authentication, Authorization, and Accounting Server Security Parameter Index
                static const char *KEY_MIP_MNHASPI;        //!< Mobile Node Home Agent Security Server Parameter Index
                static const char *KEY_MIP_REVTUN;         //!< Reverse Tunneling Enabled
                static const char *KEY_MIP_MNAAASS;        //!< Mobile Node Authentication, Authorization, and Accounting Server Shared Secret
                static const char *KEY_MIP_MNHASS;         //!< Mobile Node Home Agent Shared Secret

                //SIM Status Summary data
                static const char *KEY_IS_SIM_INSERTED;    //!< SIM card insertion indicator. True when a SIM card is inserted
                static const char *KEY_IS_SIM_LOCKED;      //!< SIM card lock status indicator. True when a SIM card is locked by PIN / PUK / other code
                static const char *KEY_SIM_LOCK_STATUS;    //!< SIM card lock status string. Either "READY", "SIM PIN", "SIM PUK" or other state
                static const char *KEY_ATTEMPTS_PIN;       //!< The number of attempts left to unlock the SIM card using PIN code
                static const char *KEY_ATTEMPTS_PUK;       //!< The number of attempts left to unlock the SIM card using PUK code

                //PDP Context
                static const char *KEY_PDP_CONTEXT_ID;
                static const char *KEY_PDP_CONTEXT_APN;
                static const char *KEY_PDP_CONTEXT_IPMODE;
                static const char *KEY_PDP_CONTEXT_AUTH_TYPE;
                static const char *KEY_PDP_CONTEXT_AUTH_USERNAME;
                static const char *KEY_PDP_CONTEXT_AUTH_PASSWORD;
                static const char *VALUE_PDP_CONTEXT_IP_MODE_IP;
                static const char *VALUE_PDP_CONTEXT_IP_MODE_IPV6;
                static const char *VALUE_PDP_CONTEXT_IP_MODE_IPV4V6;
                static const char *VALUE_PDP_CONTEXT_AUTH_TYPE_NONE;
                static const char *VALUE_PDP_CONTEXT_AUTH_TYPE_PAP;
                static const char *VALUE_PDP_CONTEXT_AUTH_TYPE_CHAP;
                static const char *VALUE_PDP_CONTEXT_AUTH_TYPE_PAP_CHAP;

                //Values - Type
                static const char *VALUE_TYPE_LTE;
                static const char *VALUE_TYPE_GSM;
                static const char *VALUE_TYPE_CDMA;

                //Values - Carrier
                static const char *VALUE_CARRIER_VERIZON;
                static const char *VALUE_CARRIER_AERIS;
                static const char *VALUE_CARRIER_SPRINT;
                static const char *VALUE_CARRIER_USCELLULAR;
                static const char *VALUE_CARRIER_ATT;
                static const char *VALUE_CARRIER_TMOBILE;

                static const char *VALUE_SD_NO_SERVICE;
                static const char *VALUE_SD_CS_ONLY;
                static const char *VALUE_SD_PS_ONLY;
                static const char *VALUE_SD_CSPS;

                static const char *VALUE_ABND_GSM_850;
                static const char *VALUE_ABND_GSM_900;
                static const char *VALUE_ABND_DCS_1800;
                static const char *VALUE_ABND_PCS_1900;

                //Values - Carrier code; abstraction over PLMN IDs, IINs and other identifiers
                static const char *VALUE_CARRIER_CODE_VERIZON;
                static const char *VALUE_CARRIER_CODE_ATT;

                static const std::vector<std::string> DEFAULT_BAIL_STRINGS;

                virtual ~ICellularRadio() = 0;

                virtual bool initialize(uint32_t iTimeoutMillis = 5000) = 0;
                virtual bool resetRadio(uint32_t iTimeoutMillis = 5000) = 0;
                virtual bool resetConnection(uint32_t iTimeoutMillis = 5000) = 0;
                virtual void shutdown() = 0;

                virtual const std::string& getName() const = 0;

                virtual CODE getModel(std::string& sModel) = 0;

                virtual CODE getFirmware(std::string& sFirmware) = 0;
                virtual CODE getFirmwareBuild(std::string& sFirmwareBuild) = 0;
                virtual CODE getVendorFirmware(std::string& sVendorFirmware) = 0;
                virtual CODE getHardware(std::string& sHardware) = 0;
                virtual CODE getManufacturer(std::string& sManufacturer) = 0;
                virtual CODE getImei(std::string& sImei) = 0;
                virtual CODE getMeid(std::string& sMeid) = 0;
                virtual CODE getImsi(std::string& sImsi) = 0;
                virtual CODE getSimStatus(std::string& sSimStatus) = 0;

                virtual CODE getSupportedCellularModes(CELLULAR_MODES &networks) = 0;
                virtual CODE getCellularMode(CELLULAR_MODES &networks) = 0;
                virtual CODE setCellularMode(CELLULAR_MODES networks) = 0;

                /**
                 * @brief getSimStatusSummary - get summary on the SIM card status
                 *        (if there is a SIM card inserted, is it locked, etc).
                 *        See below for the full list of returned fields.
                 *
                 * - `isSimInserted` - bool, is the SIM card installed or not;
                 * - `isSimLocked` - bool, is the SIM card blocked with PIN/PUK or not (or is READY);
                 * - `lockStatus` - string, either "READY", "SIM PUK", "SIM PIN" or other status as
                 *    returned by "AT+CPIN?" AT command;
                 * - `attemptsPin` - integer, the number of attempts lef to enter a PIN code;
                 * - `attemptsPuk` - integer, the number of attempts lef to enter a PUK code.
                 *
                 * **Only `isSimInserted` is always present.** All other fields are omitted if
                 * the SIM card is removed.
                 *
                 * @param jData - an object to be filled with data
                 * @return CODE::SUCCESS on success,
                 *         CODE::NOT_APPLICABLE if not supported by this radio
                 *         and CODE::ERROR otherwise
                 */
                virtual CODE getSimStatusSummary(Json::Value& jData) = 0;

                virtual CODE getIccid(std::string& sIccid) = 0;
                virtual CODE getService(std::string& sService) = 0;
                virtual CODE getLac(std::string& sLac) = 0;
                virtual CODE getMdn(std::string& sMdn) = 0;
                virtual CODE getMsid(std::string& sMsid) = 0;
                virtual CODE getType(std::string& sType) = 0;
                virtual CODE getCarrier(std::string& sCarrier) = 0;
                virtual CODE getNetwork(std::string& sNetwork) = 0;
                virtual CODE getTower(std::string& sTower) = 0;
                virtual CODE getTime(std::string& sDate, std::string& sTime, std::string& sTimeZone) = 0;
                virtual CODE getRoaming(bool& bRoaming) = 0;

                virtual CODE getSignalStrength(int32_t& iRssi) = 0;
                virtual CODE getModemLocation(std::string& sLocation) = 0;
                virtual CODE convertSignalStrengthTodBm(const int32_t& iRssi, int32_t& dBm) = 0;
                virtual CODE convertdBmToSignalStrength(const int32_t& dBm, int32_t& iRssi) = 0;

                virtual CODE getRegistration(REGISTRATION& eRegistration) = 0;
                virtual CODE convertRegistrationToString(REGISTRATION eRegistration, std::string& sRegistration) = 0;

                virtual CODE convertCellModesToString(CELLULAR_MODES eCellModes, std::string& sCellModes) = 0;

                /**
                 * @brief unlockSimCard - unlock the SIM card using PIN code provided
                 *
                 * This command does not peform any checks on the number of attempts left.
                 * Use with caution, verify the SIM status manually before execution.
                 *
                 * @param jArgs - a JSON object with the following format:
                 *
                 *        jArgs = {
                 *            "pin" : "A correct PIN code to unlock the SIM card: STRING"
                 *        }
                 *
                 * @return CODE::SUCCESS when SIM card was succeffully unlocked,
                 *         CODE::INVALID_ARGS when passed arguments are invalid,
                 *         CODE::ERROR otherwise (i.e. when modem is not responding,
                 *         when SIM card is removed, when PIN code is not correct
                 *         or on any other error).
                 */
                virtual CODE unlockSimCard(const Json::Value& jArgs) = 0;

                /**
                 * @brief getSimCarrierCode - get unique carrier identifier based on
                 *        the SIM card information.
                 *
                 * @param sCarrier - a string to be populated with one of the carrier codes:
                 *
                 *        - VALUE_CARRIER_CODE_VERIZON - Verizon
                 *        - VALUE_CARRIER_CODE_ATT - AT&T
                 *        - VALUE_UNKNOWN - Unknown carrier
                 *        - other values may be defined in the future
                 *
                 * @return CODE::SUCCESS when carrier code retrieved,
                 *         CODE::ERROR otherwise (i.e. when modem is not responding,
                 *         when SIM card is removed or on any other error).
                 */
                virtual CODE getSimCarrierCode(std::string& sCarrierCode) = 0;

                //! Gather details of the radio's Mobile IP Profile
                /*!
                 \param Json::Value object that will be populated with MIP data
                 \return Returns result code of gathering MIP
                 */
                virtual CODE getMipProfile(Json::Value& jMipProfile) = 0;

                /*
                 * jArgs = {
                 *     "msl" : "Master Subsidy Lock (Aeris, Sprint): STRING"
                 * }
                 */
                virtual CODE validateMsl(const Json::Value& jArgs) = 0;

                /*
                 * jArgs = {
                 *     "mdn" : "Mobile Directory Number : STRING",
                 *     "msl" : "[OPTIONAL] Master Subsidy Lock (Aeris, Sprint): STRING"
                 * }
                 */
                virtual CODE setMdn(const Json::Value& jArgs) = 0;

                /*
                 * jArgs = {
                 *     "msid" : "Mobil Station ID (MSID) aka MIN aka MSIN : STRING",
                 *     "msl" : "[OPTIONAL] Master Subsidy Lock (Aeris, Sprint): STRING"
                 * }
                 */
                virtual CODE setMsid(const Json::Value& jArgs) = 0;

                /*
                 * jArgs = {
                 *     "activeProfile" : "Set active profile: STRING"
                 * }
                 */
                virtual CODE setMipActiveProfile(const Json::Value& jArgs) = 0;

                /*
                 * jArgs = {
                 *     "nai" : "Network Access Identifier : STRING"
                 * }
                 */
                virtual CODE setMipNai(const Json::Value& jArgs) = 0;

                /*
                 * jArgs = {
                 *     "homeIp" : "Home Address : STRING"
                 * }
                 */
                virtual CODE setMipHomeIp(const Json::Value& jArgs) = 0;

                /*
                 * jArgs = {
                 *     "primaryHa" : "Primary Home Agent : STRING"
                 * }
                 */
                virtual CODE setMipPrimaryHa(const Json::Value& jArgs) = 0;

                /*
                 * jArgs = {
                 *     "secondaryHa" : "Secondary Home Agent : STRING"
                 * }
                 */
                virtual CODE setMipSecondaryHa(const Json::Value& jArgs) = 0;

                /*
                 * jArgs = {
                 *     "mnAaaSpi" : "Mobile Node Authentication, Authorization, and Accounting Server Security Parameter Index : STRING"
                 * }
                 */
                virtual CODE setMipMnAaaSpi(const Json::Value& jArgs) = 0;

                /*
                 * jArgs = {
                 *     "mnHaSpi" : "Mobile Node Home Agent Security Server Parameter Index : STRING"
                 * }
                 */
                virtual CODE setMipMnHaSpi(const Json::Value& jArgs) = 0;

                /*
                 * jArgs = {
                 *     "revTun" : "[DESCRIPTION] : STRING"
                 * }
                 */
                virtual CODE setMipRevTun(const Json::Value& jArgs) = 0;

                /*
                 * jArgs = {
                 *     "mnAaaSs" : "Mobile Node Authentication, Authorization, and Accounting Server Shared Secret : STRING"
                 * }
                 */
                virtual CODE setMipMnAaaSs(const Json::Value& jArgs) = 0;

                /*
                 * jArgs = {
                 *     "mnHaSs" : "Mobile Node Home Agent Shared Secret : STRING"
                 * }
                 */
                virtual CODE setMipMnHaSs(const Json::Value& jArgs) = 0;

                /*
                 * jArgs = null
                 */
                virtual CODE updateDc(const Json::Value& jArgs, UpdateCb& stepCb) = 0;

                /*
                 * jArgs = null
                 */
                virtual CODE updatePrl(const Json::Value& jArgs, UpdateCb& stepCb) = 0;

                /*
                 * jArgs = null
                 */
                virtual CODE updateFumo(const Json::Value& jArgs, UpdateCb& stepCb) = 0;

                /**
                 * @brief updateFumoLocal - Performs the radio firmware upgrade using local firmware image.
                 *
                 * This command uploads (injects) the whole delta firmware image to the radio, performs the
                 * upgrade and waits for it to complete.
                 *
                 * @param fd - file descriptor of a file that shall be injected to the radio.
                 * @param stepCb - callback to receive status updates during the firmware upgrade.
                 * @return CODE::SUCCESS when the firmware upgrade was successful,
                 *         CODE::INVALID_ARGS when the file can't be opened for reading,
                 *         CODE::FAILURE when upgrade failed on the radio side,
                 *         CODE::NOT_APPLICABLE when not supported by this radio,
                 *         CODE::ERROR otherwise.
                 */
                virtual CODE updateFumoLocal(int fd, UpdateCb& stepCb) = 0;

                /**
                 * @brief fumoLocalInject - upload delta file to the radio's internal memory.
                 *
                 * This command uploads (injects) the whole delta firmware image to some place that
                 * can be later used by the radio to perform the Delta Radio Firmware Upgrade.
                 *
                 * This delta firmware image is NOT validated on the firmware image upload step.
                 *
                 * @param fd - file sescriptor of a file that shall be uploaded to the radio.
                 * @param stepCb - callback to receive status updates during the upload.
                 * @return CODE::SUCCESS when the file was successfully uploaded,
                 *         CODE::INVALID_ARGS when the file can't be opened for reading,
                 *         CODE::NOT_APPLICABLE when not supported by this radio,
                 *         CODE::ERROR otherwise.
                 */
                virtual CODE fumoLocalInject(int fd, UpdateCb& stepCb) = 0;

                /**
                 * @brief fumoLocalApply - apply the delta file that was previously uploaded.
                 *
                 * This commands initializes and tracks the progress of the delta firmware upgrade
                 * procedure using the delta firmware image file that was previously uploaded
                 * into internal memory of the radio.
                 *
                 * See ICellularRadio::fumoLocalInject to upload the file and prepare
                 * for the upgrade.
                 *
                 * @param fd - file descriptor of a file that shall be uploaded to the radio.
                 * @param stepCb - the callback to receive status updates during the upgrade.
                 * @return CODE::SUCCESS when the firmware upgrade was successful,
                 *         CODE::FAILURE when upgrade failed on the radio side,
                 *         CODE::NOT_APPLICABLE when not supported by this radio,
                 *         CODE::ERROR otherwise.
                 */
                virtual CODE fumoLocalApply(UpdateCb& stepCb) = 0;

                /**
                 * @brief fumoLocalCleanup - remove the delta file from the radio's internal memory.
                 *
                 * This command allows to remove the old delta firmware image from the radio's internal
                 * memory for cases when it's no longer needed.
                 *
                 * @return CODE::SUCCESS when the file was successfully deleted,
                 *         CODE::FAILURE when the file can't be deleted (i.e. no such file),
                 *         CODE::NOT_APPLICABLE when not supported by this radio,
                 *         CODE::ERROR otherwise.
                 */
                virtual CODE fumoLocalCleanup() = 0;

                /*
                 * jArgs = {
                 *     "msl" : "Master Subsidy Lock (Sprint): STRING"
                 * }
                 */
                virtual CODE resetHfa(const Json::Value& jArgs, UpdateCb& stepCb) = 0;

                /*
                 * jArgs = {
                 *     "mdn" : "Mobile Directory Number (Aeris): STRING"
                 *     "msid" : "Mobile Station ID (Aeris): STRING"
                 * }
                 */
                virtual CODE activate(const Json::Value& jArgs, UpdateCb& stepCb) = 0;

                /*
                 * jArgs = {
                 *     "enabled" : "RX Diversity Enabled ("0" or "1"): STRING"
                 * }
                 */
                virtual CODE setRxDiversity(const Json::Value& jArgs) = 0;
                /*
                 * jArgs = {
                 *     "fwid" : "Firmware Image To Be Enabled: STRING"
                 * }
                 */

                virtual CODE startOmaDm(UpdateCb& stepCb) = 0;

                virtual CODE setActiveFirmware(const Json::Value& jArgs) = 0;
                virtual CODE getActiveFirmware(std::string& sFwId) = 0;

                virtual CODE getEcho(bool& bEnabled) = 0;
                virtual CODE setEcho(bool bEnabled = true) = 0;

                virtual CODE getStaticInformation(Json::Value& jData) = 0;
                virtual CODE getNetworkStatus(Json::Value& jData) = 0;

                virtual CODE sendBasicCommand(const std::string& sCmd, int32_t timeoutMillis = 100, const char& ESC = CR) = 0;

                virtual std::string sendCommand(const std::string& sCmd,
                                                const std::vector<std::string>& vBail = DEFAULT_BAIL_STRINGS,
                                                int32_t timeoutMillis = 100,
                                                const char& ESC = CR) = 0;

                virtual std::string sendCommand(const std::string& sCmd,
                                                IsNeedMoreData& isNeedMoreData,
                                                int32_t timeoutMillis = 100,
                                                const char& ESC = CR) = 0;

                //! Wait for response from the radio without sending any data to it
                virtual std::string waitResponse(const std::vector<std::string>& vBail = DEFAULT_BAIL_STRINGS,
                                                 int32_t timeoutMillis = 100) = 0;

                //! Wait for response from the radio without sending any data to it
                virtual std::string waitResponse(IsNeedMoreData& isNeedMoreData,
                                                 int32_t timeoutMillis = 100) = 0;

                virtual CODE setUeModeOfOperation(ICellularRadio::UE_MODES_OF_OPERATION mode) = 0;
                virtual CODE getUeModeOfOperation(ICellularRadio::UE_MODES_OF_OPERATION& mode) = 0;

                /**
                 * @brief getSimMccMnc - get MCC/MNC (PLMN code) of the home network from the SIM.
                 *
                 * @param sPlmnId - a string to be filled with the MCC/MNC combination,
                 *        example: "310410" (for AT&T), "90118" (for WMS).
                 * @return CODE::SUCCESS when fetched successfully,
                 *         CODE::NOT_APPLICABLE when the modem doesn't support this feature,
                 *         CODE::NO_RESPONSE when the modem doesn't respond,
                 *         CODE::ERROR when the radio returns "ERROR" (SIM card removed, SIM card locked etc),
                 *         CODE::FAILURE otherwise (unexpected response, no data in SIM etc).
                 */
                virtual CODE getSimMccMnc(std::string& sMccMnc) = 0;
                virtual CODE getSimMccMnc(std::string& sMcc, std::string& sMnc) = 0;

                /**
                 * @brief disableVoiceSupport - disable voice support (IMS and CSFB) and enable "SMS only" registration flag.
                 *
                 * @return CODE::SUCCESS when disabled successfully,
                 *         CODE::NOT_APPLICABLE when the modem doesn't support this feature,
                 *         CODE::NO_RESPONSE when the modem doesn't respond,
                 *         CODE::ERROR when the radio returns "ERROR",
                 *         CODE::FAILURE otherwise (unexpected response).
                 */
                virtual CODE disableVoiceSupport() = 0;

                /**
                 * @brief getVoiceSupport - get voice support configuration for the current radio.
                 *
                 * @param bVoiceEnabled - a boolean value indicating that "voice support" is enabled.
                 * @param bSmsOnly - a boolean value indicating that "SMS only" registration flag is enabled.
                 *
                 * @return CODE::SUCCESS when fetched successfully,
                 *         CODE::NOT_APPLICABLE when the modem doesn't support this feature,
                 *         CODE::NO_RESPONSE when the modem doesn't respond,
                 *         CODE::ERROR when the radio returns "ERROR",
                 *         CODE::FAILURE otherwise (unexpected response).
                 */
                virtual CODE getVoiceSupport(Json::Value& jData) = 0;
                virtual CODE getVoiceSupport(bool& bVoiceEnabled, bool& bSmsOnly) = 0;

                /**
                * @brief getSelectedBandsRaw - get the raw Selected Bands value for the current radio.
                *
                * This commands sends the query to the radio, selects first 3 values from the response,
                * parses the numbers as dec (Telit GSM and WCDMA fiels) or hex (Quectel GW_band and LTE,
                * Telit LTE), formats them as comma-separated hex values and saves the result to sRawBands.
                *
                * WARNING: The response format is radio-dependent. Please consult the AT command manual
                * to interpet the resulting values.
                *
                * For Telit radios:
                *
                * - command: `AT#BND?`;
                * - example radio response: `#BND: 5,15,800C5`;
                * - `sRawBands` format: `<GSM, hex, 16-bit>[,<WCDMA, hex, 16-bit>[,<LTE, hex, 64-bit>]]`;
                * - example `sRawBands` content: `5,F,800C5`.
                *
                * For Quectel radios:
                *
                * - command: `AT+QCFG="band"`;
                * - example radio response: `+QCFG: "band",0x93,0x80800c5,0x0`;
                * - `sRawBands` format: `<GW_band, hex, 16-bit>,<GW_band, hex, 16-bit>,<LTE, hex, 64-bit>`,
                *   NOTE: the `<GW_band>` value is duplicated for the first two fields;
                * - example `sRawBands` content: `93,93,80800c5`.
                *
                * @param sRawBands - radio-depended string value, shows the currently selected bands.
                *
                * @return CODE::SUCCESS when fetched successfully,
                *         CODE::NOT_APPLICABLE when the modem doesn't support this feature,
                *         CODE::NO_RESPONSE when the modem doesn't respond,
                *         CODE::ERROR when the radio returns "ERROR",
                *         CODE::FAILURE otherwise (unexpected response).
                */
                virtual CODE getSelectedBandsRaw(std::string& sRawBands) = 0;

                /**
                * @brief Get the list of PDP contexts from the radio
                * NOTE: authType, password and username are only present if the radio supports Cellular Authentication on
                * the PDP Context Level. “password” and “username” are only present if the current authentication type is
                * other than NONE. The “password” field is omitted on radios that do not allow reading the current password (i.e. on Telit LE910Cx).
                *
                * @param jData - an object to be filled with data.
                *                   {
                *                       "context_number : STRING": {
                *                           "apn" : "apn_value: STRING",
                *                           "authType" : "auth_type_value: STRING",
                *                           "ipMode" : "ip_mode_value: STRING",
                *                           "password" : "password_value (optional): STRING",
                *                           "username" : "username_value (optional): STRING"
                *                       }
                *                   }
                *
                * @return CODE::SUCCESS when fetched successfully,
                *         CODE::NO_RESPONSE when the modem doesn't respond,
                *         CODE::ERROR when the radio returns "ERROR",
                *         CODE::FAILURE otherwise (unexpected response).
                */
                virtual CODE getPdpContexts(Json::Value& jData) = 0;

                /**
                * @brief Set the PDP context to the radio. If any of the fields are omitted,
                *        the system re-uses the current configuration for such fields.
                *        If all fields are omitted - the system deletes the context.
                *        "username" and "password" are mandatory if "ipMode" is PAP, CHAP or PAP-CHAP.
                *        "username", "password" and "authType" shall be omitted on radios that do NOT
                *         support Cellular Authentication on the PDP Context Level.
                *
                * @param sId     - ID of the PDP context that should be edited.
                * @param jConfig - a JSON object that contains:
                *                     {
                *                          "apn" : "apn_value (optional): STRING",
                *                          "authType" : "auth_type_value (optional): STRING",
                *                          "ipMode" : "ip_mode_value (optional): STRING",
                *                          "password" : "password_value (optional): STRING",
                *                          "username" : "username_value (optional): STRING"
                *                     }
                *
                * @return CODE::SUCCESS when fetched successfully,
                *         CODE::NO_RESPONSE when the modem doesn't respond,
                *         CODE::ERROR when the radio returns "ERROR",
                *         CODE::INVALID_ARGS when one of the JSON object values is incorrect OR not supported by the current radio,
                *         CODE::FAILURE otherwise (unexpected response).
                */
                virtual CODE setPdpContext(const std::string& sId, const Json::Value& jConfig) = 0;

                /**
                 * @brief Execute the diagnostics AT commands and capture their output
                 *
                 * NOTE: The list of diagnostic AT commands is radio-specific and changes
                 * depending on the radio model (code).
                 *
                 * NOTE: The method stops its execution if the radio repeatedly ignores
                 * the commands (returns no execution result for several of them). This
                 * is required to limit the maximum execution time of the function and
                 * prevent the process from occupying the radio for too long. In case
                 * of timeout, the report will contain the output of all commands that
                 * it managed to execute before the failure.
                 *
                 * @param sDiagReport - the AT commands execution report.
                 *
                 * @return CODE::SUCCESS when fetched successfully,
                 *         CODE::NO_RESPONSE when the radio ignored several of the AT commands,
                 *         CODE::FAILURE otherwise.
                 */
                virtual CODE getDiagnostics(std::string& sDiagReport) = 0;
        };
    }
}

#endif