Merge branch 'mtr-mtq-sim-status' into quectel-radio

4 files changed, 93 insertions, 0 deletions

diff --git a/include/mts/MTS_IO_CellularRadio.h b/include/mts/MTS_IO_CellularRadio.h
index 899ceeb..9866d73 100644
--- a/include/mts/MTS_IO_CellularRadio.h
+++ b/include/mts/MTS_IO_CellularRadio.h
@@ -61,6 +61,7 @@ namespace MTS {
                 CODE getMeid(std::string& sMeid) override;
                 CODE getImsi(std::string& sImsi) override;
                 CODE getSimStatus(std::string& sSimStatus) override;
+                CODE getSimStatusSummary(Json::Value& jData) override;
                 CODE getLac(std::string& sLac) override;
                 CODE getMdn(std::string& sMdn) override;
                 CODE getMsid(std::string& sMsid) override;
@@ -75,6 +76,9 @@ namespace MTS {
 
                 CODE getRegistration(REGISTRATION& eRegistration) override;
                 CODE convertRegistrationToString(REGISTRATION eRegistration, std::string& sRegistration) override;
+
+                CODE unlockSimCard(const Json::Value& jArgs) override;
+
                 CODE getMipProfile(Json::Value& jMipProfile) override;
                 CODE validateMsl(const Json::Value& jArgs) override;
                 CODE setMsid(const Json::Value& jArgs) override;
@@ -122,6 +126,40 @@ namespace MTS {
 
                 virtual void getCommonNetworkStats(Json::Value& jData);
 
+                /**
+                 * @brief getIsSimInserted - returns if the SIM card is inserted / installed or not.
+                 *
+                 * @param bData - an object to be filled with the SIM card insertion status.
+                 *        `true` when SIM card is inserted / installed / present,
+                 *        `false` otherwise.
+                 * @return CODE::SUCCESS when SIM insertion status is fetched successfully,
+                 *         CODE::NOT_APPLICABLE when the modem doesn't support this feature,
+                 *         CODE::ERROR otherwise (when modem is inaccessible or in other cases).
+                 */
+                virtual CODE getIsSimInserted(bool& bData) = 0;
+
+                /**
+                 * @brief getSimLockStatus - return the SIM lock status as defined by AT+CPIN? command.
+                 *        Returns "READY", "SIM PIN", "SIM PUK" or other SIM status.
+                 *
+                 * @param sData - an object to be filled with the SIM lock status
+                 * @return CODE::SUCCESS when SIM status is fetched successfully,
+                 *         CODE::NOT_APPLICABLE when the modem doesn't support this feature,
+                 *         CODE::ERROR otherwise (SIM card removed, modem is inaccessible, etc).
+                 */
+                virtual CODE getSimLockStatus(std::string& sData);
+
+                /**
+                 * @brief getSimLockAttempts - get the number of SIM unlock attempts left.
+                 *
+                 * @param iAttemptsPin - the number of attempts left to enter a PIN code.
+                 * @param iAttemptsPuk - the number of attempts left to enter a PUK code.
+                 * @return CODE::SUCCESS when both numbers are fetched successfully,
+                 *         CODE::NOT_APPLICABLE when the modem doesn't support this feature,
+                 *         CODE::ERROR otherwise (SIM card removed, modem is inaccessible, etc).
+                 */
+                virtual CODE getSimLockAttempts(int& iAttemptsPin, int& iAttemptsPuk) = 0;
+
                 void initMipProfile(Json::Value& jData);
                 bool splitAndAssign(const std::string& sLine, const std::string& sKey, Json::Value& jParent, const std::string& sJsonKey, Json::ValueType eType = Json::ValueType::stringValue);
 
diff --git a/include/mts/MTS_IO_ICellularRadio.h b/include/mts/MTS_IO_ICellularRadio.h
index 1b95a0d..2d47fcf 100644
--- a/include/mts/MTS_IO_ICellularRadio.h
+++ b/include/mts/MTS_IO_ICellularRadio.h
@@ -168,6 +168,12 @@ namespace MTS {
                 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
 
                 //Values - Type
                 static const char *VALUE_TYPE_LTE;
@@ -213,6 +219,29 @@ namespace MTS {
                 virtual CODE getMeid(std::string& sMeid) = 0;
                 virtual CODE getImsi(std::string& sImsi) = 0;
                 virtual CODE getSimStatus(std::string& sSimStatus) = 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;
@@ -235,6 +264,25 @@ namespace MTS {
 
                 virtual CODE getRadioMode(RADIOMODE &mode) = 0;
                 virtual CODE setRadioMode(RADIOMODE mode) = 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;
 
                 //! Gather details of the radio's Mobile IP Profile
                 /*!
diff --git a/include/mts/MTS_IO_QuectelRadio.h b/include/mts/MTS_IO_QuectelRadio.h
index 0ca7f3b..3e5886c 100644
--- a/include/mts/MTS_IO_QuectelRadio.h
+++ b/include/mts/MTS_IO_QuectelRadio.h
@@ -50,6 +50,9 @@ namespace MTS {
                 bool getCarrierFromFirmware(const std::string& sFirmware, std::string& sCarrier) override;
                 bool getHardwareVersionFromFirmware(const std::string& sFirmware, std::string& sHardware) override;
 
+                CODE getIsSimInserted(bool& bData) override;
+                CODE getSimLockAttempts(int& iAttemptsPin, int& iAttemptsPuk) override;
+
                 virtual CODE getServiceDomain(SERVICEDOMAIN& sd);
                 virtual CODE convertToActiveBand(const std::string& sQuectelBand, ACTIVEBAND& band);
 
diff --git a/include/mts/MTS_IO_TelitRadio.h b/include/mts/MTS_IO_TelitRadio.h
index 47d6cf6..08b144c 100644
--- a/include/mts/MTS_IO_TelitRadio.h
+++ b/include/mts/MTS_IO_TelitRadio.h
@@ -48,7 +48,11 @@ namespace MTS {
                 bool getCarrierFromFirmware(const std::string& sFirmware, std::string& sCarrier) override;
                 bool getHardwareVersionFromFirmware(const std::string& sFirmware, std::string& sHardware) override;
 
+                CODE getIsSimInserted(bool& bData) override;
+                CODE getSimLockAttempts(int& iAttemptsPin, int& iAttemptsPuk) override;
+
             private:
+                virtual CODE getSimLockAttempts(int& iAttemptsPin, int& iAttemptsPuk, const std::string& sLockStatus);
 
         };
     }