white bream - Implementation.pdfConfidential S131 Infrared secondary station stack implementation guide Version Date Comment 0.2 Mar 17, 2004 Initial document 1.0 Jan ?, 2005 Guide

white bream

White Bream Terborchdreef 26 3262 NB Oud-Beijerland The Netherlands

Description: Infrared secondary station stack implementation guide

Project: S131

Status: Draft

Confidential

Pages: 89

S131 Infrared

protocol stack

Implementation guide

Confidential S131 Infrared secondary station stack implementation guide

Version Date Comment

0.2 Mar 17, 2004 Initial document

1.0 Jan ?, 2005 Guide with stack release 1.2

Throughout this guide, the trade names and trademarks of various companies andproducts have been used, and no such uses are intended to convey endorsement ofor other affiliations with the report. Any brand names or product names used withinthis report are trademarks or registered trademarks of their respective holders.

The IrDA feature trademark is owned by the Infrared Data Association and usedunder license therefrom.

White Bream © 2000 - 2005 S131RP002 v1.0

S131 Infrared secondary station stack implementation guide Draft

Table of Contents

1 Introduction .......................................................................................... 71.1 Specifications ................................................................................................................. 7

1.2 Supported protocols ................................................................................................... 7

1.3 Capabilities ..................................................................................................................... 8

1.4 Support ........................................................................................................................... 8

2 Infrared overview ................................................................................. 92.1 IrPHY ............................................................................................................................ 10

2.2 IrLAP ............................................................................................................................. 102.2.1 Discovery .............................................................................................................. 102.2.2 Negotiation ........................................................................................................... 11

2.3 IrLMP ............................................................................................................................ 11

2.4 Tiny TP ......................................................................................................................... 12

2.5 Information Access Service (IAS) ........................................................................... 12

2.6 IrCOMM ....................................................................................................................... 12

2.7 IrLPT ............................................................................................................................. 13

2.8 IrPNP ............................................................................................................................ 13

2.9 IrOBEX ......................................................................................................................... 13

2.10 Protocol analysis ........................................................................................................ 14

3 Easy Infrared stack API ...................................................................... 153.1 Timer ............................................................................................................................ 15

3.2 UART ............................................................................................................................ 15

3.3 Stack functions ............................................................................................................ 153.3.1 IrDA_Init ............................................................................................................... 173.3.2 IrDA_Stop ............................................................................................................. 183.3.3 IrDA_Loop ............................................................................................................ 193.3.4 IrDA_TimerTick .................................................................................................. 20

4 Full Infrared stack API ....................................................................... 214.1 Timer ............................................................................................................................ 21

4.2 UART ............................................................................................................................ 21

4.3 Stack functions ............................................................................................................ 214.3.1 IrDA_Init ............................................................................................................... 23

White Bream © 2000 - 2005 page 3 of 89


4.3.2 IrDA_Stop ............................................................................................................. 244.3.3 IrLAP_SendNRM ................................................................................................ 254.3.4 IrLAP_SessionTimeout ....................................................................................... 264.3.5 IrPHY_Recv ........................................................................................................... 274.3.6 IrPHY_PACKET_confirm .................................................................................. 284.3.7 IrPHY_SendInt ...................................................................................................... 29

4.4 User functions ............................................................................................................. 304.4.1 IrLAP_StartTAT ................................................................................................... 314.4.2 IrLAP_StartWD ................................................................................................... 324.4.3 IrPHY_InitPort ..................................................................................................... 334.4.4 IrPHY_SendByte .................................................................................................. 344.4.5 IrPHY_PACKET_indication ............................................................................... 35

4.5 Configuration .............................................................................................................. 364.5.1 IrDA parameters .................................................................................................. 364.5.2 IrLAP parameters ................................................................................................ 364.5.3 IrLMP parameters ................................................................................................ 374.5.4 Debugging .............................................................................................................. 38

5 IrCOMM API ....................................................................................... 395.1 Limitations ................................................................................................................... 39

5.2 Protocol functions ..................................................................................................... 395.2.1 IrCOMM_Init ........................................................................................................ 405.2.2 IrCOMM_SetConnectFunction ........................................................................ 415.2.3 IrCOMM_DATA_request ................................................................................. 42

5.3 User functions ............................................................................................................. 435.3.1 IrCOMM_Data ..................................................................................................... 445.3.2 IrCOMM_SignalConnect .................................................................................... 45

5.4 Configuration .............................................................................................................. 46

6 IrLPT API ............................................................................................ 476.1 Protocol functions ..................................................................................................... 47

6.1.1 IrLPT_Init ............................................................................................................... 48

6.2 User functions ............................................................................................................. 496.2.1 IrLPT_Data ............................................................................................................ 50

7 IrPNP API ........................................................................................... 517.1 Protocol functions ..................................................................................................... 51

7.1.1 IrPNP_Init .............................................................................................................. 51

7.2 Configuration .............................................................................................................. 52

White Bream © 2000 - 2005 S131RP002 v1.0


8 IrOBEX API ........................................................................................ 538.1 Protocol functions ..................................................................................................... 53

8.1.1 IrOBEX_Init .......................................................................................................... 53

8.2 User functions ............................................................................................................. 53

8.3 Configuration .............................................................................................................. 53

9 References ........................................................................................... 55

10 Literature ............................................................................................ 55

11 Annex A, Example implementation ................................................. 57

12 Annex B, E105 Infrared evaluation board ....................................... 5912.1 IrCOMM demo ........................................................................................................... 59

12.2 IrOBEX demo ............................................................................................................. 59

12.3 Configuration .............................................................................................................. 59

12.4 References ................................................................................................................... 59

13 Annex C, Freescale HCS12 support ................................................. 6113.1 IrCOMM demo ........................................................................................................... 61

13.2 IrOBEX demo ............................................................................................................. 61

13.3 Compiler and hardware notes ................................................................................ 61

13.4 Configuration .............................................................................................................. 61

13.5 References ................................................................................................................... 62

14 Annex D, Zilog Z8/Encore® support ................................................ 6314.1 IrCOMM demo ........................................................................................................... 63

14.2 IrOBEX demo ............................................................................................................. 63


14.4 Configuration .............................................................................................................. 64

14.5 References ................................................................................................................... 64

15 Annex E, Renesas H8/38076 support ................................................ 6515.1 IrCOMM demo ........................................................................................................... 65

15.2 IrOBEX demo ............................................................................................................. 65


15.4 Configuration .............................................................................................................. 65

15.5 References ................................................................................................................... 65



16 Annex F, irdaproc.c; 'proc' implementation ................................... 6716.1 'proc' introduction ..................................................................................................... 67

16.2 Configuration .............................................................................................................. 67

16.3 References ................................................................................................................... 68

17 Annex G, Custom protocols ............................................................. 6917.1 Stack internals ............................................................................................................. 69

17.1.1 IrCustom_CONNECT_indication ................................................................... 7017.1.2 IrCustom_DATA_indication ............................................................................. 7117.1.3 IrCustom_ProcessData ...................................................................................... 72

17.2 Configuration .............................................................................................................. 73

18 Annex H, s131sys.h ............................................................................. 7518.1 Debug facilities ............................................................................................................ 75

18.2 Defines in s131sys.h .................................................................................................. 76

18.3 Typedefs in s131sys.h ................................................................................................ 77

19 Annex I, Version history .................................................................... 79

20 Annex J, License agreement ............................................................. 81

White Bream © 2000 - 2005 S131RP002 v1.0


1 Introduction

