XDK API  3.6.0
Documentation
Files | Data Structures | Macros | Typedefs | Enumerations | Functions
LeanB2CAP

LeanB2CAP API for CoSP. More...

+ Collaboration diagram for LeanB2CAP:

Files

file  BCDS_LeanB2CAP.h
 

Data Structures

struct  LeanB2CAP_FrameData_S
 Structure to represent any common data frames. More...
 
struct  LeanB2CAP_Overhead_S
 Structure to represent LeanB2CAP payload overhead (header and footer). More...
 
struct  LeanB2CAP_RawData_S
 Structure to represent the raw data for LeanB2CAP frame building. More...
 

Macros

#define LEANB2CAP_FOOTER_OVERHEAD   (1UL)
 
#define LEANB2CAP_HEADER_OVERHEAD   (5UL)
 

Typedefs

typedef enum
LeanB2CAP_CommandType_E 
LeanB2CAP_CommandType_T
 Type definition to represent the LeanB2CAP command type. More...
 
typedef enum LeanB2CAP_Event_E LeanB2CAP_Event_T
 Type definition to represent the LeanB2CAP event. More...
 
typedef struct
LeanB2CAP_FrameData_S 
LeanB2CAP_FrameData_T
 Type definition to represent any common data frames. More...
 
typedef struct
LeanB2CAP_HandleDescriptor_S * 
LeanB2CAP_HandlePtr_T
 Typedef for the LeanB2CAP handle. More...
 
typedef struct LeanB2CAP_Overhead_S LeanB2CAP_Overhead_T
 Type definition to represent LeanB2CAP payload overhead (header and footer). More...
 
typedef struct LeanB2CAP_RawData_S LeanB2CAP_RawData_T
 Type definition to represent the raw data for LeanB2CAP frame building. More...
 
typedef void(* LeanB2CAPCallback )(LeanB2CAP_Event_T Event, void *Data)
 This is the data type for the LeanB2CAP event callback function. More...
 

Enumerations

enum  LeanB2CAP_CommandType_E
 
enum  LeanB2CAP_Event_E
 Enum to represent the LeanB2CAP events. More...
 

Functions

Retcode_T LeanB2CAP_Builder (LeanB2CAP_FrameData_T *LeanB2CAPBuildOuput, LeanB2CAP_RawData_T *RawDataInput)
 Builds the LeanB2CAP payload. More...
 
Retcode_T LeanB2CAP_Deinitialize (LeanB2CAP_HandlePtr_T *Handle)
 Deinitializes an LeanB2CAP instance. More...
 
Retcode_T LeanB2CAP_Initialize (LeanB2CAP_HandlePtr_T *Handle, LeanB2CAP_FrameData_T *ValidOutputDataStorageBufferInfo, LeanB2CAPCallback Callback)
 Initializes an LeanB2CAP instance. More...
 
Retcode_T LeanB2CAP_OverheadBuilder (LeanB2CAP_Overhead_T *OutputOverhead, LeanB2CAP_RawData_T *RawDataInput)
 Builds the LeanB2CAP payload overhead (header and footer). More...
 
Retcode_T LeanB2CAP_ResetRxDataProcessor (LeanB2CAP_HandlePtr_T *Handle)
 Resets the LeanB2CAP received data process informations. More...
 
Retcode_T LeanB2CAP_RxDataProcessor (LeanB2CAP_HandlePtr_T *Handle, LeanB2CAP_FrameData_T *PayLoad)
 Handles the LeanB2CAP received data processing. More...
 

Detailed Description

The LeanB2CAP is a binary framing protocol to transmit payload data over a serial transport layer. The protocol is mainly designed to be used together with stateless Client - Server architectures.

The goal for the serial transport layer is to find bit errors and to be able to resend corrupted frames. To achieve this goal LeanB2CAP has the following frame classifications.

