Implementation of the CellularInterface for u-blox C027 and C030 (non-N2xx flavour) modems that uses the IP stack on-board the cellular modem, hence not requiring LWIP (and so less RAM) and allowing any AT command exchanges to be carried out at the same time as data transfers (since the modem remains in AT mode all the time). This library may be used from mbed 5.5 onwards. If you need to use SMS, USSD or access the modem file system at the same time as using the CellularInterface then use ublox-at-cellular-interface-ext instead.

Dependents:   example-ublox-cellular-interface example-ublox-cellular-interface_r410M example-ublox-mbed-client example-ublox-cellular-interface ... more

Embed: (wiki syntax)

« Back to documentation index

<title>UbloxATCellularInterface Class Reference</title>

UbloxATCellularInterface class. More...

#include <UbloxATCellularInterface.h>

Data Structures

struct  SockCtrl
 Management structure for sockets. More...

Public Member Functions

 UbloxATCellularInterface (PinName tx=MDMTXD, PinName rx=MDMRXD, int baud=MBED_CONF_UBLOX_CELL_BAUD_RATE, bool debug_on=false, osPriority priority=osPriorityNormal)
 Constructor.
virtual nsapi_error_t gethostbyname (const char *host, SocketAddress *address, nsapi_version_t version=NSAPI_UNSPEC)
 Translates a host name to an IP address with specific IP version.
virtual void set_authentication (nsapi_security_t auth)
 Set the authentication scheme.
virtual void set_credentials (const char *apn, const char *uname=0, const char *pwd=0)
 Set the cellular network credentials.
virtual void set_sim_pin (const char *sim_pin)
 Set the PIN code for the SIM card.
virtual nsapi_error_t connect (const char *sim_pin, const char *apn=0, const char *uname=0, const char *pwd=0)
 Connect to the cellular network and start the interface.
virtual nsapi_error_t connect ()
 Attempt to connect to the cellular network.
virtual nsapi_error_t disconnect ()
 Attempt to disconnect from the network.
nsapi_error_t set_sim_pin_check (bool set, bool immediate=false, const char *sim_pin=NULL)
 Adds or removes a SIM facility lock.
nsapi_error_t set_new_sim_pin (const char *new_pin, bool immediate=false, const char *old_pin=NULL)
 Change the PIN for the SIM card.
virtual bool is_connected ()
 Check if the connection is currently established or not.
 MBED_DEPRECATED_SINCE ("mbed-os-5.15","String-based APIs are deprecated") virtual const char *get_ip_address()
 Get the local IP address.
virtual nsapi_error_t get_ip_address (SocketAddress *address)
 MBED_DEPRECATED_SINCE ("mbed-os-5.15","String-based APIs are deprecated") virtual const char *get_netmask()
 Get the local network mask.
virtual nsapi_error_t get_netmask (SocketAddress *address)
 MBED_DEPRECATED_SINCE ("mbed-os-5.15","String-based APIs are deprecated") virtual const char *get_gateway()
 Get the local gateways.
virtual nsapi_error_t get_gateway (SocketAddress *address)
void connection_status_cb (Callback< void(nsapi_error_t)> cb)
 Call back in case connection is lost.
virtual void set_plmn (const char *plmn)
 Set the plmn.

Protected Member Functions

virtual void get_next_credentials (const char **config)
 Get the next set of credentials from the database.
virtual bool activate_profile (const char *apn, const char *username, const char *password, nsapi_security_t auth)
 Activate one of the on-board modem's connection profiles.
virtual bool activate_profile_reuse_external (void)
 Activate a profile using the existing external connection.
virtual bool activate_profile_by_cid (int cid, const char *apn, const char *username, const char *password, nsapi_security_t auth)
 Activate a profile based on connection ID.
virtual bool connect_modem_stack ()
 Connect the on board IP stack of the modem.
virtual bool disconnect_modem_stack ()
 Disconnect the on board IP stack of the modem.
virtual NetworkStack * get_stack ()
 Provide access to the NetworkStack object.
virtual nsapi_error_t socket_open (nsapi_socket_t *handle, nsapi_protocol_t proto)
 Open a socket.