The S131 Infrared secondary station protocol stack is a low-cost implementation ofthe IrDA® Standards specifications. This software enables devices to provide ainfrared wireless communication facility that replaces the classic and oftencumbersome wired serial connections.

The reader of this document is assumed to have some basic knowledge about theIrDA standards and their purpose and application. A basic overview and descriptionof these standards is presented in chapter 2 of this document.

1.1 SpecificationsThe following IrDA Standards specifications are implemented in this protocol stack:

Specification: Features:

IrPHY - SIR, baudrate 9600-115200bps- Minimum turn-around applied by BOF insertion- Escape character insertion- CRC check and generation

IrLAP - Frame size 64 – 2048 bytes- Window size limited to 1

IrLMP - Static number of services (default to 5)

TinyTP

IAS - Merged with IrLMP

IrCOMM - 3 & 9-Wire- Data only, no control

These specifications are interpreted according the IrDA-Lite recommendations. Thismeans that certain parts of the specifications are simplified or ignored. See alsoparagraph 1.3 – Capabilities.

1.2 Supported protocolsThe S131 Infrared protocol stack supports the following top-level protocols:

• IrCOMM,• IrLPT,• IrPNP,



• IrOBEX (optional).

Other protocols can register on the IrLMP layer of the stack on the fly. IrOBEX is anoptional protocol that is available from White Bream. By taking one of the standardprotocols as a guideline and framework, also custom protocols can be implemented.This process is described in more detail in Annex C – Custom protocols.

1.3 CapabilitiesThis stack is a secondary station implementation. No support for primary features isavailable. All connections to a device with this IrDA Standards implementationtherefore have to be initiated from a station with primary station capabilities.

Secondary-only services that can be offered with this protocol stack are perfectlyusable for server-like applications that do not need to actively seek a connection butthat merely provide a service that can be accessed by other device. One such servicecould be for example printing.

1.4 SupportPlease specify your license number when contacting White Bream for questionsregarding the implementation of the stack.

Please check the frequently asked questions section on the website before askingquestions. If your question is not answered in the FAQ then the email address thatcan be used for support is [email protected]. Please start the subject line with“S131:” for clarity.

White Bream © 2000 - 2005 S131RP002 v1.0


2 Infrared overview

The IrDA Data specification consists of set of protocols that make it possible fordevices to communicate with each other with the protocol that is most suitable forthe application. Among the application protocols that are defined by IrDA are:

• IrCOMM, this protocol exists from the very beginning of the IrDA Dataspecifications. By using IrCOMM can an IrDA Data connection be used to replaceexisting serial and parallel cables.

• IrOBEX, this specification defines ‘HTTP over IrDA’, targeted at Handheld PCsand other portable information devices gives this specification the possibility toexchange objects between devices. These objects can be almost anything that canbe held in a file such as web pages, notes, games and emails.

These protocols rely on the core protocols that are mandatory for operation ofIrDA Data. These protocols provide the infrastructure for infrared communicationlike TCP/IP provides a basis for network communication.

Infrared core protocols:

IrPHY, the physical signaling layer

IrLAP, the Link Access Protocol

IrLMP, the Link Management Protocol

Tiny TP, a Tiny Transport Protocol control mechanism

IAS, an information store


IrLAP

IrLMP

TinyTPIASIr

LPT

OBEX custom

UART

Application

IrPHY

timers MIRSIR FIR

ASIC/FPGA

IrCOMM


2.1 IrPHYThe physical layer of IrDA can run over two different connection types. The first andoldest is SIR, which stands for Serial Infrared. This standard is used for speeds up to115.200 baud and uses a standard Universal Asynchronous Receiver / Transmitter(UART) The second standard covers in fact two different connection types. The firsttype is used for 576 and 1152 kbps and the second for 4 Mbps. IrDA has recentlypublished the drafts for a new standard called VFIR. This proposal specifiescommunication at 16 Mbps. This infrared stack only supports the SIR connectiontype for low-speed communications.

2.2 IrLAPThe key functions of the IrLAP layer are performing or responding to discoveryprocedures and providing a reliable device-to-device connection. The initiator of theconnection is called the primary device and the responder is called the secondarydevice.

2.2.1 DiscoveryThe discovery procedure is a method that is used to find other IrDA devices in thearea. Only a primary station can perform this procedure. The most important itemsin the discovery response frame are the hints. These byte or bytes inform the hostabout the capabilities of the responding device. The hints that are available at themoment are:

Hint byte 1: Hint byte 2

PnP compatible Telephony

PDA/Palmtop File Server

Computer IrCOMM

Printer Message

Modem HTTP

Fax JetSend

LAN Access Reserved

Every hint byte has an extension bit, which indicates that more hint bytes follow. Thismakes it possible to give almost any imaginable application it’s own hint bit becauseevery byte can be followed by a next byte.

White Bream © 2000 - 2005 S131RP002 v1.0


2.2.2 NegotiationThe IrLAP connection has a lot of parameters, which control the performance of theconnection. The parameters that will be used are negotiated when the connection isbuild up. The parameters that can be negotiated about are:

Baud Rate Additional BOFs

Maximum TAT (Turn Around Time) Minimum TAT

Data Size Threshold Time

Window Size

Because the devices need to be able to communicate with any other device is theconnection setup performed at predefined communication parameters. Theparameters are 9600 baud, 500ms max. TAT, 64 byte data size, window size of 1, 0additional BOFs, 50ms min. TAT and 40 seconds threshold. Every device thatsupports IrDA must support these parameters, it is however not required that thedevice supports these parameters for data communication, i.e. a device may negotiatethat it only supports 4 Mbps. The negotiation itself occurs than however still at 9600bps.

The parameters baud rate, data size and window size are directly related to theperformance of a link, it is evident that a connection at 4 Mbps, a packet size of 2048byte and a window size of 8 can transport much more data than a connection at9600 bps, a packet size of 64 and a window size of 1. It depends on the applicationwhether or not that is relevant.

A more or less time critical application may use a maximum TAT of less than 500 msto reduce latencies. Other applications that have limited processing power can makeuse of the minimum TAT value to prevent frames from coming in to fast. Theadditional BOFs parameter can be used for battery powered applications thatsuspend between transmissions and need some time to wake up.

The threshold time is mainly intended for user friendliness. It controls how long twostations will try to reestablish a connection that has been broken. Its value can rangefrom 3 to 40 seconds.

2.3 IrLMPIrLMP is the link management protocol and multiplexer.With this protocol is it possible to run multiple connections over a single IrLAPconnection.



2.4 Tiny TPTiny TP is an extension to IrLMP. It provides a flow control mechanism for eachIrLMP connection, just like IrLAP does for the device to device connection. This isdone by providing the remote peer with a delta credit value, which represents theamount of data that can currently be received.

It also adds segmentation and reassembly (SAR) features to IrDA, which makes theprotocol suite more universal.

2.5 Information Access Service (IAS)LM-IAS stands for Link Management – Information Access Service. This service keepsa database with the service that the IrDA implementation supports. Every protocolor service has its own entry in this database. Every entry or object has a more or lessattributes. The attributes that are mandatory are classname and LsapSel

When a host wants to contact a device then it first queries the IAS. The responsefrom the device will than show if the requested service is available in the device and(if available) which LSAP it wants to use for that service.

The basic IrDA stack without application protocols has also an entry in the IAS. Thename of this mandatory object is “Device”. It has at least the attribute“DeviceName”. This attribute is used for example by Windows 9x to retrieve thename that is displayed in the device description of the infrared monitor.