Start Delimiter Length Command Type Check Sum 1 Payload Check Sum 2
1 byte 2 bytes 1 byte 1 byte 1 - 65533 bytes 1 byte

The LeanB2CAP frame format is explained below.

Start Delimiter is an unique byte identifying the start of a new LeanB2CAP frame. The fixed value is 0x55.

Length indicates the number of bytes to follow. It includes the sum of the following. Length of Command Type Length of Check Sum 1 Length of Payload Length of Check Sum 2

Command Type is any one of the protocol supported commands. It is used to categorise and handle a mixture of important / unimportant data packets.

Check Sum 1 is 8-bit CRC (polynomial value - 2) of the the following. Start Delimiter Length Command Type

Payload is the actual data to be sent across the serial transport layer. It must be at-least a byte long. And a maximum of 65533 bytes.

Check Sum 2 is 8-bit CRC (polynomial value - 2) of the the following. Check Sum 1 Payload

A typical use of these API set would start with initializing the LeanB2CAP instance. Then, a frame can be build to be sent in the serial line using the builder. The received data's shall be sent to the receive processor to trigger events based on data integrity.

void LeanB2CAP_EventCallback(LeanB2CAP_Event_T Event, void * Data)
{
switch(Event)
{
LeanB2CAP_RawData_T * PayloadInfo = (LeanB2CAP_RawData_T *) Data;
// Payload information is available in PayloadInfo
break;
Retcode_T * ErrorInfo = (Retcode_T *) Data;
// Error information is available in ErrorInfo
break;
// ...
}
}
void LeanB2CAP_UsageExample()
{
LeanB2CAP_HandlePtr_T LeanB2CAPHandle;
// Lean B2CAP handle instantiation
Rc = LeanB2CAP_Initialize(&LeanB2CAPHandle, &LeanB2CAPEventCallback);
// Lean B2CAP data serialization
RawData.DataPointer = PtrToDataForSerialization;
RawData.DataSize = LengthOfDataToSerialization;
OutputData.FrameDataPointer = LeanB2CAPTransmitBuffer;
Rc = LeanB2CAP_Builder(&RawData,&OutputData);
UartSend(OutputData.FrameDataPointer, OutputData.FrameDataSize);
// Lean B2CAP data reception
FrameData.FrameDataPointer = &LeanB2CAPReceiveBuffer;
FrameData.FrameDataSize = UartReceive(LeanB2CAPReceiveBuffer, LEAN_B2CAP_RX_BUFFER_LEN);
// This would internally call the Lean B2CAP Event callback function
LeanB2CAP_RxDataProcessor(&LeanB2CAPHandle,&FrameData);
}

Data Structure Documentation

struct LeanB2CAP_FrameData_S

Data Fields

uint8_t * FrameDataPointer
 
uint16_t FrameDataSize
 

Field Documentation

uint8_t* FrameDataPointer

Frame data start pointer

uint16_t FrameDataSize

Frame data start size

struct LeanB2CAP_Overhead_S

Data Fields

uint16_t FooterLength
 
uint8_t * FooterPointer
 
uint16_t HeaderLength
 
uint8_t * HeaderPointer
 

Field Documentation

uint16_t FooterLength

Footer data length

uint8_t* FooterPointer

Pointer to the footer data

uint16_t HeaderLength

Header data length

uint8_t* HeaderPointer

Pointer to the header data

struct LeanB2CAP_RawData_S

Data Fields

LeanB2CAP_CommandType_T CommandType
 
uint8_t * DataPointer
 
uint16_t DataSize
 

Field Documentation

Command type

uint8_t* DataPointer

Pointer to the data start point

uint16_t DataSize

size of the data

Macro Definition Documentation

#define LEANB2CAP_FOOTER_OVERHEAD   (1UL)

LeanB2CAP footer size

#define LEANB2CAP_HEADER_OVERHEAD   (5UL)

LeanB2CAP header size

Typedef Documentation

typedef struct LeanB2CAP_HandleDescriptor_S* LeanB2CAP_HandlePtr_T

The actual handle context informations are hidden from the interface user.

typedef void(* LeanB2CAPCallback)(LeanB2CAP_Event_T Event, void *Data)

The callback is registered at the initialization. It is invoked by the LeanB2CAP received data processing API to notify the application about any LeanB2CAP events.

Parameters
[in]EventThe event information.
[in]DataThe data based on the event. This shall be cast to appropriate data type to retrieve valid information.
Note
Below are the Event to corresponding Data cast mapping.
Event Data
LEAN_B2CAP_EVENT_FRAME_RX_COMPLETE LeanB2CAP_RawData_T
LEAN_B2CAP_EVENT_FRAME_RX_ERROR Retcode_T
See also
LeanB2CAP_Event_E, LeanB2CAP_FrameData_S, Retcode_T, Utils_Retcode_E

Enumeration Type Documentation

Enumerator
LEAN_B2CAP_CMD_READ 

Enum to represent the LeanB2CAP command types.

Read command.

LEAN_B2CAP_CMD_READ_LONG 

Long read command.

LEAN_B2CAP_CMD_WRITE 

Write command.

LEAN_B2CAP_CMD_WRITE_WITH_CONFIRMATION 

Write with confirmation command.

LEAN_B2CAP_CMD_WRITE_LONG 

Long write command.

LEAN_B2CAP_CMD_WRITE_LONG_WITH_CONFIRMATION 

Long write with confirmation command.

LEAN_B2CAP_CMD_CONFIRMATION 

Confirmation command.

LEAN_B2CAP_CMD_INFO_CHANNEL0 

Information command from Channel 0.

LEAN_B2CAP_CMD_INFO_CHANNEL1 

Information command from Channel 1.

LEAN_B2CAP_CMD_INFO_CHANNEL2 

Information command from Channel 2.

LEAN_B2CAP_CMD_INFO_CHANNEL3 

Information command from Channel 3.

Enumerator
LEAN_B2CAP_EVENT_FRAME_RX_COMPLETE 

A valid LeanB2CAP frame is received

LEAN_B2CAP_EVENT_FRAME_RX_ERROR 

An invalid LeanB2CAP frame is encountered

Function Documentation

Retcode_T LeanB2CAP_Builder ( LeanB2CAP_FrameData_T LeanB2CAPBuildOuput,
LeanB2CAP_RawData_T RawDataInput 
)
Note
This is completely independent of the handle. Also, the input and output data buffers must be provided by the interface user.
Parameters
[in,out]LeanB2CAPBuildOuputLeanB2CAP payload that is built based on the input data information. Internally the output buffer size is validated against the input payload based on Lean B2CAP overhead.
[in]RawDataInputThe input data information based on which the resultant LeanB2CAP payload is to be built.
Return values
RETCODE_OKif successful
RETCODE_FAILUREif internal CRC calculation failed
RETCODE_LEANB2CAP_CMD_TYPE_ERRORif invalid command type was provided
RETCODE_LEANB2CAP_LENGTH_ERRORif invalid length was provided
RETCODE_NULL_POINTERNULL has been passed instead of a valid input / output payload pointer
Retcode_T LeanB2CAP_Deinitialize ( LeanB2CAP_HandlePtr_T Handle)
Note
The handle must be initialized prior to this by making use of the LeanB2CAP_Initialize API.
Parameters
[in]HandleLeanB2CAP handle.
Return values
RETCODE_OKif successful
RETCODE_INVALID_PARAMif Unknown Handle is passed instead of a valid Handle
RETCODE_NULL_POINTERNULL has been passed instead of a valid Handle
Retcode_T LeanB2CAP_Initialize ( LeanB2CAP_HandlePtr_T Handle,
LeanB2CAP_FrameData_T ValidOutputDataStorageBufferInfo,
LeanB2CAPCallback  Callback 
)
Parameters
[out]HandleLeanB2CAP handle. Use a void pointer to save the handle context address as the Handle descriptor is hidden from the user. this shall be used for further reference.
[in]ValidOutputDataStorageBufferInfoValid output data/payload storage buffer information. Must not be NULL.
[in]CallbackCallback to intimate any LeanB2CAP Receive Process event. Must not be NULL.
Return values
RETCODE_OKif successful
RETCODE_OUT_OF_RESOURCESif no free handle is available
RETCODE_NULL_POINTERif NULL has been passed instead of a valid Callback
Retcode_T LeanB2CAP_OverheadBuilder ( LeanB2CAP_Overhead_T OutputOverhead,
LeanB2CAP_RawData_T RawDataInput 
)
Note
This is completely independent of the handle. Also, the input and output data buffers must be provided by the interface user.
Parameters
in/out]OutputOverhead LeanB2CAP overhead that is created based on the input data information. The HeaderPointer pointer must point to buffer of size equalent to atleast LEANB2CAP_HEADER_OVERHEAD. Similarly, the FooterPointer pointer must point to buffer of size equalent to atleast LEANB2CAP_FOOTER_OVERHEAD.
[in]RawDataInputThe input data information based on which the resultant LeanB2CAP payload is to be built.
Return values
RETCODE_OKif successful
RETCODE_FAILUREif internal CRC calculation failed
RETCODE_LEANB2CAP_CMD_TYPE_ERRORif invalid command type was provided
RETCODE_NULL_POINTERNULL has been passed instead of a valid input / output payload pointer
RETCODE_INVALID_PARAMif invalid output buffer sizes or unsupported raw data length is provided
Retcode_T LeanB2CAP_ResetRxDataProcessor ( LeanB2CAP_HandlePtr_T Handle)
Note
The handle must be initialized prior to this by making use of the LeanB2CAP_Initialize API.
Parameters
[in]HandleLeanB2CAP handle.
Return values
RETCODE_OKif successful
RETCODE_INVALID_PARAMif Unknown Handle is passed instead of a valid Handle
RETCODE_NULL_POINTERNULL has been passed instead of a valid Handle
Retcode_T LeanB2CAP_RxDataProcessor ( LeanB2CAP_HandlePtr_T Handle,
LeanB2CAP_FrameData_T PayLoad 
)

The processed data results are intimated to the user in the same processing context via the registered callback.

Note
The handle must be initialized prior to this by making use of the LeanB2CAP_Initialize API.
Parameters
[in]HandleLeanB2CAP handle.
[in]PayLoadPayload information consisting of the received serial line data pointer and its size.
Return values
RETCODE_OKif successful
RETCODE_LEANB2CAP_RX_PROCESSOR_FAILunknown/un-handled application logic was encountered
RETCODE_FAILUREif internal CRC calculation failed in the last byte processed
RETCODE_LEANB2CAP_SD_ERRORif invalid start delimiter error was encountered in the last byte processed
RETCODE_LEANB2CAP_LENGTH_ERRORif invalid length was encountered in the last byte processed
RETCODE_LEANB2CAP_CMD_TYPE_ERRORif invalid command type was encountered in the last byte processed
RETCODE_LEANB2CAP_CRC_ERRORif invalid CRC was encountered in the last byte processed
RETCODE_LEANB2CAP_FRAME_ERRORunknown/un-handled frame state was encountered
RETCODE_LEANB2CAP_INVALID_CALLBACKCallback for Lean B2CAP is NULL
RETCODE_INVALID_PARAMif Unknown Handle is passed instead of a valid Handle
RETCODE_NULL_POINTERNULL has been passed instead of a valid Handle

All rights reserved. The use is subject to the XDK SDK EULA by Bosch Connected Devices and Solutions GmbH.
This documentation file has been automatically generated on Thu Mar 14 2019 19:12:52 by doxygen 1.8.8