User’s Manual

EMMA2 API

Infrared Receiver Interface (IR)

CONTENTS

1 Introduction ....................................................................................................................... 2
1.1 Example Source Code.......................................................................................... 4
2 Function Prototypes .......................................................................................................... 5
MMAC_IR_Initialise ......................................................................................................5
MMAC_IR_Open...........................................................................................................6
MMAC_IR_Close ..........................................................................................................7
MMAC_IR_Read ...........................................................................................................8
3 Data Structures ................................................................................................................. 9
4 Revision History .............................................................................................................. 10

Book No: S16753EE1V0UM00 Doc No: MMAC0026, Issue: 1.2

© NEC Electronics Corporation 2002 ~ 2004 Publication Date: 2004-02-18
The information is this document is subject to change without notice – it is
the reader’s responsibility to check that this is the latest available version.

This document includes company confidential information. It should only be

released to third parties under a Non-Disclosure Agreement.
1 Introduction
This section defines the Infra Red (IR) API, which provides an interface for a Remote Control Unit (RCU)
IR receiver connected to one of the EMMA2 Capture And Compare Timer (CAPCOM) inputs.
The API is initialised by calling MMAC_IR_Initialise(). It is then opened by calling MMAC_IR_Open()
It can be closed by a call to MMAC_IR_Close().
Once the API is initialised and opened any RCU key press which is successfully received and matches the
MMAC_IR_SYS_ADDRESS will be stored in a FIFO and a call is made to the callback function. It should
be noted that the callback will be performed from the LISR context, so the user should take appropriate
precautions.
The key presses in the FIFO can be retrieved by calling MMAC_IR_Read(). This returns a structure of
type MMAC_IR_READ_DATA.
The current version of the IR API implements only the RC5 protocol, but can be used as a reference to
modify for other RCU protocols.

Functions
The IR API provides the following functions:
Function Name Description
MMAC_IR_Initialise Initialises the API
MMAC_IR_Open Opens the API
MMAC_IR_Close Closes the API
MMAC_IR_Read Retrieves an RCU key press from the FIFO

Return Codes
The meanings of the various result codes returned by the API are described in the following table:
Result Code Description
MMAC_IR_OK An operation has successfully completed.
MMAC_IR_FAIL An operation has failed.
MMAC_IR_NOT_INITIALISED The IR API has not been initialised.
MMAC_IR_ALREADY_INITIALISED The IR API has already been initialised.
MMAC_IR_INVALID_PARAM An invalid parameter was passed to the IR API
MMAC_IR_ALREADY_OPEN The IR API is already open
MMAC_IR_NO_DATA The FIFO is empty.

Includes
In order to use this API, the following header files must be included, in the following order:
#include “mmac/types.h”
#include “mmac/rtos.h”
#include “mmac/mmac_config.h”
#include “mmac/ir.h”

2
Initialisations
Prior to using any functions of the IR API, the following functions must be called:
MMAC_RTOS_Initialise()
MMAC_CAPCOM_Initialise()

API Configuration
A number of configurable options, in the form of “#define”s are defined in the IR section of the
mmac\config\api.h source file clearly marked by the comment:

/****************************************************************/
/* */
/* MMAC IR SETUP */
/* */
/****************************************************************/

These options are:

Define Default Meaning
MMAC_IR_SYS_ADDR 0 Specifies the system address of the
RCU.
MMAC_IR_PROTOCOL_RC_5 MMAC_YES Specifies that the IR driver implements
the RC5 protocol.
MMAC_IR_FIFO_SIZE 100 Maximum number of consecutive RCU
codes that can be buffered
MMAC_IR_CAPCOM_TIMER MMAC_CAPCOM_0 The CAPCOM input to use for IR.
MMAC_IR_PARAMETER_CHECKING MMAC_YES Enables API level parameter checking.

3
1.1 Example Source Code

void main( void )

{
MMAC_CAPCOM_Initialise();
MMAC_IR_Initialise();
MMAC_IR_Open(&RCU_KeyPressCallback);
}
void RCU_KeyPressCallback ( void )
{ signal to RCU_TASK }
static void RCU_TASK (UI32 argc, void *argv)
{
MMAC_IR_READ_DATA irReadData;
suspend untill signalled from RCU_KeyPressedCallback ...
while (MMAC_IR_Read(&irReadData) == MMAC_IR_OK)
{
if ([Link] == MMAC_IR_STATUS_OK)
{
/* process the key message */
switch ([Link])
{
case MMAC_IR_KEY_PRESSED:
MMAC_DEBUG_Print( MMAC_DEBUG_MSG,
” New Key : %d \r\n”,
[Link]);
break;
case MMAC_IR_KEY_REPEAT:
MMAC_DEBUG_Print( MMAC_DEBUG_MSG,
”Key Repeat : %d \r\n”
[Link]);
break;
default:
MMAC_DEBUG_Print(
MMAC_DEBUG_MSG,”ERROR\r\n”);
break;
}
}
}
}

4
2 Function Prototypes

MMAC_IR_Initialise

Function Prototype
MMAC_IR_RESULT_CODE MMAC_IR_Initialise ( void );

Inputs
None.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_IR_OK
MMAC_IR_FAIL
MMAC_IR_ALREADY_INITIALISED

Description
Configures the IR API ready for use and allocates any resources necessary.
If parameter checking is enabled and the API has already been initialised, the result code
MMAC_IR_ALREADY_INITIALISED is returned and no action is performed.
If the initialisation process fails for any other reason, MMAC_IR_FAIL is returned.
If the subsystem is successfully initialised the code MMAC_IR_OK will be returned.

See Also
MMAC_IR_Open
MMAC_IR_Close

Sample Code
See section 1.1, Example Source Code.

