CreateSingleIdReceiver (FUN)¶

FUNCTION CreateSingleIdReceiver : CAA.HANDLE

This function creates a receiver for one specific CAN identifier. For receiving a message use the returned receiver handle for Read function call. There are two kind of receivers:

Always Newest Receivers (xAlwaysNewest := TRUE): Receiver holds only the last received message.
Receiver with Queue (xAlwaysNewest := FALSE): Receiver holds messages in chronological order.

Receivers can be also used for Tx loopback. If xTransmit is set to TRUE CAN messages which are sent via Write will be received (applies to all transmit messages on the CAN interface). Use function IsTransmitMessage to distinguish between receive and transmit messages.

Note

To avoid losing receive messages an application has to read all messages of a receiver each cycle. All messages should be processed and released by FreeMessage afterwards.

Example

In this example a single ID receiver is created. It receives all RTR messages on CAN ID 16#100.

VAR
  hDriver : CAA.HANDLE;
  hReceiver : CAA.HANDLE;
  hMsg : CAA.HANDLE;
  pData : POINTER TO CL2I.DATA;
  eError : CL2.ERROR;
  ctMsgLeft : CAA.COUNT;
END_VAR

hReceiver := CL2.CreateSingleIdReceiver(hDriver := hDriver,
                                        cobId := 16#100,
                                        xRTR := TRUE,
                                        x29BitId := FALSE,
                                        xTransmit := FALSE,
                                        xAlwaysNewest := FALSE,
                                        eEvent := CB.EVENT.NO_EVENT, //no receive event
                                        xEnableSyncWindow := FALSE, //not implemented
                                        peError := ADR(eError) //optional pointer to error
);

REPEAT
    //receive a message from hReceiver
    hMsg := CL2.Read(hReceiverId := hReceiver, pctMsgLeft := ADR(ctMsgLeft), peError := ADR(eError));
    IF hMsg <> CAA.gc_hINVALID THEN
        //TODO: Process message (CL2.GetMessageDataPointer, CL2.GetMessageId, ...)
        CL2.FreeMessage(hMsg); //release message
        hMsg := CAA.gc_hINVALID; //to avoid using an already released message
    END_IF
UNTIL ctMsgLeft = 0
END_REPEAT

Optionally, an event can be registered which is triggered upon reception of a corresponding message. A callback function can be registerd via CB.RegisterCallback (CAA Callback library). Use event class CB.EVENT_CLASS.FIELDBUS, event source CB.EVENT_SOURCE.CB_DRIVER and any unassigned event number (see CB.EVENT). Use the same event number for eEvent input. Input variable dwParam of the registered callback function contains the CAN ID of the received message.

Note

Event mechanism is not supported on all systems. Futhermore it is not possible to register an event for extended identifiers (29bit).

Example

In this example a single ID receiver with event callback is created.

Step 1: Define a callback function with following interface (function name can be changed!).

FUNCTION CallbackReceiveCANMessage : DWORD
VAR_INPUT
  dwSpec  : DWORD;  (* CB.Event and CB.EventClass *)
  dwSource : DWORD; (* CB.EventSource *)
  dwParam : DWORD;  (* CAN ID *)
END_VAR

Step 2: Activate Enable system call in build settings of CallbackReceiveCANMessage.

Step 3: Register callback and create receiver.

VAR
  hDriver : CAA.HANDLE;
  hReceiver : CAA.HANDLE;
  eError : CL2.ERROR;
  callback : CB.CB_CALLBACK;
  hEvent : CAA.HANDLE;
  eCBError : CB.ERROR;
END_VAR

callBack.eClass := CB.EVENT_CLASS.FIELDBUS;
callback.eSource := CB.EVENT_SOURCE.DRIVER;
callback.eEvent := 10000; //any unassigned event number
callback.pPOUFunc := ADR(CallbackReceiveCANMessage);

hEvent := CB.RegisterCallback(callback, ADR(eCBError));

hReceiver := CL2.CreateSingleIdReceiver(hDriver := hDriver,
                                        cobId := 16#100,
                                        xRTR := FALSE,
                                        x29BitId := FALSE,
                                        xTransmit := FALSE,
                                        xAlwaysNewest := FALSE,
                                        eEvent := 10000, //use the previously registered event number
                                        xEnableSyncWindow := FALSE, //not implemented
                                        peError := ADR(eError) //optional pointer to error
);

InOut:

Scope	Name	Type	Comment
Return	`CreateSingleIdReceiver`	`CAA.HANDLE`	new receiver handle or `CAA.gc_hINVALID` in case of failure
Input	`hDriver`	`CAA.HANDLE`	handle of CAN interface
	`cobId`	`CL2I.COBID`	id of message to be received
	`xRTR`	`BOOL`	`TRUE`: receive RTR messages, `FALSE`: receive no RTR messages
	`x29BitId`	`BOOL`	`TRUE`: receive 29 Bit Ids, `FALSE`: receive 11 Bid Ids
	`xTransmit`	`BOOL`	`TRUE`: receive Tx messages, `FALSE`: receive Rx messages
	`xAlwaysNewest`	`BOOL`	`TRUE`: returns only the newest message; `FALSE`: receiver with queue.
	`eEvent`	`CB.EVENT`	trigger event when message received
	`xEnableSyncWindow`	`BOOL`	use SYNC window: not implemented ==> do not care
	`peError`	POINTER TO ERROR	optional pointer to error enum