virtual nsapi_error_t socket_close (nsapi_socket_t handle)
 Close a socket.
virtual nsapi_error_t socket_bind (nsapi_socket_t handle, const SocketAddress &address)
 Bind a specific port to a socket.
virtual nsapi_error_t socket_connect (nsapi_socket_t handle, const SocketAddress &address)
 Connects TCP socket to a remote host.
virtual nsapi_size_or_error_t socket_send (nsapi_socket_t handle, const void *data, nsapi_size_t size)
 Send data over a TCP socket.
virtual nsapi_size_or_error_t socket_sendto (nsapi_socket_t handle, const SocketAddress &address, const void *data, nsapi_size_t size)
 Send a packet over a UDP socket.
virtual nsapi_size_or_error_t socket_recv (nsapi_socket_t handle, void *data, nsapi_size_t size)
 Receive data over a TCP socket.
virtual nsapi_size_or_error_t socket_recvfrom (nsapi_socket_t handle, SocketAddress *address, void *data, nsapi_size_t size)
 Receive a packet over a UDP socket.
virtual void socket_attach (nsapi_socket_t handle, void(*callback)(void *), void *data)
 Register a callback on state change of the socket.
virtual nsapi_error_t socket_listen (nsapi_socket_t handle, int backlog)
 Listen for connections on a TCP socket.
virtual nsapi_error_t socket_accept (nsapi_socket_t server, nsapi_socket_t *handle, SocketAddress *address=0)
 Accepts a connection on a TCP socket.
virtual nsapi_error_t setsockopt (nsapi_socket_t handle, int level, int optname, const void *optval, unsigned optlen)
 Set stack-specific socket options.
virtual nsapi_error_t getsockopt (nsapi_socket_t handle, int level, int optname, void *optval, unsigned *optlen)
 Get stack-specific socket options.

Protected Attributes

SockCtrl _sockets [7]
 Sockets storage.
char * _ip
 Storage for a single IP address.
const char * _apn
 The APN to use.
const char * _uname
 The user name to use.
const char * _pwd
 The password to use.
nsapi_security_t _auth
 The type of authentication to use.

Detailed Description

UbloxATCellularInterface class.

This class implements the network stack interface into the cellular modems on the C030 and C027 boards for 2G/3G/4G modules using the IP stack running on the cellular module.

Definition at line 64 of file UbloxATCellularInterface.h.


Constructor & Destructor Documentation