2.6 IrCOMMIrCOMM provides serial and parallel port emulator over IrDA. It can be used for anywireless IrDA connection that can also exist with a serial or parallel cable.

IrCOMM was introduced shortly after IrDA Data was specified. It is specified withthe intention to provide legacy applications the ability to communicate over infrared.Implementation recommendations discourage the use of IrCOMM in applications thatcan benefit from a more solid and integrated infrared implementation. Despite thoserecommendations have most manufacturers of IrDA equipped devices usedIrCOMM. This is probably caused by the fact that in the early days of IrDA onlyIrCOMM was supported under Windows 95, this windows implementation did alsonot allow for application specific protocols to be hooked to the stack. As a result ofthat most applications were designed to use IrCOMM.

White Bream © 2000 - 2005 S131RP002 v1.0


2.7 IrLPTIrLPT is in fact based on IrCOMM 3-wire raw, or better-said IrCOMM 3-wire raw isbased on IrLPT, since IrLPT existed before IrCOMM. It is only intended for use within printer applications and differs only from IrCOMM 3 wire raw in that it hasanother name for the IAS entry.

2.8 IrPNP[ under construction ]

2.9 IrOBEX[ under construction ]



2.10 Protocol analysisSniffir is a simple program that monitors infrared communication. The program isincluded in the Windows 2000 DDK. It provides output like this:

This tool is known to be picky about infrared receivers,the classic (RS232) JetEye dongle is known to work withSniffir. That is; at least at the basic baudrate of 9600bps.

This dongle is not made anymore, however variousresellers still have stock. A good place to get one is eBay.

White Bream © 2000 - 2005 S131RP002 v1.0

2998 XID cmd P dscv sa:D79BC9B6 da:FFFFFFFF Slot:00/8 [.]69 XID cmd P dscv sa:D79BC9B6 da:FFFFFFFF Slot:01/8 [.]42 XID rsp F dscv sa:0FA16A64 da:D79BC9B6 Slot:01/8 [....OPL8736.]28 XID cmd P dscv sa:D79BC9B6 da:FFFFFFFF Slot:02/8 [.]70 XID cmd P dscv sa:D79BC9B6 da:FFFFFFFF Slot:03/8 [.]65 XID cmd P dscv sa:D79BC9B6 da:FFFFFFFF Slot:04/8 [.]65 XID cmd P dscv sa:D79BC9B6 da:FFFFFFFF Slot:05/8 [.]65 XID cmd P dscv sa:D79BC9B6 da:FFFFFFFF Slot:06/8 [.]70 XID cmd P dscv sa:D79BC9B6 da:FFFFFFFF Slot:07/8 [.]73 XID cmd P dscv sa:D79BC9B6 da:FFFFFFFF Slot:FF/8 [...Muttley.]51 SNRM cmd P sa:D79BC9B6 da:0FA16A64 ca:0D <baud:2400,9600,19200,38400,57600,115200><maxTAT:500><data size:64,128,256,512,1024,2048><win size:1,2,3,4,5,6><BOFs:0><minTAT:5><disc thresh:3,8,12,16,20,25,30,40>34 UA rsp F sa:0FA16A64 da:D79BC9B6 <baud:9600><data size:64><win size:1><disc thresh:40>25 RR cmd P nr:023 I rsp F ns:0 nr:0 sls:03 dls:00 LM-Connect.req rsvd:00 !-MISSING TTP CONNECT HEADER-!24 I cmd P ns:0 nr:1 sls:03 dls:00 LM-Connect.req rsvd:00 !-MISSING TTP CONNECT HEADER-!19 I rsp F ns:1 nr:1 sls:00 dls:03 LM-Connect.conf rsvd:00 !-MISSING TTP CONNECT HEADER-!25 I cmd P ns:1 nr:2 sls:00 dls:03 LM-Connect.conf rsvd:00 !-MISSING TTP CONNECT HEADER-!14 RR rsp F nr:232 I cmd P ns:2 nr:2 sls:03 dls:00 mb:1 nc:4 [.PnP.DeviceID]33 I rsp F ns:2 nr:3 sls:00 dls:03 mb:0 nc:0 [....OPL8736]25 I cmd P ns:3 nr:3 sls:03 dls:00 LM-Disconnect.req(01:User Request)19 I rsp F ns:3 nr:4 sls:00 dls:03 LM-Disconnect.req(01:User Request)24 I cmd P ns:4 nr:4 sls:03 dls:00 LM-Connect.req rsvd:00 !-MISSING TTP CONNECT HEADER-!19 I rsp F ns:4 nr:5 sls:00 dls:03 LM-Connect.conf rsvd:00 !-MISSING TTP CONNECT HEADER-!32 I cmd P ns:5 nr:5 sls:03 dls:00 mb:1 nc:4 [.PnP.DeviceID]33 I rsp F ns:5 nr:6 sls:00 dls:03 mb:0 nc:0 [....OPL8736]31 I cmd P ns:6 nr:6 sls:03 dls:00 mb:0 nc:1 [...PnP.DeviceID]17 RR rsp F nr:729 I cmd P ns:7 nr:6 sls:03 dls:00 LM-Disconnect.req(01:User Request)19 I rsp F ns:6 nr:0 sls:00 dls:03 LM-Disconnect.req(01:User Request)


3 Easy Infrared stack API

The infrared interface incorporates functions that control the essentials of theinfrared stack.

The functionality that is mandatory for operation of the stack is one second-basedtimer. Also one (interrupt driven) UART is required to make the existence of thestack useful.

3.1 TimerThe timer is used to track the IrLAP watchdog timeout. The watchdog timeout canhave a value between 3 and 40 seconds and does not need to be highly accurate.

3.2 UARTThe UART is used for transmitting and receiving the IrDA frames at SIR speeds. Thisrequires that an IrDA transceiver and an EnDec are connected to the UART. Such anEnDec takes care for the generation and stretching of pulses, which are used in theinfrared domain. The duration of these pulses may vary between 1.6 μs and 3/16 ofthe bit time. More information on this subject can be found in the datasheets fromthe hardware manufacturers.

3.3 Stack functionsThese stack functions are functions that are provided by the stack and which can becalled from the user application or from the task that is responsible forcommunication in general or for infrared communication in particular.

Stack functions:

void IrDA_Init(void)

void IrDA_Stop(void)

void IrDA_Loop(void)

void IrDA_TimerTick(u8 vMsec)


MCU &S131 UART EnDec Trans

ceiverUART


White Bream © 2000 - 2005 S131RP002 v1.0


3.3.1 IrDA_Init

void IrDA_Init(void)Description: This initialization function performs all the necessary actions to

configure the stack and the associated hardware for first or forrenewed use.

Initialization of the high level protocols such as IrCOMM and IrLPTis not handled by this function and needs to be done separately bythe user application after this function has been called.

Defined in: S131.h / irda.h

Parameters: none

Return value: void



3.3.2 IrDA_Stop

void IrDA_Stop(void)Description: Dummy function.


Parameters: none

Return value: void

Remark: In order to stop the infrared stack only the serial port needs to beclosed or shut down.

White Bream © 2000 - 2005 S131RP002 v1.0


3.3.3 IrDA_Loop

void IrDA_Loop(void)Description: This ...

Defined in: s131.h / irda.h

Parameters: none

Return value: void



3.3.4 IrDA_TimerTick

void IrDA_TimerTick(u8 vMsec)Description: This function driver the disconnect threshold timer. This threshold

is typically between 3 and 40 seconds. In order to get a timelyresponse it is recommended to call this tick every 10 to 100msec.

