BG96Interface.h

00001 /**
00002 * copyright (c) 2018, James Flynn
00003 * SPDX-License-Identifier: Apache-2.0
00004 */
00005 
00006 /* 
00007  * Licensed under the Apache License, Version 2.0 (the "License");
00008  * you may not use this file except in compliance with the License.
00009  * You may obtain a copy of the License at
00010  *
00011  *     http://www.apache.org/licenses/LICENSE-2.0
00012  *
00013  * Unless required by applicable law or agreed to in writing, software
00014  * distributed under the License is distributed on an "AS IS" BASIS,
00015  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00016  *
00017  * See the License for the specific language governing permissions and
00018  * limitations under the License.
00019  *
00020  */
00021  
00022 /**
00023 *   @file   BG96Interface.h
00024 *   @brief  Implements NetworkInterface class for use with the Quectel BG96
00025 *           data module running MBed OS v5.x
00026 *
00027 *   @author James Flynn
00028 *
00029 *   @date   1-April-2018
00030 */
00031 
00032 #ifndef __BG96Interface_H__
00033 #define __BG96Interface_H__
00034 
00035 #include <stdint.h>
00036 
00037 #include "mbed.h"
00038 #include "Callback.h"
00039 
00040 #include "BG96.h"
00041 
00042 #define APN_DEFAULT          "m2m.com.attz"
00043 #define BG96_MISC_TIMEOUT    15000
00044 #define BG96_SOCKET_COUNT    5
00045 
00046 #define DBGMSG_DRV           0x04
00047 #define DBGMSG_EQ            0x08
00048 #define DBGMSG_ARRY          0x20
00049 
00050 #define FIRMWARE_REV(x)      (((BG96Interface*)x)->getRevision())
00051 
00052 typedef struct rx_event_t {
00053     int      m_rx_state;            //state of the socket receive 
00054     int      m_rx_socketID;         //which socket is being rcvd on
00055     uint8_t *m_rx_dptr;             //pointer to the users data buffer
00056     uint32_t m_rx_req_size;         //Requested number of bytes to receive
00057     uint32_t m_rx_asked_size;
00058     uint32_t m_rx_total_cnt;        //Total number of bytes received
00059     int      m_rx_timer;            //Rx Timeout Timer
00060     int      m_rx_disTO;            //Flag to disable Timeout Timer
00061     void    (*m_rx_callback)(void*);//callback used with attach
00062     void     *m_rx_cb_data;         //callback data to be returned
00063     uint32_t m_rx_return_cnt;       //number of bytes the Event Queue is returning
00064     } RXEVENT;
00065 
00066 typedef struct tx_event_t {
00067     int      m_tx_state;
00068     int      m_tx_socketID;
00069     uint8_t *m_tx_dptr;
00070     unsigned m_tx_orig_size;
00071     uint32_t m_tx_req_size;
00072     uint32_t m_tx_total_sent;
00073     void    (*m_tx_callback)(void*);
00074     void     *m_tx_cb_data;
00075     } TXEVENT;
00076 
00077 
00078 /** BG96_socket class
00079  *  Implementation of BG96 socket structure
00080  */
00081 typedef struct _socket_t {
00082     int              id;                   //nbr given by BG96 driver or -1 if not used
00083     SocketAddress    addr;                 //address this socket is attached to
00084     bool             disTO;                //true of socket is listening for incomming data
00085     nsapi_protocol_t proto;                //TCP or UDP
00086     bool             connected;            //true if socket is connected
00087     void             (*_callback)(void*);  //callback used with attach
00088     void             *_data;               //callback data to be returned
00089     void             *dptr_last;           //pointer to the last data buffer used
00090     unsigned         dptr_size;            //the size of the last user data buffer
00091     } BG96SOCKET;
00092 
00093 
00094 class BG96Interface : public NetworkStack, public NetworkInterface
00095 {
00096 public:
00097     BG96Interface();
00098     virtual ~BG96Interface();
00099 
00100     /** Connect to the network (no parameters)
00101      *
00102      *  @return         nsapi_error_t
00103      */
00104     virtual nsapi_error_t connect(void);
00105 
00106     /** Connect to the network
00107      *
00108      *  @param apn      Optional, APN of network
00109      *  @param user     Optional, username --not used--
00110      *  @param pass     Optional, password --not used--
00111      *  @return         nsapi_error_t
00112      */
00113     virtual nsapi_error_t connect(const char *apn, const char *username = 0, const char *password = 0);
00114  
00115     /** Set the cellular network credentials
00116      *
00117      *  @param apn      Optional, APN of network
00118      *  @param user     Optional, username --not used--
00119      *  @param pass     Optional, password --not used--
00120      *  @return         nsapi_error_t
00121      */
00122     virtual nsapi_error_t set_credentials(const char *apn = 0,
00123             const char *username = 0, const char *password = 0);
00124  
00125     /** disconnect from the network
00126      *
00127      *  @return         nsapi_error_t
00128      */
00129     virtual nsapi_error_t disconnect();
00130 
00131     /** Get the IP address of WNC device. From NetworkStack Class
00132      *
00133      *  @return         IP address string or null 
00134      */
00135     virtual const char *get_ip_address();
00136  
00137     /** Get the MAC address of the WNC device.  
00138      *
00139      *  @return         MAC address of the interface
00140      */
00141     virtual const char *get_mac_address();
00142  
00143    /** Query Module SW revision
00144      *
00145      *  @return         SW Revision string
00146      */
00147     const char* getRevision(void);
00148 
00149    /** Query registered state 
00150      *
00151      *  @return         true if registerd, false if not 
00152      */
00153     bool registered();
00154 
00155     /** Set the level of Debug output
00156      *
00157      *  @param             bit field
00158      *  mbed driver info     = 0x04
00159      *  dump buffers         = 0x20
00160      *  AT command tracing   = 0x80
00161      */
00162     void doDebug( int v );
00163     
00164 
00165 protected:
00166 
00167     /** Get Host IP by name. 
00168      *
00169      *  @return         nsapi_error_t
00170      */
00171     virtual nsapi_error_t gethostbyname(const char* name, SocketAddress *address, nsapi_version_t version);
00172 
00173 
00174     /** return a pointer to the NetworkStack object
00175      *
00176      *  @return          The underlying NetworkStack object
00177      */
00178     virtual NetworkStack *get_stack(void);
00179 
00180     /** Open a socket. 
00181      *
00182      *  @param handle       Handle in which to store new socket
00183      *  @param proto        Type of socket to open, NSAPI_TCP or NSAPI_UDP
00184      *  @return             nsapi_error_t
00185      */
00186     virtual int socket_open(void **handle, nsapi_protocol_t proto);
00187  
00188 
00189     /*  setsockopt allows applications to pass stack-specific hints
00190      *  to the underlying stack. For unsupported options,
00191      *  NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
00192      *
00193      *  @param handle   Socket handle
00194      *  @param level    Stack-specific protocol level
00195      *  @param optname  Stack-specific option identifier
00196      *  @param optval   Option value
00197      *  @param optlen   Length of the option value
00198      *  @return         nsapi_error_t
00199      */
00200      virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level, int optname, const void *optval, unsigned optlen);
00201     
00202 
00203     /*  getsockopt retrieves stack-specific options.
00204      *
00205      *  unsupported options return NSAPI_ERROR_UNSUPPORTED
00206      *
00207      *  @param level    Stack-specific protocol level or nsapi_socket_level_t
00208      *  @param optname  Level-specific option name
00209      *  @param optval   Destination for option value
00210      *  @param optlen   Length of the option value
00211      *  @return         nsapi_error_t
00212      */
00213      virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, int optname, void *optval, unsigned *optlen);
00214 
00215 
00216     /** Close the socket. 
00217      *
00218      *  @param handle       Socket handle
00219      *  @return             0 on success, negative on failure
00220      */
00221     virtual int socket_close(void *handle);
00222  
00223     /** Bind a server socket to a specific port.
00224      *
00225      *  @brief              Bind the socket to a specific port
00226      *  @param handle       Socket handle
00227      *  @param address      address to listen for 
00228      *  @return             0;
00229      */
00230     virtual int socket_bind(void *handle, const SocketAddress &address);
00231  
00232     /** Start listening for incoming connections.
00233      *
00234      *  @brief              NOT SUPPORTED
00235      *  @param handle       Socket handle
00236      *  @param backlog      Number of pending connections that can be queued up at any
00237      *                      one time [Default: 1]
00238      *  @return             nsapi_error_t
00239      */
00240     virtual nsapi_error_t socket_listen(void *handle, int backlog);
00241  
00242     /** Accept a new connection.
00243      *
00244      *  @brief              NOT SUPPORTED
00245      *  @return             NSAPI_ERROR_UNSUPPORTED;
00246      */
00247     virtual int socket_accept(nsapi_socket_t server,
00248             nsapi_socket_t *handle, SocketAddress *address=0);
00249  
00250     /** Connects this socket to the server.
00251      *
00252      *  @param handle       Socket handle
00253      *  @param address      SocketAddress 
00254      *  @return             nsapi_error_t
00255      */
00256     virtual int socket_connect(void *handle, const SocketAddress &address);
00257  
00258     /** Send data to the remote host.
00259      *
00260      *  @param handle       Socket handle
00261      *  @param data         buffer to send
00262      *  @param size         length of buffer
00263      *  @return             Number of bytes written or negative on failure
00264      *
00265      *  @note This call is non-blocking. 
00266      */
00267     virtual int socket_send(void *handle, const void *data, unsigned size);
00268  
00269     /** Receive data from the remote host.
00270      *
00271      *  @param handle       Socket handle
00272      *  @param data         buffer to store the recived data
00273      *  @param size         bytes to receive
00274      *  @return             received bytes received, negative on failure
00275      *
00276      *  @note This call is non-blocking. 
00277      */
00278     virtual int socket_recv(void *handle, void *data, unsigned size);
00279  
00280     /** Send a packet to a remote endpoint.
00281      *
00282      *  @param handle       Socket handle
00283      *  @param address      SocketAddress
00284      *  @param data         data to send
00285      *  @param size         number of bytes to send
00286      *  @return the         number of bytes sent or negative on failure
00287      *
00288      *  @note This call is non-blocking 
00289      */
00290     virtual int socket_sendto(void *handle, const SocketAddress &address, const void *data, unsigned size);
00291  
00292     /** Receive packet remote endpoint
00293      *
00294      *  @param handle       Socket handle
00295      *  @param address      SocketAddress 
00296      *  @param buffer       buffer to store data to
00297      *  @param size         number of bytes to receive
00298      *  @return the         number bytes received or negative on failure
00299      *
00300      *  @note This call is non-blocking 
00301      */
00302     virtual int socket_recvfrom(void *handle, SocketAddress *address, void *buffer, unsigned size);
00303  
00304     /** Register a callback on state change of the socket
00305      *
00306      *  @param handle       Socket handle
00307      *  @param callback     Function to call on state change
00308      *  @param data         Argument to pass to callback
00309      *
00310      *  @note Callback may be called in an interrupt context.
00311      */
00312     virtual void socket_attach(void *handle, void (*callback)(void *), void *data);
00313 
00314 private:
00315     
00316     int        tx_event(TXEVENT *ptr);                  //called to TX data
00317     int        rx_event(RXEVENT *ptr);                  //called to RX data
00318     void       g_eq_event(void);                        //event queue to tx/rx
00319     void       _eq_schedule(void);
00320 
00321     nsapi_error_t g_isInitialized;                      //TRUE if the BG96Interface is connected to the network
00322     int        g_bg96_queue_id;                         //the ID of the EventQueue used by the driver
00323     uint32_t   scheduled_events;
00324 
00325     BG96SOCKET g_sock[BG96_SOCKET_COUNT];               //
00326     TXEVENT    g_socTx[BG96_SOCKET_COUNT];              //
00327     RXEVENT    g_socRx[BG96_SOCKET_COUNT];              //
00328 
00329     Thread     _bg96_monitor;                           //event queue thread
00330     EventQueue _bg96_queue;
00331 
00332     Mutex      gvupdate_mutex;                          //protect global variable updates
00333     Mutex      txrx_mutex;                              //protect RX/TX event queue activities
00334     BG96       _BG96;                                   //create the BG96 HW interface object
00335 
00336     #if MBED_CONF_APP_BG96_DEBUG == true
00337     Mutex      dbgout_mutex;
00338     int        g_debug;                                 //flag for debug settings
00339     void       _dbDump_arry( const uint8_t* data, unsigned int size );
00340     void       _dbOut(int, const char *format, ...);
00341     #endif
00342     
00343 };
00344 
00345 #endif /* __BG96Interface_H__ */
00346