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