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