The time between calls does not need to be constant since theelapsed time is used to calculate the total time.


Parameters: u8 vMsec Number of elapsed milliseconds since the last tick.

Return value: void

White Bream © 2000 - 2005 S131RP002 v1.0


4 Full Infrared stack API

The infrared interface incorporates functions that control the essentials of theinfrared stack. Also some user-application provided functions belong to this interface.These user functions are used by the infrared stack to control the timer and theUART.

The functionality that is mandatory for operation of the stack is one second-basedtimer. Also one (interrupt driven) UART is required to make the existence of thestack useful.

4.1 TimerThe timer is used to track the IrLAP watchdog timeout. The watchdog timeout canhave a value between 3 and 40 seconds and does not need to be highly accurate.

4.2 UARTThe UART is used for transmitting and receiving the IrDA frames at SIR speeds. Thisrequires that an IrDA transceiver and an EnDec are connected to the UART. Such anEnDec takes care for the generation and stretching of pulses, which are used in theinfrared domain. The duration of these pulses may vary between 1.6 μs and 3/16 ofthe bit time. More information on this subject can be found in the datasheets fromthe hardware manufacturers.

4.3 Stack functionsThese stack functions are functions that are provided by the stack and which can becalled from the user application or from the task that is responsible forcommunication in general or for infrared communication in particular.

Stack functions:

void IrDA_Init(void)

void IrDA_Stop(void)

void IrLAP_SendNRM(flag TAT)


MCU &S131 UART EnDec Trans

ceiverUART


Stack functions:

void IrLAP_SessionTimeout(void)

void IrPHY_Recv(u8 vRecvByte)

void IrPHY_PACKET_confirm(u8 * pData, u16 vDataLen)

void IrPHY_SendInt(void)

White Bream © 2000 - 2005 S131RP002 v1.0


4.3.1 IrDA_Init

void IrDA_Init(void)Description: This initialization function performs all the necessary actions to

configure the stack and the associated hardware for first or forrenewed use.

Initialization of the high level protocols such as IrCOMM and IrLPTis not handled by this function and needs to be done separately bythe user application after this function has been called.

Defined in: irda.h

Parameters: none

Return value: void



4.3.2 IrDA_Stop

void IrDA_Stop(void)Description: Dummy function.

Defined in: irda.h

Parameters: none

Return value: void

Remark: In order to stop the infrared stack only the serial port needs to beclosed or shut down.

White Bream © 2000 - 2005 S131RP002 v1.0


4.3.3 IrLAP_SendNRM

void IrLAP_SendNRM(flag TAT)Description: This function handles the link turn-around and should be called in

response to the IrLAP_StartTAT function. See also the demoimplementations.

Defined in: irlap.h

See also: IrLAP_StartTAT

Parameters: flag TAT Parameter passed from IrLAP_StartTAT.

Return value: void



4.3.4 IrLAP_SessionTimeout

void IrLAP_SessionTimeout(void)Description: This SessionTimeout function must be called when the (second-

based) session timer expires. This usually means that the infraredconnection with the primary device has been lost.

Defined in: irlap.h

See also: IrLAP_StartWD

Parameters: none

Return value: void

White Bream © 2000 - 2005 S131RP002 v1.0


4.3.5 IrPHY_Recv

void IrPHY_Recv(u8 vRecvByte)Description: This function processes the received infrared data bytes, the

function can be used from within an interrupt handler if needed ordesired. Each received byte is individually passed to the stackthrough this function.

When a complete infrared message has been recognized, then apointer to this (still unchecked) message is passed back to thesystem through the IrPHY_PACKET_indication function. Thismakes it possible to handle most of the processing outside the low-latency (interrupt-driven) hardware handling.

The user task will pass this message to IrPHY_PACKET_confirm,which will verify the message CRC and put IrLAP to work.

Defined in: irphy.h

Parameters: u8 vRecvByte The received (serial) data byte.

Return value: void



4.3.6 IrPHY_PACKET_confirm

void IrPHY_PACKET_confirm(u8 * pData, u16 vDataLen)Description: The infrared handler in the user application must call this function

after a complete received dataframe has been notified by the stackthrough the IrPHY_PACKET_indication function.

This way, the CRC check and processing of the data does not needto be done in the interrupt handler of the UART, which would bevery unwelcome practice, especially in an OS-based environment.

Defined in: irphy.h

See also: IrPHY_PACKET_indication

Parameters: u8 * pData Pointer to the datablock.

u16 vDataLen Length of the datablock.

Return value: void

White Bream © 2000 - 2005 S131RP002 v1.0


4.3.7 IrPHY_SendInt

void IrPHY_SendInt(void)Description: After the first byte of an infrared response frame is initiated by the

internal stack workings, the interrupt handler or the infrared taskmust keep the transmission going. This is done by repeatedly callingthis function until IrPHY_SendByte is not called any more.

This function is typically called from the serial transmit interrupthandler of the UART that handles the infrared connection.

Defined in: irphy.h

Parameters: none

Return value: void



4.4 User functionsThe following functions must be implemented in the user application and madeaccessible for the infrared stack. The stack calls these functions to access thehardware or uses these functions to reduce processing load or memory usage incertain parts of the stack.

User functions:

void IrLAP_StartTAT(flag vOnOff)

void IrLAP_StartWD(u8 vSeconds)

void IrPHY_InitPort(u32 vBaudrate)

void IrPHY_SendByte(u8 vByte)

void IrPHY_PACKET_indication(u8 * pData, u16 vDataLen)

When comparing this list with the list of stack functions, some functions might seemfamiliar. This is correct because the user application is used to break-down the stackprocessing flow into smaller pieces, which reduces the memory requirements. Thefollowing functions are directly related to each other:

User function: Associated stack function:

IrLAP_StartTAT IrLAP_SendNRM

IrLAP_StartWD IrLAP_SessionTimeout

IrPHY_PACKET_indication IrPHY_PACKET_confirm

When one of the user functions is invoked by the infrared stack, a semaphore shouldbe signaled. Then after the user function has returned the user application should callthe associated stack function to keep things running properly.

White Bream © 2000 - 2005 S131RP002 v1.0


4.4.1 IrLAP_StartTAT

void IrLAP_StartTAT(flag vOnOff)Description: This function manages the Turn-Around-Time timer that is

required for the IrLAP layer. It takes care of the delay during whichthe transmission of the Receive Ready frame is postponed. Thetimer is also used for the timing of the discovery sequence.

This call can better not be done in an interrupt handler because ittakes some time to assemble the packet, calculate a CRC for it andtransmit it. If the argument is zero then the timer must be deactivated.

Defined in: irlap.c (extern)

See also: IrLAP_SendNRM

Parameters: flag vOnOff

Return value: void



4.4.2 IrLAP_StartWD

void IrLAP_StartWD(u8 vSeconds)Description: The watchdog time for IrLAP can be 3, 8, 12, 16, 20, 25, 30 or 40

seconds. The time is specified in milliseconds. This time is not verycritical. When the timer runs out the functionIrLAP_SessionTimeout must be called which reinitializes the IrDAstack. This timer must be deactivated when the argument is zero.

Defined in: irlap.c (extern)

See also: IrLAP_SessionTimeout

Parameters: u8 vSeconds The time that the timer must run in seconds.The timer must be canceled when this is zero.

Return value: void

White Bream © 2000 - 2005 S131RP002 v1.0


4.4.3 IrPHY_InitPort

void IrPHY_InitPort(u32 vBaudrate)Description: The InitPort function must configure and open the serial port. Also

