The interface that a specific dongle-type source code module exposes to the generic IrFramer (through the function pointer table in OEMDONGLE.C) can have three functions:
| Function | Description |
|---|---|
| type_Init | Initializes your IR hardware and returns the capabilities mask. |
| type_SetSpeed | Sets the send and receive speed of your IR hardware and sets VCOMM to handle that speed. |
| type_Deinit | Powers down or deinitializes your IR hardware. |
A number of functions are available to the OEMDONGL.C module. You have the option of using the VCOMM functions directly and/or indirectly through the functions listed in the following. It is strongly recommended that you not use the VCOMM functions directly for two-way communication with the dongle. Use the provided functions wherever applicable. The function prototypes are in _DONGLE.H and are shown in the following:
//************************************************************************
//
// Function prototypes of utility functions that should be used by
// dongle functions.
// IrLapFrmSetSpeed will set the speed of the UART to the given speed
// using VCOMM calls.
BOOL IrLapFrmSetSpeed(U32 hCom, LM_BAUD_RATE speed);
// IrLapFrmReadChar is used to read a character from the UART using VCOMM calls
// It assumes that events are turned off so it polls. If no character is read in
// in 12 ms it will return FALSE. If a VCOMM error occurs it will return false.
// If it returns TRUE the character read is placed in the variable pointed to by
// c.
BOOL IrLapFrmReadChar(U32 hCom, PU8 c);
// IrLapFrmWriteChar is used to write a character to the UART using VCOMM calls.
// It returns TRUE if successful otherwise it returns FALSE.
BOOL IrLapFrmWriteChar(U32 hCom, U8 c);
// VMM_GetSystemTime returns the number of milliseconds since Windows started. It is
// accurate to 1ms. This is the standard VMM call.
UINT VMM_GetSystemTime( VOID );
The type_Init function is called by the framer to initialize your IR hardware and to get the dongle capabilities masks. When type_Init is called, the hCom (VCOMM handle) will be set for 9600 baud, 8 data bits, no parity, and 1 stop bit. When type_Init returns, the dongle must be active and ready to receive and send data and the VCOMM handle must be set to 9600 baud, 8 data bits, no parity, and 1 stop bit.
If the dongle cannot be initialized type_Init must return IRDA_STATUS_FAILED.
The syntax of the function call is:
BOOL type_Init(
U32 hCom,
PDONGLE_CAPABILITIES cap
)
type_Init assumes
The cap parameter points to the DONGLE_CAPABILITIES structure that type_Init returns to the framer; type_Init can, as an option, set bits in the masks that make up this structure to register Baud Rate, Minimum Turn Around Time, and Number of BOFs capabilities with the framer.
The DONGLE_CAPABILITIES structure is defined in _DONGLE.H and is shown in the following:
// DONGLE_CAPABILITIES - is a structure that contains the IrDA
// capabilities a dongle can effect. The order of the elements in
// this structure must be the same as those in the IRLAPFRM_CAPABILITIES
// structure.
typedef struct
{
U32 supportedSpeeds; // Supported speeds of the dongle
U32 minTurnAroundTime; // Min turn around time on the dongle
U32 additionalBOFs; // Additional BOFs required by the dongle.
} DONGLE_CAPABILITIES, *PDONGLE_CAPABILITES;
The meaning of the pattern of bit settings in the three capabilities bit masks is defined fully in Infrared Data Association Serial Infrared Link Access Protocol (IrLAP), but summary tables are presented here.
The bit settings in the baud rate mask indicate the speed(s) at which the IR device can transmit over the data link:
| bit 0 = | 2400 bps (LSB, transmitted first) |
| bit 1 = | 9600 bps |
| bit 2 = | 19200 bps |
| bit 3 = | 38400 bps |
| bit 4 = | 57600 bps |
| bit 5 = | 115200 bps |
| bit 6 = | reserved and must be set to 0 |
| bit 7 = | reserved and must be set to 0 |
Minimum turn around time is the time delay required by the IR device from the time it receives the last byte from one device until it is ready to receive the first byte from another device.
| bit 0 = | 10 ms (LSB, transmitted first) |
| bit 1 = | 5 ms |
| bit 2 = | 1 ms |
| bit 3 = | 0.5 ms |
| bit 4 = | 0.1 ms |
| bit 5 = | 0.05 ms |
| bit 6 = | 0.01 ms |
| bit 7 = | 0.005 ms |
These bit settings indicate the number of additional flags needed at the beginning of every frame to provide a delay at the beginning of each frame for devices with long interrupt latency. The bit settings in this mask depend on the baud rate. See Infrared Data Association Serial Infrared Link Access Protocol (IrLAP) for all the different possible values.
The following shows an example of adapting the OEMDONGLE.C sample source code function OEM_Init. The supportedSpeeds mask is set to support all speeds between 9600 baud and 115.2 baud and is set for a 1 ms turnaround, using the following code:
#define CRYSTAL_SPEEDMASK 0x3F /*supported speeds 115.2Kbps->9600 Kbps*/
#define CRYSTAL_MINTURN 0x00 /*0 turn around*/
.
.
.
//*********************************************************************
BOOL OEM_Init(U32 hCom, PDONGLE_CAPABILITIES cap)
{
.
.
.
cap->supportedSpeeds &= CRYSTAL_SPEEDMASK;
.
.
.
}
Suppose your RED88 dongle only supports 9600, 19200, and 115200 baud. You can change the supportedSpeeds mask to reflect that by changing two lines of the sample code:
#define RED88_SPEEDMASK 0x00000026
.
.
.
cap->supportedSpeeds &= RED88_SPEEDMASK;
.
.
.
The type_SetSpeed function is called by the framer IRLAPFRM_SetSpeed function to set the send and receive speed of your IR hardware. type_SetSpeed must also set VCOMM to handle the new speed because IRLAPFRM_SetSpeed does not do that.
The syntax of the type_SetSpeed function call is:
BOOL type_SetSpeed(
U32 hCom,
LM_BAUD_RATE speed
)
type_SetSpeed can send and receive characters with no interference from the IR framer because IRLAPFRM_SetSpeed disables VCOMM event callbacks before it calls type_SetSpeed.
type_SetSpeed can also assume that the framer will not reset the VCOMM speed setting. Therefore, when type_SetSpeed is called, the VCOMM speed setting is either the same as the last time type_SetSpeed set it, or 9600 baud immediately after a call to type_Init.
When type_SetSpeed returns, the framer assumes it can start sending or receiving data at the new speed and restores the VCOMM event callbacks. If it fails to set the IR device speed or the VCOMM speed setting, type_SetSpeed must return IRDA_STATUS_FAILED.
It is not particularly useful to make up an example here for the hypothetical RED88 dongle device. The convention that notifies each particular dongle device of a speed change differs from device to device. Two things to notice about the sample code, however, are:
The type_Deinit function is called to power down or otherwise deactivate your hardware. It is called by the framer just before it calls VCOMM_CloseComm to close the port.
The type_Deinit function can send and receive characters with no interference from the IR framer because VCOMM event callbacks are disabled before the call to the dongle function.
The syntax of the type_Deinit function call is:
BOOL type_Deinit(
U32 hCom
)
The OEM_Deinit function in OEMDONGL.C (which uses the Crystal chip in the ACTiSYS 200L as an IR device) does the following: