RFCOMM

General Description

The RFCOMM protocol provides emulation of serial ports over the L2CAP protocol.

The protocol is based on the ETSI standard GSM 7.1.0. RFCOMM is a simple transport protocol, with additional provisions for emulating the nine circuits of RS-232 (ITU-T V.24) serial ports. The RFCOMM protocol supports up to 60 simultaneous connections between two Bluetooth devices. The number of connections that may be used simultaneously in a Bluetooth device is implementation-specific.

Macros
#define	PORT_MASK_ALL
	RFCOMM Port Mask to enable all. More...

Typedefs
typedef int	wiced_bt_rfcomm_result_t
	RFCOMM result code (see wiced_bt_rfcomm_result_e)
typedef uint8_t	wiced_bt_rfcomm_signal_t
	RFCOMM Signals (see wiced_bt_rfcomm_signal_e)
typedef void()	wiced_bt_port_mgmt_cback_t(wiced_bt_rfcomm_result_t code, uint16_t port_handle)
	Port management callback. More...
typedef void()	wiced_bt_port_event_cback_t(wiced_bt_rfcomm_port_event_t event, uint16_t port_handle)
	Port event callback. More...
typedef void()	wiced_bt_port_tx_cback_t(uint16_t port_handle, void *p_data)
	Port TX Complete callback. More...

Enumerations
enum	wiced_bt_rfcomm_port_event_t {   PORT_EV_NONE = 0x00000000,   PORT_EV_RXCHAR = 0x00000001,   PORT_EV_RXFLAG = 0x00000002,   PORT_EV_TXEMPTY = 0x00000004,   PORT_EV_CTS = 0x00000008,   PORT_EV_DSR = 0x00000010,   PORT_EV_RLSD = 0x00000020,   PORT_EV_BREAK = 0x00000040,   PORT_EV_ERR = 0x00000080,   PORT_EV_RING = 0x00000100,   PORT_EV_CTSS = 0x00000400,   PORT_EV_DSRS = 0x00000800,   PORT_EV_RLSDS = 0x00001000,   PORT_EV_OVERRUN = 0x00002000,   PORT_EV_CONNECTED = 0x00000200,   PORT_EV_CONNECT_ERR = 0x00008000,   PORT_EV_FC = 0x00010000,   PORT_EV_FCS = 0x00020000 }
	RFCOMM Port Event Masks. More...
enum	wiced_bt_rfcomm_result_e {   WICED_BT_RFCOMM_SUCCESS,   WICED_BT_RFCOMM_ERROR,   WICED_BT_RFCOMM_ALREADY_OPENED,   WICED_BT_RFCOMM_CMD_PENDING,   WICED_BT_RFCOMM_APP_NOT_REGISTERED,   WICED_BT_RFCOMM_NO_MEM,   WICED_BT_RFCOMM_NO_RESOURCES,   WICED_BT_RFCOMM_BAD_BD_ADDR,   WICED_BT_RFCOMM_INVALID_MTU,   WICED_BT_RFCOMM_BAD_HANDLE,   WICED_BT_RFCOMM_NOT_OPENED,   WICED_BT_RFCOMM_LINE_ERR,   WICED_BT_RFCOMM_START_FAILED,   WICED_BT_RFCOMM_PAR_NEG_FAILED,   WICED_BT_RFCOMM_RFCOMM_NEG_FAILED,   WICED_BT_RFCOMM_PEER_CONNECTION_FAILED,   WICED_BT_RFCOMM_PEER_FAILED,   WICED_BT_RFCOMM_PEER_TIMEOUT,   WICED_BT_RFCOMM_CLOSED,   WICED_BT_RFCOMM_TX_FULL,   WICED_BT_RFCOMM_LOCAL_CLOSED,   WICED_BT_RFCOMM_LOCAL_TIMEOUT,   WICED_BT_RFCOMM_TX_QUEUE_DISABLED,   WICED_BT_RFCOMM_PAGE_TIMEOUT,   WICED_BT_RFCOMM_INVALID_SCN }
	RFCOMM Result Codes. More...
enum	wiced_bt_rfcomm_signal_e {   PORT_SET_DTRDSR =0x01,   PORT_CLR_DTRDSR,   PORT_SET_CTSRTS,   PORT_CLR_CTSRTS,   PORT_SET_RI,   PORT_CLR_RI,   PORT_SET_DCD,   PORT_CLR_DCD,   PORT_BREAK }
	RFCOMM Signals. More...