5
MMAC_IR_Open

Function Prototype
MMAC_IR_RESULT_CODE MMAC_IR_Open (
MMAC_IR_CALLBACK callback
);

Inputs
callback Specifies the function to call when a new valid transmission from the RCU is
decoded

Outputs
None

Event Notification
N/A

Return Codes
MMAC_IR_OK
MMAC_IR_FAIL
MMAC_IR_NOT_INITIALISED
MMAC_IR_INVALID_PARAMETER

Description
This function opens the IR API. It configures the CAPCOM API.
If parameter checking is enabled and the API has not yet been initialised, the function will return the value
MMAC_IR_NOT_INITIALISED without performing any action.
If parameter checking is enabled and callback is NULL, the function will return
MMAC_IR_INVALID_PARAMETER, without performing any further action.
If configuration of the CAPCOM API fails, the function will return MMAC_IR_FAIL, without performing
any further action.
If the API is opened successfully, the function returns MMAC_IR_OK.
The function pointed to by callback will be called from the ISR context after each successful reception of
a code from the RCU. The user should then call MMAC_IR_Read() to retrieve any outstanding RCU
codes.

See Also
MMAC_IR_Initialise
MMAC_IR_Read

Sample Code
See section 1.1, Example Source Code.

6
MMAC_IR_Close

Function Prototype
MMAC_IR_RESULT_CODE MMAC_IR_Close ( void );

Inputs
None

Outputs
None

Event Notification
N/A

Return Codes
MMAC_IR_OK
MMAC_IR_NOT_INITIALISED
MMAC_IR_NOT_OPEN

Description
This function closes the API. It frees up the CAPCOM driver device.
If parameter checking is enabled and the API has not been initialised yet, MMAC_IR_NOT_INITIALISED
will be returned without performing any action.
If parameter checking is enabled and the API has not been opened yet, MMAC_IR_NOT_OPEN will be
returned without performing any action.
If the API is successfully closed MMAC_IR_OK is returned.

See Also
MMAC_IR_Initialise
MMAC_IR_Open

Sample Code
See section 1.1, Example Source Code.

7
MMAC_IR_Read

Function Prototype
MMAC_IR_RESULT_CODE MMAC_IR_Read(
MMAC_IR_READ_DATA *readData
);

Inputs
None

Outputs
readData pointer to a structure of type MMAC_IR_READ_DATA containing a received
code from the RCU

Event Notification
N/A

Return Codes
MMAC_IR_OK
MMAC_IR_NO_DATA
MMAC_IR_NOT_INITIALISED
MMAC_IR_NOT_OPEN
MMAC_IR_INVALID_PARAMETER

Description
This function reads an RCU code from the FIFO. It should be called following a call to the function
specified as callback during the call to MMAC_IR_Open.
If parameter checking is enabled and the API has not been initialised yet, MMAC_IR_NOT_INITIALISED
will be returned without performing any action.
If parameter checking is enabled and the API has not been opened yet, MMAC_IR_NOT_OPEN will be
returned without performing any action.
If parameter checking is enabled and readData is NULL,the function will return MMAC_IR_INVALID_
PARAMETER, without performing any further action.
When the FIFO is fully emptied the function returns MMAC_IR_NO_DATA.
If the FIFO is not emptied fast enough and it overruns the field readData->currentStatus will be set to
MMAC_IR_STATUS_BUFF_OVERFLOW until the overflow condition is resolved. When the FIFO is
valid the readData->currentStatus field is set to MMAC_IR_STATUS_OK.
The field readData->[Link] specifies whether the received key press was a repeat
(MMAC_IR_KEY_REPEAT) or if it was a new key press (MMAC_IR_KEY_PRESSED).
The field readData->[Link] contains the raw code extracted from the RCU transmission.

See Also
MMAC_IR_Open

Sample Code
See section 1.1, Example Source Code.

8
3 Data Structures

Result Codes
The following result codes are defined for the IR API. The result code value 0 is reserved for indication of
a successful operation.

typedef enum
{
MMAC_IR_OK = 0,
MMAC_IR_ALREADY_INITIALISED,
MMAC_IR_NOT_INITIALISED,
MMAC_IR_FAIL,
MMAC_IR_INVALID_PARAM,
MMAC_IR_ALREADY_OPEN,
MMAC_IR_NOT_OPEN,
MMAC_IR_NO_DATA
} MMAC_IR_RESULT_CODE;

IR Callback
The callback function used to notify of a new code received from the RCU is:
typedef void(*MMAC_IR_CALLBACK)(void);

FIFO Entry
The codes received from the RCU are stored in a FIFO and can be read by calling MMAC_IR_Read, using
the following structure:

typedef enum
{
MMAC_IR_KEY_PRESSED,
MMAC_IR_KEY_REPEAT
}MMAC_IR_ACTION;

typedef struct
{
UI32 keyIdx;
MMAC_IR_ACTION action;
}MMAC_IR_EVENT;

typedef enum
{
MMAC_IR_STATUS_OK,
MMAC_IR_STATUS_BUFF_OVERFLOW
}MMAC_IR_STATUS;

typedef struct
{
MMAC_IR_EVENT event;
MMAC_IR_STATUS currentStatus;
}MMAC_IR_READ_DATA;

9
4 Revision History
Title: API Specification: Infrared Interface
Ref: API_IRR.doc

Date Doc API Details of change Ref.

Ver. Ver.
2002-02-26 0.01 Initial Revision M-AS
2002-08-13 0.02 Doc reformatted M-RI
2002-12-09 1.0 For release – same as v0.02 M-RI
2003-06-27 1.1 Doc number added. M-RJI
2004-02-18 1.2 Doc renamed and re-titled (was “_IRR”). M-RJI

10