Revision 0:55ec71dc0347, committed 2016-09-21

Comitter:

JMF

Date:

Wed Sep 21 14:30:06 2016 +0000

Child:

1:e511ea8d39d5

Commit message:

Initial Commit

Changed in this revision

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.md	Wed Sep 21 14:30:06 2016 +0000
@@ -0,0 +1,61 @@
+Interface Library
+========================
+
+The WDCInterface Library is an a C++ API for connecting to the Internet using a Wistron NeWeb Corporation (WNC) M14A2A 
+Series data module.  The WDCInterface library consists of a WDC Controller class, a collection of sockets, and an 
+interface class.  Collectively, these files creat an interface class that is used in the AT&T Cellular IoT Starter Kit 
+which is sold by Avnet (http://cloudconnectkits.org/product/att-cellular-iot-starter-kit). This interface class library 
+is a drop-in replacement for an EthernetInterface class.
+
+Occasionally, the WNC Data Module will encounter internal failures that cause the device to cease communicating. To prevent
+the system from unexpectedly hanging, the WNCInterface class has implemented three user configuration settings as described 
+below:
+
+1. Configure the WNCInterface for (1) debug enabled OR (2) disabled.  The default/current setting is debug enabled. When
+debug is enabled, it opens stdio over the USB using the OpenSDA (serial over USB running at 115200-N81).
+
+2. Configure the WNCInterface to either (1) Hang by executing a 'while(true)' loop when the error occurs OR (2) Have the 
+WNCInterface return a Failure (-1) for the current and all subsequent calls.  The default/current setting is to
+Hange execution.
+
+3. Configure the WNCInterface to either (1) Display the failure location to the debug port OR (2) display nothing when
+the error occurs.  The default/current setting is to display the failure location.
+
+To create the complete WNCInterface class, you must also install the WncController class.  This is the hardware abstraction
+layer utilized by WNCInterface to communicate wiht the hardware.  It is installed within the WNCInterface class from: 
+https://developer.mbed.org/users/fkellermavnet/code/WncControllerK64F/
+
+To demonstrate the use of the WDCInterface, a series of example programs have been developed.  Links to these examples
+are provided below.
+
+**NOTE**: This library/class is specific to the AT&T Cellular IoT Starter Kit which uses a FRDM-K64F.  The users mbed.org 
+compiler should be configured to use the FRDM-K64F platform.
+
+Example Programs
+================
+
+Import the example programs below and follow the README.md in each to run the example program.
+
+  * https://github.com/jflynn129/WNCInterface_HTTP
+  * https://github.com/jflynn129/WNCInterface_M2Xdemo
+  * https://github.com/jflynn129/WNCInterface_M2XMQTTdemo
+  * https://github.com/jflynn129/WNCInterface_MQTT_hivemq
+
+WNC FIRWARE VERSION
+===================
+
+The WNCInterface class currently supports the following version(s):
+* MPSS: M14A2A_v11.21.162331 APSS: M14A2A_v11.27.162331
+
+
+License
+=======
+This library is released under the    Licensed under the Apache License, Version 2.0 (the "License"); you may not use this 
+file except in compliance with the License and may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an 
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific 
+language governing permissions and limitations under the License.
+

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/WNCInterface.cpp	Wed Sep 21 14:30:06 2016 +0000
@@ -0,0 +1,186 @@
+/* =====================================================================
+   Copyright © 2016, Avnet (R)
+
+   Contributors:
+     * James M Flynn, www.em.avnet.com 
+ 
+   Licensed under the Apache License, Version 2.0 (the "License"); 
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, 
+   software distributed under the License is distributed on an 
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, 
+   either express or implied. See the License for the specific 
+   language governing permissions and limitations under the License.
+
+    @file          WNCInterface.cpp
+    @version       1.0
+    @date          Sept 2016
+    @author        James Flynn
+
+======================================================================== */
+
+
+#ifndef __MODULE__
+#define __MODULE__ "WNCInterface.cpp"
+#endif
+
+#include "WNCInterface.h"
+
+/////////////////////////////////////////////////////
+// NXP GPIO Pins that are used to initialize the WNC Shield
+/////////////////////////////////////////////////////
+DigitalOut  mdm_uart2_rx_boot_mode_sel(PTC17);  // on powerup, 0 = boot mode, 1 = normal boot
+DigitalOut  mdm_power_on(PTB9);                 // 0 = turn modem on, 1 = turn modem off (should be held high for >5 seconds to cycle modem)
+DigitalOut  mdm_wakeup_in(PTC2);                // 0 = let modem sleep, 1 = keep modem awake -- Note: pulled high on shield
+DigitalOut  mdm_reset(PTC12);                   // active high
+DigitalOut  shield_3v3_1v8_sig_trans_ena(PTC4); // 0 = disabled (all signals high impedence, 1 = translation active
+DigitalOut  mdm_uart1_cts(PTD0);
+
+char * _fatal_err_loc;                          //GLOBAL::holds any error location info
+
+using namespace WncControllerK64F_fk;       // namespace for the controller class use
+
+// Define pin associations for the controller class to use be careful to 
+//  keep the order of the pins in the initialization list.
+WncGpioPinListK64F wncPinList = { 
+    &mdm_uart2_rx_boot_mode_sel,
+    &mdm_power_on,
+    &mdm_wakeup_in,
+    &mdm_reset,
+    &shield_3v3_1v8_sig_trans_ena,
+    &mdm_uart1_cts
+};
+
+static MODSERIAL mdmUart(PTD3,PTD2,256,4096);       //UART for WNC Module
+
+#if WNC_DEBUG == 1
+static MODSERIAL debugUart(USBTX,USBRX,256,256);    //UART used for stdio/stderr
+static WncControllerK64F wnc(&wncPinList, &mdmUart, &debugUart);
+#else
+static WncControllerK64F wnc(&wncPinList, &mdmUart, NULL);
+#endif
+
+WncControllerK64F *WNCInterface::_pwnc = &wnc;
+WncIpStats WNCInterface::myNetStats;
+string WNCInterface::mac;
+  
+WNCInterface::WNCInterface() {
+#if WNC_DEBUG == 1
+  debugUart.baud(115200);       // set stdio/stderr. use 115.2K since the WNC part uses this--keep up.
+#endif
+}
+
+void WNCInterface::doDebug( int v ) {
+#if WNC_DEBUG == 1
+    //basic debug = 0x01
+    //more debug  = 0x02
+    //all debug   = 0x03
+    _pwnc->enableDebug( (v&1), (v&2) );
+#endif
+}
+    
+//
+// Power-up the WNC module.  The caller can optionally configure.
+// Inputs:
+//    apn - Caller can specify an APN. If none is provided will use "m2m.com.attz"
+//   debug- specify the amount of debug the WNC controller should output:
+//          1 - Basic Debug output
+//          2 - Verbose Debug output
+//          3 - Full Debug output
+// Returns: 0 if unable to initialize the WNC module
+//         -1 if successfully initialized
+//
+int WNCInterface::init(const char* apn, int debug) {
+    int ret = 0;
+    _pwnc = &wnc;   //set the pointer to the WNC controller class.  Used for all WNC accesses
+
+    if( apn==NULL )
+        apn = APN_DEFAULT;
+
+#if WNC_DEBUG == 1
+    if( debug )
+        _pwnc->enableDebug( (debug&1), (debug&2) );
+#else
+    debug=debug;        //keep the compiler from complaining.
+#endif
+
+    ret =  ( _pwnc->powerWncOn(apn,40) )? 2:0;
+    ret |= ( _pwnc->setApnName(apn) )? 1:0;
+    ret |= ( _pwnc->getWncNetworkingStats(&myNetStats) )? 4:0;
+
+    return ret;
+}
+
+//
+// check to see if we are connected to the internet or not. The 
+// connection is supposed to happen during init.  If we are
+// connected to the internet return 0 otherwise return -1
+//
+int WNCInterface::connect(void) {
+    return ( _pwnc->getWncStatus() == WNC_GOOD )? 0 : -1;
+}
+
+//
+// ok, the user wants to disconnect.  At present, this isn't possible
+// with the WNC, so just fake it and say we did...
+//
+int WNCInterface::disconnect() {
+    return 0;
+}
+
+//
+// update the networking stats and return the IP Address
+//
+char * WNCInterface::getIPAddress() {
+    if ( _pwnc->getWncNetworkingStats(&myNetStats) ) {
+        if( WNCInterface::_pwnc->getWncStatus() == FATAL_FLAG )
+            FATAL_WNC_ERROR(null);
+        return &myNetStats.ip[0];
+    }
+    return NULL;
+}
+
+//
+// update the networking stats and return the Gateway Address
+//
+char * WNCInterface::getGateway() {
+    if ( _pwnc->getWncNetworkingStats(&myNetStats) ) {
+        if( WNCInterface::_pwnc->getWncStatus() == FATAL_FLAG )
+            FATAL_WNC_ERROR(null);
+        return &WNCInterface::myNetStats.gateway[0];
+    }
+    return NULL;
+}
+
+//
+// update the networking stats and return the Network Mask
+//
+char * WNCInterface::getNetworkMask() {
+    if ( _pwnc->getWncNetworkingStats(&myNetStats) ) {
+        if( WNCInterface::_pwnc->getWncStatus() == FATAL_FLAG )
+            FATAL_WNC_ERROR(null);
+        return &WNCInterface::myNetStats.mask[0];
+    }
+    return NULL;
+}
+
+//
+// return a pesudo-MAC address created from the ICCID
+//
+char* WNCInterface::getMACAddress( void ) {
+    string str;
+  
+    if( _pwnc->getICCID(&str) ) {
+        if( WNCInterface::_pwnc->getWncStatus() == FATAL_FLAG )
+            FATAL_WNC_ERROR(null);
+        mac = str.substr(3,20);
+        mac[2]=mac[5]=mac[8]=mac[11]=mac[14]=':';
+    return (char*)mac.c_str();
+    }
+    return NULL;
+}
+

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/WNCInterface.h	Wed Sep 21 14:30:06 2016 +0000
@@ -0,0 +1,140 @@
+/* =====================================================================
+   Copyright © 2016, Avnet (R)
+
+   Contributors:
+     * James Flynn, www.em.avnet.com 
+ 
+   Licensed under the Apache License, Version 2.0 (the "License"); 
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, 
+   software distributed under the License is distributed on an 
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, 
+   either express or implied. See the License for the specific 
+   language governing permissions and limitations under the License.
+
+    @file          WNCInterface.h
+    @version       1.0
+    @date          Sept 2016
+
+======================================================================== */
+
+
+#include <stddef.h>
+#include "WncControllerK64F/WncControllerK64F.h"
+
+#ifndef _WNCINTERFACE_H_
+#define _WNCINTERFACE_H_
+
+#define WNC_DEBUG   1   //1=enable the WNC debug port
+                                //0=disable the WNC debug port
+#define STOP_ON_FE  1   //1=hang forever if a fatal error occurs
+                //0=simply return failed response for all socket calls
+#define DISPLAY_FE  1   //1 to display the fatal error when it occurs
+                //0 to NOT display the fatal error
+#define APN_DEFAULT     "m2m.com.attz"
+                        
+//
+// WNC Error Handling macros & data
+//
+#define FATAL_FLAG  WncController_fk::WncController::WNC_NO_RESPONSE
+#define WNC_GOOD    WncController_fk::WncController::WNC_ON
+
+#define RETfail return -1
+#define RETvoid return
+#define RETnull return NULL
+#define DORET(x) RET##x
+
+#define TOSTR(x) #x
+#define INTSTR(x) TOSTR(x)
+#define FATAL_STR __FILE__ ":" INTSTR(__LINE__)
+
+#if DISPLAY_FE == 1
+#define PFE     printf("WNC FAILED @ %s\r\n", FATAL_STR)
+#else
+#define PFE
+#endif
+
+#if STOP_ON_FE == 1
+#define FATAL_WNC_ERROR(v)  {extern char *_fatal_err_loc;_fatal_err_loc=FATAL_STR;PFE;while(1);}
+#else
+#define FATAL_WNC_ERROR(v)  {extern char *_fatal_err_loc;_fatal_err_loc=FATAL_STR;PFE;DORET(v);}
+#endif
+
+
+// Because the WncController has intermixed socket & interface functionallity
+// will need to make the Socket class a friend of the Interface class. This 
+// will allow the Socket class to get to the WNC functions needed for the
+// socket. Forward reference the class
+
+class Socket;
+class Endpoint;
+class UDPSocket;
+class TCPSocketConnection;
+
+class WNCInterface
+{
+  class WncControllerK64F;  //forward reference the Controller Class
+  friend class TCPSocketConnection;
+  friend class UDPSocket;
+  friend class Endpoint;
+  friend class Socket;
+
+public:
+  /** Create WNC Data Module Interface Instance for the device (M14A2A) */
+  WNCInterface();
+
+  /** Initialize the interface (no connection at this point).
+  * \return 0 on success, a negative number on failure
+  */
+  static int init(const char* apn=NULL, int debug=0); 
+
+  /** Open an LTE internet data connection
+      @return 0 on success, error code on failure
+  */
+  int connect(void);
+
+  /** Disconnect
+  * Bring the interface down
+  * \return 0 on success, a negative number on failure
+  */
+  static int disconnect();
+  
+  /** Because the WNCInterface is cellular based there is no MAC Ethernet address to return, so this function
+   *  returns a bogus MAC address created from the ICCD on the SIM that is being used.
+   * \return a pointer to a pesudo-MAC string containing "NN:NN:NN:NN:NN:NN"
+   */
+  static char* getMACAddress();
+  
+  /** Get the IP address of your Ethernet interface
+   * \return a pointer to a string containing the IP address
+   */
+  static char* getIPAddress();
+
+  /** Get the Gateway address of your Ethernet interface
+   * \return a pointer to a string containing the Gateway address
+   */
+  static char* getGateway();
+
+  /** Get the Network mask of your Ethernet interface
+   * \return a pointer to a string containing the Network mask
+   */
+  static char* getNetworkMask();
+  
+  /** Manipulate the debug output of the WncController, for debug purposes.
+   * \return nothing.
+   */
+  void doDebug(int val);  //doing this so I can get to the wnc controller pointer
+
+private:
+  static WncController_fk::WncIpStats myNetStats;     //maintaint the network statistics
+  static WncControllerK64F_fk::WncControllerK64F *_pwnc;  //pointer to the WncController instance
+  static string mac;
+};
+
+#endif /* _WNCINTERFACE_ */
+
+

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/WncControllerK64F.lib	Wed Sep 21 14:30:06 2016 +0000
@@ -0,0 +1,1 @@
+https://developer.mbed.org/users/fkellermavnet/code/WncControllerK64F/#0933aa0fe01e