CellularStateMachine.h

00001 /*
00002  * Copyright (c) 2018, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 #ifndef _CELLULAR_STATEMACHINE_H_
00018 #define _CELLULAR_STATEMACHINE_H_
00019 
00020 #include "events/EventQueue.h"
00021 #include "CellularNetwork.h"
00022 #include "CellularCommon.h"
00023 #include "PlatformMutex.h"
00024 
00025 #ifdef MBED_CONF_RTOS_PRESENT
00026 namespace rtos {
00027 class Thread;
00028 }
00029 #endif
00030 
00031 namespace mbed {
00032 
00033 class CellularDevice;
00034 
00035 /** CellularStateMachine class
00036  *
00037  *  Finite State Machine for attaching to cellular network. Used by CellularDevice.
00038  */
00039 class CellularStateMachine {
00040 private:
00041     // friend of CellularDevice so that it's the only way to close/delete this class.
00042     friend class CellularDevice;
00043     friend class AT_CellularDevice;
00044     friend class UT_CellularStateMachine; // for unit tests
00045     /** Constructor
00046      *
00047      * @param device    reference to CellularDevice
00048      * @param queue     reference to queue used in state transitions
00049      * @param nw        reference to CellularNetwork
00050      */
00051     CellularStateMachine(CellularDevice &device, events::EventQueue &queue, CellularNetwork &nw);
00052     ~CellularStateMachine();
00053 
00054     /** Cellular connection states
00055      */
00056     enum CellularState {
00057         STATE_INIT = 0,
00058         STATE_POWER_ON,
00059         STATE_DEVICE_READY,
00060         STATE_SIM_PIN,
00061         STATE_SIGNAL_QUALITY,
00062         STATE_REGISTERING_NETWORK,
00063         STATE_ATTACHING_NETWORK,
00064         STATE_MAX_FSM_STATE
00065     };
00066 
00067     /** Register cellular specific for status changes
00068      *
00069      *  The specified status callback function will be called on device status changes.
00070      *  The parameters on the callback are the event type and event-type dependent reason parameter.
00071      *
00072      *  @param status_cb The callback for status changes
00073      */
00074     void set_cellular_callback(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb);
00075 
00076     /** Start event queue dispatching
00077      *  @return see nsapi_error_t, 0 on success
00078      */
00079     nsapi_error_t start_dispatch();
00080 
00081     /** Stop event queue dispatching and close cellular interfaces.
00082      */
00083     void stop();
00084 
00085     /** Runs state machine to connected state unless callback method set with set_state_callback return false to stop.
00086      *
00087      *  @return see nsapi_error_t, 0 on success
00088      */
00089     nsapi_error_t run_to_state(CellularState state);
00090 
00091     /** Set cellular device SIM PIN code
00092      *  @param sim_pin PIN code
00093      */
00094     void set_sim_pin(const char *sim_pin);
00095 
00096     /** Sets the timeout array for network rejects. After reject next item is tried and after all items are waited and
00097      *  still fails then current network event will fail.
00098      *
00099      *  @param timeout      timeout array using seconds
00100      *  @param array_len    length of the array
00101      */
00102     void set_retry_timeout_array(const uint16_t timeout[], int array_len);
00103 
00104     /** Sets the operator plmn which is used when registering to a network specified by plmn. If plmn is not set then automatic
00105      *  registering is used when registering to a cellular network. Does not start any operations.
00106      *
00107      *  @param plmn operator in numeric format. See more from 3GPP TS 27.007 chapter 7.3.
00108      */
00109     void set_plmn(const char *plmn);
00110 
00111     /** returns readable format of the given state. Used for printing states while debugging.
00112      *
00113      *  @param state state which is returned in string format
00114      *  @return      string format of the given state
00115      */
00116     const char *get_state_string(CellularState state) const;
00117 
00118     /** Get the current status of the state machine. Thread safe.
00119      *
00120      *  @param  current_state
00121      *  @param  target_state
00122      *  @return true if state machine is running, false is not
00123      *
00124      */
00125     bool get_current_status(CellularStateMachine::CellularState &current_state, CellularStateMachine::CellularState &target_state);
00126 
00127     /** CellularDevice updates about network events and cellular events
00128      *
00129      *  @param ev   Event type
00130      *  @param ptr  Event type specific data
00131      */
00132     void cellular_event_changed(nsapi_event_t ev, intptr_t ptr);
00133 
00134     /** Reset the state machine to init state. After reset state machine can be used again to run to wanted state.
00135      */
00136     void reset();
00137 private:
00138     void get_retry_timeout_array(uint16_t *timeout, int &array_len) const;
00139     bool power_on();
00140     bool open_sim();
00141     bool get_network_registration(CellularNetwork::RegistrationType type, CellularNetwork::RegistrationStatus &status, bool &is_registered);
00142     bool is_registered();
00143     bool device_ready();
00144 
00145     // state functions to keep state machine simple
00146     void state_init();
00147     void state_power_on();
00148     void state_device_ready();
00149     void state_sim_pin();
00150     void state_signal_quality();
00151     void state_registering();
00152     void state_attaching();
00153     void enter_to_state(CellularState state);
00154     void retry_state_or_fail();
00155     void continue_from_state(CellularState state);
00156     void report_failure(const char *msg);
00157     void event();
00158     void device_ready_cb();
00159     void pre_event(CellularState state);
00160     bool check_is_target_reached();
00161     void send_event_cb(cellular_connection_status_t status);
00162     void change_timeout(const int &timeout);
00163 
00164 private:
00165 
00166 #ifdef MBED_CONF_RTOS_PRESENT
00167     rtos::Thread *_queue_thread;
00168 #endif
00169 
00170     CellularDevice &_cellularDevice;
00171     CellularState _state;
00172     CellularState _next_state;
00173     CellularState _target_state;
00174 
00175     Callback<void(nsapi_event_t, intptr_t)> _event_status_cb;
00176 
00177     CellularNetwork &_network;
00178     events::EventQueue &_queue;
00179 
00180     const char *_sim_pin;
00181     int _retry_count;
00182     int _start_time;
00183     int _event_timeout;
00184 
00185     uint16_t _retry_timeout_array[CELLULAR_RETRY_ARRAY_SIZE];
00186     int _retry_array_length;
00187     int _event_id;
00188     const char *_plmn;
00189     bool _command_success;
00190     bool _is_retry;
00191     cell_callback_data_t _cb_data;
00192     cellular_connection_status_t _current_event;
00193     int _status;
00194     PlatformMutex _mutex;
00195 
00196     // Cellular state timeouts
00197     int _state_timeout_power_on;
00198     int _state_timeout_sim_pin;
00199     int _state_timeout_registration;
00200     int _state_timeout_network;
00201     int _state_timeout_connect; // timeout for PS attach, PDN connect and socket operations
00202     // Change all cellular state timeouts to `timeout`
00203     void set_timeout(int timeout);
00204     cell_signal_quality_t _signal_quality;
00205 };
00206 
00207 } // namespace
00208 
00209 #endif /* _CELLULAR_STATEMACHINE_H_ */