Skip to content

Cellular: update doxygen and add attach CellularDevice. #8852

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Dec 7, 2018
Merged

Cellular: update doxygen and add attach CellularDevice. #8852

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a3f1ad7
Cellular: updated doxygen for CellularContext and CellularDevice.
Nov 23, 2018
76672db
Cellular: add Callback functionality to CellularDevice.
Nov 27, 2018
411320a
Edit CellularDevice.h
Dec 6, 2018
446c428
Edit CellularContext.h
Dec 6, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 25 additions & 16 deletions features/cellular/framework/API/CellularContext.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,14 +98,24 @@ class CellularContext : public CellularBase {
// pointer for next item when used as a linked list
CellularContext *_next;
protected:
// friend of CellularDevice so that it's the only way to close/delete this class.
// friend of CellularDevice, so it's the only way to close or delete this class.
friend class CellularDevice;
virtual ~CellularContext() {}

public: // from NetworkInterface
virtual nsapi_error_t set_blocking(bool blocking) = 0;
virtual NetworkStack *get_stack() = 0;
virtual const char *get_ip_address() = 0;

/** Register callback for status reporting.
*
* The specified status callback function is called on the network, and the cellular device status changes.
* The parameters on the callback are the event type and event type dependent reason parameter.
*
* @remark deleting CellularDevice/CellularContext in callback is not allowed.
*
* @param status_cb The callback for status changes.
*/
virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0;
virtual nsapi_error_t connect() = 0;
virtual nsapi_error_t disconnect() = 0;
Expand All @@ -122,13 +132,13 @@ class CellularContext : public CellularBase {
static CellularContext *get_default_instance();


// Operations, can be sync/async. Also Connect() is this kind of operations, inherited from NetworkInterface above.
// Operations, can be sync/async. Also Connect() is this kind of operation, inherited from NetworkInterface above.

/** Start the interface
*
* Power on the device and does the initializations for communication with the modem..
* By default this API is synchronous. API can be set to asynchronous with method set_blocking(...).
* In synchronous and asynchronous mode application can get result in from callback which is set with
* Powers on the device and does the initializations for communication with the modem.
* By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
* In synchronous and asynchronous mode, the application can get result in from callback, which is set with
* attach(...)
*
* @return NSAPI_ERROR_OK on success
Expand All @@ -138,9 +148,9 @@ class CellularContext : public CellularBase {

/** Start the interface
*
* Attempts to open the sim.
* By default this API is synchronous. API can be set to asynchronous with method set_blocking(...).
* In synchronous and asynchronous mode application can get result in from callback which is set with
* Attempts to open the SIM.
* By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
* In synchronous and asynchronous mode, the application can get result in from callback, which is set with
* attach(...)
*
* @return NSAPI_ERROR_OK on success
Expand All @@ -151,8 +161,8 @@ class CellularContext : public CellularBase {
/** Start the interface
*
* Attempts to register the device to cellular network.
* By default this API is synchronous. API can be set to asynchronous with method set_blocking(...).
* In synchronous and asynchronous mode application can get result in from callback which is set with
* By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
* In synchronous and asynchronous mode, the application can get result in from callback, which is set with
* attach(...)
*
* @return NSAPI_ERROR_OK on success
Expand All @@ -163,8 +173,8 @@ class CellularContext : public CellularBase {
/** Start the interface
*
* Attempts to attach the device to cellular network.
* By default this API is synchronous. API can be set to asynchronous with method set_blocking(...).
* In synchronous and asynchronous mode application can get result in from callback which is set with
* By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
* In synchronous and asynchronous mode, the application can get result in from callback, which is set with
* attach(...)
*
* @return NSAPI_ERROR_OK on success
Expand All @@ -186,7 +196,7 @@ class CellularContext : public CellularBase {
virtual nsapi_error_t get_rate_control(CellularContext::RateControlExceptionReports &reports,
CellularContext::RateControlUplinkTimeUnit &time_unit, int &uplink_rate) = 0;

/** Get the relevant information for an active non secondary PDP context.
/** Get the relevant information for an active nonsecondary PDP context.
*
* @remark optional params are not updated if not received from network.
* @param params_list reference to linked list, which is filled on successful call
Expand All @@ -205,7 +215,7 @@ class CellularContext : public CellularBase {
*/
virtual nsapi_error_t get_apn_backoff_timer(int &backoff_timer) = 0;

/** Set the file handle used to communicate with the modem. Can be used to change default file handle.
/** Set the file handle used to communicate with the modem. You can use this to change the default file handle.
*
* @param fh file handle for communicating with the modem
*/
Expand All @@ -222,8 +232,7 @@ class CellularContext : public CellularBase {
OP_MAX = 5
};

/** Status callback function will be called on status changes on the network or CellularDevice
* by the CellularDevice.
/** The CellularDevice calls the status callback function on status changes on the network or CellularDevice.
*
* @param ev event type
* @param ptr event-type dependent reason parameter
Expand Down
59 changes: 35 additions & 24 deletions features/cellular/framework/API/CellularDevice.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@

#include "CellularTargets.h"
#include "CellularStateMachine.h"
#include "Callback.h"

namespace mbed {

Expand All @@ -38,13 +39,13 @@ const int MAX_PLMN_SIZE = 16;
* Class CellularDevice
*
* An abstract interface that defines opening and closing of cellular interfaces.
* Deleting/Closing of opened interfaces can be done only via this class.
* You can delete or close opened interfaces only through this class.
*/
class CellularDevice {
public:

/** Return singleton instance of CellularDevice if CELLULAR_DEVICE is defined. If CELLULAR_DEVICE is not
* defined then returns NULL. Implementation is marked as weak.
/** Returns singleton instance of CellularDevice if CELLULAR_DEVICE is defined. If CELLULAR_DEVICE is not
* defined, then it returns NULL. Implementation is marked as weak.
*
* @return CellularDevice* instance if any
*/
Expand All @@ -62,7 +63,7 @@ class CellularDevice {

/** Creates a new CellularContext interface.
*
* @param fh file handle used in communication to modem. Can be for example UART handle. If null then the default
* @param fh file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
* file handle is used.
* @param apn access point to use with context, can be null.
*
Expand Down Expand Up @@ -94,19 +95,18 @@ class CellularDevice {
void set_sim_pin(const char *sim_pin);

/** Plmn to use when registering to cellular network.
* If plmn is set then registering is forced to this plmn. If plmn is not set then automatic
* registering is used when registering to a cellular network. Does not start any operations.
* If plmn is set, then registering is forced to this plmn. If plmn is not set, then automatic
* registering is used when registering to a cellular network. It doesn't start any operations.
*
* @param plmn plmn used when registering to cellular network
*/
void set_plmn(const char *plmn);

/** Start the interface
*
* Power on the device and does the initializations for communication with the modem..
* By default this API is synchronous. API can be set to asynchronous with method set_blocking(...).
* In synchronous and asynchronous mode application can get result in from callback which is set with
* attach(...)
* Powers on the device and does the initializations for communication with the modem.
* API is asynchronous. Application can get results from CellularContext callback, which is set
* with attach(...), or callback, which is set by attach(...), in this class.
*
* @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_MEMORY on case of memory failure
Expand All @@ -116,9 +116,8 @@ class CellularDevice {
/** Start the interface
*
* Attempts to open the sim.
* By default this API is synchronous. API can be set to asynchronous with method set_blocking(...).
* In synchronous and asynchronous mode application can get result in from callback which is set with
* attach(...)
* API is asynchronous. Application can get results from CellularContext callback, which is set
* with attach(...), or callback, which is set by attach(...), in this class.
*
* @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_MEMORY on case of memory failure
Expand All @@ -128,9 +127,8 @@ class CellularDevice {
/** Start the interface
*
* Attempts to register the device to cellular network.
* By default this API is synchronous. API can be set to asynchronous with method set_blocking(...).
* In synchronous and asynchronous mode application can get result in from callback which is set with
* attach(...)
* API is asynchronous. Application can get results from CellularContext callback, which is set
* with attach(...), or callback, which is set by attach(...), in this class.
*
* @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_MEMORY on case of memory failure
Expand All @@ -140,50 +138,62 @@ class CellularDevice {
/** Start the interface
*
* Attempts to attach the device to cellular network.
* By default this API is synchronous. API can be set to asynchronous with method set_blocking(...).
* In synchronous and asynchronous mode application can get result in from callback which is set with
* attach(...)
* API is asynchronous. Application can get results from CellularContext callback, which is set
* with attach(...), or callback, which is set by attach(...), in this class.
*
* @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_MEMORY on case of memory failure
*/
nsapi_error_t attach_to_network();

/** Register callback for status reporting.
*
* The specified status callback function is called on the network, and the cellular device status changes.
* The parameters on the callback are the event type and event type dependent reason parameter.
*
* @remark deleting CellularDevice/CellularContext in callback is not allowed.
* @remark application should not attach to this function if it uses CellularContext::attach because it contains the
* same information.
*
* @param status_cb The callback for status changes.
*/
void attach(Callback<void(nsapi_event_t, intptr_t)> status_cb);

/** Create new CellularNetwork interface.
*
* @param fh file handle used in communication to modem. Can be for example UART handle. If null then the default
* @param fh file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
* file handle is used.
* @return New instance of interface CellularNetwork.
*/
virtual CellularNetwork *open_network(FileHandle *fh = NULL) = 0;

/** Create new CellularSMS interface.
*
* @param fh file handle used in communication to modem. Can be for example UART handle. If null then the default
* @param fh file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
* file handle is used.
* @return New instance of interface CellularSMS.
*/
virtual CellularSMS *open_sms(FileHandle *fh = NULL) = 0;

/** Create new CellularPower interface.
*
* @param fh file handle used in communication to modem. Can be for example UART handle. If null then the default
* @param fh file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
* file handle is used.
* @return New instance of interface CellularPower.
*/
virtual CellularPower *open_power(FileHandle *fh = NULL) = 0;

/** Create new CellularSIM interface.
*
* @param fh file handle used in communication to modem. Can be for example UART handle. If null then the default
* @param fh file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
* file handle is used.
* @return New instance of interface CellularSIM.
*/
virtual CellularSIM *open_sim(FileHandle *fh = NULL) = 0;

/** Create new CellularInformation interface.
*
* @param fh file handle used in communication to modem. Can be for example UART handle. If null then the default
* @param fh file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
* file handle is used.
* @return New instance of interface CellularInformation.
*/
Expand Down Expand Up @@ -262,6 +272,7 @@ class CellularDevice {
char _sim_pin[MAX_PIN_SIZE + 1];
char _plmn[MAX_PLMN_SIZE + 1];
PlatformMutex _mutex;
Callback<void(nsapi_event_t, intptr_t)> _status_cb;
};

} // namespace mbed
Expand Down
12 changes: 11 additions & 1 deletion features/cellular/framework/device/CellularDevice.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ MBED_WEAK CellularDevice *CellularDevice::get_default_instance()
#endif // CELLULAR_DEVICE

CellularDevice::CellularDevice(FileHandle *fh) : _network_ref_count(0), _sms_ref_count(0), _power_ref_count(0), _sim_ref_count(0),
_info_ref_count(0), _fh(fh), _queue(5 * EVENTS_EVENT_SIZE), _state_machine(0), _nw(0)
_info_ref_count(0), _fh(fh), _queue(5 * EVENTS_EVENT_SIZE), _state_machine(0), _nw(0), _status_cb(0)
{
set_sim_pin(NULL);
set_plmn(NULL);
Expand Down Expand Up @@ -158,6 +158,11 @@ nsapi_error_t CellularDevice::start_state_machine(CellularStateMachine::Cellular
return err;
}

void CellularDevice::attach(Callback<void(nsapi_event_t, intptr_t)> status_cb)
{
_status_cb = status_cb;
}

void CellularDevice::cellular_callback(nsapi_event_t ev, intptr_t ptr)
{
if (ev >= NSAPI_EVENT_CELLULAR_STATUS_BASE && ev <= NSAPI_EVENT_CELLULAR_STATUS_END) {
Expand Down Expand Up @@ -200,6 +205,11 @@ void CellularDevice::cellular_callback(nsapi_event_t ev, intptr_t ptr)
curr->cellular_callback(ev, ptr);
curr = curr->_next;
}

// forward to callback function if set by attach(...)
if (_status_cb) {
_status_cb(ev, ptr);
}
}

} // namespace mbed