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 #if (DEVICE_SERIAL && DEVICE_INTERRUPTIN) || defined(DOXYGEN_ONLY)
25 #include "UARTSerial.h"
26 #endif // #if DEVICE_SERIAL
27 
28 /** @file CellularDevice.h
29  * @brief Class CellularDevice
30  *
31  */
32 namespace mbed {
33 
34 class CellularSMS;
35 class CellularInformation;
36 class CellularNetwork;
37 class CellularContext;
38 class FileHandle;
39 
40 const int MAX_PIN_SIZE = 8;
41 const int MAX_PLMN_SIZE = 16;
42 const int MAX_SIM_READY_WAITING_TIME = 30;
43 
44 /**
45  * @addtogroup cellular
46  * @{
47  */
48 
49 /**
50  * Class CellularDevice
51  *
52  * An abstract interface that defines opening and closing of cellular interfaces.
53  * You can delete or close opened interfaces only through this class.
54  */
56 public:
57  /* enumeration for possible SIM states */
58  enum SimState {
59  SimStateReady = 0,
60  SimStatePinNeeded,
61  SimStatePukNeeded,
62  SimStateUnknown
63  };
64 
65  /** Returns singleton instance of CellularDevice, if Mbed target board has a supported
66  * onboard modem, or provide-default is defined for a cellular driver in JSON configuration
67  * files. Otherwise returns NULL. See NetworkInterface::get_default_instance for details.
68  *
69  * @remark Application may override this (non-weak) default implementation.
70  *
71  * @return default CellularDevice, NULL if not defined
72  */
74 
75  /** Return target onboard instance of CellularDevice
76  *
77  * @remark Mbed OS target shall override (non-weak) this function for an onboard modem.
78  *
79  * @return CellularDevice* instance, NULL if not defined
80  */
82 
83  /** Default constructor
84  *
85  * @param fh File handle used in communication with the modem.
86  */
88 
89  /** virtual Destructor
90  */
91  virtual ~CellularDevice();
92 
93  /** Sets the modem up for powering on
94  * This is equivalent to plugging in the device, i.e., attaching power and serial port.
95  * In general, hard_power_on and soft_power_on provides a simple hardware abstraction layer
96  * on top of the modem drivers written for Mbed OS; they can be overridden
97  * in a derived class to perform custom power controls in a particular board configuration.
98  * In many boards this will be a no-op if there is no separate power supply control circuitry.
99  *
100  * @remark CellularStateMachine calls hard_power_on at first until successful,
101  * then soft_power_on and init until the modem responds.
102  * If you are not using CellularStateMachine then you need to call these functions yourself.
103  *
104  * @post You must call soft_power_on to power on the modem after calling hard_power_on.
105  *
106  * @return NSAPI_ERROR_OK on success
107  */
108  virtual nsapi_error_t hard_power_on() = 0;
109 
110  /** Sets the modem in unplugged state
111  *
112  * This is equivalent to pulling the plug off of the device, i.e.,
113  * detaching power and serial port.
114  *
115  * This puts the modem in the lowest power state.
116  *
117  * @remark CellularStateMachine disconnect or destruct does not shutdown or power off the modem,
118  * but you need to do that yourself.
119  *
120  * @pre You must call soft_power_off to power off the modem before calling hard_power_off.
121  *
122  * @return NSAPI_ERROR_OK on success
123  */
124  virtual nsapi_error_t hard_power_off() = 0;
125 
126  /** Powers up the modem
127  *
128  * This is equivalent to pressing the "power button" to activate or reset the modem
129  * and usually implemented as a short pulse on a dedicated GPIO signal.
130  * It is expected to be present to make it possible to reset the modem.
131  * The driver may repeat this if the modem is not responsive to AT commands.
132  *
133  * @remark CellularStateMachine calls this when requested to connect.
134  * If you are not using CellularStateMachine then you need to call this function yourself.
135  *
136  * @post You must call init to setup the modem.
137  *
138  * @return NSAPI_ERROR_OK on success
139  */
140  virtual nsapi_error_t soft_power_on() = 0;
141 
142  /** Powers down the modem
143  *
144  * This is equivalent to turning off the modem by button press.
145  *
146  * @remark CellularStateMachine disconnect or destruct does not shutdown or power off the modem,
147  * but you need to do that yourself.
148  *
149  * @pre You must call shutdown to prepare the modem for power off.
150  *
151  * @return NSAPI_ERROR_OK on success
152  */
153  virtual nsapi_error_t soft_power_off() = 0;
154 
155  /** Open the SIM card by setting the pin code for SIM.
156  *
157  * @param sim_pin PIN for the SIM card
158  * @return NSAPI_ERROR_OK on success
159  * NSAPI_ERROR_PARAMETER if sim_pin is null and sim is not ready
160  * NSAPI_ERROR_DEVICE_ERROR on failure
161  */
162  virtual nsapi_error_t set_pin(const char *sim_pin) = 0;
163 
164  /** Get SIM card's state
165  *
166  * @param state current state of SIM
167  * @return NSAPI_ERROR_OK on success
168  * NSAPI_ERROR_DEVICE_ERROR on failure
169  */
170  virtual nsapi_error_t get_sim_state(SimState &state) = 0;
171 
172  /** Creates a new CellularContext interface.
173  *
174  * @param fh file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
175  * file handle is used.
176  * @param apn access point to use with context, can be null.
177  * @param cp_req flag indicating if EPS control plane optimization is required
178  * @param nonip_req flag indicating if this context is required to be Non-IP
179  *
180  * @return new instance of class CellularContext or NULL in case of failure
181  *
182  */
183  virtual CellularContext *create_context(FileHandle *fh = NULL, const char *apn = NULL, bool cp_req = false, bool nonip_req = false) = 0;
184 
185 #if (DEVICE_SERIAL && DEVICE_INTERRUPTIN) || defined(DOXYGEN_ONLY)
186  /** Creates a new CellularContext interface. This API should be used if serial is UART and PPP mode used.
187  * CellularContext created will use data carrier detect to be able to detect disconnection much faster in PPP mode.
188  * UARTSerial usually is the same which was given for the CellularDevice.
189  *
190  * @param serial UARTSerial used in communication to modem. If null then the default file handle is used.
191  * @param apn access point to use with context, can be null.
192  * @param dcd_pin Pin used to set data carrier detect on/off for the given UART
193  * @param active_high a boolean set to true if DCD polarity is active low
194  * @param cp_req Flag indicating if EPS control plane optimization is required
195  * @param nonip_req Flag indicating if this context is required to be Non-IP
196  *
197  * @return new instance of class CellularContext or NULL in case of failure
198  *
199  */
200  virtual CellularContext *create_context(UARTSerial *serial, const char *apn, PinName dcd_pin = NC,
201  bool active_high = false, bool cp_req = false, bool nonip_req = false) = 0;
202 #endif // #if DEVICE_SERIAL
203 
204  /** Deletes the given CellularContext instance
205  *
206  * @param context CellularContext to delete
207  */
208  virtual void delete_context(CellularContext *context) = 0;
209 
210  /** Stop the current operation. Operations: set_device_ready, set_sim_ready, register_to_network, attach_to_network
211  *
212  */
213  void stop();
214 
215  /** Get the current FileHandle item used when communicating with the modem.
216  *
217  * @return reference to FileHandle
218  */
219  FileHandle &get_file_handle() const;
220 
221  /** Get event queue that can be chained to main event queue.
222  * @return event queue
223  */
224  virtual events::EventQueue *get_queue();
225 
226  /** Set the pin code for SIM card
227  *
228  * @param sim_pin PIN for the SIM card
229  */
230  void set_sim_pin(const char *sim_pin);
231 
232  /** Plmn to use when registering to cellular network.
233  * If plmn is set, then registering is forced to this plmn. If plmn is not set, then automatic
234  * registering is used when registering to a cellular network. It doesn't start any operations.
235  *
236  * @param plmn plmn used when registering to cellular network
237  */
238  void set_plmn(const char *plmn);
239 
240  /** Start the interface
241  *
242  * Initializes the modem for communication.
243  * API is asynchronous. Application can get results from CellularContext callback, which is set
244  * with attach(...), or callback, which is set by attach(...), in this class.
245  *
246  * @return NSAPI_ERROR_OK on success
247  * NSAPI_ERROR_NO_MEMORY on case of memory failure
248  */
250 
251  /** Start the interface
252  *
253  * Attempts to open the sim.
254  * API is asynchronous. Application can get results from CellularContext callback, which is set
255  * with attach(...), or callback, which is set by attach(...), in this class.
256  *
257  * @return NSAPI_ERROR_OK on success
258  * NSAPI_ERROR_NO_MEMORY on case of memory failure
259  */
261 
262  /** Start the interface
263  *
264  * Attempts to register the device to cellular network.
265  * API is asynchronous. Application can get results from CellularContext callback, which is set
266  * with attach(...), or callback, which is set by attach(...), in this class.
267  *
268  * @return NSAPI_ERROR_OK on success
269  * NSAPI_ERROR_NO_MEMORY on case of memory failure
270  */
272 
273  /** Start the interface
274  *
275  * Attempts to attach the device to cellular network.
276  * API is asynchronous. Application can get results from CellularContext callback, which is set
277  * with attach(...), or callback, which is set by attach(...), in this class.
278  *
279  * @return NSAPI_ERROR_OK on success
280  * NSAPI_ERROR_NO_MEMORY on case of memory failure
281  */
283 
284  /** Register callback for status reporting.
285  *
286  * The specified status callback function will be called on the network and cellular device status changes.
287  * The parameters on the callback are the event type and event-type dependent reason parameter.
288  *
289  * @remark deleting CellularDevice/CellularContext in callback not allowed.
290  * @remark Allocating/adding lots of traces not recommended as callback is called mostly from State machines thread which
291  * is now 2048. You can change to main thread for example via EventQueue.
292  *
293  * @param status_cb The callback for status changes.
294  */
295  void attach(Callback<void(nsapi_event_t, intptr_t)> status_cb);
296 
297  /** Create new CellularNetwork interface.
298  *
299  * @param fh file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
300  * file handle is used.
301  * @return New instance of interface CellularNetwork.
302  */
303  virtual CellularNetwork *open_network(FileHandle *fh = NULL) = 0;
304 
305  /** Create new CellularSMS interface.
306  *
307  * @param fh file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
308  * file handle is used.
309  * @return New instance of interface CellularSMS.
310  */
311  virtual CellularSMS *open_sms(FileHandle *fh = NULL) = 0;
312 
313  /** Create new CellularInformation interface.
314  *
315  * @param fh file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
316  * file handle is used.
317  * @return New instance of interface CellularInformation.
318  */
319  virtual CellularInformation *open_information(FileHandle *fh = NULL) = 0;
320 
321  /** Closes the opened CellularNetwork by deleting the CellularNetwork instance.
322  */
323  virtual void close_network() = 0;
324 
325  /** Closes the opened CellularSMS by deleting the CellularSMS instance.
326  */
327  virtual void close_sms() = 0;
328 
329  /** Closes the opened CellularInformation by deleting the CellularInformation instance.
330  */
331  virtual void close_information() = 0;
332 
333  /** Set the default response timeout.
334  *
335  * @param timeout milliseconds to wait response from modem
336  */
337  virtual void set_timeout(int timeout) = 0;
338 
339  /** Turn modem debug traces on
340  *
341  * @param on set true to enable debug traces
342  */
343  virtual void modem_debug_on(bool on) = 0;
344 
345  /** Initialize cellular device must be called right after the module is ready.
346  *
347  * For example, when multiple cellular modules are supported in a single driver this function
348  * detects and adapts to an actual module at runtime.
349  *
350  * @remark CellularStateMachine calls soft_power_on and init repeatedly when starting to connect
351  * until the modem responds.
352  *
353  * @return NSAPI_ERROR_OK on success
354  * NSAPI_ERROR_NO_MEMORY on case of memory failure
355  * NSAPI_ERROR_UNSUPPORTED if current cellular module type is not detected
356  * NSAPI_ERROR_DEVICE_ERROR if model information could not be read
357  *
358  */
359  virtual nsapi_error_t init() = 0;
360 
361  /** Shutdown cellular device to minimum functionality.
362  *
363  * Actual functionality is modem specific, for example UART may is not be responsive without
364  * explicit wakeup signal (such as RTS) after shutdown.
365  *
366  * @remark You must call shutdown before power off to prepare the modem and to quit cellular network.
367  *
368  * @return NSAPI_ERROR_OK on success
369  * NSAPI_ERROR_DEVICE_ERROR on failure
370  */
371  virtual nsapi_error_t shutdown();
372 
373  /** Check whether the device is ready to accept commands.
374  *
375  * @return NSAPI_ERROR_OK on success
376  * NSAPI_ERROR_DEVICE_ERROR on failure
377  */
378  virtual nsapi_error_t is_ready() = 0;
379 
380  /** Set callback function to listen when device is ready.
381  *
382  * @param callback function to call on device ready, or NULL to remove callback.
383  */
384  virtual void set_ready_cb(Callback<void()> callback) = 0;
385 
386  /** Set power save mode
387  *
388  * @remark See 3GPP TS 27.007 PSM for details
389  *
390  * @param periodic_time in seconds to enable power save, or zero to disable
391  * @param active_time in seconds to wait before entering power save mode
392  *
393  * @return NSAPI_ERROR_OK on success
394  * NSAPI_ERROR_DEVICE_ERROR on failure
395  */
396  virtual nsapi_error_t set_power_save_mode(int periodic_time, int active_time = 0) = 0;
397 
398  /** Get the linked list of CellularContext instances
399  *
400  * @return Pointer to first item in linked list
401  */
402  virtual CellularContext *get_context_list() const;
403 
404  /** Get the current ATHandler instance in use for debug purposes etc.
405  * Once use has been finished call to release_at_handler() has to be made
406  *
407  * @return Pointer to the ATHandler in use
408  */
409  virtual ATHandler *get_at_handler() = 0;
410 
411  /** Release the ATHandler taken into use with get_at_handler()
412  *
413  * @param at_handler
414  * @return NSAPI_ERROR_OK on success, NSAPI_ERROR_PARAMETER on failure
415  */
416  virtual nsapi_error_t release_at_handler(ATHandler *at_handler) = 0;
417 
418 protected:
419  friend class AT_CellularNetwork;
420  friend class AT_CellularContext;
421 
422  /** Cellular callback to be attached to Network and CellularStateMachine classes.
423  * CellularContext calls this when in PPP mode to provide network changes.
424  * This method will broadcast to every interested classes:
425  * CellularContext (might be many) and CellularStateMachine if available.
426  */
427  void cellular_callback(nsapi_event_t ev, intptr_t ptr, CellularContext *ctx = NULL);
428  void stm_callback(nsapi_event_t ev, intptr_t ptr);
429  int _network_ref_count;
430  int _sms_ref_count;
431  int _info_ref_count;
432  FileHandle *_fh;
433  events::EventQueue _queue;
434  CellularStateMachine *_state_machine;
435 private:
436  nsapi_error_t start_state_machine(CellularStateMachine::CellularState target_state);
437  nsapi_error_t create_state_machine();
438 
439  CellularNetwork *_nw;
440  char _sim_pin[MAX_PIN_SIZE + 1];
441  char _plmn[MAX_PLMN_SIZE + 1];
442  PlatformMutex _mutex;
444 };
445 
446 /**
447  * @}
448  */
449 
450 } // namespace mbed
451 
452 #endif // CELLULAR_DEVICE_H_
virtual nsapi_error_t soft_power_off()=0
Powers down the modem.
void stop()
Stop the current operation.
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.
EventQueue.
Definition: EventQueue.h:52
FileHandle & get_file_handle() const
Get the current FileHandle item used when communicating with the modem.
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 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.
Class CellularDevice.
void set_plmn(const char *plmn)
Plmn to use when registering to cellular network.
virtual CellularInformation * open_information(FileHandle *fh=NULL)=0
Create new CellularInformation interface.
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:95
Class FileHandle.
Definition: FileHandle.h:46
void cellular_callback(nsapi_event_t ev, intptr_t ptr, CellularContext *ctx=NULL)
Cellular callback to be attached to Network and CellularStateMachine classes.
Class providing buffered UART communication functionality using separate circular buffer for send and...
Definition: UARTSerial.h:50
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 ~CellularDevice()
virtual Destructor
Callback< R()> callback(R(*func)()=0)
Create a callback class with type inferred from the arguments.
Definition: Callback.h:3848
The PlatformMutex class is used to synchronize the execution of threads.
Definition: PlatformMutex.h:47
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 nsapi_error_t release_at_handler(ATHandler *at_handler)=0
Release the ATHandler taken into use with get_at_handler()
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.
virtual CellularContext * create_context(FileHandle *fh=NULL, const char *apn=NULL, bool cp_req=false, bool nonip_req=false)=0
Creates a new CellularContext interface.
Class CellularInformation.
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.
Class CellularSMS.
Definition: CellularSMS.h:48
nsapi_error_t register_to_network()
Start the interface.
virtual CellularNetwork * open_network(FileHandle *fh=NULL)=0
Create new CellularNetwork 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.
static CellularDevice * get_default_instance()
Returns singleton instance of CellularDevice, if Mbed target board has a supported onboard modem...
Class AT_CellularNetwork.
CellularDevice(FileHandle *fh)
Default constructor.
virtual CellularContext * get_context_list() const
Get the linked list of CellularContext instances.
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.
Callback class based on template specialization.
Definition: Callback.h:39
Definition: AnalogIn.h:28
virtual void close_network()=0
Closes the opened CellularNetwork by deleting the CellularNetwork instance.
virtual CellularSMS * open_sms(FileHandle *fh=NULL)=0
Create new CellularSMS interface.
Class for sending AT commands and parsing AT responses.
Definition: ATHandler.h:62
nsapi_error_t set_sim_ready()
Start the interface.
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.