the baudrate must be configured. This function is called each timethe baudrate of the infrared link changes.

Defined in: irphy.c (extern)

Parameters: u32 vBaudrate Long integer representation of the desiredbaudrate.

Return value: void



4.4.4 IrPHY_SendByte

void IrPHY_SendByte(u8 vByte)Description: The user application must provide this function so that the infrared

stack can use it to pass framedata to the UART. This data is passedone byte at a time, either from the stack internal dataflow or fromthe IrPHY_SendInt transmission handler.


Parameters: u8 vByte Databyte to be transmitted.

Return value: void

White Bream © 2000 - 2005 S131RP002 v1.0


4.4.5 IrPHY_PACKET_indication

void IrPHY_PACKET_indication(u8 * pData, u16 vDataLen)Description: After an entire infrared frame is received, it must be checked for

correct CRC and then processed through the stack. Since we donot want all this to happen in the interrupt handler of the UART,this function is introduced.

When the end of frame character is received, a pointer to thecollected data is passed to this function. The infrared handler taskin the user application should store this pointer and pass it on tothe IrPHY_PACKET_confirm function. This way, the processing ofthe data is isolated from the interrupt handler.


See also: IrPHY_PACKET_confirm

Parameters: u8 * pData Pointer to the start of the unverified infrareddataframe.

u16 vDataLen Length of the dataframe.

Return value: void



4.5 ConfigurationThe stack can be configured relatively easy by changing defines in config.h. Becausecertain functionality is not always wanted or needed, and some designs might havevery little spare memory is it possible to remove some parts of the stack by disablingthe corresponding defines.

A couple of defines control which parts of the code are skipped and what the defaultvalues will be.

4.5.1 IrDA parameters

PRODUCT_IDDescription: This is the name that is sent during the discoveries. (This name

appears in the Windows XP popup window.)

Default: “S131”

PRODUCT_DESCDescription: This is the name that send during the discoveries. This is the

description that appears in the Infrared monitor of Ms. Windows.

Default: “protocol stack ”

4.5.2 IrLAP parameters

LAPLENGTHDescription: The maximum length of the LAP frame in bytes.

Default: 64

Other values: 128, 256, 512, 1024, 2048

White Bream © 2000 - 2005 S131RP002 v1.0


LAP_DEFAULT_MAXTATDescription: Default value for the maximum Turn-Around-Time.

Default: LAP_MAX_TAT_500 500 ms

Other values: LAP_MAX_TAT_250,LAP_MAX_TAT_100,LAP_MAX_TAT_50

250 ms100 ms50 ms

LAP_DEFAULT_THRESHOLDDescription: Default value for the Threshold time.

Default: LAP_THRESHOLD_3S 3 sec.

Other values: LAP_THRESHOLD_8S,LAP_THRESHOLD_12S,LAP_THRESHOLD_16S,LAP_THRESHOLD_20S,LAP_THRESHOLD_25S,LAP_THRESHOLD_30S,LAP_THRESHOLD_40S

8 sec.12 sec.16 sec.20 sec.25 sec.30 sec.40 sec.

4.5.3 IrLMP parameters

LMP_SERVICEHINT_BYTESDescription: The number of bytes that is reserved for the hint bytes in the LMP

header. Normally this number does not need to be changed.

Default: 2



LMP_SERVICES_COUNTDescription: The number of services that can be registered on top of the IrLMP

layer.Adjust this number accordingly when adding IrOBEX or your ownadditional protocols in conjunction with the standard protocols.

Default: 5

4.5.4 DebuggingThe debugging options are not controlled in the config file, but can be specified onthe compiler command line. Debugging is simply implemented by using the printf()function. All the calls to printf are conditionally compiled under the control of__DEBUG1 to __DEBUG4. __DEBUG3 and 4 both imply the use if __DEBUG1 and2. The higher two values can produce a lot of data to be dumped because data isprinted for every packet that is received and transmitted. This can heavily affect theperformance of the stack and even corrupt communication!

White Bream © 2000 - 2005 S131RP002 v1.0


5 IrCOMM API

This top-level protocol provides the serial and parallel port emulation.

5.1 LimitationsThe IrCOMM layer can communicate by using the 3-wire raw, the 3-wire or the 9-wire protocol. All these protocols are handled the same. This means that all thecontrol data, such as handshake and baudrate settings, is ignored and not respondedto.1 For most embedded applications no real serial port emulation is needed anywaysince the data flows directly into the application without any configurable hardwarein between.

5.2 Protocol functionsThese are functions that are provided by the stack and which can be called from theuser application.

Functions:

void IrCOMM_Init(pFunction)

void IrCOMM_SetConnectFunction(pFunction)

u16 IrCOMM_DATA_request(pData, vLength)

1 More sophisticated processing of the control data is planned for future versions ofthe infrared protocol stack.



5.2.1 IrCOMM_Init

void IrCOMM_Init(IrCOMM_Data pFunction)Description: Registers the IrCOMM protocol to the IrLMP layer and the IAS

database of the infrared protocol stack. The 'IrCOMM' bit in thediscovery hints is set to indicate the availability of the protocol.Depending on the additional configuration defines also the hints for'printer' and for 'modem' can be set.

When IrCOMM is initialized with a NULL-pointer as argument,nothing will be done with the received data, of course this makesthe existence of IrCOMM somewhat useless. But it will continue towork as expected.

Defined in: ircomm.h

Parameters: ... pFunction Pointer to the callback function that will receiveand handle the received data.

Return value: void

IrCOMM_DataDefinition: typedef void

(*IrCOMM_Data)(u8 * pData, u16 vLength);


Parameters: u8 * pData Pointer to the first byte of the datablock thatshould be processed.

u16 vLength Number of bytes in the datablock.

White Bream © 2000 - 2005 S131RP002 v1.0


5.2.2 IrCOMM_SetConnectFunction

void IrCOMM_SetConnectFunction (IrCOMM_SignalConnect pFunction)Description: This initialization function must be used to register the user

function that must receive the connection state change events withthe IrCOMM layer.


Parameters: ... pFunction Pointer to the callback function that will handlethe notifications.

Return value: void

Remark: This function must be used after IrCOMM_Init, otherwise thefunction pointer gets cleared again.

The pointer is set to NULL by default in IrCOMM_Init; no explicitcall with a NULL-pointer argument is needed.

IrCOMM_SignalConnectDefinition: typedef void

(*IrCOMM_SignalConnect)(flag OnOff);


Parameters: flag vOnOff Boolean value that represents the connectionstate. TRUE = connected, FALSE = disconnected.



5.2.3 IrCOMM_DATA_request

u16 IrCOMM_DATA_request(u8 * pData, u16 vLength)Description: By calling this function, the user application can request the

specified data to be send to the remote station.


Parameters: u8 * pData Pointer to the datablock that must be send to theprimary station using IrCOMM.

u16 vLength Length in bytes of the datablock to be transmitted.

Return value: u16 Number of bytes actually transferred from thedatablock to the IrCOMM transmit buffer.

Remark: This function should only be used from within the IrCOMM_Datacallback function!

White Bream © 2000 - 2005 S131RP002 v1.0


5.3 User functions

Functions:

void IrCOMM_Data(u8 * pData, u16 vLength)

void IrCOMM_SignalConnect(flag vOnOff)

These functions are registered by using the appropriate IrCOMM initializationfunctions.

Note that these function names cannot be used in the real application since theseexact names are already used in the typedefs for the function pointers in theinitialization functions of IrCOMM (see also the previous sections).



