This class adds HTTP, FTP and CellLocate client support for u-blox modules for the C027 and C030 boards (excepting the C030 N2xx flavour) from mbed 5.5 onwards. The HTTP, FTP and CellLocate operations are all hosted on the module, minimizing RAM consumption in the mbed MCU. It also sub-classes ublox-cellular-driver-gen to bring in SMS, USSD and modem file system support if you need to use these functions at the same time as the cellular interface.

Dependencies:   ublox-at-cellular-interface

Dependents:   example-ublox-at-cellular-interface-ext HelloMQTT ublox_new_driver_test example-ublox-at-cellular-interface-ext ... more

Embed: (wiki syntax)

« Back to documentation index

UbloxATCellularInterfaceExt Class Reference

UbloxATCellularInterfaceExt class. More...

#include <UbloxATCellularInterfaceExt.h>

Data Structures

struct  CellLocData
 Cell Locate data. More...
struct  Error
 A struct containing an HTTP or FTP error class and code. More...
struct  HttpProfCtrl
 Management structure for HTTP profiles. More...

Public Types

enum  HttpOpCode
 

HTTP configuration parameters (reference to HTTP control +UHTTP).

More...
enum  HttpCmd
 

Type of HTTP Command.

More...
enum  HttpContentType
 

HTTP content types.

More...
enum  FtpOpCode
 

FTP configuration parameters (reference to FTP control +UFTP).

More...
enum  FtpCmd
 

Type of FTP Command.

More...
enum  CellSensType
 

Which form of Cell Locate sensing to use.

More...
enum  CellRespType
 

Types of Cell Locate response.

More...

Public Member Functions

 UbloxATCellularInterfaceExt (PinName tx=MDMTXD, PinName rx=MDMRXD, int baud=MBED_CONF_UBLOX_CELL_BAUD_RATE, bool debugOn=false, osPriority priority=osPriorityNormal)
 Constructor.
int httpAllocProfile ()
 Find a free HTTP profile.
bool httpFreeProfile (int profile)
 Free the HTTP profile.
bool httpSetTimeout (int profile, int timeout)
 Set the timeout for this profile.
bool httpResetProfile (int httpProfile)
 Reset a HTTP profile back to defaults.
bool httpSetPar (int httpProfile, HttpOpCode httpOpCode, const char *httpInPar)
 Set HTTP parameters.
ErrorhttpCommand (int httpProfile, HttpCmd httpCmd, const char *httpPath, const char *rspFile, const char *sendStr, int httpContentType, const char *httpCustomPar, char *buf, int len, int *read_size=NULL)
 Perform a HTTP command.
bool ftpSetTimeout (int timeout)
 Set the timeout for FTP operations.
void ftpResetPar ()
 Reset the FTP configuration back to defaults.
bool ftpSetPar (FtpOpCode ftpOpCode, const char *ftpInPar)
 Set FTP parameters.
ErrorftpCommand (FtpCmd ftpCmd, const char *file1=NULL, const char *file2=NULL, char *buf=NULL, int len=0, int offset=0)
 Perform an FTP command.
bool cellLocSrvTcp (const char *token, const char *server_1="cell-live1.services.u-blox.com", const char *server_2="cell-live2.services.u-blox.com", int days=14, int period=4, int resolution=1)
 Configure the Cell Locate TCP aiding server.
bool cellLocSrvUdp (const char *server_1="cell-live1.services.u-blox.com", int port=46434, int latency=1000, int mode=0)
 Configure Cell Locate UDP aiding server.
bool cellLocConfig (int scanMode)
 Configure Cell Locate location sensor.
bool cellLocRequest (CellSensType sensor, int timeout, int accuracy, CellRespType type=CELL_DETAILED, int hypothesis=1)
 Request a one-shot Cell Locate.
bool cellLocGetData (CellLocData *data, int index=0)
 Get a position record.
int cellLocGetRes ()
 Get the number of position records received.
int cellLocGetExpRes ()
 Get the number of position records expected to be received.

Protected Member Functions

void UUHTTPCR_URC ()
 Callback to capture the response to an HTTP command.
int findProfile (int modemHandle=HTTP_PROF_UNUSED)
 Find a profile with a given handle.
const char * getHttpCmd (HttpCmd httpCmd)
 Helper function to get a HTTP command as a text string, useful for debug purposes.
void UUFTPCR_URC ()
 Callback to capture the result of an FTP command.
void UUFTPCD_URC ()
 Callback to capture data returned from an FTP command.
const char * getFtpCmd (FtpCmd ftpCmd)
 Helper function to get an FTP command as a text string, useful for debug purposes.
void UULOCIND_URC ()
 Callback to capture +UULOCIND.
void UULOC_URC ()
 Callback to capture +UULOC.

Protected Attributes

HttpProfCtrl _httpProfiles [4]
 The HTTP profile storage.
int _ftpTimeout
 The FTP timeout in milliseconds.
volatile int _lastFtpOpCodeResult
 A place to store the FTP op code for the last result.
volatile int _lastFtpResult
 A place to store the last FTP result.
volatile int _lastFtpOpCodeData
 A place to store the last FTP op code for data response.
char * _ftpBuf
 A place to store data returns from an FTP operation.
int _ftpBufLen
 The length of FTP data that can be stored (at _ftpBuf).
Error _ftpError
 storage for the last FTP error
volatile int _locRcvPos
 Received positions.
volatile int _locExpPos
 Expected positions.
CellLocData _loc [CELL_MAX_HYP]
 The Cell Locate data.
char urcBuf [128]
 Buffer for the URC to work with.

Detailed Description

UbloxATCellularInterfaceExt class.

This interface extends the UbloxATCellularInterface to include other features that use the IP stack on board the cellular modem: HTTP, FTP and Cell Locate.

Note: the UbloxCellularGeneric class is required because reading a large HTTP response is performed via a modem file system call and the UbloxCellularGeneric class is where modem file system support is provided.

Definition at line 33 of file UbloxATCellularInterfaceExt.h.


Member Enumeration Documentation

Types of Cell Locate response.

Definition at line 367 of file UbloxATCellularInterfaceExt.h.

Which form of Cell Locate sensing to use.

Definition at line 358 of file UbloxATCellularInterfaceExt.h.

enum FtpCmd

Type of FTP Command.

Definition at line 239 of file UbloxATCellularInterfaceExt.h.

enum FtpOpCode

FTP configuration parameters (reference to FTP control +UFTP).

Definition at line 224 of file UbloxATCellularInterfaceExt.h.

enum HttpCmd

Type of HTTP Command.

Definition at line 91 of file UbloxATCellularInterfaceExt.h.

HTTP content types.

Definition at line 102 of file UbloxATCellularInterfaceExt.h.

enum HttpOpCode

HTTP configuration parameters (reference to HTTP control +UHTTP).

Definition at line 78 of file UbloxATCellularInterfaceExt.h.


Constructor & Destructor Documentation

UbloxATCellularInterfaceExt ( PinName  tx = MDMTXD,
PinName  rx = MDMRXD,
int  baud = MBED_CONF_UBLOX_CELL_BAUD_RATE,
bool  debugOn = false,
osPriority  priority = osPriorityNormal 
)

Constructor.

Parameters:
txthe UART TX data pin to which the modem is attached.
rxthe UART RX data pin to which the modem is attached.
baudthe UART baud rate.
debugOntrue to switch AT interface debug on, otherwise false.

Definition at line 439 of file UbloxATCellularInterfaceExt.cpp.


Member Function Documentation

bool cellLocConfig ( int  scanMode )

Configure Cell Locate location sensor.

Parameters:
scanModenetwork scan mode: 0 normal, 1 deep scan.
Returns:
true if the request is successful, otherwise false.

Definition at line 985 of file UbloxATCellularInterfaceExt.cpp.

bool cellLocGetData ( CellLocData data,
int  index = 0 
)