Functions
wiced_bt_rfcomm_result_t	wiced_bt_rfcomm_create_connection (uint16_t uuid, uint8_t scn, wiced_bool_t is_server, uint16_t mtu, wiced_bt_device_address_t bd_addr, uint16_t *p_handle, wiced_bt_port_mgmt_cback_t *p_mgmt_cb)
	Establish serial port connection to the peer device, or allow RFCOMM to accept a connection from peer devices. More...
wiced_bt_rfcomm_result_t	wiced_bt_rfcomm_remove_connection (uint16_t handle, wiced_bool_t remove_server)
	Close the specified connection. More...
wiced_bt_rfcomm_result_t	wiced_bt_rfcomm_set_event_callback (uint16_t port_handle, wiced_bt_port_event_cback_t *p_port_cb, wiced_bt_port_tx_cback_t *p_tx_cmpl_cb)
	Set event callback the specified connection(neither of the callback can be NULL). More...
wiced_bt_rfcomm_result_t	wiced_bt_rfcomm_set_event_mask (uint16_t port_handle, wiced_bt_rfcomm_port_event_t mask)
	Set events for which to be notified. More...
wiced_bt_rfcomm_result_t	wiced_bt_rfcomm_control (uint16_t handle, uint8_t signal)
	Send control signal to the peer device. More...
wiced_bt_rfcomm_result_t	wiced_bt_rfcomm_flow_control (uint16_t handle, wiced_bool_t enable)
	This function directs a specified connection to pass flow control message to the peer device. More...
wiced_bt_rfcomm_result_t	wiced_bt_rfcomm_set_rx_fifo (uint16_t handle, char *p_mem, uint16_t size)
	This function provides RFCOMM with a data area to receive peer's data. More...
wiced_bt_rfcomm_result_t	wiced_bt_rfcomm_read_data (uint16_t handle, char *p_data, uint16_t max_len, uint16_t *p_len)
	This function reads the received application data from the peer device. More...
wiced_bt_rfcomm_result_t	wiced_bt_rfcomm_write_data (uint16_t handle, char *p_data, uint16_t max_len)
	This function sends the given application data to the peer device. More...
wiced_bt_rfcomm_result_t	wiced_bt_rfcomm_check_connection (uint16_t handle, wiced_bt_device_address_t bd_addr, uint16_t *p_lcid)
	This function checks connection referenced by handle is up and running. More...

Macro Definition Documentation

PORT_MASK_ALL

#define PORT_MASK_ALL

Value:

(PORT_EV_RXCHAR | PORT_EV_TXEMPTY | PORT_EV_CTS | \
                                   PORT_EV_DSR | PORT_EV_RLSD | PORT_EV_BREAK | \
                                   PORT_EV_ERR | PORT_EV_RING | PORT_EV_CONNECT_ERR | \
                                   PORT_EV_DSRS | PORT_EV_CTSS | PORT_EV_RLSDS | \
                                   PORT_EV_RXFLAG | PORT_EV_OVERRUN | \
                                   PORT_EV_FC | PORT_EV_FCS | PORT_EV_CONNECTED)

RFCOMM Port Mask to enable all.

Typedef Documentation

wiced_bt_port_mgmt_cback_t

typedef void() wiced_bt_port_mgmt_cback_t(wiced_bt_rfcomm_result_t code, uint16_t port_handle)

Port management callback.

Parameters

code	: Result code
port_handle	: Port handle from wiced_bt_rfcomm_create_connection.

wiced_bt_port_event_cback_t

typedef void() wiced_bt_port_event_cback_t(wiced_bt_rfcomm_port_event_t event, uint16_t port_handle)

Port event callback.

Parameters

event	: A 32-bit event code that contains a bit-mask of one or more events the caller would like to register.(see wiced_bt_rfcomm_port_event_t)
port_handle	: Port handle from wiced_bt_rfcomm_create_connection .

wiced_bt_port_tx_cback_t

typedef void() wiced_bt_port_tx_cback_t(uint16_t port_handle, void *p_data)

Port TX Complete callback.

Parameters

