Mistake on this page?
Report an issue in GitHub or email us
CellularStateMachine.h
1 /*
2  * Copyright (c) 2018, 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 #ifndef _CELLULAR_STATEMACHINE_H_
18 #define _CELLULAR_STATEMACHINE_H_
19 
20 #include "events/EventQueue.h"
21 #include "CellularNetwork.h"
22 #include "CellularCommon.h"
23 #include "PlatformMutex.h"
24 
25 namespace mbed {
26 
27 class CellularDevice;
28 
29 /** CellularStateMachine class
30  *
31  * Finite State Machine for attaching to cellular network. Used by CellularDevice.
32  */
34 public:
35  friend class UT_CellularStateMachine; // for unit tests
36 
37  /** Constructor
38  *
39  * @param device reference to CellularDevice
40  * @param queue reference to queue used in state transitions
41  * @param nw reference to CellularNetwork
42  */
45 
46  /** Cellular connection states
47  */
49  STATE_INIT = 0,
50  STATE_POWER_ON,
51  STATE_DEVICE_READY,
52  STATE_SIM_PIN,
53  STATE_SIGNAL_QUALITY,
54  STATE_REGISTERING_NETWORK,
55  STATE_ATTACHING_NETWORK,
56  STATE_MAX_FSM_STATE
57  };
58 
59  /** Register cellular specific for status changes
60  *
61  * The specified status callback function will be called on device status changes.
62  * The parameters on the callback are the event type and event-type dependent reason parameter.
63  *
64  * @param status_cb The callback for status changes
65  */
66  void set_cellular_callback(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb);
67 
68  /** Start event queue dispatching
69  * @return see nsapi_error_t, 0 on success
70  */
72 
73  /** Stop event queue dispatching and close cellular interfaces.
74  */
75  void stop();
76 
77  /** Runs state machine to connected state unless callback method set with set_state_callback return false to stop.
78  *
79  * @return see nsapi_error_t, 0 on success
80  */
82 
83  /** Set cellular device SIM PIN code
84  * @param sim_pin PIN code
85  */
86  void set_sim_pin(const char *sim_pin);
87 
88  /** Sets the timeout array for network rejects. After reject next item is tried and after all items are waited and
89  * still fails then current network event will fail.
90  *
91  * @param timeout timeout array using seconds
92  * @param array_len length of the array
93  */
94  void set_retry_timeout_array(const uint16_t timeout[], int array_len);
95 
96  /** Sets the operator plmn which is used when registering to a network specified by plmn. If plmn is not set then automatic
97  * registering is used when registering to a cellular network. Does not start any operations.
98  *
99  * @param plmn operator in numeric format. See more from 3GPP TS 27.007 chapter 7.3.
100  */
101  void set_plmn(const char *plmn);
102 
103  /** returns readable format of the given state. Used for printing states while debugging.
104  *
105  * @param state state which is returned in string format
106  * @return string format of the given state
107  */
108  const char *get_state_string(CellularState state) const;
109 
110  /** Get the current status of the state machine. Thread safe.
111  *
112  * @param current_state
113  * @param target_state
114  * @return true if state machine is running, false is not
115  *
116  */
118 
119  /** CellularDevice updates about network events and cellular events
120  *
121  * @param ev Event type
122  * @param ptr Event type specific data
123  */
124  void cellular_event_changed(nsapi_event_t ev, intptr_t ptr);
125 
126  /** Reset the state machine to init state. After reset state machine can be used again to run to wanted state.
127  */
128  void reset();
129 
130  /** Get retry timeout array
131  *
132  * @param timeout Pointer to timeout array
133  * @param array_len Max lenght of the array
134  */
135  void get_retry_timeout_array(uint16_t *timeout, int &array_len) const;
136 
137  /** Change all cellular state timeouts
138  *
139  * @param timeout Timeout value (milliseconds)
140  */
141  void set_timeout(std::chrono::duration<int, std::milli> timeout);
142 
143 private:
144  bool power_on();
145  bool open_sim();
146  bool get_network_registration(CellularNetwork::RegistrationType type, CellularNetwork::RegistrationStatus &status, bool &is_registered);
147  bool is_registered();
148  bool device_ready();
149 
150  // state functions to keep state machine simple
151  void state_init();
152  void state_power_on();
153  void state_device_ready();
154  void state_sim_pin();
155  void state_signal_quality();
156  void state_registering();
157  void state_attaching();
158  void enter_to_state(CellularState state);
159  void retry_state_or_fail();
160  void continue_from_state(CellularState state);
161  void report_failure(const char *msg);
162  void event();
163  void device_ready_cb();
164  void pre_event(CellularState state);
165  bool check_is_target_reached();
166  void send_event_cb(cellular_connection_status_t status);
167  void change_timeout(const std::chrono::duration<int, std::milli> &timeout);
168 
169 private:
170  CellularDevice &_cellularDevice;
171  CellularState _state;
172  CellularState _next_state;
173  CellularState _target_state;
174 
176 
177  CellularNetwork &_network;
178  events::EventQueue &_queue;
179 
180  const char *_sim_pin;
181  int _retry_count;
182  std::chrono::duration<int> _start_time;
183  std::chrono::duration<int> _event_timeout;
184 
185  std::chrono::duration<uint16_t> _retry_timeout_array[CELLULAR_RETRY_ARRAY_SIZE];
186  int _retry_array_length;
187  int _event_id;
188  const char *_plmn;
189  bool _command_success;
190  bool _is_retry;
191  cell_callback_data_t _cb_data;
192  cellular_connection_status_t _current_event;
193  int _status;
194  PlatformMutex _mutex;
195 
196  // Cellular state timeouts
197  std::chrono::duration<int, std::milli> _state_timeout_power_on;
198  std::chrono::duration<int, std::milli> _state_timeout_sim_pin;
199  std::chrono::duration<int, std::milli> _state_timeout_registration;
200  std::chrono::duration<int, std::milli> _state_timeout_network;
201  std::chrono::duration<int, std::milli> _state_timeout_connect; // timeout for PS attach, PDN connect and socket operations
202 
203  cell_signal_quality_t _signal_quality;
204 };
205 
206 } // namespace
207 
208 #endif /* _CELLULAR_STATEMACHINE_H_ */
bool get_current_status(CellularStateMachine::CellularState &current_state, CellularStateMachine::CellularState &target_state)
Get the current status of the state machine.
CellularStateMachine(CellularDevice &device, events::EventQueue &queue, CellularNetwork &nw)
Constructor.
EventQueue.
Definition: EventQueue.h:62
CellularState
Cellular connection states.
Class CellularDevice.
void stop()
Stop event queue dispatching and close cellular interfaces.
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:95
nsapi_error_t start_dispatch()
Start event queue dispatching.
void cellular_event_changed(nsapi_event_t ev, intptr_t ptr)
CellularDevice updates about network events and cellular events.
The PlatformMutex class is used to synchronize the execution of threads.
Definition: PlatformMutex.h:47
void get_retry_timeout_array(uint16_t *timeout, int &array_len) const
Get retry timeout array.
CellularStateMachine class.
const char * get_state_string(CellularState state) const
returns readable format of the given state.
An abstract interface for connecting to a network and getting information from it.
void set_sim_pin(const char *sim_pin)
Set cellular device SIM PIN code.
nsapi_error_t run_to_state(CellularState state)
Runs state machine to connected state unless callback method set with set_state_callback return false...
void set_cellular_callback(mbed::Callback< void(nsapi_event_t, intptr_t)> status_cb)
Register cellular specific for status changes.
Callback class based on template specialization.
Definition: Callback.h:53
Definition: ATHandler.h:46
void set_retry_timeout_array(const uint16_t timeout[], int array_len)
Sets the timeout array for network rejects.
void set_timeout(std::chrono::duration< int, std::milli > timeout)
Change all cellular state timeouts.
void reset()
Reset the state machine to init state.
void set_plmn(const char *plmn)
Sets the operator plmn which is used when registering to a network specified by plmn.
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.