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
00121      *  @return sim interface, NULL on failure
00122      */
00123     CellularSIM* get_sim();
00124 
00125     /** Change cellular connection to the target state
00126      *  @param state to continue. Default is to connect.
00127      *  @return see nsapi_error_t, 0 on success
00128      */
00129     nsapi_error_t continue_to_state(CellularState state = STATE_CONNECTED);
00130 
00131     /** Set cellular device SIM PIN code
00132      *  @param sim_pin PIN code
00133      */
00134     void set_sim_pin(const char *sim_pin);
00135 
00136     /** Sets the timeout array for network rejects. After reject next item is tried and after all items are waited and
00137      *  still fails then current network event will fail.
00138      *
00139      *  @param timeout      timeout array using seconds
00140      *  @param array_len    length of the array
00141      */
00142     void set_retry_timeout_array(uint16_t timeout[], int array_len);
00143 
00144     /** Sets the operator plmn which is used when registering to a network specified by plmn. If plmn is not set then automatic
00145      *  registering is used when registering to a cellular network. Does not start any operations.
00146      *
00147      *  @param plmn operator in numeric format. See more from 3GPP TS 27.007 chapter 7.3.
00148      */
00149     void set_plmn(const char* plmn);
00150 
00151     /** returns readable format of the given state. Used for printing states while debugging.
00152      *
00153      *  @param state state which is returned in string format
00154      *  @return      string format of the given state
00155      */
00156     const char* get_state_string(CellularState state);
00157 
00158 private:
00159     bool power_on();
00160     bool open_sim();
00161     bool get_network_registration(CellularNetwork::RegistrationType type, CellularNetwork::RegistrationStatus &status, bool &is_registered);
00162     bool set_network_registration();
00163     bool get_attach_network(CellularNetwork::AttachStatus &status);
00164     bool set_attach_network();
00165     bool is_registered();
00166     bool device_ready();
00167     nsapi_error_t is_automatic_registering(bool& auto_reg);
00168 
00169     // state functions to keep state machine simple
00170     void state_init();
00171     void state_power_on();
00172     void state_device_ready();
00173     void state_sim_pin();
00174     void state_registering();
00175     void state_manual_registering_network();
00176     void state_attaching();
00177     void state_activating_pdp_context();
00178     void state_connect_to_network();
00179     void state_connected();
00180     void enter_to_state(CellularState state);
00181     void retry_state_or_fail();
00182     void network_callback(nsapi_event_t ev, intptr_t ptr);
00183     nsapi_error_t continue_from_state(CellularState state);
00184     bool is_registered_to_plmn();
00185 
00186 private:
00187     friend class EasyCellularConnection;
00188     NetworkStack *get_stack();
00189 
00190 private:
00191     void report_failure(const char* msg);
00192     void event();
00193     void ready_urc_cb();
00194 
00195     UARTSerial *_serial;
00196     CellularState _state;
00197     CellularState _next_state;
00198 
00199     Callback<bool(int, int)> _status_callback;
00200     Callback<void(nsapi_event_t, intptr_t)> _event_status_cb;
00201 
00202     CellularNetwork *_network;
00203     CellularPower *_power;
00204     CellularSIM *_sim;
00205     events::EventQueue _queue;
00206     rtos::Thread *_queue_thread;
00207     CellularDevice *_cellularDevice;
00208     char _sim_pin[PIN_SIZE+1];
00209     int _retry_count;
00210     int _start_time;
00211     int _event_timeout;
00212 
00213     uint16_t _retry_timeout_array[MAX_RETRY_ARRAY_SIZE];
00214     int _retry_array_length;
00215     events::EventQueue _at_queue;
00216     char _st_string[20];
00217     int _event_id;
00218     const char* _plmn;
00219     bool _command_success;
00220     bool _plmn_network_found;
00221 };
00222 
00223 } // namespace
00224 
00225 #endif // CELLULAR_DEVICE || DOXYGEN
00226 
00227 #endif /* _CELLULAR_CONNECTION_UTIL_H */