port_handle	: Port handle from wiced_bt_rfcomm_create_connection .
p_data	: Pointer to application data

Enumeration Type Documentation

wiced_bt_rfcomm_port_event_t

enum wiced_bt_rfcomm_port_event_t

RFCOMM Port Event Masks.

Enumerator
PORT_EV_NONE	No event.
PORT_EV_RXCHAR	Any Character received.
PORT_EV_RXFLAG	Received certain character.
PORT_EV_TXEMPTY	Transmitt Queue Empty.
PORT_EV_CTS	CTS changed state.
PORT_EV_DSR	DSR changed state.
PORT_EV_RLSD	RLSD changed state.
PORT_EV_BREAK	BREAK received.
PORT_EV_ERR	Line status error occurred.
PORT_EV_RING	Ring signal detected.
PORT_EV_CTSS	CTS state.
PORT_EV_DSRS	DSR state.
PORT_EV_RLSDS	RLSD state.
PORT_EV_OVERRUN	receiver buffer overrun
PORT_EV_CONNECTED	RFCOMM connection established.
PORT_EV_CONNECT_ERR	Was not able to establish connection or disconnected.
PORT_EV_FC	data flow enabled flag changed by remote
PORT_EV_FCS	data flow enable status true = enabled

wiced_bt_rfcomm_result_e

enum wiced_bt_rfcomm_result_e

RFCOMM Result Codes.

Enumerator
WICED_BT_RFCOMM_SUCCESS	Success.
WICED_BT_RFCOMM_ERROR	Error.
WICED_BT_RFCOMM_ALREADY_OPENED	Already Opened.
WICED_BT_RFCOMM_CMD_PENDING	Command Pending.
WICED_BT_RFCOMM_APP_NOT_REGISTERED	App Not Registered.
WICED_BT_RFCOMM_NO_MEM	No Memory.
WICED_BT_RFCOMM_NO_RESOURCES	No Resources.
WICED_BT_RFCOMM_BAD_BD_ADDR	Bad BD Address.
WICED_BT_RFCOMM_INVALID_MTU	Invalid MTU.
WICED_BT_RFCOMM_BAD_HANDLE	Bad Handle.
WICED_BT_RFCOMM_NOT_OPENED	Not Opened.
WICED_BT_RFCOMM_LINE_ERR	Line Error.
WICED_BT_RFCOMM_START_FAILED	Start Failed.
WICED_BT_RFCOMM_PAR_NEG_FAILED	DLC parameter negotiation failed.
WICED_BT_RFCOMM_RFCOMM_NEG_FAILED	Remote port negotiation failed.
WICED_BT_RFCOMM_PEER_CONNECTION_FAILED	Peer Connection Failed.
WICED_BT_RFCOMM_PEER_FAILED	Peer Failed.
WICED_BT_RFCOMM_PEER_TIMEOUT	Peer Timeout.
WICED_BT_RFCOMM_CLOSED	Closed.
WICED_BT_RFCOMM_TX_FULL	No space to transmit the packet.
WICED_BT_RFCOMM_LOCAL_CLOSED	Local Closed.
WICED_BT_RFCOMM_LOCAL_TIMEOUT	Local Timeout.
WICED_BT_RFCOMM_TX_QUEUE_DISABLED	Transmit queue disabled.
WICED_BT_RFCOMM_PAGE_TIMEOUT	Page Timeout.
WICED_BT_RFCOMM_INVALID_SCN	Invalid SCN.

wiced_bt_rfcomm_signal_e

enum wiced_bt_rfcomm_signal_e

RFCOMM Signals.

Enumerator
PORT_CLR_DTRDSR	DTRDSR set.
PORT_SET_CTSRTS	DTRDSR clear.
PORT_CLR_CTSRTS	CTSRTS set.
PORT_SET_RI	CTSRTS clear.
PORT_CLR_RI	RI set (DCE only)
PORT_SET_DCD	RI clear (DCE only)
PORT_CLR_DCD	DCD set (DCE only)
PORT_BREAK	DCD clear (DCE only)

Function Documentation

wiced_bt_rfcomm_create_connection()

wiced_bt_rfcomm_result_t wiced_bt_rfcomm_create_connection	(	uint16_t	uuid,
		uint8_t	scn,
		wiced_bool_t	is_server,
		uint16_t	mtu,
		wiced_bt_device_address_t	bd_addr,
		uint16_t *	p_handle,
		wiced_bt_port_mgmt_cback_t *	p_mgmt_cb
	)