Get a position record.

Parameters:
datapointer to a CellLocData structure where the location will be put.
indexof the position to retrieve.
Returns:
true if data has been retrieved and copied, false otherwise.

Definition at line 1035 of file UbloxATCellularInterfaceExt.cpp.

int cellLocGetExpRes (  )

Get the number of position records expected to be received.

Returns:
number of position records expected to be received.

Definition at line 1066 of file UbloxATCellularInterfaceExt.cpp.

int cellLocGetRes (  )

Get the number of position records received.

Returns:
number of position records received.

Definition at line 1050 of file UbloxATCellularInterfaceExt.cpp.

bool cellLocRequest ( CellSensType  sensor,
int  timeout,
int  accuracy,
CellRespType  type = CELL_DETAILED,
int  hypothesis = 1 
)

Request a one-shot Cell Locate.

This function is non-blocking, the result is retrieved using cellLocGetxxx.

Note: none of the CellLocate methods switch on the GNSS receiver chip. That should be done by instantiating the GnssSerial or GnssI2C classes and calling the init() method.

Note: during the location process, unsolicited result codes will be returned by the modem indicating progress and potentially flagging interesting errors. In order to see these errors, instantiate this class with debugOn set to true.

Parameters:
sensorsensor selection.
timeouttimeout period in seconds (1 - 999).
accuracytarget accuracy in meters (1 - 999999).
typedetailed or multi-hypothesis.
hypothesismaximum desired number of responses from CellLocate (up to 16), must be 1 if type is CELL_DETAILED.
Returns:
true if the request is successful, otherwise false.

Definition at line 998 of file UbloxATCellularInterfaceExt.cpp.

bool cellLocSrvTcp ( const char *  token,
const char *  server_1 = "cell-live1.services.u-blox.com",
const char *  server_2 = "cell-live2.services.u-blox.com",
int  days = 14,
int  period = 4,
int  resolution = 1 
)

Configure the Cell Locate TCP aiding server.

Connect() must have been called previously to establish a data connection.

Parameters:
server_1host name of the primary MGA server.
server_2host name of the secondary MGA server.
tokenauthentication token for MGA server access.
daysthe number of days into the future the off-line data for the u-blox 7.
periodthe number of weeks into the future the off-line data for u-blox M8.
resolutionresolution of off-line data for u-blox M8: 1 every day, 0 every other day.
Returns:
true if the request is successful, otherwise false.

Definition at line 947 of file UbloxATCellularInterfaceExt.cpp.

bool cellLocSrvUdp ( const char *  server_1 = "cell-live1.services.u-blox.com",
int  port = 46434,
int  latency = 1000,
int  mode = 0 
)

Configure Cell Locate UDP aiding server.

Connect() must have been called previously to establish a data connection.

Parameters:
server_1host name of the primary MGA server.
portserver port.
latencyexpected network latency in seconds from 0 to 10000 milliseconds.
modeAssist Now management, mode of operation: 0 data downloaded at GNSS power up, 1 automatically kept alive, manual download.
Returns:
true if the request is successful, otherwise false.

Definition at line 967 of file UbloxATCellularInterfaceExt.cpp.

int findProfile ( int  modemHandle = HTTP_PROF_UNUSED ) [protected]

Find a profile with a given handle.

If no handle is given, find the next free profile.

Parameters:
modemHandlethe handle of the profile to find.
Returns:
the profile handle or negative if not found/created.

Definition at line 51 of file UbloxATCellularInterfaceExt.cpp.

UbloxATCellularInterfaceExt::Error * ftpCommand ( FtpCmd  ftpCmd,
const char *  file1 = NULL,
const char *  file2 = NULL,
char *  buf = NULL,
int  len = 0,
int  offset = 0 
)

Perform an FTP command.

Connect() must have been called previously to establish a data connection.

See section 27.2 of u-blox-ATCommands_Manual(UBX-13002752).pdf for full details. By example, it works like this:

