CellularConnectionFSM.h

00001 /*
00002  * Copyright (c) 2017, 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 
00018 #ifndef _CELLULAR_CONNECTION_UTIL_H
00019 #define _CELLULAR_CONNECTION_UTIL_H
00020 
00021 #include "CellularTargets.h"
00022 #if defined(CELLULAR_DEVICE) || defined(DOXYGEN_ONLY)
00023 
00024 #include "UARTSerial.h"
00025 #include "NetworkInterface.h"
00026 #include "EventQueue.h"
00027 #include "Thread.h"
00028 
00029 #include "CellularNetwork.h"
00030 #include "CellularPower.h"
00031 #include "CellularSIM.h"
00032 #include "CellularUtil.h"
00033 
00034 // modem type is defined as CELLULAR_DEVICE macro
00035 #include CELLULAR_STRINGIFY(CELLULAR_DEVICE.h)
00036 
00037 namespace mbed {
00038 
00039 const int PIN_SIZE = 8;
00040 const int MAX_RETRY_ARRAY_SIZE = 10;
00041 
00042 /** CellularConnectionFSM class
00043  *
00044  *  Finite State Machine for connecting to cellular network
00045  */
00046 class CellularConnectionFSM
00047 {
00048 public:
00049     CellularConnectionFSM();
00050     virtual ~CellularConnectionFSM();
00051 
00052 public:
00053     /** Cellular connection states
00054      */
00055     enum CellularState {
00056         STATE_INIT = 0,
00057         STATE_POWER_ON,
00058         STATE_DEVICE_READY,
00059         STATE_SIM_PIN,
00060         STATE_REGISTERING_NETWORK,
00061         STATE_MANUAL_REGISTERING_NETWORK,
00062         STATE_ATTACHING_NETWORK,
00063         STATE_ACTIVATING_PDP_CONTEXT,
00064         STATE_CONNECTING_NETWORK,
00065         STATE_CONNECTED
00066     };
00067 
00068 public:
00069     /** Initialize cellular device
00070      *  @remark Must be called before any other methods
00071      *  @return see nsapi_error_t, 0 on success
00072      */
00073     nsapi_error_t init();
00074 
00075     /** Set serial connection for cellular device
00076      *  @param serial UART driver
00077      */
00078     void set_serial(UARTSerial *serial);
00079 
00080     /** Set callback for state update
00081      *  @param status_callback function to call on state changes
00082      */
00083     void set_callback(mbed::Callback<bool(int, int)> status_callback);
00084 
00085     /** Register callback for status reporting
00086      *
00087      *  The specified status callback function will be called on status changes
00088      *  on the network. The parameters on the callback are the event type and
00089      *  event-type dependent reason parameter.
00090      *
00091      *  @param status_cb The callback for status changes
00092      */
00093     virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb);
00094 
00095     /** Get event queue that can be chained to main event queue (or use start_dispatch)
00096      *  @return event queue
00097      */
00098     events::EventQueue *get_queue();
00099 
00100     /** Start event queue dispatching
00101      *  @return see nsapi_error_t, 0 on success
00102      */
00103     nsapi_error_t start_dispatch();
00104 
00105     /** Stop event queue dispatching and close cellular interfaces. After calling stop(), init() must be called
00106      *  before any other methods.
00107      */
00108     void stop();
00109 
00110     /** Get cellular network interface
00111      *  @return network interface, NULL on failure
00112      */
00113     CellularNetwork *get_network();
00114 
00115     /** Get cellular device interface
00116      *  @return device interface, NULL on failure
00117      */
00118     CellularDevice *get_device();
00119 
00120     /** Get cellular sim interface. SIM interface is released after SIM is open and ready for use (moving from STATE_SIM_PIN to next state).
00121      *  After SIM interface is closed this method will return NULL. SIM interface can be created again via CellularDevice
00122      *  which you can get with the method get_device().
00123      *  @return sim interface, NULL on failure
00124      */
00125     CellularSIM *get_sim();
00126 
00127     /** Change cellular connection to the target state
00128      *  @param state to continue. Default is to connect.
00129      *  @return see nsapi_error_t, 0 on success
00130      */
00131     nsapi_error_t continue_to_state(CellularState state = STATE_CONNECTED);
00132 
00133     /** Set cellular device SIM PIN code
00134      *  @param sim_pin PIN code
00135      */
00136     void set_sim_pin(const char *sim_pin);
00137 
00138     /** Sets the timeout array for network rejects. After reject next item is tried and after all items are waited and
00139      *  still fails then current network event will fail.
00140      *
00141      *  @param timeout      timeout array using seconds
00142      *  @param array_len    length of the array
00143      */
00144     void set_retry_timeout_array(uint16_t timeout[], int array_len);
00145 
00146     /** Sets the operator plmn which is used when registering to a network specified by plmn. If plmn is not set then automatic
00147      *  registering is used when registering to a cellular network. Does not start any operations.
00148      *
00149      *  @param plmn operator in numeric format. See more from 3GPP TS 27.007 chapter 7.3.
00150      */
00151     void set_plmn(const char* plmn);
00152 
00153     /** returns readable format of the given state. Used for printing states while debugging.
00154      *
00155      *  @param state state which is returned in string format
00156      *  @return      string format of the given state
00157      */
00158     const char *get_state_string(CellularState state);
00159 
00160 private:
00161     bool power_on();
00162     bool open_sim();
00163     bool get_network_registration(CellularNetwork::RegistrationType type, CellularNetwork::RegistrationStatus &status, bool &is_registered);
00164     bool is_registered();
00165     void device_ready();
00166 
00167     // state functions to keep state machine simple
00168     void state_init();
00169     void state_power_on();
00170     void state_device_ready();
00171     void state_sim_pin();
00172     void state_registering();
00173     void state_manual_registering_network();
00174     void state_attaching();
00175     void state_activating_pdp_context();
00176     void state_connect_to_network();
00177     void state_connected();
00178     void enter_to_state(CellularState state);
00179     void retry_state_or_fail();
00180     void network_callback(nsapi_event_t ev, intptr_t ptr);
00181     nsapi_error_t continue_from_state(CellularState state);
00182     bool is_registered_to_plmn();
00183 
00184 private:
00185     friend class EasyCellularConnection;
00186     NetworkStack *get_stack();
00187 
00188 private:
00189     void report_failure(const char* msg);
00190     void event();
00191     void ready_urc_cb();
00192 
00193     UARTSerial *_serial;
00194     CellularState _state;
00195     CellularState _next_state;
00196 
00197     Callback<bool(int, int)> _status_callback;
00198     Callback<void(nsapi_event_t, intptr_t)> _event_status_cb;
00199 
00200     CellularNetwork *_network;
00201     CellularPower *_power;
00202     CellularSIM *_sim;
00203     events::EventQueue _queue;
00204     rtos::Thread *_queue_thread;
00205     CellularDevice *_cellularDevice;
00206     char _sim_pin[PIN_SIZE+1];
00207     int _retry_count;
00208     int _start_time;
00209     int _event_timeout;
00210 
00211     uint16_t _retry_timeout_array[MAX_RETRY_ARRAY_SIZE];
00212     int _retry_array_length;
00213     events::EventQueue _at_queue;
00214     char _st_string[20];
00215     int _event_id;
00216     const char *_plmn;
00217     bool _command_success;
00218     bool _plmn_network_found;
00219 };
00220 
00221 } // namespace
00222 
00223 #endif // CELLULAR_DEVICE || DOXYGEN
00224 
00225 #endif /* _CELLULAR_CONNECTION_UTIL_H */