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_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
00105      */
00106     void stop();
00107 
00108     /** Get cellular network interface
00109      *  @return network interface, NULL on failure
00110      */
00111     CellularNetwork* get_network();
00112 
00113     /** Get cellular device interface
00114      *  @return device interface, NULL on failure
00115      */
00116     CellularDevice* get_device();
00117 
00118     /** Get cellular sim interface
00119      *  @return sim interface, NULL on failure
00120      */
00121     CellularSIM* get_sim();
00122 
00123     /** Change cellular connection to the target state
00124      *  @param state to continue. Default is to connect.
00125      *  @return see nsapi_error_t, 0 on success
00126      */
00127     nsapi_error_t continue_to_state(CellularState state = STATE_CONNECTED);
00128 
00129     /** Set cellular device SIM PIN code
00130      *  @param sim_pin PIN code
00131      */
00132     void set_sim_pin(const char *sim_pin);
00133 
00134     /** Sets the timeout array for network rejects. After reject next item is tried and after all items are waited and
00135      *  still fails then current network event will fail.
00136      *
00137      *  @param timeout      timeout array using seconds
00138      *  @param array_len    length of the array
00139      */
00140     void set_retry_timeout_array(uint16_t timeout[], int array_len);
00141 
00142     const char* get_state_string(CellularState state);
00143 private:
00144     bool power_on();
00145     bool open_sim();
00146     bool get_network_registration(CellularNetwork::RegistrationType type, CellularNetwork::RegistrationStatus &status, bool &is_registered);
00147     bool set_network_registration(char *plmn = 0);
00148     bool get_attach_network(CellularNetwork::AttachStatus &status);
00149     bool set_attach_network();
00150     bool is_registered();
00151     bool device_ready();
00152     nsapi_error_t is_automatic_registering(bool& auto_reg);
00153 
00154     // state functions to keep state machine simple
00155     void state_init();
00156     void state_power_on();
00157     void state_device_ready();
00158     void state_sim_pin();
00159     void state_registering();
00160     void state_attaching();
00161     void state_activating_pdp_context();
00162     void state_connect_to_network();
00163     void state_connected();
00164     void enter_to_state(CellularState state);
00165     void retry_state_or_fail();
00166     void network_callback(nsapi_event_t ev, intptr_t ptr);
00167     nsapi_error_t continue_from_state(CellularState state);
00168 
00169 private:
00170     friend class EasyCellularConnection;
00171     NetworkStack *get_stack();
00172 
00173 private:
00174     void report_failure(const char* msg);
00175     void event();
00176     void ready_urc_cb();
00177 
00178     UARTSerial *_serial;
00179     CellularState _state;
00180     CellularState _next_state;
00181 
00182     Callback<bool(int, int)> _status_callback;
00183     Callback<void(nsapi_event_t, intptr_t)> _event_status_cb;
00184 
00185     CellularNetwork *_network;
00186     CellularPower *_power;
00187     CellularSIM *_sim;
00188     events::EventQueue _queue;
00189     rtos::Thread *_queue_thread;
00190     CellularDevice *_cellularDevice;
00191     char _sim_pin[PIN_SIZE+1];
00192     int _retry_count;
00193     int _start_time;
00194     int _event_timeout;
00195 
00196     uint16_t _retry_timeout_array[MAX_RETRY_ARRAY_SIZE];
00197     int _retry_array_length;
00198     events::EventQueue _at_queue;
00199     char _st_string[20];
00200     int _event_id;
00201 };
00202 
00203 } // namespace
00204 
00205 #endif // CELLULAR_DEVICE || DOXYGEN
00206 
00207 #endif /* _CELLULAR_CONNECTION_UTIL_H */