Establish serial port connection to the peer device, or allow RFCOMM to accept a connection from peer devices.

Note

Server can call this function with the same scn parameter multiple times if it is ready to accept multiple simulteneous connections.

DLCI for the connection is (scn * 2 + 1) if client originates connection on existing none initiator multiplexer channel. Otherwise it is (scn * 2). For the server DLCI can be changed later if client will be calling it using (scn * 2 + 1) dlci.

Parameters

[in]	uuid	: The Universal Unique Identifier (UUID) of the Class ID of the service being opened
[in]	scn	: The Service Channel Number(SCN) as registered with the SDP (server) or obtained using SDP from the peer device (client)
[in]	is_server	: TRUE if requesting application is a server
[in]	mtu	: The maximum number of bytes transferred per frame If 0, a default size of L2CAP_MAX_BR_RX_MTU minus 5 bytes is used
[in]	bd_addr	: BD_ADDR of the peer (if client), NULL if server (see wiced_bt_device_address_t)
[in]	p_mgmt_cb	: Pointer to callback function to receive connection up/down events (see wiced_bt_port_mgmt_cback_t)
[out]	p_handle	: A pointer to the handle set by RFCOMM to be used in consecutive calls for this connection

Returns

WICED_BT_RFCOMM_SUCCESS : If successful
WICED_BT_RFCOMM_ALREADY_OPENED : If the client tries to establish a connection to the same BD_ADDR
WICED_BT_RFCOMM_NO_RESOURCES : If there is not enough memory to allocate a control block structure

wiced_bt_rfcomm_remove_connection()

wiced_bt_rfcomm_result_t wiced_bt_rfcomm_remove_connection	(	uint16_t	handle,
		wiced_bool_t	remove_server
	)

Close the specified connection.

Parameters

[in]	handle	: The connection handle returned by wiced_bt_rfcomm_create_connection.
[in]	remove_server	: (for server only) If TRUE, then also remove server; otherwise server remains enabled after connection is closed.

Returns

WICED_BT_RFCOMM_SUCCESS : If successful
WICED_BT_RFCOMM_BAD_HANDLE : If the handle is out of range
WICED_BT_RFCOMM_NOT_OPENED : If the connection is not opened

wiced_bt_rfcomm_set_event_callback()

wiced_bt_rfcomm_result_t wiced_bt_rfcomm_set_event_callback	(	uint16_t	port_handle,
		wiced_bt_port_event_cback_t *	p_port_cb,
		wiced_bt_port_tx_cback_t *	p_tx_cmpl_cb
	)

Set event callback the specified connection(neither of the callback can be NULL).

Parameters

[in]	port_handle	: A 16-bit unsigned integer returned by wiced_bt_rfcomm_create_connection
[in]	p_port_cb	: Address of the callback function which should be called from the RFCOMM when an event specified in the mask occurs. (see wiced_bt_port_event_cback_t)
[in]	p_tx_cmpl_cb	: Address of the callback function which should be called from the RFCOMM when TX complete (see wiced_bt_port_tx_cback_t)

Returns

WICED_BT_RFCOMM_SUCCESS : If successful
WICED_BT_RFCOMM_BAD_HANDLE : If the handle is out of range
WICED_BT_RFCOMM_NOT_OPENED : If the connection is not opened

wiced_bt_rfcomm_set_event_mask()

wiced_bt_rfcomm_result_t wiced_bt_rfcomm_set_event_mask	(	uint16_t	port_handle,
		wiced_bt_rfcomm_port_event_t	mask
	)

Set events for which to be notified.

Parameters

[in]	port_handle	: A 16-bit unsigned integer returned by wiced_bt_rfcomm_create_connection
[in]	mask	: Event mask (see wiced_bt_rfcomm_port_event_t)

Returns

WICED_BT_RFCOMM_SUCCESS : If successful
WICED_BT_RFCOMM_BAD_HANDLE : If the handle is out of range
WICED_BT_RFCOMM_NOT_OPENED : If the connection is not opened

wiced_bt_rfcomm_control()

