Avnet
This library controls the WNC. There is a derived class for usage from the K64F board.
Fork of
WncControllerLibrary
by 
Fred Kellerman
Revision 33:2958e09ad308, committed 2016-11-17
- Comitter:
- fkellermavnet
- Date:
- Thu Nov 17 15:30:42 2016 +0000
- Parent:
- 32:6512f41ac6f0
- Child:
- 34:68283b201052
- Commit message:
- Added docs, changed ::write() to use uint8_t instead of char.
Changed in this revision
| WncController.cpp | Show annotated file Show diff for this revision Revisions of this file |
| WncController.h | Show annotated file Show diff for this revision Revisions of this file |
--- a/WncController.cpp Mon Oct 10 17:02:24 2016 +0000
+++ b/WncController.cpp Thu Nov 17 15:30:42 2016 +0000
@@ -24,6 +24,54 @@
@version 1.0
@date July 2016
@author Fred Kellerman
+
+
+ An Example of usage:
+
+ WncControllerK64F mdm(&wncPinList, &mdmUart, &debugUart);
+
+ mdm.enableDebug(true, true);
+
+ if (false == mdm.powerWncOn("m2m.com.attz", 60)) {
+ while(1);
+ }
+
+ // ICCID and MSISDN
+ string iccid; string msisdn;
+ if (mdm.getICCID(&iccid) == true) {
+ if (mdm.convertICCIDtoMSISDN(iccid, &msisdn) == true) {
+ // Send an SMS message (must use 15-digit MISDN number!)
+ mdm.sendSMSText(msisdn.c_str(), "Hello from WNC Kit -> from WNC");
+ }
+ }
+
+ // Get an IP address setup for the socket #1 (0 indexed))
+ if (true == mdm.resolveUrl(0, "www.att.com"))
+ {
+ // Report server IP
+ if (true == mdm.getIpAddr(0, ipAddrStr)) {
+ debugUart.puts("Server IP: ");
+ debugUart.puts(ipAddrStr);
+ debugUart.puts("\r\n");
+ }
+
+ // Open Socket #1, TCP=true resolved IP on port 80:
+ if (true == mdm.openSocket(0, 80, true)) {
+ // Write some data
+ const uint8_t * dataStr = "GET /index.html HTTP/1.0\r\nFrom: someuser@someuser.com\r\nUser-Agent: HTTPTool/1.0\r\n\r\n";
+ if (true == mdm.write(0, dataStr, strlen((const char *)dataStr)))
+ {
+ const uint8_t * myBuf;
+ mdm.setReadRetries(0, 20);
+ uint32_t n = mdm.read(0, &myBuf);
+ if (n > 0)
+ debugUart.printf("Read %d chars: %s\r\n", n, myBuf);
+ else
+ debugUart.puts("No read data!\r\n");
+ }
+ }
+ }
+
*/
@@ -55,8 +103,7 @@
* C++ version 0.4 char* style "itoa":
* Written by Lukás Chmela
* Released under GPLv3.
-*/
-
+ */
static char* itoa(int64_t value, char* result, int base)
{
// check that the base is valid
@@ -103,18 +150,6 @@
return (str);
}
-/**
- * \brief Constructor for UART controlled WNC
- *
- * \param [in] wnc_uart - Reference to a SerialBuffered object which will
- * be used as the bus to control the WNC.
- *
- * \return None.
- *
- * \details Adding another way to talk to the WNC, like I2C or USB,
- * a constructor should be added for each type just like the SerialBuffered
- * constructor below.
- */
WncController::WncController(void)
{
for(unsigned i; i<MAX_NUM_WNC_SOCKETS; i++)
@@ -127,29 +162,11 @@
m_sMoreDebugEnabled = moreDebugOn;
}
-/**
- * \brief Used internally but also make public for a user of the Class to interrogate state as well.
- *
- * \param [in] None.
- *
- * \return The state of the WNC Modem.
- *
- * \details None.
- */
WncController::WncState_e WncController::getWncStatus(void)
{
return (m_sState);
}
-/**
- * \brief Return signal quality dBm level
- *
- * \param [in] None.
- *
- * \return The dBm signal level at the time of the request.
- *
- * \details This polls (at the time of the call) the cell signal.
- */
int16_t WncController::getDbmRssi(void)
{
int16_t rssi, ber;
@@ -168,18 +185,6 @@
return (99);
}
-
-/**
- * \brief Power up and down (down not implemented yet)
- *
- * \param [in] on - set true to power on, otherwise false
- *
- * \return None.
- *
- * \details Power-on works but not power-down. This will manipulate WNC Shield hardware
- * and bring it to life. It will also initialize the WNC enough to get it to be able to open sockets
- * (with AT commands)
- */
bool WncController::powerWncOn(const char * const apn, uint8_t powerUpTimeoutSecs)
{
dbgPuts("Waiting for WNC to Initialize...");
@@ -270,16 +275,6 @@
return (false);
}
-
-/**
- * \brief Look-up a URL text string and convert into an IP Address string.
- *
- * \param [in] url - the URL to lookup. numSock - the socket number to resolve.
- *
- * \return true - if the IP address has been resolved. false - if the URL could not be resolved.
- *
- * \details None.
- */
bool WncController::resolveUrl(uint16_t numSock, const char * url)
{
bool cmdRes;
@@ -300,16 +295,6 @@
return (false);
}
-/**
- * \brief Set IP Address string
- *
- * \param [in] numSock - socket reference to set the string for. ipStr - text string of the IP
- * address you want to talk to. There is no sanity check - beware!!!
- *
- * \return true - if the IP address has been set. false - if the IP could not be set.
- *
- * \details None.
- */
bool WncController::setIpAddr(uint16_t numSock, const char * ipStr)
{
if (numSock < MAX_NUM_WNC_SOCKETS) {
@@ -327,17 +312,6 @@
m_sCmdTimeoutMs = toMs;
}
-/**
- * \brief Opens a WNC socket.
- *
- * \param [in] sockNum - the number of the socket to open. ipAddr - a string containing
- * the IP address. port - the IP port number to open the socket connection.
- *
- * \return true - if the socket is/was opened. false otherwise.
- *
- * \details None.
- */
-
bool WncController::openSocketUrl(uint16_t numSock, const char * url, uint16_t port, bool tcp, uint16_t timeOutSec)
{
if (resolveUrl(numSock, url) == true)
@@ -402,19 +376,7 @@
return (m_sSock[numSock].open);
}
-/**
- * \brief Write bytes of data to an open socket
- *
- * \param [in] sockNum - the number of the socket to write. s - a string containing
- * the byte data to send must be less than = 1500.
- *
- * \return true - if the write was successful. false otherwise.
- *
- * \details The results of the write do not have anything to do with the data
- * arriving at the endpoint.
- */
-
-bool WncController::sockWrite(const char * const s, uint16_t n, uint16_t numSock, bool isTcp)
+bool WncController::sockWrite(const uint8_t * const s, uint16_t n, uint16_t numSock, bool isTcp)
{
bool result = true;
@@ -433,7 +395,7 @@
return (result);
}
-bool WncController::write(uint16_t numSock, const char * s, uint32_t n)
+bool WncController::write(uint16_t numSock, const uint8_t * s, uint32_t n)
{
bool result;
@@ -472,18 +434,6 @@
return (result);
}
-/**
- * \brief Poll and read back data from the WNC (if it has any)
- * If auto poll is enabled this read might fail (return with no data).
- *
- * \param [in] sockNum - the number of the socket to read. result - a string pointer containing
- * the byte data readback from the WNC.
- *
- * \return The number of bytes/chars that are read from the socket.
- *
- * \details DO NOT use the same string as is passed to the auto poll setup method!
- */
-
size_t WncController::read(uint16_t numSock, const uint8_t ** readBuf)
{
static string theBuf;
@@ -613,16 +563,6 @@
return (numCopied);
}
-/**
- * \brief Set how many times the above read method will retry if data is not returned.
- *
- * \param [in] sockNum - the number of the socket to set. retries - how many times to
- * poll until data is found.
- *
- * \return None.
- *
- * \details None.
- */
void WncController::setReadRetries(uint16_t numSock, uint16_t retries)
{
if (numSock < MAX_NUM_WNC_SOCKETS)
@@ -631,16 +571,6 @@
dbgPuts("Bad socket num!");
}
-/**
- * \brief Set how long between retries to wait.
- *
- * \param [in] sockNum - the number of the socket to set. readRetryWaitMs - how long to wait
- * before doing the read poll (calling read(...)).
- *
- * \return None.
- *
- * \details None.
- */
void WncController::setReadRetryWait(uint16_t numSock, uint16_t readRetryWaitMs)
{
if (numSock < MAX_NUM_WNC_SOCKETS)
@@ -649,15 +579,6 @@
dbgPuts("Bad socket num!");
}
-/**
- * \brief Close the socket.
- *
- * \param [in] sockNum - the number of the socket to close.
- *
- * \return None.
- *
- * \details None.
- */
bool WncController::closeSocket(uint16_t numSock)
{
if (numSock < MAX_NUM_WNC_SOCKETS) {
@@ -676,8 +597,6 @@
return (m_sSock[numSock].open == false);
}
-// Note: If you want to make it more portable, create a
-// arecharsavailable() and readchar()
size_t WncController::mdmGetline(string * buff, int timeout_ms)
{
char chin = '\0';
@@ -707,7 +626,6 @@
return (len);
}
-// Eventually this should try to reinstate the sockets open
bool WncController::softwareInitMdm(void)
{
static bool reportStatus = true;
@@ -744,8 +662,6 @@
}
}
-
-// Sets a global with failure or success, assumes 1 thread all the time
WncController::AtCmdErr_e WncController::sendWncCmd(const char * const s, string ** r, int ms_timeout)
{
if (checkCellLink() == false) {
@@ -883,7 +799,6 @@
} while (m_sSock[numSock].open == false);
}
-
bool WncController::getICCID(string * iccid)
{
if (at_geticcid_wnc(iccid) == false) {
@@ -919,7 +834,6 @@
return (true);
}
-
bool WncController::convertICCIDtoMSISDN(const string & iccid, string * msisdn)
{
msisdn->erase();
@@ -939,7 +853,6 @@
return (true);
}
-
bool WncController::sendSMSText(const char * const phoneNum, const char * const text)
{
if (at_sendSMStext_wnc(phoneNum, text) == true)
@@ -1628,7 +1541,6 @@
return (true);
}
-
int16_t WncController::at_sockopen_wnc(const char * const ip, uint16_t port, uint16_t numSock, bool tcp, uint16_t timeOutSec)
{
string * pRespStr;
@@ -1748,7 +1660,7 @@
return (false);
}
-WncController::AtCmdErr_e WncController::at_sockwrite_wnc(const char * s, uint16_t n, uint16_t numSock, bool isTcp)
+WncController::AtCmdErr_e WncController::at_sockwrite_wnc(const uint8_t * s, uint16_t n, uint16_t numSock, bool isTcp)
{
AtCmdErr_e result;
@@ -1768,7 +1680,7 @@
cmd_str += ",\"";
while(n > 0) {
n--;
- num2str = _to_hex_string((uint8_t)*s++);
+ num2str = _to_hex_string(*s++);
// Always 2-digit ascii hex:
if (num2str[1] == '\0')
cmd_str += '0';
@@ -2197,7 +2109,6 @@
puts("\r\n");
}
-// WNC used to have troubles handling full speed, seems to not need this now.
void WncController::sendCmd(const char * cmd, unsigned n, unsigned wait_uS, bool crLf)
{
while (n--) {
@@ -2212,5 +2123,4 @@
}
}
-
}; // End namespace WncController_fk
--- a/WncController.h Mon Oct 10 17:02:24 2016 +0000
+++ b/WncController.h Thu Nov 17 15:30:42 2016 +0000
@@ -1,4 +1,4 @@
-/*
+/**
Copyright (c) 2016 Fred Kellerman
Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -38,24 +38,16 @@
#include <stdint.h>
namespace WncController_fk {
-
+
using namespace std;
-/**
- * \file WncController.h
- * \brief This mbed C++ class is for controlling the WNC
- * Cellular modem via the AT command interface. This was
- * developed with respect to version 1.3 of the WNC authored
- * spec. This class is only designed to have 1 instantiation
- * it is also not multi-thread safe.
- */
-
+/** @defgroup API The WncControllerLibrary API */
+/** @defgroup MISC Misc WncControllerLibrary functions */
+/** @defgroup INTERNALS WncControllerLibrary Internals */
static const uint8_t MAX_LEN_IP_STR = 16; // Length includes room for the extra NULL
-/**
- * \brief Contains info fields for the WNC Internet Attributes
- */
+/** \brief Contains info fields for the WNC Internet Attributes */
struct WncIpStats
{
string wncMAC;
@@ -66,14 +58,30 @@
char dnsSecondary[MAX_LEN_IP_STR];
};
+
+/**
+ * @author Fred Kellerman
+ * @see API
+ *
+ * <b>WncController</b> This mbed C++ class is for controlling the WNC
+ * Cellular modem via the serial AT command interface. This was
+ * developed with respect to version 1.3 of the WNC authored
+ * unpublished spec. This class is only designed to have 1 instantiation,
+ * it is also not multi-thread safe. There are no OS specific
+ * entities being used, there are pure virtual methods that an
+ * inheriting class must fulfill. That inheriting class will have
+ * OS and platform specific entities. See WncControllerK64F for an
+ * example for the NXP K64F Freedom board.
+ */
class WncController
{
public:
+
static const unsigned MAX_NUM_WNC_SOCKETS = 5; // Max number of simultaneous sockets that the WNC supports
static const unsigned MAX_POWERUP_TIMEOUT = 60; // How long the powerUp method will try to turn on the WNC Shield
// (this is the default if the user does not over-ride on power-up
- // Tracks mode of the WNC Shield hardware
+ /** Tracks mode of the WNC Shield hardware */
enum WncState_e {
WNC_OFF = 0,
WNC_ON, // This is intended to mean all systems go, including cell link up but socket may not be open
@@ -82,180 +90,229 @@
};
/**
- * \brief Constructor for UART controlled WNC
*
- * \param [in] wnc_uart - Reference to a SerialBuffered object which will
- * be used as the bus to control the WNC. apnStr = a text string for
- * the cellular APN name.
- *
- * \return None.
- *
- * \details Adding another way to talk to the WNC, like I2C or USB,
- * a constructor should be added for each type just like the SerialBuffered
- * constructor below. Assumes UART is enabled, setup and ready to go. This
- * class will read and write to this UART.
+ * Constructor for WncController class, sets up internals.
+ * @ingroup API
+ * @return none.
*/
WncController(void);
- // WncController( const char * const apnStr, MODSERIAL * wnc_uart, MODSERIAL * debug_uart = NULL);
-
/**
- * \brief Used internally but also make public for a user of the Class to interrogate state as well.
*
- * \param [in] None.
- *
- * \return The state of the WNC Modem.
- *
- * \details None.
+ * Used internally but also make public for a user of the Class to
+ * interrogate state as well.
+ * @ingroup API
+ * @return the current state of the Wnc hardware.
*/
WncState_e getWncStatus(void);
+ /**
+ *
+ * Allows a user to set the WNC modem to use the given Cellular APN
+ * @ingroup API
+ * @param apnStr - a null terminated c-string
+ * @return true if the APN set was succesful, else false
+ */
bool setApnName(const char * const apnStr);
/**
- * \brief Return signal quality dBm level
*
- * \param [in] None.
- *
- * \return The dBm signal level at the time of the request.
- *
- * \details This polls (at the time of the call) the cell signal.
+ * Queries the WNC modem for the current RX RSSI in units of coded dBm
+ * @ingroup API
+ * @return 0 – -113 dBm or less
+ * 1 – -111 dBm
+ * 2...30 – -109 dBm to –53 dBm
+ * 31 – -51 dBm or greater
+ * 99 – not known or not detectable
*/
int16_t getDbmRssi(void);
+
+ /**
+ *
+ * Queries the WNC modem for the current Bit Error Rate
+ * @ingroup API
+ * @return 0...7 – as RXQUAL values in the table in 3GPP TS 45.008
+ * subclause 8.2.4
+ * 99 – not known or not detectable
+ */
int16_t get3gBer(void);
/**
- * \brief Power up and down (down not implemented yet)
*
- * \param [in] NXP Pins that are critical for the initialization of the WNC Shield.
- *
- * \return true if request successful else false.
- *
- * \details Power-on works but not power-down. This will manipulate WNC Shield hardware
- * and bring it to life. It will also initialize the WNC enough to get it to be able to open sockets
- * (with AT commands)
+ * Powers up the WNC modem
+ * @ingroup API
+ * @param apn - the apn c-string to set the WNC modem to use
+ * @param powerUpTimeoutSecs - the amount of time to wait for the WNC modem to turn on
+ * @return true if powerup was a success, else false.
*/
bool powerWncOn(const char * const apn, uint8_t powerUpTimeoutSecs = MAX_POWERUP_TIMEOUT);
/**
- * \brief Query the WNC modem for its Internet attributes
*
- * \param [in] Pointer to a struct where to put the info.
- *
- * \return true if request successful else false.
- *
- * \details This method will do a few sanity checks and then gather the
- * fields of the struct.
+ * Returns the NAT Self, gateway, masks and dns IP
+ * @ingroup API
+ * @param s - a pointer to a struct that will contain the IP info.
+ * @return true if success, else false.
*/
bool getWncNetworkingStats(WncIpStats * s);
/**
- * \brief Look-up a URL text string and convert into an IP Address string.
*
- * \param [in] url - the URL to lookup. numSock - the socket reference.
- *
- * \return true - if the IP address has been resolved. false - if the URL could not be resolved.
- *
- * \details None.
+ * Takes a text URL and converts it internally to an IP address for the
+ * socket number given.
+ * @ingroup API
+ * @param numSock - The number of the socket to lookup the IP address for.
+ * @param url - a c-string text URL
+ * @return true if success, else false.
*/
bool resolveUrl(uint16_t numSock, const char * url);
/**
- * \brief Set IP Address string
*
- * \param [in] numSock - socket reference to set the string for. ipStr - text string of the IP
- * address you want to talk to. There is no sanity check - beware!!!
- *
- * \return true - if the IP address has been set. false - if the IP could not be set.
- *
- * \details None.
+ * If you know the IP address you can set the socket up to use it rather
+ * than using a text URL.
+ * @ingroup API
+ * @param numSock - The number of the socket to use the IP address for.
+ * @param ipStr - a c-string text IP addrese like: 192.168.0.1
+ * @return true if success, else false.
*/
bool setIpAddr(uint16_t numSock, const char * ipStr);
/**
- * \brief Opens a WNC socket.
*
- * \param [in] sockNum - the number of the socket to open. ipAddr - a string containing
- * the IP address. port - the IP port number to open the socket connection.
- *
- * \return true - if the socket is/was opened. false otherwise.
- *
- * \details None.
+ * Opens a socket for the given number, port and IP protocol. Before
+ * using open, you must use either resolveUrl() or setIpAddr().
+ * @ingroup API
+ * @param numSock - The number of the socket to open.
+ * @param port - the IP port to open
+ * @param tcp - set true for TCP, false for UDP
+ * @param timeoutSec - the amount of time in seconds to wait for the open to complete
+ * @return true if success, else false.
*/
bool openSocket(uint16_t numSock, uint16_t port, bool tcp, uint16_t timeOutSec = 30);
-
+
+ /**
+ *
+ * Opens a socket for the given text URL, number, port and IP protocol.
+ * @ingroup API
+ * @param numSock - The number of the socket to open.
+ * @param url - a c-string text URL, the one to open a socket for.
+ * @param port - the IP port to open.
+ * @param tcp - set true for TCP, false for UDP.
+ * @param timeoutSec - the amount of time in seconds to wait for the open to complete.
+ * @return true if success, else false.
+ */
bool openSocketUrl(uint16_t numSock, const char * url, uint16_t port, bool tcp, uint16_t timeOutSec = 30);
+ /**
+ *
+ * Opens a socket for the given text IP address, number, port and IP protocol.
+ * @ingroup API
+ * @param numSock - The number of the socket to open.
+ * @param ipAddr - a c-string text IP address like: "192.168.0.1".
+ * @param port - the IP port to open.
+ * @param tcp - set true for TCP, false for UDP.
+ * @param timeoutSec - the amount of time in seconds to wait for the open to complete.
+ * @return true if success, else false.
+ */
bool openSocketIpAddr(uint16_t numSock, const char * ipAddr, uint16_t port, bool tcp, uint16_t timeOutSec = 30);
/**
- * \brief Write bytes of data to an open socket
*
- * \param [in] sockNum - the number of the socket to write. s - a string containing
- * the byte data to send.
- *
- * \return true - if the write was successful. false otherwise.
- *
- * \details The results of the write do not have anything to do with the data
- * arriving at the endpoint.
+ * Write data bytes to a Socket, the Socket must already be open.
+ * @ingroup API
+ * @param numSock - The number of the socket to open.
+ * @parma s - an array of bytes to write to the socket.
+ * @param n - the number of bytes to write.
+ * @return true if success, else false.
*/
- bool write(uint16_t numSock, const char * s, uint32_t n);
+ bool write(uint16_t numSock, const uint8_t * s, uint32_t n);
/**
- * \brief Poll and read back data from the WNC (if it has any)
- * If auto poll is enabled this read might fail (return with no data).
*
- * \param [in] sockNum - the number of the socket to read. result - a string pointer containing
- * the byte data readback from the WNC.
- *
- * \return The number of bytes/chars that are read from the socket.
- *
- * \details DO NOT use the same string as is passed to the auto poll setup method!
+ * Poll to read available data bytes from an already open Socket. This method
+ * will retry reads to what setReadRetries() sets it to and the delay in between
+ * retries that is set with setReadRetryWait()
+ * @ingroup API
+ * @param numSock - The number of the socket to open.
+ * @parma readBuf - a pointer to where read will put the data.
+ * @param maxReadBufLen - The number of bytes readBuf has room for.
+ * @return the number of bytes actually read into readBuf. 0 is a valid value if no data is available.
*/
size_t read(uint16_t numSock, uint8_t * readBuf, uint32_t maxReadBufLen);
+ /**
+ *
+ * Poll to read available data bytes from an already open Socket. This method
+ * will retry reads to what setReadRetries() sets it to and the delay in between
+ * retries that is set with setReadRetryWait()
+ * @ingroup API
+ * @param numSock - The number of the socket to open.
+ * @parma readBuf - a pointer to pointer that will be set to point to an internal byte buffer that contains any read data.
+ * @return the number of bytes actually read into the pointer that readBuf points to. 0 is a valid value if no data is available.
+ */
size_t read(uint16_t numSock, const uint8_t ** readBuf);
/**
- * \brief Set how many times the above read method will retry if data is not returned.
*
- * \param [in] sockNum - the number of the socket to set. retries - how many times to
- * poll until data is found.
- *
- * \return None.
- *
- * \details None.
+ * Set the number of retries that the read methods will use. If a read returns 0 data this setting will have the read
+ * re-read to see if new data is available.
+ * @ingroup API
+ * @param numSock - The number of the socket to open.
+ * @parma retries - the number of retries to perform.
+ * @return none.
*/
void setReadRetries(uint16_t numSock, uint16_t retries);
/**
- * \brief Set how long between retries to wait.
*
- * \param [in] sockNum - the number of the socket to set. waitMs - how long to wait
- * before doing the read poll (calling read(...)).
- *
- * \return None.
- *
- * \details None.
+ * Set the time between retires that the read methods will use. If a read returns 0 data this setting will have the read
+ * re-read and use this amount of delay in between the re-reads.
+ * @ingroup API
+ * @param numSock - The number of the socket to open.
+ * @parma waitMs - the amount of time in mS to wait between retries.
+ * @return none.
*/
void setReadRetryWait(uint16_t numSock, uint16_t waitMs);
/**
- * \brief Close the socket.
*
- * \param [in] sockNum - the number of the socket to close.
- *
- * \return None.
- *
- * \details None.
+ * Closes an already open Socket.
+ * @ingroup API
+ * @param numSock - The number of the socket to open.
+ * @return true if success else false.
*/
bool closeSocket(uint16_t numSock);
+ /**
+ *
+ * Sets the amount of time to wait between the raw AT commands that are sent to the WNC modem.
+ * Generally you don't want to use this but it is here just in case.
+ * @ingroup API
+ * @param toMs - num mS to wait between the AT cmds.
+ * @return none.
+ */
void setWncCmdTimeout(uint16_t toMs);
-
+
+ /**
+ *
+ * Gets the IP address of the given socket number.
+ * @ingroup API
+ * @param numSock - The number of the socket to open.
+ * @param myIpAddr - a c-string that contains the socket's IP address.
+ * @return true if success else false.
+ */
bool getIpAddr(uint16_t numSock, char myIpAddr[MAX_LEN_IP_STR]);
+ /**
+ *
+ * Enables debug output from this class.
+ * @ingroup API
+ * @param on - true enables debug output, false disables
+ * @param moreDebugOn - true enables verbose debug, false truncates debug output.
+ * @return none.
+ */
void enableDebug(bool on, bool moreDebugOn);
///////////////////////////////////////////
@@ -265,6 +322,7 @@
static const uint16_t MAX_WNC_SMS_MSG_SLOTS = 3; // How many SMS messages the WNC can store and receive at a time.
static const uint16_t MAX_WNC_SMS_LENGTH = 160; // The maximum length of a 7-bit SMS message the WNC can send and receive.
+ /** Struct for SMS messages */
struct WncSmsInfo
{
// Content
@@ -282,34 +340,110 @@
bool msgReceipt;
};
+ /** Struct to contain a list of SMS message structs */
struct WncSmsList
{
uint8_t msgCount;
WncSmsInfo e[MAX_WNC_SMS_MSG_SLOTS];
};
+ /**
+ *
+ * Sends an SMS text message to someone.
+ * @ingroup API
+ * @param phoneNum - c-string 15 digit MSISDN number or ATT Jasper number (standard phone number not supported because ATT IoT SMS does not support it).
+ * @param text - the c-string text to send to someone.
+ * @return true if success else false.
+ */
bool sendSMSText(const char * const phoneNum, const char * const text);
+ /**
+ *
+ * Incoming messages are stored in a log in the WNC modem, this will read that
+ * log.
+ * @ingroup API
+ * @param log - the log contents if reading it was successful.
+ * @return true if success else false.
+ */
bool readSMSLog(struct WncSmsList * log);
+ /**
+ *
+ * Incoming messages are stored in a log in the WNC modem, this will read out
+ * messages that are unread and also then mark them read.
+ * @ingroup API
+ * @param w - a list of SMS messages that unread messages will be put into.
+ * @param deleteRead - if a message is read and this is set true the message will be deleted from the WNC modem log.
+ * If it is false the message will remain in the internal log but be marked as read.
+ * @return true if success else false.
+ */
bool readUnreadSMSText(struct WncSmsList * w, bool deleteRead = true);
+ /**
+ *
+ * Saves a text message into internal SIM card memory of the WNC modem.
+ * There are only 3 slots available this is for unread, read and saved.
+ * @ingroup API
+ * @param phoneNum - c-string 15 digit MSISDN number or ATT Jasper number (standard phone number not supported because ATT IoT SMS does not support it).
+ * @param text - the c-string text to send to someone.
+ * @param msgIdx - the slot position to save the message: '1', '2', '3'
+ * @return true if success else false.
+ */
bool saveSMSText(const char * const phoneNum, const char * const text, char * msgIdx);
-
+
+ /**
+ *
+ * Sends a prior stored a text message from internal SIM card memory of the WNC modem.
+ * If no messages are stored the behaviour of this method is undefined.
+ * @ingroup API
+ * @param msgIdx - the slot position to save the message: '1', '2', '3'
+ * @return true if success else false.
+ */
bool sendSMSTextFromMem(char msgIdx);
+ /**
+ *
+ * Deletes a prior stored a text message from internal SIM card memory of the WNC modem.
+ * If no messages are stored the behaviour of this method is undefined.
+ * @ingroup API
+ * @param msgIdx - the slot position to save the message: '1', '2', '3' or '*' deletes them all.
+ * @return true if success else false.
+ */
bool deleteSMSTextFromMem(char msgIdx);
+ /**
+ *
+ * Retreives the SIM card ICCID number.
+ * @ingroup API
+ * @param iccid - a pointer to C++ string that contains the retrieved number.
+ * @return true if success else false.
+ */
bool getICCID(string * iccid);
+ /**
+ *
+ * Converts an ICCID number into a MSISDN number. The ATT SMS system for IoT only allows use of the 15-digit MSISDN number.
+ * @ingroup API
+ * @param iccid - the number to convert.
+ * @param msisdn - points to a C++ string that has the converted number.
+ * @return true if success else false.
+ */
bool convertICCIDtoMSISDN(const string & iccid, string * msisdn);
///////////////////////////////////////////
// Neighborhood Cell Info
///////////////////////////////////////////
+
+ /**
+ *
+ * Fetches the signal quality log from the WNC modem.
+ * @ingroup API
+ * @param log - a pointer to an internal buffer who's contents contain the signal quality metrics.
+ * @return The number of chars in the log.
+ */
size_t getSignalQuality(const char ** log);
- // Date Time
+ /** A struct for the WNC modem Date and Time */
struct WncDateTime
{
uint8_t year;
@@ -320,13 +454,44 @@
uint8_t sec;
};
+ /**
+ *
+ * Fetches the cell tower's time and date. The time is accurate when read
+ * but significant delays exist between the time it is read and returned.
+ * @ingroup API
+ * @param tod - User supplies a pointer to a tod struct and this method fills it in.
+ * @return true if success else false.
+ */
bool getTimeDate(struct WncDateTime * tod);
- // Ping
+ /**
+ *
+ * ICMP Pings a URL, the results are only output to the debug log for now!
+ * @ingroup API
+ * @param url - a c-string whose URL is to be pinged.
+ * @return true if success else false.
+ */
bool pingUrl(const char * url);
+
+ /**
+ *
+ * ICMP Pings an IP, the results are only output to the debug log for now!
+ * @ingroup API
+ * @param ip - a c-string whose IP is to be pinged.
+ * @return true if success else false.
+ */
bool pingIp(const char * ip);
- // User command:
+ /**
+ *
+ * Allows a user to send a raw AT command to the WNC modem.
+ * @ingroup API
+ * @param cmd - the c-string cmd to send like: "AT"
+ * @param resp - a pointer to the c-string cmd's response.
+ * @param sizeRespBuf - how large the command response buffer is, sets the max response length.
+ * @param ms_timeout - how long to wait for the WNC to respond to your command.
+ * @return the number of characters in the response from the WNC modem.
+ */
size_t sendCustomCmd(const char * cmd, char * resp, size_t sizeRespBuf, int ms_timeout);
protected:
@@ -349,7 +514,11 @@
WNC_AT_CMD_WNC_NOT_ON
};
- // Users must define these functionalities:
+ bool waitForPowerOnModemToRespond(uint8_t powerUpTimeoutSecs);
+ AtCmdErr_e sendWncCmd(const char * const s, string ** r, int ms_timeout);
+
+ // Users must define these functionalities in the inheriting class:
+ // General I/O and timing:
virtual int putc(char c) = 0;
virtual int puts(const char * s) = 0;
virtual char getc(void) = 0;
@@ -360,7 +529,7 @@
virtual void waitUs(int t) = 0;
virtual bool initWncModem(uint8_t powerUpTimeoutSecs) = 0;
- // Isolate OS timers
+ // Isolate OS timers
virtual int getLogTimerTicks(void) = 0;
virtual void startTimerA(void) = 0;
virtual void stopTimerA(void) = 0;
@@ -368,9 +537,6 @@
virtual void startTimerB(void) = 0;
virtual void stopTimerB(void) = 0;
virtual int getTimerTicksB_mS(void) = 0;
-
- bool waitForPowerOnModemToRespond(uint8_t powerUpTimeoutSecs);
- AtCmdErr_e sendWncCmd(const char * const s, string ** r, int ms_timeout);
private:
@@ -383,7 +549,7 @@
int16_t at_sockopen_wnc(const char * const ip, uint16_t port, uint16_t numSock, bool tcp, uint16_t timeOutSec);
bool at_sockclose_wnc(uint16_t numSock);
bool at_dnsresolve_wnc(const char * s, string * ipStr);
- AtCmdErr_e at_sockwrite_wnc(const char * s, uint16_t n, uint16_t numSock, bool isTcp);
+ AtCmdErr_e at_sockwrite_wnc(const uint8_t * s, uint16_t n, uint16_t numSock, bool isTcp);
AtCmdErr_e at_sockread_wnc(uint8_t * pS, uint16_t * numRead, uint16_t n, uint16_t numSock, bool isTcp);
AtCmdErr_e at_sockread_wnc(string * pS, uint16_t numSock, bool isTcp);
bool at_reinitialize_mdm(void);
@@ -396,7 +562,7 @@
size_t at_readSMStext_wnc(const char n, const char ** log);
bool at_getrssiber_wnc(int16_t * dBm, int16_t * ber3g);
void closeOpenSocket(uint16_t numSock);
- bool sockWrite(const char * const s, uint16_t n, uint16_t numSock, bool isTcp);
+ bool sockWrite(const uint8_t * const s, uint16_t n, uint16_t numSock, bool isTcp);
bool at_sendSMStextMem_wnc(char n);
bool at_deleteSMSTextFromMem_wnc(char n);
bool at_saveSMStext_wnc(const char * const phoneNum, const char * const text, char * msgIdx);