ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #7768 from jarvte/document_all_cellular_errcodes 

Cellular: Document all possible error codes for cellular API.
pull/7890/head
Cruz Monrreal 2018-08-21 09:42:55 -05:00 committed by GitHub
parent 08afaf2f85 9f5a71a7bb
commit cd0126ae29
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 180 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
features/cellular/framework/API/CellularInformation.h
View File

@ -42,7 +42,8 @@ public:
* *
* @param buf manufacturer identification as zero terminated string * @param buf manufacturer identification as zero terminated string
* @param buf_size max length of manufacturer identification is 2048 characters * @param buf_size max length of manufacturer identification is 2048 characters
* @return zero on success, on failure negative error code * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t get_manufacturer(char *buf, size_t buf_size) = 0; virtual nsapi_error_t get_manufacturer(char *buf, size_t buf_size) = 0;
@ -50,7 +51,8 @@ public:
* *
* @param buf model identification as zero terminated string * @param buf model identification as zero terminated string
* @param buf_size max length of model identification is 2048 characters * @param buf_size max length of model identification is 2048 characters
* @return zero on success, on failure negative error code * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t get_model(char *buf, size_t buf_size) = 0; virtual nsapi_error_t get_model(char *buf, size_t buf_size) = 0;
@ -58,7 +60,8 @@ public:
* *
* @param buf revision identification as zero terminated string * @param buf revision identification as zero terminated string
* @param buf_size max length of revision identification is 2048 characters * @param buf_size max length of revision identification is 2048 characters
* @return zero on success, on failure negative error code * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t get_revision(char *buf, size_t buf_size) = 0; virtual nsapi_error_t get_revision(char *buf, size_t buf_size) = 0;
@ -67,7 +70,9 @@ public:
* @param buf serial number as zero terminated string * @param buf serial number as zero terminated string
* @param buf_size max length of serial number is 2048 characters * @param buf_size max length of serial number is 2048 characters
* @param type serial number type to read * @param type serial number type to read
* @return zero on success, on failure negative error code * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_UNSUPPORTED if the modem does not support SerialNumberType
* NSAPI_ERROR_DEVICE_ERROR on other failures
*/ */
enum SerialNumberType { enum SerialNumberType {
SN = 0, // Serial Number SN = 0, // Serial Number

149
features/cellular/framework/API/CellularNetwork.h
View File

@ -226,21 +226,24 @@ public:
/** Does all the needed initializations that can fail /** Does all the needed initializations that can fail
* *
* @remark must be called immediately after constructor. * @remark must be called immediately after constructor.
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_MEMORY on memory failure
*/ */
virtual nsapi_error_t init() = 0; virtual nsapi_error_t init() = 0;
/** Request registering to network. /** Request registering to network.
* *
* @param plmn format is in numeric format or 0 for automatic network registration * @param plmn format is in numeric format or 0 for automatic network registration
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t set_registration(const char *plmn = 0) = 0; virtual nsapi_error_t set_registration(const char *plmn = 0) = 0;
/** Get the current network registering mode /** Get the current network registering mode
* *
* @param mode on successful return contains the current network registering mode * @param mode on successful return contains the current network registering mode
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t get_network_registering_mode(NWRegisteringMode &mode) = 0; virtual nsapi_error_t get_network_registering_mode(NWRegisteringMode &mode) = 0;
@ -249,17 +252,21 @@ public:
* After successful call network class starts to get information about network changes like * After successful call network class starts to get information about network changes like
* registration statue, access technology, cell id... * registration statue, access technology, cell id...
* *
* @param type RegistrationType to set urc on/off * @param type RegistrationType to set urc on/off
* @param on Controls are urc' active or not * @param on Controls are urc active or not
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_UNSUPPORTED if the modem does not support RegistrationType
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t set_registration_urc(RegistrationType type, bool on) = 0; virtual nsapi_error_t set_registration_urc(RegistrationType type, bool on) = 0;
/** Gets the network registration status. /** Gets the network registration status.
* *
* @param type see RegistrationType values * @param type see RegistrationType values
* @param status see RegistrationStatus values * @param status see RegistrationStatus values
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_UNSUPPORTED if the modem does not support RegistrationType
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t get_registration_status(RegistrationType type, RegistrationStatus &status) = 0; virtual nsapi_error_t get_registration_status(RegistrationType type, RegistrationStatus &status) = 0;
@ -268,7 +275,8 @@ public:
* @param apn Optional name of the network to connect to * @param apn Optional name of the network to connect to
* @param username Optional username for the APN * @param username Optional username for the APN
* @param password Optional password fot the APN * @param password Optional password fot the APN
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_MEMORY on memory failure
*/ */
virtual nsapi_error_t set_credentials(const char *apn, virtual nsapi_error_t set_credentials(const char *apn,
const char *username = 0, const char *password = 0) = 0; const char *username = 0, const char *password = 0) = 0;
@ -279,7 +287,8 @@ public:
* @param type Authentication type to use * @param type Authentication type to use
* @param username Optional username for the APN * @param username Optional username for the APN
* @param password Optional password fot the APN * @param password Optional password fot the APN
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_MEMORY on memory failure
*/ */
virtual nsapi_error_t set_credentials(const char *apn, AuthenticationType type, virtual nsapi_error_t set_credentials(const char *apn, AuthenticationType type,
const char *username = 0, const char *password = 0) = 0; const char *username = 0, const char *password = 0) = 0;
@ -287,22 +296,25 @@ public:
/** Request attach to network. /** Request attach to network.
* *
* @deprecated Parameter timeout will be deprecated. Use mbed-os/features/cellular/framework/API/CellularDevice.h set_timeout instead. * @deprecated Parameter timeout will be deprecated. Use mbed-os/features/cellular/framework/API/CellularDevice.h set_timeout instead.
* @param timeout milliseconds to wait for attach response * @param timeout milliseconds to wait for attach response
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
MBED_DEPRECATED_SINCE("mbed-os-5.9", "Parameter timeout will be deprecated. Use mbed-os/features/cellular/framework/API/CellularDevice.h set_timeout instead.") MBED_DEPRECATED_SINCE("mbed-os-5.9", "Parameter timeout will be deprecated. Use mbed-os/features/cellular/framework/API/CellularDevice.h set_timeout instead.")
virtual nsapi_error_t set_attach(int timeout = 10 * 1000) = 0; virtual nsapi_error_t set_attach(int timeout = 10 * 1000) = 0;
/** Request attach status from network. /** Request attach status from network.
* *
* @param status see AttachStatus values * @param status see AttachStatus values
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t get_attach(AttachStatus &status) = 0; virtual nsapi_error_t get_attach(AttachStatus &status) = 0;
/** Request detach from a network. /** Request detach from a network.
* *
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t detach() = 0; virtual nsapi_error_t detach() = 0;
@ -312,7 +324,8 @@ public:
* @param reports Additional exception reports at maximum rate reached are allowed to be sent [optional] * @param reports Additional exception reports at maximum rate reached are allowed to be sent [optional]
* @param time_unit Uplink time unit with values 0=unrestricted, 1=minute, 2=hour, 3=day, 4=week [optional] * @param time_unit Uplink time unit with values 0=unrestricted, 1=minute, 2=hour, 3=day, 4=week [optional]
* @param uplink_rate Maximum number of messages per timeUnit [optional] * @param uplink_rate Maximum number of messages per timeUnit [optional]
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on case of failure
*/ */
virtual nsapi_error_t get_rate_control(CellularNetwork::RateControlExceptionReports &reports, virtual nsapi_error_t get_rate_control(CellularNetwork::RateControlExceptionReports &reports,
CellularNetwork::RateControlUplinkTimeUnit &time_unit, int &uplink_rate) = 0; CellularNetwork::RateControlUplinkTimeUnit &time_unit, int &uplink_rate) = 0;
@ -320,29 +333,36 @@ public:
/** Get backoff timer value /** Get backoff timer value
* *
* @param backoff_timer Backoff timer value associated with PDP APN in seconds * @param backoff_timer Backoff timer value associated with PDP APN in seconds
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_PARAMETER if no access point is set or found when activating context
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t get_apn_backoff_timer(int &backoff_timer) = 0; virtual nsapi_error_t get_apn_backoff_timer(int &backoff_timer) = 0;
/** Sets radio access technology. /** Sets radio access technology.
* *
* @param rat Radio access technology * @param rat Radio access technology
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_UNSUPPORTED if the given rat is RAT_UNKNOWN or inheriting target class
* has not implemented method set_access_technology_impl(...)
* OR return value of the inheriting target class set_access_technology_impl(...)
*/ */
virtual nsapi_error_t set_access_technology(RadioAccessTechnology rat) = 0; virtual nsapi_error_t set_access_technology(RadioAccessTechnology rat) = 0;
/** Get current radio access technology. /** Get current radio access technology.
* *
* @param rat Radio access technology * @param rat Radio access technology
* @return zero on success * @return NSAPI_ERROR_OK
*/ */
virtual nsapi_error_t get_access_technology(RadioAccessTechnology &rat) = 0; virtual nsapi_error_t get_access_technology(RadioAccessTechnology &rat) = 0;
/** Scans for operators module can reach. /** Scans for operators module can reach.
* *
* @param operators Container of reachable operators and their access technologies * @param operators Container of reachable operators and their access technologies
* @param ops_count Number of found operators * @param ops_count Number of found operators
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_MEMORY on memory failure
* NSAPI_ERROR_DEVICE_ERROR on other failures
*/ */
virtual nsapi_error_t scan_plmn(operList_t &operators, int &ops_count) = 0; virtual nsapi_error_t scan_plmn(operList_t &operators, int &ops_count) = 0;
@ -350,7 +370,8 @@ public:
* *
* @param supported_opt Supported CIoT EPS optimizations. * @param supported_opt Supported CIoT EPS optimizations.
* @param preferred_opt Preferred CIoT EPS optimizations. * @param preferred_opt Preferred CIoT EPS optimizations.
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t set_ciot_optimization_config(Supported_UE_Opt supported_opt, virtual nsapi_error_t set_ciot_optimization_config(Supported_UE_Opt supported_opt,
Preferred_UE_Opt preferred_opt) = 0; Preferred_UE_Opt preferred_opt) = 0;
@ -359,14 +380,20 @@ public:
* *
* @param supported_opt Supported CIoT EPS optimizations. * @param supported_opt Supported CIoT EPS optimizations.
* @param preferred_opt Preferred CIoT EPS optimizations. * @param preferred_opt Preferred CIoT EPS optimizations.
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t get_ciot_optimization_config(Supported_UE_Opt &supported_opt, virtual nsapi_error_t get_ciot_optimization_config(Supported_UE_Opt &supported_opt,
Preferred_UE_Opt &preferred_opt) = 0; Preferred_UE_Opt &preferred_opt) = 0;
/** Start the interface. Attempts to connect to a cellular network. /** Start the interface. Attempts to connect to a cellular network.
* *
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_CONNECTION if fails to find suitable context to activate or activation failed (if not already activated)
* NSAPI_ERROR_UNSUPPORTED if NetworkStack was not found
* NSAPI_ERROR_AUTH_FAILURE if password and username were provided and authentication to network failed
* Also if PPP mode
* NSAPI_ERROR_DEVICE_ERROR on failure and check more error from nsapi_ppp_connect(...)
*/ */
virtual nsapi_error_t connect() = 0; virtual nsapi_error_t connect() = 0;
@ -375,7 +402,13 @@ public:
* @param apn Optional name of the network to connect to * @param apn Optional name of the network to connect to
* @param username Optional username for your APN * @param username Optional username for your APN
* @param password Optional password for your APN * @param password Optional password for your APN
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_CONNECTION if fails to find suitable context to activate or activation failed (if not already activated)
* NSAPI_ERROR_UNSUPPORTED if NetworkStack was not found
* NSAPI_ERROR_AUTH_FAILURE if password and username were provided and authentication to network failed
* NSAPI_ERROR_NO_MEMORY on memory failure
* Also if PPP mode
* NSAPI_ERROR_DEVICE_ERROR on failure and check more error from nsapi_ppp_connect(...)
*/ */
virtual nsapi_error_t connect(const char *apn, virtual nsapi_error_t connect(const char *apn,
const char *username = 0, const char *password = 0) = 0; const char *username = 0, const char *password = 0) = 0;
@ -383,7 +416,10 @@ public:
/** Finds the correct PDP context and activates it. If correct PDP context is not found, one is created. /** Finds the correct PDP context and activates it. If correct PDP context is not found, one is created.
* Given APN (or not given) and stack type (IPv4/IPv6/dual) are influencing when finding the PDP context. * Given APN (or not given) and stack type (IPv4/IPv6/dual) are influencing when finding the PDP context.
* *
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_CONNECTION if fails to find suitable context to activate or activation failed (if not already activated)
* NSAPI_ERROR_UNSUPPORTED if NetworkStack was not found
* NSAPI_ERROR_AUTH_FAILURE if password and username were provided and authentication to network failed
*/ */
virtual nsapi_error_t activate_context() = 0; virtual nsapi_error_t activate_context() = 0;
@ -392,7 +428,8 @@ public:
* *
* @param stack_type the stack type to be used. * @param stack_type the stack type to be used.
* *
* @return NSAPI_ERROR_OK on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_PARAMETER if modem does not support the given stack_type
*/ */
virtual nsapi_error_t set_stack_type(nsapi_ip_stack_t stack_type) = 0; virtual nsapi_error_t set_stack_type(nsapi_ip_stack_t stack_type) = 0;
@ -406,35 +443,39 @@ public:
/** Get the relevant information for an active non secondary PDP context. /** Get the relevant information for an active non secondary PDP context.
* *
* @remark optional params are not updated if not received from network. * @remark optional params are not updated if not received from network.
* @param params_list reference to linked list which is filled on successful call * @param params_list reference to linked list, which is filled on successful call
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_MEMORY on memory failure
* NSAPI_ERROR_DEVICE_ERROR on other failures
*/ */
virtual nsapi_error_t get_pdpcontext_params(pdpContextList_t &params_list) = 0; virtual nsapi_error_t get_pdpcontext_params(pdpContextList_t &params_list) = 0;
/** Get extended signal quality parameters. /** Get extended signal quality parameters.
* *
* @param rxlev signal strength level * @param rxlev signal strength level
* @param ber bit error rate * @param ber bit error rate
* @param rscp signal code power * @param rscp signal code power
* @param ecno ratio of the received energy per PN chip to the total received power spectral density * @param ecno ratio of the received energy per PN chip to the total received power spectral density
* @param rsrq signal received quality * @param rsrq signal received quality
* @param rsrp signal received power * @param rsrp signal received power
* @return NSAPI_ERROR_OK on success, negative error code on failure * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on other failures
*/ */
virtual nsapi_error_t get_extended_signal_quality(int &rxlev, int &ber, int &rscp, int &ecno, int &rsrq, int &rsrp) = 0; virtual nsapi_error_t get_extended_signal_quality(int &rxlev, int &ber, int &rscp, int &ecno, int &rsrq, int &rsrp) = 0;
/** Get signal quality parameters. /** Get signal quality parameters.
* *
* @param rssi signal strength level * @param rssi signal strength level
* @param ber bit error rate * @param ber bit error rate
* @return NSAPI_ERROR_OK on success, negative error code on failure * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on other failures
*/ */
virtual nsapi_error_t get_signal_quality(int &rssi, int &ber) = 0; virtual nsapi_error_t get_signal_quality(int &rssi, int &ber) = 0;
/** Get cell id. /** Get cell id.
* *
* @param cell_id cell id * @param cell_id cell ID
* @return NSAPI_ERROR_OK on success, negative error code on failure * @return NSAPI_ERROR_OK
*/ */
virtual nsapi_error_t get_cell_id(int &cell_id) = 0; virtual nsapi_error_t get_cell_id(int &cell_id) = 0;
@ -445,9 +486,10 @@ public:
/** Get the operator parameters. /** Get the operator parameters.
* *
* @param format format of the operator field * @param format format of the operator field
* @param operator_params applicable operator param fields filled * @param operator_params applicable operator param fields filled
* @return NSAPI_ERROR_OK on success, negative error code on failure * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on case of other failures
*/ */
virtual nsapi_error_t get_operator_params(int &format, operator_t &operator_params) = 0; virtual nsapi_error_t get_operator_params(int &format, operator_t &operator_params) = 0;
@ -470,14 +512,17 @@ public:
/** Set blocking status of connect() which by default should be blocking /** Set blocking status of connect() which by default should be blocking
* *
* @param blocking true if connect is blocking * @param blocking true if connect is blocking
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK
* if PPP mode check errors from nsapi_ppp_set_blocking(...)
*/ */
virtual nsapi_error_t set_blocking(bool blocking) = 0; virtual nsapi_error_t set_blocking(bool blocking) = 0;
/** Read operator names /** Read operator names
* *
* @param op_names on successful return will contain linked list of operator names. * @param op_names on successful return contains linked list of operator names.
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_MEMORY on memory failure
* NSAPI_ERROR_DEVICE_ERROR on other failures
*/ */
virtual nsapi_error_t get_operator_names(operator_names_list &op_names) = 0; virtual nsapi_error_t get_operator_names(operator_names_list &op_names) = 0;
}; };

