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