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