33
features/cellular/framework/API/CellularPower.h
View File

@ -53,7 +53,8 @@ public:
* *
* @remark set_at_mode must be called to initialise modem * @remark set_at_mode must be called to initialise modem
* *
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_UNSUPPORTED if not overridden by the target modem
*/ */
virtual nsapi_error_t on() = 0; virtual nsapi_error_t on() = 0;
@ -61,8 +62,8 @@ public:
* Device power on/off is modem/board specific behavior and must be done on inherited class if needed. * Device power on/off is modem/board specific behavior and must be done on inherited class if needed.
* Power off is done by toggling power pin/button. * Power off is done by toggling power pin/button.
* *
* * @return NSAPI_ERROR_OK on success
* @return zero on success * NSAPI_ERROR_UNSUPPORTED if not overridden by the target modem
*/ */
virtual nsapi_error_t off() = 0; virtual nsapi_error_t off() = 0;
@ -70,7 +71,8 @@ public:
* *
* @remark must be called after power on to prepare correct AT mode * @remark must be called after power on to prepare correct AT mode
* *
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t set_at_mode() = 0; virtual nsapi_error_t set_at_mode() = 0;
@ -88,23 +90,27 @@ public:
* *
* @remark See 3GPP TS 27.007 CFUN for more details * @remark See 3GPP TS 27.007 CFUN for more details
* *
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t set_power_level(int func_level, int do_reset = 0) = 0; virtual nsapi_error_t set_power_level(int func_level, int do_reset = 0) = 0;
/** Reset and wake-up cellular device. /** Reset and wake-up cellular device.
* *
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t reset() = 0; virtual nsapi_error_t reset() = 0;
/** Opt for power save setting on cellular device. If both parameters are zero then disables PSM. /** Opt for power save setting on cellular device. If both parameters are zero, this disables PSM.
* *
* @remark See 3GPP TS 27.007 PSM for details * @remark See 3GPP TS 27.007 PSM for details
* *
* @param periodic_time Timeout in seconds IoT subsystem is not expecting messaging * @param periodic_time Timeout in seconds IoT subsystem is not expecting messaging
* @param active_time Timeout in seconds IoT subsystem waits for response * @param active_time Timeout in seconds IoT subsystem waits for response
* @return zero on success *
* @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t opt_power_save_mode(int periodic_time, int active_time) = 0; virtual nsapi_error_t opt_power_save_mode(int periodic_time, int active_time) = 0;
@ -116,13 +122,15 @@ public:
* @param act_type type of access technology * @param act_type type of access technology
* @param edrx_value requested edxr value. Extended DRX parameters information element. * @param edrx_value requested edxr value. Extended DRX parameters information element.
* *
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t opt_receive_period(int mode, EDRXAccessTechnology act_type, uint8_t edrx_value) = 0; virtual nsapi_error_t opt_receive_period(int mode, EDRXAccessTechnology act_type, uint8_t edrx_value) = 0;
/** Check whether the device is ready to accept commands. /** Check whether the device is ready to accept commands.
* *
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t is_device_ready() = 0; virtual nsapi_error_t is_device_ready() = 0;
@ -131,7 +139,10 @@ public:
* for using at commands and possible sim. * for using at commands and possible sim.
* *
* @param callback Callback function called when urc received * @param callback Callback function called when urc received
* @return zero on success *
* @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_MEMORY on memory failure
* NSAPI_ERROR_UNSUPPORTED if not overridden by the target modem
*/ */
virtual nsapi_error_t set_device_ready_urc_cb(mbed::Callback<void()> callback) = 0; virtual nsapi_error_t set_device_ready_urc_cb(mbed::Callback<void()> callback) = 0;

