Sending SCOM packets

Once the SCOM protocol is running, it is possible to schedule sending of SCOM packets. The SCOM API provides several ways to do that.

Sending single-frames

If the required packet payload is small enough to fit into a single frame (see SCOM_MAX_DATA_LENGTH) then the easiest way to send a packet is to call the SCOM_SendFrame function:

// schedules sending of a packet with priority=3, type=17 and 5 bytes of payload - "hello"
if (SCOM_RESULT_OK != SCOM_SendFrame(&mySCOM, 3, 17, "hello", 5)) {
    // unable to send this packet - frame buffer full?
}

Calling the SCOM_SendFrame does not automatically send the frame. Instead it buffers it in the frame buffer and it is the SCOM_Proc responsibility do decide which of the buffered packets will be send next, based on the priority - thus the result of SCOM_SendFrame does not reflect the status of actual sending process.

Sending single-frames using pre-allocation

Sometimes it is more convenient to access the internal payload buffer of the frame, for easier completion of the payload, instead of building such structure and then passing it to SCOM_SendFrame. To achieve that it is possible to first allocate an SCOM frame and then complete it and send it.

The SCOM_AllocFrame allocates a frame in the frame buffer and returns a pointer to SCOMFrame structure:

SCOMFrame* myFrame;
if (SCOM_RESULT_OK != SCOM_AllocFrame(&mySCOM, &myFrame)) {
    // unable to allocate packet
}

This structure can be then used to build the frame and complete it's payload:

SCOMFrame_SetType(myFrame, 17);
SCOMFrame_SetPriority(myFrame, 3);
memcpy(SCOMFrame_GetPayloadPtr(myFrame), "hello", 5);
SCOMFrame_SetPayloadSize(myFrame, 5);

Once the frame is ready, it can be sent using SCOM_SendAllocatedFrame :

// schedules sending of a pre-allocated packet
if (SCOM_RESULT_OK != SCOM_SendAllocatedFrame(&mySCOM, myFrame)) {
    // unable to send this packet
}

Sending multi-frames

The multi-frame mechanism provides an easy way for fragmentation of larger payloads across multiple SCOM frames. The API provides a special function for sending multi-frames: SCOM_SendMultiFrame. Apart from standard SCOM frame description, this function also requires a pointer to a SCOMMultiFrameDesc structure that describes the whole large payload transfer. Each call to SCOM_SendMultiFrame sends a single SCOM frame with sequential parts of the payload, and updates the transfer descriptor. Below is an exemplary usage

// this is what we want to send
uint8_t bigPayload[1024];

// declaration of a multi-frame descriptor, that will hold information about the whole transfer
SCOMMultiFrameDesc multiDesc = {0, 0};

// the following loop will send each part of the multi-frame
while(multiDesc.progress < sizeof(bigPayload)) {

    // send another part of a mult-frame, with priority = 1 and type = 2
    if (SCOM_RESULT_OK != SCOM_SendMultiFrame(&&mySCOM, 1, 2, bigPayload, sizeof(bigPayload), &multiDesc)) {
        // Unable to send a part of the multi-frame. This may happen in ex. because the transmission frame
        // buffer is full. If this happens, we can wait until there is a space in the transmission frame
        // buffer and pick up from where we stopped.
    }

}

Sending service frames

In order to support service frames, a convenient function SCOM_SendServiceFrame is provided in the API. Here's the exemplary usage:

// schedules sending of a packet with priority=1, serviceId=230, primitiveId=12 and 5 bytes of payload - "hello"
if (SCOM_RESULT_OK != SCOM_SendServiceFrame(&mySCOM, 1, 230, 12, "hello", 5));
    // unable to send this packet - frame buffer full?
}