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 
00033 // modem type is defined as CELLULAR_DEVICE macro
00034 #define _CELLULAR_STRINGIFY(a) #a
00035 #define CELLULAR_STRINGIFY(a) _CELLULAR_STRINGIFY(a)
00036 #include CELLULAR_STRINGIFY(CELLULAR_DEVICE.h)
00037 
00038 namespace mbed {
00039 
00040 const int PIN_SIZE = 8;
00041 const int MAX_RETRY_ARRAY_SIZE = 10;
00042 
00043 /** CellularConnectionFSM class
00044  *
00045  *  Finite State Machine for connecting to cellular network
00046  */
00047 class CellularConnectionFSM
00048 {
00049 public:
00050     CellularConnectionFSM();
00051     virtual ~CellularConnectionFSM();
00052 
00053 public:
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_REGISTER_NETWORK,
00062         STATE_REGISTERING_NETWORK,
00063         STATE_ATTACH_NETWORK,
00064         STATE_ATTACHING_NETWORK,
00065         STATE_CONNECT_NETWORK,
00066         STATE_CONNECTED,
00067     };
00068 
00069 public:
00070     /** Initialize cellular device
00071      *  @remark Must be called before any other methods
00072      *  @return see nsapi_error_t, 0 on success
00073      */
00074     nsapi_error_t init();
00075 
00076     /** Set serial connection for cellular device
00077      *  @param serial UART driver
00078      */
00079     void set_serial(UARTSerial *serial);
00080 
00081     /** Set callback for state update
00082      *  @param status_callback function to call on state changes
00083      */
00084     void set_callback(mbed::Callback<bool(int, int)> status_callback);
00085 
00086     /** Get event queue that can be chained to main event queue (or use start_dispatch)
00087      *  @return event queue
00088      */
00089     events::EventQueue* get_queue();
00090 
00091     /** Start event queue dispatching
00092      *  @return see nsapi_error_t, 0 on success
00093      */
00094     nsapi_error_t start_dispatch();
00095 
00096     /** Stop event queue dispatching and close cellular interfaces
00097      */
00098     void stop();
00099 
00100     /** Get cellular network interface
00101      *  @return network interface, NULL on failure
00102      */
00103     CellularNetwork* get_network();
00104 
00105     /** Get cellular device interface
00106      *  @return device interface, NULL on failure
00107      */
00108     CellularDevice* get_device();
00109 
00110     /** Get cellular sim interface
00111      *  @return sim interface, NULL on failure
00112      */
00113     CellularSIM* get_sim();
00114 
00115     /** Change cellular connection to the target state
00116      *  @param state to continue
00117      *  @return see nsapi_error_t, 0 on success
00118      */
00119     nsapi_error_t continue_to_state(CellularState state);
00120 
00121     /** Set cellular device SIM PIN code
00122      *  @param sim_pin PIN code
00123      */
00124     void set_sim_pin(const char *sim_pin);
00125 
00126     /** Sets the timeout array for network rejects. After reject next item is tried and after all items are waited and
00127      *  still fails then current network event will fail.
00128      *
00129      *  @param timeout      timeout array using seconds
00130      *  @param array_len    length of the array
00131      */
00132     void set_retry_timeout_array(uint16_t timeout[], int array_len);
00133 
00134 private:
00135     bool open_power(FileHandle *fh);
00136     bool open_sim();
00137     bool get_network_registration(CellularNetwork::RegistrationType type, CellularNetwork::RegistrationStatus &status, bool &is_registered);
00138     bool set_network_registration(char *plmn = 0);
00139     bool get_attach_network(CellularNetwork::AttachStatus &status);
00140     bool set_attach_network();
00141 
00142 private:
00143     friend class EasyCellularConnection;
00144     NetworkStack *get_stack();
00145 
00146 private:
00147     void device_ready();
00148     void report_failure(const char* msg);
00149     void event();
00150 
00151     UARTSerial *_serial;
00152     CellularState _state;
00153     CellularState _next_state;
00154 
00155     Callback<bool(int, int)> _status_callback;
00156 
00157     CellularNetwork *_network;
00158     CellularPower *_power;
00159     CellularSIM *_sim;
00160     events::EventQueue _queue;
00161     rtos::Thread *_queue_thread;
00162     CellularDevice *_cellularDevice;
00163     char _sim_pin[PIN_SIZE+1];
00164     int _retry_count;
00165     int _state_retry_count;
00166     int _start_time;
00167     uint16_t _retry_timeout_array[MAX_RETRY_ARRAY_SIZE];
00168     int _retry_array_length;
00169     events::EventQueue _at_queue;
00170 };
00171 
00172 } // namespace
00173 
00174 #endif // CELLULAR_DEVICE || DOXYGEN
00175 
00176 #endif /* _CELLULAR_CONNECTION_UTIL_H */