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:

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.
debug_on	true 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:

apn	The APN to use.
username	The user name to use.
password	The password to use.
auth	The 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:

cid	The connection ID.
apn	The APN to use.
username	The user name to use.
password	The password to use.
auth	The 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_pin	PIN for the SIM card.
apn	Optionally, access point name.
uname	Optionally, user name.
pwd	Optionally, 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:

cb	The 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:

host	Host name to resolve.
address	Destination for the host SocketAddress.
version	IP 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:

handle	Socket handle.
level	Stack-specific protocol level.
optname	Stack-specific option identifier.
optval	Destination for option value.
optlen	Length 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:

auth	The 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:

apn	Access point name.
uname	Optionally, user name.
pwd	Optionally, 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_pin	New PIN to be used in string format, must be a const.
immediate	If 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_pin	Old 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:

plmn	user 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_pin PIN 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:

set	Can be set to true if the SIM PIN check is supposed to be enabled and vice versa.
immediate	If 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_pin	The 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:

handle	Socket handle.
level	Stack-specific protocol level.
optname	Stack-specific option identifier.
optval	Option value.
optlen	Length 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:

server	Socket handle to server to accept from.
handle	Destination for a handle to the newly created socket.
address	Destination 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:

handle	Socket handle.
callback	Function to call on state change.
data	Argument 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:

handle	Socket handle.
address	Local 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:

handle Socket 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:

handle	Socket handle.
address	The 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:

handle	Socket handle.
backlog	Number 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:

handle	Destination for the handle to a newly created socket.
proto	Protocol 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:

handle	Socket handle.
data	Destination buffer for data received from the host.
size	Size 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:

handle	Socket handle.
address	Destination for the source address or NULL.
data	Destination buffer for data received from the host.
size	Size 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:

handle	Socket handle.
data	Buffer of data to send to the host.
size	Size 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: