Initializing SCOM connection

The SCOM descriptor

The SCOMDataLinkDesc structure holds a complete description of an SCOM protocol instance. Most SCOM API calls require a pointer to this structure as an argument. The SCOM descriptor can be simply declared by the user:

SCOMDataLinkDesc mySCOM;

In environments where heap memory is available, it can also be created dynamically using SCOM_Create, and possibly freed after usage using SCOM_Destroy.

Frame buffer

SCOM instance requires a frame buffer. The frame buffer is a structure, that internally maintains a space for SCOM packets that are transmitted and received. The SCOM API provides two types of frame buffers:

• static frame buffer, meaning that the memory pool for packets is declared at compile time and is constant
• dynamic frame buffer, that uses heap memory each time a space for packet is needed

In order to declare a static SCOM frame buffer, the SCOM_DECLARE_FRAME_BUFFER macro can be used:

// declare frame buffer that fits 5 outgoing packets and 10 incoming packets
SCOM_DECLARE_FRAME_BUFFER(myFrameBuffer, 5, 10);

To declare a dynamic SCOM frame buffer, the SCOM_DECLARE_FRAME_BUFFER_USING_HEAP macro can be used:

// declare frame buffer that uses heap
SCOM_DECLARE_FRAME_BUFFER_USING_HEAP(myFrameBuffer);

It is also possible to create the frame buffer using SCOM API call SCOM_CreateFrameBuffer and later destroy it using SCOM_DestroyFrameBuffer.

The frame buffer is used during SCOM connection initialization.

Timing

The SCOM protocol is a real-time tool, meaning that it requires timing operation in order to behave correctly. During initialization, the user provides a timing function, that is internally called by the SCOM functions to get information about current time. This function should return a monotonic, stable clock. A good example would be a function returning the count of milliseconds elapsed since the system started.

Initializing the SCOM connection.

The SCOM_Init function initializes the given SCOM protocol instance, preparing it for operation. Several arguments are required to successfully set up the protocol:

• iodevice - the IODevice instance representing the serial port, over which the protocol should operate
• frameBuffer - the frame buffer that is used to handle incoming and outgoing SCOM packets (see description above)
• clockSource - the function that provides time information
• ackTimeout - amount of time waiting for the acknowledgment of a packet
• deviceClass - SCOM device class identifier
• deviceUID - SCOM unique device identifier
• numberOfServices - number of services supported by the SCOM instance
• serviceIDs - array of supported service identifiers

The following example illustrates how to initialize the connection:

// declare the connection structure
SCOMDataLinkDesc mySCOM;

// declare frame buffer
SCOM_DECLARE_FRAME_BUFFER(myFrameBuffer, 5, 10);

uint8_t uid[8] = { 0x00,0x11,0x22,0x33,0x44,0x55,0x66,0x77 };

// initialize the connection over USART1 IODevice
SCOM_Init(&mySCOM, USART1, &myFrameBuffer, OS_GetSystemTime, 200, 0x10002000, uid, 0, NULL);

Deinitializing the SCOM connection.

When done with the protocol, simply call SCOM_Deinit to deinitialize the connection instance and free up all allocated resources.

Retrieving IODevice associated with the SCOM connection.

The SCOM_GetIODevice function allows to retrieve at any time the IODevice associated with the given SCOM connection object.