5.3.1 IrCOMM_Data

void IrCOMM_Data(u8 * pData, u16 vLength)Description: IrCOMM data is passed to the user application through this

function. This function provided by the user application andattached to the IrCOMM protocol by passing it's pointer as anargument to IrCOMM_Init().

This user function is responsible for processing all the data. Afterthe function has returned, no valid data can be expected any moreat the buffer location!


Condition: This callback must be initialized by using the function IrCOMM_Init.The received data gets completely ignored when this function isnot provided.



Return value: void The function must have handled the buffer beforereturning. No data is left afterwards, and noretries done with remaining data.

Remark: The function name cannot be equal to 'IrCOMM_Data' since thisexact name is already used for the typedef that defines theIrCOMM_Init parameter.

White Bream © 2000 - 2005 S131RP002 v1.0


5.3.2 IrCOMM_SignalConnect

void IrCOMM_SignalConnect(flag vOnOff)Description: By providing this function in the user application, a notification can

be received when the IrCOMM connection is activated and when itis ended. This feature can be useful for providing a connectionindicator or things like that.


Condition: This callback must be initialized by using the functionIrCOMM_SetConnectFunction.

Parameters: flag vOnOff Signals the connection state of the IrCOMMconnection. TRUE = connected, FALSE =disconnected.

Return value: void

Remark: The function name cannot be the same as'IrCOMM_SignalConnect' since this exact name is already used forthe typedef that defines the IrCOMM_SetConnectFunctionparameter.



5.4 ConfigurationConfiguration defines for IrCOMM are located in the implementation file S131cfg.h.

COMM_HINT_MODEMDescription: Enable or disable the modem hint bit in the discovery frame.

Default: FALSE

COMM_HINT_PRINTERDescription: Enable or disable the printer hint bit in the discovery frame.

Default: FALSE

COMM_SERVICE_TYPEDescription: Default service type.

Default: COMM_3WIRERAW

Other values: COMM_3WIRE,COMM_9WIRE,COMM_CENTRONICS

COMM_PORT_TYPEDescription: Default port type.

Default: COMM_SERIAL

Other values: COMM_PARALLEL

White Bream © 2000 - 2005 S131RP002 v1.0


6 IrLPT API


Functions:

void IrLPT_Init(IrLPT_Data pFunction)



6.1.1 IrLPT_Init

void IrLPT_Init(IrLPT_Data pFunction)Description: Registers the IrLPT protocol to the IrLPT layer and the IAS

database of the infrared protocol stack. The 'printer' bit in thediscovery hints is set to indicate the availability of the protocol.

Defined in: irlpt.h

Parameters: ... pFunction Pointer to the function that will handle thereceived printing data.

Return value: void

IrLPT_DataDefinition: typedef void

(*IrLPT_Data)(u8 * pData, u16 vLength);

Defined in: irlpt.h



White Bream © 2000 - 2005 S131RP002 v1.0


6.2 User functions

Functions:

void IrLPT_Data(u8 * pData, u16 vLength)



6.2.1 IrLPT_Data

void IrLPT_Data(u8 * pData, u16 vLength)Description: IrLPT data is passed to the user application through this function.

This function provided by the user application and attached to theIrLPT protocol by passing it's pointer as an argument to IrLPT_Init.

This user function is responsible for processing all the data. Afterthe function has returned, no valid data can be expected any moreat the buffer location!

Defined in: irlpt.h

Condition: This callback must be initialized by using the function IrLPT_Init.The received data gets completely ignored when this function isnot provided.



Return value: void The function must have handled the buffer beforereturning. No data is left afterwards, and noretries done with remaining data.

Remark: The function name cannot be equal to 'IrLPT_Data' since this exactname is already used for the typedef that defines the IrLPT_Initparameter.

White Bream © 2000 - 2005 S131RP002 v1.0


7 IrPNP API

The IrPNP protocol causes the host to contact the device immediately upondiscovery and to query its PnP parameters.

7.1 Protocol functionsThere is only one function provided by this protocol:

Functions:

void IrPNP_Init(void)

7.1.1 IrPNP_Init

void IrPNP_Init(void)Description: Registers the IrPNP protocol to the IrLMP layer and the IAS

database of the infrared protocol stack. The 'PnP' bit in thediscovery hints is set to indicate the availability of the protocol.

Defined in: irpnp.h

Parameters: none

Return value: void



7.2 ConfigurationThe following parameter of the IrPNP protocol is configurable in the stack-wideconfiguration file config.h:

MANUFACTURERDescription: Product manufacturer identification string.

Default: “White Bream ”

Certain other parameters are used by IrPNP but are defined elsewhere:

#Define: Default: Location:

PRODUCT_ID “S131 ” s131cfg.h

PRODUCT_DESC “protocol stack ” s131cfg.h

PNP_ID “PNP0510 ” irpnp.h

White Bream © 2000 - 2005 S131RP002 v1.0


8 IrOBEX API2


Functions:

void IrOBEX_Init(void)

8.1.1 IrOBEX_Init

void IrOBEX_Init(void)Description: Initializer.

Defined in: irobex.h

Parameters: none

Return value: void

8.2 User functions[ tbd ]

8.3 Configuration[ tbd ]

2 Optional; only available when explicitly licensed



White Bream © 2000 - 2005 S131RP002 v1.0


9 References

Infrared Data Association www.irda.orgMicrosoft www.microsoft.com

10 Literature

“‘IrCOMM’: Serial and Parallel Port Emulation over IR (Wire Replacement)” v. 1.0 November 7, 1995 Infrared Data Association

“Minimal IrDA Protocol Implementation (IrDA Lite)” version 1.0November 7, 1996 Infrared Data Association

“‘Tiny TP’: A Flow-Control Mechanism for use with IrLMP” version 1.1October 20, 1996 Infrared Data Association

“Link Management Protocol” version 1.1January 23, 1996 Infrared Data Association

“Serial Infrared Link Access Protocol (IrLAP)” version 1.1June 16, 1996 Infrared Data Association

“Serial Infrared Physical Layer Specification” version 1.3October 15, 1998 Infrared Data Association

“Plug and Play Extensions to Link Management Protocol” version 1.1January 8, 1996 Infrared Data Association

“Object Exchange Protocol OBEX™” version 1.3January 3, 2003 Infrared Data Association

“Windows Generic Device IDs”February 2, 1998 Microsoft



White Bream © 2000 - 2005 S131RP002 v1.0


11 Annex A, Example implementation

[ under construction ]

11.1 Compiler notesIt is important that the root directory of the infrared stack (i.e. .\s131) is specified inthe optionlist of the compiler/preprocessor. Also the path to the configuration filesmust be added there. Without these two paths set correctly, a lot of errorsregarding undefined issues will appear.



White Bream © 2000 - 2005 S131RP002 v1.0


12 Annex B, E105 Infrared evaluation board


12.1 IrCOMM demo[ under construction ]

12.2 IrOBEX demo[ under construction ]

12.3 Configuration[ under construction ]

12.4 Compiler and hardware notes[ under construction ]

12.5 Referenceswww.whitebream.com/e105.shtmlwww.whitebream.com/i121.shtmlwww.renesas.comwww.xilinx.com/xlnx/xil_prodcat_product.jsp?title=xc9500xl_pagewww.kpitgnutools.com



White Bream © 2000 - 2005 S131RP002 v1.0


13 Annex C, Freescale HCS12 support