ftpCmd file1 file2 buf len offset FTP_LOGOUT N/A N/A N/A N/A N/A FTP_LOGIN N/A N/A N/A N/A N/A FTP_DELETE_FILE "the_file" N/A N/A N/A N/A FTP_RENAME_FILE "old_name" "new_name" N/A N/A N/A FTP_GET_FILE "the_file" Note 1 N/A N/A 0 - 1 (Notes 2 & 3) FTP_PUT_FILE "the_file" Note 1 N/A N/A 0 - 65535 (Notes 2 & 4 & 5) FTP_CD "dir1\dir2" N/A N/A N/A N/A FTP_MKDIR "newdir" N/A N/A N/A N/A FTP_RMDIR "dir" N/A N/A N/A N/A FTP_FILE_INFO "the_path" N/A Note 6 N/A FTP_LS "the_path" N/A Note 6 N/A FTP_FOTA_FILE "the_file" N/A Note 7 N/A

Note 1: for this case, file2 is the name that the file should be given when it arrives (in the modem file system for a GET, at the FTP server for a PUT); if set to NULL then file1 is used. Note 2: the file will placed into the modem file system for the GET case (and can be read with readFile()), or must already be in the modem file system, (can be written using writeFile()) for the PUT case. Note 3: if offset is 1 then, where supported, the FTP GET will be continued from the point it previously stopped. Note 4: if the file already exists in the modem file system some modems will return an error. It is up to the caller to ensure that the file does not exist before the FTP PUT operation. Note 5: where supported, offset is the position in the file to continue the FTP PUT from. Note 6: buf should point to the location where the file info or directory listing is to be stored and len should be the maximum length that can be stored. Note 7: a hex string representing the MD5 sum of the FOTA file will be stored at buf; len must be at least 32 as an MD5 sum is 16 bytes. FTP_FOTA_FILE is not supported on SARA-U2. Note 8: FTP_GET_DIRECT and FTP_PUT_DIRECT are not supported by this driver.

Parameters:
ftpCmdthe FTP command.
file1the first file name if required (NULL otherwise).
file2the second file name if required (NULL otherwise).
bufpointer to a buffer, required for FTP_DIRECT mode and FTP_LS only.
lenthe size of buf.
continueif true then attempt to continue a download that was previously interrupted.
Returns:
NULL if successful, otherwise a pointer to a Error struct containing the error class and error code, see section Appendix A.B of u-blox-ATCommands_Manual(UBX-13002752).pdf for details.

Definition at line 828 of file UbloxATCellularInterfaceExt.cpp.

void ftpResetPar (  )

Reset the FTP configuration back to defaults.

Definition at line 780 of file UbloxATCellularInterfaceExt.cpp.

bool ftpSetPar ( FtpOpCode  ftpOpCode,
const char *  ftpInPar 
)

Set FTP parameters.

This should be called as many times as is necessary to set all the possible parameters (FtpOpCode).

See section 27.1 of u-blox-ATCommands_Manual(UBX-13002752).pdf for full details. By example:

ftpOpCode ftpInPar FTP_IP_ADDRESS "145.33.18.10" (the target FTP server IP address) FTP_SERVER_NAME "www.ftpserver.com" (the target FTP server name) FTP_USER_NAME "my_username" FTP_PASSWORD "my_password" FTP_ACCOUNT "my_account" (not required by most FTP servers) FTP_INACTIVITY_TIMEOUT "60" (the default is 0, which means no timeout) FTP_MODE "0" for active, "1" for passive (the default is 0) FTP_SERVER_PORT "25" (default is port 21) FTP_SECURE "0" for no security, "1" for SFTP (the default is 0)

Parameters:
ftpOpCodethe FTP operation code.
ftpInParthe FTP input parameter.
Returns:
true if successful, false otherwise.

Definition at line 793 of file UbloxATCellularInterfaceExt.cpp.

bool ftpSetTimeout ( int  timeout )

Set the timeout for FTP operations.

Parameters:
timeout-1 blocking, else non-blocking timeout in milliseconds.
Returns:
true if successful, otherwise false.

