Mistake on this page?
Report an issue in GitHub or email us
CellularDevice.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2017, Arm Limited and affiliates.
3  * SPDX-License-Identifier: Apache-2.0
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 
18 #ifndef CELLULAR_DEVICE_H_
19 #define CELLULAR_DEVICE_H_
20 
21 #include "CellularStateMachine.h"
22 #include "Callback.h"
23 #include "ATHandler.h"
24 #include "PinNames.h"
25 
26 #ifdef MBED_CONF_RTOS_PRESENT
27 #include "rtos/Thread.h"
28 #endif // MBED_CONF_RTOS_PRESENT
29 
30 /** @file CellularDevice.h
31  * @brief Class CellularDevice
32  *
33  */
34 namespace mbed {
35 
36 class CellularSMS;
37 class CellularInformation;
38 class CellularNetwork;
39 class CellularContext;
40 
41 const int MAX_PIN_SIZE = 8;
42 const int MAX_PLMN_SIZE = 16;
43 const int MAX_SIM_READY_WAITING_TIME = 30;
44 
45 /**
46  * @addtogroup cellular
47  * @{
48  */
49 
50 /**
51  * Class CellularDevice
52  *
53  * An abstract interface that defines opening and closing of cellular interfaces.
54  * You can delete or close opened interfaces only through this class.
55  */
57 public:
58  /* enumeration for possible SIM states */
59  enum SimState {
60  SimStateReady = 0,
61  SimStatePinNeeded,
62  SimStatePukNeeded,
63  SimStateUnknown
64  };
65 
66  /** Returns singleton instance of CellularDevice, if Mbed target board has a supported
67  * onboard modem, or provide-default is defined for a cellular driver in JSON configuration
68  * files. Otherwise returns NULL. See NetworkInterface::get_default_instance for details.
69  *
70  * @remark Application may override this (non-weak) default implementation.
71  *
72  * @return default CellularDevice, NULL if not defined
73  */
75 
76  /** Return target onboard instance of CellularDevice
77  *
78  * @remark Mbed OS target shall override (non-weak) this function for an onboard modem.
79  *
80  * @return CellularDevice* instance, NULL if not defined
81  */
83 
84  /** Default constructor
85  */
87 
88  /** virtual Destructor
89  */
90  virtual ~CellularDevice();
91 
92 public: //Virtual functions
93 
94  /** Shutdown cellular device to minimum functionality.
95  *
96  * Actual functionality is modem specific, for example UART may is not be responsive without
97  * explicit wakeup signal (such as RTS) after shutdown.
98  *
99  * @remark You must call shutdown before power off to prepare the modem and to quit cellular network.
100  *
101  * @return NSAPI_ERROR_OK on success
102  * NSAPI_ERROR_DEVICE_ERROR on failure
103  */
104  virtual nsapi_error_t shutdown();
105 
106  /** Get event queue that can be chained to main event queue.
107  * @return event queue
108  */
109  virtual events::EventQueue *get_queue();
110 
111 protected: //Virtual functions
112  /** Cellular callback to be attached to Network and CellularStateMachine classes.
113  * CellularContext calls this when in PPP mode to provide network changes.
114  * This method will broadcast to every interested classes:
115  * CellularContext (might be many) and CellularStateMachine if available.
116  */
117  virtual void cellular_callback(nsapi_event_t ev, intptr_t ptr, CellularContext *ctx = NULL);
118 
119 public: //Pure virtual functions
120 
121  /** Clear modem to a default initial state
122  *
123  * Clear persistent user data from the modem, such as PDP contexts.
124  *
125  * @pre All open network services on modem, such as contexts and sockets, must be closed.
126  * @post Modem power off/on may be needed to clear modem's runtime state.
127  * @remark CellularStateMachine calls this on connect when `cellular.clear-on-connect: true`.
128  *
129  * @return NSAPI_ERROR_OK on success, otherwise modem may be need power cycling
130  */
131  virtual nsapi_error_t clear() = 0;
132 
133 
134  /** Get the linked list of CellularContext instances
135  *
136  * @return Pointer to first item in linked list
137  */
138  virtual CellularContext *get_context_list() const = 0;
139 
140  /** Sets the modem up for powering on
141  * This is equivalent to plugging in the device, i.e., attaching power and serial port.
142  * In general, hard_power_on and soft_power_on provides a simple hardware abstraction layer
143  * on top of the modem drivers written for Mbed OS; they can be overridden
144  * in a derived class to perform custom power controls in a particular board configuration.
145  * In many boards this will be a no-op if there is no separate power supply control circuitry.
146  *
147  * @remark CellularStateMachine calls hard_power_on at first until successful,
148  * then soft_power_on and init until the modem responds.
149  * If you are not using CellularStateMachine then you need to call these functions yourself.
150  *
151  * @post You must call soft_power_on to power on the modem after calling hard_power_on.
152  *
153  * @return NSAPI_ERROR_OK on success
154  */
155  virtual nsapi_error_t hard_power_on() = 0;
156 
157  /** Sets the modem in unplugged state
158  *
159  * This is equivalent to pulling the plug off of the device, i.e.,
160  * detaching power and serial port.
161  *
162  * This puts the modem in the lowest power state.
163  *
164  * @remark CellularStateMachine disconnect or destruct does not shutdown or power off the modem,
165  * but you need to do that yourself.
166  *
167  * @pre You must call soft_power_off to power off the modem before calling hard_power_off.
168  *
169  * @return NSAPI_ERROR_OK on success
170  */
171  virtual nsapi_error_t hard_power_off() = 0;
172 
173  /** Powers up the modem
174  *
175  * This is equivalent to pressing the "power button" to activate or reset the modem
176  * and usually implemented as a short pulse on a dedicated GPIO signal.
177  * It is expected to be present to make it possible to reset the modem.
178  * The driver may repeat this if the modem is not responsive to AT commands.
179  *
180  * @remark CellularStateMachine calls this when requested to connect.
181  * If you are not using CellularStateMachine then you need to call this function yourself.
182  *
183  * @post You must call init to setup the modem.
184  *
185  * @return NSAPI_ERROR_OK on success
186  */
187  virtual nsapi_error_t soft_power_on() = 0;
188 
189  /** Powers down the modem
190  *
191  * This is equivalent to turning off the modem by button press.
192  *
193  * @remark CellularStateMachine disconnect or destruct does not shutdown or power off the modem,
194  * but you need to do that yourself.
195  *
196  * @pre You must call shutdown to prepare the modem for power off.
197  *
198  * @return NSAPI_ERROR_OK on success
199  */
200  virtual nsapi_error_t soft_power_off() = 0;
201 
202  /** Open the SIM card by setting the pin code for SIM.
203  *
204  * @param sim_pin PIN for the SIM card
205  * @return NSAPI_ERROR_OK on success
206  * NSAPI_ERROR_PARAMETER if sim_pin is null and sim is not ready
207  * NSAPI_ERROR_DEVICE_ERROR on failure
208  */
209  virtual nsapi_error_t set_pin(const char *sim_pin) = 0;
210 
211  /** Get SIM card's state
212  *
213  * @param state current state of SIM
214  * @return NSAPI_ERROR_OK on success
215  * NSAPI_ERROR_DEVICE_ERROR on failure
216  */
217  virtual nsapi_error_t get_sim_state(SimState &state) = 0;
218 
219  /** Creates a new CellularContext interface.
220  *
221  * @param fh file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
222  * file handle is used.
223  * @param apn access point to use with context, can be null.
224  * @param cp_req flag indicating if EPS control plane optimization is required
225  * @param nonip_req flag indicating if this context is required to be Non-IP
226  *
227  * @return new instance of class CellularContext or NULL in case of failure
228  *
229  */
230  virtual CellularContext *create_context(const char *apn = NULL, bool cp_req = false, bool nonip_req = false) = 0;
231 
232  /** Deletes the given CellularContext instance
233  *
234  * @param context CellularContext to delete
235  */
236  virtual void delete_context(CellularContext *context) = 0;
237 
238  /** Turn modem debug traces on
239  *
240  * @param on set true to enable debug traces
241  */
242  virtual void modem_debug_on(bool on) = 0;
243 
244  /** Initialize cellular device must be called right after the module is ready.
245  *
246  * For example, when multiple cellular modules are supported in a single driver this function
247  * detects and adapts to an actual module at runtime.
248  *
249  * @remark CellularStateMachine calls soft_power_on and init repeatedly when starting to connect
250  * until the modem responds.
251  *
252  * @return NSAPI_ERROR_OK on success
253  * NSAPI_ERROR_NO_MEMORY on case of memory failure
254  * NSAPI_ERROR_UNSUPPORTED if current cellular module type is not detected
255  * NSAPI_ERROR_DEVICE_ERROR if model information could not be read
256  *
257  */
258  virtual nsapi_error_t init() = 0;
259 
260  /** Check whether the device is ready to accept commands.
261  *
262  * @return NSAPI_ERROR_OK on success
263  * NSAPI_ERROR_DEVICE_ERROR on failure
264  */
265  virtual nsapi_error_t is_ready() = 0;
266 
267  /** Set callback function to listen when device is ready.
268  *
269  * @param callback function to call on device ready, or NULL to remove callback.
270  */
271  virtual void set_ready_cb(Callback<void()> callback) = 0;
272 
273  /** Set power save mode
274  *
275  * @remark See 3GPP TS 27.007 PSM for details
276  *
277  * @param periodic_time in seconds to enable power save, or zero to disable
278  * @param active_time in seconds to wait before entering power save mode
279  *
280  * @return NSAPI_ERROR_OK on success
281  * NSAPI_ERROR_DEVICE_ERROR on failure
282  */
283  virtual nsapi_error_t set_power_save_mode(int periodic_time, int active_time = 0) = 0;
284 
285  /** Get the current ATHandler instance in use for debug purposes etc.
286  *
287  * @return Pointer to the ATHandler in use, NULL if device is non-AT -device.
288  */
289  virtual ATHandler *get_at_handler() = 0;
290 
291  /** Sets cellular modem to given baud rate
292  *
293  * @param baud_rate
294  * @return NSAPI_ERROR_OK on success, NSAPI_ERROR_DEVICE_ERROR on failure
295  */
296  virtual nsapi_error_t set_baud_rate(int baud_rate) = 0;
297 
298  /** Create new CellularNetwork interface.
299  *
300  * @param fh file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
301  * file handle is used.
302  * @return New instance of interface CellularNetwork.
303  */
304  virtual CellularNetwork *open_network() = 0;
305 
306 #if MBED_CONF_CELLULAR_USE_SMS || defined(DOXYGEN_ONLY)
307  /** Create new CellularSMS interface.
308  *
309  * @param fh file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
310  * file handle is used.
311  * @return New instance of interface CellularSMS.
312  */
313  virtual CellularSMS *open_sms() = 0;
314 
315  /** Closes the opened CellularSMS by deleting the CellularSMS instance.
316  */
317  virtual void close_sms() = 0;
318 
319 #endif // MBED_CONF_CELLULAR_USE_SMS
320 
321  /** Create new CellularInformation interface.
322  *
323  * @param fh file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
324  * file handle is used.
325  * @return New instance of interface CellularInformation.
326  */
327  virtual CellularInformation *open_information() = 0;
328 
329  /** Closes the opened CellularNetwork by deleting the CellularNetwork instance.
330  */
331  virtual void close_network() = 0;
332 
333  /** Closes the opened CellularInformation by deleting the CellularInformation instance.
334  */
335  virtual void close_information() = 0;
336 
337  /** Set the default response timeout.
338  *
339  * @remark CellularStateMachine timeouts for all states are also changed to `timeout`.
340  *
341  * @param timeout milliseconds to wait response from modem
342  */
343  virtual void set_timeout(int timeout) = 0;
344 
345 
346 public: //Common functions
347 
348 
349  /** Set the pin code for SIM card
350  *
351  * @param sim_pin PIN for the SIM card
352  */
353  void set_sim_pin(const char *sim_pin);
354 
355  /** Plmn to use when registering to cellular network.
356  * If plmn is set, then registering is forced to this plmn. If plmn is not set, then automatic
357  * registering is used when registering to a cellular network. It doesn't start any operations.
358  *
359  * @param plmn plmn used when registering to cellular network
360  */
361  void set_plmn(const char *plmn);
362 
363  /** Start the interface
364  *
365  * Initializes the modem for communication.
366  * API is asynchronous. Application can get results from CellularContext callback, which is set
367  * with attach(...), or callback, which is set by attach(...), in this class.
368  *
369  * @return NSAPI_ERROR_OK on success
370  * NSAPI_ERROR_NO_MEMORY on case of memory failure
371  */
373 
374  /** Start the interface
375  *
376  * Attempts to open the sim.
377  * API is asynchronous. Application can get results from CellularContext callback, which is set
378  * with attach(...), or callback, which is set by attach(...), in this class.
379  *
380  * @return NSAPI_ERROR_OK on success
381  * NSAPI_ERROR_NO_MEMORY on case of memory failure
382  */
384 
385  /** Start the interface
386  *
387  * Attempts to register the device to cellular network.
388  * API is asynchronous. Application can get results from CellularContext callback, which is set
389  * with attach(...), or callback, which is set by attach(...), in this class.
390  *
391  * @return NSAPI_ERROR_OK on success
392  * NSAPI_ERROR_NO_MEMORY on case of memory failure
393  */
395 
396  /** Start the interface
397  *
398  * Attempts to attach the device to cellular network.
399  * API is asynchronous. Application can get results from CellularContext callback, which is set
400  * with attach(...), or callback, which is set by attach(...), in this class.
401  *
402  * @return NSAPI_ERROR_OK on success
403  * NSAPI_ERROR_NO_MEMORY on case of memory failure
404  */
406 
407  /** Register callback for status reporting.
408  *
409  * The specified status callback function will be called on the network and cellular device status changes.
410  * The parameters on the callback are the event type and event-type dependent reason parameter.
411  *
412  * @remark deleting CellularDevice/CellularContext in callback not allowed.
413  * @remark Allocating/adding lots of traces not recommended as callback is called mostly from State machines thread which
414  * is now 2048. You can change to main thread for example via EventQueue.
415  *
416  * @param status_cb The callback for status changes.
417  */
418  void attach(Callback<void(nsapi_event_t, intptr_t)> status_cb);
419 
420  /** Set an array of timeouts to wait before CellularStateMachine retries after failure.
421  * To disable retry behavior completely use `set_retry_timeout_array(NULL, 0)`.
422  * CellularContext callback event `cell_callback_data_t.final_try` indicates true when all retries have failed.
423  *
424  * @remark Use `set_retry_timeout_array` for CellularStateMachine to wait before it retries again after failure,
425  * this is useful to send repetitive requests when don't know exactly when modem is ready to accept requests.
426  * Use `set_timeout` for timeout how long to wait for a response from modem for each request,
427  * this is useful if modem can accept requests but processing takes long time before sending response.
428  *
429  * @param timeout timeout array using seconds
430  * @param array_len length of the array
431  */
432  void set_retry_timeout_array(const uint16_t timeout[], int array_len);
433 
434 protected: //Common functions
435  friend class AT_CellularNetwork;
436  friend class AT_CellularContext;
437  friend class CellularContext;
438 
439  /** Get the retry array from the CellularStateMachine. Array is used in retry logic.
440  * Array contains seconds and retry logic uses those second to wait before trying again.
441  *
442  * @param timeout timeout array containing seconds for retry logic. Must have space for
443  * CELLULAR_RETRY_ARRAY_SIZE (defined in CellularCommon.h)
444  * @param array_len length of the timeout array on return
445  */
446  void get_retry_timeout_array(uint16_t *timeout, int &array_len) const;
447 
448 private: //Common functions
449  nsapi_error_t start_state_machine(CellularStateMachine::CellularState target_state);
450  nsapi_error_t create_state_machine();
451  void stm_callback(nsapi_event_t ev, intptr_t ptr);
452 
453 protected: //Member variables
454  int _network_ref_count;
455 #if MBED_CONF_CELLULAR_USE_SMS
456  int _sms_ref_count;
457 #endif // MBED_CONF_CELLULAR_USE_SMS
458  int _info_ref_count;
459  events::EventQueue _queue;
460  CellularStateMachine *_state_machine;
462 
463 private: //Member variables
464  CellularNetwork *_nw;
465  char _sim_pin[MAX_PIN_SIZE + 1];
466  char _plmn[MAX_PLMN_SIZE + 1];
467  PlatformMutex _mutex;
468 
469 #ifdef MBED_CONF_RTOS_PRESENT
470  rtos::Thread _queue_thread;
471 #endif
472 };
473 
474 /**
475  * @}
476  */
477 
478 } // namespace mbed
479 
480 #endif // CELLULAR_DEVICE_H_
The Thread class allow defining, creating, and controlling thread functions in the system...
Definition: Thread.h:92
virtual nsapi_error_t soft_power_off()=0
Powers down the modem.
virtual void close_information()=0
Closes the opened CellularInformation by deleting the CellularInformation instance.
virtual nsapi_error_t hard_power_on()=0
Sets the modem up for powering on This is equivalent to plugging in the device, i.e., attaching power and serial port.
virtual CellularContext * get_context_list() const =0
Get the linked list of CellularContext instances.
EventQueue.
Definition: EventQueue.h:62
virtual void set_ready_cb(Callback< void()> callback)=0
Set callback function to listen when device is ready.
virtual void close_sms()=0
Closes the opened CellularSMS by deleting the CellularSMS instance.
CellularContext is CellularInterface/NetworkInterface with extensions for cellular connectivity...
static CellularDevice * get_target_default_instance()
Return target onboard instance of CellularDevice.
virtual CellularInformation * open_information()=0
Create new CellularInformation interface.
virtual nsapi_error_t init()=0
Initialize cellular device must be called right after the module is ready.
virtual void modem_debug_on(bool on)=0
Turn modem debug traces on.
CellularState
Cellular connection states.
Class CellularDevice.
void set_plmn(const char *plmn)
Plmn to use when registering to cellular network.
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:95
nsapi_error_t attach_to_network()
Start the interface.
virtual nsapi_error_t hard_power_off()=0
Sets the modem in unplugged state.
virtual nsapi_error_t set_pin(const char *sim_pin)=0
Open the SIM card by setting the pin code for SIM.
virtual nsapi_error_t set_baud_rate(int baud_rate)=0
Sets cellular modem to given baud rate.
Callback< R(ArgTs...)> callback(R(*func)(ArgTs...)=nullptr) noexcept
Create a callback class with type inferred from the arguments.
Definition: Callback.h:678
CellularDevice()
Default constructor.
virtual ~CellularDevice()
virtual Destructor
The PlatformMutex class is used to synchronize the execution of threads.
Definition: PlatformMutex.h:47
virtual CellularNetwork * open_network()=0
Create new CellularNetwork interface.
virtual nsapi_error_t soft_power_on()=0
Powers up the modem.
virtual nsapi_error_t get_sim_state(SimState &state)=0
Get SIM card&#39;s state.
CellularStateMachine class.
virtual void delete_context(CellularContext *context)=0
Deletes the given CellularContext instance.
An abstract interface for connecting to a network and getting information from it.
Class CellularInformation.
virtual CellularContext * create_context(const char *apn=NULL, bool cp_req=false, bool nonip_req=false)=0
Creates a new CellularContext interface.
void attach(Callback< void(nsapi_event_t, intptr_t)> status_cb)
Register callback for status reporting.
virtual void set_timeout(int timeout)=0
Set the default response timeout.
nsapi_error_t register_to_network()
Start the interface.
virtual events::EventQueue * get_queue()
Get event queue that can be chained to main event queue.
virtual ATHandler * get_at_handler()=0
Get the current ATHandler instance in use for debug purposes etc.
void get_retry_timeout_array(uint16_t *timeout, int &array_len) const
Get the retry array from the CellularStateMachine.
static CellularDevice * get_default_instance()
Returns singleton instance of CellularDevice, if Mbed target board has a supported onboard modem...
Class AT_CellularNetwork.
virtual void cellular_callback(nsapi_event_t ev, intptr_t ptr, CellularContext *ctx=NULL)
Cellular callback to be attached to Network and CellularStateMachine classes.
virtual CellularSMS * open_sms()=0
Create new CellularSMS interface.
virtual nsapi_error_t shutdown()
Shutdown cellular device to minimum functionality.
virtual nsapi_error_t is_ready()=0
Check whether the device is ready to accept commands.
virtual nsapi_error_t clear()=0
Clear modem to a default initial state.
Callback class based on template specialization.
Definition: Callback.h:53
Definition: ATHandler.h:46
virtual void close_network()=0
Closes the opened CellularNetwork by deleting the CellularNetwork instance.
Class for sending AT commands and parsing AT responses.
Definition: ATHandler.h:70
nsapi_error_t set_sim_ready()
Start the interface.
void set_retry_timeout_array(const uint16_t timeout[], int array_len)
Set an array of timeouts to wait before CellularStateMachine retries after failure.
void set_sim_pin(const char *sim_pin)
Set the pin code for SIM card.
virtual nsapi_error_t set_power_save_mode(int periodic_time, int active_time=0)=0
Set power save mode.
nsapi_error_t set_device_ready()
Start the interface.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.