The HC9S12E128 is a member of the HC9S12E embedded low-cost MCU familywhich provides up to 256kB of flash ROM and 16kB of RAM. This family has threeasynchronous serial ports with IrDA capabilities as well as a variety of other portssuch as I2C, SPI, 16-channel/10-bit AD converter, 2 DA converters, three 16-bittimers and various PWM timers.

The demo implementation is created to run on theAdapt9S12E128 evaluation board from TechnologicalArts. This board has all infrared requirements availableon-board, which makes evaluation and developmentmuch easier.

Total memory allocation for the demo applcation onthis board is 16kB ROM and 3kB RAM compiled in large memory model with 64-bytepacket size. The S131 libarized infrared protocol stack alone is good for 6.1kB ROMand 1.2kB RAM.


13.2 IrOBEX demoNot yet supported.

13.3 Compiler and hardware notesWhen using evaluation board 'Adapt9S12E128' from Technological Arts, make surethat jumper 6 (JB6) is in position VCC, otherwise the infrared transceiver remainsunpowered.

13.4 Configuration

USE_UARTxDescription: Selection of on-chip SCI-port that is to be used for infrared

communications.

Default: USE_UART0



USE_UARTxOther values: USE_UART1, USE_UART2

SCI_CLOCKDescription: The peripheral clockrate. This is the clock speed after the PLL

circuit, which is not necessarily the same speed as the value of theon-board crystal!

Default: 25000000L

GENERATE_INTERRUPT_HANDLERDescription: The interrupt handler must be added to the interrupt vector table

when using the this interrupt handler type. When using ProcessorExpert, this involves in adding the function-name to the appropriatelocation in this vector table.

GENERATE_ANSIC_INT_HANDLERDescription: With this define the compiler and the linker automatically allocate

the necessary interrupt vector for the interrupt handler. Thiscannot be used in conjunction with processor expert.

13.5 Referenceswww.freescale.com/webapp/sps/site/prod_summary.jsp?code=MC9S12E128www.technologicalarts.com/myfiles/AD9S12E128.htmlwww.metrowerks.com/MW/Develop/Embedded/HC12/

White Bream © 2000 - 2005 S131RP002 v1.0


14 Annex D, Zilog Z8/Encore® support


The demo is based on the Zilog Encore! F64x Evaluation module, which contains theZ8F6423FT020SC microcontroller and an IrDA transceiver device.

Total memory allocation for this demo is 24.7kB ROM and 1.9kB RAM, compiled inlarge memory model with 64-byte packet size. These figures also include librariessuch as stdio.

14.1 IrCOMM demoOn this board, the IrCOMM protocol is implemented as a loopback function. Afterinitiating a session, the demo will first respond with the following message. Then itsimply echoes all the data that is send to the board. This message is also transmittedwhen the TEST-button is pressed.

The RS232 serial port cannot be used simultaneously with the IrDA interfacebecause both interfaces are connected in parallel. Therefore no serial I/O throughRS232 is possible on this board.

14.2 IrOBEX demoNot yet supported.

14.3 Compiler and hardware notesWhen using the Encore! F64x Evaluation module, make sure that JP4 (DIS RS232) isclosed and JP3 (DIS IRDA) is open.

The evaluation module that is used for this demo exhibited a very low sensitivity.Because of that the board has to be held against the IrDA window of the primarystation to establish good communication. This might be a incidental anomaly though.


__ __ _ _ _ _____ ____ ____ ____ ____ ___ ___ ___\ \_/\_/ /| |_| || ||_ _|| ___| | __ \| __ \| ___| / _ \ | \/ | \ / | _ || | | | | __| | __ <| /| __| | _ || |\ /| | \_/\_/ |_| |_||_| |_| |____| |____/|_|\_\|____||_| |_||_| \/ |_|

S131 Infrared protocol stack demo for Zilog Z8 Encore!

www.whitebream.nl www.whitebream.com www.carpc.nl


14.4 Configuration


communications.

Default: USE_UART0

Other values: USE_UART1

SCI_CLOCKDescription: The peripheral clockrate. This is the clock speed after the PLL,

which is not necessarily the same as the on-board crystal value!

Default: extern long get_freq(void)

14.5 Referenceswww.zilog.com

White Bream © 2000 - 2005 S131RP002 v1.0


15 Annex E, Renesas H8/38076 support



15.2 IrOBEX demo[ under construction ]

15.3 Compiler and hardware notes[ under construction ]

15.4 Configuration


communications.

Default: USE_UART0

Other values: USE_UART1

SCI_CLOCKDescription: The peripheral clockrate. This is the clock speed after the PLL,

which is not necessarily the same as the on-board crystal value!

Default: 25000000L


15.5 Referenceswww.whitebream.com/s131.shtmlwww.renesas.com



www.kpitgnutools.com

White Bream © 2000 - 2005 S131RP002 v1.0


16 Annex F, irdaproc.c; 'proc' implementation

16.1 'proc' introductionProc is a free real-time kernel for small microcontrollers. The kernel is written andmaintained by Nilsen Elektronikk as from Normay.

The task implementation for the infrared protocol handler eliminates the need toperiodically poll the IrDA_Loop function. Also the timer is now handled by the OS-timer system.

16.2 Configuration

IRDA_STACK_SIZEDescription: The stack size that is needed for the Infrared protocol handler task.

This value might need to be changed when the task functionality isaltered.

Default: 512

IRDA_CHAN_SIZEDescription: The message channel for the infrared handler contains usually just

up to one message. So the default size should be sufficient, even forunforseen extreme exceptions.

Default: 4

IRDA_TASK_PRIODescription: Default priority for the infrared protocol handler.

Default: 3



PROC_TICKS_PER_SECONDDescription: Number of milliseconds between timerticks.

Default: 1000

16.3 Referenceshttp://home.eunet.no/~jen/neproc.html

White Bream © 2000 - 2005 S131RP002 v1.0


17 Annex G, Custom protocols


17.1 Stack internals

Functions:

flag IrCustom_CONNECT_indication(PCONNECT_IND_PARAMSpParams)

flag IrCustom_DATA_indication(PDATA_IND_PARAMS pParams)

flag IrCustom_ProcessData(void)



17.1.1 IrCustom_CONNECT_indication

flagIrCustom_CONNECT_indication(PCONNECT_IND_PARAMS pParams)Description: The remote node is trying to establish a connection to this cutsom

protocol. The device can accept or decline the connection requestwith the return value.

Defined in: custom.h

Parameters: pParams See below for struct definition

Return value: flag Reject connection when false, accept when TRUE.

PCONNECT_IND_PARAMSDefinition: typedef struct {

u8 vOurLSAP; u8 vRmtLSAP; flag vOnOff; u8 * pData; u16 vLength;} CONNECT_IND_PARAMS, *PCONNECT_IND_PARAMS;

Defined in: irlmp.h

White Bream © 2000 - 2005 S131RP002 v1.0


PCONNECT_IND_PARAMSMembers: vOurLSAP Address of our service.

vRmtLSAP Address of the remote node.

vOnOff TRUE when connection is established.

pData Pointer to connection data.

vLength Length of connection data.

17.1.2 IrCustom_DATA_indication

flag IrCustom_DATA_indication(PDATA_IND_PARAMS pParams)Description: Notification of data received from the primary station.

Any data that needs to be send back must be passed to the stackbefore the function returns.See also the implementation of IrCOMM_DATA_indication.

Defined in: irlmp.h

Parameters: pParams Structure containing the data. See below.

Return value: flag