wiced_bt_rfcomm_result_t wiced_bt_rfcomm_control	(	uint16_t	handle,
		uint8_t	signal
	)

Send control signal to the peer device.

Parameters

[in]	handle	: The connection handle returned by wiced_bt_rfcomm_create_connection
[in]	signal	: Signal to send (see wiced_bt_rfcomm_signal_e)

Returns

WICED_BT_RFCOMM_SUCCESS : If successful
WICED_BT_RFCOMM_BAD_HANDLE : If the handle is out of range
WICED_BT_RFCOMM_NOT_OPENED : If the connection is not opened

wiced_bt_rfcomm_flow_control()

wiced_bt_rfcomm_result_t wiced_bt_rfcomm_flow_control	(	uint16_t	handle,
		wiced_bool_t	enable
	)

This function directs a specified connection to pass flow control message to the peer device.

Enable flag passed shows if port can accept more data.

Parameters

[in]	handle	: The connection handle returned by wiced_bt_rfcomm_create_connection
[in]	enable	: Flow control setting TRUE Enable data flow FALSE Disable data flow

Returns

WICED_BT_RFCOMM_SUCCESS : If successful
WICED_BT_RFCOMM_BAD_HANDLE : If the handle is out of range
WICED_BT_RFCOMM_NOT_OPENED : If the connection is not opened

wiced_bt_rfcomm_set_rx_fifo()

wiced_bt_rfcomm_result_t wiced_bt_rfcomm_set_rx_fifo	(	uint16_t	handle,
		char *	p_mem,
		uint16_t	size
	)

This function provides RFCOMM with a data area to receive peer's data.

Parameters

[in]	handle	: The connection handle returned by wiced_bt_rfcomm_create_connection
[in]	p_mem	: Pointer to the fifo area
[in]	size	: Size of the fifo area

Returns

WICED_BT_RFCOMM_SUCCESS : If successful
WICED_BT_RFCOMM_BAD_HANDLE : If the handle is out of range
WICED_BT_RFCOMM_NOT_OPENED : If the connection is not opened

wiced_bt_rfcomm_read_data()

wiced_bt_rfcomm_result_t wiced_bt_rfcomm_read_data	(	uint16_t	handle,
		char *	p_data,
		uint16_t	max_len,
		uint16_t *	p_len
	)

This function reads the received application data from the peer device.

Parameters

[in]	handle	: The connection handle returned by wiced_bt_rfcomm_create_connection
[in]	p_data	: Where to read the data into
[in]	max_len	: Maximum Byte count to read
[out]	p_len	: Bytes actually read

Returns

WICED_BT_RFCOMM_SUCCESS : If successful
WICED_BT_RFCOMM_BAD_HANDLE : If the handle is out of range
WICED_BT_RFCOMM_NOT_OPENED : If the connection is not opened

wiced_bt_rfcomm_write_data()

wiced_bt_rfcomm_result_t wiced_bt_rfcomm_write_data	(	uint16_t	handle,
		char *	p_data,
		uint16_t	max_len
	)

This function sends the given application data to the peer device.

Note

the application shall pass a valid p_data buffer allocated on the heap or a global to this call. The buffer contents cannot be altered till a TX complete callback wiced_bt_port_tx_cback_t is received

Parameters

[in]	handle	: The connection handle returned by wiced_bt_rfcomm_create_connection
[in]	p_data	: Data to write
[in]	max_len	: Byte count to write

Returns

WICED_BT_RFCOMM_SUCCESS : If successful
WICED_BT_RFCOMM_BAD_HANDLE : If the handle is out of range
WICED_BT_RFCOMM_NOT_OPENED : If the connection is not opened

wiced_bt_rfcomm_check_connection()

wiced_bt_rfcomm_result_t wiced_bt_rfcomm_check_connection	(	uint16_t	handle,
		wiced_bt_device_address_t	bd_addr,
		uint16_t *	p_lcid
	)

This function checks connection referenced by handle is up and running.

Parameters

[in]	handle	: The connection handle returned by wiced_bt_rfcomm_create_connection
[out]	bd_addr	: Peer BD Address (see wiced_bt_device_address_t)
[out]	p_lcid	: L2CAP's LCID

Returns

WICED_BT_RFCOMM_SUCCESS : If successful
WICED_BT_RFCOMM_LINE_ERR : If connection is not up and running