UbloxATCellularInterface ( PinName  tx = MDMTXD,
PinName  rx = MDMRXD,
int  baud = MBED_CONF_UBLOX_CELL_BAUD_RATE,
bool  debug_on = 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.
debug_ontrue to switch AT interface debug on, otherwise false.

Definition at line 1067 of file UbloxATCellularInterface.cpp.


Member Function Documentation

bool activate_profile ( const char *  apn,
const char *  username,
const char *  password,
nsapi_security_t  auth 
) [protected, virtual]

Activate one of the on-board modem's connection profiles.

Parameters:
apnThe APN to use.
usernameThe user name to use.
passwordThe password to use.
authThe authentication method to use (NSAPI_SECURITY_NONE, NSAPI_SECURITY_PAP, NSAPI_SECURITY_CHAP or NSAPI_SECURITY_UNKNOWN).
Returns:
True if successful, otherwise false.

Definition at line 245 of file UbloxATCellularInterface.cpp.

bool activate_profile_by_cid ( int  cid,
const char *  apn,
const char *  username,
const char *  password,
nsapi_security_t  auth 
) [protected, virtual]

Activate a profile based on connection ID.

Parameters:
cidThe connection ID.
apnThe APN to use.
usernameThe user name to use.
passwordThe password to use.
authThe authentication method to use.
Returns:
True if successful, otherwise false.

Definition at line 342 of file UbloxATCellularInterface.cpp.

bool activate_profile_reuse_external ( void   ) [protected, virtual]

Activate a profile using the existing external connection.

Returns:
true if successful, otherwise false.

Definition at line 308 of file UbloxATCellularInterface.cpp.

nsapi_error_t connect ( const char *  sim_pin,
const char *  apn = 0,
const char *  uname = 0,
const char *  pwd = 0 
) [virtual]

Connect to the cellular network and start the interface.

Attempts to connect to a cellular network. Note: if init() has not been called beforehand, connect() will call it first.

Parameters:
sim_pinPIN for the SIM card.
apnOptionally, access point name.
unameOptionally, user name.
pwdOptionally, password.
Returns:
NSAPI_ERROR_OK on success, or negative error code on failure.

Definition at line 1181 of file UbloxATCellularInterface.cpp.

nsapi_error_t connect (  ) [virtual]

Attempt to connect to the cellular network.

Brings up the network interface. Connects to the cellular radio network and then brings up IP stack on the cellular modem to be used indirectly via AT commands, rather than LWIP. Note: if init() has not been called beforehand, connect() will call it first. NOTE: even a failed attempt to connect will cause the modem to remain powered up. To power it down, call deinit().

For APN setup, default behaviour is to use 'internet' as APN string and assuming no authentication is required, i.e., user name and password are not set. Optionally, a database lookup can be requested by turning on the APN database lookup feature. The APN database is by no means exhaustive (feel free to submit a pull request with additional values). It contains a short list of some public APNs with publicly available user names and passwords (if required) in some particular countries only. Lookup is done using IMSI (International mobile subscriber identifier).

The preferred method is to setup APN using 'set_credentials()' API.

If you find that the AT interface returns "CONNECT" but shortly afterwards drops the connection then 99% of the time this will be because the APN is incorrect.

Returns:
0 on success, negative error code on failure.

Definition at line 1210 of file UbloxATCellularInterface.cpp.

bool connect_modem_stack (  ) [protected, virtual]

Connect the on board IP stack of the modem.

Returns:
True if successful, otherwise false.

Definition at line 459 of file UbloxATCellularInterface.cpp.

void connection_status_cb ( Callback< void(nsapi_error_t)>  cb )

Call back in case connection is lost.

Parameters:
cbThe function to call.
nsapi_error_t disconnect (  ) [virtual]

Attempt to disconnect from the network.

Brings down the network interface. Does not bring down the Radio network.

Returns:
0 on success, negative error code on failure.

Definition at line 1263 of file UbloxATCellularInterface.cpp.

bool disconnect_modem_stack (  ) [protected, virtual]

Disconnect the on board IP stack of the modem.

Returns:
True if successful, otherwise false.

Definition at line 506 of file UbloxATCellularInterface.cpp.

virtual nsapi_error_t get_gateway ( SocketAddress *  address ) [virtual]
virtual nsapi_error_t get_ip_address ( SocketAddress *  address ) [virtual]
virtual nsapi_error_t get_netmask ( SocketAddress *  address ) [virtual]
void get_next_credentials ( const char **  config ) [protected, virtual]

Get the next set of credentials from the database.

Definition at line 230 of file UbloxATCellularInterface.cpp.

NetworkStack * get_stack (  ) [protected, virtual]

Provide access to the NetworkStack object.

Returns:
The underlying NetworkStack object.

Definition at line 546 of file UbloxATCellularInterface.cpp.

nsapi_error_t gethostbyname ( const char *  host,
SocketAddress *  address,
nsapi_version_t  version = NSAPI_UNSPEC 
) [virtual]

Translates a host name to an IP address with specific IP version.

The host name may be either a domain name or an IP address. If the host name is an IP address, no network transactions will be performed.

If no stack-specific DNS resolution is provided, the host name will be resolved using a UDP socket on the stack.

Parameters:
hostHost name to resolve.
addressDestination for the host SocketAddress.
versionIP version of address to resolve, NSAPI_UNSPEC indicates version is chosen by the stack (defaults to NSAPI_UNSPEC).
Returns:
0 on success, negative error code on failure.

Definition at line 1149 of file UbloxATCellularInterface.cpp.

nsapi_error_t getsockopt ( nsapi_socket_t  handle,
int  level,
int  optname,
void *  optval,
unsigned *  optlen 
) [protected, virtual]

Get stack-specific socket options.

The getstackopt allow an application to retrieve stack-specific hints from the underlying stack. For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.

Parameters:
handleSocket handle.
levelStack-specific protocol level.
optnameStack-specific option identifier.
optvalDestination for option value.
optlenLength of the option value.
Returns:
0 on success, negative error code on failure.

Definition at line 1054 of file UbloxATCellularInterface.cpp.

virtual bool is_connected (  ) [virtual]

Check if the connection is currently established or not.

Returns:
True if connected to a data network, otherwise false.
MBED_DEPRECATED_SINCE ( "mbed-os-5.15"  ,
"String-based APIs are deprecated"   
) const

Get the local IP address.

Returns:
Null-terminated representation of the local IP address or null if no IP address has been received.
MBED_DEPRECATED_SINCE ( "mbed-os-5.15"  ,
"String-based APIs are deprecated"   
) const

Get the local network mask.

Returns:
Null-terminated representation of the local network mask or null if no network mask has been received.
MBED_DEPRECATED_SINCE ( "mbed-os-5.15"  ,
"String-based APIs are deprecated"   
) const

Get the local gateways.

Returns:
Null-terminated representation of the local gateway or null if no network mask has been received.
void set_authentication ( nsapi_security_t  auth ) [virtual]

Set the authentication scheme.

Parameters:
authThe authentication scheme, chose from NSAPI_SECURITY_NONE, NSAPI_SECURITY_PAP, NSAPI_SECURITY_CHAP or NSAPI_SECURITY_UNKNOWN; use NSAPI_SECURITY_UNKNOWN to try all of none, PAP and CHAP.

Definition at line 1127 of file UbloxATCellularInterface.cpp.

void set_credentials ( const char *  apn,
const char *  uname = 0,
const char *  pwd = 0 
) [virtual]

Set the cellular network credentials.

Please check documentation of connect() for default behaviour of APN settings.

Parameters:
apnAccess point name.
unameOptionally, user name.
pwdOptionally, password.

Definition at line 1133 of file UbloxATCellularInterface.cpp.

nsapi_error_t set_new_sim_pin ( const char *  new_pin,
bool  immediate = false,
const char *  old_pin = NULL 
)

Change the PIN for the SIM card.

Provide the new PIN for your SIM card with this API. It is ONLY possible to change the SIM PIN when SIM PIN checking is ENABLED.

Parameters:
new_pinNew PIN to be used in string format, must be a const.
immediateIf true, change the SIM PIN now, else set a flag and make the change only when connect() is called. If this is true and init() has not been called previously, it will be called first.
old_pinOld PIN, must be a const. If this is not provided, the SIM PIN must have previously been set by a call to set_sim_pin().
Returns:
0 on success, negative error code on failure.
virtual void set_plmn ( const char *  plmn ) [virtual]

Set the plmn.

PLMN controls to what network device registers.

Parameters:
plmnuser to force what network to register.
void set_sim_pin ( const char *  sim_pin ) [virtual]

Set the PIN code for the SIM card.

Parameters:
sim_pinPIN for the SIM card.

Definition at line 1143 of file UbloxATCellularInterface.cpp.

nsapi_error_t set_sim_pin_check ( bool  set,
bool  immediate = false,
const char *  sim_pin = NULL 
)

Adds or removes a SIM facility lock.

Can be used to enable or disable SIM PIN check at device startup.

Parameters:
setCan be set to true if the SIM PIN check is supposed to be enabled and vice versa.
immediateIf true, change the SIM PIN now, else set a flag and make the change only when connect() is called. If this is true and init() has not been called previously, it will be called first.
sim_pinThe current SIM PIN, must be a const. If this is not provided, the SIM PIN must have previously been set by a call to set_sim_pin().
Returns:
0 on success, negative error code on failure.
nsapi_error_t setsockopt ( nsapi_socket_t  handle,
int  level,
int  optname,
const void *  optval,
unsigned  optlen 
) [protected, virtual]

Set stack-specific socket options.

The setsockopt allow an application to pass stack-specific hints to the underlying stack. For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.

Parameters:
handleSocket handle.
levelStack-specific protocol level.
optnameStack-specific option identifier.
optvalOption value.
optlenLength of the option value.
Returns:
0 on success, negative error code on failure.

Definition at line 1047 of file UbloxATCellularInterface.cpp.

nsapi_error_t socket_accept ( nsapi_socket_t  server,
nsapi_socket_t *  handle,
SocketAddress *  address = 0 
) [protected, virtual]

Accepts a connection on a TCP socket.

The server socket must be bound and set to listen for connections. On a new connection, creates a network socket and stores it in the specified handle. The handle must be passed to following calls on the socket.

A stack may have a finite number of sockets, in this case NSAPI_ERROR_NO_SOCKET is returned if no socket is available.

This call is non-blocking. If accept would block, NSAPI_ERROR_WOULD_BLOCK is returned immediately.

Parameters:
serverSocket handle to server to accept from.
handleDestination for a handle to the newly created socket.
addressDestination for the remote address or NULL.
Returns:
0 on success, negative error code on failure.

Definition at line 1039 of file UbloxATCellularInterface.cpp.

void socket_attach ( nsapi_socket_t  handle,
void(*)(void *)  callback,
void *  data 
) [protected, virtual]

Register a callback on state change of the socket.

The specified callback will be called on state changes such as when the socket can recv/send/accept successfully and on when an error occurs. The callback may also be called spuriously without reason.

The callback may be called in an interrupt context and should not perform expensive operations such as recv/send calls.

Parameters:
handleSocket handle.
callbackFunction to call on state change.
dataArgument to pass to callback.

Definition at line 1021 of file UbloxATCellularInterface.cpp.

nsapi_error_t socket_bind ( nsapi_socket_t  handle,
const SocketAddress &  address 
) [protected, virtual]

Bind a specific port to a socket.

Binding a socket specifies port on which to receive data. The IP address is ignored. Note that binding a socket involves closing it and reopening and so the bind operation should be carried out before any others.

Parameters:
handleSocket handle.
addressLocal address to bind (of which only the port is used).
Returns:
0 on success, negative error code on failure.

Definition at line 615 of file UbloxATCellularInterface.cpp.

nsapi_error_t socket_close ( nsapi_socket_t  handle ) [protected, virtual]

Close a socket.

Closes any open connection and deallocates any memory associated with the socket.

Parameters:
handleSocket handle.
Returns:
0 on success, negative error code on failure.

Definition at line 594 of file UbloxATCellularInterface.cpp.

nsapi_error_t socket_connect ( nsapi_socket_t  handle,
const SocketAddress &  address 
) [protected, virtual]

Connects TCP socket to a remote host.

Initiates a connection to a remote server specified by the indicated address.

Parameters:
handleSocket handle.
addressThe SocketAddress of the remote host.
Returns:
0 on success, negative error code on failure.

Definition at line 654 of file UbloxATCellularInterface.cpp.

nsapi_error_t socket_listen ( nsapi_socket_t  handle,
int  backlog 
) [protected, virtual]

Listen for connections on a TCP socket.

Marks the socket as a passive socket that can be used to accept incoming connections.

Parameters:
handleSocket handle.
backlogNumber of pending connections that can be queued simultaneously, defaults to 1.
Returns:
0 on success, negative error code on failure.

Definition at line 1034 of file UbloxATCellularInterface.cpp.

nsapi_error_t socket_open ( nsapi_socket_t *  handle,
nsapi_protocol_t  proto 
) [protected, virtual]

Open a socket.

Creates a network socket and stores it in the specified handle. The handle must be passed to following calls on the socket.

Parameters:
handleDestination for the handle to a newly created socket.
protoProtocol of socket to open, NSAPI_TCP or NSAPI_UDP.
Returns:
0 on success, negative error code on failure.

Definition at line 552 of file UbloxATCellularInterface.cpp.

nsapi_size_or_error_t socket_recv ( nsapi_socket_t  handle,
void *  data,
nsapi_size_t  size 
) [protected, virtual]

Receive data over a TCP socket.

The socket must be connected to a remote host. Returns the number of bytes received into the buffer. This class sets no upper limit on the buffer size and the maximum packet size is not connected with the platform.buffered-serial-txbuf-size/platform.buffered-serial-rxbuf-size definitions.

Parameters:
handleSocket handle.
dataDestination buffer for data received from the host.
sizeSize of the buffer in bytes.
Returns:
Number of received bytes on success, negative error code on failure.

Definition at line 785 of file UbloxATCellularInterface.cpp.

nsapi_size_or_error_t socket_recvfrom ( nsapi_socket_t  handle,
SocketAddress *  address,
void *  data,
nsapi_size_t  size 
) [protected, virtual]

Receive a packet over a UDP socket.

Receives data and stores the source address in address if address is not NULL. Returns the number of bytes received into the buffer.

PACKET SIZES: the maximum packet size that can be retrieved in a single call to this method is limited by the configuration value platform.buffered-serial-rxbuf-size (default 256). The maximum UDP packet size is:

platform.buffered-serial-rxbuf-size - AT_PACKET_OVERHEAD

...with a limit of 1024 (at the AT interface). So to allow reception of a 1024 byte UDP packet in a single call, edit your mbed_app.json to add a target override setting platform.buffered-serial-rxbuf-size to 1101.

If the received packet is larger than this limit, any remainder will be returned in subsequent calls to this method. Once a single UDP packet has been received, this method will return.

Parameters:
handleSocket handle.
addressDestination for the source address or NULL.
dataDestination buffer for data received from the host.
sizeSize of the buffer in bytes.
Returns:
Number of received bytes on success, negative error code on failure.

Definition at line 894 of file UbloxATCellularInterface.cpp.

nsapi_size_or_error_t socket_send ( nsapi_socket_t  handle,
const void *  data,
nsapi_size_t  size 
) [protected, virtual]

Send data over a TCP socket.

The socket must be connected to a remote host. Returns the number of bytes sent from the buffer. This class sets no upper buffer limit on buffer size and the maximum packet size is not connected with the platform.buffered-serial-txbuf-size/platform.buffered-serial-rxbuf-size definitions.

Parameters:
handleSocket handle.
dataBuffer of data to send to the host.
sizeSize of the buffer in bytes.
Returns:
Number of sent bytes on success, negative error code on failure.

Definition at line 677 of file UbloxATCellularInterface.cpp.

nsapi_size_or_error_t socket_sendto ( nsapi_socket_t  handle,
const SocketAddress &  address,
const void *  data,
nsapi_size_t  size 
) [protected, virtual]

Send a packet over a UDP socket.

Sends data to the specified address. Returns the number of bytes sent from the buffer.

PACKET SIZES: the maximum packet size that can be sent in a single UDP packet is limited by the configuration value platform.buffered-serial-txbuf-size (defaults to 256). The maximum UDP packet size is:

platform.buffered-serial-txbuf-size - AT_PACKET_OVERHEAD

...with a limit of 1024 bytes (at the AT interface). So, to allow sending of a 1024 byte UDP packet, edit your mbed_app.json to add a target override setting platform.buffered-serial-txbuf-size to 1101. However, for UDP packets, 508 bytes is considered a more realistic size, taking into account fragmentation sizes over the public internet, which leads to a platform.buffered-serial-txbuf-size/platform.buffered-serial-rxbuf-size setting of 585.

If size is larger than this limit, the data will be split across separate UDP packets.

Parameters:
handleSocket handle.
addressThe SocketAddress of the remote host.
dataBuffer of data to send to the host.
sizeSize of the buffer in bytes.
Returns:
Number of sent bytes on success, negative error code on failure.

Definition at line 729 of file UbloxATCellularInterface.cpp.


Field Documentation

const char* _apn [protected]

The APN to use.

Definition at line 318 of file UbloxATCellularInterface.h.

nsapi_security_t _auth [protected]

The type of authentication to use.

Definition at line 330 of file UbloxATCellularInterface.h.

char* _ip [protected]

Storage for a single IP address.

Definition at line 314 of file UbloxATCellularInterface.h.

const char* _pwd [protected]

The password to use.

Definition at line 326 of file UbloxATCellularInterface.h.

SockCtrl _sockets[7] [protected]

Sockets storage.

Definition at line 310 of file UbloxATCellularInterface.h.

const char* _uname [protected]

The user name to use.

Definition at line 322 of file UbloxATCellularInterface.h.