PDATA_IND_PARAMSDefinition: typedef struct {

u8 vRmtLSAP; u8 * pData; u16 vLength;} DATA_IND_PARAMS, *PDATA_IND_PARAMS;



PDATA_IND_PARAMSDefined in: irlmp.h

Members: vRmtLSAP .Address of the remote node.

pData Pointer to extracted data packet.

vLength Length of the data packet.

White Bream © 2000 - 2005 S131RP002 v1.0


17.1.3 IrCustom_ProcessData

flag IrCustom_ProcessData(void)Description: Poll from IrLMP if any data is waiting before returning the link

control to the remote.See also the implementation of IrCOMM_ProcessData.

Defined in: irlmp.h

Parameters: none

Return value: flag TRUE when waiting/queued data is passed toIrLMP.



17.2 ConfigurationThe following parameter must be configured in the header file that belongs to thecustom protocol implementation:

LMP_CUSTOMDescription: Selects the hint bit that must be associated with this protocol.

Default: LMP_RESERVED1

Other values: LMP_RESERVED2 (Also used for OBEX)LMP_RESERVED3LMP_RESERVED4

IAP_CLASS_CUSTOMDescription: Class name that appears in the information access service (IAS).

Default: “WHBR ”

White Bream © 2000 - 2005 S131RP002 v1.0




18 Annex H, s131sys.h

18.1 Debug facilitiesThe sources for the infrared stack contain four levels of debugging output. Theselevels are activated with the following defines. Usually these defines are passed usingthe compiler commandline.

__DEBUG1Description: .


Remark: When activated, also __DEBUG1 gets activated.


Remark: When activated, also __DEBUG2 (and __DEBUG1) gets activated.


Remark: When activated, also __DEBUG2 (and __DEBUG1) gets activated.

The debug output uses printf to output formatted textual information. Depending onthe development environment, these defines might need to be changed toaccommodate other (probably more suitable) debug output mechanisms. Such othermechanism should at least accept a format specifier and a variable parameter list, likethe stdio functions do.

White Bream © 2000 - 2005 S131RP002 v1.0


18.2 Defines in s131sys.h

TRUE, FALSEDescription: Values for booleans. Some preprocessors do not know these by

default...

Value: TRUE: -1FALSE: 0

Remark: Only defined when #ifndef TRUE is valid.

safestructDescription: If the compiler realigns or pads structmembers then the stack will

not function correctly. Usually some qualifiers are available tosuppress this optimizing behavior.

Default: struct

CONSTDescription: Certain compilers need special code to map constant data

correctly in the ROM. Otherwise that data will be copied to RAMon startup which consumes (usually) scarce memory.

Default: const



18.3 Typedefs in s131sys.hThese typedefs take care of standard number types.

c8Description: Standard character. Used for strings and text pointers.

Range: Depending on compiler settings -128 to 127 or 0 to 255

Type: char

u8Range: 0 to 255

Type: unsigned char

s8Range: -128 to 127

Type: signed char

U16Range: .0 to 65535

Type: unsigned int

s16Range: -32768 to 32767

White Bream © 2000 - 2005 S131RP002 v1.0


s16Type: signed int

U32Range: 0 to 4294967295

Type: unsigned long

s32Range: -2147483648 to 2147483647

Type: signed long

flagDescription: Boolean type

Range: 0 (FALSE) and !0 (TRUE)

Type: s8 (signed char)



19 Annex I, Version history

Version Date Major changes

0.2 Mar 17, 2004

1.2.0 Jan ?, 2005

White Bream © 2000 - 2005 S131RP002 v1.0




20 Annex J, License agreement

S131 Infrared Secondary protocol stack is copyright © 2000-2005 by White Bream,all rights reserved.

This software and accompanying documentation are protected by copyright law andalso by International Treaty provisions. Any use of this software in violation ofcopyright law or the terms of this agreement will be prosecuted to the best of ourability.

White Bream authorizes you to make archival copies of this software for the solepurpose of back-up and protecting your investment from loss. Under nocircumstances may you copy this software or documentation for the purposes ofdistribution to others. Under no conditions may you remove the copyright noticesmade part of the software or documentation.

You may distribute your own compiled programs based on any of the source code ofthe S131 Infrared Secondary protocol stack. You may not distribute any of the S131Infrared Secondary protocol stack source code, compiled units, or compiled exampleprograms without the express written approval of an Executive Officer of WhiteBream. You may not use S131 Infrared Secondary protocol stack to create modulesto be used by other developers without the express written approval of an ExecutiveOfficer of White Bream.

Note that the previous restrictions do not prohibit you from distributing your ownsource code or units that depend upon S131 Infrared Secondary protocol stack.However, others who receive your source code or units need to purchase their owncopies of S131 Infrared Secondary protocol stack in order to compile the sourcecode or to write programs that use your modules.

One single license may be used for one type of device only, to be specified uponpurchase of the product. In case of royalty based licensing, Buyer shall update thelicense when the licensed quantity is passed.

White Bream warrants that the software will function as described in thedocumentation for a period of 60 days from receipt. If you encounter a bug ordeficiency, we will require a problem report detailed enough to allow us to find andfix the problem. If you properly notify us of such a software problem within thewarranty period, White Bream will update the defective software at no cost to you.

White Bream © 2000 - 2005 S131RP002 v1.0


WHITE BREAM DOES NOT ASSUME ANY LIABILITY FOR THE USE OF S131INFRARED SECONDARY PROTOCOL STACK BEYOND THE ORIGINALPURCHASE PRICE OF THE SOFTWARE. IN NO EVENT WILL WHITE BREAM BELIABLE TO YOU FOR ADDITIONAL DAMAGES, INCLUDING ANY LOSTPROFITS, LOST SAVINGS, OR OTHER INCIDENTAL OR CONSEQUENTIALDAMAGES ARISING OUT OF THE USE OF OR INABILITY TO USE THESEPROGRAMS, EVEN IF WHITE BREAM HAS BEEN ADVISED OF THE POSSIBILITYOF SUCH DAMAGES.

White Bream products are not authorized for use in, or in connection with surgicalimplants, or as critical components in any medical, or aircraft, or othertransportation devices or systems where failure to perform can reasonably beexpected to cause significant injury to the user, without the express written approvalof an Executive Officer of White Bream. Such use is at Buyer's sole risk, and Buyer is responsible for verification and validation ofthe suitability of products incorporated in any such devices or systems. Buyer agreesthat White Bream is not liable, in whole or in part, for any claim or damage arisingfrom such use and shall have no obligation to warranty such products. Buyer agreesto indemnify, defend and hold White Bream harmless from and against any and allclaims, damages losses, costs, expenses and liabilities arising out of or in connectionwith Buyer's use of White Bream products in such applications to the extent Buyerhas not obtained the express written approval of an Executive Officer of WhiteBream.

All brand and product names are trademarks or registered trademarks of theirrespective holders.



Notes

White Bream © 2000 - 2005 S131RP002 v1.0


Notes



Notes

White Bream © 2000 - 2005 S131RP002 v1.0


Notes



Notes

White Bream © 2000 - 2005 S131RP002 v1.0

White BreamTerborchdreef 263262NB Oud-BeijerlandThe Netherlands

Electronics and embedded projects www.whitebream.nlHardware and software www.whitebream.comCarPC demo project www.carpc.nl

Copyright © 2000-2005 White Bream, all rights reserved

*S131RP002*

Documents

white bream - Implementation.pdfConfidential S131 Infrared secondary station stack implementation guide Version Date Comment 0.2 Mar 17, 2004 Initial document 1.0 Jan ?, 2005 Guide