Definition at line 767 of file UbloxATCellularInterfaceExt.cpp.

const char * getFtpCmd ( FtpCmd  ftpCmd ) [protected]

Helper function to get an FTP command as a text string, useful for debug purposes.

Parameters:
ftpCmdCodethe FTP command.
Returns:
FTP command in string format.

Definition at line 146 of file UbloxATCellularInterfaceExt.cpp.

const char * getHttpCmd ( HttpCmd  httpCmd ) [protected]

Helper function to get a HTTP command as a text string, useful for debug purposes.

Parameters:
httpCmdCodethe HTTP command.
Returns:
HTTP command in string format.

Definition at line 64 of file UbloxATCellularInterfaceExt.cpp.

int httpAllocProfile (  )

Find a free HTTP profile.

A profile will be blocking when first allocated.

Returns:
the profile or negative if none are available.

Definition at line 489 of file UbloxATCellularInterfaceExt.cpp.

UbloxATCellularInterfaceExt::Error * httpCommand ( int  httpProfile,
HttpCmd  httpCmd,
const char *  httpPath,
const char *  rspFile,
const char *  sendStr,
int  httpContentType,
const char *  httpCustomPar,
char *  buf,
int  len,
int *  read_size = NULL 
)

Perform a HTTP command.

See section 28.3 of u-blox-ATCommands_Manual(UBX-13002752).pdf for full details. By example, it works like this:

httpCmd httpPath rspFile sendStr httpContentType httpCustomPar HEAD "path/file.html" NULL NULL 0 NULL GET "path/file.html" NULL NULL 0 NULL DELETE "path/file.html" NULL NULL 0 NULL PUT "path/file.html" NULL "myfile.txt" 0 to 6 Note 1 POST_FILE "path/file.html" NULL "myfile.txt" 0 to 6 Note 1 POST "path/file.html" NULL "hello there!" 0 to 6 Note 1

Note 1: httpCustomPar is only applicable when httpContentType = HTTP_CONTENT_USER_DEFINED.

The server to which this command is directed must have previously been set with a call to httpSetPar(). If the server requires TLS (i.e. "HTTPS"), then set that up with httpSetPar() also (HTTP_SECURE).

rspFile may be left as NULL as the server response will be returned in buf. Alternatively, a rspFile may be given (e.g. "myresponse.txt") and this can later be read from the modem file system using readFile().

Parameters:
httpProfilethe HTTP profile identifier.
httpCmdthe HTTP command.
httpPaththe path of resource on the HTTP server.
rspFilethe local modem file where the server response will be stored, use NULL for don't care.
sendStrthe filename or string to be sent to the HTTP server with the command request.
httpContentTypethe HTTP Content-Type identifier.
httpCustomParthe parameter for a user defined HTTP Content-Type.
bufthe buffer to read into.
lenthe size of the buffer to read into.
read_sizeZero initialized variable address
Returns:
NULL if successful, otherwise a pointer to a Error struct containing the error class and error code, see section Appendix A.B of u-blox-ATCommands_Manual(UBX-13002752).pdf for details.

Definition at line 618 of file UbloxATCellularInterfaceExt.cpp.

bool httpFreeProfile ( int  profile )

Free the HTTP profile.

Parameters:
profilethe HTTP profile handle.
Returns:
true if successful, otherwise false.

Definition at line 511 of file UbloxATCellularInterfaceExt.cpp.

bool httpResetProfile ( int  httpProfile )

Reset a HTTP profile back to defaults.

This may be called if the state of a HTTP profile during parameter setting or exchange of HTTP commands has become confusing/unknown.

Parameters:
httpProfilethe HTTP profile to be reset.
Returns:
true if successful, false otherwise.

Definition at line 548 of file UbloxATCellularInterfaceExt.cpp.

bool httpSetPar ( int  httpProfile,
HttpOpCode  httpOpCode,
const char *  httpInPar 
)

Set HTTP parameters.

