UbloxATCellularInterface class. More...

#include <UbloxATCellularInterfaceN2xx.h>

Data Structures
struct	SockCtrl
	Management structure for sockets. More...
Public Member Functions
	UbloxATCellularInterfaceN2xx (PinName tx=MDMTXD, PinName rx=MDMRXD, int baud=MBED_CONF_UBLOX_CELL_N2XX_BAUD_RATE, bool debug_on=false)
	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.
void	set_LocalListenPort (int port)
	Set the local listen port when opening a UDP socket.
bool	initialise ()
	Turns on the modem and reads the module information.
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.
virtual const char *	get_ip_address ()
	Get the local IP address.
virtual const char *	get_netmask ()
	Get the local network mask.
virtual const char *	get_gateway ()
	Get the local gateways.
virtual void	set_plmn (const char *plmn)
	Set the plmn.
void	connection_status_cb (Callback< void(nsapi_error_t)> cb)
	Call back in case connection is lost.
Protected Member Functions
virtual void	get_next_credentials (const char *config)
	Get the next set of credentials from the database.
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 UbloxATCellularInterfaceN2xx.h.

Constructor & Destructor Documentation

UbloxATCellularInterfaceN2xx	(	PinName	tx = `MDMTXD`,
		PinName	rx = `MDMRXD`,
		int	baud = `MBED_CONF_UBLOX_CELL_N2XX_BAUD_RATE`,
		bool	debug_on = `false`
	)

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 644 of file UbloxATCellularInterfaceN2xx.cpp.

Member Function Documentation

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 initialise() 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 733 of file UbloxATCellularInterfaceN2xx.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 768 of file UbloxATCellularInterfaceN2xx.cpp.

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

Call back in case connection is lost.

Parameters:

cb	The function to call.

Definition at line 885 of file UbloxATCellularInterfaceN2xx.cpp.

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 796 of file UbloxATCellularInterfaceN2xx.cpp.

const char * get_gateway ( ) [virtual]

Get the local gateways.

Returns:: Null-terminated representation of the local gateway or null if no network mask has been received.

Definition at line 871 of file UbloxATCellularInterfaceN2xx.cpp.

const char * get_ip_address ( ) [virtual]

Get the local IP address.

Returns:: Null-terminated representation of the local IP address or null if no IP address has been received.

Definition at line 834 of file UbloxATCellularInterfaceN2xx.cpp.

const char * get_netmask ( ) [virtual]

Get the local network mask.

Returns:: Null-terminated representation of the local network mask or null if no network mask has been received.

Definition at line 864 of file UbloxATCellularInterfaceN2xx.cpp.

void get_next_credentials ( const char * config ) [protected, virtual]

Get the next set of credentials from the database.

Definition at line 142 of file UbloxATCellularInterfaceN2xx.cpp.

NetworkStack * get_stack ( ) [protected, virtual]

Provide access to the NetworkStack object.

Returns:: The underlying NetworkStack object.

Definition at line 160 of file UbloxATCellularInterfaceN2xx.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 715 of file UbloxATCellularInterfaceN2xx.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 631 of file UbloxATCellularInterfaceN2xx.cpp.

bool initialise ( )

Turns on the modem and reads the module information.

Definition at line 762 of file UbloxATCellularInterfaceN2xx.cpp.

bool is_connected ( ) [virtual]

Check if the connection is currently established or not.

Returns:: True if connected to a data network, otherwise false.

Definition at line 828 of file UbloxATCellularInterfaceN2xx.cpp.

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 694 of file UbloxATCellularInterfaceN2xx.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 700 of file UbloxATCellularInterfaceN2xx.cpp.

void set_LocalListenPort ( int port )

Set the local listen port when opening a UDP socket.

Definition at line 876 of file UbloxATCellularInterfaceN2xx.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.

Definition at line 820 of file UbloxATCellularInterfaceN2xx.cpp.

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.

Definition at line 880 of file UbloxATCellularInterfaceN2xx.cpp.

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 710 of file UbloxATCellularInterfaceN2xx.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.

Definition at line 812 of file UbloxATCellularInterfaceN2xx.cpp.

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 624 of file UbloxATCellularInterfaceN2xx.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 616 of file UbloxATCellularInterfaceN2xx.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 598 of file UbloxATCellularInterfaceN2xx.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 228 of file UbloxATCellularInterfaceN2xx.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 205 of file UbloxATCellularInterfaceN2xx.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 235 of file UbloxATCellularInterfaceN2xx.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 611 of file UbloxATCellularInterfaceN2xx.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 166 of file UbloxATCellularInterfaceN2xx.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 403 of file UbloxATCellularInterfaceN2xx.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 411 of file UbloxATCellularInterfaceN2xx.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 242 of file UbloxATCellularInterfaceN2xx.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: