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
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. | |
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. | |
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. | |
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. | |
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
enum CellRespType |
Types of Cell Locate response.
Definition at line 367 of file UbloxATCellularInterfaceExt.h.
enum CellSensType |
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.
enum HttpContentType |
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:
-
tx the UART TX data pin to which the modem is attached. rx the UART RX data pin to which the modem is attached. baud the UART baud rate. debugOn true 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:
-
scanMode network 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:
-
data pointer to a CellLocData structure where the location will be put. index of 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:
-
sensor sensor selection. timeout timeout period in seconds (1 - 999). accuracy target accuracy in meters (1 - 999999). type detailed or multi-hypothesis. hypothesis maximum 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_1 host name of the primary MGA server. server_2 host name of the secondary MGA server. token authentication token for MGA server access. days the number of days into the future the off-line data for the u-blox 7. period the number of weeks into the future the off-line data for u-blox M8. resolution resolution 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_1 host name of the primary MGA server. port server port. latency expected network latency in seconds from 0 to 10000 milliseconds. mode Assist 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:
-
modemHandle the 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:
-
ftpCmd the FTP command. file1 the first file name if required (NULL otherwise). file2 the second file name if required (NULL otherwise). buf pointer to a buffer, required for FTP_DIRECT mode and FTP_LS only. len the size of buf. continue if 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:
-
ftpOpCode the FTP operation code. ftpInPar the 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:
-
ftpCmdCode the 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:
-
httpCmdCode the 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:
-
httpProfile the HTTP profile identifier. httpCmd the HTTP command. httpPath the path of resource on the HTTP server. rspFile the local modem file where the server response will be stored, use NULL for don't care. sendStr the filename or string to be sent to the HTTP server with the command request. httpContentType the HTTP Content-Type identifier. httpCustomPar the parameter for a user defined HTTP Content-Type. buf the buffer to read into. len the size of the buffer to read into. read_size Zero 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:
-
profile the 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:
-
httpProfile the 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:
-
httpProfile the HTTP profile identifier. httpOpCode the HTTP operation code. httpInPar the 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:
-
profile the 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.
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.
Generated on Tue Jul 12 2022 21:43:58 by 1.7.2