This should be called as many times as is necessary to set all the possible parameters (HttpOpCode).

See section 28.1 of u-blox-ATCommands_Manual(UBX-13002752).pdf for full details. By example:

httpOpCode httpInPar HTTP_IP_ADDRESS "145.33.18.10" (the target HTTP server IP address) HTTP_SERVER_NAME "www.myhttpserver.com" (the target HTTP server name) HTTP_USER_NAME "my_username" HTTP_PASSWORD "my_password" HTTP_AUTH_TYPE "0" for no authentication, "1" for username/password authentication (the default is 0) HTTP_SERVER_PORT "81" (default is port 80) HTTP_SECURE "0" for no security, "1" for TLS (the default is 0), not all modems support this parameter

Parameters:
httpProfilethe HTTP profile identifier.
httpOpCodethe HTTP operation code.
httpInParthe HTTP input parameter.
Returns:
true if successful, false otherwise.

Definition at line 561 of file UbloxATCellularInterfaceExt.cpp.

bool httpSetTimeout ( int  profile,
int  timeout 
)

Set the timeout for this profile.

Parameters:
profilethe HTTP profile handle.
timeout-1 blocking, else non-blocking timeout in milliseconds.
Returns:
true if successful, otherwise false.

Definition at line 531 of file UbloxATCellularInterfaceExt.cpp.

void UUFTPCD_URC (  ) [protected]

Callback to capture data returned from an FTP command.

Definition at line 123 of file UbloxATCellularInterfaceExt.cpp.

void UUFTPCR_URC (  ) [protected]

Callback to capture the result of an FTP command.

Definition at line 99 of file UbloxATCellularInterfaceExt.cpp.

void UUHTTPCR_URC (  ) [protected]

Callback to capture the response to an HTTP command.

Definition at line 33 of file UbloxATCellularInterfaceExt.cpp.

void UULOC_URC (  ) [protected]

Callback to capture +UULOC.

Definition at line 275 of file UbloxATCellularInterfaceExt.cpp.

void UULOCIND_URC (  ) [protected]

Callback to capture +UULOCIND.

Definition at line 199 of file UbloxATCellularInterfaceExt.cpp.


Field Documentation

char* _ftpBuf [protected]

A place to store data returns from an FTP operation.

Definition at line 558 of file UbloxATCellularInterfaceExt.h.

int _ftpBufLen [protected]

The length of FTP data that can be stored (at _ftpBuf).

Definition at line 562 of file UbloxATCellularInterfaceExt.h.

Error _ftpError [protected]

storage for the last FTP error

Definition at line 566 of file UbloxATCellularInterfaceExt.h.

int _ftpTimeout [protected]

The FTP timeout in milliseconds.

Definition at line 542 of file UbloxATCellularInterfaceExt.h.

HttpProfCtrl _httpProfiles[4] [protected]

The HTTP profile storage.

Definition at line 510 of file UbloxATCellularInterfaceExt.h.

volatile int _lastFtpOpCodeData [protected]

A place to store the last FTP op code for data response.

Definition at line 554 of file UbloxATCellularInterfaceExt.h.

volatile int _lastFtpOpCodeResult [protected]

A place to store the FTP op code for the last result.

Definition at line 546 of file UbloxATCellularInterfaceExt.h.

volatile int _lastFtpResult [protected]

A place to store the last FTP result.

Definition at line 550 of file UbloxATCellularInterfaceExt.h.

CellLocData _loc[CELL_MAX_HYP] [protected]

The Cell Locate data.

Definition at line 602 of file UbloxATCellularInterfaceExt.h.

volatile int _locExpPos [protected]

Expected positions.

Definition at line 598 of file UbloxATCellularInterfaceExt.h.

volatile int _locRcvPos [protected]

Received positions.

Definition at line 594 of file UbloxATCellularInterfaceExt.h.

char urcBuf[128] [protected]

Buffer for the URC to work with.

Definition at line 606 of file UbloxATCellularInterfaceExt.h.