29
features/cellular/framework/API/CellularSIM.h
View File

@ -54,30 +54,34 @@ public:
/** Open the SIM card by setting the pin code for SIM. /** Open the SIM card by setting the pin code for SIM.
* *
* @param sim_pin PIN for the SIM card * @param sim_pin PIN for the SIM card
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t set_pin(const char *sim_pin) = 0; virtual nsapi_error_t set_pin(const char *sim_pin) = 0;
/** Change sim pin code. /** Change SIM pin code.
* *
* @param sim_pin Current PIN for sim * @param sim_pin Current PIN for SIM
* @param new_pin New PIN for sim * @param new_pin New PIN for SIM
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t change_pin(const char *sim_pin, const char *new_pin) = 0; virtual nsapi_error_t change_pin(const char *sim_pin, const char *new_pin) = 0;
/** Change is pin query needed after boot /** Change is pin query needed after boot
* *
* @param sim_pin Valid PIN for SIM card * @param sim_pin Valid PIN for SIM card
* @param query_pin False is PIN query not needed, True if PIN query needed after boot. * @param query_pin False if PIN query not needed, True if PIN query needed after boot.
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t set_pin_query(const char *sim_pin, bool query_pin) = 0; virtual nsapi_error_t set_pin_query(const char *sim_pin, bool query_pin) = 0;
/** Get sim card's state /** Get SIM card's state
* *
* @param state current state of SIM * @param state current state of SIM
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t get_sim_state(SimState &state) = 0; virtual nsapi_error_t get_sim_state(SimState &state) = 0;
@ -85,7 +89,9 @@ public:
* @remark Given imsi buffer length must be 16 or more as imsi max length is 15! * @remark Given imsi buffer length must be 16 or more as imsi max length is 15!
* *
* @param imsi preallocated char* which after successful request contains imsi * @param imsi preallocated char* which after successful request contains imsi
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_PARAMETER if imsi if null
* NSAPI_ERROR_DEVICE_ERROR on other failures
*/ */
virtual nsapi_error_t get_imsi(char *imsi) = 0; virtual nsapi_error_t get_imsi(char *imsi) = 0;
@ -93,7 +99,8 @@ public:
* *
* @param buf SIM ICCID as zero terminated string * @param buf SIM ICCID as zero terminated string
* @param buf_size max length of SIM ICCID is MAX_ICCID_LENGTH * @param buf_size max length of SIM ICCID is MAX_ICCID_LENGTH
* @return zero on success, on failure negative error code * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t get_iccid(char *buf, size_t buf_size) = 0; virtual nsapi_error_t get_iccid(char *buf, size_t buf_size) = 0;
}; };

55
features/cellular/framework/API/CellularSMS.h
View File

@ -57,44 +57,53 @@ public:
CellularSMSMmodeText CellularSMSMmodeText
}; };
/** Does all the necessary initializations needed for receiving and sending sms. /** Does all the necessary initializations needed for receiving and sending SMS.
* *
* @param mode enumeration for choosing the correct mode: text/pdu * @param mode enumeration for choosing the correct mode: text/pdu
* @return zero on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_MEMORY on memory failure
* NSAPI_ERROR_DEVICE_ERROR on other failures
*/ */
virtual nsapi_error_t initialize(CellularSMSMmode mode) = 0; virtual nsapi_error_t initialize(CellularSMSMmode mode) = 0;
/** Send the SMS with the given parameters /** Send the SMS with the given parameters
* *
* @param phone_number Phone number where to send sms * @param phone_number Phone number where to send SMS
* @param message SMS message content * @param message SMS message content
* @param msg_len Length of the message * @param msg_len Length of the message
* @return possible error code or length of the sent sms * @return On success, length of the sent SMS (positive value)
* NSAPI_ERROR_PARAMETER if invalid parameters
* NSAPI_ERROR_NO_MEMORY on memory failure
* NSAPI_ERROR_DEVICE_ERROR on other failures
*/ */
virtual nsapi_size_or_error_t send_sms(const char *phone_number, const char *message, int msg_len) = 0; virtual nsapi_size_or_error_t send_sms(const char *phone_number, const char *message, int msg_len) = 0;
/** Gets the oldest received sms. /** Gets the oldest received sms.
* *
* @param buf preallocated buffer for sms message content * @param buf preallocated buffer for SMS message content
* @param buf_len length of allocated buf * @param buf_len length of allocated buf
* @param phone_num preallocated buffer for phone number where sms was sent * @param phone_num preallocated buffer for phone number where SMS was sent
* @param phone_len length of allocated phone_num buffer * @param phone_len length of allocated phone_num buffer
* @param time_stamp preallocated buffer for TP-Service Centre Time Stamp (format: yy/MM/dd,hh:mm:ss-+zz). +-zz is timezone. * @param time_stamp preallocated buffer for TP-Service Centre Time Stamp (format: yy/MM/dd,hh:mm:ss-+zz). +-zz is timezone.
* The unit of time zone is a quarter of an hour relative to GMT. For example +32 would be GMT+8. * The unit of time zone is a quarter of an hour relative to GMT. For example +32 would be GMT+8.
* @param time_len length of allocated time_stamp buffer * @param time_len length of allocated time_stamp buffer
* @param buf_size if method return error NSAPI_ERROR_NO_MEMORY because the given buf was not big enough this will * @param buf_size if method return error NSAPI_ERROR_NO_MEMORY because the given buf was not big enough, this
* hold the size which is enough. Otherwise zero. * holds the size which is enough. Otherwise zero.
* @return possible error code or size of buf. Will return SMS_ERROR_MULTIPART_ALL_PARTS_NOT_READ * @return On success, length of the received SMS, (length of the buf, positive value)
* if sms was multipart but not all parts are present/failed to read. * NSAPI_ERROR_PARAMETER if invalid parameters
* NSAPI_ERROR_NO_MEMORY on memory failure
* SMS_ERROR_MULTIPART_ALL_PARTS_NOT_READ if SMS was multipart but not all parts are present/failed to read.
* -1 if no SMS was found
* NSAPI_ERROR_DEVICE_ERROR on other failures
*/ */
virtual nsapi_size_or_error_t get_sms(char *buf, uint16_t buf_len, char *phone_num, uint16_t phone_len, virtual nsapi_size_or_error_t get_sms(char *buf, uint16_t buf_len, char *phone_num, uint16_t phone_len,
char *time_stamp, uint16_t time_len, int *buf_size) = 0; char *time_stamp, uint16_t time_len, int *buf_size) = 0;
/** Callback which is called when new sms is received. SMS can be fetched via method get_sms(). /** Callback that is called when new SMS is received. SMS can be fetched using method get_sms().
* *
* @remark In PDU mode there can be multipart sms and callback is called for every received part. * @remark In PDU mode, there can be multipart SMS, and callback is called for every received part.
* *
* @param func Callback function which is called when new sms is received. * @param func Callback function that is called when new SMS is received.
*/ */
virtual void set_sms_callback(Callback<void()> func) = 0; virtual void set_sms_callback(Callback<void()> func) = 0;
@ -110,7 +119,8 @@ public:
* "SM" - SIM SMS memory storage (default) * "SM" - SIM SMS memory storage (default)
* "ME" - NVM SMS storage * "ME" - NVM SMS storage
* *
* @return 1 for success, 0 for failure * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t set_cpms(const char *memr, const char *memw, const char *mems) = 0; virtual nsapi_error_t set_cpms(const char *memr, const char *memw, const char *mems) = 0;
@ -119,7 +129,8 @@ public:
* @param sca Service Center Address to be used for mobile originated SMS transmissions. * @param sca Service Center Address to be used for mobile originated SMS transmissions.
* @param type 129 - national numbering scheme, 145 - international numbering scheme (contains the character "+") * @param type 129 - national numbering scheme, 145 - international numbering scheme (contains the character "+")
* *
* @return 1 for success, 0 for failure * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t set_csca(const char *sca, int type) = 0; virtual nsapi_error_t set_csca(const char *sca, int type) = 0;
@ -127,22 +138,24 @@ public:
* *
* @remark Current implementation support only ASCII so choose the correct character set. * @remark Current implementation support only ASCII so choose the correct character set.
* *
* @param chr_set preferred character set list (comma separated). Modem might not support the wanted character set * @param chr_set preferred character set list (comma separated). Modem might not support the wanted character set,
* so chr_set list is looped from start until supported set is found. Used character set index is returned. * so chr_set list is looped from start until supported set is found. Used character set index is returned.
* See more from 3GPP TS 27.005. * See more from 3GPP TS 27.005.
* @return Used character set index from the given list in case of success. Otherwise negative errorcode. * @return Used character set index from the given list in case of success.
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_size_or_error_t set_cscs(const char *chr_set) = 0; virtual nsapi_size_or_error_t set_cscs(const char *chr_set) = 0;
/** Deletes all messages from the currently set memory/SIM /** Deletes all messages from the currently set memory/SIM
* *
* @return possible error code * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_DEVICE_ERROR on failure
*/ */
virtual nsapi_error_t delete_all_messages() = 0; virtual nsapi_error_t delete_all_messages() = 0;
/** Some modems need extra time between AT commands and responses or there will be error -314, SIM busy. /** Some modems need extra time between AT commands and responses, or there will be error -314, SIM busy.
* If SIM busy errors are an issue this time should be increased. It can also be set to zero to make * If SIM busy errors are an issue, this time should be increased. It can also be set to zero to make
* operations faster and more energy efficient if no errors will follow. By default wait time is zero. * operations faster and more energy efficient if no errors will follow. By default, wait time is zero.
* *
* @param sim_wait_time * @param sim_wait_time
*/ */