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 const int RETRY_ARRAY_SIZE = 10;
34 
35 /** CellularStateMachine class
36  *
37  * Finite State Machine for attaching to cellular network. Used by CellularDevice.
38  */
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  */
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_REGISTERING_NETWORK,
62  STATE_ATTACHING_NETWORK,
63  STATE_MAX_FSM_STATE
64  };
65 
66  /** Register cellular specific for status changes
67  *
68  * The specified status callback function will be called on device status changes.
69  * The parameters on the callback are the event type and event-type dependent reason parameter.
70  *
71  * @param status_cb The callback for status changes
72  */
73  void set_cellular_callback(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb);
74 
75  /** Start event queue dispatching
76  * @return see nsapi_error_t, 0 on success
77  */
78  nsapi_error_t start_dispatch();
79 
80  /** Stop event queue dispatching and close cellular interfaces.
81  */
82  void stop();
83 
84  /** Runs state machine to connected state unless callback method set with set_state_callback return false to stop.
85  *
86  * @return see nsapi_error_t, 0 on success
87  */
88  nsapi_error_t run_to_state(CellularState state);
89 
90  /** Set cellular device SIM PIN code
91  * @param sim_pin PIN code
92  */
93  void set_sim_pin(const char *sim_pin);
94 
95  /** Sets the timeout array for network rejects. After reject next item is tried and after all items are waited and
96  * still fails then current network event will fail.
97  *
98  * @param timeout timeout array using seconds
99  * @param array_len length of the array
100  */
101  void set_retry_timeout_array(const uint16_t timeout[], int array_len);
102 
103  /** Sets the operator plmn which is used when registering to a network specified by plmn. If plmn is not set then automatic
104  * registering is used when registering to a cellular network. Does not start any operations.
105  *
106  * @param plmn operator in numeric format. See more from 3GPP TS 27.007 chapter 7.3.
107  */
108  void set_plmn(const char *plmn);
109 
110  /** returns readable format of the given state. Used for printing states while debugging.
111  *
112  * @param state state which is returned in string format
113  * @return string format of the given state
114  */
115  const char *get_state_string(CellularState state) const;
116 
117  /** Get the current status of the state machine. Thread safe.
118  *
119  * @param current_state
120  * @param target_state
121  * @return true if state machine is running, false is not
122  *
123  */
124  bool get_current_status(CellularStateMachine::CellularState &current_state, CellularStateMachine::CellularState &target_state);
125 
126  /** CellularDevice updates about network events and cellular events
127  *
128  * @param ev Event type
129  * @param ptr Event type specific data
130  */
131  void cellular_event_changed(nsapi_event_t ev, intptr_t ptr);
132 
133  /** Reset the state machine to init state. After reset state machine can be used again to run to wanted state.
134  */
135  void reset();
136 private:
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_registering();
149  void state_attaching();
150  void enter_to_state(CellularState state);
151  void retry_state_or_fail();
152  void continue_from_state(CellularState state);
153  void report_failure(const char *msg);
154  void event();
155  void device_ready_cb();
156  void pre_event(CellularState state);
157  bool check_is_target_reached();
158 
159  CellularDevice &_cellularDevice;
160  CellularState _state;
161  CellularState _next_state;
162  CellularState _target_state;
163 
165 
166  CellularNetwork &_network;
167  events::EventQueue &_queue;
168  rtos::Thread *_queue_thread;
169 
170  const char *_sim_pin;
171  int _retry_count;
172  int _start_time;
173  int _event_timeout;
174 
175  uint16_t _retry_timeout_array[RETRY_ARRAY_SIZE];
176  int _retry_array_length;
177  int _event_id;
178  const char *_plmn;
179  bool _command_success;
180  bool _is_retry;
181  cell_callback_data_t _cb_data;
182  nsapi_event_t _current_event;
183  int _status;
184  PlatformMutex _mutex;
185 };
186 
187 } // namespace
188 
189 #endif /* _CELLULAR_STATEMACHINE_H_ */
The Thread class allow defining, creating, and controlling thread functions in the system...
Definition: Thread.h:85
EventQueue.
Definition: EventQueue.h:52
Class CellularDevice.
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:95
The PlatformMutex class is used to synchronize the execution of threads.
Definition: PlatformMutex.h:47
CellularStateMachine class.
An abstract interface for connecting to a network and getting information from it.
Class AT_CellularDevice.
Callback class based on template specialization.
Definition: Callback.h:39
Definition: AnalogIn.h:28
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.